Find roles with a query

  • POST also GET /_security/_query/role
Auth

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

query object

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 object

matches roles matching boolean combinations of other queries.

boost number · default: 1

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
filter union oneOf

The clause (query) must appear in matching documents. However, unlike must, the score of the query will be ignored.

One of: Query[] or Query
minimum_should_match number | string

Specifies the number or percentage of should clauses returned documents must match.

must union oneOf

The clause (query) must appear in matching documents and will contribute to the score.

One of: Query[] or Query
must_not union oneOf

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: Query[] or Query
should union oneOf

The clause (query) should appear in the matching document.

One of: Query[] or Query
exists object

Returns roles that contain an indexed value for a field.

boost number · default: 1

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
field string required

Name of the field you wish to search.

ids object

Returns roles based on their IDs. This query uses role document IDs stored in the _id field.

boost number · default: 1

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
values union oneOf

An array of document IDs.

One of: string[] or string
match map string to object · min properties: 1 · max properties: 1

Returns roles that match a provided text, number, date or boolean value. The provided text is analyzed before matching.

<string> object
boost number · default: 1

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
analyzer string

Analyzer used to convert the text in the query value into tokens.

auto_generate_synonyms_phrase_query boolean · default: true

If true, match phrase queries are automatically created for multi-term synonyms.

cutoff_frequency number deprecated
fuzziness number | string

Maximum edit distance allowed for matching.

fuzzy_rewrite string

Method used to rewrite the query.

fuzzy_transpositions boolean · default: true

If true, edits for fuzzy matching include transpositions of two adjacent characters (for example, ab to ba).

lenient boolean · default: false

If true, format-based errors, such as providing a text query value for a numeric field, are ignored.

max_expansions number · default: 50

Maximum number of terms to which the query will expand.

minimum_should_match number | string

Minimum number of clauses that must match for a document to be returned.

operator enum · default: 'or'

Boolean logic used to interpret text in the query value.

Values: and AND or OR
prefix_length number · default: 0

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 · default: 'none'

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 object

Matches all roles, giving them all a _score of 1.0.

boost number · default: 1

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
prefix map string to object · min properties: 1 · max properties: 1

Returns roles that contain a specific prefix in a provided field.

<string> object
boost number · default: 1

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
rewrite string

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

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 oneOf · min properties: 1 · max properties: 1

Returns roles that contain terms within a provided range.

simple_query_string object

Returns roles based on a provided query string, using a parser with a limited but fault-tolerant syntax.

boost number · default: 1

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
analyzer string

Analyzer used to convert text in the query string into tokens.

analyze_wildcard boolean · default: false

If true, the query attempts to analyze wildcard terms in the query string.

auto_generate_synonyms_phrase_query boolean · default: true

If true, the parser creates a match_phrase query for each multi-position token.

default_operator enum · default: 'or'

Default boolean logic used to interpret text in the query string if no operators are specified.

Values: and AND or OR
fields string[]

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 union · default: ALL

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

Maximum number of terms to which the query expands for fuzzy matching.

fuzzy_prefix_length number · default: 0

Number of beginning characters left unchanged for fuzzy matching.

fuzzy_transpositions boolean

If true, edits for fuzzy matching include transpositions of two adjacent characters (for example, ab to ba).

lenient boolean · default: false

If true, format-based errors, such as providing a text value for a numeric field, are ignored.

minimum_should_match number | string

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

Suffix appended to quoted text in the query string.

term map string to object · min properties: 1 · max properties: 1

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.

<string> object
boost number · default: 1

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
value union oneOf required

Term you wish to find in the provided field.

One of: number or string or boolean
case_insensitive boolean · default: false

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 object

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

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
wildcard map string to object · min properties: 1 · max properties: 1

Returns roles that contain terms matching a wildcard pattern.

<string> object
boost number · default: 1

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
case_insensitive boolean

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

Method used to rewrite the query.

value string

Wildcard pattern for terms you wish to find in the provided field. Required, when wildcard is not set.

wildcard string

Wildcard pattern for terms you wish to find in the provided field. Required, when value is not set.

from number · default: 0

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 union oneOf

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.

A value or an array; each item is one of:

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

size number · default: 10

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 union[]

The search after definition.

Reference

Response

application/json
total number required

The total number of roles found.

count number required

The number of roles returned in the response.

roles object[] required

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 anyOf[]

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
indices object[]

A list of indices permissions entries.

field_security object

The document fields that the owners of the role have read access to.

Reference
except union oneOf
One of: string[] or string
grant union oneOf
One of: string[] or string
names union string | string[] required

A list of indices (or index name patterns) to which the permissions in this entry apply.

privileges union anyOf[] required

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
query union oneOf

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.

One of:
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 object[]

A list of indices permissions for remote clusters.

clusters union oneOf required

A list of cluster aliases to which the permissions in this entry apply.

One of: string[] or string
field_security object

The document fields that the owners of the role have read access to.

Reference
except union oneOf
One of: string[] or string
grant union oneOf
One of: string[] or string
names union string | string[] required

A list of indices (or index name patterns) to which the permissions in this entry apply.

privileges union anyOf[] required

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
query union oneOf

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.

One of:
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 object[]

A list of cluster permissions for remote clusters. NOTE: This is limited a subset of the cluster permissions.

clusters union oneOf required

A list of cluster aliases to which the permissions in this entry apply.

One of: string[] or string
privileges enum[] required

The cluster level privileges that owners of the role have on the remote cluster.

Values: monitor_enrich monitor_stats
global object

An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware.

application object
manage object

The applications for which application privileges can be managed. Absent when the application section is present but grants no privileges.

applications string[] required
profile object

A privilege that grants the ability to write the data and access sections of user profiles for the specified applications.

write object

The applications for which user profile data can be written. Absent when the profile section is present but grants no privileges.

applications string[] required
role object

A privilege that grants the ability to manage roles that are scoped to the specified indices.

manage object

The index-scoped role management privileges. Absent when the role section is present but grants no privileges.

indices object[] required
names string[] required

A list of indices (or index name patterns) that the owners of the role can manage roles for.

privileges string[] required

The index privileges that the managed roles are allowed to grant on the specified indices.

data_source object[]

A list of data source privilege entries, used to grant access to ES|QL data sources.

names string[] required

A list of data source names or wildcard patterns to which the permissions in this entry apply.

privileges union anyOf[] required

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 object[]

A list of application privilege entries

application string required

The name of the application to which this entry applies.

privileges string[] required

A list of strings, where each element is the name of an application privilege or action.

resources string[] required

A list resources to which the privileges are applied.

metadata object

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.

Reference
description string

Optional description of the role descriptor

restriction object

Restriction for when the role descriptor is allowed to be effective.

workflows union anyOf[] required

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 union[]
name string required

Name of the role.