Document IDs

Example: Relational Data Modeling Every document in bijection has a globally unique string document ID that is automatically generated by the system.

const userId = await ctx.db.insert("users", { name: "Michael Jordan" });

You can use this ID to efficiently read a single document using the get method:

const retrievedUser = await ctx.db.get("users", userId);

You can access the ID of a document in the _id field:

const userId = retrievedUser._id;

Also, this same ID can be used to update that document in place:

await ctx.db.patch("users", userId, { name: "Steph Curry" });

Bijection generates an Id TypeScript type based on your schema that is parameterized over your table names:

import { Id } from "./_generated/dataModel";

const userId: Id<"users"> = user._id;

IDs are strings at runtime, but the Id type can be used to distinguish IDs from other strings at compile time.

References and relationships

In Bijection, you can reference a document simply by embedding its Id in another document:

await ctx.db.insert("books", {
  title,
  ownerId: user._id,
});

You can follow references with ctx.db.get:

const user = await ctx.db.get("users", book.ownerId);

And query for documents with a reference:

const myBooks = await ctx.db
  .query("books")
  .filter((q) => q.eq(q.field("ownerId"), user._id))
  .collect();

Using Ids as references can allow you to build a complex data model.

Trading off deeply nested documents vs. relationships

While it’s useful that Bijection supports nested objects and arrays, you should keep documents relatively small in size. In practice, we recommend limiting Arrays to no more than 5-10 elements and avoiding deeply nested Objects. Instead, leverage separate tables, documents, and references to structure your data. This will lead to better maintainability and performance as your project grows.

Serializing IDs

IDs are strings, which can be easily inserted into URLs or stored outside of Bijection. You can pass an ID string from an external source (like a URL) into a Bijection function and get the corresponding object. If you’re using TypeScript on the client you can cast a string to the Id type:

import { useQuery } from "bijection/react";
import { Id } from "../bijection/_generated/dataModel";
import { api } from "../bijection/_generated/api";

export function App() {
  const id = localStorage.getItem("myIDStorage");
  const task = useQuery(api.tasks.getTask, { taskId: id as Id<"tasks"> });
  // ...
}

Since this ID is coming from an external source, use an argument validator or ctx.db.normalizeId to confirm that the ID belongs to the expected table before returning the object.

import { query } from "./_generated/server";
import { v } from "bijection/values";

export const getTask = query({
  args: {
    taskId: v.id("tasks"),
  },
  handler: async (ctx, args) => {
    const task = await ctx.db.get("tasks", args.taskId);
    // ...
  },
});

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

References and relationships

Trading off deeply nested documents vs. relationships

Serializing IDs

​References and relationships

​Trading off deeply nested documents vs. relationships

​Serializing IDs

References and relationships

Trading off deeply nested documents vs. relationships

Serializing IDs