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.
Required privileges
- Cluster privileges read_security
Request body
-
queryobject -
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. -
boolobject -
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.
-
filterunion oneOf -
The clause (query) must appear in matching documents. However, unlike
must, the score of the query will be ignored. -
One of:
Query[]orQuery -
minimum_should_matchnumber | string -
Specifies the number or percentage of
shouldclauses returned documents must match. -
mustunion oneOf -
The clause (query) must appear in matching documents and will contribute to the score.
-
One of:
Query[]orQuery -
idsobject -
Returns roles based on their IDs. This query uses role document IDs stored in the
_idfield. -
matchmap 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 -
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.
-
auto_generate_synonyms_phrase_queryboolean · default: true -
If
true, match phrase queries are automatically created for multi-term synonyms. -
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. -
minimum_should_matchnumber | string -
Minimum number of clauses that must match for a document to be returned.
-
operatorenum · default: 'or' -
Boolean logic used to interpret text in the query value.
-
Values:
andANDorOR -
queryboolean | number | stringrequired -
Text, number, boolean value or date you wish to find in the provided field.
-
zero_terms_queryenum · 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 -
prefixmap string to object · min properties: 1 · max properties: 1 -
Returns roles that contain a specific prefix in a provided field.
-
<string>object -
rangemap string to oneOf · min properties: 1 · max properties: 1 -
Returns roles that contain terms within a provided range.
-
<string>union oneOf -
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.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
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.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
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.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
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.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
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.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
simple_query_stringobject -
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.
-
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_operatorenum · default: 'or' -
Default boolean logic used to interpret text in the query string if no operators are specified.
-
Values:
andANDorOR -
fieldsstring[] -
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*. -
flagsunion · 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 -
Minimum number of clauses that must match for a document to be returned.
-
termmap 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 -
termsobject -
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 object · min properties: 1 · max properties: 1 -
Returns roles that contain terms matching a wildcard pattern.
-
<string>object -
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.
-
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.
-
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. -
sortunion oneOf -
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.
Response
-
rolesobject[]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.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. -
clusterunion anyOf[] -
A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.
-
Values:
allcancel_taskmanagemanage_api_keymanage_behavioral_analyticsmanage_enrichmanage_esqlmanage_index_templatesmanage_inferencemanage_ingest_pipelinesmanage_logstash_pipelinesmanage_mlmanage_own_api_keymanage_pipelinemanage_reindexmanage_search_applicationmanage_search_query_rulesmanage_search_synonymsmanage_securitymanage_transformmonitormonitor_enrichmonitor_esqlmonitor_inferencemonitor_mlmonitor_reindexmonitor_transformnonepost_behavioral_analytics_eventread_pipelineread_securityread_project_routingmanage_project_routing -
indicesobject[] -
A list of indices permissions entries.
-
field_securityobject -
The document fields that the owners of the role have read access to.
- Reference
-
namesunion string | string[]required -
A list of indices (or index name patterns) to which the permissions in this entry apply.
-
privilegesunion anyOf[]required -
The index level privileges that owners of the role have on the specified indices.
-
Values:
allauto_configurecreatecreate_doccreate_indexcreate_viewdeletedelete_indexdelete_viewindexmaintenancemanagemanage_data_stream_lifecyclemanage_viewmonitornonereadread_view_metadataview_index_metadatawrite -
queryunion 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:
-
templateobject -
When you create a role, you can specify a query that defines the 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 Elasticsearch 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.
- Reference
-
sourceunion oneOf - One of:
-
paramsmap string to object -
Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
-
langunion anyOf · default: painless -
Specifies the language the script is written in.
Supported values include:
painless: Painless scripting language, purpose-built for Elasticsearch.expression: Lucene’s expressions language, compiles a JavaScript expression to bytecode.mustache: Mustache templated, used for templates.java: Expert Java API
-
Values:
painlessexpressionmustachejava -
metadataobject -
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
Query
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Query
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.