Query Eurostat Dataset
eurostat_query_datasetFetch statistical data from a Eurostat dataset with dimension filters. Returns a deterministic inline prefix of decoded observations with dimension codes and labels, numeric values, an OBS_FLAG status (e.g., "p" = provisional, "e" = estimated) and a separate CONF_STATUS confidentiality marker (e.g., "C" = confidential, which is usually why a value is null). preview_limit controls only that prefix; filters and period controls reduce the matched result itself. Call eurostat_get_dataset_info first to discover valid dimension codes and values. Apply filters to keep the result set manageable — large unfiltered queries may trigger an async response error. Use filters.geo for specific country/region codes, or geo_level for NUTS hierarchy filtering (mutually exclusive). Use last_n_periods for the N most recent periods without knowing the end date. Matches above 5,000 observations are staged whole when this deployment runs a dataframe canvas: call eurostat_dataframe_describe first, then eurostat_dataframe_query. Matches at or below 5,000 are never staged. When the target is a whole dataset rather than a slice, eurostat_download_dataset reads the SDMX bulk endpoint instead and is the cheaper route.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language for labels in the response. Default is "EN". Options: "EN", "FR", "DE". | EN |
| filters | No | Dimension filters as a map of dimension code → array of valid values. Example: {"unit": ["CP_MEUR"], "na_item": ["B1GQ"], "geo": ["DE", "FR"]}. An empty array is treated as no filter for that dimension and is dropped from the request. Do not include "geo" here if using geo_level. Invalid dimension values silently return no data — verify with eurostat_get_dimension_values first. | |
| canvas_id | No | Reuse an existing dataframe canvas, so a result staged by this call lands beside earlier ones and can be joined against them. Pass a canvasId from a previous response; omit to start a fresh canvas. Ignored on deployments without a dataframe canvas and when the match is at or below 5,000 observations. | |
| geo_level | No | Filter by NUTS hierarchy level. Mutually exclusive with a "geo" key in filters. Options: "aggregate" (EU/EA totals), "country" (41 member/candidate states), "nuts1" (127 major regions), "nuts2" (309 basic regions), "nuts3" (1,343 small regions). | |
| dataset_code | Yes | Dataset code (e.g., "nama_10_gdp"). Required. | |
| since_period | No | Start of time range (e.g., "2020", "2023-Q1", "2024-01"). Mutually exclusive with last_n_periods. | |
| until_period | No | End of time range (e.g., "2024"). Omit for data through the latest available period. Mutually exclusive with last_n_periods. | |
| preview_limit | No | How many matched observations to return inline, from the deterministic start of the JSON-stat cell order. Default 50; maximum 500. This changes only the inline prefix: it does not reduce obsCount, missingObsCount, timeRange, the upstream response, or the rows staged when the match exceeds 5,000. Use filters or period controls to reduce the match itself. | |
| last_n_periods | No | Return only the N most recent periods. Mutually exclusive with since_period and until_period. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Guidance when preview_limit omits matched rows or the match was staged — distinguishes the inline prefix from filters that reduce the match and, when staged, gives the describe-then-query sequence. Omitted when the preview contains the whole match. | |
| canvasId | No | Dataframe canvas holding the staged result. Pass to eurostat_dataframe_describe, eurostat_dataframe_query, or a later eurostat_query_dataset call. Omitted when nothing was staged. | |
| obsCount | No | Total number of observations matched (before any cap). | |
| tableName | No | Canvas table holding every matched observation in flat form — one code column per dimension plus a "_label" companion, then obs_value, obs_flag, obs_flag_label, conf_status, conf_status_label. Call eurostat_dataframe_describe with canvasId first to confirm the table and columns, then eurostat_dataframe_query. Omitted when nothing was staged: either the match was at or below 5,000 observations, or this deployment runs without a dataframe canvas. | |
| timeRange | No | Time coverage of everything matched — the same set obsCount counts, so it can reach periods absent from observations when truncated is true. Each bound is omitted when neither the match nor Eurostat report it — an omitted bound is unknown, not empty. | |
| truncated | No | True only when the match exceeded the 5,000-observation staging threshold. Independent of preview_limit: observations can be a shorter prefix while truncated is false. When tableName is set, call eurostat_dataframe_describe first and then eurostat_dataframe_query; when it is absent, use filters or period controls to reduce the match. | |
| datasetCode | No | Dataset code as provided. | |
| datasetLabel | No | Human-readable dataset title. | |
| observations | No | The first preview_limit decoded observations in deterministic JSON-stat cell order — the leading combinations of the dataset dimensions, neither a sample nor necessarily the most recent periods. This prefix is independent of the 5,000-observation staging threshold. When tableName is set, the table holds every matched row; otherwise use filters or a period range to reduce the match itself. | |
| appliedFilters | No | Effective query parameters applied to the Eurostat API. | |
| dimensionsUsed | No | Ordered list of dimension codes present in the response (e.g., ["freq", "unit", "na_item", "geo", "time"]). | |
| stagedRowCount | No | Rows written to the canvas table. Matches obsCount. Omitted alongside tableName when nothing was staged. | |
| missingObsCount | No | Number of matched observations carrying no numeric value, counted across everything matched rather than only the returned rows. Covers both unavailable and withheld cells — a slice can be wholly confidential, so this equalling obsCount does not mean the data is absent. |