c3db

Query the C3DB competition-climbing warehouse from your terminal — as raw SQL or from your own AI coding tool. It's a thin client over C3DB's hosted, read-only MCP server: every query is a single SELECT/WITH, cost-capped, row-capped, and timed out server-side. Nothing about the vetted query core is reimplemented here.

pip install c3db
c3db login                                   # paste your c3db_… key (once)
c3db query "SELECT * FROM event_standings WHERE final_rank = 1 LIMIT 5"
c3db connect claude                          # wire the warehouse into Claude Code

pip install "c3db[ask]"                      # natural-language querying (bring your own model)
export ANTHROPIC_API_KEY=sk-ant-…            # your own model key — c3db never sees it
c3db ask "who has won the most World Cup golds in lead?"

from c3db import Client

df = Client().query("SELECT athlete_name, count(*) wins "
                    "FROM event_standings WHERE final_rank = 1 GROUP BY 1 ORDER BY 2 DESC")

Commands

Command What it does
c3db login Verify a c3db_… key against the server and store it in ~/.config/c3db/config.json (0600).
c3db query "<sql>" Run a read-only query. -f file.sql or stdin for the SQL; --format table|csv|json.
c3db ask "<question>" Plain-English → SQL → rows, using your own model. --provider, --model, --base-url, --show-sql. Needs pip install "c3db[ask]".
c3db connect claude|cursor Register the hosted MCP into your AI tool so its model can query the warehouse. --scope user|local|project.
c3db schema Print the query conventions + authoritative BigQuery DDL.

Natural language — bring your own model

c3db ask and Client().ask() are bring-your-own-model: your own LLM reads the warehouse schema and writes the SQL; c3db validates and runs it. c3db never sees or pays for your model key — it's separate from the c3db_… data key. Install a provider and set its key:

pip install "c3db[anthropic]"    # or "c3db[openai]", or "c3db[ask]" for both
export ANTHROPIC_API_KEY=…       # Anthropic (default: claude-sonnet-5 — plenty for NL→SQL)
export OPENAI_API_KEY=…          # OpenAI-compatible; add C3DB base url / --base-url for DeepSeek/GLM/local
c3db ask "top 3 nations by lead World Cup wins since 2020"

Provider auto-detects from whichever key is set (override with --provider); --model picks the model. Client().ask(q) returns a DataFrame with the generated SQL on df.attrs["sql"].

The two kinds of access

  • Raw SQL (c3db query, Client().query()) — you write the SQL; c3db runs it and hands back rows.
  • Your own AI (c3db connect) — your AI tool's model reads the schema and writes the SQL itself, then runs it through the same server. This is bring-your-own-model: c3db never sees or pays for your AI subscription; it only issues the c3db_… data key that identifies you to the warehouse.

Config

Resolved in order: environment → ~/.config/c3db/config.json → built-in default.

Variable Meaning
C3DB_API_KEY Your c3db_… data key (overrides the stored one).
C3DB_SERVER_URL MCP endpoint (defaults to the hosted service).
C3DB_CONFIG_DIR Override the config directory (default ~/.config/c3db).

Get a key from the project admin (python -m cccd.api.mint_key <your-email>); self-serve signup comes later.

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for yvonne.ngaiyeung from gravatar.com yvonne.ngaiyeung

Credits

Author: C3DB

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

anthropic ask openai

Tags

analytics bigquery climbing ifsc mcp sports-data sql

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

c3db-0.1.0.tar.gz (10.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

c3db-0.1.0-py3-none-any.whl (13.7 kB view details)

Uploaded Python 3

File details

Details for the file c3db-0.1.0.tar.gz.

File metadata

  • Download URL: c3db-0.1.0.tar.gz
  • Upload date:
  • Size: 10.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for c3db-0.1.0.tar.gz
Algorithm Hash digest
SHA256 1b5dfecb9be14d6f45081d846642d96460e9c9709ef0ca6d4ac0f878fdd0ea0f
MD5 970ed57cbd693ffaec59ccff5a3b0e83
BLAKE2b-256 1840b6ae175e8ff042dba43e81e664952c6ec4842862f6a8a775167305cf3c46

See more details on using hashes here.

Provenance

The following attestation bundles were made for c3db-0.1.0.tar.gz:

Publisher: publish-c3db.yml on NGYeung/C3DB

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file c3db-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: c3db-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 13.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for c3db-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8e30b0466283f0f4bdd2c98f92bd62e39bfe32799a23669d2a6f48f80fcf8a64
MD5 f9311afc3d498d4ddee83b36ecf1f337
BLAKE2b-256 d81c6280aaf953b28d9ca9d6c07abd1b67ed231d00e1aba34158bef316896370

See more details on using hashes here.

Provenance

The following attestation bundles were made for c3db-0.1.0-py3-none-any.whl:

Publisher: publish-c3db.yml on NGYeung/C3DB

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page