QueriaQueria

仕組み

「はじめに」でブラウザから操作したこと、「接続方法」でCLIから接続したことの裏側で何が起きているかを解説します。

3つの要素

Queriaは以下の3つの技術で構成されています。

  • DuckLake: テーブル定義とデータファイルの場所を管理するメタデータカタログ
  • Cloudflare R2: Parquetファイルを配信するオブジェクトストレージ
  • DuckDB: SQLクエリエンジン（ブラウザではWASM版、CLIではネイティブ版）

データがどこにあるか

データの実体はCloudflare R2上のParquetファイルです。DuckLakeカタログ（.duckdb ファイル）がテーブル名・カラム定義・Parquetファイルの場所を記録しています。

Cloudflare R2
├── tsukuba/
│   ├── ducklake.duckdb        ← DuckLakeカタログ（メタデータ）
│   └── data/
│       └── mart_tsukuba_population/
│           └── *.parquet      ← データの実体
├── k_oxon/
│   ├── ducklake.duckdb
│   └── data/...
└── zipcode/
    ├── ducklake.duckdb
    └── data/...

ブラウザで動く仕組み

「はじめに」でプレビューやSQLを実行したとき、以下の流れで処理されています。

ブラウザ
┌──────────────────────────────────────────────┐
│  Queria UI                                   │
│    ↓ SQL                                     │
│  DuckDB WASM                                 │
│    ↓ ATTACH                                  │
│  DuckLake拡張                                │
│    ↓ HTTPSでR2からデータ取得                   │
└──────────────────────────────────────────────┘
        ↓ HTTPS
┌──────────────────────────────────────────────┐
│  Cloudflare R2                               │
│  (カタログ + Parquetファイル)                  │
└──────────────────────────────────────────────┘

DuckDB WASMがブラウザ内で動作し、DuckLakeカタログに接続してR2からParquetファイルを直接取得します。サーバーサイドの処理は介在しません。

CLIから動く仕組み

「接続方法」で ATTACH コマンドを実行したときも、同じDuckLakeカタログに接続しています。

ローカルマシン
┌──────────────────────────────────────────────┐
│  DuckDB CLI / Python                         │
│    ↓ ATTACH                                  │
│  DuckLake拡張                                │
│    ↓ HTTPSでR2からデータ取得                   │
└──────────────────────────────────────────────┘
        ↓ HTTPS
┌──────────────────────────────────────────────┐
│  Cloudflare R2                               │
│  (カタログ + Parquetファイル)                  │
└──────────────────────────────────────────────┘

ブラウザもCLIも、同じカタログ・同じデータにアクセスします。

データが公開されるまで

元データからQueriaに公開されるまでの流れです。

+-------------------+     +------------------+     +------------------+
|   データソース     | --> |  dbt パイプライン  | --> |  Cloudflare R2   |
| (CSV, オープン     |     | (変換・正規化)    |     | (Parquetファイル) |
|  データ)           |     +------------------+     +--------+---------+
+-------------------+                                       |
                                                            |
                              +-----------------------------+
                              |
                    +---------v----------+
                    |     DuckLake       |
                    | (メタデータカタログ) |
                    +---------+----------+
                              |
              +---------------+---------------+
              |                               |
    +---------v----------+          +---------v----------+
    |  DuckDB WASM       |          |  DuckDB CLI /      |
    | (ブラウザ)          |          |  プログラム         |
    +--------------------+          +--------------------+
  1. dbtパイプラインが元データ（CSVなど）を取り込み、分析しやすい形に変換
  2. 変換済みデータをParquet形式でCloudflare R2にアップロード
  3. DuckLakeカタログにテーブル定義とファイルの場所を登録
  4. ブラウザやCLIからDuckLakeカタログに接続すると、R2上のデータにアクセスできる