Guides / Sending and managing data / Format and structure your data

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"]

Integers and booleans are treated as strings by searchable attributes but they’re treated as numerical values by numerical facets.

Unique record identifier

The engine identifies each object with a unique objectID attribute.

You should set objectIDs yourself, based on your data. Since you use objectIDs to update and delete specific records, it’s easier if you’ve defined them yourself. If you don’t set objectIDs, Algolia generates them for you: you can check their values by browsing the index.

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, convert objectID into integers after retrieving the objects but make sure that all your objectIDs contain integer values.

Since objectID uniquely identifies your objects:

Acceptable characters for objectIDs

objectID strings can:

Dates

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

Reserved attribute names

Algolia’s API uses underscore prefixes to identify reserved attribute names, both in records and 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 attributes 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.

Did you find this page helpful?