github.com/lyeb/hugo@v0.47.1/docs/content/en/functions/where.md (about)

     1  ---
     2  title: where
     3  # linktitle: where
     4  description: Filters an array to only the elements containing a matching value for a given field.
     5  godocref:
     6  date: 2017-02-01
     7  publishdate: 2017-02-01
     8  lastmod: 2017-02-01
     9  categories: [functions]
    10  menu:
    11    docs:
    12      parent: "functions"
    13  keywords: [filtering]
    14  signature: ["where COLLECTION KEY [OPERATOR] MATCH"]
    15  workson: [lists,taxonomies,terms,groups]
    16  hugoversion:
    17  relatedfuncs: [intersect,first,after,last]
    18  deprecated: false
    19  toc: true
    20  needsexample: true
    21  ---
    22  
    23  `where` filters an array to only the elements containing a matching value for a given field.
    24  
    25  ```go-html-template
    26  {{ range where .Pages "Section" "post" }}
    27    {{ .Content }}
    28  {{ end }}
    29  ```
    30  
    31  It can be used by dot-chaining the second argument to refer to a nested element of a value.
    32  
    33  ```
    34  +++
    35  series: golang
    36  +++
    37  ```
    38  
    39  ```go-html-template
    40  {{ range where .Site.Pages "Params.series" "golang" }}
    41     {{ .Content }}
    42  {{ end }}
    43  ```
    44  
    45  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 `=`.
    46  
    47  ```go-html-template
    48  {{ range where .Pages "Section" "!=" "post" }}
    49     {{ .Content }}
    50  {{ end }}
    51  ```
    52  
    53  The following logical operators are available with `where`:
    54  
    55  `=`, `==`, `eq`
    56  : `true` if a given field value equals a matching value
    57  
    58  `!=`, `<>`, `ne`
    59  : `true` if a given field value doesn't equal a matching value
    60  
    61  `>=`, `ge`
    62  : `true` if a given field value is greater than or equal to a matching value
    63  
    64  `>`, `gt`
    65  : `true` if a given field value is greater than a matching value
    66  
    67  `<=`, `le`
    68  : `true` if a given field value is lesser than or equal to a matching value
    69  
    70  `<`, `lt`
    71  : `true` if a given field value is lesser than a matching value
    72  
    73  `in`
    74  : `true` if a given field value is included in a matching value; a matching value must be an array or a slice
    75  
    76  `not in`
    77  : `true` if a given field value isn't included in a matching value; a matching value must be an array or a slice
    78  
    79  `intersect`
    80  : `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].
    81  
    82  ## Use `where` with `intersect`
    83  
    84  ```go-html-template
    85  {{ range where .Site.Pages ".Params.tags" "intersect" .Params.tags }}
    86    {{ if ne .Permalink $.Permalink }}
    87      {{ .Render "summary" }}
    88    {{ end }}
    89  {{ end }}
    90  ```
    91  
    92  You can also put the returned value of the `where` clauses into a variable:
    93  
    94  {{< code file="where-intersect-variables.html" >}}
    95  {{ $v1 := where .Site.Pages "Params.a" "v1" }}
    96  {{ $v2 := where .Site.Pages "Params.b" "v2" }}
    97  {{ $filtered := $v1 | intersect $v2 }}
    98  {{ range $filtered }}
    99  {{ end }}
   100  {{< /code >}}
   101  
   102  ## Use `where` with `first`
   103  
   104  The following grabs the first five content files in `post` using the [default ordering](/templates/lists/) for lists (i.e., `weight => date`):
   105  
   106  {{< code file="where-with-first.html" >}}
   107  {{ range first 5 (where .Pages "Section" "post") }}
   108     {{ .Content }}
   109  {{ end }}
   110  {{< /code >}}
   111  
   112  ## Nest `where` Clauses
   113  
   114  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:
   115  
   116  ```go-html-template
   117  {{ range where (where .Pages "Section" "blog" ) ".Params.featured" "!=" "true" }}
   118  ```
   119  
   120  ## Unset Fields
   121  
   122  Filtering only works for set fields. To check whether a field is set or exists, you can use the operand `nil`.
   123  
   124  This can be useful to filter a small amount of pages from a large pool. Instead of set field on all pages, you can set field on required pages only.
   125  
   126  Only the following operators are available for `nil`
   127  
   128  * `=`, `==`, `eq`: True if the given field is not set.
   129  * `!=`, `<>`, `ne`: True if the given field is set.
   130  
   131  ```go-html-template
   132  {{ range where .Pages ".Params.specialpost" "!=" nil }}
   133     {{ .Content }}
   134  {{ end }}
   135  ```
   136  
   137  ## Portable `where` filters
   138  
   139  This is especially important for themes, but to list the most relevant pages on the front page or similar, you can use `.Site.Params.mainSections` list.
   140  
   141  This will, by default, list pages from the _section with the most pages_.
   142  
   143  ```go-html-template
   144  {{ $pages := where .Site.RegularPages "Type" "in" .Site.Params.mainSections }}
   145  ```
   146  
   147  The user can override the default in `config.toml`:
   148  
   149  ```toml
   150  [params]
   151  mainSections = ["blog", "docs"]
   152  ```
   153  
   154  [intersect]: /functions/intersect/