Find users with a query
- POST also GET /_security/_query/user
Get information for users in a paginated manner. You can optionally filter the results with a query.
As opposed to the get user API, built-in users are excluded from the result. This API is only for native users.
Required privileges
- Cluster privileges read_security
Request body
-
queryobject -
A query to filter which users 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 user:username,roles,enabled,full_name, andemail. -
idsobject -
Returns users based on their IDs. This query uses the user document IDs stored in the
_idfield. -
boolobject -
matches users 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 -
matchmap string to object · min properties: 1 · max properties: 1 -
Returns users 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 users that contain a specific prefix in a provided field.
-
<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 · default: falseThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 7.10 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
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 oneOf · min properties: 1 · max properties: 1 -
Returns users 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 users 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 users 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 -
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.
-
valueunion oneOfrequired -
Term you wish to find in the provided field.
-
One of:
numberorstringorboolean -
case_insensitiveboolean · default: falseThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 7.10 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
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. -
termsobject -
Returns users 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 users 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_insensitivebooleanThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 7.10 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
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. Fields eligible for sorting are:
username,roles,enabled. In addition, sort can also be applied to the_docfield to sort by index order. - Reference