table-rows

Query table rows

List a table's rows with keyset pagination on an opaque cursor. Without a sort, rows come in DISPLAY order: the user-controlled row position, with the time-ordered record ID as a tiebreak. With one, they come in that column's value order, and rows with no value for it sort LAST in both directions. Filters are predicates on cell values and compose with either order.

column_ids projects each row's cells: send the columns the grid will render and the response carries only those. It echoes the projection back, so a column outside it reads as 'not fetched' rather than 'blank'.

A POST because a filter list has no honest query-string encoding. Each cell's computing flag is derived: stale AND an active run covers that row.

Performance note: an unfiltered sort streams the column's index. Add a filter and Postgres sorts the matched set instead, so a filter that matches most of a very large table is correspondingly slower.

post/tables/{table_id}/rows/query/

Request

  • Base URL: https://api.getoneprofile.ai (the document declares no server; this is the origin it was published from)
  • URL: https://api.getoneprofile.ai/tables/{table_id}/rows/query/
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

table_idstring uuid required

Request body

column_idsstring[] nullable

Project each row's cells to these columns. Omit for every column. The response echoes the projection in column_ids so a client can tell a blank cell from one it did not ask for.

cursorstring nullable

Opaque cursor from a previous page's next_cursor.

limitinteger

Maximum rows per page.

offsetinteger nullable

Start the listing this many rows in, rather than at the top: a jump-to-row seek. Mutually exclusive with cursor, which resumes a listing rather than starting one. Postgres walks the skipped rows, so use this for a deliberate jump. Keep paging with next_cursor.

record_idsstring[] nullable

Hydrate exactly these rows, instead of describing a listing. Mutually exclusive with sorts, where, row_status, offset and cursor: those select rows, and this names them. Pair with /rows/ids/ to fetch an ordering once and then fill in row contents a window at a time, which lets re-sorting or re-filtering reuse cells the client already holds.

row_status'errored' | 'fully_computed'

A row-level state, derived from its cells rather than stored.

ERRORED is "any cell of this row failed to compute"; FULLY_COMPUTED is its exact complement, so the two partition the table. Serves the built-in smart views, which are questions about computation rather than about values. The ordinary filter vocabulary cannot express either.

Response

Successful Response

column_idsstring[] nullable required

The columns whose cells this page carries, or null for all of them. A column outside this list is NOT blank. It was simply not fetched.

has_moreboolean required
limitinteger required
next_cursorstring nullable required

Cursor for the next page; None when this is the last page.

Changes

No recorded changes to this operation across all 1 revision of this API.