SemiLayerDocs

Search — Fields & weights

Semantic search lives or dies by the lens's fields block and each field's searchable flag. This is the page to read before your first production lens.

The rule: searchable is opt-in

Only fields where searchable is true or { weight: N } are embedded and included in search ranking. Everything else is stored as metadata — returned in the result payload, filterable in query(), but invisible to search().

searchableWhat happens
trueField is embedded, contributes to the vector with weight 1
{ weight: N }Field is embedded, contributes with weight N (repeats N times in the embedding text)
false / omittedNot embedded. Field is stored and queryable, but doesn't affect search ranking
⚠️

Do not mark IDs, timestamps, or numeric codes as searchable. They'll waste embedding cost and pull the vector in a meaningless direction. Reserve searchable for natural-language content.

Weights change the ranking, not the cost

A weight of 3 on name vs 1 on description means a name match scores roughly three times as high as an equivalent description match. Weights don't cost extra embedding API calls — each field is still embedded once.

searchproducts
products: {
  source: 'main',
  table: 'products',
  fields: {
    id:          { type: 'number', primaryKey: true },
    name:        { type: 'text',   searchable: { weight: 3 } },
    description: { type: 'text',   searchable: true },
    category:    { type: 'enum',   values: ['headphones', 'footwear', 'apparel'] },
    brand:       { type: 'text' },   // stored, not embedded
  },
  grants: { search: 'public' },
}

Note that brand and category are NOT searchable — they're metadata. They come back in the result rows, and you can filter on them via query(), but they don't influence the ranking.

Common patterns

  • Product catalog: name with { weight: 3 }, description as true. Brand/category stored as metadata.
  • Docs / articles: title with { weight: 2 }, body as true. Tags as metadata.
  • People directory: name with { weight: 2 }, bio and skills as true. Team/role as metadata.
  • Tickets: subject and body both as true. Status, priority, assignee as metadata.

Up next: Filters — combining structured predicates with vector ranking.