HUGO

  • News
  • Docs
  • Themes
  • Showcase
  • Community
  • GitHub
Star

What's on this Page

  • Use where with boolean values
  • Use where with intersect
  • Use where with like
  • Use where with first
  • Nest where clauses
  • Unset fields
  • Portable where filters – site.Params.mainSections
FUNCTIONS

where

Filters an array to only the elements containing a matching value for a given field.

Syntax

where COLLECTION KEY [OPERATOR] MATCH

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.

content/example.md
     
---
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 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.
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.

{{ 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:

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

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:

first-and-where-together.html
{{ 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:

hugo.
     
params:
  mainSections:
  - blog
  - docs
[params]
  mainSections = ['blog', 'docs']
{
   "params": {
      "mainSections": [
         "blog",
         "docs"
      ]
   }
}
  • About Hugo
    • Overview
    • What is Hugo
    • Hugo features
    • Static site generators
    • Hugo's security model
    • Hugo and the GDPR
    • License
  • Installation
    • Overview
    • macOS
    • Linux
    • Windows
    • BSD
  • Getting started
    • Overview
    • Quick start
    • Basic usage
    • Directory structure
    • Configuration
    • Configure markup
    • Glossary of terms
    • External learning resources
  • Hugo Modules
    • Overview
    • Configure Hugo modules
    • Use Hugo Modules
    • Theme components
  • Content management
    • Overview
    • Organization
    • Page bundles
    • Content formats
    • Diagrams
    • Front matter
    • Build options
    • Page resources
    • Image processing
    • Shortcodes
    • Related content
    • Sections
    • Content types
    • Archetypes
    • Taxonomies
    • Summaries
    • Links and cross references
    • URL management
    • Menus
    • Static files
    • Table of contents
    • Comments
    • Multilingual
    • Syntax highlighting
  • Templates
    • Overview
    • Templating
    • Template lookup order
    • Base templates and blocks
    • Single page templates
    • List templates
    • Homepage template
    • Section templates
    • Taxonomy templates
    • Pagination
    • Content view templates
    • Partial templates
    • Shortcode templates
    • Menu templates
    • Data templates
    • RSS templates
    • Sitemap templates
    • Local file templates
    • Internal templates
    • Render hooks
    • Custom output formats
    • 404 page
    • Robots.txt
    • Template debugging
  • Functions
    • Overview
    • .AddDate
    • .Format
    • .Get
    • .GetPage
    • .HasMenuCurrent
    • .IsMenuCurrent
    • .Param
    • .Render
    • .RenderString
    • .Scratch
    • .Store
    • .Unix
    • absLangURL
    • absURL
    • after
    • anchorize
    • append
    • apply
    • base64
    • chomp
    • complement
    • cond
    • countrunes
    • countwords
    • crypto.FNV32a
    • default
    • delimit
    • dict
    • duration
    • echoParam
    • emojify
    • eq
    • errorf and warnf
    • fileExists
    • findRE
    • findRESubmatch
    • first
    • float
    • ge
    • getenv
    • group
    • gt
    • highlight
    • hmac
    • htmlEscape
    • htmlUnescape
    • hugo
    • humanize
    • i18n
    • Image filters
    • in
    • index
    • int
    • intersect
    • isset
    • jsonify
    • lang
    • lang.Merge
    • last
    • le
    • len
    • lower
    • lt
    • markdownify
    • Math
    • md5
    • merge
    • ne
    • now
    • os.Stat
    • partialCached
    • path.Base
    • path.BaseName
    • path.Clean
    • path.Dir
    • path.Ext
    • path.Join
    • path.Split
    • plainify
    • pluralize
    • print
    • printf
    • println
    • querify
    • range
    • readDir
    • readFile
    • ref
    • reflect.IsMap
    • reflect.IsSlice
    • relLangURL
    • relref
    • relURL
    • replace
    • replaceRE
    • safeCSS
    • safeHTML
    • safeHTMLAttr
    • safeJS
    • safeURL
    • seq
    • sha
    • shuffle
    • singularize
    • site
    • slice
    • slicestr
    • sort
    • split
    • string
    • strings.Contains
    • strings.ContainsAny
    • strings.ContainsNonSpace
    • strings.Count
    • strings.FirstUpper
    • strings.HasPrefix
    • strings.HasSuffix
    • strings.Repeat
    • strings.RuneCount
    • strings.TrimLeft
    • strings.TrimPrefix
    • strings.TrimRight
    • strings.TrimSuffix
    • substr
    • symdiff
    • templates.Exists
    • time
    • time.Format
    • time.ParseDuration
    • title
    • transform.Remarshal
    • transform.Unmarshal
    • trim
    • truncate
    • union
    • uniq
    • upper
    • urlize
    • urlquery
    • urls.JoinPath
    • urls.Parse
    • where
    • with
  • Variables
    • Overview
    • Site variables
    • Page variables
    • Shortcode variables
    • Pages methods
    • Taxonomy variables
    • File variables
    • Menu variables
    • Git variables
    • Sitemap variables
  • Hugo Pipes
    • Overview
    • Introduction
    • Transpile Sass to CSS
    • PostCSS
    • PostProcess
    • JavaScript building
    • Babel
    • Asset minification
    • Concatenating assets
    • Fingerprinting and SRI hashing
    • Resource from string
    • Resource from template
  • CLI
  • Troubleshooting
    • Overview
    • Frequently asked questions
    • Build performance
  • Developer tools
    • Overview
    • Editor plugins
    • Frontends
    • Search
    • Migrations
    • Other projects
  • Hosting and deployment
    • Overview
    • Hugo Deploy
    • Deploy with Rclone
    • Deploy with Rsync
    • Host on 21YunBox
    • Host on AWS Amplify
    • Host on Azure Static Web Apps
    • Host on Cloudflare Pages
    • Host on Firebase
    • Host on GitHub Pages
    • Host on GitLab Pages
    • Host on KeyCDN
    • Host on Netlify
    • Host on Render
  • Contribute
    • Overview
    • Development
    • Documentation
    • Themes
  • Maintenance
Last updated: August 3, 2023: Use shared file to describe regex syntax (d415bae2)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • @GoHugoIO
  • @spf13
  • @bepsays

Netlify badge

 

Hugo Sponsors

 

The Hugo logos are copyright © Steve Francia 2013–2023.

The Hugo Gopher is based on an original work by Renée French.

  • News
  • Docs
  • Themes
  • Showcase
  • Community
  • GitHub
  • About Hugo
  • Installation
  • Getting started
  • Hugo Modules
  • Content management
  • Templates
  • Functions
  • Variables
  • Hugo Pipes
  • CLI
  • Troubleshooting
  • Developer tools
  • Hosting and deployment
  • Contribute
  • Maintenance