コンテンツにスキップ
Queria Docs
日本語
日本語English
Esc
↑↓navigate↵open⌘Jpreview
このページの内容

データセットの規約

公開するテーブルを、ほかのデータセットと前処理なしで結べる形にそろえるための約束

公開するテーブルを、ほかのデータセットと前処理なしで結べる形にそろえるための約束です。Queria 自身のデータセットにも、ほかの発行者のデータセットにも同じように効きます。

機械で確かめられるものは queria validate（queria compile / queria sync の中でも動きます）と dbt のテストに任せ、ここには判断の拠り所になることを書きます。説明をどの階層に書くかは説明の書き分けにあります。

名前

どの名前も、小文字の英数字とアンダースコアで書きます。

  • データセット: 配布元や原典の名前（nlftp, e_stat, gif）。一度公開したら変えない
  • スキーマ: 主題（boundary, facility, vocab）。main のままにせず、層の名前（stg, mart, silver）も出さない
  • テーブル: 1 行が表すものの名詞（shelter, term, code_system）。日付や版を名前に入れない

テーブルやスキーマを改名するときは、古い名前をしばらく残します。

列名

列名は、データの種類に応じて決まった語彙に揃えます。

  • 一般のデータ（地図・施設・海外由来など）: schema.org の語を snake_case にする（postalCode → postal_code）
  • 日本の公的データ（自治体・国の統計や台帳）: デジタル庁の政府相互運用性フレームワーク（GIF）の英語名を snake_case にする（localGovernmentCode → local_government_code）。GIF の語が schema.org の語に修飾を足しただけのときは短い方を使う（latitudeOfRepresentativePoint ではなく latitude）
  • 列の title はどちらでも GIF の項目名、無ければ共通語彙基盤（IMI）の語、どちらにも無ければ原典の列見出し

名前が違っても同じ意味の列は、語彙 queria-io/vocabulary で結ばれています。列が何を表すかはデータ項目の語彙 data_elements.csv に、何を識別するかは実体の語彙 entities.csv にあります。新しく列名を決めるときは次の順で探します。

  1. data_elements.csv にあるデータ項目なら、その title を使う。列名は日本の公的データならその name 列の値、一般のデータなら schema_org 列の語を snake_case にしたもの（schema_org が空なら name 列の値）
  2. 無ければ基準の語彙（後述の schemaorg か gif データセット）から探して snake_case にする
  3. どの語彙にも無ければ自由に決めてよい。ただし省略形（lat, pref, num）は使わない

よく使うデータ項目の例です。

  • 全国地方公共団体コード（6 桁）: local_government_code（ほかに使われている名前: lg_code）
  • 都道府県: 公的データは prefecture、一般のデータは address_region（pref_name）
  • 郵便番号: postal_code（postcode, zipcode）
  • 緯度・経度: latitude / longitude（lat / lon）

原典が独自のコード体系を使う列は、体系の名前で修飾して標準の列と紛れさせません（警察の管轄コードなら police_city_code）。

既存の列を無理に改名する必要はありません。lat や pref_code のような省略形だけは、旧列を残したまま新しい名前の列を足し、旧列の説明に非推奨と書いてから落とします。

型と値の形式

値は、そのまま結合・集計できる型で公開します。変換で落ちた意味は別の列に残します。型はデータから読むので、*.table.yml には書きません。

  • コード（地方公共団体コード・法人番号・郵便番号・メッシュ）: VARCHAR。先頭のゼロを保ち、桁数と検査数字の有無を列の説明に書く。郵便番号は 7 桁でハイフンなし
  • 量・金額・件数: 数値型。VARCHAR のまま公開しない。単位は列の説明に書く
  • 日付・時点: 日付は DATE、年だけなら西暦の INTEGER。和暦は変換して持つ
  • 座標: latitude / longitude は世界測地系の十進度の DOUBLE。日本測地系（旧測地系）の原典は変換して持つ。地点のデータには geometry も作り、座標参照系を列の説明に EPSG:xxxx で書く
  • 真偽: BOOLEAN。○・有・1 などは変換する
  • 文字列: NFKC で正規化し、前後の空白を落とす
  • 全国・都道府県・市区町村が同じ列に並ぶ表: 階層を表す area_level 列を足し、小計の行には印を付ける

欠測と秘匿

統計表の「-」「x」「…」のように、数値の代わりに記号が入る列は、数値と状態の 2 列に分けます。

  • value: 数値。値が 0 と分かる記号は 0、それ以外の記号の行は NULL
  • value_flag: 観測値の状態。国際的な統計データ交換の標準 SDMX の観測ステータス（OBS_STATUS）の 1 文字コードを使う
  • value_raw: 原典の記号をそのまま残す

日本の統計表でよく出る記号と value_flag の対応です。原典の凡例と違うときは凡例に従い、対応を列の説明に書きます。

  • 通常の値: A
  • 推計値: E
  • 速報値・暫定値: P
  • 該当数字なし（「-」など、凡例が 0 件を意味する）: value を 0 にして A
  • 該当なし（凡例が、値が存在し得ないと言うもの。合併前の年の市町村など）: M
  • 秘匿（「x」など）: Q
  • 調査していない・不詳（「…」など）: L

value と value_flag は、列名を変えても構いません（population と population_flag など）。

対応表と共通の変換

コードを名称に変える対応表は、SQL の CASE に埋めず dbt の seeds/ に置き、未対応の値をテストで拾います。日付の表記ゆれ・度分秒・先頭ゼロの復元のような、どのデータセットでも要る変換は、データセットごとに書き直さず共通の部品にします。Queria 自身のデータセットでは、その置き場所は dataset-shared の macros/ です。まだ無い変換は、データセットの中に書かずそこに dbt マクロとして足します。

粒度

公開するテーブルは、1 行が何かを決めて、それをテストで守ります。重複した行は集計を黙って狂わせるので、公開する前に止めます。

  • テーブルの説明の 1 文目に粒度を書く（「1 行が 1 市区町村の 1 年」）
  • 粒度に当たる列を *.table.yml の primary_key に書く（書き方はデータを公開する）
  • 原典が改定されるデータ（訂正報告、確報への差し替え、市町村の廃置分合）は、どの時点の断面かを列に持つかどうかをデータセットごとに決めて、説明に書く
  • 行ごとに出所が変わるデータは、取得元を列（source_url）で持つ

キーの列

データセットをまたいで突き合わせられる列には、semantic: { role: entity, name: ... } でキーを宣言します。書き方とキーの一覧はデータを公開するにあります。

  • 公開するテーブルに突き合わせに使える列があれば、必ずキーを付ける
  • name は実体の語彙 entities.csv にある名前を使う。無い名前を書くと queria compile が警告し、検索のキーの列にも出ない。足したいキーは queria-io/vocabulary に提案する
  • 列名が data_elements.csv のデータ項目（またはその別名）に当たり、そのデータ項目がキーを持つのに semantic が無い列は、警告が出る。キーとして使わない列なら semantic: { role: dimension } と書く
  • 集計する値は role: measure にし、agg に sum / avg / min / max / count のどれかを書く

メタデータ

dataset.yml は、W3C のデータカタログ語彙 DCAT（日本政府の版は DCAT-GoJ）にそのまま写せる形で書きます。queria export --format dcat-goj が JSON-LD を書き出すので、それぞれの欄を埋めることがそのまま DCAT のメタデータになります。

  • title / title_kana → dct:title: 原典の正式名と、その読み
  • description → dct:description: 何のデータか、使い道、出典の表示文の順に書く
  • licenses → dct:license: SPDX か Queria の登録簿の ID。登録簿に無いライセンスは条件（商用利用・継承・表示）まで書く
  • contributors の roles → dct:publisher / dct:rightsHolder など: 権利者と提供者を分けて書く
  • sources → dct:source: 取得元の URL。テーブルごとの取得元は各テーブルの sources に書く。書いたテーブルではデータセットの sources を受け継がず置き換えるので、両方要るなら両方書く（DCAT にはデータセットの分だけが出る）
  • update_frequency → dct:accrualPeriodicity: 実際の更新の頻度に合わせる
  • spatial_coverage → dct:spatial: 国コードか地方公共団体コード
  • temporal_coverage → dct:temporal: 収録期間
  • keywords → dcat:keyword: 分類する語と、利用者が使う別の呼び方

語彙を引く

列名や title を決めるときは、語彙そのものを Queria のデータセットから SQL で引けます。どれも原典から定期的に取り直しているので、写しを手元に置く必要はありません。

  • gif: 日本の公的データの項目（vocab.term）、コード一覧（vocab.code）、行政のコード体系の定義と配布元（vocab.code_system）
  • imi: 共通語彙基盤の語と恒久的な URI（vocab.term）、クラスごとのプロパティ（vocab.class_property）
  • schemaorg: schema.org のプロパティ（vocab.property、snake_case の名前は snake_case_name）と型（vocab.type, vocab.type_property）
-- 「郵便」を含む GIF の項目と、列名の候補
SELECT class_name, term_ja, snake_case_name FROM gif.vocab.term WHERE term_ja LIKE '%郵便%';

-- schema.org に同じ名前のプロパティがあるか
SELECT name, snake_case_name, description FROM schemaorg.vocab.property WHERE snake_case_name = 'postal_code';

検査

公開の前に queria validate が次を確かめます。

  • 宣言のスキーマ、権利（ライセンス・出典）、説明の有無
  • semantic の role と agg の値（誤りはエラー）
  • キーの名前が実体の語彙にあるか、キーになるはずの列に semantic があるか（警告）
  • primary_key の列が実データにあり、値が一意で NULL が無いか（エラー）

このページは役に立ちましたか？