API Reference / API Methods / Indexing / Get objects

Aug. 16, 2022

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)

index.get_objects(
  Array objectIds
)
index.get_objects(
  Array objectIds,
  Hash opts = {
    nil|Array|String attributesToRetrieve: nil,
    # any requestOptions
  }
)

// get a single object
index.get_object(
  String objectId,
)
index.get_object(
  String objectId,
  Hash opts = {
    nil|Array|String attributesToRetrieve: nil,
    # any requestOptions
  }
)

// get multiple objects
client.multiple_get_objects(Array multipleObjects, Hash opts = {
  # any requestOptions
})

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(str objectID)

index.getObject(str objectID, {
  // All the following parameters are optional
  attributesToRetrieve: array
  // Any other requestOptions
})

client.multipleGetObjects(array multipleObjects)

client.multipleGetObjects(array multipleObjects, {
  // Any other requestOptions
})

index.get_objects(list objectIds)

index.get_objects(list objectIds, {
    // All the following parameters are optional
    'attributesToRetrieve': list
    // Any other requestOptions
})

// get a single object
index.get_object(str objectId)
index.get_object(str objectId, {
    // All the following parameters are optional
    'attributesToRetrieve': list
    // Any other requestOptions
})

client.multiple_get_objects(list multipleObjects)

index.getObjects<T: Decodable>(
  withIDs objectIDs: [ObjectID],
  attributesToRetrieve: [Attribute] = [],
  requestOptions: RequestOptions? = nil,
  completion: Result<ObjectsResponse<T>> -> Void
)
  
// get a single object
index.getObject(
  withID objectID: ObjectID,
  attributesToRetrieve: [Attribute] = [],
  requestOptions: RequestOptions? = nil,
  completion: Result<T> -> Void
)

// get multiple objects
client.multipleGetObjects(
  requests: [ObjectRequest],
  requestOptions: RequestOptions? = nil,
  completion: Result<ObjectsResponse<T>> -> Void
)

suspend fun <T : Indexable> Index.getObject(
    serializer: KSerializer<T>,
    objectID: ObjectID,
    attributesToRetrieve: List<Attribute>? = null,
    requestOptions: RequestOptions? = null
): T

suspend fun Index.getObject(
    objectID: ObjectID,
    attributesToRetrieve: List<Attribute>? = null,
    requestOptions: RequestOptions? = null
): JsonObject

suspend fun Index.getObjects(
    objectIDs: List<ObjectID>,
    attributesToRetrieve: List<Attribute>? = null,
    requestOptions: RequestOptions? = null
): ResponseObjects

suspend fun Client.multipleGetObjects(
    multipleObjects: List<RequestObjects>
): ResponseObjects

index.GetObjects(
  IEnumerable<String> objectIds,

  // All the following parameters are optional
  attributesToRetrieve: IEnumerable<String>,
  requestOptions: RequestOptions
)

// get a single object
index.GetObject(
  String objectId,

  // All the following parameters are optional
  attributesToRetrieve: IEnumerable<String>,
  requestOptions: RequestOptions
)

// get multiple objects
client.MultipleGetObjects(
  multipleObjects: IEnumerable<MultipleGetObject>
)

index.getObjects(
  List<String> objectIds
)
index.getObjects(
  List<String> objectIds,
  List<String> attributesToRetrieve,
  RequestOptions requestOptions
)

// get a single object
index.getObject(
  String objectId
)
index.getObject(
  String objectId,
  List<String> attributesToRetrieve,
  RequestOptions requestOptions
)

// get multiple objects
client.multipleGetObjects(
  List<MultipleGetObject> multipleObjects
)

index.GetObjects(
  []String objectIDs
)
index.GetObjectsAttrs(
  []String objectIDs,
  []String attributesToRetrieve,
  RequestOptions requestOptions
)
index.GetObjects(
  []String objectIDs,
  RequestOptions requestOptions
)

// get a single object
index.GetObject(
  String objectID
)
index.GetObjectAttrs(
  String objectID,
  []String attributesToRetrieve,
  RequestOptions requestOptions
)
index.GetObject(
  String objectID,
  RequestOptions requestOptions
)

// get multiple objects
client.MultipleGetObjects(
  []IndexedGetObject multipleObjects
)

get from "index_name" objectIds objectIDs
get from "index_name" objectIds objectIDs attributesToRetrieve attributesToRetrieve options requestOptions

// get a single object
get from "index_name" objectId objectID
get from "index_name" objectId objectID attributesToRetrieve attributesToRetrieve options requestOptions

// multipleGetObjects is not implemented

See code examples

About this method

We released a new version of the PHP API client in public beta. Read the beta documentation for more information.

We released a new version of the JavaScript API client in public beta. Read the beta documentation for more information.

We released a new version of the Java API client in public beta. Read the beta documentation for more information.

You’re currently reading the JavaScript API client v4 documentation. Check the migration guide to learn how to upgrade from v3 to v4. You can still access the v3 documentation.

You’re currently reading the Ruby API client v2 documentation. Check the migration guide to learn how to upgrade from v1 to v2. You can still access the v1 documentation.

Get one or more objects using their objectIDs.

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

The getObject method lets you retrieve a single object from a specified index.
The getObjects method lets you retrieve multiple objects from a specified index.
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

Read the Algolia CLI documentation for more information.

Retrieve a set of objects with their objectIDs

Copy

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

1
2
3
4
5
6
7
8
9
10
11
struct Contact: Codable {
  let objectID: ObjectID
  let firstname: String
  let lastname: String
}

index.getObjects(withIDs: ["myId1", "myId2"]) { (result: Result<ObjectsResponse<Contact>, Error>) in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
IEnumerable<Contact> contacts = index.GetObjects<Contact>(new List<string> {"myId1", "myId2"});

// Asynchronous
IEnumerable<Contact> contacts = await index.GetObjectsAsync<Contact>(new List<string> {"myId1", "myId2"});

1
2
3
4
5
6
7
8
// Sync version
List<Contact> contacts =
  index.getObjects(Arrays.asList("myId", "myId2"));

// Async version
CompletableFuture<List<Contact>> contacts = index.getObjectsAsync(
  Arrays.asList("myId", "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.

Copy

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

1
2
3
4
5
6
7
8
9
10
struct Contact: Codable {
  let firstname: String
}

index.getObjects(withIDs: ["myId1", "myId2"],
                 attributesToRetrieve: ["firstname"]) { (result: Result<ObjectsResponse<Contact>, Error>) in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
val objectIDs = listOf(ObjectID("myID1"), ObjectID("myID2"))
val attributes = listOf(Attribute("firstname"), Attribute("lastname"))

index.getObjects(objectIDs, attributes)

1
2
3
4
IEnumerable<Contact> contacts = index.GetObjects<Contact>(new List<string> {"myId1", "myId2"}, attributesToRetrieve: new String[] { "firstname" });

// Asynchronous
IEnumerable<Contact> contacts = await index.GetObjectsAsync<Contact>(new List<string> {"myId1", "myId2"}, attributesToRetrieve: new String[] { "firstname" });

1
2
3
4
5
6
7
8
9
// Sync version
List<Contact> contacts =
  index.getObjects(Arrays.asList("myId", "myId2"), Arrays.asList("firstname"));

// Async version
CompletableFuture<List<Contact>> contacts = index.getObjectsAsync(
  Arrays.asList("myId", "myId2"),
  Arrays.asList("firstname")
);

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

Retrieve only one object

Copy

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

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

1
2
3
4
5
6
# Retrieves all attributes
index.get_object('myId')
# Retrieves firstname and lastname attributes
res = index.get_object('myId', { attributesToRetrieve: ['firstname', 'lastname'] })
# Retrieves only the firstname attribute
res = index.get_object('myId', { attributesToRetrieve: ['firstname'] })

1
2
3
4
5
6
7
8
9
10
11
// Retrieves all attributes
index.getObject('myId').then(object => {
  console.log(object);
});

// Retrieves only firstname and lastname attributes
index.getObject('myId', {
  attributesToRetrieve: ['firstname', 'lastname']
}).then(object => {
  console.log(object);
});

1
2
3
4
5
6
7
8
9
10
11
12
# Retrieves all attributes
index.get_object('myId')

# Retrieves firstname and lastname attributes
index.get_object('myId', {
    'attributesToRetrieve': ['firstname, lastname']
})

# Retrieves only the firstname attribute
index.get_object('myId', {
    'attributesToRetrieve': ['firstname']
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
struct Contact: Codable {
  let firstname: String
  let lastname: String?
}

// Retrieve all attributes.
index.getObject(withID: "myId") { (result: Result<Contact, Error>) in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

// Retrieves `firstname` and `lastname` attributes.
index.getObject(withID: "myId",
                attributesToRetrieve: ["firstname", "lastname"]) { (result: Result<Contact, Error>) in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

// Retrieve only the `firstname` attribute.
index.getObject(withID: "myId",
                attributesToRetrieve: ["firstname"]) { (result: Result<Contact, Error>) in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
index.getObject(ObjectID("myID1"))

@Serializable
data class Contact(
    val firstname: String,
    val lastname: String,
    override val objectID: ObjectID
) : Indexable

val objectID = ObjectID("myID1")

index.getObject(objectID)
index.getObject(Contact.serializer(), objectID)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Retrieves all attributes
Contact res = index.GetObject<Contact>("myId");

// Asynchronous
Contact res = await index.GetObjectAsync<Contact>("myId");

// Retrieves firstname and lastname attributes
Contact res = index.GetObject<Contact>("myId", attributesToRetrieve: new List<string> { "firstname", "lastname" });

// Asynchronous
Contact res = await index.GetObjectAsync<Contact>("myId", attributesToRetrieve: new List<string> { "firstname", "lastname" });

// Retrieves only the firstname attribute
Contact res = index.GetObject<Contact>("myId", attributesToRetrieve: new List<string> { "firstname" });

// Asynchronous
Contact res = await index.GetObjectAsync<Contact>("myId", attributesToRetrieve: new List<string> { "firstname" });

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Retrieves all attributes
Contact contact = index.getObject("myId");

// Async version
// CompletableFuture<Contact> contact =
  index.getObject("myId");

// Retrieves firstname and lastname attributes
Contact contact = index.getObject("myId", Arrays.asList("firstname", "lastname"));

// Async version
// CompletableFuture<Contact> contact =
  index.getObject("myId", Arrays.asList("firstname", "lastname"));

// Retrieves only the firstname attribute
Contact contact = index.getObject("myId", Arrays.asList("firstname"));

// Async version
// CompletableFuture<Contact> contact =
  index.getObject("myId", Arrays.asList("firstname"));

1
2
3
4
5
6
7
8
// Retrieves the object with all its attributes
err := index.GetObject("myId", &object)

// Retrieves the object with only its `firstname` attribute
err := index.GetObject("myId", &object, opt.AttributesToRetrieve("firstname"))

// Retrieves the object with only its `firstname` and `lastname` attributes
err := index.GetObject("myId", &object, opt.AttributesToRetrieve("firstname", "lastname"))

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Retrieves all attributes
client.execute {
  get from "index" objectId "myId"
}

// Retrieves firstname and lastname attributes
client.execute {
  get from "index" objectId "myId" attributesToRetrieve Seq("firstname", "lastname")
}

// Retrieves only the firstname attribute
client.execute {
  get from "index" objectId "myId" attributesToRetrieve Seq("firstname")
}

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

Copy

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

1
2
3
4
5
6
client.multipleGetObjects([
  { indexName: 'index1', objectID: 'myId1' },
  { indexName: 'index2', objectID: 'myId2' }
]).then(({ results }) => {
  console.log(results);
});

1
2
3
4
5
6
7
8
9
10
let requests: [ObjectRequest] = [
  .init(indexName: "index1", objectID: "myId1"),
  .init(indexName: "index2", objectID: "myId2"),
]

client.multipleGetObjects(requests: requests) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
val requests = listOf( 
  RequestObject(
    IndexName("index1"),
    ObjectID("myId1")
  ),
  RequestObject(
    IndexName("index2"),
    ObjectID("myId2")
  )
)

client.multipleGetObjects(requests)

1
2
3
4
5
6
7
8
9
10
var objectsToRetrieve = new List<MultipleGetObject>
{
  new MultipleGetObject { IndexName = "index1", ObjectID = "myId1" },
  new MultipleGetObject { IndexName = "index2", ObjectID = "myId2" }
};

IEnumerable<Object> objects = client.MultipleGetObjects<Object>(objectsToRetrieve);

// Asynchronous
IEnumerable<Object> objects = await client.MultipleGetObjectsAsync<Object>(objectsToRetrieve);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
List<MultipleGetObject> objectsToRetrieve =
    Arrays.asList(
        new MultipleGetObject("index1", "myId1"),
        new MultipleGetObject("index2", "myId2")
    );
    
    MultipleGetObjectsResponse<AlgoliaMultipleOpObject> multipleGet =
    searchClient
      // Async
      .multipleGetObjectsAsync(objectsToRetrieve, AlgoliaMultipleOpObject.class)
      .join();

      // Sync
      .multipleGetObjects(objectsToRetrieve, AlgoliaMultipleOpObject.class)
      .join();

1
2
3
4
5
6
requests := []IndexedGetObject{
    {IndexName: "index1", ObjectID: "myId1"},
    {IndexName: "index2", ObjectID: "myId2"},
  }
  
  res, err = client.MultipleGetObjects(requests, &objects)

Retrieve a set of objects and send extra HTTP headers

Copy

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

$index->getObjects($objectIDs, [
  'X-Forwarded-For' => '94.228.178.246'
];

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-User-ID"] = "user123"

struct Contact: Codable {
  let objectID: ObjectID
  let firstname: String
  let lastname: String
}

index.getObjects(withIDs: ["myId1", "myId2"],
                 requestOptions: requestOptions) { (result: Result<ObjectsResponse<Contact>, Error>) in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
val requestOptions = requestOptions {
    headerAlgoliaUserId(UserID("user123"))
}

index.getObjects(listOf(ObjectID("myID1"), ObjectID("myID2")), requestOptions = requestOptions)

1
2
3
4
5
6
7
8
9
RequestOptions requestOptions = new RequestOptions
{
    Headers = new Dictionary<string,string>{ { "X-Algolia-User-ID", "user123" } }
};

index.GetObjects(new List<string> {"myId1", "myId2"}, requestOptions);

// Asynchronous
await index.GetObjectsAsync<Contact>(new List<string> {"myId1", "myId2"}, requestOptions);

1
2
3
4
5
6
7
8
9
10
11
// Sync version
List<Contact> contacts = index.getObjects(
  Arrays.asList("myId", "myId2"),
  new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123")
);

// Async version
CompletableFuture<List<Contact>> contacts = index.getObjectsAsync(
  Arrays.asList("myId", "myId2"),
  new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123")
);

1
2
3
4
5
extraHeaders := opt.ExtraHeaders(map[string]string{
    "X-Algolia-User-ID": "userID2",
})

err := index.GetObjects([]string{"myId1", "myId2"}, &objects, extraHeaders)

1
2
3
4
5
6
7
8
client.execute {
  get from "index" objectIds Seq(
    "myId1",
    "myId2"
  ) options RequestOptions(
    extraHeaders = Some(Map("X-Algolia-User-ID" => "user123"))
  )
}

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 `requestOptions` to send along with the query. Search parameters can’t be used with `getObjects`.
`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

This section shows the JSON response returned by the API. Since each language encapsulates this response inside objects specific to that language and/or implementation, the actual type in your language might differ from what’s written here. You can view the response in the logs (using the getLogs method).

JSON format

Copy

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

Copy

          {
  "results": [
    null,
    {
      "objectID": "1182729442",
      "name": "product 1"
    }
  ],
  "message": "ObjectID 1182729441 does not exist."
}

        


          results

list

List of the retrieved objects.

Did you find this page helpful?

Get Objects

About this method

Examples

Retrieve a set of objects with their objectIDs

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

Retrieve only one object

Retrieve several objects across several indices

Retrieve a set of objects and send extra HTTP headers

Parameters

multipleObjects ➔ multipleObject

Response

JSON format

On this page