Authoring reference

​

Tables & fields

• A column default must stay within the BMP. A 4-byte character (codepoint > U+FFFF, e.g. an emoji) is mangled into invalid UTF-8 by the engine’s default pipeline, so it is rejected at export rather than 500ing at deploy with Postgres 22021. Accents, €, and most CJK are fine; otherwise put the value on an endpoint input, applied at runtime bind.
• id and created_at auto-inject at the head of the schema unless system: false or you declare them (idType: "uuid" for a uuid key). Both are usable wherever a column name is expected and both appear in InferRow. The standard indexes — primary(id), btree(created_at desc), plus gin(xdo) when the table stores fields as JSON — auto-prepend, de-duped against your own. Declare yours as { type, fields: [{ name, op? }] }; "unique" is shorthand for "btree|unique".
• use_xdo picks the storage mode — every field as JSON under the internal xdo column, or a real Postgres column per field. It is a workspace setting (default false) each table mirrors, overridable per table with table({ useXdo }), resolved at export() so the two can register in any order.

​

Statements, values & inputs

stack: [
  s.set_var("total", c.int(0)),
  s.math.add({ name: "total", value: c.int(5) }),
  s.array.find({ as: "hit", expr: ref("items"), if: expr(ref("$this"), "=", c.int(1)) }),
  s.conditional({ when: expr(ref("total"), ">", c.int(0)), then: [s.return(ref("total"))] }),
  s.function.run({ fn: getUser, as: "u", input: { id: ref("total") } }),
]

s.security.create_uuid({ as: "token", asFilters: [fl.upper()] })
s.set_var("email", inp("raw"), { asFilters: [fl.trim(), fl.lower()] })

s.db.query({ table: users, as: "rows", asFilters: [fl.count()] })       // rows: number
s.db.query({ table: users, as: "rows", asFilters: [fl.reverse(), fl.first()] })  // rows: Row
withFilters(ref("rows"), fl.count())                                    // number

s.ai.external.mcp.tool.run({ url, tool, connection_type: "stream" }) // ✅ "sse" | "stream"
s.ai.external.mcp.tool.run({ url, tool, connection_type: "streaming" }) // ❌ compile error, and throws
s.ai.external.mcp.tool.run({ url, tool, connection_type: inp("mode") }) // ✅ resolved at runtime

• A join condition spells its two sides differently. The joined table’s column takes its as alias; this query’s own columns stay bare: bind: [{ table: users, as: "author", join: "left", where: expr(col("author_id"), "=", col("author.id")) }]. Qualifying your own column by the table’s name (col("posts.author_id")) resolves only if the query also sets tableAlias — the alias the qualifier is matched against. Unqualified, the engine reads the operand as a text literal and fails at runtime with a parse error naming the other operand, so db.query rejects that spelling at export instead.
• A join adds no columns to the returned row. With or without a bind, a row is the queried table’s columns — which is what InferResponse types, so there is no row.author to read. To bring a joined column back, project it with an eval whose name is the dotted path: eval: [{ name: "author.name", as: "author_name" }] puts author_name on the row and on the inferred type. A bare name there fails at runtime (it qualifies to the base table), and a dotted joined column in output is dropped with no error.
• Paging changes the response shape. Supplying paging with metadata on (the default) returns a paging envelope — { items, curPage, nextPage, prevPage, offset, perPage, itemsReceived }, plus totals when totals: true — instead of a bare Row[], and InferResponse reflects that. Pass metadata: false to keep the bare array. Read nextPage (number | null) as the typed has-next signal. It also moves what output selects from. The selection applies to the value the statement binds, so under the envelope its roots are the counters and items.<column> — output: ["itemsReceived", "curPage", "items.id", "items.title"]. A bare column list there matches no envelope key, so every key is dropped and the endpoint answers [] at HTTP 200 with no error. export() warns and --strict fails; with metadata: false the statement binds the rows and bare columns are the right form.
• Don’t author mixed(...) conditions. Xano’s editor allows a container whose terms don’t all join the same way, so pulled workspaces contain it and it round-trips — but the stored form doesn’t record the intended grouping, and the two places it can appear disagree: a branch folds terms strictly left to right (a OR b AND c = (a OR b) AND c) while a db.query filter inherits SQL’s AND-before-OR precedence (a OR (b AND c)). Write and(or(a, b), c) or or(a, and(b, c)) — each says exactly one thing in every context.
• like/ilike take the operand as the pattern, verbatim. The operand is the pattern, so cmp(col("body"), "ilike", inp("q")) with a bare term matches only a whole-string equal — and the endpoint answers 200 with an empty list, which reads as “no results for that query”. For substring search use includes / not includes, which wrap the operand in %…% themselves and match case-insensitively. Prefer that over building "%" + term + "%": a hand-built pattern is non-empty even for a blank term, which defeats the ignoreEmpty below. contains / @> / overlaps are JSON and array containment, not text — on a text column they fail with a parse error.
• ignoreEmpty DROPS the clause — it does not match zero rows. cmp(col("owner"), "in", ids, { ignoreEmpty: true }) with an empty ids returns the unfiltered table, where the same clause without the flag matches nothing. Never put it on a filter that scopes rows to a permitted set: an empty permission list then returns everything. It is for an optional search filter, where a blank box really does mean “don’t filter”. export() warns when the operand is empty in the bundle; a runtime-empty list is yours to reason about.
• Compose a rule set as siblings, not a folded chain. and(...)/or(...) take any number of terms and encode flat, so build the array and spread it — and(...rules). Folding one term at a time (rules.reduce((acc, r) => and(acc, r))) nests a container per rule, and nesting costs quadratic bytes: 512 terms are 394 KiB as siblings and 21 MiB folded. Past 128 levels the build fails with a message naming the fix. Mixing joins? Group each run: and(or(...anyOf), ...allOf).
• An aggregate or eval name is written bare ("status") and alias-qualified on emit; the engine rejects a bare column in either, and an already-dotted joined column passes through. The statement also declares the alias it qualified with, so the qualified name resolves — nothing to set by hand.
• eval is where vector search lives. An eval filter pipeline compiles to SQL, so it resolves a different filter registry than fl.* (which runs in the request) — including the distance filters an f.vector column needs. Compute the distance, then sort by the alias it grafts onto the row; the ranking happens in the database, over the column’s index:
  s.db.query({
    table: chunk,                                     // index: [{ type: "vector", fields: [{ name: "embedding", op: "vector_cosine_ops" }] }]
    eval: [{ name: "embedding", as: "distance",
             filters: [{ name: "vector_cos_distance", arg: [inp("q")] }] }],
    sort: [{ sortBy: "distance", dir: "asc" }],       // nearest first
    paging: { per_page: 10, metadata: false },
  })
  
  Match the filter to the index op (VECTOR_FILTERS, on @xanots/sdk/internal, lists the family). The same filter works on a where operand to cut off by distance rather than by row count.
• A where operand may carry filters — except the request-time timestamp ones. A where is compiled into SQL, and most filters have a SQL form there (trim, concat, upper, lower, and the epochms_add_day / epochms_sub_month family). The request-time timestamp filters do not — epochms_transform, epochms_add_ms, epochms_add_secs, epochms_date, epochms_from_format — and the engine doesn’t degrade gracefully: the request dies with a bare fatal naming nothing. For a relative cutoff, use the SQL-side spelling — by raw name, since fl.* carries no builder for that family: filter("epochms_add_day", …) or the raw { name, arg } form — or compute it in an earlier s.set_var and ref() that. export() warns; a bare c.now() is always fine.
• A s.switch case without break: true falls through. The engine’s default is fallthrough, so a matched case also runs every later case body — and the default block too. Whatever those bodies write gets written two or three times, at HTTP 200, with tsc and a plain export both clean. Set break: true on every case unless you mean the cascade; export() warns when a break-less case has somewhere to fall into.

export const authorAddon = addon({
  name: "author",
  table: userTable,
  where: expr(col("id"), "=", inp("user_id")),   // bind to the parent row
  output: ["id", "name"],
  cardinality: "single",
  input: { user_id: input.int({ required: true }) },
});

s.db.query({
  table: post,
  addon: [{ addon: authorAddon, as: "_author", input: { user_id: out("author") } }],
  as: "rows",
});

• c.obj/c.array take plain JSON literals only. A nested tagged value (inp/ref/auth/c.*) is a compile error. For a computed object — a response, or an api.request params — use a record of values ({ count: ref("count") }). For a dynamic object argument use obj({...}), which builds a checked expression.
• An obj({...}) member may carry a filter chain. That matters most for the null-safe drill: db.get binds null on a miss, so obj({ city: ref("row.address.city", { safe: true }) }) is the normal shape — no per-member s.set_var to hoist it out. c.now(), env() and sys.*() are members too. { safe: true } is for a base that exists and may be null: on a base nothing binds it would hide a typo behind a null, which is why export() warns (with a did-you-mean) when a ref()’s base segment names no as in that stack.
• c.int takes a string or bigint past Number.MAX_SAFE_INTEGER. The engine stores integers as strings and has no 53-bit limit, so c.int("18446744073709551615") is exact where the number literal for it is already …616. A number that is not a safe integer throws rather than encoding the rounded value.
• A bare scalar works in any fl.* argument. fl.get("a.b", 0) encodes identically to fl.get(c.text("a.b"), c.int(0)); strings, numbers and booleans are all wrapped for you. Objects and arrays still need c.obj/c.array.
• A typed fl.* call is capped at its declared argument count. Passing more throws, in the type and at runtime — an extra argument used to ride into the filter’s arg list for the engine to ignore or fail on. filter("name", …) is the untyped escape. Seven filters the catalog under-declares stay variadic (concat, index_by, get, array_merge, array_merge_recursive, jwe_encode, jwe_decode). The other 95 filters take no arguments at all — they are emitted (), so fl.abs(x) is a compile error rather than an argument silently shipped to an engine that does not accept one.
• api.request headers take a { "Name": value } record, values may be tagged: headers: { "x-api-key": env("KEY") }. Prefer a header over a ?key= query param for a credential — a URL travels into access logs, proxies and Referer. That is not envelope safety, though: the as envelope’s request half mirrors url, params and headers, so never return it raw from a credentialed request; read response.result.
• Some filters require an argument their own docs call optional. Filter arguments are positional, and a short call is refused by the engine before the filter runs — so fl.csv_encode() and fl.number_format() are compile errors here rather than a failure on a deployed endpoint. Which filters those are is probed, not declared: fl.round() is also documented optional and genuinely works. Pass every argument the signature shows without a ?; the runtime guard names the count if you reach it from JavaScript.
  withFilters(ref("rows"), fl.csv_encode(",", '"', "\\")), // not fl.csv_encode()
  
• fl.csv_encode writes no header — fl.csv_create is the one that does. They read as interchangeable and are not. csv_encode emits each row’s values in that row’s key order with no normalization across rows, so rows whose keys differ in order or count misalign columns silently; nested cells are JSON-encoded, false writes empty, and a piped array of scalars collapses to a single line. csv_create takes the column names as its piped value and the data as its rows argument.
• Only fl.fsort({ type: "number" }) sorts numerically. Every other comparator — including a spelling the engine does not recognize — sorts as case-insensitive text, silently and with no error, so [2, 10, 1] comes back [1, 10, 2]. A lexicographic sort agrees with a numeric one whenever the values share a digit count, so this looks correct on small data and goes wrong on real data: a “top N by score/distance/recency” endpoint returns the right rows in the wrong order. The union rejects the two plausible wrong spellings ("decimal", "int") outright.
  withFilters(ref("rows"), fl.fsort({ path: "score", type: "number", asc: true })),
  
• col() does not resolve to a stored value inside a db.edit row. To read-modify-write a column — incrementing a counter — db.get the row first and pipe its bound value through a filter. col() evaluates to null there, so fl.add(1) computes null + 1 and the engine aborts.
  s.db.get({ table, fieldValue: inp("id"), as: "current" }),
  s.db.edit({ table, fieldValue: inp("id"), row: { clicks: withFilters(ref("current.clicks"), fl.add(c.int(1))) } }),
  
  That pair is not atomic — concurrent writers can lose an increment, and no atomic increment statement exists. A genuinely safe counter needs the arithmetic in the database via s.db.direct_query, which in turn needs the table’s physical Postgres name; that name is assigned at import and is not knowable from a table() def, so it has to be hardcoded after inspecting the deployed table. A typed path requires an engine change (issue #35).
• A JavaScript body is written as a function, not a c.text string. The lambda statement (s.lambda) and eight filters (fl.map/filter/some/every/find/ findIndex/reduce/lambda) run JavaScript against a small, closed set of injected identifiers — and which ones are in scope depends on the surface. Write the body inline and the surface is implied by where it sits: the bindings are the function’s parameters, typed from the position, so your editor supplies them and a wrong name is a compile error rather than a wrong value in production.
  // reduce's accumulator is `$result`. Autocomplete says so; `$acc` does not compile.
  withFilters(ref("prices"), fl.reduce({ initial_value: 0, code: ({ $result, $this }) => $result + $this })),
  
  // A map body, typed as a map body — nothing names the surface.
  withFilters(ref("prices"), fl.map(({ $this, $index }) => $this * ($index + 1))),
  
  // The statement surface binds ambient state only: `$this` here is a compile error.
  s.lambda({ as: "total", code: ({ $var }) => $var.subtotal * 1.2 }),
  
  The parameters are a fiction — only the body is sent, and the engine injects the bindings as free identifiers — so destructure them. (b) => b.$this * 2 would emit return b.$this * 2 with b undefined at runtime, and the SDK refuses it. fl.transform is not one of these. It sits next to them and reads like one, but it takes a Xano expression — no return, and the piped value binds as $0 (or $$), not $this. A $this there resolves to null and the call still returns HTTP 200, so the SDK refuses both spellings at author time and points at $0.
  // An expression over the piped value — not a JS body.
  withFilters(ref("prices"), fl.transform("$0 * 1.2")),
  
  // Parenthesize a pipe inside an object literal, or the filter argument's comma is read
  // as the key separator and every later key silently vanishes.
  withFilters(ref("items"), fl.transform('{ names: ($0|sort|join:","), n: ($0|count) }')),
  
  For a body built away from its call site, lam.* names the surface explicitly:
  const rate = 0.2;
  // Nothing from the enclosing scope crosses implicitly — declare what the body needs.
  // The capture key must differ from the module binding: the loader renames one of two
  // same-named bindings and the prelude is written under the original name.
  s.lambda({ as: "vat", code: lam.fn(({ $var }, { capturedRate }) => $var.total * capturedRate, { surface: "s.lambda", capture: { capturedRate: rate } }) }),
  
  Omit surface and the check is deferred to wherever the body lands, which is the thing that knows. lam.file("./lambdas/total.ts") reads a default-exported function of the same shape from its own type-checked module — the deterministic option under a bundler, where a function’s own source is whatever the bundler emitted. It needs a filesystem, so it ships on the Node entry only: import { lam } from "@xanots/sdk/node", whose lam carries fn and raw unchanged. lam.raw(code) is the text escape hatch, guarded identically, and works on either entry. The full binding table per surface is in llms/lambda.md. Three things to know, all live-verified against a real engine:
  • A body that throws does not fail the request — the engine returns its diagnostic text as the value with HTTP 200, so the failure arrives as bad data rather than an error. That is engine behavior and not interceptable from an SDK; validate before consuming a lambda result numerically, and prefer an authored body, which cannot fail that way for a binding reason.
  • The body is a function body, not a module: it must return, and a top-level import is a syntax error. Reach a dependency through the preloaded globals — crypto, fetch, Buffer, axios, jose, _, math, moment, DateTime, uuid and friends, which need no specifier. A dynamic import("…") or require("…") with a literal specifier is not portable: some instances bundle the body before running it and resolve every literal specifier ahead of time, so await import("node:crypto") comes back as the text Could not resolve "node:crypto" with HTTP 200; others resolve it at run time and it works (issue #265).
  • console output goes to the request log, not stdout.
  A plain c.text(...) body is still accepted and gets the same build-time check — the guard sits at the call site, not inside lam.* — so an unknown $identifier fails whichever way you write it (issue #221).
• c.expression("…") is carried through verbatim and NOT validated. XanoTS does not parse it or type-check it; nothing inside participates in InferResponse, so a var named there is invisible to a rename that updates every typed ref(). A malformed expression fails at runtime; one that is merely wrong ($var.tota1) returns a wrong answer. Reach for it only for syntax the typed surfaces can’t express — ~ concatenation, inline arithmetic, conditionals — and note it is not the expr() condition builder. (c.expressionLegacy exists only so codegen can return an older stored form.)

s.precondition({
  // `fl.regex_test` is PATTERN-piped: the piped value is the regex and the arg is the
  // text tested — the reverse of `istarts_with`. Build the pattern with `c.regex(...)`,
  // which delimiter-wraps it (a bare `c.text("^…")` is an invalid PCRE matching nothing).
  expr: expr(withFilters(c.regex("^https?://", "i"), fl.regex_test(inp("url"))), "=", c.bool(true)),
  error_type: "badrequest",
  error: c.text("url must be an http(s) URL"),
})

// Signup — plaintext in; the f.password COLUMN hashes on write.
query({ name: "signup", verb: "POST", apiGroup: authApi,
  input: { email: input.email({ required: true }), name: input.text(),
           password: input.text({ required: true, methods: ["min:6"] }) }, // NOT input.password()
  stack: [
    s.db.add({ table: usersTbl,
      row: { email: inp("email"), name: inp("name"), password: inp("password") }, as: "user" }),
    s.security.create_auth_token({ table: usersTbl, id: ref("user.id"), as: "token" }),
  ],
  response: ref("token") });

// Login — plaintext compared against the stored hash.
query({ name: "login", verb: "POST", apiGroup: authApi,
  input: { email: input.email({ required: true }),
           password: input.text({ required: true }) },                     // NOT input.password()
  stack: [
    s.db.get({ table: usersTbl, fieldName: "email", fieldValue: inp("email"),
               output: ["id", "email", "password"], as: "user" }),
    s.precondition({ expr: expr(ref("user"), "!=", c.null()),
      error_type: "accessdenied", error: c.text("Invalid email or password.") }),
    s.security.check_password({ text_password: inp("password"),            // plaintext
      hash_password: ref("user.password"), as: "ok" }),
    s.precondition({ expr: expr(ref("ok"), "=", c.bool(true)),
      error_type: "accessdenied", error: c.text("Invalid email or password.") }),
    s.security.create_auth_token({ table: usersTbl, id: ref("user.id"), as: "token" }),
  ],
  response: ref("token") });

​

Middleware, request history & env vars

query({
  name: "get_user", verb: "GET", apiGroup: blog,
  middleware: { pre: [rateLimit], post: [audit] },
  stack: [/* ... */], response: ref("user"),
});

• exceptionPolicy decides whether a guard is a guard. "silent" is the default and swallows the throw, so a rate limit or auth check authored without an explicit policy is not enforced. "rethrow" aborts the request and surfaces the authored error/status (a tripped s.redis.ratelimit → 429) while still running post; "critical" is the same but skips the post chain. That is the only difference.
• Inheritance is override, not merge. Providing a phase overrides it; omitting a phase inherits the parent tier’s chain, resolved at request time Query → API Group → Workspace. pre: middleware.clear() overrides a phase with nothing.
• Setting workspaceConfig.middleware at all emits the whole map. Any host/phase you don’t list is emitted empty, which clears that tier on deploy. Omit the field entirely to leave the workspace’s existing middleware untouched. The same wholesale rule applies to datasources.
• auth() is null on a public host, and a pre middleware runs after auth resolution. A rate limit keyed by auth("id") on a public endpoint collapses every caller into one bucket, silently. export() warns on direct attachment of an auth()-keyed middleware to a host where auth() may be null.
• A resultStrategy: "replace" middleware attached post rewrites the response at runtime, which InferResponse can’t see — declare responseShape on the endpoint.
• workspaceConfig also carries realtime, documentation, and swagger, which are server-shaped and carried verbatim rather than authored. realtime there is the legacy workspace-level block, not the realtime primitives you author.

const writeRl = middleware({
  name: "write_rl",
  exceptionPolicy: "rethrow", // a tripped limit must abort (silent would let it through)
  stack: [
    s.redis.ratelimit({
      key: withFilters(c.text("rl:write:"), fl.concat(auth("id"))), // "rl:write:<id>"
      max: c.int(10), ttl: c.int(30), error: c.text("Too fast."),
    }),
  ],
});

query({ name: "create_post", verb: "POST", apiGroup: blog, auth: users, // authed ⇒ per-user
  middleware: { pre: [writeRl] }, stack: [/* ... */], response: ref("post") });

query({ name: "get_user", verb: "GET", history: 100 });   // capture, depth cap 100
apiGroup({ name: "blog", history: false });               // default for its queries
workspaceConfig({ history: { query: 100, trigger: "all" } });  // name inherited from workspace("…")

workspaceConfig({
  name: "my-app",
  env: {
    STRIPE_KEY: process.env.STRIPE_KEY!,          // sourced from the deploy environment
    APP_BASE_URL: "https://my-app.example.com",   // a plain config value
  },
});

​

Seed data

const product = table({
  name: "product",
  schema: {
    sku:   f.text({ required: true }),
    name:  f.text({ required: true }),
    price: f.decimal(),
    tags:  f.text({ array: true }),
  },
  // Rows are validated against the column types before deploy. A column without
  // `required: true` may be omitted (the engine applies its default). Omit `id` and
  // rows are keyed for you — 1..N for an int PK, a stable uuid for a uuid PK (or
  // set `id` on every row); a bad value
  // or unknown column is a loud error, never a silent drop.
  seed: [
    { sku: "SKU-001", name: "Aeron Chair",   price: 1395, tags: ["furniture", "ergonomic"] },
    { sku: "SKU-002", name: "Standing Desk", price: 599,  tags: ["furniture"] },
  ],
});

seed: seedFile("./products.seed.json", import.meta.url),