API Reference / API Methods / Indexing / Get objects
Feb. 26, 2019

Get objects

Required API Key: any key with the search ACL
Method signature
$index->getObjects(array objectIds)
$index->getObjects(array objectIds, [
  // All the following parameters are optional
  'attributesToRetrieve' => array
  // Any other requestOptions
])'


// get a single object
$index->getObject(string objectId)
$index->getObject(string objectId, [
  // All the following parameters are optional
  'attributesToRetrieve' => array
  // Any other requestOptions
])

About this method

Get one or more objects using their object ids.

The get objects method enables you to retrieve index objects.

You can specify a list of attributes to retrieve. This list will apply to all objects.

If you don’t specify any attributes, every attribute will be returned.

Examples

Retrieve a set of objects with their objectIDs

1
$index->getObjects(['myId1', 'myId2']);

Retrieve a set of objects with only a subset of their attributes

Optionally you can specify a comma separated list of attributes you want to retrieve.

1
2
3
$index->getObjects(['myId1', 'myId2'], [
  'attributeToRetrieve' => ['firstname', 'lastname']
]);

Note: This will return an array of objects for all objects found; for those not found, it will return a null.

Retrieve only one object

1
2
3
4
5
6
7
8
// Retrieves all attributes
$index->getObject('myId');

// Retrieves only firstname and lastname attributes
$index->getObject('myId', [
  'attributeToRetrieve' => ['firstname', 'lastname'],
]);

If the object exists it will be returned as is. Otherwise the function will return an error and not null like getObjects.

Retrieve a set of objects and send extra http headers

1
2
3
4
5
$objectIDs = [/* objectIDs */];

$index->getObjects($objectIDs, [
  'X-FORWARDED-FOR' => '94.228.178.246'
];

Parameters

objectIDs
type: list
Required

List of objectIDs to retrieve.

attributesToRetrieve
type: string|array
default: ""
Optional

Comma separated list of attributes to retrieve.

By default, all retrievable attributes are returned.

requestOptions
type: key value mapping
default: No requestOptions
Optional

A mapping of request options to send along with the query.

objectID
type: integer|string
Required

The objectID of the object to get.

Response

In this section we document the JSON response returned by the API. Each language will encapsulate this response inside objects specific to the language and/or the implementation. So the actual type in your language might differ from what is documented.

JSON format

1
2
3
4
5
6
7
8
{
  "results": [
    {
      "objectID": "1182729442",
      "name": "product 1"
    }
  ]
}

Here is an example where we try to get two objects. The first one doesn’t exist (null is returned) but the second one does (the object is returned). If an object does not exist, null will be return instead.

1
2
3
4
5
6
7
8
9
10
{
  "results": [
    null,
    {
      "objectID": "1182729442",
      "name": "product 1"
    }
  ],
  "message": "ObjectID 1182729442 does not exist."
}
results
list

List of the retrieved objects.

Did you find this page helpful?