collections.Where
Syntax
collections.Where COLLECTION KEY [OPERATOR] MATCH ⟼ any
Alias
where
where
filters an array to only the elements containing a matching
value for a given field.
It works in a similar manner to the where
keyword in
SQL.
{{ range where .Pages "Section" "foo" }}
{{ .Content }}
{{ end }}
It can be used by dot-chaining the second argument to refer to a nested element of a value.
---
series: golang
title: Example
---
+++
series = 'golang'
title = 'Example'
+++
{
"series": "golang",
"title": "Example"
}
{{ range where .Site.Pages "Params.series" "golang" }}
{{ .Content }}
{{ end }}
It can also be used with the logical operators !=
, >=
, in
, etc. Without an operator, where
compares a given field with a matching value equivalent to =
.
{{ range where .Pages "Section" "!=" "foo" }}
{{ .Content }}
{{ end }}
The following logical operators are available with where
:
=
,==
,eq
true
if a given field value equals a matching value!=
,<>
,ne
true
if a given field value doesn’t equal a matching value>=
,ge
true
if a given field value is greater than or equal to a matching value>
,gt
true
if a given field value is greater than a matching value<=
,le
true
if a given field value is lesser than or equal to a matching value<
,lt
true
if a given field value is lesser than a matching valuein
true
if a given field value is included in a matching value; a matching value must be an array or a slicenot in
true
if a given field value isn’t included in a matching value; a matching value must be an array or a sliceintersect
true
if a given field value that is a slice/array of strings or integers contains elements in common with the matching value; it follows the same rules as theintersect
function.like
true
if a given field value matches a regular expression. Use thelike
operator to comparestring
values. Returnsfalse
when comparing other data types to the regular expression.
Use where
with boolean values
When using booleans you should not put quotation marks.
{{ range where .Pages "Draft" true }}
<p>{{ .Title }}</p>
{{ end }}
Use where
with intersect
{{ range where .Site.Pages "Params.tags" "intersect" .Params.tags }}
{{ if ne .Permalink $.Permalink }}
{{ .Render "summary" }}
{{ end }}
{{ end }}
You can also put the returned value of the where
clauses into a variable:
{{ $v1 := where .Site.Pages "Params.a" "v1" }}
{{ $v2 := where .Site.Pages "Params.b" "v2" }}
{{ $filtered := $v1 | intersect $v2 }}
{{ range $filtered }}
{{ end }}
Use where
with like
This example matches pages where the “foo” parameter begins with “ab”:
{{ range where site.RegularPages "Params.foo" "like" `^ab` }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
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 regular expression 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.
Use where
with first
Using first
and where
together can be very
powerful. Below snippet gets a list of posts only from main
sections, sorts it using the default
ordering for lists (i.e., weight => date
), and
then ranges through only the first 5 posts in that list:
{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections) }}
{{ .Content }}
{{ end }}
Nest where
clauses
You can also nest where
clauses to drill down on lists of content by more than one parameter. The following first grabs all pages in the “blog” section and then ranges through the result of the first where
clause and finds all pages that are not featured:
{{ range where (where .Pages "Section" "blog" ) "Params.featured" "!=" true }}
Unset fields
Filtering only works for set fields. To check whether a field is set or exists, you can use the operand nil
.
This can be useful to filter a small amount of pages from a large pool. Instead of setting a field on all pages, you can set that field on required pages only.
Only the following operators are available for nil
=
,==
,eq
: True if the given field is not set.!=
,<>
,ne
: True if the given field is set.
{{ range where .Pages "Params.specialpost" "!=" nil }}
{{ .Content }}
{{ end }}
Portable where
filters – site.Params.mainSections
This is especially important for themes.
To list the most relevant pages on the front page or similar, you
should use the site.Params.mainSections
list instead of comparing
section names to hard-coded values like "posts"
or "post"
.
{{ $pages := where site.RegularPages "Type" "in" site.Params.mainSections }}
If the user has not set this configuration parameter in their site configuration, it will default to the section with the most pages.
The user can override the default:
params:
mainSections:
- blog
- docs
[params]
mainSections = ['blog', 'docs']
{
"params": {
"mainSections": [
"blog",
"docs"
]
}
}