yml ファイルの記述方法

yml ファイルの記述方法 #

次に yml ファイル (先ほどの dig ファイルの記述例で言えば unification_ex1.yml) について、以下の例を参考に記述方法を紹介していく。

name: production
keys:
  - name: td_client_id
    valid_regexp: "[0-9a-fA-F]{8}-..."
    invalid_texts: ['']

  - name: td_global_id
    valid_regexp: "[0-9a-fA-F]{8}-..."
    invalid_texts: ['', '0000000000-...']

  - name: email
    valid_regexp: ".*@.*"

tables:
  - database: prod
    table: pageviews
    incremental_columns: [updated_at, id]
    key_columns:
      - {column: td_client_id, key: td_client_id}

 - database: brand2
    table: pageviews
    as: brand2_pageviews
    key_columns:
      - {column: td_client_id, key: td_client_id}
      - {column: td_global_id, key: td_global_id}
      - {column: email, key: email}

  - database: prod
    table: contacts
    key_columns:
      - {column: email, key: email}

canonical_ids:
  - name: browser_id
    merge_by_keys: [td_client_id, td_global_id]

master_tables:
  - name: marketing_master
    canonical_id: browser_id

    attributes:
      - name: browser_id
        source_canonical_id: browser_id

      - name: email
        source_columns:
          - {table: contacts, column: email}

name:#

この Unification の名前を指定する。この名前は ID Unification のアウトプットを格納するデータベース名 (cdp_unification_${name})として入ることになる。上記の例では cdp_unification_production データベースが作成され、アウトプットが格納される。

keys:#

keys:
  - name: td_client_id
    valid_regexp: "[0-9a-fA-F]{8}-..."
    invalid_texts: ['']

  - name: td_global_id
    valid_regexp: "[0-9a-fA-F]{8}-..."
    invalid_texts: ['', '0000000000-...']

  - name: email
    valid_regexp: ".*@.*"

使用する全てのテーブルを通じて、ID の縫い合わせに利用する識別子を key として全て列挙する。

keys: のオプション #

Option Name	Required?	Value	Description
`name:`	Required	String	各 key の名前を指定する。基本的にはカラム名となるが、email / mail_address など、テーブルによってカラム名が異なる場合にはその中でどれか1つの名前を指定する。また長い名前の key の場合には、代わりにシンプルを設定しても良い。つまり、key の名前はテーブルのカラム名と一致しなくても構わない。テーブルごとに key がそのテーブルのどのカラム名に対応するのかを明示する記述を行うことになるので。
`valid_regexp:`	Optional	Regular expression	記述した正規表現にマッチする key のみを有効とみなしたい場合に設定する。
`invalid_texts:`	Optional	Array(String)	`valid_regexp:` が正規表現にマッチする key “だけ” を使用する設定に対して、`invalid_texts` は配列として列挙した値を持つ key を “除外” する設定である。`''` や `N/A` などの値を不特定多数のユーザーが持っている可能性がある場合、この値で紐づいてしまっては困るのでここに必ず指定するようにする。

(参考) td_client_id / td_global_id に用いるべき正規表現 #

td_client_id や td_global_id は

307423ab-9cbc-4bca-9cae-05c3700cc8f2
fc6422e1-48bb-4396-b7aa-bdd2075c000d

のような値を持つが、これは正規表現として

"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}[0-9a-fA-F]{4}[0-9a-fA-F]{4}[0-9a-fA-F]{12}"

と一律に表現することができる。これらを key として使い場合は valid_regexp: にて上記の設定をしておくことをお勧めする。

tables:#

tables:
  - database: prod
    table: pageviews
    incremental_columns: [updated_at, id]
    key_columns:
      - {column: td_client_id, key: td_client_id}
 - database: brand2
    table: pageviews
    as: brand2_pageviews
    key_columns:
      - {column: td_client_id, key: td_client_id}
      - {column: td_global_id, key: td_global_id}
      - {column: email, key: email}

  - database: prod
    table: contacts
    key_columns:
      - {column: email, key: email}

tables: のオプション #

Option Name	Required?	Value	Description
`database:`	Required	String	database 名を指定
`table:`	Required	String	table 名を指定
`key_columns:`	Required	Array(Map)	指定したテーブルごとに、その中で縫い合わせに使用される key を `key_columns:` に全て列挙する。その際、`key_columns:` のそれぞれには、そのテーブル内で縫い合わせキーとなるカラムの名前を指定する `column:` と、 `keys:` で列挙されている `name` の中の値を指定する `key:` を指定する。
`as:`	Optional	String	オリジナルのテーブル名とは異なる名前でアウトプットしたい場合、このオプションで名前を設定する。
`incremental_columns:`	Optinal	Array(String)	incremental_update を行う場合に設定する。`[time]` 以外の値を指定すると差分更新が行われないので、このオプションを使う場合は常に `[time]` を指定するようにしよう。

(参考) key_columns: において、column: と key: が異なる場合 #

多くの場合、 column: と key: の値は一致するかもしれないが、例えばあるテーブルの中では cookie_id というカラム名で記録されている識別子が、他のテーブルの td_client_id カラム (かつ keys: には td_client_id で登録されている) と縫い合わせられる場合、

- {column: cookie_id, key: td_client_id}

と記述することになる。

as: を使用すべきケース #

このオプションが必要となるのは、今回の例のように異なるデータベースで pageviews などの同じテーブル名を持っていて、そのどちらもソーステーブルとて使用する場合である。アウトプット先のデータベース内でエンリッチされたテーブルを作成する際に、同じ名前となってしまうため、衝突を避けるために as: を利用する。

canonical_ids:#

ID Unification を実行するための設定と、実行後、統一されたユーザーに新たに識別子を割り当てる設定を行う。

canonical_ids:
  - name: browser_id
    merge_by_keys: [td_client_id, td_global_id, td_ssc_id]

  - name: marketing_id
    merge_by_canonical_ids: [browser_id]
    merge_by_keys: [email]
    source_tables: [pageviews, contacts]

  - name: contact_id
    merge_by_canonical_ids: [browser_id]
    merge_by_keys: [membership_id, email]
    merge_iterations: 3
    incremental_merge_iterations: 2

canonical_ids: のオプション #

Option Name	Required?	Value	Description
`name:`	Required	String	canonical_id の名前を設定する。
`merge_by_keys:`	Required	String	どの key 群を使って縫い合わせ (Unification Algorithm) を実行するかの設定になる。設定する key のバリエーションだけでなく、設定する順番 (優先度) が非常に重要になってくる。
`merge_iterations:`	Optional	Integer	Unification Algorithm はループ処理となるため、何回ループさせるかの設定となる。ループの回数は問題 (データ) に依存するが、ループが不十分であることは実行結果から確認できる。回数を多く設定しても、アルゴリズムが収束した時点で処理を打ち切ってくれるので、まずは 5 や 10 あたりを指定して実行すると良い。デフォルト値は`3`。
`incremental_merge_iterations:`	Optional	Integer	incremental_update が実行される際に使われるループの回数の設定。デフォルト値は `2`。
`source_tables:`	Optional	Array(String)	`tables:` で指定したテーブルの中から一部のテーブルをこのオプションで列挙することで、指定した一部のテーブルの key のみを用いて Unification を行うことができる。指定されない場合には全てのテーブルを参照する。
`merge_by_canonical_ids:`	Optional	Array(String)	canonical_id をマージした canonical_id を作成したい場合に使用する。

(参考) canonical_id の name の考え方 #

canonical_id の命名については、命名については、何が統合されてできた ID なのかがわかるようなものにしよう。かつこの canonical_id の名前は出力するテーブル名にも入ってくることを意識して長過ぎないものにしよう。例えば

browser_id, unified_cookie_id
- td_client_id, td_global_id, td_ssc_id, cookie_id をメインに統合する場合
person_id, customer_id, cust_id, member_id
- email や member_id などの個人情報を含む key で統合する場合

master_tables:#

master_tables:
  - name: marketing_master
    canonical_id: marketing_id
    attributes:
      - name: browser_id
        source_canonical_id: browser_id

      - name: firstname
        source_columns:
          - {table: pageviews}
          - {table: form_submits, column: first_name}

      - name: birthdate
        valid_regexp: "[0-9]{4}-[0-9]{1,2}-[0-9]{1,2}"
        invalid_texts: ['']
        source_columns:
          - {table: contacts, priority: 1}
          - {table: pageviews, priority: 2}
          - {table: form_submits, priority: 3}

      - name: all_emails
        array_elements: 5
        source_columns:
          - {table: contacts, order: last, order_by: time, priority: 1}
          - {table: pageviews, order: first, order_by: time, priority: 2}
          - {table: form_submits, order: first, order_by: time, priority: 2}

master_tables: のオプション #

Option Name	Required?	Value	Description
`name:`	Required	String	`canonical_id:` で指定した canonical_id を持った master_table を、この `name:` で指定した名前で作成することになる。
`canonical_id:`	Required	String	master_table のベースとなる canonical_id を指定する。master_table の行数はこの canonical_id のユニーク数となる。指定した canonical_id における `merge_by_keys:` の設定が、全てのテーブルを横断する key の組み合わせになっていないとエラーが出る (全てのソーステーブルにエンリッチできないので) ので注意しよう。
`attributes:`	Optional	(Deep Nests)	ソーステーブルの canonical_id 以外のカラムを `attributes:` で指定することで master_table 内のカラムとして登場させることができる。このオプションについては後述。

attributes: のオプション #

Option Name	Required?	Value	Description
`name:`	Required	String	アトリビュート名を指定し、これが master_table 内のカラム名となる。
`array_elements:`	Optional	Array(String)	指定するカラムの値が、1つの canonical_id に対して複数の値が存在することが多々ある (例えば `keys:` として使用した td_clitent_id などの key ) 。そのような場合、配列として複数の値を持たせることができる。その際、何個の値を要素として持つかの数の設定となる (最大 `10`)。このオプションを指定しなければ1つの値のみをもつカラムとなる。
`source_columns:`	Required	(Deep Nests)	指定したアトリビュートは基本的に複数のテーブルおよび (1つのテーブルであっても) 複数のレコードにまたがるため、どのテーブルのどのレコードの値を優先的に取得するのかのプライオリティの設定が必要となる場合がある。あるテーブル内で `name:` で指定したカラム名とは異なる場合は、別途この中に `column:` でカラム名を指定する必要がある。
`valid_regexp:`	Optional	Regular expression	`keys:`における同名のオプションと同じ。
`invalid_texts:`	Optional	Array(String)	`keys:`における同名のオプションと同じ。

source_columns: のオプション #

Option Name	Required?	Value	Description
`table:`	Required	String	アトリビュートとして使用したい table 名 (データベース名は不要)
`column:`	Optional	String	テーブルの中に `name:` で指定した名前と異なるカラム名が入っていた場合、特定のためにこのオプションを指定する。
`priority:`	Optional	Integer	複数の table を指定した際、値を採用するための優先度を指定できる。優先度は同じ値のものがあっても構わない。その優先度の上で、テーブル内のレコードをどの順番で優先的に取得するかを `order:` のオプションで指定する。
`order:`	Optional	String	レコードを `order_by:` で指定したカラム (デフォルトは “time”) について並び替えを行うが、昇順 (ASC) なら `:first`、降順 (DESC) なら `:last` をここに記述する。 (デフォルトは `:last`)
`order_by:`	Optional	String	`order:` に付随して利用するオプション。並び替えを行うカラムを指定する。 (デフォルトは “time”)

priority: を同じにした場合の注意点 #

priotity: を同じにした table 群は必ず同じ並び替えでないといけない (異なるものがある場合はエラー)。同順位のテーブル群は一律に指定された並び替えが適用され、上から順に選ばれることになる。

yml ファイルの記述方法

Contents