Secedgar Dataframe Query
secedgar_dataframe_queryRun a single-statement SELECT against the canvas dataframes registered by the data-returning secedgar_* tools — any tool whose response carries a dataset handle. Inspect a dataframe with secedgar_dataframe_describe first; its column schema is what the SQL has to match. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected. System catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are denied — reference dataframes by the df_ name a data tool returned. Optional register_as chains the result as a new dataframe with a fresh TTL.
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": "secedgar_dataframe_query"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | Single-statement SELECT against df_<id> tables on the shared canvas. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all supported. Reference dataframes by the df_<id> name a data tool returned in its `dataset` field, or a register_as name. BIGINT columns (e.g., XBRL `value`, COUNT/SUM results) serialize as JSON strings to preserve precision past 2^53 — CAST(col AS DOUBLE) in projections for inline arithmetic. | |
| preview | No | Rows to include in the immediate response. Defaults to `row_limit`, and a value above `row_limit` is read as `row_limit`. Set lower (e.g., 50) when chaining via register_as and only a sample is needed inline. Capped at 10000: a larger value, up to 100000, returns what 10000 returns. | |
| row_limit | No | Hard cap on rows materialized in the response. Default 1000. A query matching more rows than this stops at the cap and `row_count_capped` comes back true; the full result lives on-canvas under register_as when provided, so do not raise this to keep large results. One case is not detectable: a SQL LIMIT exactly equal to this cap reads identically to a result that genuinely holds that many rows, and is reported as exact. Capped at 10000: a larger value, up to 100000, returns what 10000 returns. | |
| register_as | No | When set, persist the result as a new dataframe under this name (must match df_XXXXX_XXXXX shape, or pass a fresh df_<id> generated by the agent). Fresh TTL window — not inherited from the parents in the SELECT. Use to chain analyses without re-running the source SQL. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The row cap that actually bound — `preview` when it is lower than `row_limit`, otherwise `row_limit`. | |
| rows | No | Materialized rows, bounded by `preview` / `row_limit`. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of rows returned inline. | |
| notice | No | Guidance when the query returned no rows or the row cap withheld some. | |
| columns | No | Column names in projection order. | |
| row_count | No | Rows the query produced, up to `row_limit` — with `register_as`, every row of the registered table; exceeds `rows.length` when `preview` or `row_limit` returned fewer. When `row_count_capped` is true this is the cap, not the full size. | |
| truncated | No | True when the row cap withheld rows. | |
| expires_at | No | ISO 8601 expiry timestamp of `registered_as`. | |
| registered_as | No | Set when `register_as` was supplied and the new dataframe was materialized. | |
| row_count_capped | No | True when more rows matched than `row_limit`, so `row_count` is the cap; false means `row_count` is exact. |