Indexing

Creating indices

You don’t need to explicitly create an index, as it will be automatically created 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 customer names, user IDs, or email addresses. Index names appear in network requests and should be considered publicly available.

Index Objects

Schemaless

The objects sent to our Indexing methods schemaless: your objects can contain any number of fields, of any definition and content.

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

The Object ID

That said, every object (record) in an index eventually requires a unique ID, called the objectID. This is the only field you are sure to see in an index object.

You can create the ID yourself or Algolia can generate it for you. Which means that you are not required to send us an objectID.

Whether sent or generated, once a record is added, it will have a unique identifier called objectID.

This ID will be used later by any method that needs to reference a specific record, such as Update Objects or Partial Updates.

Add, Update and Partial Update differences

Add Objects

The Add Objects method does not require an objectID.

• If you specify an objectID:
  • If the objectID does not exist in the index, the record will be created
  • If the objectID already exists, the record will be replaced
• If you do not specify an objectID:
  • Algolia will automatically assign an objectID, which will be returned in the response

Update Objects

The Update Objects method requires an objectID.

• If the objectID exists, the record will be replaced
• If the objectID is specified but does not exist, the record is created
• If the objectID is not specified, the method returns an error

Note: Update Object is also known as Save Object. In this context, the terms are used interchangeably.

Partial Update Ojects

The Partial Update Objects method requires an objectID.

• If the objectID exists, the attributes will be replaced
• If the objectID is specified but does not exist, the record is created
• If the objectID is not specified, the method returns an error

Note: As already discussed, Partial Update does not replace the whole object, it only adds, removes, or updates the attributes mentioned; the remaining attributes are left untouched. This is different from Add Object and Update Object, both of which replace the whole object.

For all three

• The method for all three can be singular or plural.
  • If singular (e.g. AddObject), the method accepts only one object as a parameter
  • If plural (e.g. AddObjects), the method can accept one or many objects

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

Terminology

Object = Record

We use the words “object” and “record” interchangeably. Sometimes within the same sentence. While they can certainly be different within the field of computer science, for us, they are the same. So don’t place any significance on their usage:

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

Indexes = Indices

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

In our documentation, we try to always use “indices”.

Don’t place any significance on their usage.

Attribute

All objects and records contain attributes. Sometimes we refer to them as fields, or elements. Within the search and indexing contexts, we often speak of settings and parameters. Again, these terms are mostly interchangeable.

Some attributes are simple key/value pairs. But others can be more complex, as in Java or C#, where they are often 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 is this job, and not the method, that actually performs the desired action. In most cases, the job is executed within seconds if not milliseconds. But it all depends on what is in the queue: if the queue has many pending tasks, the new job will need to wait its turn.

To help manage this asynchronicity, each method returns a unique task id 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 will want to 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.

This is used most often in debugging scenarios where you are testing a search immediately after updating an index.