java_small_white Created with Sketch.

Advanced

Custom batch - batch

You may want to perform multiple operations with one API call to reduce latency.

If you have one index per user, you may want to perform a batch operations across several indices. We expose a method to perform this type of batch:

//Sync version
Index<Contact> index1 = client.initIndex("index1", Contact.class);

//BatchOperations accepts an Index object or a String
client.batch(Arrays.asList(
  new BatchAddObjectOperation<>(index1, new Contact().setFirstName("Jimmie").setLastName("Barninger")),
  new BatchAddObjectOperation<>("index2", new Contact().setFirstName("Warren").setLastName("Speach")),
));
//ASync version
AsyncIndex<Contact> index1 = client.initIndex("index1", Contact.class);

//BatchOperations accepts an Index object or a String
client.batch(Arrays.asList(
  new BatchAddObjectOperation<>(index1, new Contact().setFirstName("Jimmie").setLastName("Barninger")),
  new BatchAddObjectOperation<>("index2", new Contact().setFirstName("Warren").setLastName("Speach")),
));

The attribute action can have these values:

  • addObject
  • updateObject
  • partialUpdateObject
  • partialUpdateObjectNoCreate
  • deleteObject

Backup / Export an index - browse

The search method cannot return more than 1,000 results. If you need to retrieve all the content of your index (for backup, SEO purposes or for running a script on it), you should use the browse method instead. This method lets you retrieve objects beyond the 1,000 limit.

This method is optimized for speed. To make it fast, distinct, typo-tolerance, word proximity, geo distance and number of matched words are disabled. Results are still returned ranked by attributes and custom ranking.

Response Format

Sample
{
  "hits": [
    {
      "firstname": "Jimmie",
      "lastname": "Barninger",
      "objectID": "433"
    }
  ],
  "processingTimeMS": 7,
  "query": "",
  "params": "filters=level%3D20",
  "cursor": "ARJmaWx0ZXJzPWxldmVsJTNEMjABARoGODA4OTIzvwgAgICAgICAgICAAQ=="
}
Fields
  • cursor (string, optional): A cursor to retrieve the next chunk of data. If absent, it means that the end of the index has been reached.
  • query (string): Query text used to filter the results.
  • params (string, URL-encoded): Search parameters used to filter the results.
  • processingTimeMS (integer): Time that the server took to process the request, in milliseconds. Note: This does not include network time.

The following fields are provided for convenience purposes, and only when the browse is not filtered:

  • nbHits (integer): Number of objects in the index.
  • page (integer): Index of the current page (zero-based).
  • hitsPerPage (integer): Maximum number of hits returned per page.
  • nbPages (integer): Number of pages corresponding to the number of hits. Basically, ceil(nbHits / hitsPerPage).

Example

This method does not exists in the Async version

// Iterate with a filter over the index
IndexIterable<Contact> it = index.browse(new Query("text").setFilters("i<42"));

// Iterate with a stream
it.stream.map(o -> {});

// Retrieve the next cursor from the browse method
IndexIterable<Contact> it  = index.browseFrom(new Query("text").setFilters("i<42"), null);
System.out.println(it.getCursor());

Get latest logs - getLogs

You can retrieve the latest logs via this API. Each log entry contains:

  • Timestamp in ISO-8601 format
  • Client IP
  • Request Headers (API Key is obfuscated)
  • Request URL
  • Request method
  • Request body
  • Answer HTTP code
  • Answer body
  • SHA1 ID of entry

You can retrieve the logs of your last 1,000 API calls and browse them using the offset/length parameters:

offset

Specify the first entry to retrieve (0-based, 0 is the most recent log entry). Defaults to 0.

length

Specify the maximum number of entries to retrieve starting at the offset. Defaults to 10. Maximum allowed value: 1,000.

onlyErrors

Retrieve only logs with an HTTP code different than 200 or 201. (deprecated)

type

Specify the type of logs to retrieve:

  • query: Retrieve only the queries.
  • build: Retrieve only the build operations.
  • error: Retrieve only the errors (same as onlyErrors parameters).
//Sync & Async version

// Get last 10 log entries
client.getLogs();

// Get last 100 log entries, of type build
client.getLogs(0, 100, LogType.LOG_BUILD);

Retry logic

Algolia’s architecture is heavily redundant, to provide optimal reliability. Every application is hosted on at least three different servers. As a developer, however, you don’t need to worry about those details. The API Client handles them for you:

  • It leverages our dynamic DNS to perform automatic load balancing between servers.
  • Its retry logic switches the targeted server whenever it detects that one of them is down or unreachable. Therefore, a given request will not fail unless all servers are down or unreachable at the same time.

Application-level errors (e.g. invalid query) are still reported without retry.

Error handling

Requests can fail for two main reasons:

  1. Network issues: the server could not be reached, or did not answer within the timeout.
  2. Application error: the server rejected the request.

In the latter case, the error reported by the API client contains:

  • an HTTP status code indicating the type of error;
  • an error message indicating the cause of the error.

The error message is purely informational and intended for the developer. You should never rely on its content programmatically, as it may change without notice.

Configuring timeouts

Network & DNS resolution can be slow. That is why we have pre-configured timeouts. We do not advise to change them, but it could make sense to change them in some special cases:

//Sync version
new ApacheAPIClientBuilder(...)
  .setConnectTimeout(4000)
  .setReadTimeout(4000)
  .setHostDownTimeout(4000);
//Async version
new AsyncHttpAPIClientBuilder(...)
  .setConnectTimeout(4000)
  .setReadTimeout(4000)
  .setHostDownTimeout(4000);