eurostat-mcp-server

Search the Eurostat catalogue by keyword. Returns matching datasets with codes, descriptions, period coverage, and theme breadcrumbs. Use this to discover dataset codes before calling eurostat_get_dataset_info, then eurostat_query_dataset for a slice of a dataset or eurostat_download_dataset for the whole of one. Results are limited to datasets and predefined tables — folders are excluded. The catalogue joins two sources: the dissemination table of contents, and the Comext host's dataflow list, which adds the DS-* collections — detailed trade by CN8, HS, SITC, BEC and CPA, and PRODCOM — filed under "International trade in goods - detailed data (Comext)" and "Statistics on the production of manufactured goods (PRODCOM)". Comext entries report a last-update date but no period coverage or observation count. A collection on neither list, such as the legacy PRODCOM DS-056120, is not disseminated and cannot be reached through this server.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "pattern": "\\S",
      "description": "Search terms — at least one non-whitespace token is required. Split on whitespace into tokens; every token must match (AND), case-insensitively, somewhere across the dataset label, theme breadcrumb, or code. Word order does not matter, so \"business demography NUTS 3\" or \"regional economic accounts\" resolve without naming a label verbatim."
    },
    "limit": {
      "default": 20,
      "description": "Page size — maximum datasets returned per page (1–100). Default is 20. To retrieve matches beyond one page, pass the returned nextCursor back as cursor; the page size is fixed by this first call.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "description": "Opaque pagination cursor from a previous call's nextCursor. Omit for the first page; pass it back — with the same query — to fetch the next page of matches over a stable order. A cursor is bound to the query that produced it and to the catalogue snapshot in effect at that time, so reusing one with a different query, or after the catalogue refreshes, is rejected rather than silently paging a different result set.",
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "datasets": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Dataset code (e.g., \"nama_10_gdp\"). Use this in eurostat_get_dataset_info, eurostat_query_dataset, and eurostat_download_dataset."
          },
          "label": {
            "type": "string",
            "description": "Human-readable dataset title."
          },
          "type": {
            "type": "string",
            "enum": [
              "dataset",
              "table"
            ],
            "description": "Entry type: \"dataset\" for standard datasets, \"table\" for predefined tables."
          },
          "dataStart": {
            "description": "Earliest data period available (e.g., \"1975\"). Omitted when not reported by Eurostat.",
            "type": "string"
          },
          "dataEnd": {
            "description": "Most recent data period available (e.g., \"2025\"). Omitted when not reported by Eurostat.",
            "type": "string"
          },
          "lastUpdated": {
            "description": "Date of last data update (e.g., \"22.05.2026\"). Omitted when not reported.",
            "type": "string"
          },
          "obsCount": {
            "description": "Approximate number of observations. Omitted when not reported by Eurostat.",
            "type": "number"
          },
          "themePath": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Breadcrumb path from root theme to this dataset (e.g., [\"Database by themes\", \"Economy and finance\"]). Eurostat files some datasets under several branches; this is the first branch that matched the query. Empty for top-level entries."
          }
        },
        "required": [
          "code",
          "label",
          "type",
          "themePath"
        ],
        "additionalProperties": false,
        "description": "A matched dataset entry."
      },
      "description": "Matching datasets for the current page, up to the requested limit."
    },
    "nextStep": {
      "description": "Suggested next action based on these results. Populated when there is a clear follow-up call.",
      "type": "string"
    },
    "query": {
      "type": "string",
      "description": "Search terms as submitted."
    },
    "totalMatches": {
      "type": "number",
      "description": "Total distinct dataset codes matching the query across all pages, before the page limit."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when more matches remain beyond this page — pass nextCursor as cursor to fetch them."
    },
    "nextCursor": {
      "description": "Opaque cursor for the next page of matches. Pass it back as cursor with the same query; it stops working once the catalogue refreshes. Omitted on the last page.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `no_match`: No datasets matched the query string — including a query naming a DS-* code that neither the dissemination table of contents nor the Comext dataflow list carries, which is a collection Eurostat does not disseminate. `invalid_cursor`: The cursor is malformed, came from a different query, or came from a catalogue snapshot that has since refreshed. Other values are possible when a failure originates below the handler.",
              "examples": [
                "no_match",
                "invalid_cursor"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "datasets",
        "query",
        "totalMatches",
        "truncated"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Navigate the Eurostat theme tree. Without theme_code returns the top-level theme folders (Economy, Population, Transport, etc.) — the practical starting points. With a theme_code returns its immediate children: subtheme folders and datasets in that branch. Use this for structured discovery when you know the domain but not the dataset code, or to drill down from a broad topic to a specific dataset. Pair with eurostat_search_datasets for keyword-based discovery. The tree is the dissemination table of contents plus the Comext host's DS-* collections: detailed trade under ext_go_detail (inside ext_go, "International trade in goods") and PRODCOM under prom (inside icts, "Industry, trade and services"). A collection on neither, such as the legacy PRODCOM DS-056120, is not disseminated and appears nowhere in the tree.

{
  "type": "object",
  "properties": {
    "theme_code": {
      "description": "Folder code to expand (e.g., \"economy\", \"reg\"). Omit to list the top-level theme folders.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Theme or dataset code. Pass to theme_code to drill into a folder, or use as dataset_code for data tools."
          },
          "label": {
            "type": "string",
            "description": "Human-readable name."
          },
          "type": {
            "type": "string",
            "enum": [
              "folder",
              "dataset",
              "table"
            ],
            "description": "Item type: \"folder\" has sub-items; \"dataset\"/\"table\" can be queried for data."
          },
          "hasChildren": {
            "type": "boolean",
            "description": "True when this folder contains sub-items. Only meaningful for type \"folder\"."
          },
          "dataStart": {
            "description": "Earliest data period (e.g., \"1995\"). Omitted for folders and when not reported.",
            "type": "string"
          },
          "dataEnd": {
            "description": "Most recent data period. Omitted for folders and when not reported.",
            "type": "string"
          },
          "obsCount": {
            "description": "Approximate observation count. Omitted for folders and when not reported.",
            "type": "number"
          }
        },
        "required": [
          "code",
          "label",
          "type",
          "hasChildren"
        ],
        "additionalProperties": false,
        "description": "A theme folder, dataset, or table entry."
      },
      "description": "Immediate children of the requested theme, or the root themes if theme_code was omitted."
    },
    "parentPath": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Breadcrumb from root to the requested theme (e.g., [\"Database by themes\", \"Economy and finance\"]). Empty when browsing root."
    },
    "otherPlacements": {
      "description": "Breadcrumbs of the other branches that file this same theme_code. Eurostat lists a few folder codes in more than one branch; the items above come from the first one the catalogue lists, which never has fewer children than the branches named here but can list different ones. theme_code takes a bare code, so those branches cannot be addressed directly — browse down to them from the root instead. Omitted when the code has a single placement — the normal case.",
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Breadcrumb from root to one other folder carrying the requested code."
      }
    },
    "nextStep": {
      "description": "Suggested next action based on these results. Populated when there is a clear follow-up call.",
      "type": "string"
    },
    "itemCount": {
      "type": "number",
      "description": "Number of items returned in this level."
    },
    "themeCode": {
      "description": "Folder code that was browsed, or omitted for root.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: The provided theme_code does not exist in the TOC. `not_a_folder`: The provided theme_code identifies a dataset or table entry instead of a folder. Other values are possible when a failure originates below the handler.",
              "examples": [
                "not_found",
                "not_a_folder"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "items",
        "parentPath",
        "itemCount"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch metadata for a Eurostat dataset: dimensions with valid values, time range, observation count, and last-update date. Call this before eurostat_query_dataset or eurostat_download_dataset to discover what dimension codes are valid (unit, na_item, geo, etc.); eurostat_download_dataset builds its positional filter key from this dimension list, so a filter naming a dimension absent here is rejected outright. Returns up to 10 sample values per dimension for orientation; use eurostat_get_dimension_values to list the full set for large dimensions. A DS-* code (detailed trade and PRODCOM, in any case) is read from the Comext dissemination host, which reports no period coverage or observation count, so timeRange and obsCount come back unreported; the first call on a large Comext collection downloads its full structure (23 MB for DS-045409) and takes longer, and repeat calls within the hour reuse it.

{
  "type": "object",
  "properties": {
    "dataset_code": {
      "type": "string",
      "minLength": 1,
      "description": "Dataset code (e.g., \"nama_10_gdp\", or \"DS-045409\" for a Comext collection). Use eurostat_search_datasets or eurostat_browse_themes to find codes."
    }
  },
  "required": [
    "dataset_code"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Dataset code as provided."
    },
    "label": {
      "type": "string",
      "description": "Human-readable dataset title."
    },
    "dimensions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Dimension code (e.g., \"unit\", \"geo\", \"na_item\"). Use these as filter keys in eurostat_query_dataset and eurostat_download_dataset."
          },
          "label": {
            "type": "string",
            "description": "Human-readable dimension name (e.g., \"Unit of measure\")."
          },
          "valuesCount": {
            "description": "Number of dataset-available values in this dimension, taken from the dataset content constraint. For \"time\" this is the full period count. Omitted only when Eurostat does not supply a measurable value set.",
            "type": "number"
          },
          "sampleValues": {
            "description": "First 10 dataset-available values for orientation. Use eurostat_get_dimension_values for the full constrained list. Omitted alongside valuesCount when Eurostat does not supply a measurable value set.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "description": "Dimension value code."
                },
                "label": {
                  "type": "string",
                  "description": "Human-readable label for this value."
                }
              },
              "required": [
                "code",
                "label"
              ],
              "additionalProperties": false,
              "description": "A dimension value code and label pair."
            }
          }
        },
        "required": [
          "code",
          "label"
        ],
        "additionalProperties": false,
        "description": "A dataset dimension with its valid values."
      },
      "description": "All dimensions of the dataset with their valid codes and labels."
    },
    "timeRange": {
      "type": "object",
      "properties": {
        "start": {
          "description": "Earliest available period (e.g., \"1975\"). Omitted when Eurostat does not report it.",
          "type": "string"
        },
        "end": {
          "description": "Most recent available period (e.g., \"2024\"). Omitted when Eurostat does not report it.",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "description": "Overall data coverage period for this dataset. Each bound is omitted when Eurostat does not report it — an omitted bound is unknown, not empty."
    },
    "obsCount": {
      "description": "Total number of observations in the full dataset (all periods). Omitted when Eurostat does not report it — an omitted count is unknown, not zero.",
      "type": "number"
    },
    "lastUpdated": {
      "description": "ISO 8601 timestamp of the most recent data update. Omitted when Eurostat does not report it.",
      "type": "string"
    },
    "metadataUrl": {
      "description": "URL to the ESMS HTML metadata page for this dataset. Omitted when not provided by Eurostat.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: The dataset code does not exist or is not available for dissemination. `upstream_fault`: Eurostat returned a dataset structure or content constraint this server cannot read: malformed, truncated, not XML, or missing the requested dataset's dataflow. Other values are possible when a failure originates below the handler.",
              "examples": [
                "not_found",
                "upstream_fault"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "code",
        "label",
        "dimensions",
        "timeRange"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

List the valid values for a specific dimension in a Eurostat dataset (e.g., all unit codes for nama_10_gdp, all geo codes for a regional dataset). Use this when eurostat_get_dataset_info returns more values than the 10-item sample, or to confirm exact codes before querying. For the "geo" dimension, use geo_level to filter by NUTS hierarchy (country, nuts1, nuts2, nuts3). An invalid code matches nothing: eurostat_query_dataset names it in unmatchedValues, or in its no_results error when the query matched nothing at all, and Eurostat rejects it as a fault on eurostat_download_dataset; use this tool to verify codes first. At most 2,000 values come back inline — a longer list, such as the 37,069 CN8 product codes of DS-045409 or a daily time dimension, is cut there and says so. Pass canvas_id to also stage the whole list, whatever its length, as a two-column code/label table on that dataframe canvas: search it with SQL, or join it to a eurostat_download_dataset table, whose columns carry dimension codes only.

{
  "type": "object",
  "properties": {
    "dataset_code": {
      "type": "string",
      "minLength": 1,
      "description": "Dataset code (e.g., \"nama_10_gdp\", or \"DS-045409\" for a Comext collection)."
    },
    "dimension": {
      "type": "string",
      "minLength": 1,
      "description": "Dimension code to retrieve values for (e.g., \"unit\", \"na_item\", \"geo\"). Use eurostat_get_dataset_info to see available dimensions."
    },
    "geo_level": {
      "description": "NUTS hierarchy level filter — applies only when dimension is \"geo\"; passing it with any other dimension is rejected. Options: \"aggregate\" (EU/EA codes), \"country\" (2-letter codes, default), \"nuts1\" (3-char), \"nuts2\" (4-char), \"nuts3\" (5-char).",
      "type": "string",
      "enum": [
        "aggregate",
        "country",
        "nuts1",
        "nuts2",
        "nuts3"
      ]
    },
    "canvas_id": {
      "description": "Also stage the values on this dataframe canvas as a table with two columns, code and label, holding every value the dimension lists — past the inline cap too — at the geo_level requested, country when it is omitted. Pass the canvasId a eurostat_download_dataset or eurostat_query_dataset response returned, then search the staged table with SQL or join it to a download on the dimension column (e.g., d.geo = g.code). Omit to return the values inline only: this tool never starts a canvas. Ignored on deployments without a dataframe canvas.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "required": [
    "dataset_code",
    "dimension"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "dimensionCode": {
      "type": "string",
      "description": "The dimension code that was queried."
    },
    "dimensionLabel": {
      "type": "string",
      "description": "Human-readable dimension name."
    },
    "geoLevel": {
      "description": "Effective NUTS hierarchy level for the geo value set. Present only for the geo dimension; country is reported when geo_level was omitted.",
      "type": "string",
      "enum": [
        "aggregate",
        "country",
        "nuts1",
        "nuts2",
        "nuts3"
      ]
    },
    "values": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Dimension value code. Use these as filter values in eurostat_query_dataset and eurostat_download_dataset."
          },
          "label": {
            "type": "string",
            "description": "Human-readable label for this value."
          }
        },
        "required": [
          "code",
          "label"
        ],
        "additionalProperties": false,
        "description": "A dimension value code and label pair."
      },
      "description": "Dataset-available values for this dimension, in Eurostat's order — for geo, the subset at geoLevel. Holds every value up to 2,000; past that, the first 2,000, with truncated set and the whole list on the canvas table when canvas_id was passed."
    },
    "totalCount": {
      "type": "number",
      "description": "Number of distinct values the dimension lists, after geoLevel filtering for geo — all of them, including any past the inline cap."
    },
    "canvasId": {
      "description": "Dataframe canvas the values were staged on — the canvas_id supplied. Omitted when nothing was staged: canvas_id was omitted, this deployment runs without a dataframe canvas, or the dimension lists no values.",
      "type": "string"
    },
    "tableName": {
      "description": "Canvas table holding every value as two VARCHAR columns, code and label. Call eurostat_dataframe_describe with canvasId first to confirm it, then join it in eurostat_dataframe_query. Omitted alongside canvasId.",
      "type": "string"
    },
    "stagedRowCount": {
      "description": "Rows written to the canvas table. Equals totalCount. Omitted alongside tableName.",
      "type": "number"
    },
    "truncated": {
      "description": "True when the dimension lists more values than the inline cap and values holds only the first of them. Omitted when values holds every one.",
      "type": "boolean"
    },
    "shown": {
      "description": "Values returned inline. Present alongside truncated.",
      "type": "number"
    },
    "cap": {
      "description": "The inline cap applied. Present alongside truncated.",
      "type": "number"
    },
    "notice": {
      "description": "Where the values past the inline cap are: the staged table when canvas_id was passed, or how to stage them. Present alongside truncated.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: The dataset code or dimension code does not exist. `no_results`: The dataset has no geo values at the effective geo_level. `conflicting_params`: geo_level was combined with a dimension other than \"geo\", where it has no effect. `upstream_fault`: Eurostat returned a dataset structure or content constraint this server cannot read: malformed, truncated, not XML, or missing the requested dataset's dataflow. `canvas_not_found`: A canvas_id was supplied for staging but is unknown or its lifetime has elapsed. Other values are possible when a failure originates below the handler.",
              "examples": [
                "not_found",
                "no_results",
                "conflicting_params",
                "upstream_fault",
                "canvas_not_found"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "dimensionCode",
        "dimensionLabel",
        "values",
        "totalCount"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch 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.

{
  "type": "object",
  "properties": {
    "dataset_code": {
      "type": "string",
      "minLength": 1,
      "description": "Dataset code (e.g., \"nama_10_gdp\"). Required. A DS-* code — Comext detailed trade or PRODCOM, in any case — is served by the Comext host: filter freq on its trade flows, which mix annual and monthly series, and note that product, reporter and partner carry aggregates (TOTAL, EU27_2020) that double-count when summed with their members."
    },
    "filters": {
      "default": {},
      "description": "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. Dimension codes match in any case (\"GEO\" is geo). Do not include \"geo\" here if using geo_level. A value that matches nothing contributes no rows rather than an error; the response names it in unmatchedValues, or in the no_results error when nothing matched at all. eurostat_get_dimension_values lists the valid values.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "geo_level": {
      "description": "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).",
      "type": "string",
      "enum": [
        "aggregate",
        "country",
        "nuts1",
        "nuts2",
        "nuts3"
      ]
    },
    "since_period": {
      "description": "Start of the time range, inclusive. Accepted forms: YYYY, YYYY-MM, YYYY-MM-DD, YYYY-Qn (1–4), YYYY-Sn (1–2), YYYY-Tn (1–3), YYYY-Mnn (01–12), YYYY-Wnn (a week the year has, up to 53) or YYYY-Dnnn (a day the year has, up to 366) (e.g., \"2020\", \"2023-Q1\", \"2024-01\"). Extra leading zeros after the letter are dropped (\"2020-Q01\" is sent as \"2020-Q1\"), a day of the year is sent as three digits (\"2026-D1\" as \"2026-D001\"), and YYYY-A1 is sent as YYYY. A period of another frequency is mapped onto the dataset's own, so \"2020-01\" works on annual data. A malformed or non-existent period (e.g., \"2020-13\") is rejected as invalid_period. Mutually exclusive with last_n_periods.",
      "type": "string"
    },
    "until_period": {
      "description": "End of the time range, inclusive (e.g., \"2024\"), in the same forms as since_period. Omit for data through the latest available period. The range must hold at least one day: a since_period that starts after until_period ends is rejected as invalid_period, while pairs of different frequencies are fine (\"2020-06\" to \"2020\"). Mutually exclusive with last_n_periods.",
      "type": "string"
    },
    "last_n_periods": {
      "description": "Return only the N most recent periods. N counts back from the dataset's latest period, not from the latest period published for this slice, so a slice that lags the rest of the dataset can come back empty — raise N, or use until_period ending at a period the slice has published. Mutually exclusive with since_period and until_period.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "preview_limit": {
      "default": 50,
      "description": "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "lang": {
      "default": "EN",
      "description": "Language for labels in the response. Default is \"EN\". Options: \"EN\", \"FR\", \"DE\".",
      "type": "string",
      "enum": [
        "EN",
        "FR",
        "DE"
      ]
    },
    "canvas_id": {
      "description": "Reuse an existing dataframe canvas, so a result staged by this call lands beside earlier ones and can be joined against them. Pass the canvasId a previous eurostat_query_dataset or eurostat_download_dataset response returned; omit to start a fresh canvas. Ignored on deployments without a dataframe canvas and when the match is at or below 5,000 observations.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "required": [
    "dataset_code"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "datasetCode": {
      "type": "string",
      "description": "Dataset code as provided."
    },
    "datasetLabel": {
      "type": "string",
      "description": "Human-readable dataset title."
    },
    "dimensionsUsed": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Ordered list of dimension codes present in the response (e.g., [\"freq\", \"unit\", \"na_item\", \"geo\", \"time\"])."
    },
    "observations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "dimensions": {
            "type": "object",
            "properties": {},
            "additionalProperties": {},
            "description": "Map of dimension code → {code, label}. One entry per dimension in dimensionsUsed, keyed by dimension code (e.g., {\"geo\": {\"code\": \"DE\", \"label\": \"Germany\"}, \"time\": {\"code\": \"2023\", \"label\": \"2023\"}})."
          },
          "value": {
            "description": "Numeric observation value, or null when Eurostat reports none — unavailable in the source data, withheld (confStatus says so), or published as text (valueText holds it).",
            "type": [
              "number",
              "null"
            ]
          },
          "valueText": {
            "description": "A value Eurostat published as text rather than a number, verbatim — PRODCOM (DS-*) flag and unit indicators such as QNTUNIT publish a unit like \"KG\" — with value null. PRODCOM's \":C\" is decoded to confStatus \"C\" instead. Omitted for numeric and missing values.",
            "type": "string"
          },
          "status": {
            "description": "Eurostat OBS_FLAG for this observation. Omitted for unflagged observations, and never carries a confidentiality code — that arrives in confStatus.",
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "OBS_FLAG code (e.g., \"p\", \"e\", \"d\")."
              },
              "label": {
                "type": "string",
                "description": "Status description (e.g., \"provisional\", \"estimated\", \"definition differs\")."
              }
            },
            "required": [
              "code",
              "label"
            ],
            "additionalProperties": false
          },
          "confStatus": {
            "description": "Eurostat CONF_STATUS for this observation — a different codelist from status. Present when Eurostat restricts the cell, which is usually why value is null. Omitted otherwise.",
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "CONF_STATUS code: \"C\", \"N\", or \"P\"."
              },
              "label": {
                "type": "string",
                "description": "Confidentiality description (e.g., \"confidential\", \"not for publication\")."
              }
            },
            "required": [
              "code",
              "label"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "dimensions",
          "value"
        ],
        "additionalProperties": false,
        "description": "A single decoded observation with dimension values, numeric value, and the optional OBS_FLAG and CONF_STATUS markers."
      },
      "description": "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."
    },
    "obsCount": {
      "type": "number",
      "description": "Total number of observations matched (before any cap)."
    },
    "truncated": {
      "type": "boolean",
      "description": "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."
    },
    "canvasId": {
      "description": "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.",
      "type": "string"
    },
    "tableName": {
      "description": "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. A DS-* table also carries obs_value_text, the valueText of each row. 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.",
      "type": "string"
    },
    "stagedRowCount": {
      "description": "Rows written to the canvas table. Matches obsCount. Omitted alongside tableName when nothing was staged.",
      "type": "number"
    },
    "timeRange": {
      "type": "object",
      "properties": {
        "start": {
          "description": "Earliest period matched. Omitted when the match carries no time dimension and Eurostat reports no overall period.",
          "type": "string"
        },
        "end": {
          "description": "Most recent period matched. Omitted when the match carries no time dimension and Eurostat reports no overall period.",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "description": "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."
    },
    "missingObsCount": {
      "type": "number",
      "description": "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."
    },
    "unmatchedValues": {
      "description": "Filter values that matched nothing in the dataset, keyed by dimension code and spelled as sent (matching ignores case). The observations cover only the values that did match. Omitted when every filter value matched.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "appliedFilters": {
      "type": "object",
      "properties": {
        "filters": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "description": "Dimension filters actually sent to Eurostat. Empty arrays from the request are dropped and do not appear here."
        },
        "geoLevel": {
          "description": "NUTS geo level filter applied, if any.",
          "type": "string"
        },
        "sincePeriod": {
          "description": "Start of time range applied, if any.",
          "type": "string"
        },
        "untilPeriod": {
          "description": "End of time range applied, if any.",
          "type": "string"
        },
        "lastNPeriods": {
          "description": "Last N periods filter applied, if any.",
          "type": "number"
        }
      },
      "required": [
        "filters"
      ],
      "additionalProperties": false,
      "description": "Effective query parameters applied to the Eurostat API."
    },
    "notice": {
      "description": "Guidance when a filter value matched nothing, when preview_limit omits matched rows, or when the match was staged — names the unmatched values, distinguishes the inline prefix from filters that reduce the match and, when staged, gives the describe-then-query sequence. Omitted when every filter value matched and the preview contains the whole match.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: The dataset code does not exist (HTTP 404 carrying Eurostat error id 100). `no_results`: The query matched no observation cells — including Eurostat HTTP-200 error id 100. The dataset is valid, but no cell carries a value or a status flag for that filter combination and period range. When Eurostat returns the empty table, the error names the filter values that matched nothing (data.unmatchedValues) and the selected periods that carry no value (data.matchedPeriods, the newest 24, with data.matchedPeriodCount counting all of them). `invalid_period`: since_period or until_period is not a period literal, or names a month, quarter, semester, trimester, week or day that does not exist, or since_period starts after until_period ends. Checked before any request; a period Eurostat itself rejects maps here too. `async_response`: Eurostat returned an async warning or an HTTP-413 error array — the query matched too many observations, including an EXTRACTION_TOO_BIG refusal past Eurostat's 5,000,000-row limit. `invalid_dimension`: A dimension code in filters does not exist in this dataset (HTTP 400, Eurostat error id 150). `conflicting_params`: Mutually exclusive parameters were combined: \"geo\" filter + geo_level, or since_period/until_period + last_n_periods. `canvas_not_found`: A canvas_id was supplied for staging but is unknown or its lifetime has elapsed. Other values are possible when a failure originates below the handler.",
              "examples": [
                "not_found",
                "no_results",
                "invalid_period",
                "async_response",
                "invalid_dimension",
                "conflicting_params",
                "canvas_not_found"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "datasetCode",
        "datasetLabel",
        "dimensionsUsed",
        "observations",
        "obsCount",
        "truncated",
        "timeRange",
        "missingObsCount",
        "appliedFilters"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Download a Eurostat dataset in bulk through the SDMX 2.1 TSV endpoint and stage every observation as a SQL table on the dataframe canvas — the route to a whole dataset, where eurostat_query_dataset is the route to a slice of one. The TSV wire format is roughly half the bytes of the JSON-stat body eurostat_query_dataset reads, so it reaches datasets that would otherwise time out, and it is expanded here into one row per observation. Filters take the same dimension-code map eurostat_query_dataset uses and are applied server-side by Eurostat; call eurostat_get_dataset_info first for the dimension codes and eurostat_get_dimension_values for their values. Narrow with since_period/until_period rather than asking for the most recent N periods — the TSV layout keeps a column for every period whichever is requested, so a period range is what actually shrinks the response. Transfers are bounded by a byte budget enforced while streaming: when it is spent the download stops and budgetExceeded is set, leaving a prefix of the dataset rather than an error. Only preview_limit rows come back inline. When a table is staged, call eurostat_dataframe_describe first to confirm its columns, then eurostat_dataframe_query; without a canvas, rows past the preview are not retained.

{
  "type": "object",
  "properties": {
    "dataset_code": {
      "type": "string",
      "minLength": 1,
      "description": "Dataset code (e.g., \"nama_10_gdp\"). Required. A DS-* code — Comext detailed trade or PRODCOM, in any case — is served by the Comext host, which refuses an unfiltered download of its large collections as extraction_too_big: filter it, including freq on the trade flows, which mix annual and monthly series."
    },
    "filters": {
      "default": {},
      "description": "Dimension filters as a map of dimension code → array of accepted values, applied by Eurostat before the body is sent. Example: {\"unit\": [\"CP_MEUR\"], \"na_item\": [\"B1G\"], \"geo\": [\"DE\", \"FR\"]}. Omit a dimension or pass an empty array to accept every value for it. Dimension codes match in any case (\"GEO\" is geo). Do not put \"time\" here — use since_period/until_period. Naming a dimension the dataset does not have is rejected with the dataset's dimension list rather than silently ignored.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "since_period": {
      "description": "Start of the period range, inclusive, sent as startPeriod. Accepted forms: YYYY, YYYY-MM, YYYY-MM-DD, YYYY-Qn (1–4), YYYY-Sn (1–2), YYYY-Tn (1–3), YYYY-Mnn (01–12), YYYY-Wnn (a week the year has, up to 53) or YYYY-Dnnn (a day the year has, up to 366) (e.g., \"2020\", \"2023-Q1\", \"2024-01\"). Extra leading zeros after the letter are dropped (\"2020-W001\" is sent as \"2020-W01\"), a day of the year is sent as three digits (\"2026-D1\" as \"2026-D001\"), YYYY-A1 is sent as YYYY, and a period of another frequency is mapped onto the dataset's own. A malformed or non-existent period (e.g., \"2020-13\") is rejected as invalid_period. The most effective way to shrink a bulk response: it removes period columns from the TSV rather than blanking their cells.",
      "type": "string"
    },
    "until_period": {
      "description": "End of the period range, inclusive (e.g., \"2024\"), sent as endPeriod, in the same forms as since_period. Omit for data through the latest available period. The range must hold at least one day: a since_period that starts after until_period ends is rejected as invalid_period, while pairs of different frequencies are fine (\"2020-06\" to \"2020\").",
      "type": "string"
    },
    "preview_limit": {
      "default": 50,
      "description": "How many observations to echo inline, from the start of the download. Caps at 500. The full download is on the canvas table when one was staged; this is orientation, not the result set.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "canvas_id": {
      "description": "Reuse an existing dataframe canvas so this download lands beside earlier results and can be joined against them. Pass the canvasId a previous eurostat_download_dataset or eurostat_query_dataset response returned; omit to start a fresh canvas. Ignored on deployments without a dataframe canvas. A download that carries no observations fails as no_results and leaves the canvas untouched.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "required": [
    "dataset_code"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "datasetCode": {
      "type": "string",
      "description": "Dataset code as provided."
    },
    "dimensionsUsed": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Dimension codes carried by the downloaded rows, in the order Eurostat keys them (e.g., [\"freq\", \"unit\", \"na_item\", \"geo\"]). Read from the TSV header, so it reflects the response rather than metadata. The period lives in the separate \"time\" column."
    },
    "rowCount": {
      "type": "number",
      "description": "Observations expanded from the download — one per populated cell, counting those Eurostat reports as unavailable."
    },
    "missingCount": {
      "type": "number",
      "description": "Downloaded observations carrying no numeric value (obs_value is null)."
    },
    "periodRange": {
      "type": "object",
      "properties": {
        "start": {
          "description": "Earliest period carrying an observation. Omitted when nothing was downloaded.",
          "type": "string"
        },
        "end": {
          "description": "Latest period carrying an observation. Omitted when nothing was downloaded.",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "description": "Period coverage of the rows actually downloaded. Narrower than the dataset when budgetExceeded is true or a period range was applied."
    },
    "bytesRead": {
      "type": "number",
      "description": "Decoded TSV bytes read from Eurostat — after gzip decompression when the body arrived compressed, so it measures the payload rather than the wire."
    },
    "compressed": {
      "type": "boolean",
      "description": "True when Eurostat sent the body gzip-compressed. It does so without a Content-Encoding header on large responses, so this reports what the stream actually carried."
    },
    "budgetExceeded": {
      "type": "boolean",
      "description": "True when the byte budget stopped the transfer before the dataset ended, making the rows a prefix rather than the whole thing. Narrow with filters or a period range, or raise EUROSTAT_BULK_MAX_BYTES."
    },
    "observations": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": [
            "string",
            "number",
            "null"
          ]
        },
        "description": "One observation as a flat row: one column per dimension holding its code, \"time\" for the period, then obs_value, obs_flag, obs_flag_label, conf_status, conf_status_label. A label column is null when Eurostat publishes no label for that code. Rows of a DS-* dataset also carry obs_value_text after obs_value: a value Eurostat published as text, such as a PRODCOM quantity unit (\"KG\"), kept verbatim with obs_value null; a PRODCOM \":C\" arrives as conf_status \"C\" instead."
      },
      "description": "The first preview_limit observations of the download, in the order Eurostat streamed them. A prefix of the staged table, not a sample."
    },
    "canvasId": {
      "description": "Dataframe canvas holding the staged download. Pass to eurostat_dataframe_describe, eurostat_dataframe_query, or a later staging call. Omitted when nothing was staged.",
      "type": "string"
    },
    "tableName": {
      "description": "Canvas table holding every downloaded observation. Call eurostat_dataframe_describe with canvasId first to confirm the table and columns, then eurostat_dataframe_query. Omitted when this deployment runs without a dataframe canvas, in which case only the inline preview survives the call.",
      "type": "string"
    },
    "stagedRowCount": {
      "description": "Rows written to the canvas table. Matches rowCount. Omitted alongside tableName.",
      "type": "number"
    },
    "totalCount": {
      "type": "number",
      "description": "Observations the download produced — equal to rowCount. The inline observations array holds only the first preview_limit of them; budgetExceeded, not this count, says whether the download is the whole dataset."
    },
    "appliedQuery": {
      "type": "object",
      "properties": {
        "filters": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "description": "Dimension filters sent to Eurostat. Empty arrays are dropped."
        },
        "sincePeriod": {
          "description": "startPeriod applied, if any.",
          "type": "string"
        },
        "untilPeriod": {
          "description": "endPeriod applied, if any.",
          "type": "string"
        },
        "url": {
          "type": "string",
          "description": "The SDMX request URL, so the download can be reproduced."
        }
      },
      "required": [
        "filters",
        "url"
      ],
      "additionalProperties": false,
      "description": "The bulk request as the server built it."
    },
    "notice": {
      "description": "Guidance on every download: the staged table with the required eurostat_dataframe_describe then eurostat_dataframe_query sequence (or, without a canvas, what was returned inline and what was discarded), preceded by byte-budget disclosure when the budget stopped the transfer and by the inline-preview length when preview_limit returns fewer rows than were downloaded.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: The dataset code is not available for dissemination (HTTP 404, SDMX faultcode 100). `invalid_dimension`: A filter names a dimension the dataset does not have, or a value or period range Eurostat rejects (SDMX faultcode 150). `filter_arity`: Eurostat rejected the positional dimension key because it carried the wrong number of positions (SDMX faultcode 140, INVALID_QUERY_NB_FILTERS), meaning the dataset structure has changed since the metadata call. `invalid_period`: since_period or until_period is not a period literal, or names a month, quarter, semester, trimester, week or day that does not exist, or since_period starts after until_period ends. Checked before any request — the bulk endpoint would otherwise roll an out-of-range period into a neighbouring one, and answer an inverted range with the whole series — and SDMX faultcode 140 TIME_PERIOD_FILTER_SPEC_INVALID maps here too. `async_queued`: Eurostat answered HTTP 200 with a SOAP syncResponse queue ticket (status SUBMITTED) instead of data, because the extraction was too costly to serve synchronously. `no_results`: The download completed but carried no populated observation cells. Nothing is staged, and no canvas is created or touched. `extraction_too_big`: Eurostat refused the extraction as too large (SDMX faultcode 413, HTTP 413): past its 5,000,000-row extraction limit, or an unfiltered download of a large DS-* Comext collection, which Eurostat serves only filtered. Covers every dataset, on either host. `upstream_fault`: The SDMX endpoint returned a fault this server does not model, or a body that is not a TSV table. `canvas_not_found`: A canvas_id was supplied for staging but is unknown or its lifetime has elapsed. Other values are possible when a failure originates below the handler.",
              "examples": [
                "not_found",
                "invalid_dimension",
                "filter_arity",
                "invalid_period",
                "async_queued",
                "no_results",
                "extraction_too_big",
                "upstream_fault",
                "canvas_not_found"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "datasetCode",
        "dimensionsUsed",
        "rowCount",
        "missingCount",
        "periodRange",
        "bytesRead",
        "compressed",
        "budgetExceeded",
        "observations",
        "totalCount",
        "appliedQuery"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

List the tables staged on a Eurostat dataframe canvas, with their row counts and column names and types. Call this before eurostat_dataframe_query to learn the table and column names to write SQL against. The canvas_id comes from a eurostat_query_dataset or eurostat_download_dataset response that reported a staged table. Three tools stage tables, and they write different columns, so read the columns reported here rather than assuming. The two observation stagers keep every column flat: eurostat_query_dataset gives each dimension a code column named after the dimension (e.g. "geo") plus a label companion (e.g. "geo_label"); eurostat_download_dataset gives code columns only — the bulk endpoint carries no labels — plus a "time" column. Both write the same five measure columns — obs_value, obs_flag, obs_flag_label, conf_status, conf_status_label — carrying the same codes for the same observation, so their tables join on dimension codes and time and compare like with like. A table staged from a DS-* dataset (Comext detailed trade, PRODCOM) adds obs_value_text, holding a value Eurostat published as text, such as a PRODCOM quantity unit. eurostat_get_dimension_values, given a canvas_id, stages one dimension's value list as two columns, code and label, which labels a download's code column through a join (e.g. d.geo = g.code).

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas identifier returned as canvasId by eurostat_query_dataset, eurostat_download_dataset, or eurostat_get_dimension_values. Identifies the workspace holding the staged tables."
    }
  },
  "required": [
    "canvas_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "canvasId": {
      "type": "string",
      "description": "Canvas identifier the tables were read from."
    },
    "expiresAt": {
      "type": "string",
      "description": "ISO 8601 timestamp when the canvas expires. Every call on it slides this forward."
    },
    "tables": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Table name to reference in SQL."
          },
          "kind": {
            "type": "string",
            "enum": [
              "table",
              "view"
            ],
            "description": "Whether the entry is a base table or a view."
          },
          "rowCount": {
            "type": "number",
            "description": "Rows the table holds."
          },
          "expiresAt": {
            "description": "ISO 8601 expiry of this table specifically. Omitted when the table ages with the canvas rather than on its own clock.",
            "type": "string"
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Column name."
                },
                "type": {
                  "type": "string",
                  "description": "SQL column type (e.g. \"VARCHAR\", \"DOUBLE\")."
                },
                "nullable": {
                  "type": "boolean",
                  "description": "Whether the column admits NULL."
                }
              },
              "required": [
                "name",
                "type",
                "nullable"
              ],
              "additionalProperties": false,
              "description": "One column of the table."
            },
            "description": "Columns in declaration order."
          }
        },
        "required": [
          "name",
          "kind",
          "rowCount",
          "columns"
        ],
        "additionalProperties": false,
        "description": "One table or view staged on the canvas."
      },
      "description": "Tables staged on this canvas. Empty when nothing has been staged yet, or when every staged table has expired."
    },
    "notice": {
      "description": "Guidance when the canvas holds no tables. Omitted when it holds at least one.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: This deployment runs without a dataframe canvas, so there is nothing to describe. `canvas_not_found`: The canvas_id is unknown or its lifetime has elapsed. Other values are possible when a failure originates below the handler.",
              "examples": [
                "canvas_disabled",
                "canvas_not_found"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "canvasId",
        "expiresAt",
        "tables"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Run a read-only SQL SELECT against tables staged on a Eurostat dataframe canvas — the way to reach observations past the 5,000-row inline cap of eurostat_query_dataset and past the inline preview of a eurostat_download_dataset bulk download, and to aggregate, group, or join across staged tables without re-fetching from Eurostat. Call eurostat_dataframe_describe first for the table and column names, which differ between the tools that stage them. Only a single SELECT statement runs: statement chaining, non-SELECT verbs, and functions that read files or external data are rejected. Columns are flat — every dimension is a code column named after the dimension, the measure is obs_value, the observation flag is obs_flag / obs_flag_label and the confidentiality marker is conf_status / conf_status_label; a "_label" companion per dimension exists only on tables eurostat_query_dataset staged. Both observation stagers write the same five measure columns with the same codes, so join their tables on dimension codes and time and compare obs_flag or conf_status across them directly; a DS-* table also carries obs_value_text, a value published as text (e.g. a PRODCOM unit "KG"). A value list eurostat_get_dimension_values staged has two columns, code and label: join it to the code column of a download (e.g. JOIN df_x g ON d.geo = g.code) to label that table.

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas identifier returned as canvasId by eurostat_query_dataset, eurostat_download_dataset, or eurostat_get_dimension_values. Identifies the workspace holding the staged tables."
    },
    "sql": {
      "type": "string",
      "minLength": 1,
      "description": "A single read-only SELECT statement. Reference tables by the names eurostat_dataframe_describe reports. Example: SELECT geo, geo_label, AVG(obs_value) AS mean FROM df_a1b2c3d4 WHERE time >= '2020' GROUP BY geo, geo_label ORDER BY mean DESC."
    }
  },
  "required": [
    "canvas_id",
    "sql"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "canvasId": {
      "type": "string",
      "description": "Canvas identifier the query ran against."
    },
    "columns": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Column names in projection order."
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      },
      "description": "Result rows, each keyed by column name. Bounded by the canvas row limit. 64-bit integer results — COUNT(*) among them — arrive as strings so values outside the JSON number range survive intact; cast to DOUBLE in the SQL if a number is wanted."
    },
    "rowCount": {
      "type": "number",
      "description": "Rows materialized into this response. Equals the full result size unless truncated is true."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when the result exceeded the canvas row limit and was cut short. Add a LIMIT, an aggregate, or a narrower WHERE clause to see the rest."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: This deployment runs without a dataframe canvas, so there is nothing to query. `canvas_not_found`: The canvas_id is unknown or its lifetime has elapsed. `missing_table`: The SQL names a table that is not staged on this canvas, or that has expired. Other values are possible when a failure originates below the handler.",
              "examples": [
                "canvas_disabled",
                "canvas_not_found",
                "missing_table"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "canvasId",
        "columns",
        "rows",
        "rowCount",
        "truncated"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}