API リファレンス: Scribe

Scribe は ApexEloquent のクエリビルダー。型ヒントとメソッドチェーンで SOQL を組み立てる immutable なクラスです。各メソッドは新しい Scribe インスタンスを返します。

使い方や典型シナリオは Scribe でクエリを組み立てる を参照してください。

Static ファクトリ

SELECT 系

List<String> oppFields = new List<String>{ 'Id', 'Name', 'StageName' };
Scribe scribe = Scribe.of(Opportunity.class)
  .fields(oppFields)
  .parentField(Scribe.asParent('AccountId').field('Name'));

SELECT id, name, stagename, Account.name FROM Opportunity

SELECT 句の項目名は小文字に正規化され、親項目はリレーション名を前置して並びます (自分の項目 → 親の項目の順)。WHERE 句の項目名は元の表記のままです。

WHERE 系

比較・包含・パターンマッチ

項目名は組み立て時に検証される (v3.12.0+ / v2.10.0+)

SELECT 句が存在しない項目を弾くのは以前からですが、v3.12.0 からは WHERE 句の項目名も、組み立て時 (toSoql() / get()) に対象オブジェクトの describe と照合されます。存在しない項目名は ApexEloquentException になります。

Scribe.of(Contact.class).field('LastNam')                        // 弾かれる (以前から)
Scribe.of(Contact.class).field('Id').whereEqual('LastNam', 'x')  // 弾かれる (v3.12.0 から)

以前のバージョンでは、未知の項目名は型が解決できないため値が文字列として引用符付きで出力されていました (whereGreaterThan('Amoun', 1000) → Amoun > '1000')。実行時のエラーは型の不一致を指すので綴り間違いに気づきにくく、しかも MockEloquent は SOQL を実行しないので、単体テストでは緑のまま本番まで届いていました。

• 項目名にドットは書けません。whereEqual('Account.Type', 'x') は弾かれます。親の項目で絞るときは parentCondition(Scribe.asParent('AccountId').whereEqual('Type', 'x')) と書きます
• ポリモーフィックな親 (Owner / Queue / What / Who) での絞り込みと、項目の位置に SOQL 関数 (toLabel(Status) / convertCurrency(...) / CALENDAR_YEAR(...)) を書く形は未対応です
• ignoreWhen(true) で取り下げた条件は検証されません。取り下げる側の分岐しか通らないテストでは綴り間違いが残るので、ignoreWhen を書いたら両方の分岐をテストで通します
• orderBy('Account.Name') のドット表記は引き続き使えます (SOQL に親側の ORDER BY 構文が無く、親の項目で並べる唯一の書き方のため)。ORDER BY / GROUP BY / 集計句の項目名は、現時点では検証対象外です

⚠️ 上げた瞬間に、これまで一度も失敗していなかったクエリが落ちることがあります。空の whereNotIn で条件ごと消えていたもの、テストが通らない分岐にあったものなどです。テストが赤くなったら、旧バージョンに戻す前に項目名を確認してください。

空コレクションの扱い (whereIn / whereNotIn で非対称)

whereIn / whereNotIn に空のコレクションを渡したときの挙動は、両者で異なります。

SOQL としてはどちらも妥当ですが、「空なら絞り込まない」つもりで whereIn を書くと 0 件になります。意図を明示するなら、次の ignoreWhen を使ってください。

論理結合とグループ化

// (Industry = 'Tech' AND Name = 'X') OR BillingCity = 'Tokyo'
Scribe scribe = Scribe.of(Account.class)
  .field('Id')
  .whereGroup(
    Scribe.asGroup()
      .whereEqual('Industry', 'Tech')
      .whereEqual('Name', 'X')
  )
  .orCondition()
  .whereEqual('BillingCity', 'Tokyo');

SELECT id FROM Account WHERE (Industry = 'Tech' AND Name = 'X') OR BillingCity = 'Tokyo'

AND と OR を素で混ぜると組み立て時に落ちる (v3.5.0+)

SOQL は 1 つの階層で AND と OR が括弧なしで混ざることを許しません。次はどちらの向きでも ApexEloquentException になり、whereGroup を使うよう案内されます。

// ❌ AND のあとに OR
.whereEqual('Industry', 'Tech').whereEqual('Name', 'X').orCondition().whereEqual('BillingCity', 'Tokyo')

⚠️ v3.5.0 未満では OR-after-AND がすり抜けます。 toSoql() は成功するのに、実行時に SOQL 側が unexpected token: OR で落ちるという分かりにくい失敗になっていました。

判定はチェーン時ではなく組み立て時です。ignoreWhen() による取り下げや、空の whereNotIn のような意味上のスキップで混在が解消されるケースを、正しく通すためです。

条件を動的に取り下げる: ignoreWhen

「入力が空なら条件を付けない」を、if 分岐や再代入なしに 1 本のチェーンで書けます。

Scribe scribe = Scribe.of(Opportunity.class)
  .field('Id')
  .whereIn('Id', ids).ignoreWhen(ids.isEmpty())
  .whereLike('Name', keyword).ignoreWhen(String.isBlank(keyword));

実行時の値によって、組み上がる SOQL が変わります。

-- ids に値があり、keyword は空のとき
SELECT id FROM Opportunity WHERE Id IN ('006000000000000AAA', '006000000000000AAB')
 
-- 両方とも空のとき (WHERE 句自体が付かない)
SELECT id FROM Opportunity

上の「空コレクションの扱い」で触れた、空の whereIn が 0 件になる罠も、これで避けられます。

必ず where...() の直後にチェーンします。 先頭で呼ぶ / orderBy() の後で呼ぶ / 2 回続けて呼ぶと ApexEloquentException になります。ignoreWhen() がどの条件に掛かっているかを曖昧にしないための制約です。

whereGroup(...) の直後に置いた場合は、そのグループ全体が取り下げ対象になります。

null 値も取り下げられる (v3.5.0+)

whereGreaterThan / whereGreaterThanOrEqual / whereLessThan / whereLessThanOrEqual / whereLike / whereNotLike / whereIn / whereNotIn / whereIncludes / whereExcludes の 10 種 (オーバーロード込みで 12 メソッド) は null を受け付けません。

v3.5.0 から、この null エラーは組み立て時 (toSoql()) まで遅延します。チェーン時点では「無効な条件」として記録されるだけなので、直後の ignoreWhen(true) で取り下げられます。

// v3.4.x まで: whereGreaterThan の時点で例外 → ignoreWhen に到達しない
// v3.5.0 から: 取り下げられて WHERE 句に出ない
.whereGreaterThan('CloseDate', closeAfter).ignoreWhen(closeAfter == null)

取り下げられずに toSoql() まで残った場合は、どのメソッドのどの項目かを名指しし、ignoreWhen という逃げ道も併記した例外になります。

⚠️ whereEqual / whereNotEqual はこの 12 に含まれません。X = null は SOQL として正当なので、null がそのまま条件になります。

orCondition との組み合わせ

条件が 1 つも無い状態で orCondition() を呼んでも 何も起きません (no-op)。取り下げによって先頭の条件が消えても落ちず、残ったほうが単独の条件になります。

// 両方あれば OR、片方が消えれば残りが単独条件、両方消えれば WHERE 自体が付かない
Scribe scribe = Scribe.of(Opportunity.class)
  .field('Id')
  .whereIn('StageName', stages).ignoreWhen(stages.isEmpty())
  .orCondition()
  .whereIn('OwnerId', ownerIds).ignoreWhen(ownerIds.isEmpty());

-- 両方あるとき
SELECT id FROM Opportunity WHERE StageName IN ('Prospecting') OR OwnerId IN ('005000000000000AAA')
 
-- stages だけあるとき (OR が消え、単独条件になる)
SELECT id FROM Opportunity WHERE StageName IN ('Prospecting')
 
-- 両方とも空のとき
SELECT id FROM Opportunity

OR 条件だけが取り下げられた場合、OR モードも一緒に解除されます。取り下げた条件の OR マーカーが残って、後続の素の条件が弾かれる、ということは起きません。

ORDER / LIMIT / OFFSET / forUpdate

制約: forUpdate は orderBy および offset と併用できません。組み立て段階で例外が出ます。

集計関数

alias は必須引数 です。Salesforce 標準の AggregateResult はエイリアスを省略するとデフォルトで expr0 / expr1 / ... (宣言順) のフィールド名でアクセスする必要があり、初学者の罠になりがちですが、ApexEloquent はメソッドシグネチャでエイリアスを強制することでこのつまずきを避けています。戻り値の取り出しは aggregateEntry.get('alias 名') で、自分が付けた名前で参照できます。

そのほかの注意:

• 同じ alias を複数の集計関数で使うと例外。
• 子サブクエリ (withChildren) と集計関数の併用は不可。

GROUP BY / HAVING

Scribe scribe = Scribe.of(OpportunityLineItem.class)
  .field('Product2Id')
  .sum('TotalPrice', 'totalPrice')
  .parentField(
    Scribe.asParent('OpportunityId').field('Id').max('Amount', 'maxAmount')
  )
  .groupByField('Product2Id')
  .groupByParent(Scribe.asParent('OpportunityId').groupByField('Id'))
  .havingCondition(
    Scribe.asHaving().whereGreaterThan('totalPrice', 1000)
  );

SELECT product2id, SUM(TotalPrice) totalPrice, Opportunity.id, MAX(Opportunity.Amount) maxAmount
FROM OpportunityLineItem
GROUP BY Product2Id, Opportunity.Id
HAVING SUM(TotalPrice) > 1000

HAVING では alias が集計式に展開されます。whereGreaterThan('totalPrice', 1000) と書けば SUM(TotalPrice) > 1000 になるので、集計式を二度書く必要はありません。

検査・出力

toSoql() はデバッグや学習用にも使いますが、実用上の主役はバッチの start() です。

このほか、単体テスト専用に、組み立てたクエリが特定の条件を持っているかを検証する assertCondition / assertNoCondition / assertConditionAt / assertNoConditionAt / hasCondition / hasConditionAt / conditionAssertionMessage があります (v3.11.0+ / v2.9.0+、すべて @TestVisible)。MockEloquent.scribeAt(label) と組み合わせて使います。詳しくは API リファレンス: IEloquent / Eloquent / MockEloquent の「クエリの形を検証する」を参照してください。

toSoql() でバッチの QueryLocator を組み立てる

Database.getQueryLocator() は SOQL を文字列で要求するため、ここだけは Scribe をそのまま渡せません。組み立ては Scribe で行い、最後に toSoql() で文字列にします。

public Database.QueryLocator start(Database.BatchableContext bc) {
  return Database.getQueryLocator(scope().toSoql());
}

Scribe を切り出すと、テストでも SELECT 漏れ検知が効く

バッチには構造上の穴があります。execute(bc, scope) に渡ってくるレコードは プラットフォームが直接渡してくる もので、IEloquent を通りません。つまり「このクエリが何を SELECT したか」という契約が、Usecase 側に届きません。

• 本番: scope は実クエリの結果なので、SELECT していない項目に触れればプラットフォームが例外を投げます
• テスト: scope は自分で組み立てた MockEntry なので、何も検査されません

この差を埋めるのが fetchedBy(scribe) です。クエリの組み立てを @TestVisible なメソッドに切り出しておけば、テストから本番とまったく同じ Scribe を取り出して、モックに焼き付けられます。

public with sharing class RematchCompanyCardsHandler implements Database.Batchable<SObject> {
  public Database.QueryLocator start(Database.BatchableContext bc) {
    return Database.getQueryLocator(scope().toSoql());
  }
 
  // 本番とテストで同じ 1 つの定義を共有する
  @TestVisible
  private static Scribe scope() {
    List<String> cardFields = new List<String>{ 'Id', 'CompanyName__c', 'MatchStatus__c' };
    return Scribe.of(BusinessCard__c.class)
      .fields(cardFields)
      .whereEqual('MatchStatus__c', 'Unprocessed');
  }
}

SELECT id, companyname__c, matchstatus__c FROM BusinessCard__c WHERE MatchStatus__c = 'Unprocessed'

// テスト側: 本番の SELECT 契約をモックに焼き付ける
MockEntry card = MockEntry.of(BusinessCard__c.class)
  .autoId(1)
  .set('CompanyName__c', 'Acme')
  .fetchedBy(RematchCompanyCardsHandler.scope());

これで、Usecase が scope() に無い項目を読んだ瞬間に単体テストで落ちます。バッチの start に項目を足し忘れたまま Usecase 側だけ増やした、という食い違いを、本番に出る前に捕まえられます。

fetchedBy は API リファレンス: MockEntry を参照してください。

次に読む

• Scribe でクエリを組み立てる: 使い方ガイド
• 親項目・子サブクエリ・多対多: リレーション操作の典型例
• API リファレンス: IEloquent / Eloquent / MockEloquent: 組み立てた Scribe を実行する
• ApexEloquent ガイド: ガイド目次に戻る