Build with BQL

{
  "kinds": {
    "User": {
      "dataFields": {
        "name": { "valueType": "TEXT" },
        "email": { "valueType": "EMAIL", "unique": true },
        "age": { "valueType": "INTEGER" }
      }
    },
    "Article": {
      "dataFields": {
        "title": { "valueType": "TEXT", "required": true, "fts": true },
        "body": { "valueType": "TEXT", "fts": true },
        "status": { "valueType": "TEXT" }
      }
    }
  }
}

// multipart body has parts: "mutation" (JSON) + named file parts
{
  "$setKinds": ["Document"],
  "title": "Annual report",
  "attachment": { "#file": "file_0" }
}
// → server stores blob, returns FileValue with signed url

{
  "hooks": {
    // Post survives when its author User is deleted; the broken arc
    // arrives as an unlink entry in $delta.arcs on the survivor's update.
    "Post.markUnlinkSeen": {
      "type": "unit.transform",
      "target": {
        "ops": ["update"],
        "$kinds": { "$any": ["Post"] }
      },
      "$js": "var arcs = ($delta && $delta.arcs) || []; return { unlinkSeen: arcs.some(a => a.$op === 'unlink') };"
    }
  }
}

// Direct relation, no tunnel.
// One valid ownership choice: Book owns the roleField, Author keeps the reverse linkField.
{
  "kinds": {
    "Author": {
      "dataFields": {
        "name": { "valueType": "TEXT" },
        "slug": { "valueType": "TEXT", "unique": true }
      },
      "linkFields": {
        "books": {
          "relation": "Book",
          "plays": "author"
        }
      }
    },
    "Book": {
      "dataFields": {
        "title": { "valueType": "TEXT" },
        "publishedYear": { "valueType": "INTEGER" }
      },
      "roleFields": {
        "author": {
          "playedBy": ["Author"],
          "cardinality": "ONE",
          "required": true
        }
      }
    }
  }
}

{
  "kinds": {
    "Company": {
      "dataFields": {
        "name": { "valueType": "TEXT" }
      },
      "linkFields": {
        "memberships": {
          "relation": "Membership",
          "plays": "company",
          "target": "relation"
        },
        "employees": {
          "relation": "Membership",
          "plays": "company",
          "target": "role",
          "targetRoles": ["employee"]
        }
      }
    },
    "Employee": {
      "dataFields": {
        "name": { "valueType": "TEXT" },
        "email": { "valueType": "EMAIL" }
      },
      "linkFields": {
        "memberships": {
          "relation": "Membership",
          "plays": "employee",
          "target": "relation"
        },
        "companies": {
          "relation": "Membership",
          "plays": "employee",
          "target": "role",
          "targetRoles": ["company"]
        }
      }
    },
    "Membership": {
      "dataFields": {
        "title": { "valueType": "TEXT" },
        "startDate": { "valueType": "DATE" }
      },
      "roleFields": {
        "company": { "playedBy": ["Company"], "cardinality": "ONE" },
        "employee": { "playedBy": ["Employee"], "cardinality": "ONE" }
      }
    }
  }
}

{
  "$kinds": "Company",
  "$fields": [
    "name",
    {
      "$expand": "memberships",
      "$fields": [
        "title",
        "startDate",
        { "$expand": "employee", "$fields": ["name", "email"] }
      ]
    }
  ]
}

{
  "kinds": {
    "Employee": {
      "dataFields": { "name": { "valueType": "TEXT" } }
    },
    "Agency": {
      "dataFields": { "name": { "valueType": "TEXT" } }
    },
    "Project": {
      "dataFields": { "name": { "valueType": "TEXT" } },
      "linkFields": {
        "assignments": {
          "relation": "Assignment",
          "plays": "project",
          "target": "relation"
        },
        "assignees": {
          "relation": "Assignment",
          "plays": "project",
          "target": "role",
          "targetRoles": ["assignee"]
        }
      }
    },
    "Assignment": {
      "roleFields": {
        "project": { "playedBy": ["Project"], "cardinality": "ONE" },
        "assignee": { "playedBy": ["Employee", "Agency"], "cardinality": "ONE" }
      }
    }
  }
}

// Nested create: $setKinds disambiguates the polymorphic assignee
{
  "$setKinds": ["Assignment"],
  "project": "project_123",
  "assignee": { "$setKinds": ["Agency"], "name": "Acme Staffing" }
}

{
  "kinds": {
    "Friendship": {
      "roleFields": {
        "friends": { "playedBy": ["User"], "cardinality": "MANY", "symmetric": true }
      }
    },
    "Reference": {
      "roleFields": {
        "from": { "playedBy": ["Document"], "allowSelfRelation": true },
        "to":   { "playedBy": ["Document"], "allowSelfRelation": true }
      }
    }
  }
}

// POST /definitions/import
{
  // Required: this build's definitions wire fingerprint.
  // Read it from GET /health ("$definitionContract"); the JS SDK stamps it for you.
  "$definitionContract": "<value from GET /health>",
  "schema": {
    "kinds": {
      "User": {
        "dataFields": {
          "name": { "valueType": "TEXT" },
          "email": { "valueType": "EMAIL", "unique": true }
        },
        "linkFields": {
          "posts": { "relation": "Post", "plays": "author" }
        }
      },
      "Post": {
        "dataFields": { "title": { "valueType": "TEXT" } },
        "roleFields": {
          "author": { "playedBy": ["User"], "cardinality": "ONE" }
        }
      }
    }
  },
  "opts": { "defaultSubspace": "main" }
}

// POST /definitions/export
{ "opts": { "defaultSubspace": "main" } }

// → { "data": { "$bzv": "0.34.0", "$definitionContract": "…", "schema": { "kinds": { ... } }, "portals": { ... } } }
// The exported "$definitionContract" round-trips straight back into /definitions/import.
// For schema-only export: POST /schema/export with the same opts shape.
// For per-field type metadata: GET /docs/fields/content-types.

// Preview bundle contents
GET /namespace/bundle/plan

// Download a .bzg bundle (writes pause only while the artifact is staged)
POST /namespace/bundle/export
{
  "include": { "definitions": true, "units": true, "files": false },
  "subspaces": ["main"]
}

// Upload the bundle; import completes asynchronously
POST /namespace/bundle/import?definitions=true&units=true&files=false
Content-Type: multipart/form-data
[email protected]

// → 202 { "importId": "01...", "resumed": false }
// Poll GET /admin/import-status until terminal.importId matches.

{
  "schema": {
    "kinds": {
      "Member": {
        "userKind": true,
        "idField": "email",
        "emailField": "email",
        "dataFields": {
          "email": { "valueType": "EMAIL", "unique": true },
          "name": { "valueType": "TEXT" }
        }
      },
      "Admin": {
        "extends": "Member",
        "userKind": true
      },
      "Note": {
        "dataFields": {
          "title": { "valueType": "TEXT" },
          "privateText": { "valueType": "TEXT" }
        },
        "roleFields": {
          "owner": { "playedBy": ["Member"], "cardinality": "ONE" }
        },
        "permissions": {
          "query": "owner",
          "create": { "$me.$kinds": "Member" },
          "fields": {
            "privateText": { "query": { "$me.$kinds": "Admin" } }
          }
        }
      }
    }
  },
  "env": {
    "domains": {
      "notes-auth": {
        "secrets": ["password_pepper", "resend_api_key"]
      }
    }
  },
  "portals": {
    "apps": {
      "notes": {
				"slug": "notes",
        "env": ["notes-auth"],
        "access": { "$kinds": ["Member"] },
        "auth": {
          "providers": {
            "emailPassword": {
              "enabled": true,
              "pepper": { "$secret": "env.notes-auth.password_pepper" }
            }
          },
          "delivery": {
            "provider": "resend",
            "apiKey": { "$secret": "env.notes-auth.resend_api_key" },
            "fromAddress": "Notes <[email protected]>"
          },
          "signup": {
            "mode": "open",
            "blueprint": {
              "$setKinds": ["Member"],
              "$authAnchorKind": "Member",
              "email": { "$auth": "email" },
              "name": { "$input": "name" }
            }
          }
        },
        "pages": {
          "/": {
            "tsxSource": "export default function NotesPage() { return null }"
          }
        }
      }
    }
  }
}

// POST /definitions/query: all kinds
{ "query": { "$type": "kind" }, "opts": { "defaultSubspace": "main" } }

// Query a specific kind by $did
{ "query": { "$type": "kind", "$did": "K:abc123" } }

// Query fields of a kind
{ "query": { "$type": "dataField", "$filter": { "ownerKind": "User" } } }

// POST /definitions/mutate
{
  "mutation": [
    {
      "$op": "create",
      "$type": "kind",
      "name": "Product",
      "dataFields": {
        "title": { "valueType": "TEXT" },
        "price": { "valueType": "INTEGER" }
      }
    },
    {
      "$op": "create",
      "$type": "roleField",
      "ownerKind": "Order",
      "name": "customer",
      "playedBy": ["User"],
      "cardinality": "ONE"
    },
    {
      "$op": "create",
      "$type": "linkField",
      "ownerKind": "User",
      "name": "orders",
      "relation": "Order",
      "plays": "customer",
      "target": "relation"
    }
  ],
  "opts": { "defaultSubspace": "main" }
}

{
  "$kinds": "User",
  "$fields": ["name", "email", "age"],
  "$sort": [{ "$by": "age", "$order": "desc" }],
  "$limit": 10,
  "$offset": 20
}

// First page
{ "$kinds": "Task", "$limit": 50 }

// → { "data": [ ... ], "meta": { "count": 50, "$nextCursor": "eyJ..." } }

// Next page: replay meta.$nextCursor verbatim as $cursor
{ "$kinds": "Task", "$limit": 50, "$cursor": "<token from meta.$nextCursor>" }

// No meta.$nextCursor in the response → last page

{
  "$kinds": "User",
  "$filter": {
    "status": "active",
    "age": { "$gte": 18 }
  },
  "$fields": ["name", "email"]
}

{
  "$kinds": "User",
  "$filter": { "name": { "$fuzzy": "alcie", "$distance": 1 } },
  "$fields": ["name"],
  "$limit": 5
}

{
  "$kinds": "Article",
  "$search": "rust programming",
  "$fields": ["title", "$score"],
  "$limit": 10
}

// All fields
{ "$kinds": "User", "$fields": "*" }

// Specific fields only
{ "$kinds": "User", "$fields": ["name", "email"] }

// All except some
{ "$kinds": "User", "$fields": "*", "$excludedFields": ["password"] }

// Arc fields without $expand → raw IDs
{ "$kinds": "Post", "$fields": ["title", "author"] }
// → { "title": "Hello", "author": "user_abc123" }

{
  "$kinds": ["Bot", "User"],
  "$fields": [
    { "$fetch": "name", "$definedOn": "User", "$as": "userName" },
    { "$fetch": "name", "$definedOn": "Bot", "$as": "botName" }
  ]
}

{
  "$kinds": "Post",
  "$fields": [
    "title",
    { "$expand": "author", "$fields": ["name", "email"] },
    { "$expand": "comments", "$fields": ["text"] }
  ]
}

{
  "$kinds": "User",
  "$fields": [
    "name",
    {
      "$expand": "posts",
      "$filter": { "status": "published" },
      "$sort": [{ "$by": "title", "$order": "asc" }],
      "$limit": 5,
      "$fields": ["title", "status"]
    }
  ]
}

{
  "$kinds": "User",
  "$fields": [
    { "$expand": "posts", "$as": "articles", "$fields": ["title"] }
  ]
}

{
  "$kinds": "Team",
  "$id": "team1",
  "$fields": [
    "name",
    { "$expandArc": "members", "$fields": ["name"] }
  ]
}

// Response wraps each member in an arc envelope:
// { "name": "Devs", "members": [
//   { "$arcCreatedAt": "2026-03-15T10:30:00Z", "$unit": { "$id": "...", "name": "Alice" } },
//   { "$arcCreatedAt": "2026-03-16T09:00:00Z", "$unit": { "$id": "...", "name": "Bob" } }
// ]}

{
  "$kinds": "Team",
  "$id": "t1",
  "$fields": [
    {
      "$expandArc": "members",
      "$filter": { "$arcCreatedAt": { "$gte": { "#datetime": "2026-01-01T00:00:00.000Z" } } },
      "$sort": "-$arcCreatedAt",
      "$limit": 10
    }
  ]
}

{
  "$kinds": "Order",
  "$aggFields": [
    { "%count": { "$agg": "COUNT" } },
    { "%total": { "$agg": "SUM", "$field": "amount" } },
    { "%avg": { "$agg": "AVG", "$field": "amount" } }
  ]
}

{
  "$kinds": "Order",
  "$groupBy": {
    "$by": ["status"],
    "$filter": { "total": { "$gte": 1000 } },
    "$sort": [{ "$by": "total", "$order": "desc" }],
    "$limit": 5
  },
  "$aggFields": [
    { "%count": { "$agg": "COUNT" } },
    { "%total": { "$agg": "SUM", "$field": "amount" } }
  ]
}

{
  "$kinds": "Order",
  "$groupBy": {
    "$by": [
      "customer",
      { "$js": "status.trim().toLowerCase()", "$as": "normalizedStatus" }
    ]
  },
  "$aggFields": [
    { "%count": { "$agg": "COUNT" } }
  ]
}

{
  "$kinds": "Team",
  "$fields": [
    "name",
    {
      "$expand": "members",
      "$groupBy": ["position"],
      "$aggFields": [
        { "%count": { "$agg": "COUNT" } }
      ]
    }
  ]
}

// Create: $setKinds without $id
{ "$setKinds": ["User"], "name": "Alice", "email": "[email protected]" }

// Update: $id with fields
{ "$id": "user_abc123", "email": "[email protected]" }

// Delete: $id without fields
{ "$id": "user_abc123" }

// Bulk delete: with $filter
{ "$op": "delete", "$kinds": "Task", "$filter": { "done": true } }

// User → Tag → Group → Colors, all created atomically
{
  "$setKinds": ["User"],
  "tags": [{
    "$setKinds": ["Tag"],
    "group": {
      "$setKinds": ["Group"],
      "colors": [
        { "$setKinds": ["Color"], "name": "Red" },
        { "$setKinds": ["Color"], "name": "Blue" }
      ]
    }
  }]
}

// Create + update in the same atomic batch
[
  { "$setKinds": ["User"], "name": "Bob", "status": "new" },
  { "$id": "existing_user_id", "status": "updated" }
]

// Link: add connections
{ "$id": "book1", "authors": { "$op": "link", "$id": "user1" } }

// Unlink: remove a connection
{ "$id": "book1", "authors": { "$op": "unlink", "$id": "user1" } }

// Replace: set exact connections
{ "$id": "book1", "authors": { "$op": "replace", "$id": ["user1", "user2"] } }

// DX sugar: direct assignment = replace
{ "$id": "book1", "authors": ["user1", "user2"] }

{
  "$id": "book1",
  "authors": {
    "$op": "link",
    "$kinds": "User",
    "$filter": { "role": "dev" }
  }
}

// Query projected endpoints through a tunnel link
{
  "$kinds": "Candidate",
  "$fields": [
    "name",
    {
      "$expand": "interviewers",
      "$fields": ["name", "department"]
    }
  ]
}

// Update the projected endpoints selected by the tunnel
{
  "$id": "candidate_123",
  "interviewers": {
    "$op": "update",
    "$filter": { "department": "Ops" },
    "department": "Platform"
  }
}

{
  "$id": "candidate_123",
  "interviewers": {
    "$setKinds": ["Interview"],
    "date": "2026-04-11T09:00:00Z",
    "interviewer": {
      "$setKinds": ["Interviewer"],
      "name": "Dana",
      "department": "Platform"
    }
  }
}

{
  "$setKinds": ["Invoice"],
  "subtotal": 100,
  "tax": { "$js": "subtotal * 0.21" },
  "total": { "$js": "subtotal + tax" }
}

{
  "$id": "line1",
  "total": { "$js": "price * qty" },
  "count": { "$js": "count + 1" }
}

{
  "$setKinds": ["Post"],
  "title": "Hello World",
  "slug": { "$js": "title.toLowerCase().replaceAll(' ', '-')" }
}

{
  "$setKinds": ["Invoice"],
  "subtotal": 100,
  "total": { "$ts": "const rate: number = 0.21; subtotal * (1 + rate)" }
}

// Query an existing user, then create a post using their data
[
  { "$op": "query", "$var": "_:author", "$kinds": "User", "$id": "user1" },
  {
    "$setKinds": ["Post"],
    "title": "Hello World",
    "authorName": { "$js": "_:author.name" },
    "boost": { "$js": "_:author.karma * 0.1" },
    "greeting": { "$js": "`Hello ${_:author.name}!`" }
  }
]

{
  "$kinds": "Order",
  "$fields": [
    "name", "price", "quantity",
    { "%line_total": { "$js": "price * quantity" } },
    { "%tax_label": { "$js": "'Tax: ' + (price * 0.21).toFixed(2)" } }
  ]
}

{
  "$setKinds": ["Invoice"],
  "created":  { "#datetime": "2024-01-15T10:30:00Z" },
  "dueDate":  { "#date":     "2024-02-15" },
  "openAt":   { "#time":     "09:00:00.000" },
  "price":    { "#decimal":  "19.99" },
  "eta":      { "#duration": "1h30m" },
  "active":   { "#boolean":  "true" },
  "count":    { "#integer":  "42" },
  "ratio":    { "#float":    "3.14" },
  "owner":    { "#unit":     "01J..." },
  "rawText":  { "#text":     ".name" }
}

// Write: a Schedule with two ranges. Compact notation is the
// shortest spelling; a member array of nested tuples also works.
{
  "$setKinds": ["Schedule"],
  "officeHours": { "#intervals": "[09:00:00.000,13:00:00.000) U [14:00:00.000,18:00:00.000)" }
}

// Read: results never echo the "#intervals" cast. The shape follows the
// field's intervalFormat — "tuple" here, so bounds render as pairs:
// { "officeHours": [["09:00:00.000","13:00:00.000"], ["14:00:00.000","18:00:00.000"]] }

// Schedules whose office hours contain 10:30
{
  "$kinds": "Schedule",
  "$filter": { "officeHours": { "$contains": { "#time": "10:30:00.000" } } }
}

// Schedules whose office hours overlap a meeting window
{
  "$kinds": "Schedule",
  "$filter": {
    "officeHours": {
      "$intersects": {
        "#intervals": [[{ "#time": "12:30:00.000" }, { "#time": "15:30:00.000" }]]
      }
    }
  }
}

{
  "$kinds": "User",
  "$fields": [
    "name",
    { "%fullName": { "$expr": { "@text.concat": [".name", " ", ".familyName"] } } }
  ]
}

{
  "data": {
    "$id": "abc123",
    "$kinds": ["User"],
    "name": "Alice",
    "email": "[email protected]"
  },
  "outcome": "completed"
}

{
  "data": [
    { "$id": "abc123", "$kinds": ["User"], "name": "Alice" },
    { "$id": "def456", "$kinds": ["User"], "name": "Bob" }
  ],
  "outcome": "completed",
  "meta": { "count": 2, "timing_ms": 1.23 }
}

{ "$kinds": "User", "$filter": { "status": "active" }, "$explain": "full" }

// Response shape
{
  "data": [ ... ],
  "outcome": "completed",
  "meta": { "count": 10, "timing_ms": 1.8 },
  "explain": { "steps": [ ... ], "rows_scanned": 25000, "timing_ms": { ... } }
}

{
  "data": [],
  "outcome": "completed",
  "issues": [
    { "code": "FILTER_MATCHED_NOTHING", "severity": "warning", "phase": "execution", "field": "$filter", "message": "filter matched 0 units" }
  ],
  "meta": { "count": 0, "timing_ms": 0.21, "issues": { "total": 1, "returned": 1, "omitted": 0, "errors": 0, "warnings": 1, "info": 0 } }
}

{
  "data": null,
  "outcome": "rejected",
  "issues": [
    { "code": "UNKNOWN_KIND", "severity": "error", "phase": "execution", "message": "unknown kind 'Userr'. Did you mean 'User'?" }
  ],
  "meta": { "timing_ms": 0.12 }
}