Skip to content
Verified

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

POST/cpi/dbs_update
admin

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

POST/cpi/dbs_delete
admin

DBS Delete

Soft-deletes (or permanently deletes when 'permanent' is set) the listed record IDs from an app table.

POST/cpi/dbs_restore
admin

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.

Row archive, not table archive

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

POST/cpi/get_table_counts
admin

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:

json
{
  "query": {
    "STU_Campus": { "filterType": "text", "type": "equals", "filter": "Downtown" },
    "STU_Age": { "filterType": "number", "type": "greaterThanOrEqual", "filter": 18 }
  }
}

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":

json
{
  "query": {
    "STU_Campus": {
      "operator": "OR",
      "conditions": [
        { "filterType": "text", "type": "equals", "filter": "Downtown" },
        { "filterType": "text", "type": "equals", "filter": "Uptown" }
      ]
    }
  }
}

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: