Algolia records

Learn about Algolia records: attributes, types, limits, formatting, nesting, and more.

Algolia uses JSON to model records.

Your records can have attributes with the following types:

Type	Example
String	"title": "Breaking Bad"
Integer	"like_count": 978
Float	"avg_rating": 1.23456
Boolean	"featured": true
Object	"lead_role": { "name": "Walter White", "portrayed_by": "Bryan Cranston" }
Array	"episodes": ["Crazy Handful of Nothin'", "Gray Matter"]

For example, this record includes different data types and the _tags reserved attribute:

JSON

[
  {
    "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"]
  }
]

Although integer and boolean values are treated as strings by searchable attributes, they’re interpreted as numbers for numerical facets. For example, Algolia treats like_count as a number.

Unique record identifiers

The objectID attribute is a unique identifier for each record.

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 assigns them automatically: you can check their values by browsing the index.

When you retrieve records, objectIDs are in string format, even if you set them as integers. If you want to use integers in your app, convert objectID to integers after retrieving the records but make sure that all your objectIDs contain integer values.

Since objectID uniquely identifies your objects, the following applies:

• 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, Algolia ignores it.
• You can’t exclude it from results. If you declare objectID in unretrievableAttributes or omit it from attributesToRetrieve, Algolia 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, Algolia ignores it. Faceting on a unique identifier makes little sense since every facet count would equal one.

Acceptable characters for object IDs

objectID strings can:

• Contain any character.
• Be of any length as long as the record fits within your plan’s size limit.

Dates

Date attributes must be formatted as Unix timestamps (for example, 1435735848).

To convert dates to Unix timestamps, use an appropriate function for your programming language, for example:

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

Depending on the language, the output might require conversion from milliseconds to seconds.

Reserved attribute names

The following attribute names are reserved by Algolia.

• _geoloc
• _highlightResult
• _rankingInfo
• _snippetResult
• _tags
• distinctSeqId

The _collections attribute is reserved only if you’re using InstantSearch to implement a collections page. If you’re not using InstantSearch, _collections behaves like any other attribute.

In your records

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

Algolia doesn’t search reserved attribute names unless you explicitly include them in searchableAttributes.

In the search response

Algolia returns _highlightResult, _snippetResult, _rankingInfo, and _distinctSeqID in the search response. They’re reserved Algolia attributes tied to specific features. To avoid conflicts, don’t specify these attribute names in your records.