Imf Query Dataset
imf_query_datasetQuery an IMF SDMX dataflow by dimension key over a time range. Returns observations with time_period, value, and status, plus the unit, scale, and decimals of each series — a key resolving to several series carries one entry per series in series_metadata, since unit and scale differ between them. Requires imf_get_database first to obtain the correct key_format and valid dimension codes. Country codes are ISO 3-letter (USA, GBR, DEU — not US, GB, DE). Key format: dot-separated codes in DSD keyPosition order (e.g. USA.NGDP_RPCH.A for WEO). Every position must carry a code: use + to combine codes (e.g. USA+GBR.NGDP_RPCH.A) and * to match every code at a position (e.g. *.NGDP_RPCH.A for all countries). Codelists from imf_get_database enumerate the code universe, not actual coverage — valid codes can still return no_data if the combination has no series. start_period and end_period must be valid period strings (YYYY, YYYY-SN, YYYY-QN, YYYY-MM, or a calendar-valid YYYY-MM-DD) with start_period no later than end_period; malformed or reversed ranges are rejected. A bound covers the whole period it names, so end_period 2023 includes 2023-M12 and 2023-Q4. Large analytical result sets (multi-country, long time range) spill to DataCanvas; call imf_dataframe_describe first to inspect staged tables and columns, then imf_dataframe_query for SQL analysis.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Dot-separated dimension codes in DSD keyPosition order. Call imf_get_database to get key_format and valid codes first. Use + to combine codes at one position (e.g. USA+GBR.NGDP_RPCH.A). Use * to match every code at a position — *.NGDP_RPCH.A returns the indicator for all countries, and CAN.*.A every indicator for Canada. Every position needs a code or a *; an empty segment (USA..A) is rejected. Country codes are ISO 3-letter: USA not US, GBR not GB, DEU not DE. | |
| version | No | Dataflow version. Auto-detected from dataflow list when omitted. | |
| agency_id | No | Agency ID, e.g. IMF.RES or IMF.STA. Auto-detected from dataflow list when omitted. | |
| canvas_id | No | Existing canvas ID to accumulate results into across multiple queries. This selects the destination only; it does not force staging. Use output_mode="canvas" to stage an under-budget result. | |
| end_period | No | End of time range (inclusive). Same formats as start_period, and must not be earlier than it. The bound covers the whole period it names, so end_period 2023 admits 2023-M12 and 2023-Q4. Observations after this period are excluded from the result. | |
| dataflow_id | Yes | Dataflow identifier from imf_list_databases, e.g. WEO, BOP, CPI. | |
| output_mode | No | Result placement. auto returns an under-budget result inline and spills only when needed. canvas explicitly stages the full result, using canvas_id when supplied or allocating a fresh canvas. | auto |
| start_period | No | Start of time range (inclusive). Accepts any of YYYY (annual), YYYY-SN (semi-annual, e.g. 2023-S1), YYYY-QN (quarterly, e.g. 2023-Q1), YYYY-MM (monthly), or a calendar-valid YYYY-MM-DD (daily), whatever the dataflow's frequency. The bound covers the whole period it names, so start_period 2023 admits 2023-M01 and 2023-Q1. Observations before this period are excluded from the result. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Dimension key used in the query, e.g. USA.NGDP_RPCH.A. | |
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Populated when a period bound was set but some observations carry a time_period label the range filter does not recognize. Composes with staged retrieval_guidance when both apply. | |
| source | No | Attribution string required by IMF data terms: "Source: International Monetary Fund, <dataflow name>, <link>". | |
| staged | No | True when the complete observation set is stored on DataCanvas. canvas_id and table_name are present whenever true. | |
| canvas_id | No | DataCanvas session ID — present when staged=true. Pass first to imf_dataframe_describe, then to imf_dataframe_query. | |
| truncated | No | True only when observations is an incomplete preview of observation_count. A result can be staged=true and truncated=false when every observation also fits inline. | |
| end_period | No | Latest period covered; absent when the full available range was used. | |
| table_name | No | DuckDB table name on the canvas — present when staged=true; reference in SQL via FROM <table_name>. | |
| dataflow_id | No | Dataflow identifier that was queried, e.g. WEO. | |
| observations | No | Inline observation preview. For staged results this may contain the full set or a budget-limited prefix; observation_count remains the full count. | |
| start_period | No | Earliest period covered; absent when the full available range was used. | |
| series_metadata | No | Per-series attributes, one entry per distinct series_key in the result. Present only when the query resolved to more than one series; a single-series query carries its values in series_attributes instead. Unit and scale differ across series in one query — WEO NGDPD is USD at scale 9 while NGDP_RPCH is PT unscaled — so interpret each series against its own entry. | |
| observation_count | No | Total observations in the result. | |
| series_attributes | No | Attributes of the first series in the result — the same series as series_metadata[0]. A key with + or * resolves to several series whose scale and unit differ, and this field describes only the first of them: read series_metadata for the rest, and never apply these values to another series_key. | |
| retrieval_guidance | No | Present on every staged result. Identifies the imf_dataframe_describe-before-imf_dataframe_query retrieval workflow. |