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

// get multiple objects
$client->getMultipleObject(array multipleObjects)

About this method

Get one or more objects using their objectIDs.

There are three methods you can use to retrieve your objects:

  1. The getObject method lets you retrieve a single object from a specified index.
  2. The getObjects method lets you retrieve multiple objects from a specified index.
  3. The multipleGetObjects method lets you retrieve multiple objects from multiple indices within the same app. This method is called from the client.

With getObject and getObjects, you can also specify which attributes to retrieve. This list applies to all objects, and defaults to all attributes.

Objects are returned in the order in which they were requested.

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'], [
  'attributesToRetrieve' => ['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 several objects across several indices

1
2
3
4
5
6
7
8
9
10
$client->multipleGetObjects(array(
  [
    "indexName" => "index1",
    "objectID" => "myId1"
  ], 
  [
    "indexName" => "index2",
    "objectID" => "myId2"
  ]
));

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.

multipleObjects
type: list of multipleObject
true (for multipleGetObjects)

A list of mappings that represent specific objects in specific indices.

multipleObjects ➔ multipleObject

The multipleObject parameter must have exactly two key/value mappings:

  • indexName to specify the index in which to search (as a string).
  • objectId to specify the objectID of the record to retrieve (as a string).

Check out this example for reference.

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?