API Reference / API Parameters / attributesToRetrieve
Type: list of strings
Engine default: * (all attributes)
Formerly: attributes
Parameter syntax
'attributesToRetrieve' => [
  'attribute1', // list of attributes to retrieve
  'attribute2'
]
'attributesToRetrieve' => [
  '*' // retrieves all attributes
]
'attributesToRetrieve' => [
  '*', // retrieves all attributes
  '-attribute1', // except this list of attributes (starting with a '-')
  '-attribute2'
]

Can be used in these methods:

About this parameter

Gives control over which attributes to retrieve and which not to retrieve.

This setting helps to improve performance by reducing the size of records in the search response. You don’t always need to retrieve a full response that includes every attribute in your index. Sometimes you may just want the attributes that are most relevant for the user, and exclude others, for example, internal attributes for business purposes.

Usage notes:

  • Special characters:
    • Use * to retrieve all values.

    • Prefix a dash (-) to an attribute that you don’t wish to retrieve.

    • Negative attributes (-) only work when using *. For example, [“*”, “-title”] retrieves every attribute except “title”. Using negative attributes doesn’t make them unsearchable. If your users make queries that match an attribute not to retrieve, they will still get the same results, but the attribute won’t be part of the response.

  • If you don’t include your custom ranking attributes in attributesToRetrieve, they won’t be part of the response. This can be useful if you don’t want to expose your custom ranking attributes, for example, if you use sensitive data.

  • objectID is always retrieved, even when not specified.

  • Attributes listed in unretrievableAttributes won’t be retrieved even if requested, unless the request is authenticated with the admin API key.

Examples

Set default list of retrievable attributes

1
2
3
4
5
6
7
$index->setSettings([
  'attributesToRetrieve' => [
    'author',
    'title',
    'content'
  ]
]);

Make all attributes as retrievable by default

1
2
3
4
5
$index->setSettings([
  'attributesToRetrieve' => [
    "*"
  ]
]);
1
2
3
4
5
6
$results = $index->search('query', [
  'attributesToRetrieve' => [
    'title',
    'content'
  ]
]);

Specify some attributes not to retrieve

Here, you retrieve all attributes of an item except for its SKU and internal description.

1
2
3
4
5
6
7
$index->setSettings([
  'attributesToRetrieve' => [
    '*',
    '-SKU',
    '-internal_desc'
  ]
]);

Did you find this page helpful?