collections.Where

Usage

The where function returns the given slice, removing elements that do not satisfy the comparison condition. The comparison condition is composed of the KEY, OPERATOR, and VALUE arguments:

collections.Where SLICE KEY [OPERATOR] VALUE
                        --------------------
                        comparison condition

Hugo will test for equality if you do not provide an OPERATOR argument. For example:

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

Arguments

The where function takes three or four arguments. The OPERATOR argument is optional.

SLICE

([]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" }}

Use the Params key to compare custom fields. To compare a reserved field, use the name of the corresponding Page method, such as Title.

Deprecated in v0.169.0

Comparing a reserved field with the Params key, such as Params.title, is deprecated. Use the name of the corresponding Page method instead, such as Title. Hugo does not log a deprecation warning in every case.

OPERATOR

(string) The logical comparison operator.

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.

Operators

Use any of the following logical operators:

=, ==, 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.

not in

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

intersect

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

like

(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.

Examples

The following examples demonstrate comparisons using various operators and data types. The examples perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps.

String comparison

Compare the value of the given field to a string:

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

Numeric comparison

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 }}

Boolean comparison

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 }}

Member comparison

Compare a scalar to a slice.

For example, to return a slice 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 slice 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 elements with common values. This is frequently used when comparing taxonomy terms.

For example, to return a slice 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 }}

Regular expression comparison

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

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

When specifying the regular expression, use a raw string literal (backticks) instead of an interpreted string literal (double quotes) to simplify the syntax. With an interpreted string literal you must escape backslashes.

Go’s regexp package implements the RE2 syntax. The RE2 syntax is a subset of that accepted by PCRE, roughly speaking, and with various caveats. Note that the RE2 \C escape sequence is not supported.

Date comparison

Compare predefined front matter dates, or custom dates that you specify as custom page parameters under the params key in front matter. The function compares time.Time values by the moment they represent, regardless of time zone.

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 slice 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 dates, the comparison depends on the front matter data format (TOML, YAML, or JSON) and on whether you quote the date.

TOML has a date data type, while JSON and YAML do not. If you do not quote a TOML date, the function compares it as a time.Time value. In the TOML example below, the event date is not quoted:

+++
title = '2024 User Conference'
[params]
eventDate = 2024-04-01
+++

To return a slice of future events:

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

Custom dates in JSON or YAML front matter, and quoted custom dates in TOML front matter, are strings. Comparing a string with a time.Time value matches no pages, regardless of the operator. To compare these dates, range over the pages and convert each date with the time.AsTime function:

{{ $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 slice 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 slice 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 their project configuration:

mainSections:
- blog
- galleries

mainSections = ['blog', 'galleries']

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

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

Boolean/undefined comparison

Consider this project structure:

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 slice using a boolean comparison
2. Create a slice using a nil comparison
3. Subtract the second slice from the first slice 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>