Finding rows

Consider a catalogue with “Product”, “Price”, and “In stock” columns. You can ask an agent: “Which products with ‘tea’ in their name are in stock? Show the cheapest first.” Connect the table to the agent and allow it to read tables. Edit permission is not required.

Prepare the headers

Name the columns in the first row of the worksheet. A blank header excludes that column from named queries; the cells keep their data. If two headers match, the query fails and the error identifies both cells, such as A1 and C1. Rename one column.

Use the exact header from the sheet in filters and sorting. In an agent's row query, row_number is reserved for the worksheet row number. The first data row is row 2. Do not use this name for your own column. If you cannot change the headers, specify a cell range such as A2:C20; you can read it without querying by column name.

Example API request

POST /api/knowledge-base/tables/:id/rows/query reads data without changing the table. It requires knowledge base view access. For the example catalogue, send this request body:

{
  "filters": [
    { "column": "Product", "contains": "tea" },
    { "column": "In stock", "equals": true }
  ],
  "sort": { "column": "Price", "direction": "asc" },
  "limit": 10
}

All filters must match. contains matches part of the text, ignoring case. equals compares the exact value: the number 0 and the text "0" are different. Empty values in the sort column come last.

Without sheet_id, the query uses the first worksheet. The default limit is 50 rows, with a maximum of 500 per request; use offset for the next page. Unlike the agent tool, the API does not add a row number field to the results.