Indexing

Creating indices

You don’t need to create an index explicitly: Algolia creates it automatically the first time you add an object. If you wish to configure your index, the settings section provides details about advanced settings. Since index objects are schemaless, you don’t need any pre-configuration to start indexing.

Be aware that the client.initIndex method doesn’t initialize an index. Instead, initIndexinstantiates an object that allows you to interact with an Algolia index at the API level(for example, to create multiple objects to query an index). If you’re using initIndex without doing anything with it afterward, nothing is sent to the API.

Make sure you don’t use any sensitive or personally identifiable information (PII) as your index name, including users’ names, IDs, or email addresses. Since index names appear in network requests, you should consider them publicly available.

Index objects

Index objects schema

The objects you index are schemaless: they can hold any number of fields, with any definition and content.

The engine has no expectations of what your data contains, other than some formatting concerns, and the objectID.

The objectID

Every object (record) in an index eventually requires a unique ID, called the objectID. You can create the objectID yourself and send it when indexing. If you don’t send an objectID, Algolia generates it for you.

Whether sent or generated, once you add a record, it has a unique identifier called objectID.

You can use this identifier later with any method that needs to reference a specific record, such as saveObjects or partialUpdateObjects.

Add, update, and partially update objects

saveObjects

The saveObjects method requires an objectID, unless you set autoGenerateObjectID to true.

• If the objectID exists, Algolia replaces the record
• If the objectID is present but doesn’t exist, Algolia creates the record
• If the objectID isn’t specified and autoGenerateObjectID is false (the default), the engine returns an error.
• If the objectID isn’t specified and autoGenerateObjectID is true, the engine generates an objectID and returns it in the response.

partialUpdateObjects

The partialUpdateObjects method requires an objectID.

• If the objectID exists, Algolia replaces the attributes
• If the objectID is specified but doesn’t exist, Algolia creates a new record
• If the objectID isn’t specified, the method returns an error

As mentioned earlier, partialUpdateObjects doesn’t replace the whole object, but adds, removes, or updates the attributes you pass. The remaining attributes remain untouched. This is different from saveObjects and saveObjects, both of which replace the whole object.

For all indexing methods

The method for all three can be singular or plural.

• If singular (for example, saveObject), the method accepts one object as a parameter
• If plural (for example, saveObjects), the method accepts one or multiple objects.

See the individual methods for more information on syntax and usage.

Asynchronous methods

Most of the indexing methods are asynchronous. What you are doing when calling these methods is adding a new job to a queue: it’s this job, and not the method, that performs the desired action. Usually, the engine performs the job within seconds, if not milliseconds. But it all depends on the queue: if the queue has multiple pending tasks, the new job needs to wait its turn.

To help manage this asynchronous indexing, each method returns a unique taskID which you can use with the waitTask method. Using the waitTask method guarantees that the job has finished before proceeding with your new requests. You can use this to manage dependencies. For example, when deleting an index before creating a new index with the same name or clearing an index before adding new objects.

Documentation terminology

Object and record

The documentation uses “object” and “record” interchangeably. Although different in the field of computer science, within Algolia’s domain, they’re the same:

• Indices contain “objects” or “records”
• JSON contains “objects” or “records”

Attributes

All objects and records contain attributes, sometimes referred to as fields or elements. Some attributes are key-value pairs, while others can be more complex, like a collection or an object.

Indexes and indices

The documentation uses these words interchangeably. The former is the American spelling, while the API often uses the latter, British spelling.