Codatumのクエリ結果をKARTE Datahubに書き込んで、配信対象にする

By Codatum Team2026年9月10日

CodatumのBigQueryコネクションにKARTE Datahubのデータセットへの書き込み権限を渡すと、Codatumで書いたSQLの結果を、そのままKARTEの配信対象にできます。

できるようになること

配信対象をSQLで定義できるので、KARTEのセグメントだけでは組みにくい条件を扱えます。

KARTEに取り込んでいないデータを条件にする — 基幹システムの購買履歴、算出済みのチャーンスコアなど、データウェアハウス側にしかない値をそのまま使えます
「〜していない人」を対象にする — セグメントの所属はイベント発生時に判定されるため、「90日購入がない人」のような条件は判定が走るきっかけがありません
その時点で固定した配信リストを作る — 抽出条件ではなく、抽出した結果の一覧を配信対象にできます

出せるチャネルは3つで、必要な準備が違います。

チャネル	Datahub側に追加で必要な準備
KARTE Messageで一斉配信（メール・LINEなど）	テーブルとクエリがUSマルチリージョンにあること
接客サービスからターゲット配信	なし
Web接客（ポップアップ・バナー）	ジョブフローと紐付けテーブル

前提

KARTE Datahubの契約と、Datahub設定を開くためのKARTEの管理者権限が要ります。Codatum側は、コネクションの詳細を見るのでワークスペースオーナーで作業してください。

Datahub自体は東京リージョン（asia-northeast1）でも動きますが、KARTE Messageのリストに使うテーブルとクエリだけはUSマルチリージョンである必要があります（Datahubを元にリストを作成する）。DatahubはUSマルチリージョンが既定なので通常は気にせずに済みますが、東京リージョンで運用している場合は、この経路だけ先に確認してください。接客サービスのターゲット配信とWeb接客にはこの制約はありません。

Codatum側の準備

サービスアカウントのメールアドレスを確認する

グローバルナビのワークスペース設定 > コネクションから、対象者を抽出するSQLを実行するBigQueryコネクションを開きます。抽出とKARTEへの書き込みは1本のSQLで実行するので、基幹システムの購買履歴やチャーンスコアなど抽出元のテーブルを読めるコネクションを選んでください。

コネクションを開いたら、基本設定のClient emailの値を控えます。

xxx@xxx.iam.gserviceaccount.com の形式です。この値を、次のKARTE側の設定で入力します。同じ画面のプロジェクトIDは、クエリのジョブが実行されるプロジェクトです。

KARTE側の設定

データセットを作成する

KARTEですべてのメニュー > Datahub > データセットを開き、Codatumの書き込み先にするデータセットを作成します。

入力するのはデータセット名と表示名の2つです。データセット名は400字以内の半角英数字とアンダースコアのみで、後から変更できません。表示名は任意で、後から変更できます。

codatum_segments のように用途がわかる名前にしておくと、あとでKARTE側の運用者が迷いません。

作成後の画面上部に出る実際のデータセットIDをコピーして、後述のSQLに使ってください。 入力した名前のままSQLを書くと、テーブルが見つからずに失敗します（※1）。

データセットの共有設定で書き込み権限を渡す

データセットの操作メニューからデータセットの共有設定を開き、Codatumで控えたClient emailを入力して閲覧と編集（WRITER）を選びます。手順の詳細はKARTE Datahubのデータセットを共有するにあります。書き込むので閲覧のみ（READER）では足りません。

もう1つ、同じダイアログの下にあるデータセットを共有するプロダクトを許可のチェックが要ります。

このチェックは既定でオフです。入れないと、書いたデータをMessageなどのプロダクト側から使えません。保存に成功すると、データセット名の右にKARTEプロダクトと共有中と表示されます。

対象者を書き込む

Codatumの保存済クエリ、またはノートブックのSQLブロックで実行します。テーブル名の <データセットID> には、先ほど画面からコピーした、末尾にAPIキーが付いた形を使います。

CREATE OR REPLACE TABLE `prd-karte-per-client.<データセットID>.dormant_users` AS
SELECT
  user_id,        -- KARTEのユーザーIDに一致させる
  last_order_at,  -- 配信本文に差し込みたい値があればここに入れる
  total_revenue
FROM
  `your-project.mart.customer_summary`
WHERE
  last_order_at < DATE_SUB(CURRENT_DATE(), INTERVAL 90 DAY)
  AND total_revenue >= 30000

条件の書き方は自由です。データウェアハウスにあるテーブルであれば、そのまま条件に使えます。

どのカラムを入れるか

必要なカラムは、出す先によって違います。

出し先	必須のカラム	満たさないと
KARTE Messageのリスト	ユーザーIDか、メールアドレス・FCMトークン・LINE IDのいずれか（Datahubを元にリストを作成する）	リストにできない
Web接客の紐付けテーブル	KARTEのユーザーIDと一致する `user_id`	エラーにならず、誰にも当たらない

MessageでもユーザーIDは入れておくのが無難です。無いとコンバージョン計測や、配信ログで誰に配信したかの確認ができません。ただしリストとはに注意書きがあるとおり、ユーザーIDは配信ログに平文で保存されます。メールアドレスや電話番号を入れないでください。

KARTEで計測したイベントを条件に混ぜる

KARTE側のイベントも、データセットの共有設定でサービスアカウントに閲覧のみを付与すれば条件に使えます。共有するのは karte_stream_<APIキー> のデータセットです。

外部から引くときはテーブル名が変わります。Datahubの画面で使う karte_event ではなく、実体は日付ごとに分かれた krt_pockyevent_v1_<YYYYMMDD> で、期間はワイルドカードと _TABLE_SUFFIX で絞ります。記法とスキーマはkarte_eventテーブルへのクエリを作成するにまとまっています（※2）。

CREATE OR REPLACE TABLE `prd-karte-per-client.<データセットID>.viewed_not_bought` AS
SELECT
  user_id,
  MAX(sync_date) AS last_event_at,
  COUNT(DISTINCT IF(event_name = 'view', event_hash, NULL)) AS view_count
FROM
  `karte-data.karte_stream_<APIキー>.krt_pockyevent_v1_*`
WHERE
  _TABLE_SUFFIX BETWEEN FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY))
                    AND FORMAT_DATE('%Y%m%d', CURRENT_DATE())
  AND user_id IS NOT NULL
GROUP BY
  user_id
HAVING
  view_count >= 3                                  -- この30日で3回以上見た
  AND COUNTIF(event_name = 'buy') = 0              -- ただしこの30日は買っていない

_TABLE_SUFFIX を入れないと全期間を読みます。検証したプロジェクトでは、30日に絞った場合の45倍のスキャン量になりました。

配信対象に指定する

一斉配信の2つはKARTE側の設定だけで済みます。Web接客だけ、ジョブフローと紐付けテーブルを足します。

チャネル	どこで指定するか	ソースに指定するもの
KARTE Message	リスト管理 > リストを作成（リストとは）	Datahubのテーブルまたはクエリ
接客サービス	配信設定の配信モードでターゲット配信（ターゲット配信を行う）	Datahubクエリ。テーブルは指定できない

KARTE Messageのリストは実体を持ちません。Datahub上のデータセットまたはクエリを参照していて、配信時に最新のデータで抽出されます。つまり以降、配信対象を変えたいときはSQLを変えるだけで、リストを作り直す必要がありません。

Web接客に出す場合

ポップアップやバナーに出す場合は、書き込んだテーブルをKARTEのユーザー情報として載せます。空の紐付けテーブルを作り、ジョブフローで書き込んだテーブルを読むクエリの結果をそこへエクスポートし（メインキーは user_id）、データ紐付けの紐付け先をKARTEのユーザーIDにします。ここまでの操作はユーザーにデータを紐付けるのとおりです。あとは紐付けテーブルの列を条件にしたセグメントを作り、接客サービスの対象ユーザーに指定すれば完了です。一度作れば、以降はSQLを変えるだけです。

制約が2つあります。紐付けた値はセグメント条件専用で、配信トリガーの条件には使えません。 また、ジョブフローのスケジュールは最短1時間間隔で、そこからセグメントに入るのはそのユーザーにイベントが発生したタイミングです。即時性が必要な用途には向きません。

対象者を定期的に入れ替える

Codatumのワークフローに保存済クエリをRun Queryで実行するステップを置き、スケジュールを設定します。Web接客まで含める場合は、KARTE側のジョブフローも時間差でスケジュールします。

#	どこ	何を	いつ
1	Codatumのワークフロー	対象者を抽出してDatahubへ書き出す	毎日 3:00
2	KARTEのジョブフロー	実行結果を紐付けテーブルへエクスポート	毎日 4:00

必ずCodatum側を先に、KARTE側を後に走らせます。 逆にすると、KARTEは前日のテーブルを取り込みます。

行数のガードを効かせたいときは、Run Queryを2つに分けます。ステップ1は対象者を SELECT するだけの保存済クエリ、ステップ2が CREATE OR REPLACE TABLE です。実行条件で参照できるのは先行ステップの出力だけなので、1ステップのままでは行数を条件にできません。ステップ2の実行条件に {{ query.rowCount }} > 0 を置けば、抽出が0件の日に空のテーブルで洗い替える事故を防げます。

あわせて、Slackステップに 件数: {{ query.rowCount }} を入れておくと異常に気づけます。「今週は12,400人」が毎週流れていれば、それが3人や400,000人になった週に誰かが気づきます。通知ステップの実行条件に failure() を置けば、静かに止まっている状態も防げます。

よくある質問

Codatumから書き込めません

データセットの共有設定で、Codatumのサービスアカウントに閲覧と編集（WRITER）が付いているかを確認してください。閲覧のみでは書き込めません。

テーブルは書けたのに、KARTEのMessageから選べません

データセットを共有するプロダクトを許可のチェック（既定でオフ）、テーブルのリージョンがUSか、フィールドが1つ以上あるか、を確認してください。ビューは直接リストにできないので、ビューを読むクエリを作ってそのクエリからリストを作ります。

Codatumのカタログにテーブルが出てきません

コネクションのテーブル同期を実行してください。同期を待たずに使う場合は、SQLから prd-karte-per-client.<データセットID>.<テーブル名> で直接参照できます。

BigQueryのクエリ課金はどちらのプロジェクトに発生しますか

Codatumから書き込む分は、Codatumのコネクションに設定したプロジェクトです。一方、Datahub上でKARTEが払い出したサービスアカウントでクエリを実行すると、契約しているDatahubの月間クエリリソース枠を消費します。

補足

※1 実際のデータセットIDは、入力した名前と一致しません

KARTEは入力した名前の末尾にプロジェクトのAPIキーを連結したものをデータセットIDにします。codatum_segments と入力すると、実体は prd-karte-per-client.codatum_segments_<APIキー> になります。

※2 KARTEイベントを引くときに気をつける4点

イベントの種類は event_name の値で区別します（view / buy / message_open など）。テーブル名は固定です
時刻は sync_date（UTC）、イベントごとの値は values にJSONで入ります
karte_event として公開されていない列は予告なく変わるため、KARTEは利用を推奨していません
ID連携前のユーザーは先頭に vis- が付いた値で混ざります。会員だけに配信するなら除外してください。またイベントは稀に重複し、そのとき event_hash が同じになります

まとめ

Codatumでデータを掘って見つけた顧客の集まりを、そのままKARTEの配信対象にできます。 準備はデータセットを1つ作って権限を1つ渡すだけで、あとは配信対象の定義がSQLに集約されます。条件を変えたいときもSQLを書き換えるだけで、KARTE側の設定は触りません。

Datahubのデータを逆にCodatum側で見る設定は、Signed Embed Lightで、CodatumのノートブックをKARTE Datahubに埋め込むにまとめています。

Codatumのクエリ結果をKARTE Datahubに書き込んで、配信対象にする

Contents

できるようになること

前提