Query User API
editQuery User API
editRetrieves native users with Query DSL in a paginated fashion.
As opposed to the get user api, built-in users are excluded from the result. This API is only for native users.
Prerequisites
edit-
To use this API, you must have at least the
read_security
cluster privilege.
Description
editUse this API to retrieve users managed by the native realm in a paginated manner. You can optionally filter the results with a query.
Request body
editYou can specify the following parameters in the request body:
-
query
-
(Optional, string) A query to filter which users to return. The query supports a subset of query types, including
match_all
,bool
,term
,terms
,match
,ids
,prefix
,wildcard
,exists
,range
, andsimple query string
.You can query the following public values associated with a user.
Valid values for
query
-
username
- An identifier for the user.
-
roles
- An array of the role names of the roles that are assigned to the user.
-
full_name
- Full name of the user.
-
email
- The email of the user.
-
enabled
- Specifies whether the user is enabled.
-
-
from
-
(Optional, integer) Starting document offset. Needs to be non-negative and defaults to
0
.By default, you cannot page through more than 10,000 hits using the
from
andsize
parameters. To page through more hits, use thesearch_after
parameter. -
size
-
(Optional, integer) The number of hits to return. Must not be negative and defaults to
10
.By default, you cannot page through more than 10,000 hits using the
from
andsize
parameters. To page through more hits, use thesearch_after
parameter. -
sort
-
(Optional, object) Sort definition. You can sort on
username
,roles
orenabled
. In addition, sort can also be applied to the_doc
field to sort by index order. -
search_after
- (Optional, array) Search after definition.
Query parameters
edit-
with_profile_uid
-
(Optional, boolean) Determines whether to retrieve the user profile
uid
, if exists, for the users. Defaults tofalse
.
Response body
editThis API returns the following top level fields:
-
total
- The total number of users found.
-
count
- The number of users returned in the response.
-
users
- A list of users that match the query.
Examples
editThe following request lists all users, assuming you have the
read_security
privilege:
resp = client.perform_request( "GET", "/_security/_query/user", ) print(resp)
const response = await client.security.queryUser(); console.log(response);
GET /_security/_query/user
A successful call returns a JSON structure that contains the information retrieved from one or more users:
{ "total": 2, "count": 2, "users": [ { "username": "jacknich", "roles": [ "admin", "other_role1" ], "full_name": "Jack Nicholson", "email": "jacknich@example.com", "metadata": { "intelligence": 7 }, "enabled": true }, { "username": "sandrakn", "roles": [ "admin", "other_role1" ], "full_name": "Sandra Knight", "email": "sandrakn@example.com", "metadata": { "intelligence": 7 }, "enabled": true } ] }
If you create a user with the following details:
resp = client.security.put_user( username="jacknich", password="l0ng-r4nd0m-p@ssw0rd", roles=[ "admin", "other_role1" ], full_name="Jack Nicholson", email="jacknich@example.com", metadata={ "intelligence": 7 }, ) print(resp)
const response = await client.security.putUser({ username: "jacknich", password: "l0ng-r4nd0m-p@ssw0rd", roles: ["admin", "other_role1"], full_name: "Jack Nicholson", email: "jacknich@example.com", metadata: { intelligence: 7, }, }); console.log(response);
POST /_security/user/jacknich { "password" : "l0ng-r4nd0m-p@ssw0rd", "roles" : [ "admin", "other_role1" ], "full_name" : "Jack Nicholson", "email" : "jacknich@example.com", "metadata" : { "intelligence" : 7 } }
A successful call returns a JSON structure:
{ "created": true }
Use the user information retrieve the user with a query:
resp = client.perform_request( "POST", "/_security/_query/user", headers={"Content-Type": "application/json"}, body={ "query": { "prefix": { "roles": "other" } } }, ) print(resp)
const response = await client.security.queryUser({ query: { prefix: { roles: "other", }, }, }); console.log(response);
POST /_security/_query/user { "query": { "prefix": { "roles": "other" } } }
A successful call returns a JSON structure for a user:
{ "total": 1, "count": 1, "users": [ { "username": "jacknich", "roles": [ "admin", "other_role1" ], "full_name": "Jack Nicholson", "email": "jacknich@example.com", "metadata": { "intelligence": 7 }, "enabled": true } ] }
To retrieve the user profile_uid
as part of the response:
resp = client.perform_request( "POST", "/_security/_query/user", params={ "with_profile_uid": "true" }, headers={"Content-Type": "application/json"}, body={ "query": { "prefix": { "roles": "other" } } }, ) print(resp)
const response = await client.security.queryUser({ with_profile_uid: "true", query: { prefix: { roles: "other", }, }, }); console.log(response);
POST /_security/_query/user?with_profile_uid=true { "query": { "prefix": { "roles": "other" } } }
{ "total": 1, "count": 1, "users": [ { "username": "jacknich", "roles": [ "admin", "other_role1" ], "full_name": "Jack Nicholson", "email": "jacknich@example.com", "metadata": { "intelligence": 7 }, "enabled": true, "profile_uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0" } ] }
Use a bool
query to issue complex logical conditions and use
from
, size
, sort
to help paginate the result:
POST /_security/_query/user { "query": { "bool": { "must": [ { "wildcard": { "email": "*example.com" } }, { "term": { "enabled": true } } ], "filter": [ { "wildcard": { "roles": "*other*" } } ] } }, "from": 1, "size": 2, "sort": [ { "username": { "order": "desc"} } ] }
The email must end with |
|
The user must be enabled |
|
The result will be filtered to only contain users with at least one role that contains the substring |
|
The offset to begin the search result is the 2nd (zero-based index) user |
|
The page size of the response is 2 users |
|
The result is sorted by |
The response contains a list of matched users along with their sort values:
{ "total": 5, "count": 2, "users": [ { "username": "ray", "roles": [ "other_role3" ], "full_name": "Ray Nicholson", "email": "rayn@example.com", "metadata": { "intelligence": 7 }, "enabled": true, "_sort": [ "ray" ] }, { "username": "lorraine", "roles": [ "other_role3" ], "full_name": "Lorraine Nicholson", "email": "lorraine@example.com", "metadata": { "intelligence": 7 }, "enabled": true, "_sort": [ "lorraine" ] } ] }