Skip to main content
The DatabaseReader service is used to read documents from the database.

Retrieve a single document

By ID

By index

Single field

Multiple fields

Validate document IDs

Use DocumentIds when you receive a string, such as a URL parameter, and need a table-typed ID before reading a document. Import the schema-typed service from confect/_generated/services. Confect provides it in queries, mutations, and middleware that covers only those function types, not in actions or HTTP handlers. An action or HTTP handler can call a query to perform the check. Both methods return an Effect containing an Option. Table arguments are limited to your schema’s table names plus _storage and _scheduled_functions.

Parse before reading

Use parse to prove that an untrusted string is a valid ID for the expected table. On success, you receive the table-typed ID without a cast. parse returns Some(id) when the string is a valid ID for the specified table. Invalid strings and IDs for a different table return None.
Parsing does not prove that a document exists. The separate get can still fail with GetByIdFailure, for example after deletion. None of the DocumentIds methods establishes authorization or proves that an ID originated in your deployment. Check access before returning a document to the caller.

Identify an unknown table

identify tries the tables in your schema and both system tables using native runtime ID lookups, not document scans. It validates the input in the same way as parse. An invalid string or an ID that matches none of the known tables returns None. The result keeps each table name paired with its ID type. Narrow table to use id with a specific table:
Identification is scoped to the current runtime and schema. It is not a frontend-only decoder or a way to discover tables across Convex components. Invalid or mismatching IDs return None. Unexpected native runtime failures remain Effect defects; the service does not disguise them as invalid input. This failure behavior applies to both methods.

Retrieve multiple documents

Indexes

Every query must specify either a standard index or a search index.

Standard indexes

Standard indexes are what you’ll use most of the time. There are two default standard indexes, which exist for every table: by_creation_time and by_id. The rest are defined in your schema. Standard indexes determine both the sort order of the results and which fields may be filtered on. Fields must be filtered in the order they are defined in the index. Order is ascending by default, but can be specified in the final argument to the index method.
Users sorted by name and age, ascending
Users sorted by name and age, descending
Users sorted by name and age, where name equals "John Doe", ascending
Users sorted by name and age, where name equals "John Doe", and age equals 21, descending

Search indexes

Search indexes are used for full-text search, and are defined in your schema. The results are always sorted by relevance, descending.

Methods

The following methods are available for queries using both database indexes and search indexes.

Collect

Collect all documents matching the query.

First

Retrieve the first document matching the query.

Take

Take the first n documents matching the query.

Paginate

Retrieve a page of documents matching the query. Expects a PaginationOptions object, including Convex’s optional pagination protocol fields. A paginated query handler typically forwards its decoded paginationOpts argument unchanged.

Stream

Get a Stream of documents matching the query.
To merge, join, or paginate several queries together, use a query stream insteadβ€”reader.table("notes").stream("by_creation_time")β€”which stays paginable after composition.

Accessing the current time

Reading real time inside a query handler affects how aggressively Convex caches the result. See Determinism for how Confect keeps queries cacheable by default and how to opt in to real time via Effect’s Clock service.