Which Query Type Do I Use? (v2, Beta)

v2 exposes one JSON query language over several endpoints. They share from / where / select; the endpoint (and a couple of top-level keys) picks the task. This guide is the "I know my problem, which endpoint?" map.

Quick reference

You want to…	Endpoint	Top-level key	Returns
Filter & project rows	_query	where / select	matching rows
Classify / fill a field	_predict	predict	ranked values with $p
Rank options for an outcome	_recommend	recommend + goal	ranked candidates
Estimate a number	_estimate	estimate	a single numeric value
BM25 relevance search	_search	search	rows ranked by $score
Mine co-occurring patterns	_relate	relate	itemsets / correlations

There is no _similarity endpoint in v2 (it returns 404). Similarity is an in-query operator — $nearest (vector) and $knn/$nn (feature) — that composes inside any where/orderBy, which is strictly more flexible. ($similarity is the per-row score those operators expose, not the operator itself.)

v2 works on v2 collections

v2 is built for v2 collections ("type": "collection") — the CollectionDb engine, with native full-text search, links, vectors, and calibrated inference. A legacy rep1 table ("type": "table") can still be reached through /api/v2 for basic where / select filtering and predict, but that support is deliberately minimal — v1 tables are being retired. In particular the text matchers $match / $search (and a few other operators) are not available on a rep1 table via /api/v2; they fail loud with a message pointing here, rather than returning a wrong result.

To use v2 fully on data that currently lives in a v1 table:

• Migrate it to a v2 collection — see Schema Migration. New tables should be defined as "type": "collection" from the start.
• Or branch it into an environment and trial v2 features there, without touching production — the recommended way to test v2 on existing data.

For full-text search (and the other v1-native operations) on a table you haven't migrated, keep using the mature v1 API.

Query vs Predict — retrieve vs infer

_query returns the rows that match — deterministic, exact. Use it to filter, project, and page.

{ "from": "products", "where": { "name": { "$match": "milk" } },
  "select": ["name", "price"], "limit": 5 }

_predict infers the most likely values of a field from evidence, with a calibrated probability. Use it to classify or fill an unknown.

{ "from": "products", "where": { "name": { "$match": "milk" } },
  "predict": "category", "select": ["$value", "$p"] }
// -> [{ "$p": 0.738, "$value": "104" }, { "$p": 0.140, "$value": "109" }, …]

Rule of thumb: "which rows?" → _query; "which value is this likely to be?" → _predict.

Predict vs Recommend — classify vs optimize

_predict completes a single field for one row's evidence — "what GL code for this invoice?".

_recommend ranks candidates by how well each achieves a stated goal — "which product to surface so an impression converts?". It needs a goal.

{ "from": "impressions", "recommend": "product",
  "goal": { "purchase": true }, "select": ["$value", "$p"] }

Predict answers "what is this?"; recommend answers "which one should I pick to get outcome X?".

Predict vs Estimate — categorical vs numeric

_predict is for categorical targets — it returns a probability distribution over discrete values.

_estimate is for a numeric target — it returns one number.

{ "from": "products", "where": { "name": { "$match": "milk" } },
  "estimate": "price" }
// -> { "estimate": 1.62 }

If the target is a category/label/tag → _predict. If it's a price, quantity, or duration → _estimate.

Search vs the $match filter — ranked vs boolean

$match inside a _query where is a boolean filter — a row either contains the tokens or it doesn't.

_search ranks rows by BM25 relevance and returns a $score (and $highlight). Use it for "most relevant first", agent-assist, and FAQ retrieval.

{ "from": "prompts", "search": { "field": "prompt", "text": "refund" },
  "select": ["prompt", "$highlight"], "limit": 5 }

Content similarity — operators, not an endpoint

To rank by similarity, use an operator inside a query:

• $knn / $nn — feature similarity (BM25 on text, shared features elsewhere). No vectors needed.
• $similarity / $nearest — vector similarity on a Vector column.

{ "from": "products", "where": { "$knn": { "near": { "name": "semi-skimmed milk" } } },
  "select": ["name", "$similarity"], "limit": 3 }

Relate — discover patterns

_relate with { "$patterns": … } mines co-occurring itemsets (market basket, association rules) directly from array/set/text columns — no export, no batch job.

{ "from": "products", "relate": { "$patterns": ["tags"] } }

See Market Basket Analysis.

Decision tree

                       What do you need?
                              │
     ┌───────────┬────────────┼────────────┬───────────┐
     │           │            │            │           │
  exact       relevance    infer a      optimize    discover
  rows        ranking      value        an outcome   patterns
     │           │            │            │           │
  _query      _search    ┌────┴────┐   _recommend   _relate
                         │         │
                    categorical  numeric
                     _predict   _estimate

   want "similar to X"? → $knn / $similarity operator inside a _query

Summary

Endpoint	Input	Output	Use when
_query	where / select	matching rows	you know exactly what to fetch
_search	search block	rows + $score	you want relevance-ranked results
_predict	evidence where	values + $p	you're classifying / filling a category
_estimate	evidence where	one number	you're predicting a numeric value
_recommend	recommend + goal	ranked candidates	you're optimizing for an outcome
_relate	relate $patterns	itemsets	you're discovering correlations

Related: Query Reference · Inference · Use Cases · Sandbox