SemiLayerDocs

Search

The simplest operation SemiLayer offers — and the one that earns its keep first. Turning a table into a semantic endpoint is two moves: mark the relevant columns searchable: true on the field, grant search access under grants.search. SemiLayer embeds them, and beam.<lens>.search(params) ranks rows by vector similarity. No separate index to manage, no custom sync code, no query DSL.

searchdishes
dishes: {
  source: 'main',
  table: 'dishes',
  fields: {
    id:          { type: 'number', primaryKey: true },
    name:        { type: 'text',   searchable: true },
    description: { type: 'text',   searchable: { weight: 2 } },
    cuisine:     { type: 'enum',   values: ['thai', 'japanese', 'italian', 'mexican'] },
  },
  grants: {
    search: 'public',
  },
}

Flip between Config, Explorer, Call, and Result above — the same lens, shown four ways. Config toggles between raw JSON and a slice of the Console lens editor; Call toggles between the Beam client, raw HTTP, streaming WebSocket, and cURL. This is the shape every page in this section will take: one config, one canonical call, one predictable result.

ℹ️

Want to see search running against real data? demo.semilayer.com/search is a working playground — type a query, watch results rank in real time.

ℹ️

searchable is opt-in. Only fields where searchable is true or { weight: N } are embedded. A field declared { type: 'text' } with no searchable is stored as metadata but never vectorized — useful for display-only columns like URLs, slugs, or human-readable IDs.

What search does (and doesn't)

search is a declarative vector search primitive. You mark fields as searchable; SemiLayer handles the rest — embedding on push, storing and indexing the vectors, and ranking query results.

  • Does: semantic ranking over free-text queries, typo tolerance, cross-language recall, per-field weight tuning, RBAC enforcement, streaming results over WS.
  • Doesn't: keyword-only scoring unless you pass mode: 'keyword', server-side aggregations (use beam.<lens>.query()), document-level BM25.

If your query is "show me dishes where cuisine = 'thai'", that's Direct Queries, not search. If your query is "something spicy with broth", that's search.

Three shapes from one primitive

  1. Semantic — the default. { query: string } in, ranked rows out. Powers type-ahead, discovery pages, chat-grounding.
  2. Filtered — narrow the candidate pool before ranking with a pre-query. See Filters.
  3. Hybrid — request-time mode: 'hybrid' (or beam.<lens>.searchHybrid(...)) blends semantic similarity with a keyword score for queries that contain both intent and exact tokens (SKU, brand, proper noun).

Where to start

  • Quickstart — copy-paste config + your first beam.search call in under 60 seconds.
  • Fields & weights — the searchable flag, weight tuning, cost implications.
  • Filters — combining vector ranking with structured predicates.
  • Recipes — product catalog, docs, people directory, support tickets.