Brapi Dataframe Query
brapi_dataframe_queryRun read-only SQL across in-memory dataframes. Dataframes auto-populate when find_* tools spill (named df_<uuid>) — the dataframe name appears inline on every find_* response that spilled (result.dataframe.tableName), so the typical flow is find_* → read the name → query here. Use brapi_dataframe_describe to inspect schema and provenance for a known name. Use LIMIT/OFFSET to walk results, projection to trim columns, and aggregation to summarize. Use registerAs to chain — the result lands as a new dataframe.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"sql": "<sql>"
},
"name": "brapi_dataframe_query"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | One read-only SQL statement against dataframes. Use SELECT for rows and aggregation, DESCRIBE or SHOW for a known table or query, and SUMMARIZE for column statistics. Writes, DDL, file reads, and exports are rejected. Use `LIMIT/OFFSET` to page a large dataframe and projection to trim columns. | |
| preview | No | Cap the number of rows returned in this response. A value above `rowLimit` (or, when `rowLimit` is omitted, above the deployment-wide response cap) returns rows up to that ceiling. When omitted, the ceiling applies. Lower this with `registerAs` when you only need a sample to verify the query. | |
| rowLimit | No | Hard cap on rows materialized into the response, bounded by the deployment-wide response cap. For larger result sets, use `registerAs` to keep the full result queryable instead of raising this. | |
| registerAs | No | Persist the full result as a new dataframe under this name. The response is bounded by preview and a 24,000-byte row budget. Conflicts fail — choose a different name, or remove the existing dataframe with brapi_dataframe_drop where this deployment enables it. Identifier rules: letters, digits, and underscores; must start with a letter or underscore; max 63 characters. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | Row ceiling that bound the response: the smallest of preview, rowLimit, and the deployment-wide response cap. | |
| rows | No | Leading rows bounded by preview/rowLimit and 24,000 bytes on each serialized row representation. May be empty when the first row is oversized. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Rows materialized into `rows`. | |
| notice | No | Guidance for reaching the rows this response left out. | |
| columns | No | Column names and types in projection order, enough to write a follow-up query. | |
| rowCount | No | Total rows the query produced (may exceed `rows.length` when capped). | |
| dataframe | No | Name of the dataframe holding the full result, populated when `registerAs` was supplied. Reference this name in follow-up queries. | |
| truncated | No | True when the response carries fewer rows than the query produced. |