Get objects

Get one or more records using their object IDs.

Required ACL: search

You can use three methods to get records from your indices:

• getObject: get a single record from an index.
• getObjects: get multiple records from an index.
• multipleGetObjects: get multiple records from multiple indices within the same Algolia application.

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

When retrieving large numbers of records, be aware of the rate limitations on these processes and the impact on your analytics data.

To get all records from an index, use the browse method.

Examples

Return a list of records by their IDs

C#

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

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

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

// Sync version
List<Contact> contacts =
  index.getObjects(Arrays.asList("myId", "myId2"));

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

index.getObjects(['myId1', 'myId2']).then(({ results }) => {
  console.log(results);
});

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

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

index.get_objects(['myId1', 'myId2'])

res = index.get_objects(['myId', 'myId2'])

client.execute {
  get from "index" objectIds Seq("myId2", "myId2")
}

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)")
  }
}

Return a list of records with a subset of their attributes

C#

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" });

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

// 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")
);

index.getObjects(['myId1', 'myId2'], {
  attributesToRetrieve: ['firstname', 'lastname']
}).then(({ results }) => {
  console.log(results);
});

val objectIDs = listOf(ObjectID("myID1"), ObjectID("myID2"))
val attributes = listOf(Attribute("firstname"), Attribute("lastname"))

index.getObjects(objectIDs, attributes)

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

index.get_objects(['myId1', 'myId2'], {
    'attributesToRetrieve': ['firstname', 'lastname']
})

res = index.get_objects(['myId', 'myId2'], { attributesToRetrieve: ['firstname', 'lastname'] })

client.execute {
  get from "index" objectIds Seq(
    "myId2",
    "myId2"
  ) attributesToRetrieve Seq("firstname")
}

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)")
  }
}

If an object ID isn’t found in your index, the result is null for that object ID.

Return a single record by its ID

C#

// 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" });

// 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"))

// 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"));

// 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);
});

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)

// Retrieves all attributes
$index->getObject('myId');

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

# 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']
})

# 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'] })

// 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")
}

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)")
  }
}

If the object ID doesn’t exist in your index, this method returns an error.

Return records from multiple indices

C#

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

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

    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();

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

val requests = listOf( 
  RequestObject(
    IndexName("index1"),
    ObjectID("myId1")
  ),
  RequestObject(
    IndexName("index2"),
    ObjectID("myId2")
  )
)

client.multipleGetObjects(requests)

$client->multipleGetObjects(array(
  [
    "indexName" => "index1",
    "objectID" => "myId1"
  ], 
  [
    "indexName" => "index2",
    "objectID" => "myId2"
  ]
));

client.multiple_get_objects([
  {'indexName': 'index1', 'objectID': 'myId1'}, 
  {'indexName': 'index2', 'objectID': 'myId2'}
])

client.multiple_get_objects([
  { "indexName" => "index1", "objectID" => "myId1" },
  { "indexName" => "index2", "objectID" => "myId2" }
])

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)")
  }
}

Return a list of records and send extra HTTP headers

C#

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

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

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

// 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")
);

index.getObjects(['myId1', 'myId2'], {
  headers: {
    'X-Forwarded-For': '94.228.178.246'
  }
}).then(({ results }) => {
  console.log(results);
});

val requestOptions = requestOptions {
    headerAlgoliaUserId(UserID("user123"))
}

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

$objectIDs = [/* objectIDs */];

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

index.get_objects(['myId1', 'myId2'], {
    'X-Forwarded-For': '94.228.178.246'
})

res = index.get_objects(['myId1', 'myId2'], {
  headers: {
    'X-Algolia-User-ID': 'user123'
  }
})

client.execute {
  get from "index" objectIds Seq(
    "myId1",
    "myId2"
  ) options RequestOptions(
    extraHeaders = Some(Map("X-Algolia-User-ID" => "user123"))
  )
}

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)")
  }
}

Parameters

multipleObjects · object[] · required

A list of key-value pairs that represent specific records in specific indices. (Required for multipleGetObjects).

Show child attributes

indexName · string · required

Index in which to search.

objectId · string · required

Object ID of the record to retrieve.

objectID · string · required

Object ID for the record you want to get. (Required for getObject)

objectIDs · string[] · required

List of objectIDs to retrieve. (Required for getObjects).

attributesToRetrieve · string | string[]

Comma-separated list of attributes to include with each record.

By default, all retrievable attributes are returned.

requestOptions · object

request options to add to the request.

You can’t use search parameters with getObjects.

Response

results · list

List of the retrieved records.

Response as JSON

This section shows the JSON response returned by the API. Each API client wraps this response in language-specific objects, so the structure may vary. To view the response, use the getLogs method. Don’t rely on the order of properties—JSON objects don’t preserve key order.

JSON

{
  "results": [
    {
      "objectID": "1182729442",
      "name": "product 1"
    }
  ]
}