Api clients / Ruby / V1 / Methods

Jan. 09, 2023

Get Objects | Ruby API Client V1 (Deprecated)

This version of the Ruby API client has been deprecated in favor of the latest version of the Ruby API client.

Required API Key: any key with the search ACL

Method signature

index.get_objects(
  Array objectIds
)
index.get_objects(
  Array objectIds,
  Array attributesToRetrieve,
  Hash requestOptions
)

// get a single object
index.get_object(
  String objectId,
  Array attributesToRetrieve
)
index.get_object(
  String objectId,
  Array attributesToRetrieve,
  Hash requestOptions
)

// get multiple objects
client.multiple_get_objects(Array multipleObjects)

See code examples

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

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

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

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', ['firstname', 'lastname'])
# Retrieves only the firstname attribute
res = index.get_object('myId', ['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
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

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

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 | Ruby API Client V1 (Deprecated)

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