Python API リファレンス

queria は CLI と同じ操作を Python パッケージとしても公開しています。ノートブックやスクリプトから、サブプロセスなしで Queria のデータを読めます。

概要

import queria

with queria.connect() as conn:
    # データセット一覧（メタデータカタログ）
    conn.sql("SELECT datasource, title FROM catalog.main.mart_datasets").show()

    # 参照したデータセットは自動 ATTACH される
    df = conn.sql("""
        SELECT date, holiday_name
        FROM calendar.main.mart_calendar
        WHERE is_holiday AND date >= DATE '2026-01-01'
    """).df()

Connection.sql() は DuckDB の DuckDBPyRelation を返すので、.df()（pandas）、.pl()（Polars)、.arrow()、.fetchall() など DuckDB の標準 API がそのまま使えます。

安定性

queria.connect() と Connection の公開メソッド（sql / execute / attach / close）は公式 API です。それ以外のモジュール内部は予告なく変わることがあります。

API

queria

Queria — query Japanese open data (data.queria.io) from Python and the CLI.

Connection

Read-only connection to Queria's public DuckLake catalogs.

On construction the catalog metadata dataset is attached. Other datasets are attached lazily: when a query references a dataset that is not attached yet, :meth:sql catches the missing-catalog error, attaches the dataset, and retries.

Use as a context manager to make sure the underlying duckdb connection is closed::

with queria.connect() as conn:
    conn.sql("SELECT * FROM catalog.main.mart_datasets").show()

attach

attach(dataset: str) -> None

Attach a dataset by name (idempotent).

close

close() -> None

Close the underlying duckdb connection.

execute

execute(query: str) -> None

Execute a statement (e.g. COPY), auto-attaching referenced datasets.

sql

sql(query: str) -> duckdb.DuckDBPyRelation

Run a query, auto-attaching datasets it references.

connect

connect(storage: str = DEFAULT_STORAGE, *, user_agent: str | None = None) -> Connection

Open a read-only connection to Queria's public catalogs.

PARAMETER	DESCRIPTION
`storage`	Base URL (or local path) of the catalog storage. TYPE: `str` DEFAULT: `DEFAULT_STORAGE`
`user_agent`	HTTP user agent reported to the storage. Defaults to `queria-python/<version>`. TYPE: `str \| None` DEFAULT: `None`

queria.core.Connection