Databricks Events

概要 Labs

プレイヤーイベントがすでにDatabricksのレイクハウスに存在している場合、エクスポートジョブを構築することなくFirstLookに接続できます。FirstLookは、Delta Sharingのレシピエント（DatabricksではOpenSharingとも呼ばれる同一のプロトコル）としてワークスペースに接続します。イベントテーブルを共有すると、FirstLookはDatabricksにデータが届いてから数分以内に新しい行をインポートします。インポートされたイベントは、次回のスケジュールされた集計更新（通常は1時間以内）後にアナリティクスチャートに表示されます。

取り込まれたイベントは、FirstLook SDKで収集されたデータと同様に、S3 Eventsページで説明されているS3パイプラインとまったく同じように、アナリティクス、リテンションチャート、プレイヤープロフィールに反映されます。S3ルートとは異なり、スケジュールするエクスポートジョブもなく、合わせるべきCSVフォーマットもなく、読み取りがDatabricksのコンピュートを消費することもありません。

機能の概要

• 共有テーブルを監視し、約1分ごとに新しいバージョンを確認して、最後に処理したバージョン以降に追加された行のみを読み取ります。
• まず履歴をインポートし、増分読み取りに切り替える前に既存の行（任意で指定した開始日以降）を取り込みます。
• プラットフォームIDから統合されたFirstLookプレイヤープロフィールへのプレイヤーID解決を行い、プラットフォームIDが初めて出現した際に新しいプレイヤーレコードを作成します。
• 取り込みステータスをダッシュボードに表示し、取り込み実行のログとして何がいつインポートされたかを常に確認できます。

アクセスの仕組み

FirstLookはオープンレシピエントです。生成したベアラートークンを使ってワークスペースの共有サーバーに認証し、テーブルのデータファイルへの短命なダウンロードリンクを受け取ります。ワークスペースやストレージへの書き込みアクセスはありません。認証情報はいつでも失効または更新できます。

---

テーブルの要件

Delta Sharingでは、FirstLookのような外部レシピエントに提供するテーブルにいくつかの条件があります。テーブル作成時にこれらを正しく設定してください。後から修正するのが難しいものがいくつかあります。

要件	理由
プレーンなDeltaテーブル（ストリーミングテーブルやマテリアライズドビューは不可）	パイプライン管理オブジェクト（Lakeflow / Delta Live Tablesの出力）は、外部レシピエントに対してスナップショットのみで提供されます。バージョン履歴もChange Feedもありません。イベントがそこに存在する場合は、パイプラインの最終的な追記専用シンクとしてプレーンなDeltaテーブルを追加し、それを共有してください。
作成時にChange Data Feedを有効化（delta.enableChangeDataFeed = true）	これにより、FirstLookはテーブル全体を再スキャンする代わりに、毎分新しい行のみを読み取れます。後から有効化すると、それ以前のバージョンが読み取り不能になるため、最初から設定してください。
作成時にDeletion Vectorsを無効化（delta.enableDeletionVectors = false）	最近のDatabricksランタイムではDeletion Vectorsがデフォルトで有効ですが、この機能を持つテーブルはFirstLookが読み取る共有フォーマットで提供できません。また、後でプロパティをオフにしてもテーブルの履歴に残り続けます。追記専用のイベントテーブルにはそもそもDeletion Vectorsは不要です。
ターゲットファイルサイズの設定（delta.targetFileSize = '256mb'）	FirstLookはテーブルのデータファイルをまるごとダウンロードして処理しますが、ファイルあたりのサイズ制限があります。DatabricksのOPTIMIZEはデフォルトで約1 GBにファイルを圧縮するため、制限を超える可能性があります。このプロパティにより、圧縮後のファイルをその制限以下に抑えられます。
データが自分のクラウドストレージ（S3、ADLS、またはGCS）にあること	Delta Sharingは、ストレージへの事前署名済みリンクを生成することで外部レシピエントにデータを提供します。Databricksが管理する「デフォルトストレージ」（Free EditionおよびサーバーレスデフォルトのWorkspace）にあるテーブルは、外部へ共有できません。明示的なLOCATIONを持つ外部テーブル、またはマネージドロケーションが自分のバケットであるカタログを使用してください。

---

Databricks共有のセットアップ

Unity Catalogが有効なワークスペースと、共有およびレシピエントを作成する権限が必要です。

1. イベントテーブルを作成する

以下のリファレンステーブルは5つの要件をすべて満たしています。スキーマをカウンターまたはデュレーションの仕様（テーブルスキーマを参照）に合わせ、locationをご自分のバケットに変更してください。

CREATE TABLE game_analytics.player_counter_events (
  steam_id      STRING,     -- exactly one player identity column
  session_id    STRING,     -- UUID
  timestamp     TIMESTAMP,
  counter_name  STRING,     -- e.g. 'match.kills'
  counter_value INT,
  build_version STRING      -- optional
)
LOCATION 's3://your-bucket/firstlook/player_counter_events'
TBLPROPERTIES (
  delta.enableChangeDataFeed  = true,
  delta.enableDeletionVectors = false,
  delta.targetFileSize        = '256mb'
);

2. 共有とレシピエントを作成する

イベントテーブルを含む共有を作成し、FirstLookを表すレシピエントを作成してアクセスを付与します。WITH HISTORY句は増分読み取りを可能にするものなので、省略しないでください。

CREATE SHARE firstlook_share;

ALTER SHARE firstlook_share
  ADD TABLE game_analytics.player_counter_events WITH HISTORY;

CREATE RECIPIENT firstlook;

GRANT SELECT ON SHARE firstlook_share TO RECIPIENT firstlook;

レシピエントを作成するとアクティベーションリンクが生成され、そこからクレデンシャルファイル（共有エンドポイントとベアラートークンを含む小さなJSONファイル）をダウンロードできます。パスワードと同様に取り扱ってください。Databricksはレシピエントにトークンの有効期限を設定することを推奨しています。ローテーションの仕組みについてはクレデンシャルのライフサイクルを参照してください。

3. ダッシュボードで設定する

ゲームのダッシュボードで Configuration > Databricks Events に移動し、以下を入力します。

• Credential File — ダウンロードしたクレデンシャルファイルの内容をすべてペーストします。
• Tables — 共有テーブルごとに1行ずつ: 共有名、スキーマ名、テーブル名（例: firstlook_share / game_analytics / player_counter_events）。
• Backfill from — （省略可、テーブルごと） インポートする最も古いイベント日付。空白のままにするとテーブルの全履歴をインポートします。
• Enabled — 取り込みをいつでもオン/オフできます。

保存すると、FirstLookは共有サーバーに対してすべてのテーブルをその場で検証し、スキーマ仕様、Change Data Feedのサポート、テスト読み取りを確認します。設定に問題があるテーブルはすぐに具体的なエラーが表示されます。有効なテーブルには「Validated: counter events, steam_id identity — awaiting first ingestion」のような確認メッセージが表示され、最初のインポートは1分以内に開始されます。

---

テーブルスキーマ

共有テーブルは、カウンターテーブル（数値を持つ個別イベント）またはデュレーションテーブル（時間計測されたアクティビティ）のいずれかです。タイプはカラムから自動検出され、1テーブルにつき1タイプです。余分なカラムは無視されるため、追加フィールドを持つテーブルをそのまま共有できます。

すべてのテーブルには1つのみのプレイヤー識別子カラムを含める必要があり、S3パイプラインがサポートするものと同じセットから選択します。サポートされている識別子についてはプレイヤーIDカラムのリストを、行がプレイヤープロフィールになる仕組みについてはID解決を参照してください。

カウンターテーブル

カラム	型	説明
（識別子）	STRING	プレイヤーIDカラム（1つ）。
session_id	STRING（UUID）	プレイセッション内のイベントをグループ化します。
timestamp	TIMESTAMP	イベントが発生した日時。
counter_name	STRING	ドット区切りのイベント名（例: match.kills）。パラメーターを記録するには#<parameter>を付加します（例: level.started#forest_3）。
counter_value	INT	イベントの値（例: キル数）。
build_version	STRING	（省略可） イベントを生成したゲームビルド。

デュレーションテーブル

カラム	型	説明
（識別子）	STRING	プレイヤーIDカラム（1つ）。
session_id	STRING（UUID）	プレイセッション内のイベントをグループ化します。
start_time	TIMESTAMP	アクティビティが開始した日時。
end_time	TIMESTAMP	アクティビティが終了した日時。
duration_name	STRING	ドット区切りのイベント名（例: match.round）。

---

取り込みの動作

最初にフルインポート、その後は増分

テーブルが初めて検証されると、FirstLookはそのスナップショット（全履歴、またはBackfill from日付以降のすべて）を読み取り、その後テーブルのDeltaバージョンを追跡して各変更で追加された行のみを読み取ります。上記のdelta.targetFileSizeのガイダンスに従っている場合、大きな履歴も1回のパスでインポートされます。

イベントは追記専用

FirstLookは挿入された行のみを取り込みます。テーブルの更新と削除は無視されます。プレイヤーイベントは不変のファクトとして扱われるため、修正は既存の行を編集するのではなく、新しいイベントとして追記してください。これには2つの影響があります。

• フルリロードは安全です。 上流のジョブがテーブルを書き直す（INSERT OVERWRITE、パイプラインの再実行）場合でも、FirstLookの重複検出が再挿入された行を吸収するため、二重カウントは発生しません。非効率ではありますが、実害はありません。
• Databricksで行を削除しても、FirstLookからイベントは削除されません。

イベントがチャートに表示されるタイミング

インポートされた行はその実行が完了次第保存され、アナリティクスチャートには次回のスケジュールされた集計更新（通常は1時間以内）で反映されます。インポートが完了しているにもかかわらずチャートがまだ更新されていない場合は正常な状態です。

クレデンシャルのライフサイクル

Delta Sharingのベアラートークンは通常、有効期限付きで作成されます。FirstLookはクレデンシャルファイルから有効期限を読み取り、失効の14日前から設定ページにバナーを表示します。読み取りが繰り返し失敗した場合、取り込みは一時停止されます。

ローテーションするには、Databricksでレシピエントの新しいクレデンシャルファイルを生成し（ALTER RECIPIENT firstlook ROTATE TOKENまたはUIから）、設定ページのCredentialセクションにペーストします。テーブルの設定とインポート履歴はそのまま維持され、クレデンシャルの失敗により取り込みが一時停止されていた場合は自動的に再開されます。

---