Python API リファレンス

queria パッケージの Python API

queria は Queria のデータを読む Python パッケージも公開しています。ノートブックやスクリプトから、サブプロセスなしでカタログを引き、クエリを実行できます。

概要

import queria

# 何が公開されていて、何が入っているか
queria.list_datasets()
queria.tables("calendar")
queria.columns("calendar", "mart_calendar")

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

カタログを引く関数と connect() は別々に使えます。前者は queria.io に HTTP で問い合わせ、後者は data.queria.io の DuckLake に接続します。データセットの一覧を見るだけなら接続は開きません。

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

安定性

公式 API は次のとおりです。

• カタログ関数 queria.list_datasets() / search() / info() / tables() / columns() と、例外 queria.CatalogError
• queria.connect() と Connection の公開メソッド（sql / execute / attach / close）
• 定数 queria.DEFAULT_STORAGE（デフォルトのカタログベース URL）と queria.__version__

カタログ関数が返す dict は、下の表に挙げたキーが無くなることはありません。キーが増えることはあります。licenses のように宣言が無いと現れないキーがあるので、row.get(...) で読んでください。

info() と tables() が返す宣言は、データセットを公開するときに書く dataset.yml と *.table.yml に対応します（データセットを公開する）。

それ以外のモジュール内部は予告なく変わることがあります。

カタログ

queria.list_datasets()

queria.list_datasets(
    *,
    limit: int | None = None,
    token: str | None = None,
) -> list[dict]

読めるデータセットをすべて返します。匿名なら公開データセット、トークンがあれば自分の非公開データセットも含まれます。limit を渡さなければ全件です（1 リクエストの上限を超える分はページを辿ります）。

import pandas as pd

pd.DataFrame(queria.list_datasets())

行のキー:

queria.search()

queria.search(
    keyword: str | None = None,
    *,
    entry_type: str | None = None,
    limit: int = 50,
    columns: Sequence[str] = (),
    keys: Sequence[str] = (),
    geo: bool = False,
    token: str | None = None,
) -> dict

データセット・テーブル・カラムを横断して検索します。空白で区切ったすべての語を含むものだけが返るので、語を足すと絞り込みになります。entry_type に dataset / table / column を渡すと種別を絞れます。

columns / keys / geo は表が持つ列で絞ります。意味は queria search の --column / --key / --geo と同じです。どれかを渡せば keyword は省略できます。

queria.search(columns=["町丁目", "人口"])          # 町丁目と人口の列を持つ表
queria.search("公園", keys=["city"], geo=True)

返り値は 3 つのキーを持ちます。

queria.info()

queria.info(name: str, *, token: str | None = None) -> dict

データセット 1 件のカタログ行と、公開されている宣言を返します。

name はデータセット名（e_stat）でも、アカウントまで含めた名前（queria/e_stat）でも構いません。同じ名前を複数のアカウントが公開している場合、データセット名だけでは決まらないのでエラーになり、候補が示されます。

queria.tables()

queria.tables(name: str, *, token: str | None = None) -> list[dict]

公開されているテーブルを返します。宣言に書かれていても公開されていないテーブルは含まれません。

各要素は宣言のテーブル定義そのもので、schema と name でテーブルを指定でき、列は fields に入れ子で入っています。列を平坦に取りたいときは columns() を使ってください。

queria.columns()

queria.columns(
    name: str,
    table: str | None = None,
    *,
    token: str | None = None,
) -> list[dict]

公開されているテーブルの列を平坦な配列で返します。table を渡すと 1 テーブルに絞れます。

各要素は宣言の列定義（name / type / description と、宣言されていれば title / nullable / index / semantic）に、schema_name と table_name を加えたものです。存在しないテーブル名を渡すとエラーになります。

トークン

カタログの関数はどれも token を取ります。省略すると CLI と同じ順序で解決します（環境変数 QUERIA_TOKEN、次に queria login が書き込む設定ファイル）。

これらの関数はトークンの有無で答えが変わります。認証すると自分の非公開データセットが結果に含まれるためです。トークンを保存しているマシンで公開データセットだけを見たいときは、token="" を渡してください。

connect() の token も同じ値です。こちらはストレージへのリクエストに付いてレートリミットの上限を上げるほか、非公開データセットを ATTACH するときの持ち主の照会にも使われます（認証参照）。

接続

queria.connect()

queria.connect(
    storage: str = "https://data.queria.io",
    *,
    user_agent: str | None = None,
    token: str | None = None,
    api_url: str | None = None,
) -> Connection

Queria の公開カタログへの接続を開きます。

接続時に ducklake / httpfs 拡張をロードします。データセットの ATTACH は最初に参照したときに行われます。

Connection

コンテキストマネージャとして使うと、内部の duckdb 接続を確実にクローズできます:

with queria.connect() as conn:
    conn.sql("SELECT * FROM calendar.main.mart_calendar LIMIT 10").show()

Connection.sql()

Connection.sql(query: str) -> duckdb.DuckDBPyRelation

クエリを実行します。クエリが参照しているまだ未接続のデータセットは自動的に ATTACH されます。

Connection.execute()

Connection.execute(query: str) -> None

結果を返さない文（COPY など）を実行します。sql() と同様に、参照されたデータセットを自動 ATTACH します。

Connection.attach()

Connection.attach(dataset: str) -> None

データセットを名前で明示的に ATTACH します（冪等）。通常は sql() の自動 ATTACH に任せれば十分です。

sales のような短い名前と、alice/sales のようにハンドルを含む名前の両方を受け付けます。短い名前は queria.io に問い合わせて持ち主を決めるので、2 つのアカウントが同じ名前を公開しているときはハンドルまで書いてください（短い名前のままだと、どちらか分からない旨と候補を挙げた例外が上がります）。

SQL から参照する名前は、どちらで ATTACH しても短い名前です。alice/sales を ATTACH したあとは sales.main.… と書きます。同じ短い名前で別のデータセットを ATTACH することはできません。

非公開のデータセットを ATTACH するには connect(token=...) でトークンを渡してください。トークンが無いと、そのデータセットは存在しないものとして扱われます。

Connection.close()

Connection.close() -> None

内部の duckdb 接続をクローズします。