Database-side relation loading
Use join when the database should assemble nested relation data and return it through one query.
Prisma · Pipe
relationLoadStrategy
relationLoadStrategy selects how Prisma loads related records for a relation query. Use join for a database-level single-query strategy or query for multiple queries merged in application code.
How it works
Add the relationJoins preview feature, regenerate Prisma Client, then set relationLoadStrategy at the top level of a query that uses include or relation select. Choose join for database-side aggregation in one query, or query for multiple table queries merged by the application.
Syntax
relationLoadStrategy: "join" | "query"Parameters
| Name | Type | Description |
|---|---|---|
relationLoadStrategy | "join" | "query" | Controls relation loading; accepted values are join or query. |
Returns
The selected relation query result; the loading strategy changes execution rather than the returned data shape.
Key points
- The option provides two choices: join and query.
- join is the default and delegates relation assembly to the database using database-specific SQL techniques.
- query retrieves each table separately and combines the related results in application code.
- Use the option only on the query root when the query includes relations through include or select.
- Supported database providers are PostgreSQL, CockroachDB, and MySQL.
- Regenerate the client after changing the generator configuration.
Common mistakes
- The option is still Preview, so enable relationJoins in the generator and run prisma generate again.
- Do not place the option inside nested relation selections; the top-level choice applies to every nested subquery.
Example: Choose a relation load strategy
generator client {
provider = "prisma-client-js"
previewFeatures = ["relationJoins"]
}
const users = await prisma.user.findMany({
relationLoadStrategy: "join",
include: { posts: true },
});Loads users and their posts with one database query using the join strategy.
When to use it
Application-side relation loading
Use query when database-server resource usage should be reduced or profiling favors application-level merging.
Per-query performance tuning
Choose the strategy separately for each root query that loads relations.
Interview questions
QWhat does relationLoadStrategy control, and what are its two values?
relationLoadStrategy controls how Prisma loads related records. join is the default and uses a database-level join or correlated subqueries to return the complete result in one database query; query sends separate table queries and merges the results in application code.
Follow-up: When might query be preferable? Use it when reducing database-server resource usage matters or profiling shows that application-level merging performs better.
QWhere can relationLoadStrategy be specified?
The option belongs at the top level of a query that supports include or relation selection. A top-level setting governs all nested subqueries, so nested relations cannot independently choose another strategy.
Follow-up: How would you configure the feature? Add relationJoins to the generator's previewFeatures and regenerate Prisma Client.
QWhich databases support the feature, and how does join work?
The documented relationJoins feature is available for PostgreSQL, CockroachDB, and MySQL. With join, PostgreSQL uses a LATERAL JOIN, MySQL uses correlated subqueries, and the database performs JSON aggregation.
Follow-up: What is the operational distinction of query? It performs multiple queries, one per table, then joins the records in the application layer.
Related
includeselectrelationJoinsprisma generateRelation queries