gnomad-genetics-mcp-server: dataframe query
gnomad_dataframe_queryRun a read-only SQL SELECT against a canvas table staged by gnomad_list_gene_variants (table gene_variants) or gnomad_search_clinvar (table clinvar_variants) and return one page of the result. Use the canvas_id and table_name those tools returned to rank by allele frequency, group by consequence class, count loss-of-function variants, or filter the full set the inline preview only sampled. A page holds up to limit rows (default 25, capped at 3,000) and ends before a row that would take its row JSON past 4,000,000 characters; continue from next_offset until it is null. Each page re-runs the SQL, so stable paging needs an ORDER BY over a unique key (such as variant_id) and an unchanged table. Paging reaches the server row cap: above it total is null and later rows are reachable only by filtering or aggregating in SQL. BIGINT values, such as the staged ac and an counts and COUNT(*), arrive as JSON strings to keep their precision; CAST(col AS INTEGER) returns a number. SELECT statements only — writes, DDL, and file/HTTP table functions are rejected by the canvas gate. Call gnomad_dataframe_describe first to discover staged table and column names.
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": {
"canvas_id": "<canvas_id>",
"sql": "<sql>"
},
"name": "gnomad_dataframe_query"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | Read-only SQL SELECT. Reference tables by the names the staging tool returned (e.g. gene_variants). Add an ORDER BY over a unique key when paging. | |
| limit | No | Maximum rows on the page. A page also ends before a row that would take its row JSON past 4,000,000 characters. Default 25; a value above 3,000 is clamped to 3,000, with a notice. | |
| offset | No | Row offset of the page to return. Start at 0, then pass next_offset from the previous page. | |
| canvas_id | Yes | Canvas ID returned by gnomad_list_gene_variants or gnomad_search_clinvar. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rows | No | This page of result rows, in result order. | |
| error | No | Present when the call failed. Absent on success. | |
| total | No | Rows the SQL produced; null when the result exceeds the server row cap, whose later rows paging cannot reach. | |
| notice | No | Set when limit was above its cap: the requested and applied values. | |
| offset | No | Row offset this page starts at. | |
| columns | No | Column names in the result, in order. | |
| returned | No | Rows on this page — fewer than limit when the end of the result, the row cap, or the 4,000,000-character row-JSON ceiling ends it early. | |
| truncated | No | True when result rows exist after this page, including rows past the row cap that next_offset cannot reach. | |
| next_offset | No | offset for the next page; null when no page follows (end of the result, or the row cap reached). |