Tutorial: Building with CleaveDB

Meaning Search

A structured filter is precise when the application knows the field and value it needs. Discovery often starts differently: a person knows the idea they want, but not the exact words stored in a document. SCOOP supports an explicit MEANING modifier for semantic search, so that request can sit alongside the bucket and any structured conditions.

Describe the idea in ordinary language

CleaveDB uses its ONNX Transformer vector-search engine to compare the query’s meaning with document embeddings. Use this when exact keyword matching would be too brittle—for instance, someone searching a recipe archive for a delicious slice of pizza may not know whether the stored title says “pizza,” “margherita,” or “tomato and mozzarella.” The semantic request can surface related descriptions even when their wording differs.

SCOOP articles MEANING "a delicious slice of pizza"

When documents are written, CleaveDB generates embeddings from their text fields through a background worker. Because that work is asynchronous, a newly written document may become available to semantic search after its embedding has been produced; a regular structured read can see the document earlier.

Combine meaning with hard conditions

Semantic similarity and exact requirements answer different parts of a search. If the result must satisfy a structured condition as well as relate to an idea, keep the hard rule in the query and state the meaning request explicitly. For tighter relevance, the reference describes a guided meaning search with a similarity threshold.

SCOOP articles WHERE status = "published" MEANING "pizza"
SCOOP articles GUIDED BY MEANING "pizza" THRESHOLD 0.8

In the first form, only published articles qualify while semantic similarity helps select related content. The guided form makes a threshold part of the request; the example uses 0.8 as a relevance cutoff. Choose semantic search when the user’s idea is more stable than the exact phrase, and use ordinary field filters when the application needs a strict rule.