---
title: Python API リファレンス
description: queria パッケージの Python API
---

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

## 概要

```python
import queria

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

# データそのもの
with queria.connect() as conn:
    # 参照したデータセットは自動 ATTACH される
    df = conn.sql("""
        SELECT date, holiday_name
        FROM calendar.calendar.day
        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()` が返す宣言は、データセットを公開するときに書く `queria.yml` とテーブルの Markdown に対応します（[データセットを公開する](/publish)）。

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

## カタログ

### queria.list_datasets()

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

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

```python
import pandas as pd

pd.DataFrame(queria.list_datasets())
```

行のキー:

| キー | 説明 |
|---|---|
| `handle` | 公開しているアカウント |
| `name` | データセット名。SQL で `<name>.<schema>.<table>` と書くときの名前 |
| `qualified_name` | `<handle>/<name>` |
| `title` / `description` | タイトルと説明 |
| `keywords` | キーワードの配列 |
| `licenses` | ライセンスの配列。宣言が無いときはキーごと現れません |
| `visibility` | `public` または `private` |
| `catalog_url` | DuckLake カタログの URL |
| `page_url` | queria.io のデータセットページ |
| `bytes` | 公開されているデータの総バイト数 |
| `updated_at` | 最後に公開された時刻 |

### queria.search()

```python
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`](/reference/cli#queria-search) の `--column` / `--key` / `--geo` と同じです。どれかを渡せば `keyword` は省略できます。

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

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

| キー | 説明 |
|---|---|
| `datasets` | 当たったデータセットの行（`list_datasets()` と同じ形） |
| `entries` | 見つかったテーブルと列。`entry_type` / `qualified_name` / `schema_name` / `table_name` / `column_name` / `title` / `description`。テーブルには収録期間の `period_start` / `period_end` とキーの `keys` も付く |
| `has_more` | `limit` で打ち切られたかどうか |

### queria.info()

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

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

| キー | 説明 |
|---|---|
| `dataset` | `list_datasets()` と同じ形の行 |
| `declaration` | 公開された宣言。ライセンス・出典・更新頻度・テーブルとその列がすべてここに入っています |

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

### queria.tables()

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

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

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

### queria.columns()

```python
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` が書き込む設定ファイル）。

カタログの関数のリクエストには、CLI と同じく環境変数 `QUERIA_EXTRA_HEADERS` のヘッダーも追加されます（[CLI リファレンス](/reference/cli)参照）。

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

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

## 接続

### queria.connect()

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

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

| 引数 | 説明 |
|---|---|
| `storage` | カタログストレージのベース URL（またはローカルパス） |
| `user_agent` | ストレージに報告する HTTP User-Agent。デフォルトは `queria-python/<version>` |
| `token` | ストレージへの全リクエストに Bearer Authorization ヘッダとして付与する API トークン。レートリミットの上限が上がり、**自分の非公開データセットを ATTACH できます**（[認証](/authentication)参照） |
| `api_url` | データセット名からその持ち主を引くときに使う queria.io のベース URL。通常は指定しません。既定以外の `storage` を指すときは、これを渡さないとハンドル付きの名前が解決されず、短い名前として扱われます |

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

### Connection

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

```python
with queria.connect() as conn:
    conn.sql("SELECT * FROM calendar.calendar.day LIMIT 10").show()
```

#### Connection.sql()

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

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

#### Connection.execute()

```python
Connection.execute(query: str) -> None
```

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

#### Connection.attach()

```python
Connection.attach(dataset: str, alias: str | None = None, version: str | None = None) -> None
```

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

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

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

```python
conn.attach("alice/sales", alias="a")
conn.attach("bob/sales", alias="b")
conn.sql("SELECT * FROM a.main.orders JOIN b.main.orders USING (id)")
```

`version` にバージョン ID かタグを渡すと、main ではなく以前のバージョンを読みます。バージョン ID は `queria dataset versions` で確認できます。同じデータセットの 2 つのバージョンを一緒に読むときは、`alias` で別の名前を付けます。存在しないバージョンを渡すと `ValueError` になります。

```python
conn.attach("queria/calendar", alias="old", version="01a1b2b4-954f-7d0b-ad59-ae26765e29a6")
conn.sql("SELECT count(*) FROM old.calendar.day")
```

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

#### Connection.close()

```python
Connection.close() -> None
```

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