What Is in a Record

Algolia records

Algolia uses JSON to model records, making it more flexible and easier to configure.

Here’s an example of a typical record:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[
  {
    "objectID": 42,
    "title": "Breaking Bad",
    "episodes": [
      "Crazy Handful of Nothin'",
      "Gray Matter"
    ],
    "like_count": 978,
    "avg_rating": 1.23456,
    "air_date": 1356846157,
    "featured": true,
    "lead_role": {
      "name": "Walter White",
      "portrayed_by": "Bryan Cranston"
    },
    "_tags": ["tv series", "drugs"]
  }
]

Your records can have attributes with the following formats:

• string: "title": "Breaking Bad"
• integer: "like_count": 978
• float: "avg_rating": 1.23456
• boolean: "featured": true
• objects: "lead_role": { "name": "Walter White", "portrayed_by": "Bryan Cranston" }
• arrays: "episodes": ["Crazy Handful of Nothin'", "Gray Matter"]

Unique record identifier

The engine identifies each object with a unique objectID attribute.

You should set objectIDs yourself, based on your own data. When you don’t, Algolia generates one for you, and you can retrieve them by browsing the index. Later on, you need to use the objectIDs to update and delete specific records, so it’s easier when you’ve defined it yourself.

When you retrieve objects, objectIDs are in string format, even if you set them as integers. If you want to use integers in your application, you can convert every objectID into integers after retrieving the objects. In this scenario, make sure that all your objectIDs only contain integer values.

Because the objectID is as a unique identifier for your objects, the engine treats it special:

• You can search it by declaring it as a searchableAttributes.
• You can’t highlight or snippet it. If you declare objectID in attributesToHighlight or attributesToSnippet, the engine ignores it.
• You can’t exclude it from results. If you declare objectID in unretrievableAttributes, or omit it from attributesToRetrieve, the engine still returns it. For this reason, it’s important that objectIDs don’t contain any kind of sensitive data.
• You can use it as a facet filter, but you can’t facet it. If you declare objectID in attributesForFaceting, the engine ignores it. Faceting on a unique identifier makes little sense anyway, since every facet count would be equal to one.

Dates

If you want to filter or sort by date, then you should format date attributes as Unix timestamps (for example, 1435735848). The Algolia engine doesn’t interpret dates as ISO 8601 strings, so you must convert your dates into numeric values.

Reserved attribute names

The Algolia API uses underscore prefixes to identify reserved attributes name, both in records and in the search response.

In your records

In a record, you can use attribute names like _tags or _geoloc, but they have an imposed schema. All other attribute names are schema-agnostic.

Reserved words aren’t searchable by default. If you want to search into _tags or _geoloc, you need to add them to your searchableAttributes.

In the search response

In the search response, Algolia returns special attribute such as _highlightResult, _snippetResult, _rankingInfo or _distinctSeqID. They’re reserved Algolia attributes tied to specific features. Make sure not to use any of those in your records to avoid conflicts.