Published Tables

A published table is a table in your schema whose rows are written by publication instead of by your mutations. It is stored, indexed and queried exactly like an ordinary table. The difference is ownership: its rows change only when Bijection switches it to a new publication. Declare one with definePublished in your schema.ts:

bijection/schema.ts

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

export const order = v.object({
  order_number: v.string(),
  customer: v.string(),
  status: v.string(),
  amount: v.int64(),
});

export const openOrders = definePublished({
  producer: "orderSummary",
  member: "openOrders",
  row: { order_number: v.string(), customer: v.string(), amount: v.int64() },
}).index("by_customer", ["customer"]);

export const customerTotals = definePublished({
  producer: "orderSummary",
  member: "customerTotals",
  row: { customer: v.string(), open_count: v.int64(), open_amount: v.int64() },
}).index("by_customer", ["customer"]);

export default defineSchema({
  orders: defineTable(order).index("by_customer", ["customer"]),
  open_orders: openOrders,
  customer_totals: customerTotals,
});

The published tables are exported so that the pipeline that fills them can refer to the same declarations.

Producer and member

definePublished takes three fields:

producer names the pipeline that publishes this table. Every table with the same producer belongs to one group, and the whole group is published together.
member names this table’s place in the producer’s output. The pipeline’s output with the same name writes this table.
row is the document type, either an object of validators or a v.object validator.

Producer and member names must start with a letter, _ or $, contain only letters, digits, _ and $, and be at most 128 characters long. Two tables in one schema cannot claim the same producer and member; deploying such a schema is refused. Bijection adds _id and _creationTime to every published row, as it does for any table. See system fields.

Indexes and access rules

Declare indexes with .index(...) exactly as on an ordinary table, and read through them with withIndex. See indexes. You can also attach a read rule with .access(...). See access rules. Everything that would give the rows a second writer or a second derivation is refused when the schema is evaluated:

Declaration	On a published table
`.index(name, fields)`	Allowed
`.access(...)`	Allowed
Staged index (`staged: true`)	Refused
`.searchIndex(...)`, `.vectorIndex(...)`	Refused
`.staged(...)`	Refused
`.source(...)`, `.govern(...)`, `.link(...)`	Refused

A refused declaration throws an error such as:

A published relation cannot declare a search index: its rows change only through its admitted publication.

Published tables are read-only

The generated data model marks a published table as not writable, so a write is a TypeScript error:

bijection/orders.ts

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

export const closeOrder = mutation({
  args: { id: v.id("open_orders") },
  handler: async (ctx, args) => {
    // Type error: open_orders is not a writable table.
    await ctx.db.delete("open_orders", args.id);
  },
});

The same rule holds at runtime. An insert, patch, replace or delete of a published table fails with ReadOnlyPublished, and a data import cannot write one either. To change what a published table holds, change its inputs or its pipeline and let it publish again.

Adding and removing published tables

Deploying a schema that turns a table into a published table requires that table to be empty; a table that already holds rows is refused. Once a table is published, a later deployment cannot silently drop definePublished from it or move it to another producer. Changing a group’s producer, its members or a member’s row type requires an explicit ownership transition.

Before the first publication

A published table is unavailable until its first publication succeeds. A query that reads it before then fails with PublishedUnavailable. The failed read stays a dependency of the query, so a subscribed client receives the result as soon as the table becomes available. See Reading publications.

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Producer and member

Indexes and access rules

Published tables are read-only

Adding and removing published tables

Before the first publication

​Producer and member

​Indexes and access rules

​Published tables are read-only

​Adding and removing published tables

​Before the first publication

Producer and member

Indexes and access rules

Published tables are read-only

Adding and removing published tables

Before the first publication