Required API Key:
any key with the
search
ACL
About this method
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
Retrieve a set of objects with their objectIDs
1
| $index->getObjects(['myId1', 'myId2']);
|
1
| res = index.get_objects(['myId', 'myId2'])
|
1
2
3
4
5
| index.getObjects(['myId1', 'myId2'], (err, content) => {
if (err) throw err;
console.log(content);
});
|
1
| index.get_objects(['myId1', 'myId2'])
|
1
2
3
4
5
6
| index.getObjects(
withIDs: ["myId1", "myId2"],
completionHandler: { (content, error) -> {
// do something
}
)
|
1
2
3
4
5
6
| index.getObjectsAsync(Arrays.asList("myId1", "myId2"), new CompletionHandler() {
@Override
public void requestCompleted(JSONObject content, AlgoliaException error) {
// [...]
}
});
|
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")
);
|
1
| err := index.GetObjects([]string{"myId1", "myId2"}, &objects)
|
1
2
3
| client.execute {
get from "index" objectIds Seq("myId2", "myId2")
}
|
1
| index.getObjects(listOf(ObjectID("myID1"), ObjectID("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']
]);
|
1
| res = index.get_objects(['myId', 'myId2'], ['firstname', 'lastname'])
|
1
2
3
4
5
| index.getObjects(['myId1', 'myId2'], ['firstname', 'lastname'], (err, content) => {
if (err) throw err;
console.log(content);
});
|
1
2
3
| index.get_objects(['myId1', 'myId2'], {
'attributesToRetrieve': ['firstname', 'lastname']
})
|
1
2
3
4
5
6
7
| index.getObjects(
withIDs: ["myId1", "myId2"],
attributesToRetrieve: ["firstname"],
completionHandler: { (content, error) -> {
// do something
}
)
|
1
2
3
4
5
6
| index.getObjectsAsync(Arrays.asList("myId1", "myId2"), Arrays.asList("firstname"), new CompletionHandler() {
@Override
public void requestCompleted(JSONObject content, AlgoliaException error) {
// [...]
}
});
|
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")
);
|
1
| err := index.GetObjects([]string{"myId1", "myId2"}, &objects, opt.AttributesToRetrieve("firstname"))
|
1
2
3
4
5
6
| client.execute {
get from "index" objectIds Seq(
"myId2",
"myId2"
) attributesToRetrieve Seq("firstname")
}
|
1
2
3
4
| val objectIDs = listOf(ObjectID("myID1"), ObjectID("myID2"))
val attributes = listOf(Attribute("firstname"), Attribute("lastname"))
index.getObjects(objectIDs, attributes)
|
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'],
]);
|
1
2
3
4
5
6
| # Retrieves all attributes
index.get_object('myId')
# Retrieves firstname and lastname attributes
res = index.get_object('myId', ['firstname', 'lastname'])
# Retrieves only the firstname attribute
res = index.get_object('myId', ['firstname'])
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| // Retrieves all attributes
index.getObject('myId', (err, content) => {
console.log(content);
});
// Retrieves firstname and lastname attributes
index.getObject('myId', ['firstname', 'lastname'], (err, content) => {
console.log(content);
});
// Retrieves only the firstname attribute
index.getObject('myId', ['firstname'], (err, content) => {
console.log(content);
});
|
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
| // Retrieve all attributes.
index.getObject(
withID: "myId",
completionHandler: { (content, error) -> {
// do something
}
)
// Retrieves `firstname` and `lastname` attributes.
index.getObject(
withID: "myId",
attributesToRetrieve: ["firstname", "lastname"],
completionHandler: { (content, error) -> {
// do something
}
)
// Retrieve only the `firstname` attribute.
index.getObject(
withID: "myId",
attributesToRetrieve: ["firstname"],
completionHandler: { (content, error) -> {
// do something
}
)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| // Retrieves all attributes
index.getObjectAsync("myId", new CompletionHandler() {
@Override
public void requestCompleted(JSONObject content, AlgoliaException error) {
// [...]
}
});
// Retrieves the firstname and lastname attribute
index.getObjectAsync("myId", Arrays.asList("firstname", "lastname"), new CompletionHandler() {
@Override
public void requestCompleted(JSONObject content, AlgoliaException error) {
// [...]
}
});
// Retrieves only the firstname attribute
index.getObjectAsync("myId", Arrays.asList("firstname"), new CompletionHandler() {
@Override
public void requestCompleted(JSONObject content, AlgoliaException error) {
// [...]
}
});
|
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")
}
|
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)
|
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"
]
));
|
1
2
3
4
| client.multiple_get_objects([
{ "indexName" => "index1", "objectID" => "myId1" },
{ "indexName" => "index2", "objectID" => "myId2" }
])
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| client.multipleGetObjects(
[
{
'indexName': 'index1',
'objectName': 'myId1'
},
{
'indexName': 'index2',
'objectName': 'myId2'
}
],
(err, content) => {
if (err) throw err;
console.log(content);
}
);
|
1
2
3
4
| client.multiple_get_objects([
{'indexName': 'index1', 'objectName': 'myId1'},
{'indexName': 'index2', 'objectName': 'myId2'}
])
|
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)
|
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)
|
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'
];
|
1
2
3
4
5
6
7
8
9
| object_ids = []
attributes_to_retrieve = nil
extra_headers = {
'X-Algolia-User-ID': 'user123'
}
res = index.get_objects(object_ids, attributes_to_retrieve, extra_headers)
|
1
2
3
4
| client.setExtraHeader('X-Forwarded-For', '94.228.178.246');
index.getObjects(['myId1', 'myId2'], (err, content) => {
console.log(content);
});
|
1
2
3
| index.get_objects(['myId1', 'myId2'], {
'X-Forwarded-For': '94.228.178.246'
})
|
1
2
3
4
5
6
7
8
9
10
| let requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-User-ID"] = "user123"
index.getObjects(
withIDs: ["myId1", "myId2"],
requestOptions: requestOptions,
completionHandler: { (content, error) -> {
// do something
}
)
|
1
2
3
4
5
6
7
8
9
10
11
| index.getObjectsAsync(
Arrays.asList("myId1", "myId2"),
new RequestOptions()
.setHeader("X-Algolia-User-ID", "94.228.178.246"),
new CompletionHandler() {
@Override
public void requestCompleted(JSONObject content, AlgoliaException error) {
// [...]
}
}
);
|
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"))
)
}
|
1
2
3
4
5
| val requestOptions = requestOptions {
headerAlgoliaUserId(UserID("user123"))
}
index.getObjects(listOf(ObjectID("myID1"), ObjectID("myID2")), requestOptions = requestOptions)
|
Parameters
objectIDs
|
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
|
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.
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 of the retrieved objects.
|
