Download Eurostat Dataset
eurostat_download_datasetDownload 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filters | No | 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. 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. | |
| canvas_id | No | Reuse an existing dataframe canvas so this download lands beside earlier results 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. | |
| dataset_code | Yes | Dataset code (e.g., "nama_10_gdp"). Required. | |
| since_period | No | Start of the period range (e.g., "2020", "2023-Q1", "2024-01"), sent as startPeriod. The most effective way to shrink a bulk response: it removes period columns from the TSV rather than blanking their cells. | |
| until_period | No | End of the period range (e.g., "2024"), sent as endPeriod. Omit for data through the latest available period. | |
| preview_limit | No | 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The preview_limit applied to inline observations. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Observations returned in the inline preview. | |
| notice | No | Guidance for every staged result, including the required eurostat_dataframe_describe then eurostat_dataframe_query sequence, composed with byte-budget, no-canvas, or empty-result disclosure when applicable. | |
| canvasId | No | Dataframe canvas holding the staged download. Pass to eurostat_dataframe_describe, eurostat_dataframe_query, or a later staging call. Omitted when nothing was staged. | |
| rowCount | No | Observations expanded from the download — one per populated cell, counting those Eurostat reports as unavailable. | |
| bytesRead | No | Decoded TSV bytes read from Eurostat — after gzip decompression when the body arrived compressed, so it measures the payload rather than the wire. | |
| tableName | No | 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. | |
| truncated | No | True when the inline observation preview omits rows. | |
| compressed | No | 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. | |
| datasetCode | No | Dataset code as provided. | |
| periodRange | No | Period coverage of the rows actually downloaded. Narrower than the dataset when budgetExceeded is true or a period range was applied. | |
| appliedQuery | No | The bulk request as the server built it. | |
| missingCount | No | Downloaded observations carrying no numeric value (obs_value is null). | |
| observations | No | The first preview_limit observations of the download, in the order Eurostat streamed them. A prefix of the staged table, not a sample. | |
| budgetExceeded | No | 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. | |
| dimensionsUsed | No | 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. | |
| stagedRowCount | No | Rows written to the canvas table. Matches rowCount. Omitted alongside tableName. |