Search

search() is the heart of retrieval. It runs a hybrid query (a full-text search over text and a vector search over the embedded content) and merges the two with an RRF reranker (Reciprocal Rank Fusion). You get keyword precision and semantic recall in one ranked list, typed against your metadata.

Basic search

Pass a query string. The query is embedded with the table’s embedding model and matched against stored vectors and the full-text index at once.

const results = await table.search("retrieval augmented generation");
// ({ id: string } & { metadata: { ... } })[]

Each result is a full record ({ id, text, metadata }) ordered by relevance.

Options

const results = await table.search("vector databases", {
  limit: 5,
  select: ["title", "category"],
  filter: { field: "category", op: "=", value: "AI" },
  nprobes: 20,
  refineFactor: 10,
  fastSearch: true,
});

Option	Type	Default	Description
`limit`	`number`	`10`	Maximum number of results to return.
`select`	`(keyof metadata \| "id" \| "text")[]`	all columns	Columns to return; `id` is always included.
`filter`	`Filter<DataType>`	—	Conditions to scope results. See Filtering.
`nprobes`	`number`	—	Number of IVF partitions to search. Higher values improve recall but cost speed.
`refineFactor`	`number`	—	Multiplier for extra candidates during the IVF-PQ refine step, improving accuracy.
`fastSearch`	`boolean`	`true`	Skip un-indexed data for faster queries when indexes are up to date.

Selecting columns

select limits which columns come back. Use your metadata field names (they resolve to the underlying columns automatically) alongside id and text. id is always included even if you omit it.

const results = await table.search("billing", { select: ["title"] });

Filtering results

filter narrows results to matching rows before ranking. Conditions compose with AND, OR, and NOT.

const results = await table.search("machine learning", {
  limit: 10,
  filter: {
    AND: [
      { field: "category", op: "=", value: "AI" },
      { NOT: { field: "title", op: "LIKE", value: "%draft%" } },
    ],
  },
});

See Filtering for the full operator set.

Tuning recall and speed

The vector half of the search uses an IVF-PQ index, which trades exactness for speed. Three knobs let you tune that trade-off. nprobes sets how many index partitions to scan. More partitions find more true neighbors (higher recall) but take longer, so raise it when results miss relevant rows. refineFactor controls how many extra candidates are re-ranked with full-precision vectors before returning; higher values sharpen the ranking at some cost. fastSearch defaults to true, in which case only indexed data is searched. If you have just added rows and want them included before the index catches up, set it to false.

Start with the defaults. Increase nprobes first if results feel incomplete, then add a small refineFactor (e.g. 10) if the ordering needs sharpening. Measure on your own data, since the right values depend on table size and embedding model.

Inspecting query plans

When a query is slower than expected, inspect its plan to see which indexes are used and where time goes. Both methods accept limit and filter like search().

`explainPlan()`

Returns the resolved query plan as a string without executing the query. Useful for confirming an index is being used.

const plan = await table.explainPlan("retrieval augmented generation", {
  limit: 10,
  verbose: true,
});
console.log(plan);

Option	Type	Default	Description
`limit`	`number`	`10`	Result limit used when planning.
`filter`	`Filter<DataType>`	—	Filter applied in the plan.
`verbose`	`boolean`	`true`	Include detailed plan information.

`analyzePlan()`

Executes the query and returns a physical plan annotated with runtime metrics: rows scanned, time per stage, and so on. Use it to find the actual bottleneck.

const analysis = await table.analyzePlan("retrieval augmented generation", {
  limit: 10,
});
console.log(analysis);

analyzePlan() runs the query for real to collect metrics, while explainPlan() only resolves the plan. Reach for explainPlan() first; use analyzePlan() when you need measured timings.

Getting Started

AI

Framework

Command Line

Basic search

Options

Selecting columns

Filtering results

Tuning recall and speed

Inspecting query plans

`explainPlan()`

`analyzePlan()`

​Basic search

​Options

​Selecting columns

​Filtering results

​Tuning recall and speed

​Inspecting query plans

​explainPlan()

​analyzePlan()

Basic search

Options

Selecting columns

Filtering results

Tuning recall and speed

Inspecting query plans

`explainPlan()`

`analyzePlan()`