Query a Dataset
query_datasetRows of one dataset, filtered, with the district, school, county, and demographic names joined in. filters takes code columns and category columns (describe_dataset's filters lists the exact keys and valid values). Use year or year_min/year_max, not both. detail picks what one row describes (default: the dataset's finest level). Returns rows and a columns list (type, role, unit, what a NULL means, and is_key_metric on the headline column); key_metric repeats the headline column's name. A NULL usually means the source suppressed the value, not zero. columns returns only the listed columns, include_labels=false leaves out the names, and order_by with order sorts on the server, so a top-N needs only N rows. Pages are small (default 100, at most 500); when truncated is true, bulk_export gives the REST API address that returns the whole result as CSV or Parquet. A bad filter returns an error listing the valid keys and values.
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": {
"topic": "<topic>"
},
"name": "query_dataset"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Exact year. Use this or year_min/year_max, not both. | |
| limit | No | Rows per page (default 100, at most 500). | |
| order | No | Sort direction for order_by: 'asc' or 'desc'. | asc |
| topic | Yes | Dataset name, e.g. 'act_scores' (the `name` from list_datasets or search_datasets). Names are unique across subject areas. | |
| detail | No | Level of detail, i.e. what one row describes: 'schools', 'districts', 'counties', 'tracts', 'states', ... (each dataset lists its own). Omit for the dataset's default. | |
| offset | No | Number of rows to skip, for paging. | |
| columns | No | Return only these columns (dataset columns and joined name columns). Omit for all. | |
| filters | No | Column -> value (or list of values). Keys are the code columns (district_code, school_code, county_fips, tract_geoid, demographic), the dataset's category columns, and a few lookup-table attributes (demographic_category, district_type, school_level, locale); describe_dataset's `filters` lists the exact keys and valid values. A list is OR; several keys AND together. A wrong key or value returns an error listing the valid ones. | |
| order_by | No | Sort by one column (a dataset column or a joined name column). Default order is the row's identifying columns. NULL (suppressed) values sort last either way. | |
| year_max | No | Last year of a range (inclusive). | |
| year_min | No | First year of a range (inclusive). | |
| include_labels | No | Join the district, school, county, and demographic names (default true); false returns codes only. | |
| numeric_filters | No | ANDed comparisons on numeric metric columns, before pagination or aggregation. gt/gte/lt/lte use value; inclusive between uses values=[lower, upper]. Stored units: 0.9 means 90%. NULLs do not match. describe_dataset lists numeric_filter_columns. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||