データを公開する

自分のデータを Queria のカタログに載せる手順と、宣言ファイルの書き方

自分のデータを Queria のカタログに載せる手順です。必要なのは 2 つ、データそのものと、それが何なのかを説明する宣言ファイルです。

何を用意すればよいか

Queria が配信するのは DuckLake 形式のカタログです。データを DuckLake のテーブルとして書き出すところまでがビルドの仕事で、ファイルを置くだけでは公開できません。

書き出す道具は選びません。DuckLake に書ければ何でも構いません。元データの形式も、DuckDB が読めるものであれば問いません（CSV・Parquet・JSON・Excel、API から取得したものなど）。

全体の流れ

uvx queria login                  # 認証
uvx queria create my-dataset      # データセットを登録（既定は非公開）
# dataset.yml と *.table.yml を書く
uvx queria init                   # 初回のみ。ビルド先のカタログを作る
uvx queria sync -- <ビルドコマンド>  # 取得 → ビルド → 公開

uvx queria login で初めてログインするときは、ブラウザでハンドルを決めます。データセットはそのハンドルのものになり、queria.io/datasets/<ハンドル>/<データセット名> で公開されます。

データセットの作成（queria create）と公開（queria push と、それを含む queria sync）には、「データセットの変更を許可する」を有効にしたトークンが要ります。queria login の承認画面では既定で有効なので、個人のマシンからなら追加の設定は要りません。CI で公開する場合は、API トークン画面で有効にしたトークンを発行し、環境変数 QUERIA_TOKEN で渡してください。詳しくは認証を参照してください。

組織アカウントに所属している場合は、--owner で作成先を指定できます。省略すると自分のハンドルのものになります。組織として継続的に更新する場合は、管理者が queria.io/accounts/<組織のハンドル>/settings/tokens で発行する組織のサービストークンを使います。発行した人が組織を抜けても止まりません。

uvx queria create my-dataset --owner my-org

同じ名前のデータセットが複数のアカウントにあるときは、どちらを指すか決まらないため queria edit や queria delete が中断します。その場合は <ハンドル>/<データセット名> の形で指定してください。

queria sync は「公開済みのカタログを取得 → あなたのビルドを実行 → 結果を公開」を 1 コマンドで行います。-- の後ろは何でも構いません。

uvx queria sync -- python main.py
uvx queria sync -- dbt build

公開前に宣言とデータが食い違っていないか確かめられます。

uvx queria validate           # 宣言を実データと突き合わせる
uvx queria validate --strict  # 警告も失敗として扱う（CI 向け）

宣言ファイル

2 種類あります。置き場所のディレクトリ名は自由で、何についての宣言かは中身（schema と name）が決めます。

# dataset.yml
spec_version: "0.1"
name: calendar
title: 日本の暦データ
description: 1955年〜2027年の日付スパインに祝日・曜日・和暦・会計年度を付与したもの
language: ja
licenses: [CC-BY-4.0]
contributors:
  - title: 内閣府
    roles: [rightsHolder]

# models/main/mart_calendar.table.yml
schema: main
name: mart_calendar
title: 日本の暦
description: 祝日・曜日・和暦・会計年度を付与した日付スパイン
published: true
fields:
  - name: date
    title: 日付

列の型は書きません。 型・列順・NULL 許容は実データから読み取られるので、データとずれることがありません。

同じ列構成のテーブルが並ぶ場合は、1 ファイルに複数書いて YAML アンカーで共通部分をくくれます。

_fields: &fields
  - { name: area, title: 地域コード }
  - { name: value, title: 統計値, semantic: { role: measure, agg: sum } }
tables:
  - { schema: ssds, name: a_population, title: 人口・世帯, fields: *fields }
  - { schema: ssds, name: b_land,       title: 自然環境, fields: *fields }

キーの列を宣言する

行を何で識別しているかを semantic で宣言すると、検索の「キーの列」とキーの名前を使った列の条件で、その表が見つかるようになります。同じキーは、データセットをまたいで突き合わせられる列にだけ付けます。

fields:
  - name: municipality_code
    title: 全国地方公共団体コード
    semantic: { role: entity, name: city }

name に書けるキーは次のとおりです。コードの桁が違っても、変換すれば突き合わせられる列（5 桁と検査数字付き 6 桁の団体コードなど）には同じキーを付けます。

この一覧に無いキーを書くと、queria compile が警告します。公開は止まりませんが、検索のキーの列には出ません。

公開設定にすると何が起きるか

データセットには公開と非公開があります。非公開のあいだは自分（と組織のメンバー）にしか見えません。切り替えは次のとおりです。

uvx queria create my-dataset --public   # 作るときに指定する
uvx queria edit my-dataset --visibility public   # あとから変える

公開にすると、次の場所に載ります。

どの画面にも提供者のハンドルが出ます。 一覧のカードにも、データセットのページにも <ハンドル> / <データセット名> の形で表示されます。誰が公開したデータかを読み手が必ず分かるようにするためです。

これらのページは検索エンジンに収集されることがあります。非公開に戻すと Queria 上の掲載は止まりますが、検索エンジンの索引から消えるまでには時間がかかります。

公開設定の切り替えは、データの配信に反映されるまで最大 60 秒かかります。 非公開に戻した直後の 60 秒は、それまでに配信元を知っていた相手からデータを読めることがあります。

詰まりやすいところ

ライセンスは推測されません。 レジストリに無い ID を書くと validate が止まります。省略もできますが、その場合は全権利を留保することになり、利用者が何をしてよいかは Queria の利用規約に委ねられます。validate が警告します。

*.table.yml を dbt の model-paths の下に置くなら、.dbtignore に *.table.yml を足してください。 dbt はその下の .yml を自分のプロパティファイルとして読もうとして失敗します。validate が教えてくれます。

行数の少ないテーブルは parquet が書かれないことがあります。 DuckLake の既定ではカタログの中に値が埋め込まれるため、データファイルが 1 つも生成されないことがあります。ビルド側で DATA_INLINING_ROW_LIMIT を 0 にしてください。

15 分を超えるビルドは認証情報を取り直してください。 書き込みに使う認証情報は 15 分で切れます。DuckDB は期限を見て取り直さないので、それより長いビルドは途中から書けなくなり、403 SignatureDoesNotMatch で止まります。queria の Secret を書き込みの切れ目で呼んでください。

from queria import Secret

secret = Secret(conn)
secret.install()

for batch in batches:
    secret.refresh_if_due()   # 間隔が来るまで何もしません
    write(batch)

refresh_if_due() はトランザクションの外で呼んでください。また、1 つの文が 15 分を超える場合は救えません。 その文を分けてください。

書き込み用の認証情報は、1 つのアカウントにつき同時に 5 本までです。 queria sync は 1 回のビルドで複数本を使うので、CI と手元で同じアカウントのビルドを並べると、push が HTTP 429（Too many credential requests）で止まることがあります。ビルドの失敗ではありません。エラーに次の 1 本が切れる時刻が出るので、その時刻を過ぎてから再実行してください。

何を書くかで迷ったら

説明をどの階層に書くかには規約があります。説明の書き分けを参照してください。

エージェントに任せる

公開手順と説明の書き方は、それぞれエージェントスキルとしても配布しています。導入方法は Queria スキルを参照してください。

• queria-publish-dataset — 登録からビルド、公開まで
• queria-describe-dataset — 何をどこに書くか