Optional lookup
Retrieve one matching entity when absence is acceptable.
Prisma · Module
findFirst
findFirst returns the first record matching a Prisma Client query. It returns null when nothing matches and supports the same query options as findMany.
How it works
Call findFirst on a generated Prisma model delegate with optional filtering and query options. Prisma returns the first matching record, or null when nothing matches; use ordering to define which record is first, and use a negative take value to reverse the ordered list.
Syntax
prisma.<model>.findFirst(<args>)Parameters
| Name | Type | Description |
|---|---|---|
args | ModelFindFirstArgs | Query arguments, including filtering, ordering, selection, relation loading, pagination, and other options accepted by findMany. |
Returns
The first matching model record, or null if no record matches.
Key points
- It selects one record from the records matching the supplied criteria.
- Its available query options follow the findMany query API.
- A where clause can restrict the search to records with a particular field value.
- Ordering can be reversed with a negative take value when selecting the first matching post.
Common mistakes
- The method returns null when no record matches; choose findFirstOrThrow when absence should raise an error.
- A negative take reverses the list order, so use it deliberately when selecting the first result.
Example: Find the first matching record
const user = await prisma.user.findFirst({
where: { name: "Alice" },
});Looks up the first user whose name is Alice; the result is null when no matching record exists.
When to use it
Ordered selection
Choose a record according to an explicit sort order.
Filtered record retrieval
Inspect one record using filters and standard Prisma query options.
Interview questions
QWhat does findFirst do when no record matches?
findFirst returns the first record matching the supplied criteria. If no record matches, it returns null rather than throwing.
Follow-up: How can the selected record be made deterministic? Add orderBy to define the ordering before the first record is chosen.
QHow does findFirst relate to findMany?
findFirst accepts the same query options as findMany because it calls findMany internally. This includes filtering, ordering, and selection-related options supported by the model delegate.
Follow-up: What alternative should be used when absence is exceptional? Use findFirstOrThrow, which throws a PrismaClientKnownRequestError when no record is found.
QHow do ordering and take affect findFirst?
Use orderBy to control which matching record is considered first. The query can also use a negative take value to reverse the ordered list.
Follow-up: What should be checked when using negative take? Verify that reversing the ordering matches the intended business rule, because it changes which matching record is returned.
Related
findManyfindFirstOrThroworderBytake