Schemas

Schemaful vs Schemaless

Providing a schema to Triplit is optional, but it is recommended in order to take advantage of all the features provided by Triplit.

Limitations of schemaless mode include:

• You are limited to exclusively using storing value types that are supported by JSON: string, number, boolean, objects, null.
• If you use Typescript, you will not get type checking for your queries and results.
• Access control rules are defined in schemas, and thus are not supported in schemaless mode.

Defining your schema

A schema object defines your collections and the attributes and relationships on those collections. Schemas are defined in Javascript like so:

import { Schema as S, TriplitClient } from '@triplit/client';
 
const schema = S.Collections({
  todos: {
    schema: S.Schema({
      id: S.Id(),
      text: S.String(),
      complete: S.Boolean(),
      created_at: S.Date(),
      tags: S.Set(S.String()),
    }),
  },
  users: {
    schema: S.Schema({
      id: S.Id(),
      name: S.String(),
      address: S.Record({
        street: S.String(),
        city: S.String(),
        state: S.String(),
        zip: S.String(),
      }),
    }),
  },
});
 
const client = new TriplitClient({
  schema,
});

Passing a schema to the client constructor will override any schema currently stored in your cache. This can cause data corruption if the new schema is not compatible with existing data in the shape of the old schema. Refer to the schema management guide for more information.

id

Every collection in Triplit must define an id field in its schema. The S.Id() data type will generate a random id by default upon insertion. If you want to specify the id for each entity, you may pass it as a string in to the insert method as shown below.

// assigning the id automatically
await client.insert('todos', {
  text: 'get tortillas',
  complete: false,
  created_at: new Date(),
  tags: new Set([groceries]),
})
 
// assigning the id manually
await client.insert('todos', {
  id: 'tortillas'
  text: 'get tortillas',
  complete: false,
  created_at: new Date(),
  tags: new Set([groceries]),
})

Getting types from your schema

While the schema passed to the client constructor will be used to validate your queries and give you type hinting in any of the client's methods, you may want to extract the types from your schema to use in other parts of your application.

Entity

You can extract a simple type from your schema with the Entity type.

import { type Entity, Schema as S } from '@triplit/client';
 
const schema = S.Collections({
  todos: {
    schema: S.Schema({
      id: S.Id(),
      text: S.String(),
      complete: S.Boolean(),
      created_at: S.Date(),
      tags: S.Set(S.String()),
    }),
  },
});
 
type Todo = Entity<typeof schema, 'todos'>;
/* 
Todo will be a simple type:
{ 
  id: string, 
  text: string, 
  complete: boolean, 
  created_at: Date, 
  tags: Set<string> 
} 
*/

QueryResult

If you need more advanced types, e.g. that include an entity's relationships, you can use the QueryResult type. It allows you to generate the return type of any query, e.g. with a Select clause that narrows fields or Include clauses that add related entities.

import { type QueryResult, Schema as S } from '@triplit/client';
 
const schema = S.Collections({
  users: {
    schema: S.Schema({
      id: S.Id(),
      name: S.String(),
    }),
    relationships: {
      posts: S.RelationMany('posts', {
        where: [['authorId', '=', '$1.id']],
      }),
    },
  },
  posts: {
    schema: S.Schema({
      id: S.Id(),
      text: S.String(),
      authorId: S.String(),
    }),
  },
});
 
type UserWithPosts = QueryResult<
  typeof schema,
  { collectionName: 'users'; select: ['name']; include: { posts: true } }
>;
 
/*
type UserWithPosts = {
  name: string;
  posts: Array<{
    id: string;
    text: string;
  }>
}
*/

Reading your schema

Your schema is available in your codebase in the triplit/schema.ts file. However you may locally edit the schema, or you may not be aware of remote edits that have happened to the schema. To view the current state of the server's schema, run:

triplit schema print -l remote -f file

See CLI docs or run triplit schema print --help for more options.