The 22 Tables¶

The Parquet release is 22 tables, one per bundle section. They fall into six areas that you can learn one at a time. Variants and conditions are the nouns. Propositions say what is claimed about them. Statements say who claimed it, and how confidently.

The map renders at full size in a scrollable frame. Each area has a runnable query you can expand, and each table box links to that table's column reference below.

The six areas¶

Most questions start in area 1 or 2, go through area 3, and end in one statement area. The Joining Tables page covers each of those hops. For download links and the release layout, see Downloads → Parquet Files.

Ids tell you where to look¶

Every row has an id, and the id's shape names its table. Learn these shapes before writing a join. Several columns can hold more than one kind of id, so the prefix tells you which table to join.

Two details are easy to miss:

• A proposition id is its statement's id without the version. VCV000051592-G-PATH-CP is the proposition, and VCV000051592.122-G-PATH-CP is the statement about it.
• A proposition id's classification code names its table. PATH is in propositionPathogenicity, ONCO in propositionOncogenicity, SCI, DIAG, PROG and TR in propositionSomaticClinicalImpact, and every other code in propositionClinvarCustom (see the code table under Reading a variant's statements). A query that spans several codes can read all four at once: the tables share one column schema, so read_parquet('proposition*.parquet') is a single table.

Where a traversal ends¶

Five tables are leaves: they reference no other table, so a chain of joins stops there.

• sequenceReference: the bottom of the variant chain (variation → allele → location → sequenceReference).
• gene: reached from a variant's gene list.
• condition: reached from a proposition, directly or through a conditionSet.
• therapy: reached from a therapeutic-response proposition, directly or through a therapyGroup.
• submitter: reached from an SCV's contributions.

scv is a leaf of the statement graph: RCV and VCV statements cite SCVs, but an SCV cites no other statement.

Reading a variant's statements¶

A single variant usually has several VCV statements: one per classification type and aggregate level, in a germline lane and sometimes a somatic lane. The statement id encodes all three, as the diagram below shows. It also shows how somatic clinical-impact statements add an evidence-line layer, and which levels contribute to the aggregate call.

The same facts as text. A statement id reads <accession>.<version>-<lane>-<code>[-<level>], for example VCV000012871.94-G-PATH-CP.

Lane and classification code. The lane is G (germline) or S (somatic). The code is shorthand for the proposition type, and says which proposition table holds the proposition:

Root statement counts are VCV roots. An SCV's proposition id uses the same codes without a lane (SCV000056982-ASSOC). Somatic clinical impact (SCI) also has evidence lines whose target_proposition_id names the specific impact: -TR (therapeutic response), -DIAG or -PROG, all in propositionSomaticClinicalImpact with the SCI propositions. Their tier is in evidenceOutcome: Level A/B is Tier I, Level C/D is Tier II.

Aggregate level. The level suffix matches the quality.name of the submissions it groups:

A root statement takes its call from the highest level present, and the levels below it are marked non-contributing. Which level contributes therefore depends on the variant: a variant whose best submissions are NOCP contributes NOCP. Two exceptions: PG and EP both contribute when both are present (the practice guideline doesn't mask the expert panel), and flagged submissions never contribute.

The data column¶

Almost every table has a data column holding the row's complete JSON object as a string, exactly as it appears in the JSON bundle. The typed columns are a convenient, fast subset of it. When a field has no typed column, reach into data:

SELECT id,
       data->>'$.contributions[0].contributor' AS first_contributor
FROM 'scv.parquet'
LIMIT 5;

Two things differ inside data. References are bundle pointers (#/submitter/clinvar.submitter:500034), whereas typed columns carry the bare id (clinvar.submitter:500034). And data is by far the largest column. Leave it out of your SELECT unless you need it; Working at Scale explains why.

Three tables break the pattern:

• condition has camelCase columns (conceptType, primaryCoding), not snake_case. Its data column is new in 1.1.0; earlier releases don't have one.
• therapy and therapyGroup name the id column key and hold the JSON object in value, not id and data. From 1.1.0 they also have typed columns (name, members, …). On earlier releases, read a therapy's name with value->>'name'.

Reading a table remotely¶

Every table can be queried straight from https://data.clinvar-gkm.org/v1/1.1/parquet/<table>.parquet, without downloading it. How well that works depends on what you ask:

• Cheap on any table: DESCRIBE, count(*), and LIMIT reads. These touch only the file's footer or its first chunk, so they return in under a second even on the 3.2 GB scv.parquet.
• Fine on small tables: full scans of anything up to tens of megabytes (condition, gene, submitter, therapy, the somatic propositions).
• Download first for big tables: a full scan or GROUP BY over scv, variation, propositionPathogenicity, or the aggregates reads every row group, one request each, in a burst. Remotely that takes tens of seconds and hundreds of megabytes, and a heavier query can still hit the CDN's limit of 250 requests per 10 seconds (HTTP 429). Download the table once and query it locally. See Working at Scale.

The sizes in the reference below tell you which category a table is in.

Column reference¶

Every column of every table, from DESCRIBE on the 2026-10-18 release, with that release's row counts and file sizes (decimal units: 1 MB is 1,000,000 bytes). Types are shown compactly: STRUCT(a, b) lists only the top-level fields, and [] marks a list. Expand Full nested types under a table for the complete DuckDB type, or run DESCRIBE SELECT * FROM '<table>.parquet' yourself.

Read a STRUCT field with a dot (classification.name) and a list with unnest(…) or an index (members[1]). Anatomy of a Table walks through both.

1 · Variant¶

variation¶

ClinVar's variants, one row per ClinVar Variation id, as Cat-VRS CategoricalVariant records. The subject of every proposition. Each row points at the concrete VRS variant(s) that define it.

variation.parquet · 4,691,827 rows · 3.9 GB

extensions  STRUCT("name" VARCHAR, value_string VARCHAR, value_boolean BOOLEAN, value_coding BIGINT, value_hgvs_array STRUCT(nucleotideExpression STRUCT(syntax VARCHAR, "value" VARCHAR, "extensions" STRUCT("name" VARCHAR, value_string VARCHAR, value_boolean BOOLEAN)[]), nucleotideType VARCHAR, maneSelect BOOLEAN, manePlus BOOLEAN, proteinExpression STRUCT(syntax VARCHAR, "value" VARCHAR), molecularConsequence STRUCT(code VARCHAR, "system" VARCHAR, "name" VARCHAR, iris VARCHAR[])[])[], value_gene_array STRUCT(gene VARCHAR, relationship_type VARCHAR, "source" VARCHAR)[])[]
mappings  STRUCT(coding STRUCT("system" VARCHAR, code VARCHAR, iris VARCHAR[]), relation VARCHAR)[]
constraints  STRUCT("type" VARCHAR, allele VARCHAR, "location" VARCHAR, copies BIGINT, copyChange VARCHAR, matchCharacteristic STRUCT("type" VARCHAR, primaryCoding STRUCT(code VARCHAR, "system" VARCHAR, iris VARCHAR[])), relations STRUCT("type" VARCHAR, primaryCoding STRUCT(code VARCHAR, "system" VARCHAR, iris VARCHAR[]))[])[]

allele¶

VRS Allele records — a specific sequence change at a location. Reached from variation.members[] / constraints[].allele (ga4gh:VA. prefix).

allele.parquet · 4,598,672 rows · 1.1 GB

copyNumberCount¶

VRS CopyNumberCount records — an absolute copy count over a region (ga4gh:CN. prefix).

copyNumberCount.parquet · 47,466 rows · 8.7 MB

copyNumberChange¶

VRS CopyNumberChange records — a relative copy gain or loss over a region (ga4gh:CX. prefix).

copyNumberChange.parquet · 31,722 rows · 5.8 MB

location¶

VRS SequenceLocation records — a span on a reference sequence, shared by alleles and copy-number variants.

location.parquet · 4,215,441 rows · 714.9 MB

loc_start_max and loc_end_min bound the span the variant certainly covers, and are set on every row, so window queries can use them without skipping uncertain-range locations (71,973 rows in 2026-10-18, all of them copy-number variant locations). loc_start_min and loc_end_max bound the widest span it may cover.

sequenceReference¶

The reference sequences locations are placed on — RefSeq chromosomes, transcripts, and other sequences, keyed by their GA4GH refget id. A leaf: it references nothing.

sequenceReference.parquet · 214 rows · 28.9 KB

gene¶

Genes referenced by variants' gene lists and by propositions' gene_context_id, keyed by NCBI Gene id. A leaf.

gene.parquet · 92,989 rows · 5.4 MB

2 · Condition & therapy¶

condition¶

ClinVar's conditions (traits) — diseases, phenotypes, findings — one row per ClinVar trait. The object of most propositions. A leaf. camelCase column names (conceptType, primaryCoding), unlike the other tables.

condition.parquet · 23,414 rows · 4.7 MB

primaryCoding  STRUCT("name" VARCHAR, code VARCHAR, "system" VARCHAR, iris VARCHAR[])
mappings  STRUCT(coding STRUCT("name" VARCHAR, code VARCHAR, "system" VARCHAR, iris VARCHAR[]), relation VARCHAR)[]

conditionSet¶

Sets of conditions a single proposition is about. Two kinds of row share the table: accessioned ClinVar TraitSets (clinvar.traitset:) and sets minted for VCV-level aggregates (clinvar.conditionset:vcv-…).

conditionSet.parquet · 100,706 rows · 11.0 MB

therapy¶

Drug therapies named by therapeutic-response propositions. A leaf. The id column is key, not id, and the JSON object is in value, not data.

therapy.parquet · 38 rows · 4.8 KB

therapyGroup¶

Combination therapies — a set of therapy members. Same key/value shape as therapy, plus typed columns for the operator and members.

therapyGroup.parquet · 10 rows · 8.0 KB

3 · Proposition¶

From 1.1.0 propositions are grouped by meaning, in four tables that share one column schema. A proposition's table depends only on its type, and read_parquet('proposition*.parquet') reads all four as one table with no renaming. Before 1.1.0 they were grouped by the shape of their object, in varcond-, varcustom-, vartumor- and vartherapy-proposition; see Migrating from 1.0.

The shared columns¶

Every proposition table has exactly these columns, in this order. A column that does not apply to a row is NULL (submitted_gene_symbols: an empty list). Every column is derived from the bundle record in data.

propositionPathogenicity¶

Germline pathogenicity claims (VariantPathogenicityProposition, predicate isCausalFor) at every level. By far the largest table. object_type is condition or conditionSet (2,951,614 rows, mostly VCV propositions over several conditions). 6,771,946 SCV rows carry a gene-context qualifier.

propositionPathogenicity.parquet · 27,868,969 rows · 1.5 GB

propositionClinvarCustom¶

ClinVar's non-pathogenicity germline classifications, which have no standard VA-Spec proposition: not provided, drug response, risk factor, association, affects, protective, confers sensitivity, other, conflicting data from submitters, plus ClinvarUndefinedProposition, the fallback for a classification that maps to no defined type (no rows so far). object_type is condition or conditionSet.

propositionClinvarCustom.parquet · 186,184 rows · 10.4 MB

propositionSomaticClinicalImpact¶

Somatic clinical impact: the clinical significance (SCI) that SCV, VCV and RCV statements classify, and the diagnostic (DIAG), prognostic (PROG) and therapeutic-response (TR) propositions that SCI evidence lines target. No statement classifies a DIAG, PROG or TR proposition directly; they are reached through evidenceLine.target_proposition_id. The 13 TR rows have a therapy or therapyGroup object and a condition_qualifier_id; every other row's object is a condition or conditionSet.

propositionSomaticClinicalImpact.parquet · 12,607 rows · 738.0 KB

propositionOncogenicity¶

Somatic oncogenicity claims (VariantOncogenicityProposition, predicate isOncogenicFor). The object is the tumor type: almost always a condition, but 12 rows name a minted conditionSet.

propositionOncogenicity.parquet · 9,595 rows · 457.3 KB

Migrating from 1.0¶

The ids, the records and the data column are unchanged; only the table a proposition is in, and some column names, changed in 1.1.0.

Renamed columns: varcond-proposition.object_condition_id, vartumor-proposition.object_tumor_type_id and vartherapy-proposition.object_therapy are all object_id; varcustom-proposition.subject_id is subject_variant_id. New on every table: object_type, and the columns that only some of the old tables had (condition_qualifier_id, mode_of_inheritance, penetrance, the gene-context columns).

Gene context¶

gene_context_name, gene_context_id, submitted_gene_symbols and gene_context_source describe a proposition's geneContextQualifier. They are filled in only on SCV propositions; every VCV and RCV proposition has NULLs and an empty list. In 2026-10-18, 6,815,040 SCV propositions carry the qualifier, 6,771,946 of them in propositionPathogenicity.

• One representative gene per variant. The qualifier comes from the variant, not from the submission. Upstream, clinvar-ingest-bq-tools picks one gene for each variant with its single-gene method: a point-in-time priority procedure that starts from MANE transcripts and gene symbols in the variant's name, then ClinVar's gene associations. A few genes it picks come only from a variant's name and are not ones ClinVar associates; those are not in gene.parquet, so gene_context_id won't join for them. Every SCV of the variant gets that same gene. The submitter did not assert it, and the Parquet doesn't say which step chose it.
• gene_context_id is that gene's own NCBI Gene coding (primaryCoding.code), written ncbigene:<n> so it joins gene.id directly. gene_context_name is the same gene's symbol. The id is never looked up from a symbol.
• submitted_gene_symbols is what the submitter named, verbatim. It can list several genes, and may leave out the representative gene: 28,653 SCVs in 2026-10-18 do. From this release the symbols are in submitted order; earlier releases list them in no fixed order.

• gene_context_source says where the gene came from. It is filled in on every SCV proposition that has the qualifier. From this release.

  Value	Meaning	2026-10-18
  submittedSymbolMatches	The submitter's symbols include the qualifier's symbol, possibly with other genes.	5,890,310
  submittedSymbolDiffers	The submitter gave symbols, but none equals the qualifier's symbol. Most are a previous symbol of the same gene (GBA for GBA1); the genes are not necessarily different.	28,507
  inferredFromVariant	The submitter gave no symbols.	891,616
  submittedNotNormalized	The placeholder: the variant has no single representative gene.	4,607

  Symbols are compared after trimming spaces and ignoring case (C19ORF12 matches C19orf12). That is why submittedSymbolDiffers counts 28,507, not the 28,653 above, which compared exactly. - The placeholder. When the variant has no single representative gene but the submitter named genes, gene_context_name is the submitter's symbol and gene_context_id is NULL. The name is not a normalized gene, and gene_context_source is submittedNotNormalized. Several symbols are joined with , in submitted order (5 SCVs, e.g. DLK1, MEG3). The submitter's genes are still in submitted_gene_symbols. There are 4,607 of these SCVs in 2026-10-18: 4,570 in propositionPathogenicity and 37 in propositionClinvarCustom. Releases before this one name every placeholder with the literal submitted genes were not normalized.

  Because a placeholder's name is now a submitted symbol, a filter such as gene_context_name = 'TP53' also matches placeholders. In 2026-10-18 that is 29 TP53 rows (77 for BRCA1, BRCA2, TP53 and MLH1 together). To get only normalized genes, filter on gene_context_id, or exclude gene_context_source = 'submittedNotNormalized'.

Releases before 1.1.0 have only gene_context_name; the id and symbols are in data (geneContextQualifier.primaryCoding.code, and the submittedGeneSymbols extension). gene_context_source and its geneContextSource extension start with this release.

This is not the variant's gene list. The gene list (clinvarGeneList in variation.extensions) relates a variant to every gene ClinVar associates with it: many genes per variant, including genes a large copy-number variant merely overlaps. Use the gene list to find a gene's variants, as in the gene rollup recipe; use gene_context_id for the one gene a submission's proposition is framed around. A planned variant-gene lookup file will publish the gene list as a gene × variant crosswalk; it carries the gene list, not the gene context.

4 · SCV¶

scv¶

SCV statements — each submitter's classification of a variant, one row per ClinVar submission (SCV accession). The leaves every aggregate cites.

scv.parquet · 6,853,781 rows · 3.2 GB

classification  STRUCT("type" VARCHAR, conceptType VARCHAR, "name" VARCHAR, primaryCoding STRUCT(code VARCHAR, "system" VARCHAR), "extensions" STRUCT("name" VARCHAR, value_string VARCHAR)[])
strength  STRUCT("type" VARCHAR, conceptType VARCHAR, "name" VARCHAR, primaryCoding STRUCT(code VARCHAR, "system" VARCHAR))
quality  STRUCT("type" VARCHAR, conceptType VARCHAR, "name" VARCHAR)
specifiedBy  STRUCT("type" VARCHAR, methodType VARCHAR, "name" VARCHAR, reportedIn STRUCT("type" VARCHAR, pmid VARCHAR, doi VARCHAR, urls VARCHAR[], "name" VARCHAR, documentType VARCHAR, "extensions" STRUCT("name" VARCHAR, value_string VARCHAR, value_boolean BOOLEAN)[]), "extensions" STRUCT("name" VARCHAR, value_document_array STRUCT("type" VARCHAR, pmid VARCHAR, doi VARCHAR, urls VARCHAR[], "name" VARCHAR, documentType VARCHAR, "extensions" STRUCT("name" VARCHAR, value_string VARCHAR, value_boolean BOOLEAN)[])[])[])
reportedIn  STRUCT("type" VARCHAR, pmid VARCHAR, doi VARCHAR, urls VARCHAR[], "name" VARCHAR, documentType VARCHAR, "extensions" STRUCT("name" VARCHAR, value_string VARCHAR, value_boolean BOOLEAN)[])[]
extensions  STRUCT("name" VARCHAR, value_string VARCHAR, value_submitted_condition_set STRUCT(conditionSet VARCHAR, condition VARCHAR, multiple_condition_explanation VARCHAR, concepts STRUCT(id VARCHAR, "name" VARCHAR, "type" VARCHAR, medgen_id VARCHAR, xrefs STRUCT(code VARCHAR, "system" VARCHAR)[], original_medgen_match STRUCT(id VARCHAR, "name" VARCHAR), direct_match VARCHAR, normalized_match VARCHAR, normalized_resolution VARCHAR, "mapping" STRUCT("type" VARCHAR, "ref" VARCHAR, "value" VARCHAR))[]), value_submitted_condition STRUCT(conditionSet VARCHAR, condition VARCHAR, id VARCHAR, "name" VARCHAR, "type" VARCHAR, medgen_id VARCHAR, xrefs STRUCT(code VARCHAR, "system" VARCHAR)[], original_medgen_match STRUCT(id VARCHAR, "name" VARCHAR), direct_match VARCHAR, normalized_match VARCHAR, normalized_resolution VARCHAR, "mapping" STRUCT("type" VARCHAR, "ref" VARCHAR, "value" VARCHAR)))[]
contributions  STRUCT("type" VARCHAR, contributor VARCHAR, date DATE, activityType VARCHAR)[]

evidenceLine¶

SCV-level evidence lines — used only by somatic clinical impact (SCI) submissions. Each points at the specific impact (therapeutic response, diagnostic, prognostic) and carries its AMP/ASCO/CAP tier.

evidenceLine.parquet · 1,568 rows · 154.1 KB

evidenceOutcome  STRUCT("type" VARCHAR, conceptType VARCHAR, "name" VARCHAR)
extensions  STRUCT("name" VARCHAR, value_submitted_condition_set STRUCT(conditionSet VARCHAR, condition VARCHAR, multiple_condition_explanation VARCHAR, concepts STRUCT(id VARCHAR, "name" VARCHAR, "type" VARCHAR, medgen_id VARCHAR, xrefs STRUCT(code VARCHAR, "system" VARCHAR)[], original_medgen_match STRUCT(id VARCHAR, "name" VARCHAR), direct_match VARCHAR, normalized_match VARCHAR, normalized_resolution VARCHAR, "mapping" STRUCT("type" VARCHAR, "ref" VARCHAR, "value" VARCHAR))[]), value_submitted_condition STRUCT(conditionSet VARCHAR, condition VARCHAR, id VARCHAR, "name" VARCHAR, "type" VARCHAR, medgen_id VARCHAR, xrefs STRUCT(code VARCHAR, "system" VARCHAR)[], original_medgen_match STRUCT(id VARCHAR, "name" VARCHAR), direct_match VARCHAR, normalized_match VARCHAR, normalized_resolution VARCHAR, "mapping" STRUCT("type" VARCHAR, "ref" VARCHAR, "value" VARCHAR)))[]

submitter¶

The organizations that submit to ClinVar. A leaf, referenced from scv.contributions[].contributor.

submitter.parquet · 3,565 rows · 278.5 KB

5 · RCV¶

rcv¶

RCV aggregate statements — ClinVar's rollup of SCVs for one variant and one condition. Each RCV accession yields a root statement plus one statement per contributing level.

rcv.parquet · 12,056,355 rows · 861.9 MB

strength  STRUCT("type" VARCHAR, conceptType VARCHAR, "name" VARCHAR)
quality  STRUCT("type" VARCHAR, conceptType VARCHAR, "name" VARCHAR)
classification  STRUCT("type" VARCHAR, conceptType VARCHAR, "name" VARCHAR, "extensions" STRUCT("name" VARCHAR, "value" VARCHAR)[])
extensions  STRUCT("name" VARCHAR, "value" VARCHAR)[]

rcv_evidenceLine¶

Evidence lines of RCV statements: which statements each RCV statement cites, and whether they contribute.

rcv_evidenceLine.parquet · 12,156,097 rows · 643.9 MB

strengthOfEvidenceProvided  STRUCT("type" VARCHAR, conceptType VARCHAR, "name" VARCHAR)

6 · VCV¶

vcv¶

VCV aggregate statements — ClinVar's rollup of SCVs for one variant across all its conditions. Same shape as rcv.

vcv.parquet · 9,165,651 rows · 667.2 MB

strength  STRUCT("type" VARCHAR, conceptType VARCHAR, "name" VARCHAR)
quality  STRUCT("type" VARCHAR, conceptType VARCHAR, "name" VARCHAR)
classification  STRUCT("type" VARCHAR, conceptType VARCHAR, "name" VARCHAR, "extensions" STRUCT("name" VARCHAR, "value" VARCHAR)[])
extensions  STRUCT("name" VARCHAR, "value" VARCHAR)[]

vcv_evidenceLine¶

Evidence lines of VCV statements. Same shape as rcv_evidenceLine.

vcv_evidenceLine.parquet · 9,375,111 rows · 512.3 MB

strengthOfEvidenceProvided  STRUCT("type" VARCHAR, conceptType VARCHAR, "name" VARCHAR)