collections.Where

collections.Where COLLECTION KEY [OPERATOR] VALUE

any

where

where 関数は指定されたコレクションに対して、比較条件に合致しない要素を取り除いたコレクションを返します。比較条件は KEY、OPERATOR、VALUE の引数により構成されます。

collections.Where COLLECTION KEY [OPERATOR] VALUE
                             --------------------
                                 比 較 条 件

OPERATOR 引数が指定されなかった場合は、一致するかどうかが条件となります。 たとえば以下です。

{{ $pages := where .Site.RegularPages "Section" "books" }}
{{ $books := where .Site.Data.books "genres" "suspense" }}

引数

where 関数は 3 つ、または 4 つの引数をとります。 OPERATOR 引数は任意です。

COLLECTION

(any) A page collection or a slice of maps.

KEY

(string) The key of the page or map value to compare with VALUE. With page collections, commonly used comparison keys are Section, Type, and Params. To compare with a member of the page Params map, chain the subkey as shown below:

{{ $result := where .Site.RegularPages "Params.foo" "bar" }}

OPERATOR

(string) 論理比較オペレーター.

VALUE

(any) The value with which to compare. The values to compare must have comparable data types. For example:

When one or both of the values to compare is a slice, use the in, not in, or intersect operators as described below.

オペレーター

以下のいずれかの論理オペレーターを利用します。

=, ==, eq

(bool) Reports whether the given field value is equal to VALUE.

!=, <>, ne

(bool) Reports whether the given field value is not equal to VALUE.

>=, ge

(bool) Reports whether the given field value is greater than or equal to VALUE.

>, gt

true Reports whether the given field value is greater than VALUE.

<=, le

(bool) Reports whether the given field value is less than or equal to VALUE.

<, lt

(bool) Reports whether the given field value is less than VALUE.

in

(bool) Reports whether the given field value is a member of VALUE. Compare string to slice, or string to string. See details.

not in

(bool) Reports whether the given field value is not a member of VALUE. Compare string to slice, or string to string. See details.

intersect

(bool) Reports whether the given field value (a slice) contains one or more elements in common with VALUE. See details.

like v0.116.0 の新機能

(bool) Reports whether the given field value matches the regular expression specified in VALUE. Use the like operator to compare string values. The like operator returns false when comparing other data types to the regular expression.

文字列比較

Compare the value of the given field to a string:

{{ $pages := where .Site.RegularPages "Section" "eq" "books" }}
{{ $pages := where .Site.RegularPages "Section" "ne" "books" }}

数値比較

Compare the value of the given field to an int or float:

{{ $books := where site.RegularPages "Section" "eq" "books" }}

{{ $pages := where $books "Params.price" "eq" 42 }}
{{ $pages := where $books "Params.price" "ne" 42.67 }}
{{ $pages := where $books "Params.price" "ge" 42 }}
{{ $pages := where $books "Params.price" "gt" 42.67 }}
{{ $pages := where $books "Params.price" "le" 42 }}
{{ $pages := where $books "Params.price" "lt" 42.67 }}

ブール値比較

Compare the value of the given field to a bool:

{{ $books := where site.RegularPages "Section" "eq" "books" }}

{{ $pages := where $books "Params.fiction" "eq" true }}
{{ $pages := where $books "Params.fiction" "eq" false }}
{{ $pages := where $books "Params.fiction" "ne" true }}
{{ $pages := where $books "Params.fiction" "ne" false }}

メンバー比較

Compare a scalar to a slice.

For example, to return a collection of pages where the color page parameter is either “red” or “yellow”:

{{ $fruit := where site.RegularPages "Section" "eq" "fruit" }}

{{ $colors := slice "red" "yellow" }}
{{ $pages := where $fruit "Params.color" "in" $colors }}

To return a collection of pages where the “color” page parameter is neither “red” nor “yellow”:

{{ $fruit := where site.RegularPages "Section" "eq" "fruit" }}

{{ $colors := slice "red" "yellow" }}
{{ $pages := where $fruit "Params.color" "not in" $colors }}

Intersection comparison

Compare a slice to a slice, returning collection elements with common values. This is frequently used when comparing taxonomy terms.

For example, to return a collection of pages where any of the terms in the “genres” taxonomy are “suspense” or “romance”:

{{ $books := where site.RegularPages "Section" "eq" "books" }}

{{ $genres := slice "suspense" "romance" }}
{{ $pages := where $books "Params.genres" "intersect" $genres }}

正規表現比較

To return a collection of pages where the “author” page parameter begins with either “victor” or “Victor”:

{{ $pages := where .Site.RegularPages "Params.author" "like" `(?i)^victor` }}

正規表現を指定する際には、“解釈される” (interpreted) 文字列リテラル (ダブルクォートで囲む) ではなく、そのままの文字列リテラル (バッククォートで囲む) を用いることで、文法を簡易なものにしてください。 “解釈される” 文字列リテラルを用いる場合、バックスラッシュそのものはエスケープする必要があります。

Go 言語の正規表現パッケージでは RE2 文法 を実装しています。 RE2 文法とは、おおざっぱに言えば PCRE が許容する文法のサブセットであり、さまざまな 注意事項 があります。 なお RE2 のエスケープシーケンス \C はサポートされません。

Date comparison

Predefined dates

There are four predefined front matter dates: date, publishDate, lastmod, and expiryDate. Regardless of the front matter data format (TOML, YAML, or JSON) these are time.Time values, allowing precise comparisons.

For example, to return a collection of pages that were created before the current year:

{{ $startOfYear := time.AsTime (printf "%d-01-01" now.Year) }}
{{ $pages := where .Site.RegularPages "Date" "lt" $startOfYear }}

Custom dates

With custom front matter dates, the comparison depends on the front matter data format (TOML, YAML, or JSON).

With TOML, date values are first-class citizens. TOML has a date data type while JSON and YAML do not. If you quote a TOML date, it is a string. If you do not quote a TOML date value, it is time.Time value, enabling precise comparisons.

In the TOML example below, note that the event date is not quoted.

+++
title = '2024 User Conference"
eventDate = 2024-04-01
+++

To return a collection of future events:

{{ $events := where .Site.RegularPages "Type" "events" }}
{{ $futureEvents := where $events "Params.eventDate" "gt" now }}

When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with time.Time values. String comparisons may be possible if the custom date layout is consistent from one page to the next. To be safe, filter the pages by ranging through the collection:

{{ $events := where .Site.RegularPages "Type" "events" }}
{{ $futureEvents := slice }}
{{ range $events }}
  {{ if gt (time.AsTime .Params.eventDate) now }}
    {{ $futureEvents = $futureEvents | append . }}
  {{ end }}
{{ end }}

Nil comparison

To return a collection of pages where the “color” parameter is present in front matter, compare to nil:

{{ $pages := where .Site.RegularPages "Params.color" "ne" nil }}

To return a collection of pages where the “color” parameter is not present in front matter, compare to nil:

{{ $pages := where .Site.RegularPages "Params.color" "eq" nil }}

In both examples above, note that nil is not quoted.

Nested comparison

These are equivalent:

{{ $pages := where .Site.RegularPages "Type" "tutorials" }}
{{ $pages = where $pages "Params.level" "eq" "beginner" }}

{{ $pages := where (where .Site.RegularPages "Type" "tutorials") "Params.level" "eq" "beginner" }}

Portable section comparison

Useful for theme authors, avoid hardcoding section names by using the where function with the MainSections method on a Site object.

{{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }}

With this construct, a theme author can instruct users to specify their main sections in the site configuration:

params:
  mainSections:
  - blog
  - galleries

[params]
  mainSections = ['blog', 'galleries']

{
   "params": {
      "mainSections": [
         "blog",
         "galleries"
      ]
   }
}

If params.mainSections is not defined in the site configuration, the MainSections method returns a slice with one element—the top level section with the most pages.

Boolean/undefined comparison

Consider this site content:

content/
├── posts/
│   ├── _index.md
│   ├── post-1.md  <-- front matter: exclude = false
│   ├── post-2.md  <-- front matter: exclude = true
│   └── post-3.md  <-- front matter: exclude not defined
└── _index.md

The first two pages have an “exclude” field in front matter, but the last page does not. When testing for equality, the third page is excluded from the result. When testing for inequality, the third page is included in the result.

Equality test

This template:

<ul>
  {{ range where .Site.RegularPages "Params.exclude" "eq" false }}
    <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
  {{ end }}
</ul>

Is rendered to:

<ul>
  <li><a href="/posts/post-1/">Post 1</a></li>
</ul>

This template:

<ul>
  {{ range where .Site.RegularPages "Params.exclude" "eq" true }}
    <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
  {{ end }}
</ul>

Is rendered to:

<ul>
  <li><a href="/posts/post-2/">Post 2</a></li>
</ul>

Inequality test

This template:

<ul>
  {{ range where .Site.RegularPages "Params.exclude" "ne" false }}
    <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
  {{ end }}
</ul>

Is rendered to:

<ul>
  <li><a href="/posts/post-2/">Post 2</a></li>
  <li><a href="/posts/post-3/">Post 3</a></li>
</ul>

This template:

<ul>
  {{ range where .Site.RegularPages "Params.exclude" "ne" true }}
    <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
  {{ end }}
</ul>

Is rendered to:

<ul>
  <li><a href="/posts/post-1/">Post 1</a></li>
  <li><a href="/posts/post-3/">Post 3</a></li>
</ul>

To exclude a page with an undefined field from a boolean inequality test:

1. Create a collection using a boolean comparison
2. Create a collection using a nil comparison
3. Subtract the second collection from the first collection using the collections.Complement function.

This template:

{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" true }}
{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil  }}
<ul>
  {{ range $p1 | complement $p2 }}
    <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
  {{ end }}
</ul>

Is rendered to:

<ul>
  <li><a href="/posts/post-1/">Post 1</a></li>
</ul>

This template:

{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" false }}
{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil  }}
<ul>
  {{ range $p1 | complement $p2 }}
    <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
  {{ end }}
</ul>

Is rendered to:

<ul>
  <li><a href="/posts/post-1/">Post 2</a></li>
</ul>