Find roles with a query
- POST also GET /_security/_query/role
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.
- Cluster privileges:
read_security
Request
-
queryRoleQueryContainer -
A query to filter which roles to return. If the query parameter is missing, it is equivalent to a
match_allquery. The query supports a subset of query types, includingmatch_all,bool,term,terms,match,ids,prefix,wildcard,exists,range, andsimple_query_string. You can query the following information associated with roles:name,description,metadata,applications.application,applications.privileges, andapplications.resources. -
boolBoolQuery -
matches roles matching boolean combinations of other queries.
-
boostnumber · 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.
-
_namestring -
filteroneOf -
The clause (query) must appear in matching documents. However, unlike
must, the score of the query will be ignored. -
minimum_should_matchnumber | string MinimumShouldMatch -
Specifies the number or percentage of
shouldclauses returned documents must match. -
mustoneOf -
The clause (query) must appear in matching documents and will contribute to the score.
-
must_notoneOf -
The clause (query) must not appear in the matching documents. Because scoring is ignored, a score of
0is returned for all documents. -
shouldoneOf -
The clause (query) should appear in the matching document.
-
existsExistsQuery -
Returns roles that contain an indexed value for a field.
-
boostnumber · 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.
-
_namestring -
fieldstring Fieldrequired -
Name of the field you wish to search.
-
idsIdsQuery -
Returns roles based on their IDs. This query uses role document IDs stored in the
_idfield. -
boostnumber · 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.
-
_namestring -
valuesstring Ids -
An array of document IDs.
-
matchmap string to MatchQuery -
Returns roles that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
-
<string>MatchQuery -
boostnumber · 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.
-
_namestring -
analyzerstring -
Analyzer used to convert the text in the query value into tokens.
-
auto_generate_synonyms_phrase_queryboolean · default: true -
If
true, match phrase queries are automatically created for multi-term synonyms. -
cutoff_frequencynumberdeprecated -
fuzzinessnumber | string Fuzziness -
Maximum edit distance allowed for matching.
-
fuzzy_rewritestring -
Method used to rewrite the query.
-
fuzzy_transpositionsboolean · default: true -
If
true, edits for fuzzy matching include transpositions of two adjacent characters (for example,abtoba). -
lenientboolean · default: false -
If
true, format-based errors, such as providing a text query value for a numeric field, are ignored. -
max_expansionsnumber · default: 50 -
Maximum number of terms to which the query will expand.
-
minimum_should_matchnumber | string MinimumShouldMatch -
Minimum number of clauses that must match for a document to be returned.
-
operatorOperator · default: 'or' -
Boolean logic used to interpret text in the query value.
-
Values:
andANDorOR -
prefix_lengthnumber · default: 0 -
Number of beginning characters left unchanged for fuzzy matching.
-
queryboolean | number | stringrequired -
Text, number, boolean value or date you wish to find in the provided field.
-
zero_terms_queryZeroTermsQuery · default: 'none' -
Indicates whether no documents are returned if the
analyzerremoves all tokens, such as when using astopfilter.Supported values include:
all: Returns all documents, similar to amatch_allquery.none: No documents are returned if theanalyzerremoves all tokens.
-
Values:
allnone -
match_allMatchAllQuery -
Matches all roles, giving them all a
_scoreof 1.0. -
prefixmap string to PrefixQuery -
Returns roles that contain a specific prefix in a provided field.
-
<string>PrefixQuery -
boostnumber · 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.
-
_namestring -
rewritestring -
Method used to rewrite the query.
-
valuestringrequired -
Beginning characters of terms you wish to find in the provided field.
-
case_insensitiveboolean · default: false -
Allows case insensitive matching of the value with the indexed field values when set to
true. Default isfalsewhich means the case sensitivity of matching depends on the underlying field’s mapping. -
rangemap string to RangeQuery -
Returns roles that contain terms within a provided range.
-
simple_query_stringSimpleQueryStringQuery -
Returns roles based on a provided query string, using a parser with a limited but fault-tolerant syntax.
-
boostnumber · 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.
-
_namestring -
analyzerstring -
Analyzer used to convert text in the query string into tokens.
-
analyze_wildcardboolean · default: false -
If
true, the query attempts to analyze wildcard terms in the query string. -
auto_generate_synonyms_phrase_queryboolean · default: true -
If
true, the parser creates a match_phrase query for each multi-position token. -
default_operatorOperator · default: 'or' -
Default boolean logic used to interpret text in the query string if no operators are specified.
-
Values:
andANDorOR -
fieldsstring Field -
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 theindex.query.default_field indexsetting, which has a default value of*. -
flagsSimpleQueryStringFlags · default: ALL -
List of enabled operators for the simple query string syntax.
-
Values:
NONEANDNOTORPREFIXPHRASEPRECEDENCEESCAPEWHITESPACEFUZZYNEARSLOPALL -
fuzzy_max_expansionsnumber · default: 50 -
Maximum number of terms to which the query expands for fuzzy matching.
-
fuzzy_prefix_lengthnumber · default: 0 -
Number of beginning characters left unchanged for fuzzy matching.
-
fuzzy_transpositionsboolean -
If
true, edits for fuzzy matching include transpositions of two adjacent characters (for example,abtoba). -
lenientboolean · default: false -
If
true, format-based errors, such as providing a text value for a numeric field, are ignored. -
minimum_should_matchnumber | string MinimumShouldMatch -
Minimum number of clauses that must match for a document to be returned.
-
querystringrequired -
Query string in the simple query string syntax you wish to parse and use for search.
-
quote_field_suffixstring -
Suffix appended to quoted text in the query string.
-
termmap string to TermQuery -
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>TermQuery -
boostnumber · 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.
-
_namestring -
valueFieldValuerequired -
Term you wish to find in the provided field.
-
case_insensitiveboolean · default: false -
Allows case insensitive matching of the value with the indexed field values when set to
true. Whenfalse, the case sensitivity of matching depends on the underlying field’s mapping. -
termsTermsQuery -
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.
-
wildcardmap string to WildcardQuery -
Returns roles that contain terms matching a wildcard pattern.
-
<string>WildcardQuery -
boostnumber · 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.
-
_namestring -
case_insensitiveboolean -
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.
-
rewritestring -
Method used to rewrite the query.
-
valuestring -
Wildcard pattern for terms you wish to find in the provided field. Required, when wildcard is not set.
-
wildcardstring -
Wildcard pattern for terms you wish to find in the provided field. Required, when value is not set.
-
fromnumber · default: 0 -
The starting document offset. It must not be negative. By default, you cannot page through more than 10,000 hits using the
fromandsizeparameters. To page through more hits, use thesearch_afterparameter. -
sortSort -
The sort definition. You can sort on
name,description,metadata,applications.application,applications.privileges, andapplications.resources. In addition, sort can also be applied to the_docfield to sort by index order. -
sizenumber · 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
fromandsizeparameters. To page through more hits, use thesearch_afterparameter.
Response
-
totalnumberrequired -
The total number of roles found.
-
countnumberrequired -
The number of roles returned in the response.
-
rolesQueryRolerequired -
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.enabledand the_sortfields.transient_metadata.enabledis set tofalsein case the role is automatically disabled, for example when the role grants privileges that are not allowed by the installed license._sortis present when the search query sorts on some field. It contains the array of values that have been used for sorting. -
clusterClusterPrivilege -
A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.
-
Values:
allcancel_taskclone_api_keycreate_snapshotcross_cluster_replicationcross_cluster_searchdelegate_pkigrant_api_keymanagemanage_api_keymanage_autoscalingmanage_behavioral_analyticsmanage_ccrmanage_data_frame_transformsmanage_data_stream_global_retentionmanage_enrichmanage_esqlmanage_ilmmanage_index_templatesmanage_inferencemanage_ingest_pipelinesmanage_logstash_pipelinesmanage_mlmanage_oidcmanage_own_api_keymanage_pipelinemanage_reindexmanage_rollupmanage_samlmanage_search_applicationmanage_search_query_rulesmanage_search_synonymsmanage_securitymanage_service_accountmanage_slmmanage_tokenmanage_transformmanage_user_profilemanage_watchermonitormonitor_data_frame_transformsmonitor_data_stream_global_retentionmonitor_enrichmonitor_esqlmonitor_inferencemonitor_mlmonitor_reindexmonitor_rollupmonitor_snapshotmonitor_statsmonitor_text_structuremonitor_transformmonitor_watchernonepost_behavioral_analytics_eventread_ccrread_fleet_secretsread_ilmread_pipelineread_securityread_slmtransport_clientwrite_connector_secretswrite_fleet_secrets -
indicesIndicesPrivileges -
A list of indices permissions entries.
-
field_securityFieldSecurity -
The document fields that the owners of the role have read access to.
- Reference
-
namesIndexName | IndexNamerequired -
A list of indices (or index name patterns) to which the permissions in this entry apply.
-
privilegesIndexPrivilegerequired -
The index level privileges that owners of the role have on the specified indices.
-
Values:
allauto_configurecreatecreate_doccreate_indexcreate_viewcross_cluster_replicationcross_cluster_replication_internaldeletedelete_indexdelete_viewindexmaintenancemanagemanage_data_stream_lifecyclemanage_follow_indexmanage_ilmmanage_leader_indexmanage_viewmonitornonereadread_cross_clusterread_view_metadataview_index_metadatawrite -
queryIndicesPrivilegesQuery -
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_indicesboolean · default: false -
Set to
trueif 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 thenameslist, Elasticsearch checks privileges against these indices regardless of the value set forallow_restricted_indices. -
remote_indicesRemoteIndicesPrivileges -
A list of indices permissions for remote clusters.
-
clustersstring Namesrequired -
A list of cluster aliases to which the permissions in this entry apply.
-
field_securityFieldSecurity -
The document fields that the owners of the role have read access to.
- Reference
-
namesIndexName | IndexNamerequired -
A list of indices (or index name patterns) to which the permissions in this entry apply.
-
privilegesIndexPrivilegerequired -
The index level privileges that owners of the role have on the specified indices.
-
Values:
allauto_configurecreatecreate_doccreate_indexcreate_viewcross_cluster_replicationcross_cluster_replication_internaldeletedelete_indexdelete_viewindexmaintenancemanagemanage_data_stream_lifecyclemanage_follow_indexmanage_ilmmanage_leader_indexmanage_viewmonitornonereadread_cross_clusterread_view_metadataview_index_metadatawrite -
queryIndicesPrivilegesQuery -
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_indicesboolean · default: false -
Set to
trueif 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 thenameslist, Elasticsearch checks privileges against these indices regardless of the value set forallow_restricted_indices. -
remote_clusterRemoteClusterPrivileges -
A list of cluster permissions for remote clusters. NOTE: This is limited a subset of the cluster permissions.
-
clustersstring Namesrequired -
A list of cluster aliases to which the permissions in this entry apply.
-
privilegesRemoteClusterPrivilegerequired -
The cluster level privileges that owners of the role have on the remote cluster.
-
Values:
monitor_enrichmonitor_stats -
globalGlobalPrivilege -
An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware.
-
applicationApplicationGlobalUserPrivileges -
manageManageUserPrivilegesrequired -
applicationsstringrequired -
profileWriteProfileGlobalUserPrivileges -
A privilege that grants the ability to write the
dataandaccesssections of user profiles for the specified applications. -
writeManageUserPrivileges -
The applications for which user profile data can be written. Absent when the
profilesection is present but grants no privileges. -
applicationsstringrequired -
roleManageRolesGlobalUserPrivileges -
A privilege that grants the ability to manage roles that are scoped to the specified indices.
-
manageManageRolesPrivileges -
The index-scoped role management privileges. Absent when the
rolesection is present but grants no privileges. -
indicesManageRolesIndexPermissionsrequired -
namesstringrequired -
A list of indices (or index name patterns) that the owners of the role can manage roles for.
-
privilegesstringrequired -
The index privileges that the managed roles are allowed to grant on the specified indices.
-
data_sourceDataSourcePrivileges -
A list of data source privilege entries, used to grant access to ES|QL data sources.
-
namesstringrequired -
A list of data source names or wildcard patterns to which the permissions in this entry apply.
-
privilegesDataSourcePrivilegerequired -
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, includingcreate,delete,read, andread_metadata.
-
Values:
createdeleteread_metadatareadmanage -
applicationsApplicationPrivileges -
A list of application privilege entries
-
applicationstringrequired -
The name of the application to which this entry applies.
-
privilegesstringrequired -
A list of strings, where each element is the name of an application privilege or action.
-
resourcesstringrequired -
A list resources to which the privileges are applied.
-
metadataMetadata -
Optional meta-data. Within the metadata object, keys that begin with
_are reserved for system usage. -
run_asstring -
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_asfield, but a non-empty list will be rejected. - Reference
-
descriptionstring -
Optional description of the role descriptor
-
restrictionRestriction -
Restriction for when the role descriptor is allowed to be effective.
-
workflowsRestrictionWorkflowrequired -
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_metadatamap string to object -
_sortSortResults -
namestringrequired -
Name of the role.