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
Body
-
Hide query attributes Show query attributes object
-
Hide bool attributes Show bool attributes object
-
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.
filter
object | array[object] The clause (query) must appear in matching documents. However, unlike
must, the score of the query will be ignored.One of: An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation Hide attributes Show attributes
-
Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.
External documentation -
Matches
geo_pointandgeo_shapevalues that intersect a grid cell from a GeoGrid aggregation. -
Returns documents based on the order and proximity of matching terms.
External documentation -
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
External documentation -
Analyzes its input and constructs a
boolquery from the terms. Each term except the last is used in atermquery. The last term is used in a prefix query.External documentation -
Analyzes the text and creates a phrase query out of the analyzed text.
External documentation -
Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.
External documentation -
Returns documents that contain a specific prefix in a provided field.
External documentation -
Returns documents that contain terms within a provided range.
External documentation -
Returns documents that contain terms matching a regular expression.
External documentation -
Matches spans containing a term.
External documentation -
Returns documents 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.
External documentation -
Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
External documentation -
Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.
External documentation -
Supports returning text_expansion query results by sending in precomputed tokens with the query.
External documentation -
Returns documents that contain terms matching a wildcard pattern.
External documentation
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Hide attributes Show attributes object
External documentation -
Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.
-
Matches
geo_pointandgeo_shapevalues that intersect a grid cell from a GeoGrid aggregation. -
Returns documents based on the order and proximity of matching terms.
-
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
-
Analyzes its input and constructs a
boolquery from the terms. Each term except the last is used in atermquery. The last term is used in a prefix query. -
Analyzes the text and creates a phrase query out of the analyzed text.
-
Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.
-
Returns documents that contain a specific prefix in a provided field.
-
Returns documents that contain terms within a provided range.
-
Returns documents that contain terms matching a regular expression.
-
Matches spans containing a term.
-
Returns documents 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.
-
Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
-
Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.
-
Supports returning text_expansion query results by sending in precomputed tokens with the query.
-
Returns documents that contain terms matching a wildcard pattern.
must
object | array[object] The clause (query) must appear in matching documents and will contribute to the score.
One of: An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation Hide attributes Show attributes
-
Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.
External documentation -
Matches
geo_pointandgeo_shapevalues that intersect a grid cell from a GeoGrid aggregation. -
Returns documents based on the order and proximity of matching terms.
External documentation -
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
External documentation -
Analyzes its input and constructs a
boolquery from the terms. Each term except the last is used in atermquery. The last term is used in a prefix query.External documentation -
Analyzes the text and creates a phrase query out of the analyzed text.
External documentation -
Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.
External documentation -
Returns documents that contain a specific prefix in a provided field.
External documentation -
Returns documents that contain terms within a provided range.
External documentation -
Returns documents that contain terms matching a regular expression.
External documentation -
Matches spans containing a term.
External documentation -
Returns documents 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.
External documentation -
Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
External documentation -
Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.
External documentation -
Supports returning text_expansion query results by sending in precomputed tokens with the query.
External documentation -
Returns documents that contain terms matching a wildcard pattern.
External documentation
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Hide attributes Show attributes object
External documentation -
Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.
-
Matches
geo_pointandgeo_shapevalues that intersect a grid cell from a GeoGrid aggregation. -
Returns documents based on the order and proximity of matching terms.
-
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
-
Analyzes its input and constructs a
boolquery from the terms. Each term except the last is used in atermquery. The last term is used in a prefix query. -
Analyzes the text and creates a phrase query out of the analyzed text.
-
Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.
-
Returns documents that contain a specific prefix in a provided field.
-
Returns documents that contain terms within a provided range.
-
Returns documents that contain terms matching a regular expression.
-
Matches spans containing a term.
-
Returns documents 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.
-
Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
-
Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.
-
Supports returning text_expansion query results by sending in precomputed tokens with the query.
-
Returns documents that contain terms matching a wildcard pattern.
must_not
object | array[object] The clause (query) must not appear in the matching documents. Because scoring is ignored, a score of
0is returned for all documents.One of: An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation Hide attributes Show attributes
-
Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.
External documentation -
Matches
geo_pointandgeo_shapevalues that intersect a grid cell from a GeoGrid aggregation. -
Returns documents based on the order and proximity of matching terms.
External documentation -
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
External documentation -
Analyzes its input and constructs a
boolquery from the terms. Each term except the last is used in atermquery. The last term is used in a prefix query.External documentation -
Analyzes the text and creates a phrase query out of the analyzed text.
External documentation -
Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.
External documentation -
Returns documents that contain a specific prefix in a provided field.
External documentation -
Returns documents that contain terms within a provided range.
External documentation -
Returns documents that contain terms matching a regular expression.
External documentation -
Matches spans containing a term.
External documentation -
Returns documents 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.
External documentation -
Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
External documentation -
Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.
External documentation -
Supports returning text_expansion query results by sending in precomputed tokens with the query.
External documentation -
Returns documents that contain terms matching a wildcard pattern.
External documentation
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Hide attributes Show attributes object
External documentation -
Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.
-
Matches
geo_pointandgeo_shapevalues that intersect a grid cell from a GeoGrid aggregation. -
Returns documents based on the order and proximity of matching terms.
-
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
-
Analyzes its input and constructs a
boolquery from the terms. Each term except the last is used in atermquery. The last term is used in a prefix query. -
Analyzes the text and creates a phrase query out of the analyzed text.
-
Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.
-
Returns documents that contain a specific prefix in a provided field.
-
Returns documents that contain terms within a provided range.
-
Returns documents that contain terms matching a regular expression.
-
Matches spans containing a term.
-
Returns documents 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.
-
Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
-
Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.
-
Supports returning text_expansion query results by sending in precomputed tokens with the query.
-
Returns documents that contain terms matching a wildcard pattern.
should
object | array[object] The clause (query) should appear in the matching document.
One of: An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation Hide attributes Show attributes
-
Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.
External documentation -
Matches
geo_pointandgeo_shapevalues that intersect a grid cell from a GeoGrid aggregation. -
Returns documents based on the order and proximity of matching terms.
External documentation -
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
External documentation -
Analyzes its input and constructs a
boolquery from the terms. Each term except the last is used in atermquery. The last term is used in a prefix query.External documentation -
Analyzes the text and creates a phrase query out of the analyzed text.
External documentation -
Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.
External documentation -
Returns documents that contain a specific prefix in a provided field.
External documentation -
Returns documents that contain terms within a provided range.
External documentation -
Returns documents that contain terms matching a regular expression.
External documentation -
Matches spans containing a term.
External documentation -
Returns documents 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.
External documentation -
Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
External documentation -
Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.
External documentation -
Supports returning text_expansion query results by sending in precomputed tokens with the query.
External documentation -
Returns documents that contain terms matching a wildcard pattern.
External documentation
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Hide attributes Show attributes object
External documentation -
Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.
-
Matches
geo_pointandgeo_shapevalues that intersect a grid cell from a GeoGrid aggregation. -
Returns documents based on the order and proximity of matching terms.
-
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
-
Analyzes its input and constructs a
boolquery from the terms. Each term except the last is used in atermquery. The last term is used in a prefix query. -
Analyzes the text and creates a phrase query out of the analyzed text.
-
Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.
-
Returns documents that contain a specific prefix in a provided field.
-
Returns documents that contain terms within a provided range.
-
Returns documents that contain terms matching a regular expression.
-
Matches spans containing a term.
-
Returns documents 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.
-
Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
-
Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.
-
Supports returning text_expansion query results by sending in precomputed tokens with the query.
-
Returns documents that contain terms matching a wildcard pattern.
-
-
Hide exists attributes Show exists attributes object
-
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.
-
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
-
-
Hide ids attributes Show ids attributes object
-
Returns roles that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
-
Hide match_all attributes Show match_all attributes object
-
Returns roles that contain a specific prefix in a provided field.
-
Returns roles that contain terms within a provided range.
-
Hide simple_query_string attributes Show simple_query_string attributes object
-
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.
-
Analyzer used to convert text in the query string into tokens.
-
If
true, the query attempts to analyze wildcard terms in the query string. -
If
true, the parser creates a match_phrase query for each multi-position token. -
Values are
and,AND,or, orOR. -
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*. flags
string Query flags can be either a single flag or a combination of flags, e.g.
OR|AND|PREFIX-
Maximum number of terms to which the query expands for fuzzy matching.
-
Number of beginning characters left unchanged for fuzzy matching.
-
If
true, edits for fuzzy matching include transpositions of two adjacent characters (for example,abtoba). -
If
true, format-based errors, such as providing a text value for a numeric field, are ignored. -
Query string in the simple query string syntax you wish to parse and use for search.
-
Suffix appended to quoted text in the query string.
-
-
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.
-
Hide terms attributes Show terms attributes object
-
Returns roles that contain terms matching a wildcard pattern.
-
-
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. sort
string | object | array[string | object] One of: Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes
-
Hide _geo_distance attributes Show _geo_distance attributes object
-
Values are
min,max,sum,avg, ormedian. -
Values are
arcorplane. -
Values are
ascordesc. -
Values are
in,ft,yd,mi,nmi,km,m,cm, ormm. -
Hide nested attributes Show nested attributes object
-
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation Hide filter attributes Show filter attributes object
-
Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.
-
Matches
geo_pointandgeo_shapevalues that intersect a grid cell from a GeoGrid aggregation. -
Returns documents based on the order and proximity of matching terms.
-
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
-
Analyzes its input and constructs a
boolquery from the terms. Each term except the last is used in atermquery. The last term is used in a prefix query. -
Analyzes the text and creates a phrase query out of the analyzed text.
-
Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.
-
Returns documents that contain a specific prefix in a provided field.
-
Returns documents that contain terms within a provided range.
-
Returns documents that contain terms matching a regular expression.
-
Matches spans containing a term.
-
Returns documents 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.
-
Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
-
Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.
-
Supports returning text_expansion query results by sending in precomputed tokens with the query.
-
Returns documents that contain terms matching a wildcard pattern.
-
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
-
-
-
Hide _script attributes Show _script attributes object
-
Values are
ascordesc. -
Hide script attributes Show script attributes object
-
Values are
string,number, orversion. -
Values are
min,max,sum,avg, ormedian. -
Hide nested attributes Show nested attributes object
-
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation Hide filter attributes Show filter attributes object
-
Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.
-
Matches
geo_pointandgeo_shapevalues that intersect a grid cell from a GeoGrid aggregation. -
Returns documents based on the order and proximity of matching terms.
-
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
-
Analyzes its input and constructs a
boolquery from the terms. Each term except the last is used in atermquery. The last term is used in a prefix query. -
Analyzes the text and creates a phrase query out of the analyzed text.
-
Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.
-
Returns documents that contain a specific prefix in a provided field.
-
Returns documents that contain terms within a provided range.
-
Returns documents that contain terms matching a regular expression.
-
Matches spans containing a term.
-
Returns documents 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.
-
Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
-
Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.
-
Supports returning text_expansion query results by sending in precomputed tokens with the query.
-
Returns documents that contain terms matching a wildcard pattern.
-
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
-
-
One of: Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes
-
Hide _geo_distance attributes Show _geo_distance attributes object
-
Values are
min,max,sum,avg, ormedian. -
Values are
arcorplane. -
Values are
ascordesc. -
Values are
in,ft,yd,mi,nmi,km,m,cm, ormm. -
Hide nested attributes Show nested attributes object
-
-
Hide _script attributes Show _script attributes object
-
Values are
ascordesc. -
Values are
string,number, orversion. -
Values are
min,max,sum,avg, ormedian. -
Hide nested attributes Show nested attributes object
-
-
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. -
A field value.
Responses
-
Hide response attributes Show response attributes object
-
The total number of roles found.
-
The number of roles returned in the response.
-
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.Hide roles attributes Show roles attributes object
-
A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.
-
A list of indices permissions entries.
Hide indices attributes Show indices attributes object
-
The index level privileges that owners of the role have on the specified indices.
-
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.
-
A list of indices permissions for remote clusters.
Hide remote_indices attributes Show remote_indices attributes object
-
The index level privileges that owners of the role have on the specified indices.
-
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.
-
A list of cluster permissions for remote clusters. NOTE: This is limited a subset of the cluster permissions.
-
A list of application privilege entries
Hide applications attributes Show applications attributes object
-
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. -
Optional description of the role descriptor
-
A field value.
-
Name of the role.
-
-
POST /_security/_query/role
{
"sort": ["name"]
}curl \
--request POST 'http://api.example.com/_security/_query/role' \
--header "Content-Type: application/json" \
--data '"{\n \"sort\": [\"name\"]\n}"'{
"sort": ["name"]
}{
"query": {
"match": {
"description": {
"query": "user access"
}
}
},
"size": 1
}{
"query": {
"bool": {
"must_not": {
"term": {
"metadata._reserved": true
}
}
}
},
"sort": ["name"]
}{
"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"
]
}
]
}{
"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."
}
]
}