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