[anttiviljami]

Summary

Documents the consistency and freshness guarantees of the entity search & list APIs (which power entity tables), checked against the entity-api code.

• New page docs/entities/indexing-guarantees.md — Search Indexing Guarantees
  • Which operations read from the search index vs. the primary store
  • Write guarantees: default (searchable when the call returns) vs. ?async=true (eventual, no upper bound)
  • Related-entity data is re-indexed asynchronously (500 per change, nightly catch-up beyond that)
  • What is indexed (schema attributes only)
  • Search results: matching from the index, returned entities from the primary store, exact hits
  • Pagination: size ≤ 1,000, from + size ≤ 25,000 (silently clamped), search_after, stable queries
  • upsertEntity unique_key matching is not transactional
  • Repairing a stale entity with reindexEntity
• entity-api.md: info box in Search API, note under CRUD API, link from Stable Queries
• entity-tables.md: new Data Freshness section

Companion MR documenting the same in the entity-api OpenAPI spec: https://gitlab.com/e-pilot/product/entities/entity-api/-/merge_requests/1854

To check in review

• "Usually within a few seconds" for async indexing is not an SLA and was not measured
• 25,000 is the prod max result window; staging uses 10,000
• The page exposes the 500-relation fanout cap and the nightly catch-up job — drop if too much internal detail
• The page links to /docs/entities/indexing-guarantees from the OpenAPI spec in the companion MR, so the slug should stay stable

Test plan

• Docusaurus build passes in CI (not run locally)
• Internal links resolve (/docs/entities/entity-api#stable-queries, /docs/entities/capabilities, /docs/integrations/webhooks)

---

Generated by Claude Code