Openmeteo Dataframe Query
openmeteo_dataframe_queryRun a read-only SQL SELECT against tables staged on a DataCanvas by openmeteo_get_forecast, openmeteo_get_historical, openmeteo_get_marine, openmeteo_get_air_quality, openmeteo_get_ensemble, openmeteo_get_flood, or openmeteo_get_climate. Pass the canvas_id returned when any of those tools spills (truncated: true), and reference the exact table_name those tools return alongside it. Call openmeteo_dataframe_describe to list staged tables and their columns when you need to discover names. Returns the first limit rows (default 25, or the per-call row cap when that is lower), each whole, plus row_count — exact, or a lower bound flagged by count_error when counting fails or runs past 5 seconds; page the rest with LIMIT / OFFSET. A page's size rests on limit and the columns selected, so from a member-suffixed ensemble table select the columns the question needs rather than SELECT *. One response carries at most 8,000,000 characters of row data (its rows written as JSON, a character that needs escaping counted at its escaped length), and a page over that fails as result_too_large rather than being cut. An error message relayed from the query engine is cut to 2,000 characters.
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": {
"canvas_id": "<canvas_id>",
"sql": "<sql>"
},
"name": "openmeteo_dataframe_query"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | Read-only SELECT statement. Reference table names from openmeteo_dataframe_describe; in the examples below, replace <table_name> with a staged table and <column> with one of its columns. time is ISO 8601 text — YYYY-MM-DDTHH:MM on hourly rows, YYYY-MM-DD on daily rows — as are daily sunrise and sunset, so date functions need a cast: CAST(time AS TIMESTAMP). WHERE time LIKE '%T%' selects the hourly rows of a table that holds both cadences. Monthly means: `SELECT strftime(CAST(time AS TIMESTAMP), '%Y-%m') AS month, AVG(<column>) AS mean FROM <table_name> GROUP BY month ORDER BY month`. An openmeteo_get_ensemble table carries one column per member (precipitation_member01, precipitation_member02, …) beside the unsuffixed control run; count members per row with `SELECT time, list_count(list_filter([*COLUMNS('^precipitation_member\d+$')], lambda x: x > 0.5)) AS members_over, list_count([*COLUMNS('^precipitation_member\d+$')]) AS members_reporting FROM <table_name> ORDER BY time` — the anchored pattern leaves out the control column, and members_reporting is the per-row denominator, since rows past a model's last forecast hour carry no member values. Write lambdas with the lambda x: syntax. | |
| limit | No | Rows to return: the page size. Default 25; a larger value returns at most 10,000 rows and says so. Rows come back whole, so a page's size rests on limit and on the columns the SQL selects: from a member-suffixed ensemble table, select only the columns the question needs. A page over 8,000,000 characters of row data fails as result_too_large rather than being cut. A LIMIT in the SQL still applies; the page holds the smaller of the two. | |
| canvas_id | Yes | Canvas ID returned by openmeteo_get_forecast, openmeteo_get_historical, openmeteo_get_marine, openmeteo_get_air_quality, openmeteo_get_ensemble, openmeteo_get_flood, or openmeteo_get_climate when truncated: true. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rows | No | Leading result rows, at most limit, each whole: values are never cut. When row_count exceeds rows.length, continue by re-issuing the SQL with OFFSET <rows.length>, added to any OFFSET it already applies, with any LIMIT reduced by the same amount. Page under an ORDER BY: without one, DuckDB guarantees no row order between calls. | |
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Present only when limit was above the per-call row cap: names the requested and the applied limit. | |
| canvas_id | No | Canvas ID that was queried. | |
| row_count | No | Exact number of rows in the full result. When count_error is present, the total could not be counted and this is a lower bound: the rows the query confirmed exist. | |
| truncated | No | True when the full result holds more rows than this page, so row_count exceeds rows.length; continue as the rows description says. False when rows is the whole result. | |
| count_error | No | Present only when counting the full result failed after its rows were read — the failure reason (e.g. sql_execution_error, or count_timeout when counting ran past 5 seconds). The rows are still valid; row_count is then a lower bound. |