Data Access

Field Selection

Choose which fields to return and query nested relations.

Select Specific Fields

Request only the fields you need. This reduces response size and improves performance.

Return only id, title, and status from articles:

const articles = await client.Articles.readMany({
  fields: ['id', 'title', 'status'],
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=id,title,status" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://example.monospace.io/api/blog/items/articles?fields=id,title,status',
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const { data } = await response.json();

Selecting fewer fields reduces response size and improves performance. If no fields parameter is specified, all top-level primitive fields are returned.

Include Fields from a To-One Relation

Fetch fields from a related item using dot notation in REST or a relation object in the SDK.

Return each article's id and title along with the author's name and email:

const articles = await client.Articles.readMany({
  fields: ['id', 'title', { author: ['name', 'email'] }],
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=id,title,author.name,author.email" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://example.monospace.io/api/blog/items/articles?fields=id,title,author.name,author.email',
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const { data } = await response.json();

In REST, prefix each nested field with the relation name and a dot. In the SDK, use a relation object where the key is the relation name and the value is an array of fields (shorthand syntax).

Include Fields from a To-Many Relation

Fetch fields from a collection of related items. The syntax is the same as to-one relations.

Return each author's id and name along with their articles' title and status:

const authors = await client.Authors.readMany({
  fields: ['id', 'name', { articles: ['title', 'status'] }],
});

curl -g "https://example.monospace.io/api/blog/items/authors?fields=id,name,articles.title,articles.status" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://example.monospace.io/api/blog/items/authors?fields=id,name,articles.title,articles.status',
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const { data } = await response.json();

Use Wildcards in Nested Relations

The * wildcard works inside nested relations, selecting all primitive fields at that level:

const articles = await client.Articles.readMany({
  fields: ['*', { author: ['*'] }],
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=*,author.*" \
  -H "Authorization: Bearer YOUR_API_KEY"

Select Deeply Nested Fields

Chain dot notation in REST or nest relation objects in the SDK to traverse multiple relation levels.

Return each author with their articles, each article's comments, and each comment's author name:

const authors = await client.Authors.readMany({
  fields: ['id', 'name', {
    articles: ['title', {
      comments: ['body', 'created_at', {
        author: ['name'],
      }],
    }],
  }],
});

curl -g "https://example.monospace.io/api/blog/items/authors?fields=id,name,articles.title,articles.comments.body,articles.comments.created_at,articles.comments.author.name" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  fields: 'id,name,articles.title,articles.comments.body,articles.comments.created_at,articles.comments.author.name',
});

const response = await fetch(
  `https://example.monospace.io/api/blog/items/authors?${params}`,
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const { data } = await response.json();

Deeply nested queries can be expensive. Use limit on nested relations via expanded field selection to keep response times predictable.

Filter Within Nested Relations

In REST, use the deep parameter with underscore-prefixed keys to apply filters inside nested relations. In the SDK, use expanded field selection syntax with a filter property.

Filter a To-Many Relation

Return each author with only their published articles:

const authors = await client.Authors.readMany({
  fields: ['id', 'name', {
    articles: {
      fields: ['title', 'status'],
      filter: { status: { _eq: 'published' } },
    },
  }],
});

curl -g "https://example.monospace.io/api/blog/items/authors?fields=id,name,articles.title,articles.status&deep[articles][_filter][status][_eq]=published" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://example.monospace.io/api/blog/items/authors');
url.searchParams.set('fields', 'id,name,articles.title,articles.status');
url.searchParams.set('deep[articles][_filter][status][_eq]', 'published');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

const { data } = await response.json();

Filter a To-One Relation

Return each article with author details, but only if the author is active. To-one relations only support filter — sort, limit, and offset are not available.

const articles = await client.Articles.readMany({
  fields: ['id', 'title', {
    author: {
      fields: ['name', 'email'],
      filter: { active: { _eq: true } },
    },
  }],
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=id,title,author.name,author.email&deep[author][_filter][active][_eq]=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://example.monospace.io/api/blog/items/articles');
url.searchParams.set('fields', 'id,title,author.name,author.email');
url.searchParams.set('deep[author][_filter][active][_eq]', 'true');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

const { data } = await response.json();

To-many relations support filter, sort, limit, and offset in expanded field selection. To-one relations support only filter.

Sort Within Nested Relations

Use deep with _sort in REST to order nested results. In the SDK, use the sort property in expanded field selection.

Return each author with their articles sorted by created_at descending:

const authors = await client.Authors.readMany({
  fields: ['id', 'name', {
    articles: {
      fields: ['title', 'created_at'],
      sort: [{ created_at: { direction: 'desc' } }],
    },
  }],
});

curl -g "https://example.monospace.io/api/blog/items/authors?fields=id,name,articles.title,articles.created_at&deep[articles][_sort][0][created_at][direction]=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://example.monospace.io/api/blog/items/authors');
url.searchParams.set('fields', 'id,name,articles.title,articles.created_at');
url.searchParams.set('deep[articles][_sort][0][created_at][direction]', 'desc');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

const { data } = await response.json();

Paginate Within Nested Relations

Use deep with _limit and _offset in REST to paginate nested results. In the SDK, use limit and offset in expanded field selection.

Return each author with their 5 most recent articles:

const authors = await client.Authors.readMany({
  fields: ['id', 'name', {
    articles: {
      fields: ['title', 'created_at'],
      sort: [{ created_at: { direction: 'desc' } }],
      limit: 5,
    },
  }],
});

curl -g "https://example.monospace.io/api/blog/items/authors?fields=id,name,articles.title,articles.created_at&deep[articles][_sort][0][created_at][direction]=desc&deep[articles][_limit]=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://example.monospace.io/api/blog/items/authors');
url.searchParams.set('fields', 'id,name,articles.title,articles.created_at');
url.searchParams.set('deep[articles][_sort][0][created_at][direction]', 'desc');
url.searchParams.set('deep[articles][_limit]', '5');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

const { data } = await response.json();

Skip the first 5 articles and return the next 5:

const authors = await client.Authors.readMany({
  fields: ['id', 'name', {
    articles: {
      fields: ['title'],
      limit: 5,
      offset: 5,
    },
  }],
});

curl -g "https://example.monospace.io/api/blog/items/authors?fields=id,name,articles.title&deep[articles][_limit]=5&deep[articles][_offset]=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://example.monospace.io/api/blog/items/authors');
url.searchParams.set('fields', 'id,name,articles.title');
url.searchParams.set('deep[articles][_limit]', '5');
url.searchParams.set('deep[articles][_offset]', '5');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

const { data } = await response.json();

Combine Filter, Sort, and Pagination

Apply _filter, _sort, _limit, and _offset together on a nested relation.

Return each author with their 5 most recent published articles:

const authors = await client.Authors.readMany({
  fields: ['id', 'name', {
    articles: {
      fields: ['title', 'status', 'created_at'],
      filter: { status: { _eq: 'published' } },
      sort: [{ created_at: { direction: 'desc' } }],
      limit: 5,
    },
  }],
});

curl -g "https://example.monospace.io/api/blog/items/authors?fields=id,name,articles.title,articles.status,articles.created_at&deep[articles][_filter][status][_eq]=published&deep[articles][_sort][0][created_at][direction]=desc&deep[articles][_limit]=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://example.monospace.io/api/blog/items/authors');
url.searchParams.set('fields', 'id,name,articles.title,articles.status,articles.created_at');
url.searchParams.set('deep[articles][_filter][status][_eq]', 'published');
url.searchParams.set('deep[articles][_sort][0][created_at][direction]', 'desc');
url.searchParams.set('deep[articles][_limit]', '5');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

const { data } = await response.json();

Nest Deep Multiple Levels

Apply deep parameters at different nesting levels. Each level targets a specific relation in the hierarchy.

Return each author with their published articles, and each article with only approved comments:

const authors = await client.Authors.readMany({
  fields: ['id', 'name', {
    articles: {
      fields: ['title', {
        comments: {
          fields: ['body', 'created_at'],
          filter: { approved: { _eq: true } },
        },
      }],
      filter: { status: { _eq: 'published' } },
    },
  }],
});

curl -g "https://example.monospace.io/api/blog/items/authors?fields=id,name,articles.title,articles.comments.body,articles.comments.created_at&deep[articles][_filter][status][_eq]=published&deep[articles][comments][_filter][approved][_eq]=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://example.monospace.io/api/blog/items/authors');
url.searchParams.set('fields', 'id,name,articles.title,articles.comments.body,articles.comments.created_at');
url.searchParams.set('deep[articles][_filter][status][_eq]', 'published');
url.searchParams.set('deep[articles][comments][_filter][approved][_eq]', 'true');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

const { data } = await response.json();

In REST, nested deep params use bracket notation: deep[articles][comments][_filter]. In the SDK, nest expanded objects at each level.

The SDK serializes nested expanded field selection into deep query parameters automatically. See Type System.