> ## Documentation Index
> Fetch the complete documentation index at: https://www.algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Algolia records

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


export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

Algolia uses [JSON](https://www.json.org/) 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 JSON icon=braces theme={"system"}
[
  {
    "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"]
  }
]
```

<Info>
  Although integer and boolean values are treated as strings by
  [searchable attributes](/doc/guides/managing-results/must-do/searchable-attributes),
  they're interpreted as numbers for [numerical facets](/doc/api-reference/api-parameters/numericFilters).
  For example,
  Algolia treats `like_count` as a number.
</Info>

## Unique record identifiers

The `objectID` attribute is a unique identifier for each record.

**Set object IDs yourself**, based on *your* data.
If you don't set object IDs, Algolia assigns them automatically:
you can check their values by browsing the <Index />.

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

Since `objectID` uniquely identifies your objects, the following applies:

* **You can search for it** by declaring it as a [`searchableAttributes`](/doc/api-reference/api-parameters/searchableAttributes).
* **You can't highlight or snippet it**.
  If you declare `objectID` in [`attributesToHighlight`](/doc/api-reference/api-parameters/attributesToHighlight) or [`attributesToSnippet`](/doc/api-reference/api-parameters/attributesToSnippet), Algolia ignores it.
* **You can't exclude it from results**.
  If you declare `objectID` in [`unretrievableAttributes`](/doc/api-reference/api-parameters/unretrievableAttributes) or omit it from [`attributesToRetrieve`](/doc/api-reference/api-parameters/attributesToRetrieve), Algolia still returns it.
  For this reason, object IDs 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`](/doc/api-reference/api-parameters/attributesForFaceting),
  Algolia ignores it. [Faceting on a unique identifier](/doc/guides/managing-results/refine-results/faceting#faceting-on-object-id) makes little sense since every facet count would equal one.

### Keep object IDs stable

Derive each `objectID` from the unique identifier of the record's source, such as a database primary key or a product SKU.
Don't derive it from the record's content, for example by hashing the attributes you send.

An object ID must identify the same item for as long as that item exists:

* **Updates and deletions target an object ID.** If the ID changes when the content changes, an update creates a second record instead of replacing the first, and the original stays in the index until you delete it.
* **[Click and conversion events](/doc/guides/sending-events) reference an object ID.** If the ID changes, the record's event history splits across two IDs, and features that build on that history, such as Dynamic Re-Ranking, Recommend, and Personalization, lose the earlier signals.

When one source item becomes several Algolia records, for example when you split a long document into sections or flatten a product's variants, build each object ID from the source identifier plus a deterministic suffix:

```json JSON icon=braces theme={"system"}
[
  { "objectID": "sku-4815-section-1", "sku": "4815", "section": 1 },
  { "objectID": "sku-4815-section-2", "sku": "4815", "section": 2 }
]
```

Use a suffix that stays the same across reindexing, such as a variant identifier or a section anchor.
Don't use a value that shifts when the source changes, such as an array position or an incrementing counter.

### 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](https://support.algolia.com/hc/en-us/articles/4406981897617-Is-there-a-size-limit-for-my-index-records-).

## Dates

Date attributes must be formatted as [Unix timestamps](https://www.unixtimestamp.com) (for example, `1435735848`).

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

* Android: [`Date()`](https://developer.android.com/reference/java/util/Date#Date\(\))
* Go: [`time.Unix`](https://pkg.go.dev/time#Unix)
* Java and Scala (from the `java.time` package): [`getTime()`](https://docs.oracle.com/javase/7/docs/api/java/util/Date.html#getTime%28%29)
* JavaScript: [`getTime()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTime)
* Kotlin: [`kotlinx-datetime`](https://github.com/Kotlin/kotlinx-datetime#converting-instant-to-and-from-unix-time)
* C#/.Net: [`ToUnixTimeSeconds`](https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tounixtimeseconds)
* PHP: [`strtotime`](https://www.php.net/manual/en/function.strtotime.php)
* Python: [`datetime`](https://docs.python.org/3/library/datetime.html?highlight=datetime#datetime-objects)
* Ruby: [`date.to_time`](https://ruby-doc.org/stdlib-3.1.0/libdoc/date/rdoc/Date.html#method-i-to_time)
* Swift: [`NSDate(withTimeIntervalSince1970:)`](https://developer.apple.com/documentation/foundation/nstimeintervalsince1970)

<Note>
  Depending on the language,
  the output might require conversion from milliseconds to seconds.
</Note>

## Reserved attribute names

The following attribute names are reserved by Algolia.

* `_geoloc`
* `_highlightResult`
* `_rankingInfo`
* `_snippetResult`
* `_tags`
* `distinctSeqId`

<Note>
  The `_collections` attribute is reserved only if you're using InstantSearch to implement a [collections page](/doc/guides/solutions/ecommerce/browse/tutorials/collections#build-a-collections-page-with-instantsearch).
  If you're not using InstantSearch, `_collections` behaves like any other attribute.
</Note>

### In your records

In a record, you can use the `_tags` or `_geoloc` attribute names but they have an [imposed schema](/doc/guides/managing-results/refine-results/filtering/how-to/filter-by-attributes#filter-by-tags).
Other attribute names are schema-agnostic.

Algolia doesn't search reserved attribute names unless you explicitly include them in [`searchableAttributes`](/doc/api-reference/api-parameters/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.