Search

Universal search in PixService is a scoped lexical search surface over:

• clusters
• locations
• documents
• document passage text
• spatial metadata

Every query is reduced to resources the caller can already access. Clients do not query the search backend directly.

How Search Works

POST /v1/search/suggestions returns low-latency autocomplete suggestions while the user is typing.

POST /v1/search returns ranked results across multiple result types in one response. The current runtime uses lexical matching and deterministic ranking. AI planning, reranking, and assistant-style answers are not part of the active search flow.

Every search response also carries a searchId. Clients should treat that id as the server-authoritative search session identifier for telemetry.

Document Previews

Document-related results can include preview text from indexed document passages:

• item.snippet contains the preview excerpt
• item.source.documentId identifies the source document
• item.source.pageNumber points to the matching page when available
• item.source.chunkIndex points to the indexed chunk inside that page or text stream

This lets clients show relevant text before opening the original file.

Indexing Model

PostgreSQL remains the source of truth for application data and permissions.

OpenSearch is used as a secondary search index for:

• asset documents for clusters, locations, documents, and annotations
• passage documents for document text retrieval and previews

Background jobs project PostgreSQL data into those search indexes.

Search indexing is eventually consistent:

• newly uploaded or updated documents may take a short time to appear
• admin users can trigger single-document reindexing
• admin users can also trigger a full backfill for older documents
• admin users can trigger a full asset-index rebuild for clusters, locations, annotations, and document metadata

Access Control

The API remains the authorization boundary:

• the caller authenticates against PixService
• PixService resolves the caller's effective scope
• PixService applies authorization filters to every search query
• only filtered results are returned to the client

That design works with the current scoped sharing model and is intended to stay compatible with future role-based access control.

Telemetry

PixService records the search impression on the server when the search response is generated.

Clients should then report follow-up interactions with POST /v1/search/interactions, using the returned searchId. Supported interaction classes include:

• result clicks
• preview opens
• document opens
• downloads
• snippet copies
• query reformulations