API Reference / API Parameters / attributesToRetrieve

Nov. 25, 2021

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'
]

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'
]

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'
]

'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'
]

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"
]

// list of attributes to retrieve
settings {
    attributesToRetrieve {
        +"attribute1"
        +"attribute2"
    }
}

// retrieves all attributes
settings { attributesToRetrieve { +"*" } }

// retrieves all attributes except the one listed.
settings {
    attributesToRetrieve {
        +"attribute1"
        +"attribute2"
        excludeAttributes = true
    }
}

IndexSettings settings = new IndexSettings
{
    // list of attributes to retrieve
    AttributesToRetrieve = new List<string> { "attribute1", "attribute2" }
};
IndexSettings settings = new IndexSettings
{
    // retrieves all attributes
    AttributesToRetrieve = new List<string> { "*" }
};
IndexSettings settings = new IndexSettings
{
    // retrieves all attributes except the attributes starting with a "-"
    AttributesToRetrieve = new List<string> { "*" , "-attribute1", "-attribute2"}
};

new IndexSettings().setAttributesToRetrieve(Arrays.asList(
  "attribute1", // list of attributes to retrieve
  "attribute2"
))
new IndexSettings().setAttributesToRetrieve(Arrays.asList(
  "*" // retrieves all attributes
))
new IndexSettings().setAttributesToRetrieve(Arrays.asList(
  "*", // retrieves all attributes
  "-attribute1", // except this list of attributes (starting with a "-")
  "-attribute2"
))

opt.AttributesToRetrieve(
  "attribute1", // list of attributes to retrieve
  "attribute2",
)
opt.AttributesToRetrieve(
  "*", // retrieves all attributes
)
opt.AttributesToRetrieve(
  "*", // retrieves all attributes
  "-attribute1", // except this list of attributes (starting with a "-")
  "-attribute2",
)

attributesToRetrieve = Some(Seq(
  "attribute1", // list of attributes to retrieve
  "attribute2"
))
attributesToRetrieve = Some(Seq(
  "*" // retrieves all attributes
))
attributesToRetrieve = Some(Seq(
  "*", // 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

See code examples

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 just want the most relevant attributes for the user 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 you’re 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).

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 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.

Using the dashboard

You can also add and remove these attributes from the dashboard: Indices > Configuration > Search behavior > Retrieved attributes.

Under Attributes to retrieve:

Click Add an Attribute to select and add an attribute to the list
Click the trash icon to remove an attribute from the list.

Examples

Set default list of retrievable attributes

Copy

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

1
2
3
4
5
6
7
8
9
10
11
12
let settings = Settings()
  .set(\.attributesToRetrieve, to: [
    "author",
    "title",
    "content"
  ])

index.setSettings(settings) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    attributesToRetrieve = Some(Seq(
      "author",
      "title",
      "content"
    ))
  )
}

Make all attributes as retrievable by default

Copy

1
2
3
4
5
$index->setSettings([
  'attributesToRetrieve' => [
    "*"
  ]
]);

1
2
3
4
5
6
7
8
let settings = Settings()
  .set(\.attributesToRetrieve, to: ["*"])

index.setSettings(settings) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

Override default list of retrievable attributes for the current search

Copy

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

1
2
3
4
5
6
7
8
9
10
11
let query = Query("query")
  .set(\.attributesToRetrieve, to: [
    "title",
    "content"
  ])

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    attributesToRetrieve = Some(Seq(
      "title",
      "content"
    ))
  )
}

Specify some attributes not to retrieve

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

Copy

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

1
2
3
4
5
6
7
8
9
10
11
12
let settings = Settings()
  .set(\.attributesToRetrieve, to: [
    "*",
    "-SKU",
    "-internal_desc"
  ])

index.setSettings(settings) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    attributesToRetrieve = Some(Seq(
      "*",
      "-SKU",
      "-internal_desc"
    ))
  )
}

1
2
3
4
5
6
7
8
9
val settings = settings {
    attributesToRetrieve {
        +"sku"
        +"internal_desc"
        excludeAttributes = true
    }
}

index.setSettings(settings)

Did you find this page helpful?

attributesToRetrieve

About this parameter

Usage notes

Special characters

Using the dashboard

Examples

Set default list of retrievable attributes

Make all attributes as retrievable by default

Override default list of retrievable attributes for the current search

Specify some attributes not to retrieve

On this page