Fetch bounded rows for a dataflow
fetchReturn bounded rows for a dataflow — the completion path for hosted clients.
Use this when the client cannot execute a client-download plan locally (no
shell/filesystem — e.g. a hosted store app or connector) but still needs
actual values. fetch server-side downloads the exact GET/fan-out plan
build_url would produce, concatenates it, runs one bounded literal-equality
query, and releases the artifact — the raw dataset never enters model context.
Clients that CAN execute locally should keep using ask/build_url and run
the plan themselves; fetch is the affinity-free hosted shortcut, not the
power path.
POST-only selections have no hosted download path: fetch raises
fetch_shape_unsupported and the caller must execute the build_url plan
client-side. A rejected/over-length selection raises the same reason
build_url would report; narrow the selection and retry.
fetch does not page, deliberately. It holds no dataset between calls:
every call rebuilds the plan, re-downloads every part from the provider, and
releases the artifact. An offset over that would be unsound as well as
wasteful — there is no snapshot behind the cursor, so rows shifting upstream
between calls would silently skip or duplicate observations, and N pages
would mean N full downloads of the same dataflow from an agency that may
rate-limit. When a result is truncated, narrow it (select, where,
time_range) or switch to stage_url + query_dataset, which pages
with offset over ONE immutable staged artifact and downloads once.
Rows are ordered by series key, then period, before limit applies. A
series with a period that cannot be placed unambiguously keeps the
provider's order.
no_records_for_selection is TERMINAL, not a fault: the request was
well-formed and the source holds no observations for it. Widen the selection
or state that no data exists — do not retry the same selection. Only
upstream_origin_error (an origin fault) and upstream_rate_limited
are worth retrying.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Optional max rows to return (a safe default applies when omitted) | |
| where | No | Optional {column: value | [values]} literal-equality row filters | |
| select | No | Optional list of columns to return (defaults to all columns) | |
| agency_id | Yes | SDMX agency code, e.g. "ABS", "ESTAT", "OECD" | |
| max_bytes | No | Optional smaller byte budget for this response; it can only lower the server ceiling, never raise it | |
| precision | No | URL breadth — "point", "series" (default), or "cube" | series |
| selections | No | Optional {dimension_id: [code or name, ...]} to anchor the query | |
| time_range | No | Optional time filter (e.g. "2020-2024", "since 2015", "2024") | |
| dataflow_id | Yes | SDMX dataflow identifier, e.g. "ERP_Q" | |
| availability | No | "confirmed" (default) or "best_effort" | confirmed |
| response_format | No | How the rows are sent. "auto" (default) means no preference and lets the server decide; "text" sends them as CSV only — in the text content, and in structuredContent as a "csv" string in place of typed rows. "structured" sends typed rows only, "both" the CSV and the typed rows. If you got a summary but no rows, call again with response_format="text". | auto |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| csv | No | ||
| rows | No | ||
| columns | No | ||
| agency_id | Yes | ||
| truncated | Yes | ||
| dataflow_id | Yes | ||
| limit_source | Yes | ||
| matched_rows | Yes | ||
| applied_limit | Yes | ||
| returned_rows | Yes | ||
| period_calendar | Yes | ||
| max_bytes_ceiling | No | ||
| min_bytes_required | No | ||
| source_request_count | Yes |