Indexes, records and objectIDs

Index

An index is a named collection of records that gets searched together, with its own settings — the searchable attributes, ranking rules, synonyms and pins. Most sites need one index (docs); an app with distinct content types, like Toread's docs and its reading library, uses one index per type (toread-docs, toread-library).

Record

A record is one searchable unit of content: a page, a section of a page, a product, a highlight. A record is JSON with no fixed schema beyond one required field:

{
	"objectID": "getting-started-quickstart-cli",
	"title": "Quickstart: npx @suo/cli init",
	"url": "https://docs.example.com/getting-started/quickstart-cli",
	"content": "…"
}

Every other attribute is yours to define, and you choose which ones are searchable and which are just returned alongside a hit (see Index-time vs query-time settings). A record is capped at 100 KB.

objectID

objectID is the record's identity. It is how you update or delete it later, and it is what a click event refers back to. Use something stable: a page's path, a database primary key, a highlight's own ID. Do not use a value that changes when the content changes — that turns an update into an orphaned duplicate. objectID is at most 512 characters.

Writing records

Records are written in batches of up to 1,000 operations, each an upsert or a delete:

{
	"operations": [
		{ "action": "upsert", "record": { "objectID": "a", "title": "…" } },
		{ "action": "delete", "objectID": "b" }
	]
}

See Write records for the full request and response shape, and Versions and last-writer-wins for how concurrent writes are resolved.