Indexing

Creating indices

You don’t need to explicitly create an index, Algolia creates it automatically the first time you add an object.

Objects are schemaless so you don’t need any pre-configuration to start indexing.

If you wish to configure your index, the settings section provides details about advanced settings.

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

Index objects

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 partial update objects

addObjects

The addObjects method doesn’t require an objectID.

• If you specify an objectID:
  • If the objectID doesn’t exist in the index, Algolia creates the record
  • If the objectID already exists, Algolia replaces the record
• If you don’t specify an objectID:
  • Algolia generates an objectID and returns it in the response

saveObjects

The saveObjects method requires an objectID.

• 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, the method returns an error

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

Note: 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 addObjects 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, addObject), the method accepts one object as a parameter
  • If plural (for example, addObjects), the method accepts one or multiple objects

Note: see the individual methods for more information on syntax and usage.

Terminology

Object and record

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

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

Indexes and indices

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

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.

Asynchronous methods

Most of these methods are asynchronous. What you are actually doing when calling these methods is adding a new job to a queue: it’s this job, and not the method, that actually 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.