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
• admin users can repair authorization metadata for one organization with POST /v1/search/index/assets/authorization/organizations/{organizationId}/repair

When access or an organization's entitlement version changes, PixService also reconciles the authorization freshness stored with indexed assets and passages. During that convergence window, stale index branches fail closed and may temporarily return fewer results; they are never widened using older access. The service records terminal convergence only after both asset and passage updates complete without timeout, conflict, or item failure.

Access Control

The API and relational permission evaluator remain the authorization boundary:

• the caller authenticates against PixService
• PixService resolves final permissions after organization entitlement ceilings, visibility gates, and PAT scope narrowing
• PixService applies that authorization plan before search matching, ranking, paging, snippets, and result-derived suggestions
• only filtered results are returned to the client

PixService also verifies indexed response identities and freshness against the same plan before using any returned field. An inconsistent indexed batch is discarded and served from the exact PostgreSQL fallback, so a stale or invalid filename, path, snippet, or count cannot be partially retained.

Authorization query size is bounded before PixService contacts OpenSearch. If the current scope exceeds those safe limits, search and suggestions return a retryable 503 problem response with code search_authorization_plan_too_large. Clients may narrow the organization, cluster, or location scope before retrying; they must not reuse an older result set as a fallback.

If an entitlement version makes Document read unavailable, existing Documents remain stored but stop contributing to search results, passage previews, typo vocabulary, and suggestions until current access permits them again.

Telemetry

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

Suggestion history is isolated by the caller's current authorization-plan fingerprint, so terms recorded under older access cannot seed a later response. Result interactions are accepted only for results that were present in the caller's filtered impression.

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