<commit_before>[[templating-role-query]]
==== Templating a role query

When you create a role, you can specify a query that defines the 
<<document-level-security,document level security permissions>>. You can 
optionally use Mustache templates in the role query to insert the username of the
current authenticated user into the role. Like other places in {es} that support
templating or scripting, you can specify inline, stored, or file-based templates
and define custom parameters. You access the details for the current
authenticated user through the `_user` parameter.

For example, the following role query uses a template to insert the username
of the current authenticated user:

[source,console]
--------------------------------------------------
POST /_security/role/example1
{
  "indices" : [
    {
      "names" : [ "my-index-000001" ],
      "privileges" : [ "read" ],
      "query" : {
        "template" : {
          "source" : {
            "term" : { "acl.username" : "{{_user.username}}" }
          }
        }
      }
    }
  ]
}
--------------------------------------------------

You can access the following information through the `_user` variable:

[options="header"]
|======
| Property              | Description
| `_user.username`      | The username of the current authenticated user.
| `_user.full_name`     | If specified, the full name of the current authenticated user.
| `_user.email`         | If specified, the email of the current authenticated user.
| `_user.roles`         | If associated, a list of the role names of the current authenticated user.
| `_user.metadata`      | If specified, a hash holding custom metadata of the current authenticated user.
|======

You can also access custom user metadata. For example, if you maintain a
`group_id` in your user metadata, you can apply document level security
based on the `group.id` field in your documents:

[source,console]
--------------------------------------------------
POST /_security/role/example2
{
  "indices" : [
    {
      "names" : [ "my-index-000001" ],
      "privileges" : [ "read" ],
      "query" : {
        "template" : {
          "source" : {
            "term" : { "group.id" : "{{_user.metadata.group_id}}" }
          }
        }
      }
    }
  ]
}
--------------------------------------------------

If your metadata field contains an object or array, you can access it using the
`{{#toJson}}parameter{{/toJson}}` function.

[source,console]
----
POST /_security/role/example3
{
  "indices" : [
    {
      "names" : [ "my-index-000001" ],
      "privileges" : [ "read" ],
      "query" : {
        "template" : {
          "source" : {
            "terms" : { "group.statuses" : "{{#toJson}}_user.metadata.statuses{{/toJson}}" }
          }
        }
      }
    }
  ]
}
----<commit_msg>[DOCS] Fix role template snippet (#63774)<commit_after>[[templating-role-query]]
==== Templating a role query

When you create a role, you can specify a query that defines the 
<<document-level-security,document level security permissions>>. You can 
optionally use Mustache templates in the role query to insert the username of the
current authenticated user into the role. Like other places in {es} that support
templating or scripting, you can specify inline, stored, or file-based templates
and define custom parameters. You access the details for the current
authenticated user through the `_user` parameter.

For example, the following role query uses a template to insert the username
of the current authenticated user:

[source,console]
--------------------------------------------------
POST /_security/role/example1
{
  "indices" : [
    {
      "names" : [ "my-index-000001" ],
      "privileges" : [ "read" ],
      "query" : {
        "template" : {
          "source" : {
            "term" : { "acl.username" : "{{_user.username}}" }
          }
        }
      }
    }
  ]
}
--------------------------------------------------

You can access the following information through the `_user` variable:

[options="header"]
|======
| Property              | Description
| `_user.username`      | The username of the current authenticated user.
| `_user.full_name`     | If specified, the full name of the current authenticated user.
| `_user.email`         | If specified, the email of the current authenticated user.
| `_user.roles`         | If associated, a list of the role names of the current authenticated user.
| `_user.metadata`      | If specified, a hash holding custom metadata of the current authenticated user.
|======

You can also access custom user metadata. For example, if you maintain a
`group_id` in your user metadata, you can apply document level security
based on the `group.id` field in your documents:

[source,console]
--------------------------------------------------
POST /_security/role/example2
{
  "indices" : [
    {
      "names" : [ "my-index-000001" ],
      "privileges" : [ "read" ],
      "query" : {
        "template" : {
          "source" : {
            "term" : { "group.id" : "{{_user.metadata.group_id}}" }
          }
        }
      }
    }
  ]
}
--------------------------------------------------

If your metadata field contains an object or array, you can access it using the
`{{#toJson}}parameter{{/toJson}}` function.

[source,console]
----
POST /_security/role/example3
{
  "indices" : [
    {
      "names" : [ "my-index-000001" ],
      "privileges" : [ "read" ],
      "query" : {
        "template" : {
          "source" : "{ \"terms\": { \"group.statuses\": {{#toJson}}_user.metadata.statuses{{/toJson}} }}"
        }
      }
    }
  ]
}
----
{'fraction_non_alphanumeric': 0.18804483188044832, 'fraction_numerical': 0.008361501512186443, 'mean_word_length': 2.0941111722619703, 'pattern_counts': {'":': 2, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6959628', 'n_tokens_mistral': 1613, 'n_tokens_neox': 1553, 'n_words': 519}