SemiLayerDocs

Query

The structured-read primitive. Where search ranks rows by semantic similarity over the vector index, query hits your source database directly through the bridge and returns exact matches. Use it for admin list views, filter-driven pages, reporting exports, and anywhere real-time source data beats ranked relevance.

queryproducts
products: {
  source: 'main-db',
  table: 'public.products',
  fields: {
    id:       { type: 'number',  primaryKey: true },
    name:     { type: 'text' },
    category: { type: 'enum',    values: ['footwear', 'apparel', 'accessories'] },
    price:    { type: 'number' },
    in_stock: { type: 'boolean' },
  },
  grants: {
    query: 'public',   //  ← REQUIRED. query() is off unless you opt in
  },
}

Flip Config between JSON and the Console lens editor, Explorer for the where-predicate view, Call between Client / HTTP / WebSocket / cURL.

ℹ️

Play with query on real data at demo.semilayer.com/query — build a where clause, pick ordering, scroll through the rows.

What query does (and doesn't)

  • Does: equality + range predicates, orderBy, limit/offset + cursor pagination, field projection with select, row-level security via X-User-Token, join expansion via include.
  • Doesn't: semantic ranking, fuzzy matching, relevance scores. That's search.
⚠️

grants.query is required. query() is disabled by default on every lens. Set grants: { query: 'public' | 'authenticated' | ... } to opt in. The Beam codegen respects this — if the grant isn't set, no query() method is emitted for that lens.

searchquery
Reads fromVector indexSource DB via bridge
FreshnessAt last ingestReal-time
Ranks byVector similarityorderBy (your call)
Query shapeNatural languagewhere predicate
Latency~10–50msDepends on source
CostIndex lookup onlyA round-trip to your DB

They're complementary. A common pattern: use query to narrow the candidate pool to a few thousand rows, then use search to rank within that pool. See Search — Filters & mode.

Three shapes from one primitive

  1. Exact list — where: { category: 'footwear' }. Equality filters. Fast, obvious, the most common shape.
  2. Operator filter — where: { rating: { $gte: 4 }, price: { $lt: 100 } }. Ranges, $in, inequality.
  3. Paginated scroll — limit + cursor for datasets that don't fit in one response. See Pagination.

Where to start

  • Quickstart — enable grants.query on an existing lens and make your first call.
  • Predicates — the full where grammar: operators, arrays, limits.
  • Pagination — offset vs cursor, and stream.query for large exports.
  • Recipes — admin list view, reporting export, filter-driven browse, activity timeline.