Interface: GenericDatabaseReader<DataModel>

server.GenericDatabaseReader

An interface to read from the database within Convex query functions.

Available as ctx.db in queries (read-only) and mutations (read-write). You should generally use the DatabaseReader type from "./_generated/server".

The two entry points are:

• get, which fetches a single document by its GenericId.
• query, which starts building a query.

Example

// Fetch a single document by ID:
const user = await ctx.db.get("users", userId);

// Query documents with an index:
const messages = await ctx.db
  .query("messages")
  .withIndex("by_channel", (q) => q.eq("channelId", channelId))
  .order("desc")
  .take(50);

Best practice: Use .withIndex() instead of .filter() for efficient queries. Define indexes in your schema for fields you query frequently.

See

https://docs.convex.dev/database/reading-data

Type parameters

Name	Type
DataModel	extends GenericDataModel

Hierarchy

• BaseDatabaseReader<DataModel>

  ↳ GenericDatabaseReader

  ↳↳ GenericDatabaseWriter

Properties

system

• system: BaseDatabaseReader<SystemDataModel>

An interface to read from the system tables within Convex query functions.

System tables include _storage (file metadata) and _scheduled_functions (scheduled function state). Use ctx.db.system.get() and ctx.db.system.query() just like regular tables.

Example

// Get file metadata from the _storage system table:
const metadata = await ctx.db.system.get("_storage", storageId);
// metadata has: _id, _creationTime, contentType, sha256, size

Defined in

server/database.ts:152

Methods

get

▸ get<TableName>(table, id): Promise<null | DocumentByName<DataModel, TableName>>

Fetch a single document from the database by its GenericId.

Type parameters

Name	Type
TableName	extends string

Parameters

Name	Type	Description
table	TableName	The name of the table to fetch the document from.
id	GenericId<NonUnion<TableName>>	The GenericId of the document to fetch from the database.

Returns

Promise<null | DocumentByName<DataModel, TableName>>

• The GenericDocument of the document at the given GenericId, or null if it no longer exists.

Inherited from

BaseDatabaseReader.get

Defined in

server/database.ts:23

▸ get<TableName>(id): Promise<null | DocumentByName<DataModel, TableName>>

Fetch a single document from the database by its GenericId.

Type parameters

Name	Type
TableName	extends string

Parameters

Name	Type	Description
id	GenericId<TableName>	The GenericId of the document to fetch from the database.

Returns

Promise<null | DocumentByName<DataModel, TableName>>

• The GenericDocument of the document at the given GenericId, or null if it no longer exists.

Inherited from

BaseDatabaseReader.get

Defined in

server/database.ts:34

---

query

▸ query<TableName>(tableName): QueryInitializer<NamedTableInfo<DataModel, TableName>>

Begin a query for the given table name.

Queries don't execute immediately, so calling this method and extending its query are free until the results are actually used.

Type parameters

Name	Type
TableName	extends string

Parameters

Name	Type	Description
tableName	TableName	The name of the table to query.

Returns

QueryInitializer<NamedTableInfo<DataModel, TableName>>

• A QueryInitializer object to start building a query.

Inherited from

BaseDatabaseReader.query

Defined in

server/database.ts:47

---

normalizeId

▸ normalizeId<TableName>(tableName, id): null | GenericId<TableName>

Returns the string ID format for the ID in a given table, or null if the ID is from a different table or is not a valid ID.

This accepts the string ID format as well as the .toString() representation of the legacy class-based ID format.

This does not guarantee that the ID exists (i.e. db.get(id) may return null).

Type parameters

Name	Type
TableName	extends string

Parameters

Name	Type	Description
tableName	TableName	The name of the table.
id	string	The ID string.

Returns

null | GenericId<TableName>

Inherited from

BaseDatabaseReader.normalizeId

Defined in

server/database.ts:63