faostat-mcp-server: query observations
faostat_query_observationsQuery a FAOSTAT domain's data cube by area(s), item(s), element(s), and year range, returning observations (area, item, element, year, value, unit, and the data-quality flag). Resolve codes first with faostat_resolve_codes — the cube is unqueryable without them. Aggregate regions (World, continents, economic groupings) are EXCLUDED by default so a naive SUM does not double-count a region with its member countries; set include_aggregates=true to get the regional roll-ups, or pass explicit area_codes to query exactly what you name. Small result sets return inline; large ones spill to a DataCanvas table (returned canvas_id + table_name) — call faostat_dataframe_describe for its columns, then faostat_dataframe_query for GROUP BY / ranking / time-series analysis. Every row carries its flag — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain — so honor it, treat any unrecognized flag as informational, and never assume an estimated, imputed, or unrecognized value is official.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max observations returned inline — also the preview size when the result stages to a canvas table. Rows past it are never dropped silently: a match larger than limit stages in full to a DataCanvas table (canvas_id + table_name), and when no table is staged the notice reports how many matched so you can raise limit or narrow the filters. Max 1000. | |
| domain | Yes | FAOSTAT domain code (e.g. "QCL"). Must be indexed locally. | |
| year_end | No | Inclusive end year (e.g. 2022). | |
| canvas_id | No | Canvas ID to stage onto, as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to stage onto this session’s canvas, created on the first spill and reused by every later call, so tables staged earlier in the session sit alongside this one. | |
| area_codes | No | Area codes from faostat_resolve_codes. When set, aggregates are NOT auto-excluded — the codes are honored verbatim. | |
| item_codes | No | Item codes from faostat_resolve_codes. | |
| year_start | No | Inclusive start year (e.g. 2000). | |
| element_codes | No | Element codes from faostat_resolve_codes (e.g. 5510 Production). | |
| include_aggregates | No | When false (default), exclude aggregate-region rows (codes ≥ 5000 plus a few curated sub-threshold roll-ups such as China=351) so sums are not double-counted. Set true for World/continent/grouping roll-ups. Ignored when explicit area_codes are passed. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| domain | No | The domain code echoed back. | |
| notice | No | Guidance on empty results, aggregate exclusion, or how to reach the spilled set. | |
| spilled | No | True when the full result was staged on a DataCanvas table. | |
| canvas_id | No | Canvas ID holding the staged table (present when spilled) — pass it with table_name to faostat_dataframe_describe for the columns and types, then to faostat_dataframe_query for SQL. | |
| truncated | No | True when the staged table hit the 50,000-row staging cap — the staged set is a PREFIX of the match, not the complete result. Partition the query by year or code ranges to capture the rest. | |
| table_name | No | Canvas table holding the staged result set (present when spilled; a PREFIX of the match when truncated) — pass it as name to faostat_dataframe_describe, then reference it in faostat_dataframe_query SQL. | |
| totalCount | No | Observations matched. Exact when the result was returned inline or fully staged. A floor — more matched — in two cases, both named by the notice: the match exceeded the 50,000-row staging cap (truncated is then true), or staging failed and the response fell back to an inline page. | |
| observations | No | Inline observations (preview when the full set spilled to a canvas table). | |
| staged_row_count | No | Rows actually staged on the canvas table (present when spilled). Equals the full match count unless truncated, in which case it is the 50,000-row cap. |