Link Types

A link type is an ordinary table whose rows associate two records. You declare which two fields are the link’s endpoints and how many links each record may take part in, and Bijection enforces those bounds on every transaction.

bijection/schema.ts

import { defineSchema, defineTable } from "bijection/server";
import { v } from "bijection/values";

export default defineSchema({
  customers: defineTable({ name: v.string() }),
  invoices: defineTable({
    reference: v.string(),
    amount_cents: v.int64(),
  }),
  customer_invoices: defineTable({
    customer_id: v.id("customers"),
    invoice_id: v.id("invoices"),
    note: v.optional(v.string()),
  })
    .link({ customer_id: [0, "many"], invoice_id: [0, 1] })
    .index("by_customer_invoice", ["customer_id", "invoice_id"])
    .index("by_invoice", ["invoice_id"]),
});

Each customer_invoices document is one link between a customer and an invoice. A customer can have any number of invoices, and an invoice belongs to at most one customer.

Declaring a link type

Call .link on a table definition with an object that has exactly two entries. Each key is an endpoint field and each value is its cardinality, [minimum, maximum]:

The endpoint fields must be required, top-level v.id(...) fields of the table. System tables can’t be endpoints.
The other fields of the table, such as note above, are ordinary data about the link. An ID field that isn’t named in .link isn’t an endpoint.
A table can have one .link declaration.

.link can’t be used on a view, on a table filled by an integration, or on a table with a staged validator.

Cardinality

An endpoint’s bounds count the live links that each document of the endpoint’s table takes part in. In the example, invoice_id: [0, 1] means every invoice is in zero or one customer_invoices link.

Bounds	Each record takes part in
`[0, 1]`	At most one link
`[1, 1]`	Exactly one link
`[0, "many"]`	Any number of links
`[1, "many"]`	At least one link
`[2, 5]`	Between two and five links

"many" means no upper bound. Bounds are non-negative integers with the minimum no greater than the maximum. Put a bound on the endpoint it constrains. “An invoice has at most one customer” is a bound on invoice_id, not on customer_id.

Minimums

A minimum applies to every document in the endpoint’s table, including documents that have no links yet. With invoice_id: [1, 1], an invoice can’t exist without its link, so a mutation that inserts an invoice must also insert its link:

bijection/invoices.ts

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

export const create = mutation({
  args: { customer_id: v.id("customers"), reference: v.string() },
  handler: async (ctx, args) => {
    const invoice_id = await ctx.db.insert("invoices", {
      reference: args.reference,
      amount_cents: 0n,
    });
    await ctx.db.insert("customer_invoices", {
      customer_id: args.customer_id,
      invoice_id,
    });
    return invoice_id;
  },
});

Use a minimum of 0 when records can legitimately exist before they’re associated, and track unassigned records with an ordinary query.

Creating, changing and ending links

Links are written with ordinary mutations:

Create a link with db.insert.
Change its data with db.patch or db.replace, as long as both endpoint fields keep their values.
End a link with db.delete.

Endpoints can’t be changed in place. To move an invoice to another customer, end the old link and create the new one in the same mutation:

bijection/invoices.ts

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

export const reassign = mutation({
  args: { invoice_id: v.id("invoices"), customer_id: v.id("customers") },
  handler: async (ctx, args) => {
    const current = await ctx.db
      .query("customer_invoices")
      .withIndex("by_invoice", (q) => q.eq("invoice_id", args.invoice_id))
      .unique();
    if (current !== null) {
      await ctx.db.delete("customer_invoices", current._id);
    }
    await ctx.db.insert("customer_invoices", {
      customer_id: args.customer_id,
      invoice_id: args.invoice_id,
    });
  },
});

A pair of records has at most one live link. If you end a link and later insert the same pair again, the restored link gets back its original _id and _creationTime.

Checked on the final state

Bijection checks links against the state the whole transaction leaves behind, not after each write. That’s why reassign can briefly leave the invoice without a link, and why a mutation can delete a customer together with all its links. It also covers writes that don’t touch the link table: deleting a customer that still has live links fails, even though no link was written. A transaction that breaks a link rule fails with one of these errors, and none of its writes are committed:

Error	Cause
`LinkCardinality`	A record would take part in more links than its maximum, or fewer than its minimum.
`LinkEndpointMissing`	A live link would point at a document that doesn’t exist.
`LinkEndpointImmutable`	A `patch` or `replace` changed an endpoint field.
`LinkAlreadyExists`	The same pair of records already has a live link.
`LinkValidationBudget`	Checking the transaction’s links exceeded the work Bijection allows for link checks in one transaction.

Declaring a link type, or making its bounds stricter, also checks the documents already in your tables when you deploy.

Indexes

To check links efficiently, a link type needs two indexes. Taking the endpoint fields in alphabetical order, one index begins with both fields and the other begins with the second field. Bijection adds these as by_link_pair and by_link_endpoint_2 unless you’ve declared indexes that begin with the same fields, in which case it reuses yours. Declare the indexes you query yourself, so that they have meaningful names and appear in your generated types. In the example at the top of this page, by_customer_invoice begins with both endpoints and by_invoice begins with invoice_id, so Bijection adds no indexes of its own.

Reading links

A link type is a table, so you read links with ordinary indexed queries, in either direction:

bijection/invoices.ts

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

// From a customer to its invoices.
export const forCustomer = query({
  args: { customer_id: v.id("customers") },
  handler: async (ctx, args) => {
    const links = await ctx.db
      .query("customer_invoices")
      .withIndex("by_customer_invoice", (q) =>
        q.eq("customer_id", args.customer_id),
      )
      .take(100);
    return Promise.all(
      links.map((link) => ctx.db.get("invoices", link.invoice_id)),
    );
  },
});

// From an invoice to its customer.
export const customerOf = query({
  args: { invoice_id: v.id("invoices") },
  handler: async (ctx, args) => {
    const link = await ctx.db
      .query("customer_invoices")
      .withIndex("by_invoice", (q) => q.eq("invoice_id", args.invoice_id))
      .unique();
    return link === null ? null : await ctx.db.get("customers", link.customer_id);
  },
});

.unique() is safe in customerOf because invoice_id has a maximum of 1.

Links in views

You can also traverse links inside a view. Because an invoice has at most one link, a view keyed by invoices can join it with the default cardinality: "one":

bijection/schema.ts

invoice_details: defineView({
  key: { from: "invoices", field: "_id" },
  expression: q
    .table("invoices")
    .as("invoice")
    .leftJoin(q.table("customer_invoices").as("link"), {
      left: "invoice._id",
      right: "link.invoice_id",
      index: "by_invoice",
    })
    .select({
      reference: q.field("invoice.reference"),
      customer_id: q.field("link.customer_id"),
    }),
}),

In the other direction, group the links by customer to count each customer’s invoices:

bijection/schema.ts

const invoiceCounts = q
  .table("customer_invoices")
  .groupBy(["customer_id"])
  .aggregate({ invoice_count: q.count() })
  .as("invoices");

customer_invoice_counts: defineView({
  key: { from: "customers", field: "_id" },
  expression: q
    .table("customers")
    .as("customer")
    .leftJoin(invoiceCounts, {
      left: "customer._id",
      right: "invoices.customer_id",
    })
    .select({
      name: q.field("customer.name"),
      invoice_count: q.field("invoices.invoice_count"),
    }),
}),

Reads of links, directly or through views, follow the ordinary consistency and reactivity rules: a query that follows a link updates when the link is created, ended or reassigned.

Links in the console

Links in the console schema view are in beta.

The Schema page of the console draws each declared link as edges from the link table to its two endpoint tables. Selecting a table lists the links it takes part in, the table that declares each one, and each endpoint’s bounds, written like 0..1, 1 or 0..*. For a table that declares a link, the diagram shows the declared endpoints instead of guessing edges from its ID fields.

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Declaring a link type

Cardinality

Minimums

Creating, changing and ending links

Checked on the final state

Indexes

Reading links

Links in views

Links in the console

​Declaring a link type

​Cardinality

​Minimums

​Creating, changing and ending links

​Checked on the final state

​Indexes

​Reading links

​Links in views

​Links in the console

Declaring a link type

Cardinality

Minimums

Creating, changing and ending links

Checked on the final state

Indexes

Reading links

Links in views

Links in the console