API Reference / API Methods / Indexing / Get objects

Jan. 28, 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 # A

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 # A

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

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

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
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 # A

`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 # A

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 # Found an issue? Edit this page A Edit this page

Examples # Found an issue? Edit this page A Edit this page

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 # Found an issue? Edit this page A Edit this page

multipleObjects ➔ multipleObject #

Response # Found an issue? Edit this page A Edit this page

JSON format#

On this page

About this method # A

Examples # A

Parameters # A

Response # A