Query a PSA OpenSTAT dataset
query_psa_datasetQuery a PSA OpenSTAT dataset by providing explicit value codes for every dimension, with a configurable row limit and error status reporting.
Instructions
Run one bounded query against a PSA OpenSTAT dataset.
Every dimension needs an explicit list of value codes from describe_psa_dataset. That is a hard requirement, not a convention. PXWeb expands an unselected dimension to all of its values, and PSA answers the resulting full-cube request with an HTTP 403. PSA writes a missing cell as "..", and those come back as null, never zero. Examples:
one dataset, every dimension given an explicit code list
query_psa_dataset( "1F/FY/0241F3DF013.px", {"Year": ["2"], "Major Island Group": ["0", "2"], "Among Families/Population": ["0"]}, )
On failure: a bad path, a bad max_rows, or a rejected selection (a missing dimension, an unknown code, or "all"/"*") sets validation_error true and data_status "invalid_request", before any request goes out. An OpenSTAT outage sets upstream_error true and data_status "unavailable". A zero-row reply for a nonzero selection, or a row whose key does not map to the declared columns, sets data_status "indeterminate" and upstream_error true on a real HTTP 200. All four cases return an empty rows list.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"dataset_path": "<dataset_path>",
"selections": "<selections>"
},
"name": "query_psa_dataset"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| max_rows | No | Cap on returned rows (1-5000, default 500). | |
| selections | Yes | Dimension code -> list of value codes, covering every dimension the dataset declares. "all" and "*" are rejected. Example: {"Year": ["2"], "Major Island Group": ["0", "2"], "Among Families/Population": ["0"]}. | |
| dataset_path | Yes | Relative `.px` path, for example "1F/FY/0241F3DF013.px". |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| rows | Yes | ||
| title | No | ||
| source | Yes | Upstream data source name. | |
| caveats | Yes | ||
| license | No | ||
| row_count | Yes | ||
| truncated | No | ||
| disclaimer | No | ||
| source_url | Yes | Canonical OpenSTAT URL used. | |
| dataset_path | Yes | ||
| upstream_error | No | True when OpenSTAT was unreachable. Not an empty result. | |
| requested_cells | No | ||
| reference_period | No | Data vintage read from the table's own time dimension. | |
| validation_error | No | True when the caller's arguments were rejected before any request. | |
| data_retrieved_at | Yes | ||
| total_rows_available | No |