attributesToRetrieve
*
(all attributes)
'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:
search,
setSettings,
browseObjects,
searchForFacetValues,
generateSecuredApiKey,
addApiKey,
updateApiKey
search,
set_settings,
browse_objects,
search_for_facet_values,
generate_secured_api_key,
add_api_key,
update_api_key
search,
setSettings,
browseObjects,
searchForFacetValues,
generateSecuredApiKey,
addApiKey,
updateApiKey
search,
set_settings,
browse_objects,
search_for_facet_values,
generate_secured_api_key,
add_api_key,
update_api_key
search,
setSettings,
browse,
searchForFacetValues,
generateSecuredApiKey,
addAPIKey,
updateAPIKey
search,
setSettings,
browseObjects,
searchForFacetValues,
generateSecuredApiKey,
addApiKey,
updateApiKey
Search,
SetSettings,
Browse,
SearchForFacetValues,
GenerateSecuredApiKey,
AddApiKey,
UpdateApiKey
Search,
setSettings,
browse,
searchForFacetValues,
generateSecuredApiKey,
addApiKey,
updateApiKey
Search,
SetSettings,
BrowseObjects,
SearchForFacetValues,
GenerateSecuredAPIKey,
AddAPIKey,
UpdateAPIKey
search,
setSettings,
browse index,
search into facet values,
generateSecuredApiKey,
add key,
update key
About this parameter
This parameter controls 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. Reducing the size of records leads to faster network transfers.
You don’t always need to retrieve a complete response that includes every attribute in your index. Sometimes you may want the most relevant attributes for users and exclude others, for example, internal attributes for business purposes.
Usage notes
- If you don’t include your custom ranking attributes in
attributesToRetrieve
, they won’t be part of the response. Sometimes, you don’t want to expose your custom ranking attributes, such as when using 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). - Nested attributes, such as
author.name
, are supported and will be retrieved within their initial tree structure. For example,{"author": {"name": "Agatha Christie"}}
. - Attribute names are case-sensitive.
There’s no limit to the number of attributes in the list, but having many attributes slows down calls to getSettings
. This can make the Algolia dashboard slower and less responsive.
Special characters
- Use
*
to retrieve all values. - Prefix a dash (
-
) to an attribute 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 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.
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' => [
"*"
]
]);
Override default list of retrievable attributes for the current search
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'
]
]);