Salesforce Apexにおける動的SOQLの完全ガイド：開発者向け

背景と応用シナリオ

Salesforceプラットフォームでアプリケーションを開発する私たちSalesforce Developer (Salesforce 開発者) にとって、データの照会は日常的なタスクです。その中心となるのが SOQL (Salesforce Object Query Language) です。ほとんどの場合、クエリの構造が事前に分かっているため、静的なSOQLクエリを直接Apexコードに埋め込みます。これはコンパイル時に構文がチェックされ、非常に安全で効率的です。

しかし、アプリケーションの要件が複雑になると、静的なSOQLだけでは対応できない場面に直面します。例えば、以下のようなシナリオです。

1. ユーザー入力に基づく動的な検索画面

エンドユーザーが画面上で検索対象の項目、検索条件、ソート順を自由に選択できるような機能を実装する場合、SOQLクエリを事前に固定することはできません。ユーザーの選択に応じて、SELECT句、WHERE句、ORDER BY句を動的に組み立てる必要があります。

2. 設定に基づく汎用的なコンポーネント

カスタムメタデータやカスタム設定を使用して、管理者がコンポーネントの動作（どのオブジェクトのどの項目を表示するかなど）を定義できるようにする場合があります。この場合、Apexコードは実行時にそれらの設定を読み込み、SOQLクエリを生成する必要があります。

3. 項目アクセス権限（FLS）に応じたクエリの構築

実行ユーザーがアクセス権を持たない項目をSOQLに含めると、例外が発生します。ユーザーの権限に応じて、クエリに含める項目を動的に決定したい場合があります。

このような、クエリの構造が実行時まで確定しない状況で強力なツールとなるのが、Dynamic SOQL (動的 SOQL) です。Dynamic SOQLは、SOQLクエリを文字列として実行時に構築し、Database.query() メソッドなどを使って実行する手法です。これにより、静的SOQLの制約を超えた、非常に柔軟で強力なデータアクセスロジックを実装することが可能になります。

原理説明

Dynamic SOQLの核心は、SOQLクエリを単なる文字列として扱い、Apexコード内でその文字列を生成・操作することにあります。

静的SOQLは、角括弧 [ ] で囲んでコード内に直接記述します。

List<Account> accounts = [SELECT Id, Name FROM Account WHERE Name = 'ACME'];

この形式の利点は、Salesforceコンパイラが保存時にSOQLの構文、オブジェクトや項目の存在を検証してくれる点です。これにより、タイプミスなどの単純なエラーを早期に発見できます。

一方、Dynamic SOQLは文字列を組み立て、Database.query(string) メソッドに渡して実行します。

String objectName = 'Account';
String fieldName = 'Name';
String filterValue = 'ACME';
String queryString = 'SELECT Id, ' + fieldName + ' FROM ' + objectName + ' WHERE ' + fieldName + ' = \'' + filterValue + '\'';
List<sObject> sObjects = Database.query(queryString);

このアプローチでは、queryString 変数の内容は実行時に決定されます。これにより、前述のシナリオで求められるような柔軟性が得られます。しかし、大きな力には大きな責任が伴います。クエリ文字列はコンパイル時には検証されないため、実行時に構文エラーが発生する可能性があります。また、最も注意すべきは SOQL Injection (SOQLインジェクション) と呼ばれるセキュリティ脆弱性のリスクです。これについては後ほど詳しく解説します。

示例代码

ここでは、Salesforceの公式ドキュメントに記載されているコード例を基に、Dynamic SOQLの具体的な使い方を説明します。

基本的なDynamic SOQLの例

この例では、オブジェクト名とWHERE句の条件を動的に設定して取引先を検索します。

/*
 * @description 渡されたオブジェクト名とフィルター条件に基づいてレコードを検索するメソッド
 * @param objectName API参照名 (例: 'Account', 'Contact')
 * @param whereClause WHERE句の条件 (例: 'Name = \'GenePoint\'')
 * @return 検索結果のsObjectリスト
 */
public List<sObject> searchForRecords(String objectName, String whereClause) {
    // 基本となるクエリ文字列を構築
    // SELECT句には固定の項目を指定
    String queryString = 'SELECT Id, Name FROM ' + objectName;

    // whereClauseが空でない場合、WHERE句を追加
    if (String.isNotBlank(whereClause)) {
        queryString += ' WHERE ' + whereClause;
    }

    // クエリの最大件数を50件に制限
    queryString += ' LIMIT 50';

    // Database.query() を使用して動的SOQLを実行
    // このメソッドは sObject のリストを返すため、具体的な型 (Account, Contactなど) ではなく
    // 汎用的な sObject 型のリストで受け取るのが一般的
    List<sObject> recordList = Database.query(queryString);

    return recordList;
}

// メソッドの呼び出し例
// List<sObject> result = searchForRecords('Account', 'BillingState = \'CA\'');

SOQLインジェクション対策：バインド変数の使用

ユーザーからの入力を直接クエリ文字列に連結すると、悪意のある入力によって意図しないデータが漏洩する「SOQLインジェクション」のリスクが生じます。これを防ぐための最善の方法は、Database.queryWithBinds() メソッドとバインド変数を使用することです。

/*
 * @description ユーザー入力を安全に利用して取引先を検索するメソッド
 * @param nameFilter ユーザーが入力した取引先名のフィルター文字列
 * @return 検索結果のAccountリスト
 */
public static List<Account> searchAccountsSecurely(String nameFilter) {
    // クエリ文字列を構築。ユーザー入力が入る場所は「:」を接頭辞とするバインド変数でプレースホルダーにする
    // LIKE句で使用するため、ワイルドカード「%」もバインド変数に含める
    String query = 'SELECT Id, Name FROM Account WHERE Name LIKE :searchKey';

    // バインド変数に渡す値を準備する
    // ユーザー入力の前後にワイルドカードを追加
    String searchKey = '%' + nameFilter + '%';

    // バインド変数を格納するためのMapを準備
    // Mapのキーがクエリ文字列内のバインド変数名に対応する
    Map<String, Object> bindParams = new Map<String, Object>{
        'searchKey' => searchKey
    };

    // Database.queryWithBindsを使用して安全にクエリを実行
    // 第1引数: バインド変数を含むクエリ文字列
    // 第2引数: バインド変数のMap
    // 第3引数: アクセスモード (この例ではUserMode)
    // 実行時に、Salesforceが :searchKey を searchKey の値で安全に置換してくれる
    List<Account> accounts = Database.queryWithBinds(query, bindParams, AccessLevel.USER_MODE);

    return accounts;
}

// メソッドの呼び出し例
// String userInput = 'United';
// List<Account> result = searchAccountsSecurely(userInput);

この方法では、ユーザー入力はリテラル値として扱われるため、クエリの構造自体を変更することはできません。これは、SOQLインジェクションに対する最も効果的な防御策です。

注意事項

Dynamic SOQLを扱う際には、以下の点に十分注意する必要があります。

1. SOQL Injection (SOQLインジェクション)

最も警戒すべきセキュリティリスクです。ユーザーからの入力を検証せずにクエリ文字列に直接連結すると、攻撃者がクエリを操作できてしまいます。例えば、'test' OR Name LIKE '% のような入力があった場合、WHERE句が意図せず変更され、全てのデータが返されてしまう可能性があります。

対策:

Database.queryWithBinds() の使用: 最も推奨される方法です。ユーザー入力は常にバインド変数として扱ってください。
String.escapeSingleQuotes() の使用: バインド変数が使えない場合（動的に項目名やオブジェクト名を指定する場合など）の次善策です。このメソッドは、文字列内のシングルクォートをエスケープ処理し、文字列リテラルとして安全に扱えるようにします。しかし、これは完全な解決策ではなく、queryWithBinds が使える場面ではそちらを優先すべきです。

2. Governor Limits (ガバナ制限)

Dynamic SOQLも静的SOQLと同様に、Salesforceのガバナ制限に従います。

SOQLクエリ発行回数: 1トランザクションあたり、同期Apexでは100回、非同期Apexでは200回まで。ループ内でDatabase.query()を呼び出すことは絶対に避けてください。
SOQLクエリで取得できる合計レコード数: 1トランザクションあたり50,000件まで。

3. 権限と共有ルール

Dynamic SOQLは、デフォルトで実行ユーザーの権限（オブジェクト権限、項目レベルセキュリティ(FLS)）と共有設定を尊重して実行されます。しかし、これをより明確にするために、WITH SECURITY_ENFORCED 句をクエリに追加することが推奨されます。これにより、ユーザーがアクセスできない項目やオブジェクトがクエリに含まれていた場合、QueryExceptionがスローされ、意図しないデータアクセスを確実に防ぐことができます。

String query = 'SELECT Id, Name, AnnualRevenue FROM Account WITH SECURITY_ENFORCED';
try {
    List<sObject> records = Database.query(query);
} catch (System.QueryException e) {
    // ユーザーがAnnualRevenueにアクセスできない場合などに例外が発生
    System.debug('FLS check failed: ' + e.getMessage());
}

4. エラーハンドリング

Dynamic SOQLのクエリ文字列は実行時に評価されるため、構文エラーは実行時例外 (QueryException) として発生します。必ず try-catch ブロックを使用して、クエリの失敗を適切に処理するようにしてください。これにより、予期せぬエラーでプロセス全体が停止するのを防ぎ、ユーザーに分かりやすいエラーメッセージを表示することができます。

5. クエリ文字列の長さ

SOQLクエリ文字列には長さの制限があります（現在は100,000文字）。非常に複雑なクエリを動的に生成する場合、この制限に達する可能性がないか考慮する必要があります。

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

Dynamic SOQLは、Salesforce開発者にとって非常に強力なツールであり、静的SOQLでは実現不可能な柔軟なアプリケーションを構築するために不可欠です。しかし、その力を正しく安全に利用するためには、以下のベストプラクティスを遵守することが重要です。

可能な限り静的SOQLを優先する: クエリの構造が事前に分かっている場合は、常に静的SOQLを使用してください。コンパイル時のチェックにより、コードの安全性と可読性が向上します。
SOQLインジェクションを徹底的に防御する: ユーザー入力を扱う際は、Database.queryWithBinds() を第一の選択肢とします。これにより、最も一般的なセキュリティ脆弱性を根本から防ぐことができます。
権限を意識したコーディング: WITH SECURITY_ENFORCED 句を活用し、項目レベルセキュリティ(FLS)を明示的に強制します。これにより、アプリケーションのセキュリティが強化されます。
ガバナ制限を常に念頭に置く: クエリの実行回数と取得レコード数を意識し、一括処理（Bulkification）の原則に従って設計してください。
堅牢なエラーハンドリングを実装する: Database.query() の呼び出しは、必ず try-catch ブロックで囲み、実行時エラーに備えてください。
コードの可読性を維持する: クエリ文字列の組み立てロジックが複雑になる場合は、ヘルパーメソッドを作成するなどして、コードをクリーンで理解しやすい状態に保つよう努めてください。

私たち開発者は、これらの原則を理解し実践することで、Dynamic SOQLの持つポテンシャルを最大限に引き出し、安全で、スケーラブルかつ高性能なSalesforceアプリケーションを構築することができます。

にゃんこのSalesforce日記

このブログを検索