SOQL と非同期 SOQL

Big Object は、SOQL または非同期 SOQL を使用して照会できます。非同期 SOQL では SOQL コマンドのサブセットを使用します。そして、非同期 SOQL は、Big Object 内に保持できる大量のデータを処理するために新しく設計されました。非同期 SOQL クエリは非同期に実行されるため、クエリがタイムアウトすることを心配する必要はありません。非同期 SOQL クエリは、Salesforce エンティティデータ、標準オブジェクト、カスタムオブジェクト、Big Object についてバックグラウンドで実行されます。非同期 SOQL は、Chatter REST API を介して実装されます。

通常、大量のデータを扱う場合には、標準 SOQL ではなく非同期 SOQL を使用します。Big Object から小さなデータセットのみが必要な場合や、すぐに結果が必要な場合は標準 SOQL を使用します。非同期 SOQL は標準オブジェクトや Big Object ではないカスタムオブジェクトでも動作しますが、これらのオブジェクトのサポートはパイロットです。

カスタム Big Object はすべてのライセンスに含まれていますが、非同期 SOQL は追加の Big Object 容量のライセンスにのみ含まれることに注意してください。

次の場合に標準 SOQL を使用します。

ユーザを待たせずに結果を UI に表示する。
Apex コードのブロック内の操作のためにすぐに結果を返す必要がある。
クエリが少量のデータを返すことがわかっている。

次の場合に非同期 SOQL を使用します。

何百万ものレコードに対して照会する。
確実にクエリを完了させる必要がある。
インデックス外で集計クエリや絞り込みを行う必要がない。

非同期 SOQL の使用事例。

要するに、非同期 SOQL を使用すると、関連性のあるデータを Big Object の何百万ものレコードから抽出して、管理可能な作業データセットを作成できます。

SOQL を使用して Big Object を照会する方法

すでに SOQL に精通している場合は、ここでもすぐに慣れるでしょう。Big Object に標準 SOQL を使用する場合、Big Object でないオブジェクトに SOQL を使用する場合との違いについて、いくつかの点に注意する必要があります。Big Object への SOQL クエリの場合、インデックスで定義された最初の項目から始め、クエリ内の最初の項目から最後の項目まで項目を飛ばさずにクエリを作成する必要があります。たとえば、インデックスで 3 つの項目を定義している場合、最初の項目と 3 番目の項目のみを使用してクエリを作成することはできません。

クエリの最後の項目では =、<、>、<=、>=、IN の比較演算子を使用できます。クエリのそれより前の項目では = 演算子のみを使用できます。!=、LIKE、NOT IN、EXCLUDES、INCLUDES 演算子は、Big Object を含むクエリでは無効です。

次のクエリでは、Big Object 内で Account__c、Game_Platform__c、Play_Date__c によってインデックスが定義されていると仮定します。

次のクエリは、インデックスの 3 つすべての項目を指定しています。このケースでは、Play_Date__c の検索条件を範囲にすることができます。

SELECT Account__c, Game_Platform__c, Play_Date__c
FROM Customer_Interaction__b
WHERE Account__c='001R000000302D3' AND Game_Platform__c='PC' AND Play_Date__c=2017-09-06T00:00:00Z

次のクエリは、欠落があるため機能しません。Game_Platform__c が必要です。

SELECT Account__c, Game_Platform__c, Play_Date__c
FROM Customer_Interaction__b
WHERE Account__c='001R000000302D3' AND Play_Date__c=2017-09-06T00:00:00Z

非同期 SOQL を使用して Big Object を照会する方法

Big Object から管理可能なデータセットを取得するために非同期 SOQL を使用するには、主に 2 つの方法があります。1 つ目は絞り込みを使用する方法です。絞り込みを使用して Big Object データのごく一部をカスタムオブジェクトに抽出できます。その後、それをレポート、ダッシュボード、またはその他の便利な分析ツールで使用できます。

管理可能なデータセットを作成するもう 1 つの方法は、大まかな集計を使用するものです。非同期 SOQL によってサポートされている集計関数は、AVG(field)、COUNT(field)、COUNT_DISTINCT(field)、SUM(field)、MIN(field)、MAX(field) です。これらの集計関数を使用すると、Big Object からどのデータを抽出するかをより詳細に制御できます。

クエリの作成

非同期 SOQL を使用して、カスタム Big Object Customer_Interaction__b を照会し、結果を対象オブジェクト Customer_Interaction_Analysis__c に格納します。カスタム Big Object から特定の日付のアカウント情報とゲーム内購入情報を対象オブジェクトに抽出します。抽出した情報はその後、対象オブジェクトをレポートや分析に使用できます。

必須項目

名前	種別	説明
`クエリ`	文字列	実行する SOQL クエリのパラメータを指定します。
`targetObject`	文字列	クエリの結果を挿入する標準オブジェクト、カスタムオブジェクト、外部オブジェクト、または Big Object。
`targetFieldMap`	Map<String, String>	クエリ結果の項目を対象オブジェクトの項目に対応付ける方法を定義します。 `targetFieldMap` パラメータを定義する場合、データ型の対応付けが一貫していることを確認してください。ソース項目と対象項目が一致しない場合、次の考慮事項が適用されます。任意のソース項目を対象テキスト項目に対応付けることができます。ソース項目と対象項目が両方とも数値の場合、対象項目の小数点以下の桁数はソース項目の桁数以上である必要があります。それ以外の場合、要求が失敗します。この動作は、変換でデータが失われないようにするためです。クエリ結果の項目が複数回対応付けられる場合、対象オブジェクトの異なる項目に対応付けられる場合でも、最後の対応付けのみが使用されます。

URI の例

https://MyDomainName.my.salesforce.com/services/data/v41.0/async-queries/

POST のリクエストボディ

{ 
   "query": "SELECT Account__c, In_Game_Purchase__c FROM Customer_Interaction__b WHERE Play_Date__c=2017-09-06T00:00:00Z",
   
   "operation": "insert",
   
   "targetObject": "Customer_Interaction_Analysis__c", 
        
   "targetFieldMap": {"Account__c":"Account__c",
                      "In_Game_Purchase__c":"Purchase__c"
                      },
   "targetValueMap": {"$JOB_ID":"BackgroundOperationLookup__c",
                      "Copy fields from source to target":"BackgroundOperationDescription__c"
                     }
}

このクエリでは、顧客操作の Big Object から特定の日付 (2017-09-06) のアカウント情報とゲーム内購入情報を取得して、そのデータを作成済みのカスタムオブジェクト Customer_Interaction_Analysis__c に送信します。標準 SOQL ではなく非同期 SOQL を使用しているため、他のインデックス付き項目が含まれることを心配せずに絞り込むことができます。この新しいカスタムオブジェクトには、その日付のすべてのアカウント情報とゲーム内購入情報が入力されます。そしてそれを基に分析を行い、このゲームがこれほどまでに大成功した理由の解明を図ることができます。

POST のレスポンスボディ

レスポンスボディには、クエリの jobId、クエリの状況、関連メッセージが含まれます。

{ 
   "jobId": "08PD000000003kiT", 
   
   "message": "",
    
   "query": "SELECT Account__c, In_Game_Purchase__c FROM Customer_Interaction__b WHERE Play_Date__c=2017-09-06T00:00:00Z",  
    
   "status": "New",
     
   "targetObject": "Customer_Interaction_Analysis__c", 
     
   "targetFieldMap": {"Account__c":"Account__c", 
                      "In_Game_Purchase__c":"Purchase__c"
                     },
   "targetValueMap": {"$JOB_ID":"BackgroundOperationLookup__c",
                      "Copy fields from source to target":"BackgroundOperationDescription__c"
                     } 
}

クエリ状況の追跡

クエリの状況を追跡するには、jobID を指定して HTTP GET 要求を使用します。クエリの状況が status 項目に返されます。jobID を指定しなかった場合は、すべてのクエリの状況が返されます。status は、次のいずれかになります。

Canceled — ジョブが実行される前にキャンセルされました。
Success — ジョブが正常に完了しました。
Failed — ジョブが送信された後に失敗したか、要求が非同期 SOQL 制限を超えているため失敗しました。メッセージ項目に失敗の理由の詳細が表示されます。
Running — ジョブが正常に実行中で、組織は制限を超えていません。
Scheduled — 新しいジョブが作成およびスケジュールされ、まだ実行されていません。

また、jobId を指定して HTTP DELETE 要求を使用すると、クエリをキャンセルすることができます。完了したクエリをキャンセルしても影響はありません。

非同期 SOQL は非同期に実行されます。そのため、クエリの完了には時間がかかる場合があります。前述したように、時間が重要でデータセットが十分に小さい場合は標準 SOQL を使用します。または、もっと人気のない架空のゲームを考えて、これらの例に使用することもできますが、それは面白くありませんね。

URI の例

https://MyDomainName.my.salesforce.com/services/data/v41.0/async-queries/08PD000000003kiT

GET 応答の例

{
"jobId": "08PD000000003kiT",
"message": "",
"query": "SELECT Account__c, In_Game_Purchase__c FROM Customer_Interaction__b WHERE Play_Date__c=2017-09-06T00:00:00Z",  
"status": "Success",
"targetObject": "Customer_Interaction_Analysis__c",
"targetFieldMap": {"Account__c":"Account__c",
"In_Game_Purchase__c":"Purchase__c" } 
}

この応答は、クエリが正常に完了したことを示します。素晴らしい! 次は、レポートとダッシュボードの準備をしましょう!

エラーの処理

非同期 SOQL クエリの実行中には、次の 2 種類のエラーが発生する可能性があります。

クエリ実行のエラー
対象 Big Object に結果を書き込むときの 1 つ以上のエラー

実行で問題になる例として、無効なクエリを送信し、非同期 SOQL 制限のいずれかを超えることが挙げられます。もう 1 つの例は、クエリによって基盤となるインフラストラクチャに問題が発生する場合です。これらのエラーの場合、レスポンスボディに含まれる状況は Failed となります。メッセージパラメータに失敗の原因の詳細が含まれます。

クエリの実行には成功しても、対象オブジェクトに結果を書き込もうとしたときにエラーが発生する場合もあります。大量のデータを処理するため、すべてのエラーを捕捉するのは非効率的です。代わりに、生成されたエラーのサブセットが BackgroundOperationResult オブジェクトに取得され、数日間保持されます。このオブジェクトは、非同期 SOQL クエリの jobId を使用して特定の非同期 SOQL クエリのエラーに絞りこんで照会できます。非同期 SOQL ジョブの情報は 1 年間保持されます。

まとめ

組織でカスタム Big Object を使用するために必要なことをすべて学習しました。これで、何十億ものレコードを意のままに操ることができます。

非同期 SOQL については、表層部を見てきたにすぎません。「リソース」セクションを参照して、非同期 SOQL でサポートされるすべての標準 SOQL コマンドや他の使用事例を確認してください。また、使用できる省略可能な項目の情報は、POST 要求にも表示されます。そして、Big Object から抽出したデータの分析を設定する方法のアイデアについては、「Analytics データインテグレーションの基本」モジュールを参照してください。これらのデータを使用して、あらゆる便利なグラフやダッシュボードを作成することができます。

Big Object のクエリ

学習の目的