メインコンテンツへスキップ

15 · ディレクティブを組み合わせる(@filter、@sort、@top、@source、@join)

ディレクティブとは何で、何ではないのか​

ディレクティブ(@filter、@sort、@top、@source、@join)はデータブロック内に居座り、ブロックが反復する行集合を整えます。ソースセルの記述順とは関係なく、決まった順序で評価されます:

  1. @source <Name> ― ブロックがどのソースを反復するか決めます。
  2. @join <Source> on ... ― 主ソースの行を別ソースの行とペアリングします。
  3. @filter <condition> ― 条件が truthy な行だけを残します。
  4. @sort <column> [asc|desc] ― 行を並べ替えます。
  5. @top <N> ― フィルタリングと並べ替えが終わった後、先頭から N 個だけ残します。

作成のヒント: ディレクティブを実行順序通りに書いてください。スペックが強制するわけではありませんが、テンプレートがずっと読みやすくなります。

ディレクティブの組み合わせ​

よく使う形: 東京の高額更新上位 5 件。

{{ @filter [地域] = "東京" }}
{{ @filter [金額] > 1000 }}
{{ @sort [金額] desc }}
{{ @top 5 }}
{{ [取引先] }} | {{ [金額] }}

評価順序:

  1. 地域=東京でフィルタ。
  2. 金額>1000 でフィルタ(AND で結合)。
  3. 生き残った行を金額降順で並べ替え。
  4. 先頭 5 件。

複数 @filter は AND で結合される​

ADR-0029 に従って、1 ブロック内の複数 @filter は互いに AND で結ばれます。OR キーワードはありません。OR を表現するには次のいずれかを使ってください:

  • IN で 1 つのフィルタにまとめる: {{ @filter [地域] in __lists__[active_regions] }}
  • データブロックを 2 つに分ける(それぞれを自分の領域に置き、両方がレンダリングされながら自然に行集合が union されるようにする)。
  • 上流段階で事前処理する。

@source + @join の組み合わせ​

{{ @source 更新一覧 }}
{{ @join 顧客 on 更新一覧[customer_id] = 顧客[id] }}
{{ @filter 顧客[ランク] = "A" }}
{{ @sort 更新一覧[amount] desc }}
{{ @top 10 }}
{{ 更新一覧[customer_id] }}
{{ 顧客[name] }}
{{ 更新一覧[amount] }}

ステップ:

  1. 更新一覧を反復(@source が指定)。
  2. id で顧客と inner join。マッチしない行は除外。
  3. 顧客の tier が "A" な行だけ残す。
  4. 更新一覧.amount 降順で並べ替え。
  5. 上位 10 件。

@filter はどちらのソースの列も参照できます。列解釈はブラケットだけ使う場合はアクティブブロックのソースを使い、ジョイン側は明示的に Source[Column] 形式を使います。

禁止される組み合わせ​

ADR-0029 基準:

  • データブロックあたり @source は最大 1 つ。重複すると xl3/directive/invalid-syntax が発生します。
  • データブロックあたり @join も最大 1 つ。マルチジョインは対象外です。
  • self-join 禁止。アクティブソースが S のとき @join S on S[a] = S[b] を使うと xl3/join/bad-on-clause が発生します。

@sort の後の @top​

{{ @sort [金額] desc }}
{{ @top 10 }}

並べ替えなしの Top-N は意味がありません。@sort なしで @top を使うと、ソースに書かれた順序のまま先頭 N 個を切り出します ― 時々便利ですが、作成者が意図した結果である場合はめったにありません。

フィルタ後に行が空になる場合​

@filter がすべての行を落とすと、データブロックは 0 行に expand されます。テンプレート行のスタイルと書式は結果に残りますが、データ行そのものは生成されません。ブロック下のフッター行はそのまま見えます。

スペックポインタ​

  • ADR-0029 ― ディレクティブの組み合わせ + ソースエッジセマンティクス。
  • spec/language.md の「Filter」、「Sort」、「Top」、「Source」、「Join」。
  • @filter in __lists__[…] は Cookbook 05 を参照。
  • @source + @join の基本は Cookbook 07 を参照。
  • @sort + @top の基本は Cookbook 09 を参照。