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
})