Tutorial: Building with CleaveDB

Structured Retrieval

SCOOP retrieves documents from a bucket by following the shape of the question: name the data set, optionally state which records qualify, then request the result you want. It is declarative, like a well-written instruction to a librarian: describe the shelf and the records you need, and CleaveDB plans how to return them.

Read a bucket

A bucket is the collection named in the query. SCOOP EVERYTHING FROM makes a full-bucket read explicit, while SCOOP followed by the bucket is the concise form. Begin broadly when you truly need the collection; add conditions, a limit, or a field projection when the caller needs a smaller answer.

SCOOP EVERYTHING FROM users
SCOOP users

Both statements request the users collection. The explicit form is helpful in examples and longer query expressions because it spells out what is being retrieved. The concise form is easy to read in day-to-day queries. Either can be extended with the filters and result-shaping options in the lessons that follow.

Address one known document

When the application already knows a document ID, supply it with the bucket. For example, a profile route may already have Jane’s ID, so it can ask for users and "jane" directly. The bucket and ID together form the document address; an ID by itself is interpreted within its bucket.

SCOOP users "jane"
SCOOP products "wireless-mouse"

Use a direct ID lookup for a profile, order detail, or any application route that already carries the key. If all you know is a field value, use WHERE or WHOSE instead; if you need several documents, query the bucket and let conditions narrow the result.

What happens behind the query

CleaveQL turns the statement into a structured request. When a query uses an indexed field in WHERE or WHOSE, the planner can use that index to narrow the search. Without an applicable index, it evaluates the bucket’s documents. The requested filters are applied before ordering and projection, so the final response can be focused on the records and fields the application asked for.

This is why the query should say what the application needs: a selective condition can avoid unnecessary document reads, while YIELD can keep the returned payload small. SCOOP describes the answer, and CleaveDB chooses the available path for producing it.