queria 0.1.0__tar.gz

queria-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync
+      - run: uv run pytest
+      - run: uv run zensical build

queria-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "zensical.toml"
+      - "CHANGELOG.md"
+      - "src/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv run zensical build
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

queria-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  workflow_dispatch:
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+      actions: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - uses: python-semantic-release/python-semantic-release@v9
+        id: release
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - if: steps.release.outputs.released == 'true'
+        uses: astral-sh/setup-uv@v7
+
+      - if: steps.release.outputs.released == 'true'
+        run: uv build
+
+      - if: steps.release.outputs.released == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - if: steps.release.outputs.released == 'true'
+        run: gh workflow run docs.yml --ref main
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

queria-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+site/
+.pytest_cache/
+*.egg-info/

queria-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# CHANGELOG
+
+
+## v0.1.0 (2026-07-11)
+
+### Chores
+
+- Update org references from flo8s to queria-io
+  ([`ca647a6`](https://github.com/queria-io/queria-cli/commit/ca647a6880dff76e12aef7af5daeb5b189fa64cf))
+
+### Continuous Integration
+
+- Test, docs deploy, and release workflows
+  ([`5686528`](https://github.com/queria-io/queria-cli/commit/5686528933dfb1a58235332c160a1a6c2c4f4c9e))
+
+### Documentation
+
+- Documentation site for docs.queria.io
+  ([`5045b94`](https://github.com/queria-io/queria-cli/commit/5045b94cfeddd0bbd4e383f823eef3aad8b49881))
+
+### Features
+
+- **cli**: Subcommand interface with table/csv/json/jsonl and file output
+  ([`b1638a0`](https://github.com/queria-io/queria-cli/commit/b1638a0fc64d54ea437912c8830db6ca7be34a80))
+
+- **core**: Read-only connection with auto-attach and catalog queries
+  ([`cad8c13`](https://github.com/queria-io/queria-cli/commit/cad8c13671d67e00490698f90ac8152e1e677a1b))
+
+- **mcp**: Stdio MCP server with row and payload caps
+  ([`630ec15`](https://github.com/queria-io/queria-cli/commit/630ec15b1fd3239ddf56db9c1ca711249e8dc181))

queria-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flo8s
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

queria-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: queria
+Version: 0.1.0
+Summary: Query Japanese open data on Queria (data.queria.io) from the terminal, Python, and MCP
+Project-URL: Homepage, https://docs.queria.io/
+Project-URL: Documentation, https://docs.queria.io/
+Project-URL: Repository, https://github.com/queria-io/queria-cli
+Project-URL: Changelog, https://docs.queria.io/resources/changelog/
+Author: flo8s
+License-Expression: MIT
+License-File: LICENSE
+Keywords: duckdb,ducklake,japan,mcp,opendata
+Requires-Python: >=3.10
+Requires-Dist: duckdb<2.0,>=1.5.4
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# queria
+
+Query Japanese open data on [Queria](https://data.queria.io) from the terminal, Python, and MCP.
+
+[Queria](https://data.queria.io) が公開する日本のオープンデータ（e-Stat、国土数値情報、EDINET、気象庁ほか）を、ターミナル・Python・MCP から read-only で探索するクライアントです。データは DuckLake 形式で公開されており、計算はすべて手元の DuckDB で行われます。
+
+## インストール
+
+```bash
+uvx queria list          # インストール不要で実行
+pip install queria       # または通常インストール
+```
+
+Python 3.10+ が必要です。
+
+## 使い方
+
+```bash
+queria list                              # データセット一覧
+queria search 人口                        # キーワード検索
+queria schema e_stat                     # テーブル一覧
+queria columns e_stat mart_population    # カラム一覧
+queria sql "SELECT * FROM zipcode.main.zipcodes LIMIT 10"
+queria sql "SELECT * FROM zipcode.main.zipcodes" --out zipcodes.parquet
+```
+
+テーブルは `<dataset>.<schema>.<table>` で参照します。参照したデータセットは自動的に ATTACH されます。
+
+## Python API
+
+```python
+import queria
+
+with queria.connect() as conn:
+    conn.sql("SELECT * FROM catalog.main.mart_datasets").show()
+```
+
+## MCP サーバー
+
+Claude Code / Claude Desktop / Cursor などの MCP クライアントから使えます:
+
+```json
+{
+  "mcpServers": {
+    "queria": {
+      "command": "uvx",
+      "args": ["--from", "queria[mcp]", "queria", "mcp"]
+    }
+  }
+}
+```
+
+## ドキュメント
+
+https://docs.queria.io/
+
+## License
+
+MIT

queria-0.1.0/README.md

@@ -0,0 +1,59 @@
+# queria
+
+Query Japanese open data on [Queria](https://data.queria.io) from the terminal, Python, and MCP.
+
+[Queria](https://data.queria.io) が公開する日本のオープンデータ（e-Stat、国土数値情報、EDINET、気象庁ほか）を、ターミナル・Python・MCP から read-only で探索するクライアントです。データは DuckLake 形式で公開されており、計算はすべて手元の DuckDB で行われます。
+
+## インストール
+
+```bash
+uvx queria list          # インストール不要で実行
+pip install queria       # または通常インストール
+```
+
+Python 3.10+ が必要です。
+
+## 使い方
+
+```bash
+queria list                              # データセット一覧
+queria search 人口                        # キーワード検索
+queria schema e_stat                     # テーブル一覧
+queria columns e_stat mart_population    # カラム一覧
+queria sql "SELECT * FROM zipcode.main.zipcodes LIMIT 10"
+queria sql "SELECT * FROM zipcode.main.zipcodes" --out zipcodes.parquet
+```
+
+テーブルは `<dataset>.<schema>.<table>` で参照します。参照したデータセットは自動的に ATTACH されます。
+
+## Python API
+
+```python
+import queria
+
+with queria.connect() as conn:
+    conn.sql("SELECT * FROM catalog.main.mart_datasets").show()
+```
+
+## MCP サーバー
+
+Claude Code / Claude Desktop / Cursor などの MCP クライアントから使えます:
+
+```json
+{
+  "mcpServers": {
+    "queria": {
+      "command": "uvx",
+      "args": ["--from", "queria[mcp]", "queria", "mcp"]
+    }
+  }
+}
+```
+
+## ドキュメント
+
+https://docs.queria.io/
+
+## License
+
+MIT

queria-0.1.0/docs/CNAME

@@ -0,0 +1 @@
+docs.queria.io

queria-0.1.0/docs/getting-started/installation.md

@@ -0,0 +1,37 @@
+---
+title: インストール
+---
+
+# インストール
+
+queria は PyPI で配布される Python パッケージです。Python 3.10+ が必要です。
+
+## uvx（推奨）
+
+[uv](https://docs.astral.sh/uv/) があればインストール不要で実行できます:
+
+```bash
+uvx queria list
+```
+
+MCP サーバーを使う場合は `mcp` extra を付けます:
+
+```bash
+uvx --from 'queria[mcp]' queria mcp
+```
+
+## pip / pipx
+
+```bash
+pip install queria
+# MCP サーバーも使う場合
+pip install 'queria[mcp]'
+```
+
+```bash
+pipx install queria
+```
+
+## 依存関係
+
+依存は `duckdb>=1.5.4` のみです。このピンは Queria が公開する DuckLake format 1.0 を読むために必要なバージョンで、詳細は[互換性ポリシー](../guide/compatibility.md)を参照してください。

queria-0.1.0/docs/getting-started/quickstart.md

@@ -0,0 +1,51 @@
+---
+title: クイックスタート
+---
+
+# クイックスタート
+
+探索 → クエリ → 出力までの基本フローです。以下は `uvx queria` でも `queria`（インストール済み）でも同じです。
+
+## 1. データセットを探す
+
+```bash
+queria list
+queria search 人口
+```
+
+## 2. テーブルとカラムを調べる
+
+```bash
+queria schema e_stat
+queria columns e_stat mart_population_prefecture
+```
+
+## 3. SQL を実行する
+
+テーブルは `<dataset>.<schema>.<table>` で参照します。参照したデータセットは自動的に ATTACH されるので、事前準備は不要です。
+
+```bash
+queria sql "
+  SELECT date, holiday_name
+  FROM calendar.main.mart_calendar
+  WHERE is_holiday AND date BETWEEN DATE '2026-01-01' AND DATE '2026-12-31'
+  ORDER BY date
+"
+```
+
+DuckDB の SQL がそのまま使えます。データセットをまたぐ JOIN も可能です。
+
+## 4. 結果をファイルに出力する
+
+```bash
+queria sql "SELECT * FROM zipcode.main.zipcodes" --out zipcodes.parquet
+queria sql "SELECT * FROM zipcode.main.zipcodes" --out zipcodes.csv
+```
+
+stdout の形式は `--format table|csv|json|jsonl` で切り替えられます（デフォルトは `table`）。
+
+## 次のステップ
+
+- [CLI ガイド](../guide/cli.md) — オプションの詳細
+- [MCP サーバー](../guide/mcp.md) — エージェントからの利用
+- [Python API](../reference/python-api.md) — ノートブックやスクリプトからの利用

queria-0.1.0/docs/guide/cli.md

@@ -0,0 +1,49 @@
+---
+title: CLI ガイド
+---
+
+# CLI ガイド
+
+## コマンド体系
+
+| コマンド | 役割 |
+|---|---|
+| `queria list` | データセット一覧 |
+| `queria search <keyword>` | タイトル・説明のキーワード検索 |
+| `queria schema <dataset>` | データセットのテーブル一覧 |
+| `queria columns <dataset> [table]` | カラム一覧（table 指定で絞り込み） |
+| `queria sql "<query>"` | read-only SQL の実行 |
+| `queria mcp` | stdio MCP サーバーの起動 |
+
+## 出力形式
+
+`--format` で stdout の形式を選べます:
+
+- `table`（デフォルト）— 人間向けの整形テーブル
+- `csv` — ヘッダー付き CSV
+- `json` — レコードの JSON 配列
+- `jsonl` — 1行1レコードの JSON（ストリーム処理向け）
+
+```bash
+queria list --format json | jq '.[].datasource'
+```
+
+## ファイル出力
+
+`--out` で結果をファイルに書き出します。拡張子で形式が決まります（`.parquet` / `.csv`）。大きな結果は stdout ではなく `--out` を使ってください。
+
+```bash
+queria sql "SELECT * FROM e_stat.main.mart_population_prefecture" --out pop.parquet
+```
+
+## データセットの自動 ATTACH
+
+`sql` の中で `<dataset>.<schema>.<table>` を参照すると、未接続のデータセットは自動的に ATTACH されます。`information_schema` を引く場合など自動検出が効かないケースでは `--datasets` で明示できます:
+
+```bash
+queria sql "SELECT * FROM information_schema.tables WHERE table_catalog = 'jma'" --datasets jma
+```
+
+## read-only ガードについて
+
+`sql` は SELECT / WITH / DESCRIBE / SHOW / PRAGMA / EXPLAIN / SUMMARIZE で始まる文のみ受け付けます。これは事故防止のための簡易ガードであり、本質的な保護はカタログの READ_ONLY ATTACH です。公開カタログへの書き込みはエンジンレベルで失敗します。queria はサンドボックスではありません — 実行環境のローカルリソースへのアクセスは DuckDB の通常の権限に従います。

queria-0.1.0/docs/guide/compatibility.md

@@ -0,0 +1,38 @@
+---
+title: 互換性ポリシー
+---
+
+# 互換性ポリシー
+
+## データスキーマの安定性
+
+Queria が公開するテーブル（`catalog` の `mart_*` を含む）は、現在 pre-stable です。データ品質やモデリングの改善のため、テーブル名・カラム名・型は予告なく変更されることがあります。
+
+利用が定着したことを確認できた段階で、スキーマを公開 API とみなし、後方互換の維持を努力目標として宣言する予定です。CI やバッチで queria に依存する場合は、この前提を踏まえてください。変更は [Changelog](../resources/changelog.md) と各データセットのリリースノートで告知します。
+
+## DuckLake フォーマットと duckdb のバージョン
+
+Queria のカタログは DuckLake format 1.0 で公開されています。これを読むには duckdb >= 1.5.4 が必要で、queria パッケージはこのピンを依存関係として管理します。
+
+カタログのフォーマットが上がる場合は、次を1セットで行います:
+
+1. 本番カタログの移行
+2. Web（DuckDB WASM)の更新
+3. queria パッケージの新バージョンのリリース
+4. 互換マニフェスト（下記）の更新
+
+インストール済みの古い queria はフォーマット更新後に接続できなくなる可能性があります。`uvx queria` で実行している場合は最新版が使われるため、通常は意識する必要はありません。
+
+## 互換マニフェスト
+
+`https://data.queria.io/meta.json` に、カタログのフォーマットと必要なクライアントバージョンを記述したマニフェストを公開しています:
+
+```json
+{
+  "ducklake_format": "1.0",
+  "min_duckdb": "1.5.4",
+  "min_cli": "0.1.0"
+}
+```
+
+queria はカタログへの接続に失敗した場合のみこのマニフェストを参照し、「duckdb / queria をどのバージョンに上げればよいか」を示すエラーメッセージを表示します。正常時には参照しないため、マニフェストの有無が動作に影響することはありません。

queria-0.1.0/docs/guide/direct-access.md

@@ -0,0 +1,42 @@
+---
+title: 直接アクセス
+---
+
+# 直接アクセス（素の DuckDB で読む）
+
+queria は利便性レイヤーであり、Queria のデータは標準の DuckLake 形式で公開されているため、duckdb >= 1.5.4 があればどの言語・環境からでも直接読めます。
+
+## ATTACH の書き方
+
+各データセットは `https://data.queria.io/<dataset>/` 配下に公開されています:
+
+```sql
+INSTALL ducklake; LOAD ducklake;
+INSTALL httpfs; LOAD httpfs;
+
+ATTACH 'ducklake:https://data.queria.io/zipcode/ducklake.duckdb' AS zipcode (
+    READ_ONLY,
+    DATA_PATH 'https://data.queria.io/zipcode/ducklake.duckdb.files/',
+    OVERRIDE_DATA_PATH true
+);
+
+SELECT * FROM zipcode.main.zipcodes LIMIT 10;
+```
+
+メタデータカタログ（データセット・テーブル・カラムの一覧）は `catalog` データセットにあります:
+
+```sql
+ATTACH 'ducklake:https://data.queria.io/catalog/ducklake.duckdb' AS catalog (
+    READ_ONLY,
+    DATA_PATH 'https://data.queria.io/catalog/ducklake.duckdb.files/',
+    OVERRIDE_DATA_PATH true
+);
+
+SELECT datasource, title FROM catalog.main.mart_datasets;
+```
+
+## 注意点
+
+- DuckDB CLI（対話シェル）の同梱 ducklake 拡張はバージョンによって古い場合があります。`uvx duckdb` などで 1.5.4 以上を使ってください。
+- GEOMETRY カラムを含むデータセット（nlftp、e_stat の境界データなど）には `INSTALL spatial; LOAD spatial;` が必要です。
+- Python では `queria.connect()` がこの一連の処理（拡張ロード・ATTACH・自動 ATTACH）を代行します。[Python API リファレンス](../reference/python-api.md)を参照してください。

queria-0.1.0/docs/guide/mcp.md

@@ -0,0 +1,48 @@
+---
+title: MCP サーバー
+---
+
+# MCP サーバー
+
+`queria mcp` は stdio の MCP サーバーです。Claude Code、Claude Desktop、Cursor などの MCP クライアントから Queria のデータを探索・クエリできます。
+
+## セットアップ
+
+### Claude Code
+
+```bash
+claude mcp add queria -- uvx --from 'queria[mcp]' queria mcp
+```
+
+### Claude Desktop / Cursor など（JSON 設定）
+
+```json
+{
+  "mcpServers": {
+    "queria": {
+      "command": "uvx",
+      "args": ["--from", "queria[mcp]", "queria", "mcp"]
+    }
+  }
+}
+```
+
+## 提供ツール
+
+| ツール | 役割 |
+|---|---|
+| `list_datasets` | データセット一覧 |
+| `search_datasets` | キーワード検索 |
+| `get_schema` | テーブル一覧 |
+| `get_columns` | カラム一覧 |
+| `query` | read-only SQL の実行 |
+
+詳細な引数と挙動は [MCP ツールリファレンス](../reference/mcp-tools.md)を参照してください。
+
+## 結果の上限について
+
+`query` の結果は行数（デフォルト 100、最大 1000）とペイロードサイズ（約 1MB）で打ち切られます。これはエージェントのコンテキストを守るための仕様です。打ち切られた場合は `truncated: true` とヒントが返るので、集計や LIMIT で絞るか、バルク抽出には CLI の `--out` を使ってください。
+
+## スキルとの関係
+
+Claude Code では配布用スキル（queria-io/queria-skill）も利用できます。スキルはカタログの構造や活用パターンの知識を含むため、Claude Code では スキル + CLI の組み合わせを推奨します。MCP サーバーは Claude Code 以外のクライアントで使う場合の選択肢です。

queria-0.1.0/docs/index.md

@@ -0,0 +1,32 @@
+---
+title: Home
+---
+
+# Queria Docs
+
+[Queria](https://data.queria.io) は、日本のオープンデータ（e-Stat、国土数値情報、EDINET、気象庁ほか）を DuckLake 形式で公開するデータカタログです。データはすべて read-only で公開されており、クエリの計算は手元の DuckDB（ブラウザでは DuckDB WASM）で行われます。
+
+このサイトは Queria をターミナル・Python・MCP から使うためのドキュメントです。データセット個別のスキーマやガイドは[カタログ UI](https://data.queria.io) を参照してください。
+
+## はじめる
+
+インストール不要で、まず1クエリ:
+
+```bash
+uvx queria list
+uvx queria sql "SELECT * FROM zipcode.main.zipcodes LIMIT 10"
+```
+
+## 学ぶ
+
+- [クイックスタート](getting-started/quickstart.md) — 探索から Parquet 出力まで5分で
+- [CLI ガイド](guide/cli.md) — コマンド体系と使い分け
+- [MCP サーバー](guide/mcp.md) — Claude Code / Cursor などからの利用
+- [直接アクセス](guide/direct-access.md) — 素の DuckDB で ATTACH する方法
+- [互換性ポリシー](guide/compatibility.md) — スキーマとバージョンの安定性について
+
+## リファレンス
+
+- [CLI リファレンス](reference/cli.md)
+- [Python API リファレンス](reference/python-api.md)
+- [MCP ツールリファレンス](reference/mcp-tools.md)

queria-0.1.0/docs/reference/cli.md

@@ -0,0 +1,73 @@
+---
+title: CLI リファレンス
+---
+
+# CLI リファレンス
+
+## 共通オプション
+
+| オプション | 説明 |
+|---|---|
+| `--storage-url URL` | カタログのベース URL（デフォルト: `https://data.queria.io`） |
+| `--version` | バージョンを表示 |
+
+## 出力オプション（list / search / schema / columns / sql 共通）
+
+| オプション | 説明 |
+|---|---|
+| `--format {table,csv,json,jsonl}` | stdout の形式（デフォルト: `table`） |
+| `--out PATH` | 結果を `.csv` / `.parquet` ファイルに書き出す（`--format` は無視される） |
+
+## queria list
+
+公開されている全データセットを一覧します。
+
+```bash
+queria list [--format FMT] [--out PATH]
+```
+
+## queria search
+
+タイトルと説明に対するキーワード検索です（大文字小文字を区別しない部分一致）。
+
+```bash
+queria search <keyword> [--format FMT] [--out PATH]
+```
+
+## queria schema
+
+データセットのテーブル・ビュー一覧を表示します。
+
+```bash
+queria schema <dataset> [--format FMT] [--out PATH]
+```
+
+## queria columns
+
+データセットのカラム一覧を表示します。テーブル名を指定すると絞り込めます。
+
+```bash
+queria columns <dataset> [table] [--format FMT] [--out PATH]
+```
+
+## queria sql
+
+read-only SQL を実行します。`<dataset>.<schema>.<table>` で参照されたデータセットは自動 ATTACH されます。
+
+```bash
+queria sql "<query>" [--datasets DS1,DS2] [--format FMT] [--out PATH]
+```
+
+| オプション | 説明 |
+|---|---|
+| `--datasets` | 事前に ATTACH するデータセット（通常は自動検出されるため不要） |
+
+SELECT / WITH / DESCRIBE / SHOW / PRAGMA / EXPLAIN / SUMMARIZE で始まる文のみ受け付けます。
+
+## queria mcp
+
+stdio MCP サーバーを起動します。`mcp` extra が必要です（[MCP サーバー](../guide/mcp.md)参照）。
+
+```bash
+queria [--storage-url URL] mcp
+```