literal (persisted)
A real column. Stored on the backend. Validated on write against fieldType (string, number, boolean, date, json) and optional fieldEnum.
Xuda Developer Studio
Tables: typed records, real backends, real subscriptions.
The third chapter
A table is a schema plus a backend. Switch the backend without touching the schema.
A Xuda table is a record type: a list of typed fields and a list of indexes. The actual storage is
provided by a dbs plugin you pick per table. The native Xuda backend gives you live
subscriptions, the CouchDB and MySQL adapters give you classic CRUD, and you can write your own adapter
for anything that speaks JSON.
Shape
A table document under
A table document under project.tables[id].
Each table is keyed by its id. Properties hold the display name and the backend choice. Fields define the row shape. Indexes define which queries are cheap. Records themselves do not live in this document; they live in whichever backend the table points to.
project.tables.tbl_invoices
{
_id: 'tbl_invoices',
properties: {
menuType: 'table',
menuName: 'Invoices',
databaseSocket: '@xuda.io/xuda-dbs-plugin-xuda',
accountId: 'acc_default'
},
tableFields: [
{ data: { field_id: '_id', type: 'literal', serverField: true } },
{ data: { field_id: 'customer_id', type: 'literal', serverField: true } },
{ data: { field_id: 'amount', type: 'literal', serverField: true },
props: { fieldType: 'number' } },
{ data: { field_id: 'status', type: 'literal', serverField: true },
props: { fieldType: 'string', fieldEnum: ['draft','open','paid','void'] } },
{ data: { field_id: 'created_at', type: 'literal', serverField: true },
props: { fieldType: 'date' } },
{ data: { field_id: 'total_with_tax', type: 'virtual', serverField: false },
props: { propExpressions: { fieldComputed: '@amount * 1.17' } } }
],
tableIndexes: [
{ id: 'idx_status_created', data: { keys: ['status', 'created_at'] } },
{ id: 'idx_customer', data: { keys: ['customer_id'] } }
]
}
Fields
Every column has a type, a kind, and (sometimes) an expression.
The same field data.type taxonomy you saw in globals shows up here. The difference is
serverField: true means the field is persisted, false means it is
computed on read. That single flag is the line between schema and projection.
virtual (computed)
Not stored. Evaluated on every read. Use for derivations like a tax-inclusive total or a full name.
datasource (joined)
Pulls from another table. Configured with a fieldDataSource and a fieldQuery. The runtime resolves the join when the row is read.
plugin (external)
Computed by calling a library plugin method on read. Useful for fields that come from external services (geocoded addresses, exchange-rate conversions).
fieldRequired
Marks the field as mandatory at write time. The studio renders the editor as a required input; the server rejects writes missing the field.
fieldEnum
An array of allowed values. Renders as a select in the studio and as a constraint on write.
Indexes
An index is a list of keys. Composite by design.
Indexes live in tableIndexes as { id, data: { keys } }. The order of the keys
matters: it defines the sort order and the prefix the runtime can use to short-circuit queries. The
native Xuda backend uses indexes for both querying and live subscriptions; SQL adapters translate them
to CREATE INDEX; CouchDB translates them to view definitions.
A composite index, built and used
// Schema:
tableIndexes: [
{ id: 'idx_status_created', data: { keys: ['status', 'created_at'] } }
]
// Query against it (in a progDataSource on a list program):
{
dataSourceType: 'table',
dataSourceTableId: 'tbl_invoices',
dataSourceQuery: '({ status: \"open\" })',
dataSourceOrderBy: 'created_at',
dataSourceOrderDir: 'desc',
dataSourceLimit: 50
}
Read & write
Programs read tables through a
Programs read tables through a progDataSource. Writes happen through workflow actions.
A program that lists invoices points its progDataSource at the table. A program that edits
a single invoice fetches one record by id. Writes never go through the field directly: they go through a
workflow step (upsert, delete, or a plugin method) that the runtime dispatches
to the backend.
Bind a list program to a table.
progDataSource: {
dataSourceType: 'table',
dataSourceTableId: 'tbl_invoices',
dataSourceQuery: '({ customer_id: @route.params.id })',
dataSourceOrderBy: 'created_at',
dataSourceLimit: 100,
realtime: true
}
Upsert a row from a button.
<button xu-on:click='[{"workflow":[
{"data":{"action":"upsert",
"table":"tbl_invoices",
"fields":{"_id":"@_id",
"customer_id":"@customer_id",
"amount":"@amount",
"status":"\"open\""}}},
{"data":{"action":"toast",
"name":{"value":"\"Saved\""}}}
]}]'>Save</button>
Realtime
The native Xuda backend pushes changes. Other backends poll.
Set realtime: true on a datasource and the runtime opens a subscription on the chosen
backend. The native Xuda store wires it up over the broker chain so you get push updates with
sub-second latency. CouchDB falls back to _changes long-polling. SQL adapters fall back to
a polling interval. The reading code does not change either way.
Caveat (heads up)
If you see a runtime warning about a table being typed without a
dataSourceTableId, double-check that the datasource bound to the program actually has that
key set. The runtime treats the missing id as a configuration bug rather than guessing the target.
In the studio
Tables panel: schema editor, data viewer, indexes editor.
The Tables panel splits into three tabs: schema (the field list), data (a paginated record viewer with filters and inline editing), and indexes (composite key builder). Switching the backend is a one-click change in properties; the studio re-runs validation and warns about features the new backend cannot support.