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, max 5000). Fewer come back when the page would cross the 200,000-character response budget; 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 whenever paging with offset: SODA does not order results implicitly, so consecutive offsets without a deterministic order can skip or repeat rows. When the dataset has no natural unique column, Socrata's documented minimum tie-breaker is the system field `:id`, present on every dataset — order=":id". | |
| 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". | |
| 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 requested limit that bounded this response. | |
| 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 further rows remain, or when the response budget cut the page short — how to verify filters, resume paging, 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 to resume immediately after the last row returned. Present only when further rows exist and the resume point is within the offset ceiling; a deterministic order clause is what makes the walk gap-free. | |
| 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. |