Query staged dataframes with SQL
fdic_dataframe_queryRead-onlyIdempotent
Run one read-only SELECT (DuckDB SQL) across the df_ dataframes that fdic_query_financials and fdic_get_deposits staged or an earlier register_as saved; joins, aggregates, window functions, and CTEs work. Before writing SQL, pass each table name to fdic_dataframe_describe to read its columns. DOUBLE columns come back as JSON numbers and dollar columns are thousands of US dollars; BIGINT results such as COUNT(*) come back as strings, so CAST them to INTEGER or DOUBLE for arithmetic. Writes, DDL, file-reading functions, and system catalogs are rejected. register_as materializes the result as a new dataframe with a fresh TTL.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | One SELECT against df_<id> tables named in a dataset field or by fdic_dataframe_describe, up to 20,000 characters. | |
| preview | No | Rows to return inline (0–10,000); defaults to row_limit, and a value above row_limit is treated as row_limit. Set it low when register_as keeps the full result. | |
| row_limit | No | Hard cap on rows materialized (1–10,000). A query matching more stops here and row_count_capped comes back true; use register_as to keep the whole result. | |
| register_as | No | Materialize the full result as a new dataframe under this unused name (df_XXXXX_XXXXX: uppercase letters and digits). A name already staged fails as register_as_clash — including on a repeat of a call that already saved it. The live dataframes share a 1,000,000-row budget: the oldest are dropped to make room, and a result over the budget on its own fails as register_as_too_large. Omit to return rows only. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The cap that bound: preview when lower, else row_limit. | |
| rows | No | Result rows, bounded by preview and row_limit. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Rows returned inline. | |
| notice | No | Guidance when the query returned no rows or a cap withheld some. | |
| columns | No | Columns in projection order. | |
| row_count | No | Rows the query produced, up to row_limit; with register_as, the exact count of the new dataframe. | |
| truncated | No | True when rows were withheld by preview or row_limit. | |
| expires_at | No | When the register_as dataframe is dropped (ISO 8601). | |
| registered_as | No | Name of the dataframe register_as created. | |
| row_count_capped | No | True when the query matched more rows than row_limit, so row_count is that cap. |