1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
---
title: where
description: Filters an array to only the elements containing a matching value for a given field.
categories: [functions]
menu:
docs:
parent: functions
keywords: [filtering]
signature: ["where COLLECTION KEY [OPERATOR] MATCH"]
relatedfuncs: [intersect,first,after,last]
toc: true
---
`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][wherekeyword].
```go-html-template
{{ 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.
{{< code-toggle file="content/example.md" fm=true copy=false >}}
title: Example
series: golang
{{< /code-toggle >}}
```go-html-template
{{ 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 `=`.
```go-html-template
{{ 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 value
`in`
: `true` if a given field value is included in a matching value; a matching value must be an array or a slice
`not in`
: `true` if a given field value isn't included in a matching value; a matching value must be an array or a slice
`intersect`
: `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 the [`intersect` function][intersect].
`like`
: `true` if a given field value matches a regular expression. Use the `like` operator to compare `string` values. Returns `false` when comparing other data types to the regular expression.
## Use `where` with boolean values
When using booleans you should not put quotation marks.
```go-html-template
{{ range where .Pages "Draft" true }}
<p>{{ .Title }}</p>
{{ end }}
```
## Use `where` with `intersect`
```go-html-template
{{ 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:
{{< code file="where-intersect-variables.html" >}}
{{ $v1 := where .Site.Pages "Params.a" "v1" }}
{{ $v2 := where .Site.Pages "Params.b" "v2" }}
{{ $filtered := $v1 | intersect $v2 }}
{{ range $filtered }}
{{ end }}
{{< /code >}}
## Use `where` with `like`
This example matches pages where the "foo" parameter begins with "ab":
```go-html-template
{{ 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.
[string literal]: https://go.dev/ref/spec#String_literals
Go's regular expression package implements the [RE2 syntax]. Note that the RE2 `\C` escape sequence is not supported.
[RE2 syntax]: https://github.com/google/re2/wiki/Syntax/
{{% note %}}
The RE2 syntax is a subset of that accepted by [PCRE], roughly speaking, and with various [caveats].
[caveats]: https://swtch.com/~rsc/regexp/regexp3.html#caveats
[PCRE]: https://www.pcre.org/
{{% /note %}}
## Use `where` with `first`
Using `first` and `where` together can be very
powerful. Below snippet gets a list of posts only from [**main
sections**](#mainsections), sorts it using the [default
ordering](/templates/lists/) for lists (i.e., `weight => date`), and
then ranges through only the first 5 posts in that list:
{{< code file="first-and-where-together.html" >}}
{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections) }}
{{ .Content }}
{{ end }}
{{< /code >}}
## 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:
```go-html-template
{{ 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.
```go-html-template
{{ range where .Pages "Params.specialpost" "!=" nil }}
{{ .Content }}
{{ end }}
```
## Portable `where` filters -- `site.Params.mainSections` {#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"`.
```go-html-template
{{ $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:
{{< code-toggle file="hugo" >}}
[params]
mainSections = ["blog", "docs"]
{{< /code-toggle >}}
[intersect]: /functions/intersect/
[wherekeyword]: https://www.techonthenet.com/sql/where.php
|
