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
UseDocumentIds 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
Useparse 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.
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:
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 firstn documents matching the query.
Paginate
Retrieve a page of documents matching the query. Expects aPaginationOptions object, including Convexβs optional pagination protocol fields. A paginated query handler typically forwards its decoded paginationOpts argument unchanged.
Stream
Get aStream of documents matching the query.
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βsClock service.