What Is in a Record

Algolia uses JSON to model records.

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 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:

• You can search for 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, objectIDs mustn’t contain any 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 since every facet count would equal one.

Acceptable characters for objectIDs

objectID strings can:

• Contain any character
• Be of any length as long as it fits the size limit for your plan.

Dates

If you want to filter or sort by date, you must format date attributes as Unix timestamps (for example, 1435735848). Since Algolia’s engine doesn’t interpret dates as ISO 8601 strings, you must convert them into numeric timestamp values, using the appropriate functions for your chosen programming language:

• Android - Date()
• Go - time.Unix
• Java/Scala (java.time package) - getTime()
• JavaScript - getTime()
• Kotlin - kotlinx-datetime
• .Net - ToUnixTimeSeconds
• PHP - strtotime
• Python - datetime
• Ruby - date.to_time
• Swift - NSDate(withTimeIntervalSince1970:)

Depending on the function, the output may need further manipulation to produce an integer value in seconds.

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 _tags or _geoloc, you must 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.