動的 SOQL

動的 SOQL は、Apex コードを使用して、実行時に SOQL 文字列の作成を参照します。動的 SOQL によって、さらに柔軟なアプリケーションの作成が可能になります。たとえば、エンドユーザーの入力に基づいた検索を作成したり、さまざまな項目名のレコードを更新したりできます。

実行時に動的 SOQL クエリを作成するには、次のいずれかの方法で Database.query または Database.queryWithBinds メソッドを使用します。

• クエリが 1 つのレコードを返すときに、1 つの sObject を返します。
  sObject s = Database.query(string);

• クエリが複数のレコードを返すときに、sObject のリストを返します。
  List<sObject> sobjList = Database.query(string);

• バインド変数の対応付けを使用して sObject のリストを返します。
  List<sObject> sobjList = Database.queryWithBinds(string, bindVariablesMap, accessLevel);

通常の割り当てステートメントや for ループなど、インライン SOQL クエリが使用可能な場合はいつでも、Database.query および Database.queryWithBinds メソッドを使用できます。結果は、静的 SOQL クエリの処理とほぼ同様の方法で処理されます。

API バージョン 55.0 以降では、ユーザーモードでのデータベース操作機能の一部として、accessLevel パラメーターを使用してユーザーモードまたはシステムモードでクエリ操作を実行します。accessLevel パラメーターは、メソッドをシステムモードで実行するか (AccessLevel.SYSTEM_MODE)、ユーザーモードで実行するか (AccessLevel.USER_MODE) を指定します。システムモードでは、現在のユーザーのオブジェクト権限と項目レベル権限が無視され、クラスの sharing キーワードでレコード共有ルールが制御されます。ユーザーモードでは、現在のユーザーのオブジェクト権限、項目レベルのセキュリティ、および共有ルールが適用されます。デフォルトはシステムモードです。

動的 SOQL 結果は、Account や MyCustomObject__c、または汎用 sObject データ型などのように、具体的な sObject として指定できます。実行時に、システムは、クエリのタイプが宣言された変数の型と一致しているかどうか検証します。クエリが正しい sObject データ型を返さない場合、ランタイムエラーが発生します。したがって、汎用 sObject から具体的な sObject を割り当てる必要はありません。

動的 SOQL クエリには、静的クエリと同じガバナ制限があります。ガバナ制限についての詳細は、「実行ガバナと制限」を参照してください。

SOQL クエリの構文の詳細は、『SOQL および SOSL リファレンス』の「Salesforce Object Query Language (SOQL)」を参照してください。

String myTestString = 'TestName';
List<sObject> sobjList = Database.query('SELECT Id FROM MyCustomObject__c WHERE Name = :myTestString');

MyCustomObject__c myVariable = new MyCustomObject__c(field1__c ='TestField');
List<sObject> sobjList = Database.query('SELECT Id FROM MyCustomObject__c WHERE field1__c = :myVariable.field1__c');

String resolvedField1 = myVariable.field1__c;
List<sObject> sobjList = Database.query('SELECT Id FROM MyCustomObject__c WHERE field1__c =  :resolvedField1');

Map<String, Object> acctBinds = new Map<String, Object>{'acctName' => 'Acme Corporation'};

List<Account> accts = 
    Database.queryWithBinds('SELECT Id FROM Account WHERE Name = :acctName',
                            acctBinds, 
                            AccessLevel.USER_MODE);