Querying data over the API
The full data_module reference, dbs_read's filter and sort shapes, and what dbs_delete and dbs_restore actually flip.
Six methods on data_module cover a table end to end: the same six a table's grid calls, in
Studio and on the dashboard's Data tab, and the same ones a running app
calls through xu.dbs_* (see JavaScript Framework). With an account
API key they are reachable directly, see
Query and write app data for a worked dbs_read /
dbs_create walkthrough with request and response bodies. This page is the reference for the
other four, and for the filter, sort and archive options dbs_read accepts.
Methods
Every one of them takes table_id, the table node's own _id, never its display name, and every
write goes through the same field-type casts described in
Tables and fields.
Updating a row
DBS Update
Replaces the data of an existing record, identified by row_id, in the specified app table.
table_data is merged into the row's existing data by field id, only the fields you include are
changed, every other field already on the row is left as it was. Send just the fields you mean to
change, there is no need to read the row first to preserve the rest.
Deleting and restoring rows
DBS Delete
Soft-deletes (or permanently deletes when 'permanent' is set) the listed record IDs from an app table.
DBS Restore
Restores previously soft-deleted records, identified by their IDs, in the specified app table.
dbs_delete without permanent does not remove the row, it flips it to archived, the same state
a row lands in when someone archives it from the grid. An archived row stops showing in an
ordinary dbs_read, but still exists and still counts toward get_table_counts' archived
figure, and dbs_restore flips it straight back. permanent: true skips the archive step and
deletes the row outright, which dbs_restore cannot undo.
This is a row's own active/archived state, set with dbs_delete and dbs_restore and read
back with dbs_read's archived flag. It is unrelated to a whole table being archived as a
Studio node, covered in Tables and fields.
Counting rows
Get Table Counts
Returns the number of records in a table: active records, or archived records when archived is true.
Returns the active and archived row counts for one table, the same figures dbs_read already
attaches to its own response as total_table_count, useful on its own when you want a count
without paging through rows to get one.
Filtering a read
dbs_read's query field is an object keyed by field id, each value naming a filter type and
operator:
Every field named in query is combined with the others with AND. A single field can also carry
its own list of conditions with an OR or AND operator between them, for "this field
matches either of these":
Sorting and paging
sortModel is a list of { colId, sort } pairs (sort is asc or desc), applied in the order
given for a multi-column sort. from and to are a row range (from the offset, to - from the
page size), both optional; omit them and you get the table's default page.
Errors worth knowing
These apply across all six methods above, not only a write: