Cdc Query Dataset
cdc_query_datasetRead-only
Execute a SoQL query against any CDC dataset. Supports filtering, aggregation, sorting, full-text search, and field selection. Use cdc_discover_datasets to find dataset IDs and cdc_get_dataset_schema to inspect columns before querying.
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": {
"datasetId": "<datasetId>"
},
"name": "cdc_query_dataset"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | SoQL GROUP BY clause. Requires aggregate functions in select. | |
| limit | No | Rows to return (default 100). One call returns at most 1,000 rows: a larger limit, up to 1,000,000, is capped at 1,000, and the response says so and gives a nextOffset when more rows remain. Up to that cap, a page comes back shorter than limit only at the end of the result set. | |
| order | No | SoQL ORDER BY clause. Field name with optional ASC/DESC: "total_deaths DESC". Set one from the first page whenever paging with offset, and keep it for the whole walk: SODA does not order results implicitly, so consecutive offsets without a deterministic order, or under a changed one, can skip or repeat rows. End it with a tie-breaker unique to each row: on ungrouped rows, the system field `:id`, present on every dataset (order="year DESC, :id"); on a grouped query, the grouped columns (order="total DESC, state"); on a distinct select, the selected columns. Socrata rejects `:id` once rows are grouped. | |
| where | No | SoQL WHERE clause. Strings must be single-quoted: "state='California' AND year=2020". If a column name matches a SoQL keyword (group, select, where, order, limit, offset, having, search), wrap it in backticks: "`group`='By Year'". | |
| domain | No | CDC Socrata host to query. "data.cdc.gov" (default) and "chronicdata.cdc.gov" front the same catalog, so a four-by-four ID returns the same rows from either and the default works whichever host the dataset was found on. | data.cdc.gov |
| having | No | SoQL HAVING clause. Filters aggregated results. | |
| offset | No | Row offset for pagination (max 1,000,000). Pair with a deterministic order clause — an offset walk over unordered results can skip or repeat rows. | |
| search | No | Full-text search across all text columns. For precise filtering use the where parameter instead. | |
| select | No | SoQL SELECT clause — column names, aliases, or aggregates: "state, sum(deaths) as total_deaths". Omit for all columns. To enumerate distinct values of a column, set select to "{column}, count(*) as count" with group="{column}" and order="count DESC, {column}". | |
| datasetId | Yes | Four-by-four dataset identifier (e.g., "bi63-dtpu"). Obtain from cdc_discover_datasets. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The row limit that bounded this response: the requested limit, or 1,000 when a larger one was capped. | |
| rows | No | Result rows with requested fields. Most values are strings (including numbers/dates); geo columns return GeoJSON objects. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of rows returned in this response. | |
| notice | No | Guidance when no rows matched, when offset ran past the end of the result set (or the offset-0 check that tells the two apart could not complete), when every matched row came back with no fields for the projection, or when further rows remain (naming a limit above 1,000 that was capped) — how to verify filters, lower offset, pick columns the matched rows populate, resume paging under the same order or restart it from offset 0 under one that makes the walk gap-free, or broaden the query. | |
| rowCount | No | Number of rows returned in this response. | |
| truncated | No | True when rows exist beyond the ones returned, established by fetching one row more than the limit rather than inferred from the row count. Absent means this response is the complete remainder of the result set. | |
| nextOffset | No | Offset to pass on the next call, under the same order, to resume immediately after the last row returned. Present only when further rows exist and the resume point is within the offset ceiling. The walk is gap-free only when that order ends in a tie-breaker unique to each row; when it does not, the notice says to restart from offset 0 with one. | |
| effectiveQuery | No | The SoQL clauses sent to Socrata, as `$clause=value` pairs joined by "&". Values read exactly as they were supplied — not URL-encoded — so a clause can be copied back into the matching parameter of another call. |