仕様 (v1)
tabledoc が読むファイル、その検査、プログラムに返す値を定めます。
tabledoc は、人が書くデータセットの説明 (YAML と Markdown、または dbt のプロジェクトの yml) の書き方を定め、検査し、ほかのプログラムのために読むツールです。特定の配信先には依存しません。tabledoc load は説明を DuckLake のカタログに、1 つのスキーマ (既定は _tabledoc) の普通のテーブルとして書き、tabledoc dump はそこからファイルを書き戻します。tabledoc export --markdown は、AI アシスタントや人が読む Markdown のファイルとして書き出します。書き手のファイルが正です。
コマンド
tabledoc validate: 書き手のファイルを検査しますtabledoc load: 検査してから、説明を DuckLake のカタログに書きます (DuckLake のカタログに書く)tabledoc dump: カタログが持つ説明のファイルを書きます (カタログからファイルを書く)tabledoc export --markdown: 検査してから、テーブルごとに 1 つの Markdown として書き出します (AI のために Markdown を書き出す)
エラーがあると終了コード 1 (--strict では警告も)、ファイルやカタログを読み書きできないときは 2 で終わります。
ファイル
パスは tabledoc.yml のあるフォルダ (以下ルート) からの相対パスです。
tabledoc.yml データセット (名前は固定)
README.md データセットの概要 (任意)
<schema>/<table>.yml テーブル
<schema>/<table>.md テーブルのガイド (任意。<schema>/<table>/README.md でも可)
<schema>/README.md スキーマのガイド (任意)
dbt のプロジェクトでは、テーブルの説明を dbt の yml に書き、ガイドをモデルの .sql の隣に同じ名前の .md で置きます (dbt のプロジェクト)。
. で始まるフォルダと、target/・dbt_packages/・node_modules/・.venv/ は読みません。
tabledoc.yml
データセット 1 つの説明です。
$schema: https://tabledoc.queria.io/schemas/dataset/v1.json
name: boj
title: 日本銀行 時系列統計
description: 日本銀行の時系列統計データ検索サイトの全ての統計です。
language: ja
topics: [日本銀行, 金利, 物価]
homepage: https://github.com/queria-io/dataset-boj
update_frequency: irregular
licenses:
- id: boj-copyright
title: 日本銀行 著作権・免責事項
url: https://www.boj.or.jp/about/copyright.htm
sources:
- title: 日本銀行 時系列統計データ検索サイト
path: https://www.stat-search.boj.or.jp/
contributors:
- title: 日本銀行
path: https://www.boj.or.jp/
roles: [rightsHolder]
spatial_coverage: [JP]
schemas:
- name: timeseries
title: 時系列統計
docs:
- docs/methodology.md
queria:
title_kana: ニチギンジケイレツトウケイ
| キー | 必須 | 内容 |
|---|---|---|
$schema |
必須 | 書式とバージョン |
name |
必須 | データセットの名前。^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$ |
schema |
tabledoc load が説明を書くスキーマ。既定は _tabledoc |
|
title・description・topics・homepage・language・issued・update_frequency |
language は BCP 47 のタグで、言語を付けずに書いた文字列の言語です (言語)。issued は YYYY-MM-DD |
|
repository |
データセットのソースコードのリポジトリの URL。例: https://github.com/queria-io/dataset-boj。省くと tabledoc load は Git の origin を使います |
|
licenses・sources・contributors・temporal_coverage・spatial_coverage |
テーブルのファイルに書くと、そのテーブルだけの値になります | |
schemas |
name・title・description・guide (スキーマのガイドのパス。省くと、あれば <name>/README.md)・docs (スキーマのほかの文書) |
|
docs |
データセットのほかの文書のパス | |
queria |
Queria だけが読むキー (読み手ごとのキー) | |
annotations |
ほかの読み手のキー。読み手の名前ごとに書きます |
テーブルのファイル
テーブル 1 つの説明です。$schema が https://tabledoc.queria.io/schemas/table/v1.json の YAML をテーブルのファイルとして読み、$schema の無い YAML (dbt の schema.yml など) は読みません。キーは dbt の models: の 1 項目と同じで、dbt に無いキー (title・primary_key・sources など) は同じ階層に並べます。
$schema: https://tabledoc.queria.io/schemas/table/v1.json
name: series
title: 系列の一覧
description: |-
検索サイトの全 DB の系列の一覧です。1 行が 1 系列です。
primary_key: [db, series_code]
sources:
- path: https://www.stat-search.boj.or.jp/
columns:
- name: db
title: DB 名
description: databases の db と同じ
dimension: categorical
- name: series_code
title: 系列コード
- name: last_update
title: 最終更新日
dimension: time
granularity: day
| キー | 内容 |
|---|---|
name |
テーブル名。省くとファイル名 |
table |
<schema>.<table>。置き場所より優先します (テーブルとの対応) |
title・description・topics |
topics は GitHub のリポジトリのトピックと同じものです。以前の名前の keywords も topics として読みます。Queria が読むので、queria: の topics として書き出します |
primary_key |
1 行を識別する列の並び |
licenses・sources・temporal_coverage・spatial_coverage |
データセットと違うときだけ書きます |
sql・depends_on |
dbt で作らないテーブルの、元の SQL と元のテーブル |
docs |
テーブルのほかの文書のパス |
columns |
name・title・description・asset と、semantic のキー (entity・dimension・granularity) |
metrics |
集計のしかた (semantic) |
queria・annotations |
読み手ごとのキー |
型・NULL・行数は書きません。構造はデータの置き場が持ちます。
asset: true は、列の値がその行に属するファイルのパスであることを表します。
テーブルとの対応
- 既定は置き場所で決めます。
<schema>/<table>.ymlにあるファイルは<schema>.<table>を説明します。ルートの直下に置いたファイルはmainスキーマです table: <schema>.<table>を書くと、置き場所よりそちらを優先します。ほかの深さに置くときは必須です- 同じテーブルを 2 つのファイルが説明していると、エラーになります
- テーブルのファイルを dbt の
models/に置いても、dbt は読みません (models:の外のキーを dbt は無視します)
言語
人が読む文字列は、複数の言語で書けます。値を BCP 47 のタグから文字列への対応で書くか、文字列だけを書きます。文字列だけのときは、データセットの language の言語として読みます。
language: ja
title:
ja: 日本銀行時系列統計
en: Bank of Japan time-series statistics
topics:
ja: [日本銀行, 金利]
en: [Bank of Japan, interest rates]
columns:
- name: db
title: {ja: データベース, en: Database}
description: databases の db と同じ
- tabledoc のキーのうち、値が文字列か文字列の一覧のものは、どちらの形でも書けます。たとえば
title・description・topics・homepageと、ライセンス・出典・作成者のtitle・url・pathです。一覧はタグから一覧への対応にします - 何かを指す値と、決まった語彙から選ぶ値は、値を 1 つだけ持ちます。
name・table・schema・repository・primary_key・entity のname・language・$schema・issued・update_frequency・dimension・granularity・agg・expr・sql・depends_on・spdx・id・roles・spatial_coverage・temporal_coverageと、ガイドとdocsのパスです。言語ごとに変えると、同じテーブル・列・ファイルを指せなくなるためです queria:とannotations:の下のキーは、それぞれの読み手が決めます- タグは BCP 47 として検査します。文字列が 1 つも無い対応はエラーです
- dbt のプロジェクトの yml では、
descriptionは文字列だけで、languageの言語として読みます。dbt はそこに対応を受け付けません tabledoc.readはこれらの値を常に対応で返します。文字列だけの値は{<language>: 文字列}、languageが無ければ{und: 文字列}になります
ガイドと文書
- テーブルのガイドは、テーブルのファイルと同じフォルダの同じ名前の
.md(series.ymlに対してseries.md) か、その名前のフォルダのREADME.md(series/README.md) です。フロントマターは書きません - データセットの概要はルートの
README.mdです。スキーマのガイドはschemas[].guide、無ければ<schema>/README.mdです - ほかの文書は
docsにパスを並べます。データセットの文書はtabledoc.yml、スキーマの文書はschemas[].docs、テーブルの文書はテーブルのファイルに書きます。パスはルートからの相対パスです - Markdown が相対パスで指すファイル (画像・PDF・ほかの文書) も一緒に送ります。ルートの外を指すリンクはエラー、無いファイルへのリンクは警告で、フォルダへのリンクは扱いません
- ビルドや保守の手順は
CONTRIBUTING.mdに書き、docsには並べません
データセットの中のパス
データセットの中では、フォルダ 1 つが説明の対象 1 つです。ルートはデータセット、<schema>/ はスキーマ、<schema>/<table>/ はテーブルです。フォルダの README.md がその対象の説明で、同じフォルダのほかの Markdown がその対象の文書です。書き手が手元のどこに置いても、tabledoc はファイルを次のパスに置きます。
| 書いたもの | データセットの中のパス |
|---|---|
README.md |
README.md |
docs の項目 |
<ファイル名> |
| スキーマのガイド | <schema>/README.md |
schemas[].docs の項目 |
<schema>/<ファイル名> |
| テーブルのガイド | <schema>/<table>/README.md |
テーブルの docs の項目 |
<schema>/<table>/<ファイル名> |
| 文書が指すファイル | ルートからのパスのまま |
- Markdown の文書の中の相対リンクのうち、別のパスに置いたファイルを指すものは、新しいパスを指すように書き換えます。
sha256とbytesは書き換えた後の文書の値です - データセットの中の同じパスに 2 つのファイルを置くことになるときはエラーです。1 つのファイルをデータセットの中の 2 つのパスに置くことになるとき (2 つのテーブルの
docsに同じ文書を書いたときなど) もエラーです
dbt のプロジェクト
ルートに dbt_project.yml があると、tabledoc は target/manifest.json (--manifest で変更できます) を読みます。先に dbt compile (またはビルド) を実行してください。manifest が無いときは警告を出し、テーブルのファイルだけを読みます。カタログに dbt で作ったテーブル (source_path のあるテーブル) があり、説明に sql が無く、そのテーブルをすべて説明しているときは、load はその SQL を引き継ぐので、警告ではなく情報として出します。
- テーブルは、有効なモデルのうち
materializedがtable・view・incrementalのものです。モデルのschemaとaliasで名前を決めます。ephemeralと無効なモデル、seed・snapshot・テストはテーブルにならないので並べません。説明の無いモデルは dbt が埋める値 (materialized・sql・depends_on・source_path) だけで並べます - 説明はモデルの yml から取ります。
descriptionと列のdescriptionはそのまま、dbt に無いキー (title・primary_key・sources・列のtitle・assetなど) とqueriaはconfig.metaに書きます - semantic は列の
entity・dimension・granularityと、セマンティックレイヤーの simple のmetricsから取ります materializedはモデルの materialization、source_pathはoriginal_file_path、sqlはcompiled_codeです。depends_onは DuckDB の構文解析で SQL から読みます。ほかのデータセットのテーブルは<リポジトリの URL>#<schema>.<table>と書き、URL はprofiles.yml(--profiles、無ければDBT_PROFILES_DIR、無ければルート) の DuckLake の ATTACH から引きます- ガイドはモデルの
.sqlの隣の同じ名前の.mdか、その名前のフォルダのREADME.mdです (dbt は docs ブロックの無い.mdを無視します)。ほかの文書はconfig.metaのdocsに書きます - 1 つのテーブルの説明は 1 か所に書きます。テーブルのファイルと dbt の yml の両方に説明があると、エラーになります。dbt の yml に説明が無ければテーブルのファイルを読み、
sqlは dbt から取ります
models:
- name: series
description: 1 行が 1 系列です。
config:
meta:
title: 系列の一覧
primary_key: [db, series_code]
columns:
- name: db
description: databases の db と同じ
dimension: categorical
config:
meta: {title: DB 名}
dbt で作らないテーブル (Python で作るものなど) は、同じプロジェクトの中でもテーブルのファイルで書きます。
semantic
列の意味は、dbt-core 1.12 以降のセマンティックレイヤーの書き方 (列に直接書く形) にそろえます。特定の読み手のキーではなく、tabledoc 自身のキーです。
| キー | 値 | 意味 |
|---|---|---|
entity |
{type, name}、または type だけ |
結合キー。type は primary・unique・foreign・natural。name は値の語彙の名前 (corporate_number・lg_code など) |
dimension |
categorical・time、または {type, name} |
絞り込み・グループ分けに使う列 |
granularity |
day・month・year など |
dimension: time の列の細かさ |
metrics (テーブル) |
[{name, agg, expr, description}] |
集計のしかた。agg は sum・max・count_distinct など |
dbt で metrics を書くにはセマンティックレイヤー (semantic_model: true と time spine) が要ります。セマンティックレイヤーを使わないプロジェクトでも、列の entity・dimension は書けます。
読み手ごとのキー
特定の読み手だけが使うキーは、その読み手の名前の下に書きます。tabledoc は中身を検査せず、annotations.<読み手> にそのまま入れて返します。
- Queria のキーは
queria:に書きます。tabledoc が名前を知っている唯一の読み手で、中身は Queria が検査します - ほかの読み手は
annotations: {<読み手>: {...}}に書きます
Python から読む
説明をほかの場所に送るプログラムや、別の形式に変えるプログラムは tabledoc.read で読みます。validate と同じ検査をして、以前の形式を今の形に読み替えた説明を返します。
import tabledoc
report = tabledoc.Report()
d = tabledoc.read(tabledoc.Options(root), report) # root: tabledoc.yml のフォルダ
if report.failed:
print(report.render())
d.dataset # {"name": "boj", "title": …, "guide": "README.md", "docs": ["methodology.md"], "annotations": {…}}
d.schemas # [{"name": "timeseries", "title": "Time series"}]
d.tables # [{"schema": "timeseries", "name": "series", "sql": …, "depends_on": […], "guide": …, "columns": […]}]
d.files # [File(path="README.md", sha256="…", bytes=1234, media_type="text/markdown", local="README.md"), …]
d.source # {"repository": "https://github.com/…", "commit": "…", "path": "", "dirty": False}
d.dependencies # {"other": {"url": "https://…"}}: SQL が読むほかのデータセット (SQL の中の名前 → URL)。FDL の tables.json の dependencies と同じ形
d.content(d.files[0]) # そのファイルの中身
sourceは Git の作業コピーから取ります。repositoryはoriginの URL を https に直したもの (認証情報と.gitを外す)、commitは HEAD、pathはリポジトリのルートから tabledoc.yml のフォルダまでのパス、dirtyはコミットしていない変更があるかです。Git の外とOptions(with_source=False)では None です- 文書はパスで参照します。
filesに、説明と一緒に送るファイル (ガイド・README・docs・それらが指すファイル) をデータセットの中のパス・sha256・大きさ・メディアタイプと、ルートからのパスlocalで並べます。guide・docs・schemas[].guide・schemas[].docsの値はfilesのパスです。contentはデータセットに入れる中身を返します。Markdown の文書はリンクを書き換えた本文、以前の形式の Markdown のテーブルのファイルはフロントマターを外した本文です - semantic は書き方によらず
{type, name}の形にします (dimension: categoricalは{"type": "categorical"}) - テーブルは
schema・nameの順に並べ、キーの順も決まっています。同じファイルからは同じ値を返します - 構造 (型・NULL・行数・ビューかどうか) は入れません
DuckLake のカタログに書く
tabledoc load は validate と同じ検査をしてから、説明を DuckLake のカタログの 1 つのスキーマに、普通のテーブルとして書きます。スキーマは tabledoc.yml の schema か --schema で指定し、指定が無ければ _tabledoc です。テーブルはデータと一緒にバージョン管理され、カタログを読むプログラムは説明も SQL で読めます。fdl では、カタログは fdl clone が作る作業用メタデータで、fdl commit でバージョンにします。
tabledoc load --ducklake work.sqlite --out build/assets
fdl commit work.sqlite -m "..." --assets build/assets
--ducklake: カタログ (既定はFDL_WORKING)。--data-path: 新しいデータファイルを置く場所 (既定はFDL_DATA_PATH、無ければfdl cloneがカタログの横に記録したフォルダ)。HTTP のデータファイルは DuckDB の secret で読みます。カタログが fdl の作業用メタデータでFDL_TOKENがあるときは、fdl cloneが記録した remote にそのトークンを送るので、非公開データセットのファイルも読めます--schema: 書くスキーマ (既定はtabledoc.ymlのschema、無ければ_tabledoc)。Queria は_queriaを読みます。Queria で公開するデータセットでは--schema _queria(かschema: _queria) を指定します--out:fdl commit --assetsに渡すフォルダも書きます。filesテーブルの各ファイルをfiles/<path>に置きます。--assets <フォルダ>を付けると、その下のファイル (ビルドが作った asset の列のファイル) をdata/にリンクします。フォルダは空か前のloadが書いたもので、fdl だけが書く.fdl/の外でなければなりません--unlisted: 説明の無いテーブルとビューにもtablesの行を作り、publishedを false にします。dbt が作ったテーブルで、SQL のほかに説明がどこにも書かれていないものもpublishedを false にします。書き込むスキーマと、dataset・schemas・tables・columns・filesのテーブルをすべて持つスキーマ (以前の load が書いたスキーマなど) のテーブルには行を作りません- 説明や主キーにあってカタログに無いテーブルと列、
varcharでないassetの列はエラーです。名前は DuckDB と同じく大文字と小文字を区別せずに照合し、カタログの表記で書きます - 列に入らない値 (
YYYY-MM-DD以外のissuedなど) はエラーです - エラー (
--strictでは警告も) があると何も書きません
| テーブル | 主キー | 元の値 |
|---|---|---|
dataset |
id (常に dataset) |
tabledoc.yml の language・homepage・repository (無ければ Git の origin を https で)・issued・update_frequency・licenses・sources・contributors・temporal_coverage・spatial_coverage、queria: の title_kana・cover・ai_context |
schemas |
schema |
title か description のある schemas[] |
tables |
schema・name |
説明のあるテーブルとビュー: licenses・sources・temporal_coverage・spatial_coverage・sql・depends_on・source_path、queria: の published・ai_context |
columns |
schema・table・name |
title・description・entity のどれかがある列。entity は entity の name (lg_code などのコード体系) です |
texts |
schema・table・column・language |
データセット・スキーマ・テーブル・列の title・description・topics。書いた言語ごとに 1 行です。対象に当たらない段は '' にします。データセットの行は 3 つとも ''、スキーマの行は table と column が ''、テーブルの行は column が '' です |
files |
path |
データセットの中のファイル: path・sha256・bytes・media_type |
- 複数の言語で書いた文字列 (言語) は、言語ごとに 1 行として
textsに書きます。1 つの言語で書いたデータセットは、説明する対象ごとに 1 行です。言語を追加すると行が増え、ほかのテーブルは変わりません - ほかのテーブルは各キーに値を 1 つだけ持ちます。
textsに入らないキー (ライセンスのtitleなど) を複数の言語で書いたときは、languageの言語の値を書き、警告を出します topics(以前の名前のkeywords) は、queria:にtopicsが無ければ書きます。queria:のthemesは書きませんlicensesは{id, spdx, url, title, commercial_use, share_alike, attribution_required}のリストです。文字列で書いたライセンスは{id}になりますsource_pathはそのテーブルを定義しているファイルの、repositoryのルートからのパス (dbt のoriginal_file_pathに、Git の作業コピーの中でのtabledoc.ymlのフォルダを前に付けたもの)、sqlはそのテーブルを作った SQL です。分からないときはどちらも NULL です。テーブルかビューかは書きません (カタログが持っています)- ビューの行には
sqlとdepends_onを書きません。ビューの SQL はメタデータが持ちます annotations:のうち Queria 以外の読み手のキーは書きません- ファイルの中身はカタログに入れません。
files.sha256に各ファイルの sha256 を書き、fdl commit --assetsが中身ごとにファイルをアップロードします - 行は主キーごとに追加・更新・削除するので、
loadは値の違うセルだけを変えます。dbt のビルドが無いとき (説明にsqlが無いとき) は、各テーブルのsql・depends_on・source_pathをカタログから引き継ぎます - 主キーと asset の列はこれらのテーブルに書きません。カタログが
fdl cloneの作った作業用メタデータのとき (横に<catalog>.fdl.jsonがあるとき)、loadはfdl declareで FDL に宣言します (fdl-cli 0.34 以降のfdlがPATHにあることが必要です)。宣言するのは、各テーブルのprimary_keyと、列にassetがあるテーブルの asset の列 (ビューにはどちらも宣言しません)、publishedが false のテーブルとビューにプロファイルを作らないことと、説明したほかのテーブルにプロファイルを作ること、SQL が読むほかのデータセット (dbt のprofiles.ymlから) の依存先、それにこれらのテーブルの主キーと asset の列files.sha256とプロファイルを作らないことです。fdl declare listと違うものだけを実行し、説明に無いものは FDL の宣言のまま残します - コメント (
COMMENT ON) は書きません
カタログからファイルを書く
tabledoc dump は、カタログが持つ説明のファイルを書きます。tabledoc.yml、説明のあるテーブルごとのテーブルのファイル、files テーブルの各ファイル (そのパスに) です。書いたファイルを tabledoc load で読むと、同じテーブルになります。
tabledoc dump --ducklake work.sqlite --out description/
--ducklake: カタログ (既定はFDL_WORKING)。--schema: 説明のあるスキーマ (既定は_tabledoc)。ほかのスキーマはtabledoc.ymlのschemaに書くので、loadは同じスキーマに書き戻します。--out: 書くフォルダ (既定は今のフォルダ)。.fdl/の外でなければなりません--files:filesテーブルのファイルの置き場所。<files>/<sha256>で読みます。フォルダか http(s) の URL です。既定は、fdl cloneがカタログの横に記録したリポジトリのassets/です。各ファイルは sha256 で照合します--name:tabledoc.ymlのname。既定はリポジトリの URL の最後の部分です- フォルダに同じファイルがあると、
--forceを付けない限り何も書きません。カタログのパスがフォルダの外を指すときはエラーです - テーブルのファイルは
<schema>/<table>.yml、ガイドは<schema>/<table>/README.mdに書きます。フォルダのREADME.md以外の Markdown は、そのフォルダのdocsに並べます textsの行は、1 つの言語だけでそれがデータセットのlanguageなら文字列だけで、それ以外は対応で書きます- テーブルに無いものは書きません。主キー、asset の列、entity の種類 (
foreignと書きます)・dimension・granularity・metrics、ほかの読み手のキーと、dbt のprofiles.ymlから取る SQL が読むほかのデータセットです。--unlistedだけが書いたテーブルにはテーブルのファイルを作りません。sqlとdepends_onはsource_pathの無いテーブル (dbt で作らないテーブル) にだけ書きます
AI のために Markdown を書き出す
tabledoc export --markdown <フォルダ> は、validate と同じく説明を検査してから、Markdown として書き出します。データセットに 1 つ、スキーマごとに 1 つ、テーブルごとに 1 つのファイルを書きます。AI アシスタントや人はこのフォルダをそのまま読めます。データのドキュメントと一緒に公開することもできます。
tabledoc export --markdown ai-docs/
| ファイル | 内容 |
|---|---|
README.md |
データセットの名前、説明、ライセンス、出典など tabledoc.yml のキー。スキーマとテーブルの一覧 (それぞれへのリンクと、説明の最初の段落)。文書の一覧。最後にデータセットの概要 (README.md) |
<schema>/README.md |
スキーマの名前と説明、テーブルと文書の一覧。最後にスキーマのガイド |
<schema>/<table>/README.md |
テーブルの名前、説明、主キー、ライセンス、出典、materialized。列 (名前、説明、semantic、asset) とメトリクスの表。そのテーブルが読むテーブルと、そのテーブルを読むテーブル (データセットの中のテーブルはリンク)。SQL。文書の一覧。最後にテーブルのガイド |
- ファイルは データセットの中のパス に書きます。
filesのほかのファイル (文書、画像) もそれぞれのパスに書くので、ガイドの中のリンクはそのまま使えます - ガイドは区切り線 (
---) の後に、書かれたとおりに置きます。見出しのレベルは変えません - 複数の言語で書いた値は、データセットの
languageのもの (無ければ und、それも無ければタグの順で最初のもの) を書きます - 読み手ごとのキー (
queria:、annotations:) は書きません - 型・NULL の可否・行数は説明に含まれないので、書きません
- フォルダに同じパスのファイルがあると、
--forceを付けない限り何も書きません。前の書き出しにあって今回書かないファイルは、フォルダに残ります - フォルダには
.tabledoc-exportというファイルも書きます。tabledoc はこのファイルがあるフォルダの中のファイルを読まないので、書き出すフォルダをルートの中に置けます - エラーがあると (
--strictでは警告も) 何も書きません
以前の形式
すべてのデータセットを一度に書き換えずに済むように、tabledoc は置き換える前の形式も読みます。新しく書くのは tabledoc の形式だけです。
tabledoc.ymlが無くqueria.yml(https://queria.io/schemas/dataset/v1.json) があれば、それを tabledoc.yml として読みます。最上位のtitle_kana・themes・cover・ai_contextはqueria:の下にあるものとして扱います。catalogsはdepends_onに使い、dependenciesとして返します- フロントマターに
$schema: https://queria.io/schemas/table/v1.jsonを持つ Markdown は、フロントマターをテーブルのファイル、本文をガイドとして読みます。table:で対応を決め、fieldsはcolumns、published・themes・ai_contextはqueria:の下として扱います。ガイドはその Markdown のパスで、送る本文はフロントマターを外したものです - 列の
semantic: {role, name, agg}は次のように読み替えます。role: entity→entity: {type: foreign, name}、その列だけでprimary_keyになっていればtype: primary。role: dimension→dimension: categorical。role: measure→ テーブルの metrics に{name: <列名>, agg, expr: <列名>}(aggが無ければ警告) - 同じフォルダに
tabledoc.ymlとqueria.ymlがあるとエラーになります
$schema とバージョン
- JSON Schema は tabledoc に同梱し、
https://tabledoc.queria.io/schemas/<種類>/v<n>.jsonで配ります。種類はdatasetとtableです - キーを追加するだけなら同じバージョンのままです。キーの意味を変える・消すときは
v2にし、tabledoc はしばらく両方を読みます - 知らない
$schemaのファイルは断り、tabledoc を上げるよう伝えます