shillelagh-gristapi

A Shillelagh adapter that exposes the Grist REST API as SQL-queryable virtual tables via SQLite/SQLAlchemy.

Features

Query Grist documents, tables, and records with SQL
Filter pushdown for = and IN conditions; server-side ORDER BY and LIMIT
Discovery queries: list organizations, workspaces, documents, and tables via grist:// URIs
Column metadata introspection via grist://<doc_id>/<table_id>/__columns__
Built-in TTL caching (SQLite or in-memory) to reduce API calls
Enforces Grist access rules — your API key permissions apply automatically
Works with Apache Superset, the shillelagh CLI, and any SQLAlchemy-compatible tool

Installation

pip install shillelagh-gristapi

For the interactive CLI:

pip install 'shillelagh[console]'

For source installation, see docs/getting-started.md.

Quickstart

from shillelagh.backends.apsw.db import connect
import os

conn = connect(
    ":memory:",
    adapter_kwargs={"gristapi": {"grist_cfg": {
        "server": os.environ["GRIST_SERVER"],
        "org_id": int(os.environ["GRIST_ORG_ID"]),
        "api_key": os.environ["GRIST_API_KEY"],
    }}},
)
cursor = conn.cursor()
rows = cursor.execute('SELECT * FROM "grist://<DOC_ID>/<TABLE_ID>" LIMIT 10').fetchall()

Documentation

Document	Description
docs/getting-started.md	Prerequisites, install, step-by-step first queries
docs/uri-reference.md	All `grist://` URI patterns and their column schemas
docs/configuration.md	CLI, Python, and Superset configuration reference
docs/type-mapping.md	Grist column types to SQL/Shillelagh field mapping
docs/superset.md	Apache Superset integration guide
docs/limitations.md	Known restrictions and performance notes

License

MIT — see LICENSE.

Release files for shillelagh-gristapi 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for shillelagh-gristapi 0.2.1
File	Size	Uploaded
shillelagh_gristapi-0.2.1.tar.gz	25.3 kB	Jun 8, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for shillelagh-gristapi 0.2.1
File	Interpreter	ABI	Platform	Reset
shillelagh_gristapi-0.2.1-py3-none-any.whl 19.3 kB Jun 8, 2026	Python 3	none	any	Details

Total release size: 44.6 kB

Release files / shillelagh_gristapi-0.2.1.tar.gz

Download URL	shillelagh_gristapi-0.2.1.tar.gz
Size	25.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`e813511009ab177ced9705bc42dbabe00b38d1eca95b68ef99e5ee7418cdc5ad`
BLAKE2b-256 checksum How to use checksums	`ce1d3ad3df85995427e4c2751b1596396594dadece2211165719f63d2196624d`
Upload date	Jun 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/qleroy/shillelagh-gristapi
Publishing commit: github.com/qleroy/shillelagh-gristapi/tree/661c2bfc36fed72c16e32887e89c550f6b5d2904

Workflow

Publishing configuration: github.com/qleroy/shillelagh-gristapi/blob/661c2bfc36fed72c16e32887e89c550f6b5d2904/.github/workflows/pypi.yml
Publishing logs: github.com/qleroy/shillelagh-gristapi/actions/runs/27142297274/attempts/1

Artifact

Subject: shillelagh_gristapi-0.2.1.tar.gz
SHA-256 checksum: e813511009ab177ced9705bc42dbabe00b38d1eca95b68ef99e5ee7418cdc5ad Verifying attestations

Release files / shillelagh_gristapi-0.2.1-py3-none-any.whl

Download URL	shillelagh_gristapi-0.2.1-py3-none-any.whl
Size	19.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`91b2771e26fd71894017305424155e0bf3051071fdd3861b42bc7fdbe0e2a8f1`
BLAKE2b-256 checksum How to use checksums	`d0b7b568977d2955b71f4d5927f370fc1f753f1399f4db2ac04dde4cfe4bacbb`
Upload date	Jun 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/qleroy/shillelagh-gristapi
Publishing commit: github.com/qleroy/shillelagh-gristapi/tree/661c2bfc36fed72c16e32887e89c550f6b5d2904

Workflow

Publishing configuration: github.com/qleroy/shillelagh-gristapi/blob/661c2bfc36fed72c16e32887e89c550f6b5d2904/.github/workflows/pypi.yml
Publishing logs: github.com/qleroy/shillelagh-gristapi/actions/runs/27142297274/attempts/1

Artifact

Subject: shillelagh_gristapi-0.2.1-py3-none-any.whl
SHA-256 checksum: 91b2771e26fd71894017305424155e0bf3051071fdd3861b42bc7fdbe0e2a8f1 Verifying attestations