Summarize a Dataset by Group
aggregateA summary of one dataset computed on the server: one small row per group instead of raw rows. agg is avg, sum, min, max, count, or weighted_rate. To list observed values of a filter column, use agg='count', group_by=[] (one value per row, plus its count); describe_dataset lists allowed enum values without a scan. metric is the figure to summarize (default: the dataset's key_metric; ignored for count). group_by lists columns to group by (year, code columns like district_code or county_fips, or category columns). weighted_rate is a population-weighted rate, SUM(numerator) / SUM(denominator) times the rate's per-N scale (1,000 for a rate per 1,000, so the figure reads like the rows' own rates; the value column's rate_scale), over the rows that publish both counts (pooled_rows; a row withholding its numerator is left out, not counted as zero); for a rate across several places or years it is the right figure, since avg averages the rows' rates without weighting by population. With metric set to one of the dataset's pooled_rates (a school zone's people per square mile), it pools that rate's own numerator and denominator. Takes the same filters, years, and detail as query_dataset, plus order_by ('value' for the summarized figure) and order. Each row has <metric>_<agg> (or row_count) and coverage counts (input rows, pooled rows, non-null counts), so suppression is visible. aggregation_scope says whether the source publishes rows at this level or they are recomputed from finer rows. A sum or weighted_rate across a column the dataset declares non_additive (overlapping rows) is returned with a non_additive block and a leading non_additive_sum advisory: that figure is not a total. NULLs are skipped. No SQL: every column name is checked against the dataset's schema.
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": "aggregate"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agg | No | How to summarize (default 'avg'). | avg |
| year | No | Exact year. Use this or year_min/year_max, not both. | |
| limit | No | Groups 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. | |
| metric | No | Figure (metric column) to summarize. Default: the dataset's key_metric. | |
| offset | No | Number of rows to skip, for paging. | |
| 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. | |
| group_by | No | Columns to group by: year, code columns, or category columns. Omit for one overall row. | |
| order_by | No | Sort by 'value' (the summarized figure) or a group_by column. NULLs sort last. | |
| year_max | No | Last year of a range (inclusive). | |
| year_min | No | First year of a range (inclusive). | |
| 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 | |||