Onyx Database Relationships

Fetch Policy Tutorial

Fetch policies determine how the Onyx open source ORM hydrates related entities. Onyx Cloud replaces fetch policies with resolver-backed relationships that you hydrate explicitly. Use the toggle to switch between runtimes.

Choose Onyx Open Source to explore FetchPolicy usage or Onyx Cloud to see how resolvers achieve the same control.

Onyx Open Source Tutorial

Switch to Onyx Open Source to explore FetchPolicy annotations and ORM examples.

Onyx Cloud Tutorial

Instead of fetch policies, attach resolvers to attributes and choose when to hydrate related data per query or findById call.

Resolvers execute server-side with an authenticated client. Publish schema changes after editing resolver logic so your scripts can request the new data.

Attach resolver logic in the schema editor

Create resolver scripts for the relationships you want to hydrate. Use the query builder helpers and reference the current record via this.

1// Runs inside the Onyx Cloud schema editor for Series.seasons
2const seasons = await db
3  .from('Season')
4  .where(eq('seriesId', this.id))
5  .resolve('episodes')
6  .list();
7
8return seasons;

Publish the schema after editing resolvers so runtime scripts use the latest logic.

Resolve relationships when querying

Call resolve() with resolver names—or dot notation for nested data—to hydrate related entities only when required.

1// Resolve nested relationships when querying
2const seriesWithEpisodes = await db
3  .from('Series')
4  .resolve('seasons', 'seasons.episodes')
5  .where(eq('seriesId', 'SOPRANOS'))
6  .firstOrNull();
7
8db.results = seriesWithEpisodes;

Combine resolve with selectFields to limit payload size and keep responses lean.

Hydrate resolvers with findById

Pass a resolvers array to findById to populate specific relationships on a single record.

1// Ask findById to hydrate resolver-backed relationships
2const sopranos = await db.findById('Series', 'SOPRANOS', {
3  resolvers: ['seasons', 'seasons.episodes']
4});
5
6db.results = sopranos;

List resolver names in depth order (for example, ['seasons', 'seasons.episodes']) to traverse the graph.

Cloud Tips & Troubleshooting

Always return await the final query from resolver scripts.
Use dot notation in resolve calls to load nested relationships precisely.
If a resolver returns no data, verify identifiers and republish the schema.
Trim resolver lists to reduce payload size and improve performance.