Downloads¶

ClinVar-GKS releases are hosted on Cloudflare R2 object storage. All downloads are free with no authentication required and no egress fees.

Each release includes a gzip-compressed JSON bundle file containing all variations, statements, propositions, conditions, and supporting reference data for a ClinVar release. Typed Parquet files (one per bundle section) are also available for analytical workloads.

Latest Release¶

Download the most recent releases using the stable URLs below:

Format	Download	Description
Monthly (JSON)	clinvar-gks_00-latest.json.gz	Latest monthly release (first weekly of each month)
Weekly (JSON)	clinvar-gks_00-latest_weekly.json.gz	Latest weekly release
Parquet	See download instructions	Typed Parquet files (one per bundle section), always latest release

Download with curl¶

# Latest monthly release (JSON bundle)
curl -O https://pub-9c5470edadb8496fb0abbf396291660b.r2.dev/datasets/clinvar-gks_00-latest.json.gz

# Latest weekly release (JSON bundle)
curl -O https://pub-9c5470edadb8496fb0abbf396291660b.r2.dev/datasets/weekly/clinvar-gks_00-latest_weekly.json.gz

# Decompress
gunzip clinvar-gks_00-latest.json.gz

# Download a single Parquet section (e.g., SCV statements)
curl -O https://pub-9c5470edadb8496fb0abbf396291660b.r2.dev/datasets/parquet/scv.parquet

# Download all Parquet files
for section in sequenceReference location allele copyNumberCount copyNumberChange \
               gene variation condition conditionSet submitter proposition \
               evidenceLine scv vcv rcv; do
  curl -O "https://pub-9c5470edadb8496fb0abbf396291660b.r2.dev/datasets/parquet/${section}.parquet"
done

Download with Python¶

import urllib.request

BASE = "https://pub-9c5470edadb8496fb0abbf396291660b.r2.dev"

# Download latest monthly release
urllib.request.urlretrieve(
    f"{BASE}/datasets/clinvar-gks_00-latest.json.gz",
    "clinvar-gks_00-latest.json.gz"
)

# Download a specific monthly release
urllib.request.urlretrieve(
    f"{BASE}/datasets/clinvar-gks_2026-06.json.gz",
    "clinvar-gks_2026-06.json.gz"
)

# Download a specific weekly release
urllib.request.urlretrieve(
    f"{BASE}/datasets/weekly/clinvar-gks_2026-0614.json.gz",
    "clinvar-gks_2026-0614.json.gz"
)

# Download an archived release from a prior year
urllib.request.urlretrieve(
    f"{BASE}/archives/2025/clinvar-gks_2025-03.json.gz",
    "clinvar-gks_2025-03.json.gz"
)

# Download a Parquet section
urllib.request.urlretrieve(
    f"{BASE}/datasets/parquet/scv.parquet",
    "scv.parquet"
)

Browse All Releases¶

The file browser below shows all available releases organized by year and month. It is populated from the release index and updated automatically with each weekly upload.

curl -s https://pub-9c5470edadb8496fb0abbf396291660b.r2.dev/index.json | python3 -m json.tool

Loading release index...

Directory Structure¶

datasets/
  clinvar-gks_00-latest.json.gz         latest monthly release (stable URL)
  clinvar-gks_YYYY-MM.json.gz           monthly releases (current year)

datasets/weekly/
  clinvar-gks_00-latest_weekly.json.gz  latest weekly release (stable URL)
  clinvar-gks_YYYY-MMDD.json.gz         weekly releases (current month only)

datasets/parquet/
  {section}.parquet                     typed Parquet files (always latest release)

archives/{YYYY}/
  clinvar-gks_YYYY-MM.json.gz           monthly releases from prior years

Parquet Files¶

Typed Parquet files are produced alongside each release and uploaded to datasets/parquet/. Unlike JSON bundles, Parquet files are not versioned — they are overwritten on each release and always represent the latest data.

Each Parquet file contains one bundle section with typed, query-friendly columns extracted from the JSON objects. Every section includes an id column (the object identifier) and a data column (the full JSON object as a string), plus additional typed columns for key fields — enabling efficient filtering and aggregation without parsing JSON.

Available Parquet files (15 sections):

File	Description
`sequenceReference.parquet`	NCBI RefSeq sequence references
`location.parquet`	VRS SequenceLocation records
`allele.parquet`	VRS Allele records
`copyNumberCount.parquet`	VRS CopyNumberCount records
`copyNumberChange.parquet`	VRS CopyNumberChange records
`gene.parquet`	Gene records (MappableConcept with NCBI Gene / HGNC codings)
`variation.parquet`	CategoricalVariant records (Cat-VRS)
`condition.parquet`	Condition records (traits)
`conditionSet.parquet`	ConditionSet records (trait sets)
`submitter.parquet`	Submitter organization records
`proposition.parquet`	Proposition records (SCV, VCV, and RCV)
`evidenceLine.parquet`	Evidence line records (SCV, VCV, and RCV)
`scv.parquet`	SCV statement records
`vcv.parquet`	VCV aggregate statement records
`rcv.parquet`	RCV aggregate statement records

Working with Parquet Files¶

Download the Parquet files you need, then query them locally. The R2 hosting has rate limits and is designed for file downloads, not as a remote query endpoint for tools like DuckDB.

Download¶

Download individual sections or all files at once:

BASE="https://pub-9c5470edadb8496fb0abbf396291660b.r2.dev/datasets/parquet"
mkdir -p clinvar-gks-parquet && cd clinvar-gks-parquet

# Download specific sections
curl -O "${BASE}/scv.parquet"
curl -O "${BASE}/proposition.parquet"
curl -O "${BASE}/condition.parquet"

# Or download all 15 sections
for section in sequenceReference location allele copyNumberCount copyNumberChange \
               gene variation condition conditionSet submitter proposition \
               evidenceLine scv vcv rcv; do
  curl -O "${BASE}/${section}.parquet"
done

DuckDB¶

DuckDB is the fastest way to explore Parquet files — it queries them directly with no data loading step.

# Install DuckDB
brew install duckdb   # macOS
# or: pip install duckdb

# Query SCV statements
duckdb -c "
  SELECT id, classification, direction, strength, confidence
  FROM 'scv.parquet'
  WHERE classification = 'Pathogenic'
  LIMIT 10;
"

# Count classifications across all SCVs
duckdb -c "
  SELECT classification, direction, COUNT(*) as n
  FROM 'scv.parquet'
  GROUP BY classification, direction
  ORDER BY n DESC;
"

# Join SCVs with propositions to find pathogenic variants for a specific condition
duckdb -c "
  SELECT s.id, s.classification, p.predicate, p.object_condition
  FROM 'scv.parquet' s
  JOIN 'proposition.parquet' p ON s.proposition_id = p.id
  WHERE s.classification = 'Pathogenic'
    AND p.object_condition LIKE '%clinvar.trait:9580%'
  LIMIT 10;
"

# Inspect the schema of any section
duckdb -c "DESCRIBE SELECT * FROM 'scv.parquet';"

DuckDB also works from Python:

import duckdb

df = duckdb.sql("""
    SELECT id, classification, direction, strength, confidence
    FROM 'scv.parquet'
    WHERE classification = 'Pathogenic'
    LIMIT 100
""").df()

print(df)

pandas / pyarrow¶

import pandas as pd

# Load a section into a DataFrame
scv = pd.read_parquet("scv.parquet")

# Filter pathogenic SCVs
pathogenic = scv[scv["classification"] == "Pathogenic"]
print(f"{len(pathogenic)} pathogenic SCVs")

# Access the full JSON when you need nested fields
import json
record = json.loads(pathogenic.iloc[0]["data"])
print(record["proposition"])

Column Reference¶

Statement sections (scv, vcv, rcv) share a common set of typed columns:

Column	Type	Description
`id`	string	Statement identifier
`type`	string	Statement type
`proposition_id`	string	FK to `proposition.parquet`
`classification`	string	Classification label (e.g., "Pathogenic")
`strength`	string	Evidence strength (e.g., "definitive", "likely")
`direction`	string	Evidence direction ("supports", "disputes", "neutral")
`confidence`	string	Submission level label (e.g., "criteria provided")
`has_evidence_lines`	list\<string>	FK references to `evidenceLine.parquet`
`extensions`	string	JSON array of extensions
`data`	string	Full JSON object

SCV statements include additional columns: description, contributions, reported_in, specified_by.

The proposition section includes subject_variant, predicate, object_condition, object_condition_set, type, and qualifier columns — enabling JOINs across statements, variants, and conditions without parsing JSON.

Every section includes id and data at minimum. Run DESCRIBE in DuckDB to see the full schema for any section.

Joining Parquet Sections¶

The typed columns make cross-section JOINs fast and readable — most analytical queries can be answered without parsing JSON. However, some data is only available in the data column (the full JSON string), which requires JSON extraction functions.

What typed columns give you: Efficient filtering, grouping, and JOINs on the most commonly queried fields. The query below finds all pathogenic SCVs for a specific gene, joining three sections purely on typed columns:

-- All pathogenic SCVs for BRCA1, with submitter and condition
SELECT
    s.id AS scv_id,
    s.classification,
    s.direction,
    s.confidence,
    p.predicate,
    p.object_condition AS condition_id
FROM 'scv.parquet' s
JOIN 'proposition.parquet' p ON s.proposition_id = p.id
WHERE s.classification = 'Pathogenic'
  AND p.subject_variant = 'clinvar:17661';

Where you hit limits: Fields like condition names, submitter names, gene symbols, HGVS expressions, and extension values are not extracted into typed columns — they live inside the data JSON string. To access them, use DuckDB's json_extract_string:

-- Same query but with condition name and submitter name resolved
SELECT
    s.id AS scv_id,
    s.classification,
    json_extract_string(c.data, '$.name') AS condition_name,
    json_extract_string(s.data, '$.contributions[0].agent.name') AS submitter
FROM 'scv.parquet' s
JOIN 'proposition.parquet' p ON s.proposition_id = p.id
JOIN 'condition.parquet' c ON p.object_condition = c.id
WHERE s.classification = 'Pathogenic'
  AND p.subject_variant = 'clinvar:17661';

JSON extraction is slower than typed column access, but DuckDB handles it efficiently for analytical queries. For bulk processing where you need many nested fields, load the data column into your application and parse the full JSON objects there.

Summary:

Approach	Best for	Tradeoff
Typed columns only	Filtering, counting, grouping, JOINs	Fast, but limited to extracted fields
Typed columns + `json_extract_string`	Ad-hoc exploration needing a few nested fields	Slightly slower; syntax is verbose
Parse `data` column in application code	Bulk processing needing many nested fields	Full flexibility; requires application-side JSON parsing

Release Cadence¶

New releases are published weekly, typically within 1-2 days of each ClinVar XML release.

Monthly releases represent the most current data available at the start of each month. When the first release of a new month is uploaded, the previous month's final weekly release is promoted as that new month's official monthly release and the 00-latest pointer is updated. Weekly releases within a month do not affect the monthly release or latest pointer.

At month boundaries, the prior month's weekly files are deleted — only the current month's weeklies are retained in datasets/weekly/. At year boundaries, the prior year's monthly files are moved to archives/{YYYY}/. All monthly archives are retained indefinitely.

Feedback¶

This project is in active development and we welcome community feedback. If you encounter data quality issues, have questions about the output format, or want to suggest improvements:

Open an issue on GitHub
Include the release date and specific records involved