---
type: api
title: Find roles with a query
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-security-query-role
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-security-query-role
products:
  - Elasticsearch
---

# Find roles with a query


Availability: 8.15+

## Paths

- `POST` (also `GET`) `/_security/_query/role`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#bearerauth)

## Description

Get roles in a paginated manner.
The role management APIs are generally the preferred way to manage roles, rather than using file-based role management.
The query roles API does not retrieve roles that are defined in roles files, nor built-in ones.
You can optionally filter the results with a query.
Also, the results can be paginated and sorted.

## Required authorization

* Cluster privileges: `read_security`

## Request Body

`application/json`

- `query` ({} RoleQueryContainer) — optional
  A query to filter which roles to return.
If the query parameter is missing, it is equivalent to a `match_all` query.
The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`,
`ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`.
You can query the following information associated with roles: `name`, `description`, `metadata`,
`applications.application`, `applications.privileges`, and `applications.resources`.
  - `bool` ({} BoolQuery) — optional
    matches roles matching boolean combinations of other queries.
    - `boost` (number · default: 1) — optional
      Floating point number used to decrease or increase the relevance scores of the query.
Boost values are relative to the default value of 1.0.
A boost value between 0 and 1.0 decreases the relevance score.
A value greater than 1.0 increases the relevance score.
    - `_name` (string) — optional
    - `filter` (union oneOf) — optional
      The clause (query) must appear in matching documents.
However, unlike `must`, the score of the query will be ignored.
      One of: [`QueryContainer[]`](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`QueryContainer`](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
      See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
    - `minimum_should_match` (number | string MinimumShouldMatch) — optional
      Specifies the number or percentage of `should` clauses returned documents must match.
    - `must` (union oneOf) — optional
      The clause (query) must appear in matching documents and will contribute to the score.
      One of: [`QueryContainer[]`](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`QueryContainer`](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
      See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
    - `must_not` (union oneOf) — optional
      The clause (query) must not appear in the matching documents.
Because scoring is ignored, a score of `0` is returned for all documents.
      One of: [`QueryContainer[]`](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`QueryContainer`](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
      See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
    - `should` (union oneOf) — optional
      The clause (query) should appear in the matching document.
      One of: [`QueryContainer[]`](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`QueryContainer`](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
      See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
  - `exists` ({} ExistsQuery) — optional
    Returns roles that contain an indexed value for a field.
    - `boost` (number · default: 1) — optional
      Floating point number used to decrease or increase the relevance scores of the query.
Boost values are relative to the default value of 1.0.
A boost value between 0 and 1.0 decreases the relevance score.
A value greater than 1.0 increases the relevance score.
    - `_name` (string) — optional
    - `field` (string Field) — required
      Name of the field you wish to search.
  - `ids` ({} IdsQuery) — optional
    Returns roles based on their IDs.
This query uses role document IDs stored in the `_id` field.
    - `boost` (number · default: 1) — optional
      Floating point number used to decrease or increase the relevance scores of the query.
Boost values are relative to the default value of 1.0.
A boost value between 0 and 1.0 decreases the relevance score.
A value greater than 1.0 increases the relevance score.
    - `_name` (string) — optional
    - `values` (string Ids) — optional
      An array of document IDs.
  - `match` (map string to MatchQuery) — optional
    Returns roles that match a provided text, number, date or boolean value.
The provided text is analyzed before matching.
    Map values ({} MatchQuery)
    - `boost` (number · default: 1) — optional
      Floating point number used to decrease or increase the relevance scores of the query.
Boost values are relative to the default value of 1.0.
A boost value between 0 and 1.0 decreases the relevance score.
A value greater than 1.0 increases the relevance score.
    - `_name` (string) — optional
    - `analyzer` (string) — optional
      Analyzer used to convert the text in the query value into tokens.
    - `auto_generate_synonyms_phrase_query` (boolean · default: true) — optional
      If `true`, match phrase queries are automatically created for multi-term synonyms.
    - `cutoff_frequency` (number) — optional — deprecated
    - `fuzziness` (number | string Fuzziness) — optional
      Maximum edit distance allowed for matching.
    - `fuzzy_rewrite` (string) — optional
      Method used to rewrite the query.
    - `fuzzy_transpositions` (boolean · default: true) — optional
      If `true`, edits for fuzzy matching include transpositions of two adjacent characters (for example, `ab` to `ba`).
    - `lenient` (boolean · default: false) — optional
      If `true`, format-based errors, such as providing a text query value for a numeric field, are ignored.
    - `max_expansions` (number · default: 50) — optional
      Maximum number of terms to which the query will expand.
    - `minimum_should_match` (number | string MinimumShouldMatch) — optional
      Minimum number of clauses that must match for a document to be returned.
    - `operator` (enum Operator · default: 'or') — optional
      Boolean logic used to interpret text in the query value.
      Values: `and`, `AND`, `or`, `OR`
    - `prefix_length` (number · default: 0) — optional
      Number of beginning characters left unchanged for fuzzy matching.
    - `query` (boolean | number | string) — required
      Text, number, boolean value or date you wish to find in the provided field.
    - `zero_terms_query` (enum ZeroTermsQuery · default: 'none') — optional
      Indicates whether no documents are returned if the `analyzer` removes all tokens, such as when using a `stop` filter.

Supported values include:
  - `all`: Returns all documents, similar to a `match_all` query.
  - `none`: No documents are returned if the `analyzer` removes all tokens.
      Values: `all`, `none`
  - `match_all` ({} MatchAllQuery) — optional
    Matches all roles, giving them all a `_score` of 1.0.
    - `boost` (number · default: 1) — optional
      Floating point number used to decrease or increase the relevance scores of the query.
Boost values are relative to the default value of 1.0.
A boost value between 0 and 1.0 decreases the relevance score.
A value greater than 1.0 increases the relevance score.
    - `_name` (string) — optional
  - `prefix` (map string to PrefixQuery) — optional
    Returns roles that contain a specific prefix in a provided field.
    Map values ({} PrefixQuery)
    - `boost` (number · default: 1) — optional
      Floating point number used to decrease or increase the relevance scores of the query.
Boost values are relative to the default value of 1.0.
A boost value between 0 and 1.0 decreases the relevance score.
A value greater than 1.0 increases the relevance score.
    - `_name` (string) — optional
    - `rewrite` (string) — optional
      Method used to rewrite the query.
    - `value` (string) — required
      Beginning characters of terms you wish to find in the provided field.
    - `case_insensitive` (boolean · default: false) — optional
      Allows case insensitive matching of the value with the indexed field values when set to `true`.
Default is `false` which means the case sensitivity of matching depends on the underlying field’s mapping.
  - `range` (map string to RangeQuery) — optional
    Returns roles that contain terms within a provided range.
  - `simple_query_string` ({} SimpleQueryStringQuery) — optional
    Returns roles based on a provided query string, using a parser with a limited but fault-tolerant syntax.
    - `boost` (number · default: 1) — optional
      Floating point number used to decrease or increase the relevance scores of the query.
Boost values are relative to the default value of 1.0.
A boost value between 0 and 1.0 decreases the relevance score.
A value greater than 1.0 increases the relevance score.
    - `_name` (string) — optional
    - `analyzer` (string) — optional
      Analyzer used to convert text in the query string into tokens.
    - `analyze_wildcard` (boolean · default: false) — optional
      If `true`, the query attempts to analyze wildcard terms in the query string.
    - `auto_generate_synonyms_phrase_query` (boolean · default: true) — optional
      If `true`, the parser creates a match_phrase query for each multi-position token.
    - `default_operator` (enum Operator · default: 'or') — optional
      Default boolean logic used to interpret text in the query string if no operators are specified.
      Values: `and`, `AND`, `or`, `OR`
    - `fields` ([] string Field) — optional
      Array of fields you wish to search.
Accepts wildcard expressions.
You also can boost relevance scores for matches to particular fields using a caret (`^`) notation.
Defaults to the `index.query.default_field index` setting, which has a default value of `*`.
    - `flags` (SimpleQueryStringFlags · default: ALL) — optional
      List of enabled operators for the simple query string syntax.
      Values: `NONE`, `AND`, `NOT`, `OR`, `PREFIX`, `PHRASE`, `PRECEDENCE`, `ESCAPE`, `WHITESPACE`, `FUZZY`, `NEAR`, `SLOP`, `ALL`
    - `fuzzy_max_expansions` (number · default: 50) — optional
      Maximum number of terms to which the query expands for fuzzy matching.
    - `fuzzy_prefix_length` (number · default: 0) — optional
      Number of beginning characters left unchanged for fuzzy matching.
    - `fuzzy_transpositions` (boolean) — optional
      If `true`, edits for fuzzy matching include transpositions of two adjacent characters (for example, `ab` to `ba`).
    - `lenient` (boolean · default: false) — optional
      If `true`, format-based errors, such as providing a text value for a numeric field, are ignored.
    - `minimum_should_match` (number | string MinimumShouldMatch) — optional
      Minimum number of clauses that must match for a document to be returned.
    - `query` (string) — required
      Query string in the simple query string syntax you wish to parse and use for search.
    - `quote_field_suffix` (string) — optional
      Suffix appended to quoted text in the query string.
  - `term` (map string to TermQuery) — optional
    Returns roles that contain an exact term in a provided field.
To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.
    Map values ({} TermQuery)
    - `boost` (number · default: 1) — optional
      Floating point number used to decrease or increase the relevance scores of the query.
Boost values are relative to the default value of 1.0.
A boost value between 0 and 1.0 decreases the relevance score.
A value greater than 1.0 increases the relevance score.
    - `_name` (string) — optional
    - `value` (FieldValue) — required
      Term you wish to find in the provided field.
    - `case_insensitive` (boolean · default: false) — optional
      Allows case insensitive matching of the value with the indexed field values when set to `true`.
When `false`, the case sensitivity of matching depends on the underlying field’s mapping.
  - `terms` ({} TermsQuery) — optional
    Returns roles that contain one or more exact terms in a provided field.
To return a document, one or more terms must exactly match a field value, including whitespace and capitalization.
    - `boost` (number · default: 1) — optional
      Floating point number used to decrease or increase the relevance scores of the query.
Boost values are relative to the default value of 1.0.
A boost value between 0 and 1.0 decreases the relevance score.
A value greater than 1.0 increases the relevance score.
    - `_name` (string) — optional
  - `wildcard` (map string to WildcardQuery) — optional
    Returns roles that contain terms matching a wildcard pattern.
    Map values ({} WildcardQuery)
    - `boost` (number · default: 1) — optional
      Floating point number used to decrease or increase the relevance scores of the query.
Boost values are relative to the default value of 1.0.
A boost value between 0 and 1.0 decreases the relevance score.
A value greater than 1.0 increases the relevance score.
    - `_name` (string) — optional
    - `case_insensitive` (boolean) — optional
      Allows case insensitive matching of the pattern with the indexed field values when set to true. Default is false which means the case sensitivity of matching depends on the underlying field’s mapping.
    - `rewrite` (string) — optional
      Method used to rewrite the query.
    - `value` (string) — optional
      Wildcard pattern for terms you wish to find in the provided field. Required, when wildcard is not set.
    - `wildcard` (string) — optional
      Wildcard pattern for terms you wish to find in the provided field. Required, when value is not set.
- `from` (number · default: 0) — optional
  The starting document offset.
It must not be negative.
By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.
To page through more hits, use the `search_after` parameter.
- `sort` (Sort) — optional
  The sort definition.
You can sort on `name`, `description`, `metadata`, `applications.application`, `applications.privileges`,
and `applications.resources`.
In addition, sort can also be applied to the `_doc` field to sort by index order.
- `size` (number · default: 10) — optional
  The number of hits to return.
It must not be negative.
By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.
To page through more hits, use the `search_after` parameter.
- `search_after` (SortResults) — optional
  The search after definition.

## Response

`application/json`

- `total` (number)
  The total number of roles found.
- `count` (number)
  The number of roles returned in the response.
- `roles` ([] QueryRole)
  A list of roles that match the query.
The returned role format is an extension of the role definition format.
It adds the `transient_metadata.enabled` and the `_sort` fields.
`transient_metadata.enabled` is set to `false` in case the role is automatically disabled, for example when the role grants privileges that are not allowed by the installed license.
`_sort` is present when the search query sorts on some field.
It contains the array of values that have been used for sorting.
  - `cluster` ([] union ClusterPrivilege)
    A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.
    Values: `all`, `cancel_task`, `clone_api_key`, `create_snapshot`, `cross_cluster_replication`, `cross_cluster_search`, `delegate_pki`, `grant_api_key`, `manage`, `manage_api_key`, `manage_autoscaling`, `manage_behavioral_analytics`, `manage_ccr`, `manage_data_frame_transforms`, `manage_data_stream_global_retention`, `manage_enrich`, `manage_esql`, `manage_ilm`, `manage_index_templates`, `manage_inference`, `manage_ingest_pipelines`, `manage_logstash_pipelines`, `manage_ml`, `manage_oidc`, `manage_own_api_key`, `manage_pipeline`, `manage_reindex`, `manage_rollup`, `manage_saml`, `manage_search_application`, `manage_search_query_rules`, `manage_search_synonyms`, `manage_security`, `manage_service_account`, `manage_slm`, `manage_token`, `manage_transform`, `manage_user_profile`, `manage_watcher`, `monitor`, `monitor_data_frame_transforms`, `monitor_data_stream_global_retention`, `monitor_enrich`, `monitor_esql`, `monitor_inference`, `monitor_ml`, `monitor_reindex`, `monitor_rollup`, `monitor_snapshot`, `monitor_stats`, `monitor_text_structure`, `monitor_transform`, `monitor_watcher`, `none`, `post_behavioral_analytics_event`, `read_ccr`, `read_fleet_secrets`, `read_ilm`, `read_pipeline`, `read_security`, `read_slm`, `transport_client`, `write_connector_secrets`, `write_fleet_secrets`
  - `indices` ([] IndicesPrivileges)
    A list of indices permissions entries.
    - `field_security` ({} FieldSecurity)
      The document fields that the owners of the role have read access to.
      - `except` (string Fields)
      - `grant` (string Fields)
    - `names` (union IndexName | [] IndexName)
      A list of indices (or index name patterns) to which the permissions in this entry apply.
    - `privileges` ([] union IndexPrivilege)
      The index level privileges that owners of the role have on the specified indices.
      Values: `all`, `auto_configure`, `create`, `create_doc`, `create_index`, `create_view`, `cross_cluster_replication`, `cross_cluster_replication_internal`, `delete`, `delete_index`, `delete_view`, `index`, `maintenance`, `manage`, `manage_data_stream_lifecycle`, `manage_follow_index`, `manage_ilm`, `manage_leader_index`, `manage_view`, `monitor`, `none`, `read`, `read_cross_cluster`, `read_view_metadata`, `view_index_metadata`, `write`
    - `query` (IndicesPrivilegesQuery)
      A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.
    - `allow_restricted_indices` (boolean · default: false)
      Set to `true` if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the `names` list, Elasticsearch checks privileges against these indices regardless of the value set for `allow_restricted_indices`.
  - `remote_indices` ([] RemoteIndicesPrivileges)
    A list of indices permissions for remote clusters.
    - `clusters` (string Names)
      A list of cluster aliases to which the permissions in this entry apply.
    - `field_security` ({} FieldSecurity)
      The document fields that the owners of the role have read access to.
      - `except` (string Fields)
      - `grant` (string Fields)
    - `names` (union IndexName | [] IndexName)
      A list of indices (or index name patterns) to which the permissions in this entry apply.
    - `privileges` ([] union IndexPrivilege)
      The index level privileges that owners of the role have on the specified indices.
      Values: `all`, `auto_configure`, `create`, `create_doc`, `create_index`, `create_view`, `cross_cluster_replication`, `cross_cluster_replication_internal`, `delete`, `delete_index`, `delete_view`, `index`, `maintenance`, `manage`, `manage_data_stream_lifecycle`, `manage_follow_index`, `manage_ilm`, `manage_leader_index`, `manage_view`, `monitor`, `none`, `read`, `read_cross_cluster`, `read_view_metadata`, `view_index_metadata`, `write`
    - `query` (IndicesPrivilegesQuery)
      A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.
    - `allow_restricted_indices` (boolean · default: false)
      Set to `true` if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the `names` list, Elasticsearch checks privileges against these indices regardless of the value set for `allow_restricted_indices`.
  - `remote_cluster` ([] RemoteClusterPrivileges)
    A list of cluster permissions for remote clusters.
NOTE: This is limited a subset of the cluster permissions.
    - `clusters` (string Names)
      A list of cluster aliases to which the permissions in this entry apply.
    - `privileges` ([] enum RemoteClusterPrivilege)
      The cluster level privileges that owners of the role have on the remote cluster.
      Values: `monitor_enrich`, `monitor_stats`
  - `global` ({} GlobalPrivilege)
    An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware.
    - `application` ({} ApplicationGlobalUserPrivileges)
      - `manage` ({} ManageUserPrivileges)
        - `applications` ([] string)
    - `profile` ({} WriteProfileGlobalUserPrivileges)
      A privilege that grants the ability to write the `data` and `access` sections of user profiles for the specified applications.
      - `write` ({} ManageUserPrivileges)
        The applications for which user profile data can be written.
Absent when the `profile` section is present but grants no privileges.
        - `applications` ([] string)
    - `role` ({} ManageRolesGlobalUserPrivileges)
      A privilege that grants the ability to manage roles that are scoped to the specified indices.
      - `manage` ({} ManageRolesPrivileges)
        The index-scoped role management privileges.
Absent when the `role` section is present but grants no privileges.
        - `indices` ([] ManageRolesIndexPermissions)
          - `names` ([] string)
            A list of indices (or index name patterns) that the owners of the role can manage roles for.
          - `privileges` ([] string)
            The index privileges that the managed roles are allowed to grant on the specified indices.
    - `data_source` ([] DataSourcePrivileges)
      A list of data source privilege entries, used to grant access to ES|QL data sources.
      - `names` ([] string)
        A list of data source names or wildcard patterns to which the permissions in this entry apply.
      - `privileges` ([] union DataSourcePrivilege)
        The data source privileges that owners of the role have for the specified data sources.

Supported values include:
  - `create`: Grants privilege to create a data source with a matching name.
  - `delete`: Grants privilege to delete a data source with a matching name.
  - `read_metadata`: Grants privilege to read a data source's metadata.
  - `read`: Grants privilege to attach a dataset to a data source with a matching name.
  - `manage`: Grants all data source privileges, including `create`, `delete`, `read`, and `read_metadata`.
        Values: `create`, `delete`, `read_metadata`, `read`, `manage`
  - `applications` ([] ApplicationPrivileges)
    A list of application privilege entries
    - `application` (string)
      The name of the application to which this entry applies.
    - `privileges` ([] string)
      A list of strings, where each element is the name of an application privilege or action.
    - `resources` ([] string)
      A list resources to which the privileges are applied.
  - `metadata` (Metadata)
    Optional meta-data. Within the metadata object, keys that begin with `_` are reserved for system usage.
  - `run_as` ([] string)
    A list of users that the API keys can impersonate.
NOTE: In Elastic Cloud Serverless, the run-as feature is disabled.
For API compatibility, you can still specify an empty `run_as` field, but a non-empty list will be rejected.
  - `description` (string)
    Optional description of the role descriptor
  - `restriction` ({} Restriction)
    Restriction for when the role descriptor is allowed to be effective.
    - `workflows` ([] union RestrictionWorkflow)
      A list of workflows to which the API key is restricted.
NOTE: In order to use a role restriction, an API key must be created with a single role descriptor.
      Values: `search_application_query`
  - `transient_metadata` (map string to object)
  - `_sort` (SortResults)
  - `name` (string)
    Name of the role.
## Code Examples

#### Console

```console
POST /_security/_query/role
{
    "sort": ["name"]
}
```

#### JavaScript

```javascript
const response = await client.security.queryRole({
  sort: ["name"],
});
```

#### Python

```python
resp = client.security.query_role(
    sort=[
        "name"
    ],
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_security/_query/role" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sort": [
      "name"
    ]
  }'
```

#### Java

```java
client.security().queryRole(q -> q
    .sort(s -> s
        .field(f -> f
            .field("name")
        )
    )
);
```

#### C#

```c#
var response = await client.Security
    .QueryRoleAsync(d1 => d1
        .Sort(d2 => d2
            .Field(d3 => d3
                .Field(x => x.Name)
            )
        )
    );
```

#### PHP

```php
$resp = $client->security()->queryRole([
    "body" => [
        "sort" => array(
            "name",
        ),
    ],
]);
```

#### Ruby

```ruby
response = client.security.query_role(
  body: {
    "sort": [
      "name"
    ]
  }
)
```

## Response Examples

#### Query roles by name

A successful response from `POST /_security/_query/role`. It returns a JSON structure that contains the information retrieved for one or more roles.

```json
{
    "total": 2,
    "count": 2,
    "roles": [ 
        {
          "name" : "my_admin_role",
          "cluster" : [
            "all"
          ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [
            "other_user"
          ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants full access to all management features within the cluster.",
          "_sort" : [
            "my_admin_role"
          ]
        },
        {
          "name" : "my_user_role",
          "cluster" : [ ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [ ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants user access to some indicies.",
          "_sort" : [
            "my_user_role"
          ]
        }
    ]
}
```

#### Query roles by description

A successful response from `POST /_security/_query/role`.

```json
{
    "total": 2,
    "count": 1,
    "roles": [
        {
          "name" : "my_user_role",
          "cluster" : [ ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [ ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants user access to some indicies."
        }
    ]
}
```