Salesforce データエンジニア視点で深掘り！CRM Analytics (旧 Einstein Analytics) の SAQL と API 連携活用術

背景と応用シナリオ

Salesforce エコシステムにおいて、データ分析の重要性はますます高まっています。標準のレポートとダッシュボード機能は日常的な業務報告には非常に優れていますが、より大量のデータセットを扱い、複雑なデータ変換や複数のデータソースを統合した高度な分析を行いたい場合、その限界に直面することがあります。ここで登場するのが、Salesforce CRM Analytics (旧称: Einstein Analytics) です。

CRM Analytics は、Salesforce 内外の大量のデータを高速に集計・分析し、インタラクティブなダッシュボードを通じてビジネスインサイトを提供する強力なプラットフォームです。Salesforce データエンジニアの視点から見ると、CRM Analytics は単なる可視化ツールではありません。それは、Salesforce データを中心とした堅牢なデータパイプラインを構築し、ビジネスの意思決定をデータドリブンで支援するための、スケーラブルな分析基盤です。

本記事では、特にデータエンジニアが腕を振るうべき領域である SAQL (Salesforce Analytics Query Language) と Analytics REST API に焦点を当てます。

応用シナリオ

例えば、ある企業が次のような課題を抱えているとします。

「Salesforce の商談データだけでなく、外部のマーケティングオートメーションツールから得られるキャンペーンの成果データ、そして基幹システム (ERP) にある在庫データを統合し、『どのキャンペーンが、どの在庫を持つ製品の成約に最も貢献したか』を分析したい。さらに、その分析結果をプログラムで定期的に取得し、別のデータウェアハウスに格納したい。」

このシナリオでは、CRM Analytics の標準的なUI（レシピやデータフロー）だけでは要件を満たすのが難しい場合があります。特に、動的なクエリの実行や外部システムとの密な連携が求められる場面で、SAQL と Analytics REST API の知識が不可欠となります。データエンジニアはこれらの技術を駆使して、複雑なデータ統合と分析の自動化を実現するのです。

原理説明

CRM Analytics の中核をなすデータ処理の仕組みを、データエンジニアの観点から解説します。

Data Recipe (データレシピ) と Dataflow (データフロー)

これらは CRM Analytics における主要な ETL (Extract, Transform, Load) ツールです。

Data Recipe (データレシピ) は、より新しい世代の直感的なUIを持つデータ準備ツールです。複数のデータソースの結合、数式の追加、データのクレンジングなどをGUIベースで実行できます。多くのユースケースでは、レシピで十分なデータ変換が可能です。

Dataflow (データフロー) は、JSON形式でデータ変換ロジックを定義する、より伝統的なETLツールです。複雑な分岐や細かな制御が可能ですが、レシピに比べて学習コストがやや高くなります。

データエンジニアは、まずこれらのツールを使って Salesforce オブジェクトや外部データソースからデータを取り込み、分析に適した Dataset (データセット) を作成します。

Dataset (データセット)

Dataset (データセット) は、CRM Analytics 内に存在する、クエリに最適化された非正規化済みのデータストアです。Salesforce の標準オブジェクトとは異なり、インデックス化され、カラムナフォーマットで圧縮保存されているため、数億行のデータに対しても非常に高速な集計クエリを実行できます。データエンジニアの役割は、パフォーマンスを最大化するような効率的なデータセットを設計・構築することです。

SAQL (Salesforce Analytics Query Language)

SAQL (サクルと読みます) は、CRM Analytics のデータセットに対してクエリを実行するための専用言語です。SQL に似た構文を持ちますが、ビッグデータのストリーミング処理やグルーピングに特化した独自の概念を持っています。ダッシュボード上のすべてのグラフやテーブルは、裏側でこの SAQL が実行されることによって描画されています。

SAQL の基本的な流れは以下のようになります。

1. load: 対象となるデータセットを読み込みます。 2. filter: データを特定の条件で絞り込みます。 3. group by: 指定したディメンション（項目）でデータをグループ化します。 4. foreach: グループ化された各ストリームに対して集計処理（合計、平均、件数など）や射影（列の選択・追加）を行います。 5. order by: 結果をソートします。 6. limit: 結果の件数を制限します。

この `group by` と `foreach` の組み合わせが SAQL の最も強力な部分であり、SQL の `GROUP BY` 句と集計関数をより柔軟にしたものと考えることができます。

Analytics REST API

Analytics REST API は、HTTPリクエストを通じて CRM Analytics のほぼすべての機能にプログラムからアクセスするためのインターフェースです。データエンジニアはこのAPIを利用して、以下のような操作を自動化します。

・SAQL クエリの実行と結果の取得
・データセットのメタデータ取得や更新
・データフローやレシピの実行状況の監視
・アプリケーションやダッシュボードの管理

このAPIを使うことで、例えば「外部のバッチ処理の完了をトリガーにして CRM Analytics のデータ更新ジョブを開始し、完了後に SAQL を実行して結果を抽出し、外部システムに通知する」といった一連のデータパイプラインをコードで構築することが可能になります。

示例代码

ここでは、Analytics REST API を使用して SAQL クエリを実行する方法を示します。この例では、商談 (Opportunity) データセットから、ステージ (StageName) ごとに商談の件数と平均金額を算出します。

このコードは Salesforce Developer Documentation の「Execute a SAQL Query」の例に基づいています。

SAQL クエリの構造

まず、実行する SAQL クエリを定義します。

// 'DTC_Opportunity' という名前のデータセットを読み込む
q = load "DTC_Opportunity";
// StageName (商談フェーズ) でグループ化する
q = group q by 'StageName';
// グループ化された各レコードに対して処理を行う
q = foreach q generate 
    'StageName' as 'StageName', // StageName をそのまま出力
    count() as 'count',         // グループ内のレコード件数を 'count' として集計
    avg('Amount') as 'avg_Amount'; // Amount (金額) の平均値を 'avg_Amount' として集計
// 件数 (count) の降順で結果をソートする
q = order q by 'count' desc;
// 結果を100件に制限する
q = limit q 100;

Analytics REST API での実行

上記の SAQL クエリを Analytics REST API の `/services/data/vXX.X/wave/query` エンドポイントに POST リクエストで送信します。リクエストボディは以下のようになります。

{
  "query": "q = load \"DTC_Opportunity\"; q = group q by 'StageName'; q = foreach q generate 'StageName' as 'StageName', count() as 'count', avg('Amount') as 'avg_Amount'; q = order q by 'count' desc; q = limit q 100;"
}

このリクエストを、認証済みのセッション（例えば Apex から `UserInfo.getSessionId()` で取得したセッションIDや、接続アプリケーションの OAuth 2.0 フローで取得したアクセストークンを使用）を用いて送信します。

Apex からの実行例

Salesforce の Apex クラスからこの API をコールする際のサンプルコードです。

// (c) 2023 Salesforce, Inc. All rights reserved.
// This code is subject to the terms of the Salesforce Master Subscription Agreement.
// For more information, see the Salesforce Developer Documentation.
public class AnalyticsQueryExample {
    public static void executeSaqlQuery() {
        // SAQL クエリ文字列。エスケープ文字に注意。
        String saqlQuery = 'q = load "DTC_Opportunity";';
        saqlQuery += ' q = group q by \\'StageName\\';';
        saqlQuery += ' q = foreach q generate \\'StageName\\' as \\'StageName\\', count() as \\'count\\', avg(\\'Amount\\') as \\'avg_Amount\\';';
        saqlQuery += ' q = order q by \\'count\\' desc;';
        saqlQuery += ' q = limit q 100;';

        // リクエストボディの作成
        String requestBody = '{"query": "' + saqlQuery + '"}';

        // HTTPリクエストのセットアップ
        HttpRequest req = new HttpRequest();
        // エンドポイントの指定。バージョンは組織に合わせて変更してください。
        req.setEndpoint(URL.getOrgDomainUrl().toExternalForm() + '/services/data/v58.0/wave/query');
        req.setMethod('POST');
        req.setHeader('Authorization', 'Bearer ' + UserInfo.getSessionId());
        req.setHeader('Content-Type', 'application/json');
        req.setBody(requestBody);

        // HTTPリクエストの送信とレスポンスの取得
        Http http = new Http();
        try {
            HttpResponse res = http.send(req);
            
            // 成功した場合の処理 (ステータスコード 200)
            if (res.getStatusCode() == 200) {
                System.debug('SAQL Query executed successfully.');
                System.debug('Response Body: ' + res.getBody());
                // ここでレスポンスのJSONをパースして結果を処理する
            } else {
                // エラー処理
                System.debug('Error executing SAQL Query.');
                System.debug('Status Code: ' + res.getStatusCode());
                System.debug('Response Body: ' + res.getBody());
            }
        } catch(System.CalloutException e) {
            System.debug('Callout error: '+ e.getMessage());
        }
    }
}

このコードは、現在ログインしているユーザのセッションを利用して Analytics REST API をコールアウトし、SAQLクエリを実行します。成功すれば、結果がJSON形式で返却されます。

注意事項

SAQL と Analytics REST API を利用する際には、以下の点に注意が必要です。

権限 (Permissions)

・ユーザ権限: API を実行するユーザには、「CRM Analytics Plus ユーザ」や「CRM Analytics Growth ユーザ」といった適切な権限セットライセンスと権限セットが必要です。
・データセットアクセス: ユーザはクエリ対象のデータセットが格納されているアプリケーションに対する「閲覧者」以上のアクセス権を持っている必要があります。
・セキュリティ述語 (Security Predicates): CRM Analytics では、データセットに対して行レベルのアクセス制御（Row-Level Security）を実装できます。これは「セキュリティ述語」と呼ばれ、ユーザごとやロールごとに閲覧できるデータを動的に制限します。API経由でクエリを実行した場合も、このセキュリティ述語が適用されるため、実行ユーザが見るべきでないデータは結果に含まれません。

API 制限 (API Limits)

Analytics REST API のコールは、Salesforce プラットフォーム全体のガバナ制限（同時実行APIリクエスト数や24時間あたりのAPIコール総数など）の対象となります。

さらに、CRM Analytics 固有の制限も存在します。
・SAQL クエリの長さ: クエリ文字列の長さに上限があります。
・同時クエリ実行数: 組織全体で同時に実行できるクエリの数には上限が設けられています。
・クエリのタイムアウト: 非常に時間のかかるクエリは、タイムアウトによって強制的に中断されることがあります。

これらの制限は、Salesforce のリリースごとに変更される可能性があるため、常に最新の公式ドキュメント「Salesforce Developer Limits and Allocations Quick Reference」を参照することが重要です。

エラーハンドリング (Error Handling)

API コールが失敗した場合、HTTPステータスコードとエラーメッセージを含むJSONレスポンスが返されます。一般的なエラー原因には、SAQL構文エラー、権限不足、存在しないデータセットや項目の参照などがあります。堅牢なアプリケーションを構築するためには、これらのエラーレスポンスを適切に解析し、リトライ処理やロギング、ユーザへの通知といったフォールバック機構を実装することが不可欠です。

まとめとベストプラクティス

CRM Analytics は、単なるダッシュボードツールではなく、データエンジニアがそのスキルを最大限に発揮できる高度な分析プラットフォームです。直感的なレシピ機能で迅速にデータ準備を進めつつ、より複雑で動的な要件には SAQL と Analytics REST API を活用することで、Salesforce を中心としたデータ活用の可能性を大きく広げることができます。

ベストプラクティス

1. 適切なツールの選択: GUIで完結するデータ変換はレシピを優先的に使用し、保守性を高めます。SAQL と API は、動的なクエリ生成、外部システムとの連携、カスタムUIへの分析機能の埋め込みなど、宣言的なツールでは実現できない場合に限定して使用します。

2. データセット設計の最適化: SAQL のパフォーマンスはデータセットの設計に大きく依存します。クエリ実行時に頻繁に結合を行うのではなく、ETL（レシピ/データフロー）の段階でデータを非正規化し、分析に最適なフラットなデータセットを作成しておくことがパフォーマンス向上の鍵です。

3. クエリの早期フィルタリング: SAQL を記述する際は、`filter` ステートメントを可能な限り早い段階（`load` の直後など）に配置してください。これにより、後続の処理（`group` や `foreach`）で扱うデータ量を減らし、クエリ全体のパフォーマンスを劇的に改善できます。

4. SAQL のバージョン管理: API などで利用する複雑な SAQL クエリは、単なる文字列ではなく「コード」として扱うべきです。Git などのバージョン管理システムで管理し、変更履歴を追跡できるようにしましょう。

5. API 制限の考慮: 大量の API コールが想定されるシステムを設計する場合は、バルク処理やキャッシュ機構を導入し、Salesforce のガバナ制限に抵触しないように注意深く設計してください。

Salesforce データエンジニアとしてこれらの技術を習得することは、組織のデータ駆動型文化を推進し、ビジネスに直接的な価値をもたらすための強力な武器となるでしょう。

にゃんこのSalesforce日記

このブログを検索