Include

If you have defined a relation in your schema using RelationById, RelationOne, or RelationMany, you can include those related entities in a query.

For example, the following schema defines a relation between users and messages

const schema = S.Collections({
  users: {
    schema: S.Schema({
      id: S.Id(),
      name: S.Id(),
      email: S.String(),
    }),
  },
  messages: {
    schema: S.Schema({
      id: S.Id(),
      text: S.String(),
      sender_id: S.String(),
    }),
    relationships: {
      sender: S.RelationById('users', '$sender_id'),
    },
  },
});

By default, a query on messages will not include the sender as an attribute. To include the sender, use the Include method in the query builder.

const query = client.query('messages').Include('sender');
 
/*
{
  id: '1',
  text: 'hello world!',
  sender_id: 'bob',
  sender: { id: 'bob', name: 'Bob Jones', email: 'bob@triplit.dev' },
};
*/

Including multiple relations

If a collection has multiple relations, you can select them by chaining multiple Include calls.

const query = client.query('messages').Include('sender').Include('receiver');

Aliasing and extending relations

You can extend and alias relations with the Include method. Given a schema with a relation from directors to films:

const schema = S.Collections({
  films: {
    schema: S.Schema({
      id: S.Id(),
      title: S.Id(),
      rating: S.Number(),
      directorId: S.String(),
    }),
  },
  directors: {
    schema: S.Schema({
      id: S.Id(),
      name: S.String(),
    }),
    relationships: {
      allFilms: S.RelationMany('films', {
        where: [['directorId', '=', '$1.id']],
      }),
    },
  },
});

You can write an adhoc query that narrows down a director's films to just their top 3, building off the existing allFilms relation.

const query = client.query('directors').Include('bestFilms', (rel) =>
  // TODO: confirm capitalization of `rel`
  rel('allFilms').Order('rating', 'DESC').Limit(3)
);
const result = await client.fetch(query);
 
// And the result will be fully typed
// {
//   id: string;
//   name: string;
//   bestFilms: { id: string; title: string; rating: number; directorId: string }[];
// }

This is also useful for querying nested data. For example:

const query = client
  .query('directors')
  .Include('allFilms', (rel) => rel('allFilms').Include('actors'));
 
// {
//   id: string;
//   name: string;
//   allFilms: { id: string; title: string; rating: number; directorId: string, actors: { ... }[] }[];
// }

The extending query can use any valid query builder method, such as Order, Limit, Where, etc.

`Select``Where`