Single-record lookup
Retrieve one entity selected by a condition, such as a user identified by an ID.
Drizzle ORM · Module
.findFirst
findFirst() retrieves the first matching record through Drizzle ORM’s relational query API. It limits the query to one result and can load related data.
How it works
Use the relational query API on a table available through db.query. Calling findFirst builds a query constrained to one result; optional configuration can filter the table and include related records. The result is inferred from the selected table and can be absent when no row matches.
Syntax
await db.query.<table>.findFirst(config?)Parameters
| Name | Type | Description |
|---|---|---|
config | FindFirstConfig | Optional relational-query configuration, including filtering and relation-loading options. |
Returns
A promise resolving to the first matching table record, with an inferred object shape; no matching record may be returned.
Key points
- The relational query API offers
findFirstalongsidefindManyfor single-record and multi-record access. - The generated SQL is constrained to one result, making the method suitable for first-match retrieval.
- The basic invocation is asynchronous and starts from
db.queryfollowed by the table name. - A configuration object can be passed when querying a table, rather than calling the method only with no arguments.
- The
withoption lets a first matching record be loaded together with related records such as comments.
Common mistakes
- The method limits the query to one row; it does not retrieve all matching records.
Example: Find the first matching row
const user = await db.query.users.findFirst({
where: (users, { eq }) => eq(users.id, 1),
});Fetches at most one user matching the condition; the relational query API returns the first matching record or no record.
When to use it
Load related data
Fetch one parent record and selected related rows in one relational query.
Type-safe access
Use schema-derived result types when reading one record from a table.
Interview questions
QWhat does findFirst() do?
findFirst() is the relational query API method for retrieving one record from a table. It adds limit 1 to the generated query, and its result is typed from the table schema.
Follow-up: How would you load related data at the same time? Pass a with configuration, such as { with: { comments: true } }.
QWhat is the standard call shape?
Use db.query.<table>.findFirst(), for example db.query.users.findFirst(). You can pass a configuration object to add conditions or relations while retaining inferred result types.
Follow-up: How can you restrict the result to a particular row? Supply a where callback using a comparison helper such as eq.
QWhen would you choose findFirst() over findMany()?
The method is useful when the application needs a single matching entity rather than a collection. The documentation demonstrates fetching a user and separately fetching a post together with its comments.
Follow-up: When should a collection method be preferred? Use findMany() when the application needs multiple matching records.
Related
findManywithdb.queryrelations