Get objects

Required API Key: any key with the search ACL
Method signature
$index->getObjects(objectIds)
$index->getObjects(objectIds, attributesToRetrieve, requestOptions)

// get a single object
$index->getObject(objectId)
$index->getObject(objectId, attributesToRetrieve, requestOptions)
Method signature
index.get_objects(objectIds)
index.get_objects(objectIds, attributesToRetrieve, requestOptions)

// get a single object
index.get_object(objectId, attributesToRetrieve)
index.get_object(objectId, attributesToRetrieve, requestOptions)
Method signature
index.getObjects(objectIds, callback)
index.getObjects(objectIds, attributesToRetrieve, callback)

// get a single object
index.getObject(objectId, callback)
index.getObject(objectId, attributesToRetrieve, callback)
Method signature
index.get_objects(objectIds)
index.get_objects(objectIds, attributesToRetrieve, requestOptions)

// get a single object
index.get_object(objectId)
index.get_object(objectId, attributesToRetrieve, requestOptions)
Method signature
index.getObjects(withIDs: objectIDs, completionHandler)
index.getObjects(
  withIDs: objectIDs,
  attributesToRetrieve: attributesToRetrieve,
  requestOptions: requestOptions,
  completionHandler
)


// get a single object
index.getObject(withID: objectID, completionHandler)
index.getObject(
  withID: objectID,
  attributesToRetrieve: attributesToRetrieve,
  requestOptions: requestOptions,
  completionHandler
)

Method signature
index.getObjectsAsync(objectIDs, completionHandler)
index.getObjectsAsync(
  objectIDs,
  attributesToRetrieve,
  requestOptions,
  completionHandler
)


// get a single object
index.getObjectAsync(objectID, completionHandler)
index.getObjectAsync(
  objectID,
  attributesToRetrieve,
  requestOptions,
  completionHandler
)

Method signature
index.getObjects(objectIds)
index.getObjects(objectIds, attributesToRetrieve, requestOptions)

// get a single object
index.getObject(objectId)
index.getObject(objectId, attributesToRetrieve, requestOptions)
Method signature
index.getObjects(objectIds)
index.getObjects(objectIds, attributesToRetrieve, requestOptions)

// get a single object
index.getObject(objectId)
index.getObject(objectId, attributesToRetrieve, requestOptions)
Method signature
index.GetObjects(objectIDs)
index.GetObjectsAttrs(objectIDs, attributesToRetrieve, requestOptions)
index.GetObjectsWithRequestOptions(objectIDs, requestOptions)

// get a single object
index.GetObject(objectID)
index.GetObjectAttrs(objectID, attributesToRetrieve, requestOptions)
index.GetObjectWithRequestOptions(objectID, requestOptions)
Method signature
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

About this method

Get one or more objects using their object ids.

The get objects method enables you to retrieve index objects.

You can specify a list of attributes to retrieve. This list will apply to all objects.

If you don’t specify any attributes, every attribute will be returned.

Examples

Retrieve a set of objects with their objectIDs

<?php
$index->getObjects(['myId1', 'myId2']);
res = index.get_objects(['myId', 'myId2'])
index.getObjects(['myId1', 'myId2'], function(err, content) {
  if (err) throw err;

  console.log(content);
});
res = index.get_objects(["myId1", "myId2"])
index.getObjects(
  withIDs: ["myId1", "myId2"],
  completionHandler: { (content, error) -> {
    // do something
  }
)
index.getObjectsAsync(Arrays.asList("myId1", "myId2"), new CompletionHandler() {
    @Override
    public void requestCompleted(JSONObject content, AlgoliaException error) {
        // [...]
    }
});
res = index.GetObjects(new String[] {"myId1", "myId2"});

// Asynchronous
// res = await index.GetObjectsAsync(new String[] {"myId1", "myId2"});
// Sync version
List<Contact> contacts = index.getObjects(Arrays.asList("myId", "myId2"));

// Async version
CompletableFuture<List<Contact>> contacts = index.getObjects(
  Arrays.asList("myId", "myId2")
);
objects, err = index.GetObjects([]string{"myId1", "myId2"})
client.execute {
  get from "index" objectIds Seq("myId2", "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.

<?php
$index->getObjects(['myId1', 'myId2'], ['firstname', 'lastname']);
res = index.get_objects(['myId', 'myId2'], ['firstname', 'lastname'])
index.getObjects(['myId1', 'myId2'], ['firstname', 'lastname'], function(err, content) {
  if (err) throw err;

  console.log(content);
});
res = index.get_objects(["myId1", "myId2"], ["firstname", "lastname"])
index.getObjects(
  withIDs: ["myId1", "myId2"],
  attributesToRetrieve: ["firstname"],
  completionHandler: { (content, error) -> {
    // do something
  }
)
index.getObjectsAsync(Arrays.asList("myId1", "myId2"), Arrays.asList("firstname"), new CompletionHandler() {
    @Override
    public void requestCompleted(JSONObject content, AlgoliaException error) {
        // [...]
    }
});
res = index.GetObjects(new String[] {"myId1", "myId2"}, new String[] { "firstname" });

// Asynchronous
// res = await index.GetObjectsAsync(new String[] {"myId1", "myId2"}, new String[] { "firstname" });
// Sync version
List<Contact> contacts = index.getObjects(Arrays.asList("myId", "myId2"), Arrays.asList("firstname"));

// Async version
CompletableFuture<List<Contact>> contacts = index.getObjects(
  Arrays.asList("myId", "myId2")
);
objects, err = index.GetObjects([]string{"myId1", "myId2"}, []string{"firstname"})
client.execute {
  get from "index" objectIds Seq(
    "myId2",
    "myId2"
  ) attributesToRetrieve Seq("firstname")
}

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

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

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

// Retrieves only the firstname attribute
$index->getObject('myId', ['firstname']);
# 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'])
// Retrieves all attributes
index.getObject('myId', function(err, content) {
  console.log(content);
});

// Retrieves firstname and lastname attributes
index.getObject('myId', ['firstname', 'lastname'], function(err, content) {
  console.log(content);
});

// Retrieves only the firstname attribute
index.getObject('myId', ['firstname'], function(err, content) {
  console.log(content);
});
# 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"])
// 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
  }
)
// 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) {
        // [...]
    }
});
// Retrieves all attributes
var res = index.GetObject("myId");

// Asynchronous
// var res = await index.GetObjectAsync("myId");

System.Diagnostics.Debug.WriteLine(res);


// Retrieves firstname and lastname attributes
res = index.GetObject("myId", new String[] {"firstname", "lastname"});

// Asynchronous
// res = await index.GetObjectAsync("myId", new String[] {"firstname", "lastname"});

System.Diagnostics.Debug.WriteLine(res);


// Retrieves only the firstname attribute
res = index.GetObject("myId", new String[] { "firstname" });

// Asynchronous
// res = await index.GetObjectAsync("myId", new String[] { "firstname" });

System.Diagnostics.Debug.WriteLine(res);
// Retrieves all attributes
Optional<Contact> contact = index.getObject("myId");

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

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

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

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

// Async version
// CompletableFuture<Optional<Contact>> contact = index.getObject("myId", Arrays.asList("firstname"));
// Retrieves the object with all its attributes
object, err := index.GetObject("myId", nil)

// Retrieves the object with only its `firstname` attribute
object, err = index.GetObject("myId", []string{"firstname"})

// Retrieves the object with only its `firstname` and `lastname` attributes
object, err = index.GetObject("myId", []string{"firstname", "lastname"})
// 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 a set of objects and send extra http headers

<?php
$extraHeaders = [
  'X-FORWARDED-FOR' => '94.228.178.246'
];

$attributesToRetrieve = null;

$objectIDs = [/* objectIDs */];
$index->getObjects($objectIDs, $attributesToRetrieve, $extraHeaders);
object_ids = []

attributes_to_retrieve = nil

extra_headers = {
  'X-Algolia-User-ID': 'user123'
}

res = index.get_objects(object_ids, attributes_to_retrieve, extra_headers)
client.setExtraHeader('X-FORWARDED-FOR', '94.228.178.246');
index.getObjects(['myId1', 'myId2'], function(err, content) {
  console.log(content);
});
request_options = RequestOptions({'algoliaUserID': 'user123'})
res = index.get_objects(["myId1", "myId2"], request_options=request_options)
let requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-User-ID"] = "user123"

index.getObjects(
  withIDs: ["myId1", "myId2"],
  requestOptions: requestOptions,
  completionHandler: { (content, error) -> {
    // do something
  }
)
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) {
      // [...]
    }
  }
);
RequestOptions requestOptions = new RequestOptions();
requestOptions.AddExtraHeader("X-Algolia-User-ID", "user123");

res = index.GetObjects(new String[] {"myId1", "myId2"}, requestOptions);

// Asynchronous
// res = await index.GetObjectsAsync(
//   new String[] {"myId1", "myId2"},
//   requestOptions
// );
// 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.getObjects(
  Arrays.asList("myId", "myId2"),
  new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123")
);
opts := &algoliasearch.RequestOptions{
  ExtraHeaders: map[string]string{
    "X-Algolia-User-ID": "userID2",
  },
}

objects, err = index.GetObjects([]string{"myId1", "myId2"}, opts)
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
Optional
default: ""

Comma separated list of attributes to retrieve.

By default, all retrievable attributes are returned.

requestOptions
type: key value mapping
Optional
default: No requestOptions

A mapping of request options to send along with the query.

objectID
type: integer|string
Required

The objectID of the object to get.

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

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

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

List of the retrieved objects.

Php small white
PHP
Ruby small white
Ruby
Javascript small white
JavaScript
Python small white
Python
Swift small white
iOS
Android small white
Android
Csharp small white
C#
Java small white
Java
Go small white
Go
Scala small white
Scala
Php small white
PHP
Ruby small white
Ruby
Javascript small white
JavaScript
Python small white
Python
Swift small white
iOS
Android small white
Android
Csharp small white
C#
Java small white
Java
Go small white
Go
Scala small white
Scala