semantic_search_observations
Search observations by semantic similarity. Find moments that match a description like "lunch rush at fast casual restaurants" using vector embeddings.
Uses 768-dimensional Gemini embeddings on observation payloads to find promoted observations matching a natural language query via approximate nearest-neighbour (ANN) cosine similarity search over a Lance IVF_PQ index.
CONSISTENCY: results are APPROXIMATE and EVENTUALLY CONSISTENT.
Approximate: retrieval is ANN, not an exhaustive scan (measured recall ~0.96 against exact KNN), so an identical query may omit a borderline match.
Eventually consistent: the index is served from a replicated pool whose replicas refresh independently, so for up to 5 minutes after new observations are published, two identical calls may return slightly different result sets. The difference is confined to the VISIBILITY of newly-published observations; the relative ranking of already-visible ones does not change. Do not use this tool where a repeatable, exhaustive result set is required.
TIME BOUND: searches the last 30 days by default. Pass filters.time_range to widen or narrow it; the window actually applied is echoed in metadata.time_range. Observations are retained for 90 days.
WHEN TO USE:
Finding observations that match a conceptual description
Discovering contextual moments across the screen network
Searching for audience situations ("families waiting in line", "professionals on coffee break")
Finding commerce patterns ("high purchase intent near checkout")
RETURNS:
data: Array of matching observations ranked by semantic similarity, each with:
observation_id, device_id, venue_type, observation_family
observed_at, payload, confidence, evidence_grade
similarity: Cosine similarity score (0-1, higher = more relevant)
metadata: { result_count, query_embedding_model, search_scope, time_range }
suggested_next_queries: Related semantic queries to explore
EXAMPLE: User: "Find lunch rush moments at fast casual restaurants" semantic_search_observations({ query: "lunch rush at fast casual restaurants with high foot traffic", filters: { venue_type: ["restaurant_qsr"] }, limit: 20 })
User: "Find moments with high emotional engagement" semantic_search_observations({ query: "audience showing strong positive emotional reactions", filters: { observation_family: ["audience"] }, limit: 10 })
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results to return (default: 20, max: 100) | |
| query | Yes | Natural language description of the observation moments to search for | |
| filters | No | Additional structured filters to narrow semantic search |