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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | SoQL GROUP BY clause. Requires aggregate functions in select. | |
| limit | No | Max rows to return (default 100). One call returns at most 5,000 rows: a larger limit, up to 1,000,000, is capped at 5,000, and the response says so and gives a nextOffset when more rows remain. Fewer come back when the page would carry the response past its 200,000-character budget, counted over the whole result — the rows as JSON and as the rendered table together; the response says so and gives a nextOffset to resume from. | |
| 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
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The row limit that bounded this response: the requested limit, or 5,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, when further rows remain (naming a limit above 5,000 that was capped), or when the response budget cut the page short — how to verify filters, lower offset, 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. |