The search model

Splendor exposes three ways to search, and they share one response shape. Whether you run a keyword query, a SQL projection, or a semantic lookup, you get back the same envelope with the same fields — so you can switch modes without rewriting how you read results.

The three modes

Text
Semantic
SQL

Keyword and full-text search with relevance ranking. Send text (or q) with the datasets to search. Scores are bm25.

{
  "text": "connection timeout",
  "datasets": ["app-logs"],
  "limit": 20
}

Add structured where filters, a time range, and aggregations to narrow and summarize. A filter-only request (no text) browses records that match the filter.

Vector search that retrieves records by meaning rather than exact terms. Set semantic: true with query text. Scores are vector (or hybrid when blended).

{
  "text": "users can't log in",
  "datasets": ["support-tickets"],
  "semantic": true,
  "limit": 20
}

Semantic search is top-K retrieval, not a complete matching set, so its total is reported as {"value": null, "relation": "unknown"}. Use content_filter to choose modalities: text (default), images, or all to search both and merge.

Query the dataset’s inferred schema with SQL. Translate first with POST /v1/sql/translate to validate against the schema, then run with POST /v1/sql/search.SQL responses add a columns list, and each result places its projected values in row. Scores are sql.

Filtering on metadata

where clauses filter every mode. To make a field filterable, declare it under the source’s semantic.filters with a type so its values are indexed as a typed attribute:

{
  "semantic": {
    "filters": {
      "fields": [
        { "field": "severity", "type": "keyword" },
        { "field": "status_code", "type": "i64" },
        { "field": "tags", "type": "keyword", "array": true }
      ]
    }
  }
}

Types are keyword, i64, f64, bool, datetime, and ip. A where clause names the field, an operator, and a value:

Field kind	Supported operators
Scalar	`eq`, `in`, `prefix` (keyword), `gt`/`gte`/`lt`/`lte` (numbers, datetimes)
Array (`array: true`)	`eq` (the list contains the value), `in` (the list contains any of the values)

Declare a field as array when it holds a list of values (for example tags); it is stored as a distinct multi-valued attribute, so the same path can’t be both scalar and array within a dataset. Filters declared after records were indexed apply to new records immediately; to apply one to existing records, run a filter backfill.

The response envelope

Every mode returns this shape. The fields make truncation explicit so you never have to guess whether more results exist.

{
  "search_id": "srch_...",
  "mode": "text",
  "datasets": ["app-logs"],
  "returned": 20,
  "limit": 20,
  "total": { "value": 1240, "relation": "eq" },
  "has_more": true,
  "next_cursor": "opaque-or-null",
  "route": "hot",
  "wall_ms": 183.4,
  "results": [ /* normalized results */ ],
  "aggregations": {}
}

Field	Meaning
`search_id`	A handle for paging, export, or saving a view.
`total`	`{ value, relation }`. `relation` is `eq`, `gte`, or `unknown`. Semantic totals are always `unknown`.
`has_more` / `next_cursor`	Whether more results exist and the opaque cursor to fetch them.
`route`	Where the query executed: `hot`, `cold_lambda`, or `async_export`.
`truncated_reason`	Present when results were capped — for example `max_candidates` or `export_required`.

Each result is normalized to a common form regardless of mode:

{
  "id": "rec_...",
  "body": "canonical text",
  "snippets": ["matched text"],
  "score": 12.4,
  "score_kind": "bm25",
  "provenance": { "dataset_id": "...", "source": "...", "line": 123 }
}

Readiness gates which modes work

A dataset answers text and sql queries once it is text-search ready, and semantic queries once embeddings are built. Check readiness before relying on a mode. Semantic search additionally requires the tenant’s semantic backend to be configured; when it is not, semantic requests return a clear error.

Prefer refining a query over walking pages. When has_more is true, narrowing your text, where, or time usually beats fetching cursor after cursor — and for exhaustive traversal, use an export or a view instead.

Get started

Core concepts

Guides

Build a platform

Roles, permissions & plans

Platform reference

The three modes

Filtering on metadata

The response envelope

Readiness gates which modes work

​The three modes

​Filtering on metadata

​The response envelope

​Readiness gates which modes work

The three modes

Filtering on metadata

The response envelope

Readiness gates which modes work