List Filter Online の Query Builder: 条件、グループ、そして生成される CAML クエリ

概要

Query Builder は、Vitextra List Filter Online Web パーツの中でページ編集者が定義済みフィルターを設定する部分です。定義済みフィルターとは、Web パーツに表示されるすべてのアイテムが満たさなければならない条件の集合です。ユーザーはこのフィルターを見ることも解除することもできず、フィルター ウィンドウと列見出しのフィルターで結果をさらに絞り込むことだけができます。

定義済みフィルターは条件とグループのツリーとして保存され、SharePoint がサーバー側で実行する CAML クエリに変換されます。ブラウザーにすべてを読み込んでから絞り込むのではなく、条件に一致するアイテムだけがページ単位で返されます。これが、大きなリストでも Web パーツが高速に動作する理由です。

定義済みフィルターの代表的な用途:

• 現在のユーザーが作成または更新したドキュメントだけを表示する。
• ダッシュボード ページに過去 12 か月のレコードだけを表示する。
• 承認済みのアイテム、添付ファイルのあるアイテム、または Status が Closed ではないアイテムだけを表示する。
• 部署ごとにビューを作成することなく、1 つのリストから部署ごとのページを作成する。

Query Builder の場所

1. ページを編集モードで開き、List Filter Online Web パーツの [Web パーツの編集] を選択します。
2. プロパティ ウィンドウで [フィルター] グループまでスクロールします。[ビューをフィルター:] のラベルの下に現在のフィルターのプレビューが表示されます。まだ何も定義されていない場合は [フィルターが適用されていません] と表示されます。
3. [フィルターの編集] を選択します。Query Builder が大きなサイド パネルで開きます。
4. クエリを組み立て、[保存] を選択して適用するか、[キャンセル] を選択して変更を破棄します。Web パーツは新しいフィルターで直ちに再描画されます。

Query Builder は、[データ ソース] グループでサイトとリストまたはライブラリを選択した後にのみ使用できます。フィールドの一覧とその種類は、選択したリストから取得されるためです。

条件とグループ

クエリは 2 種類の構成要素で組み立てます。

• 条件は 1 つの比較です: フィールド — 演算子 — 値。たとえば Amount — より大きい — 5000 のようになります。値を必要としない演算子もあります (データを含む、現在のユーザーである、今日)。
• グループは条件と他のグループを含み、1 つの論理演算子で結合します。AND (すべてのメンバーが真であること) または OR (少なくとも 1 つのメンバーが真であること) です。グループの左端にあるトグルで切り替えます。

パネルには常に 1 つのルート グループがあり、これは削除できません。どのグループでも、[追加] ボタンから 2 つのコマンドを選択できます。

• [条件] — 現在のグループに空の行を追加します。
• [グループ] — 入れ子のグループ (既定では AND) を追加します。同じ方法で条件を入力します。

グループは最大 10 レベルまで入れ子にできます。各行と各入れ子グループの右側には削除アイコンがあります。グループを削除すると、その中のすべてが削除されます。

図のクエリは次のように読めます: タイトルが空ではなく「C」で始まる かつ (自分が作成した、または自分が更新した) かつ (過去 1 年以内に作成された、または過去 1 年以内に更新された) かつ (添付ファイルがある、または Customer が入力されていて Amount が 5,000 より大きい)。

列の種類ごとの演算子

行の演算子の一覧は、選択したフィールドの種類によって決まります。次の表は、サポートされる列の種類ごとに Query Builder が提供する演算子を示します。

データを含むとデータを含まないは、CAML の IsNotNull と IsNull と同じように、列に何らかの値があるかどうかを判定します。

値のエディターも列の種類に従います。日付には日付の選択 (次の範囲内では 2 つの日付の選択)、数値と通貨には数値フィールド、ユーザーまたはグループにはユーザー選択、管理されたメタデータには用語の選択、はい/いいえと添付ファイルには はい / いいえ の一覧、承認の状態には状態の一覧、テキスト・選択肢・参照の列にはテキスト ボックスが表示されます。

静的条件と動的条件

静的条件は、入力した固定の値 (日付、数値、テキスト、ユーザー) と列を比較します。値はそのままクエリに書き込まれます。次の範囲内は両端の日付を含み、暦日単位で判定されます。2 つの日付のうち 1 つだけを設定した場合、条件は片側のみの 以降 または 以前 になります。

動的条件は、クエリが実行される時点で SharePoint によって解決されます。そのため、同じページでもユーザーや日付によって表示されるアイテムが変わります。

過去Xと次のXの数値は、行の値フィールドに入力します。過去Xか月と過去X年はクエリ生成時に開始日に変換されるため、Modified — 過去X年 — 1 と設定したページは、誰もフィルターを編集しなくても常に直近 12 か月を対象とします。

定義済みフィルターとユーザー フィルターの組み合わせ

ユーザーがフィルター ウィンドウや列見出しでフィルターを適用しても、Web パーツは定義済みフィルターを置き換えません。定義済みフィルターとユーザー フィルターを AND で結合した新しいクエリを組み立てます。

<Where>
  <And>
    <!-- Query Builder の定義済みフィルター -->
    <!-- ユーザーがフィルター ウィンドウで選択した条件 -->
  </And>
</Where>

知っておくべき結果:

• ユーザーは結果を絞り込むことはできますが、定義済みフィルターの範囲を超えて広げることはできません。Created By — 現在のユーザーであるでフィルターされたページは、ユーザーがウィンドウで何を選択しても他の人のアイテムを表示しません。
• 並べ替え、グループ化、集計、Excel へのエクスポートはすべて、組み合わせた結果に対して動作します。
• 保存済みフィルターとフィルター リンク (KB10253. List Filter Online でフィルターを保存し、フィルター済みビューへのリンクを共有する を参照) には、クエリのユーザー部分だけが保存されます。定義済みフィルターはページ構成の一部であり、ページと共に移動します。

ツリーから CAML へ

SharePoint リストのクエリ言語である CAML では、<And> と <Or> の中に置ける被演算子はちょうど 2 つです。そのため、3 つ以上のメンバーを持つグループは 1 つの要素としては書けず、入れ子になったペアの連鎖に折りたたむ必要があります。Query Builder はこの折りたたみに加えて、種類ごとの細部 — 各値の Type 属性、参照列の LookupId、日付比較の IncludeTimeValue — も処理します。

上の図のクエリは約 70 行の <Where> 句を生成します。比較を省略した骨格は次のとおりです。

<Where>
  <And>
    <Or>  <!-- 自分が作成 OR 自分が更新 -->
      <Eq><FieldRef Name="Author" /><Value Type="Integer"><UserID /></Value></Eq>
      <Eq><FieldRef Name="Editor" /><Value Type="Integer"><UserID /></Value></Eq>
    </Or>
    <And>
      <Or>  <!-- 過去 1 年以内に作成 OR 過去 1 年以内に更新 -->
        <And> <Geq Created 2025-10-21 /> <Leq Created <Today /> /> </And>
        <And> <Geq Modified 2025-10-21 /> <Leq Modified <Today /> /> </And>
      </Or>
      <And>
        <Or>  <!-- (Customer が入力済み AND Amount > 5000) OR 添付ファイルあり -->
          <And> <IsNotNull Customer /> <Gt Amount 5000 /> </And>
          <Eq Attachments 1 />
        </Or>
        <And> <IsNotNull Title /> <BeginsWith Title "C" /> </And>
      </And>
    </And>
  </And>
</Where>

過去X年の各行は 2 つの日付比較の <And> に、各 OR グループは <Or> 要素に、ルート AND グループの 4 つのメンバーは 3 つの入れ子の <And> 要素になりました。

生成されたクエリの表示

Web パーツが送信する正確な CAML (定義済みフィルター、現在のユーザー フィルター、ビュー フィールド、行数の上限、グループ化を含む) を確認するには、次の手順を実行します。

1. プロパティ ウィンドウで [開発者ツール] を展開し、[開発者モードを有効にする] をオンにします。
2. ページを保存します。Web パーツのコマンド バーの右端に開発者ツールのメニューが表示されます。
3. [CAMLクエリ] を選択します。クエリがダイアログに表示され、コピーできます。

大きなリストでの定義済みフィルター

5,000 アイテムを超えるリストでは、結果を絞り込む最初の条件がインデックス付きの列を使用している場合にのみ、SharePoint はクエリを実行します。定義済みフィルターは最初に実行されるものなので、ページがそもそも開くかどうかを左右します。

• ルート グループはインデックス付き列の条件から始めてください (Created、Modified、Author、Editor、ID は既定でインデックス付きです。他の列はリストの設定でインデックスを作成できます)。
• ルートでは AND を優先してください。インデックスのない 2 つの列の間の OR は、どのインデックスも利用できません。
• 日付列にインデックスがある場合、動的な日付条件 (過去Xか月、今日) は最初の条件として適しています。

詳細、フィルター構成ツールのインデックス警告、およびワンクリックでのインデックス作成については、KB10257. 大きなリストのフィルター処理: インデックス付き列と 5,000 アイテムのしきい値 を参照してください。

制限事項

• Query Builder は、データ ソースで選択した 1 つのリストまたはライブラリの列を対象とします。他のリストの列に対する条件は設定できません。
• 参照列と選択肢列の値は、入力したテキストで照合されます。Query Builder にはこれらの値の選択ツールはありません。
• 条件を含まない入れ子グループは、クエリ生成時に無視されます。
• 入れ子の最大深度は 10 レベルです。実際にはほぼすべてのシナリオが 2〜3 レベルで対応でき、それより深いツリーはプレビューで読みにくくなります。
• 定義済みフィルターはユーザーには表示されません。一部のアイテムが表示されない理由をユーザーに知らせる必要がある場合は、Web パーツのタイトルまたはページ上にその旨を記載してください。

関連記事