Oecd Query Dataset
oecd_query_datasetRead-onlyIdempotent
Fetch observations from an OECD dataflow filtered by a dimension key and optional time range. Returns decoded rows (one per observation) with dimension and attribute labels, and values already scaled by the observation unit multiplier. Large multi-country time-series spill to a DataCanvas table — follow up with oecd_dataframe_query; without DataCanvas every row still comes back, but the rendered table stops at a preview slice. Call oecd_get_dataset_info first to learn the dimension order for constructing the key.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Dot-delimited dimension key matching the dimension order from oecd_get_dataset_info. Empty segments are wildcards; "+" separates multiple values per segment. Example: "A.USA+DEU.B1GQ.." — Annual, USA or Germany, GDP, all remaining dimensions. | |
| flow_ref | Yes | Full flow reference — e.g. "OECD.SDD.NAD,DSD_NAAG@DF_NAAG_I", or the bare "OECD.TAD.ARP,DF_AEI2024_DASHBOARD" form for a dataflow published without a datastructure prefix. Obtain from oecd_search_datasets and pass it through unchanged. | |
| canvas_id | No | Canvas ID from a prior oecd_query_dataset call, to stage this result alongside that one. Omit to let the server mint a canvas if this result needs one — a canvas_id comes back only when the result was large enough to spill, never on a result that fits inline. | |
| end_period | No | End of the time range — ISO period code such as "2023" or "2023-Q4". Omit to include up to the latest available period. | |
| start_period | No | Start of the time range — ISO period code such as "2010", "2010-Q1", or "2010-01". Omit to include all history (may produce very large results). |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rows | No | Observation rows. Every row of the result when truncated is absent; the leading preview slice when truncated is true — query the canvas table for the rest. | |
| error | No | Present when the call failed. Absent on success. | |
| source | No | Data source attribution — always "OECD". | |
| canvas_id | No | Canvas handle for the staged result. Present only when DataCanvas is configured and the result exceeded the inline budget; absent when DataCanvas is off, and absent when it is on but the result fit inline. Pass to oecd_dataframe_query or oecd_dataframe_describe. | |
| query_key | No | Dimension key used in this query. | |
| row_count | No | Total rows in the result (or on the canvas when truncated). | |
| truncated | No | True when rows is a preview slice and the full result was staged on DataCanvas; omitted entirely (never false) when rows holds the complete result. Use oecd_dataframe_query with the canvas_id for analytics over the full set. A complete rows never means a complete rendered table — content_table_capped reports that separately. | |
| table_name | No | Canvas table name holding the full result — present when canvas_id is set. | |
| query_flow_ref | No | Flow reference used in this query. | |
| query_end_period | No | End period filter applied in this query, if any. | |
| content_table_rows | No | Rows the rendered table shows when content_table_capped is true. | |
| query_start_period | No | Start period filter applied in this query, if any. | |
| content_table_capped | No | True when the rendered table shows only the leading rows of the result. Distinct from truncated: nothing was staged anywhere, and structuredContent.rows still holds every row. To shrink the result itself, name fewer values per key segment or set a narrower start_period / end_period; to reach the full set as a queryable table instead, run with CANVAS_PROVIDER_TYPE=duckdb and follow up with oecd_dataframe_query. |