Suggest user profile API
editSuggest user profile API
editThe user profile feature is designed only for use by Kibana and Elastic’s Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice.
Get suggestions for user profiles that match specified search criteria.
Prerequisites
editTo use this API, you must have at least the read_security
cluster privilege (or a greater privilege
such as manage_user_profile
or manage_security
).
Query parameters
edit-
data
-
(Optional, string) Comma-separated list of filters for the
data
field of the profile document. To return all content, usedata=*
. To return a subset of content, usedata=<key>
to retrieve the content nested under the specified<key>
. Defaults to returning no content.
Request body
edit-
name
-
(Optional, string)
Query string used to match name-related fields in user profile documents. Name-related fields are the user’s
username
,full_name
andemail
. -
size
-
(Optional, integer)
Number of profiles to return. Defaults to
10
. -
data
-
(Optional, string)
Comma-separated list of filters for the
data
field of the profile document. It works the same way as thedata
query parameter.
It is an error to specify data
as both the query parameter and the request body field.
-
hint
-
(Optional, object) Extra search criteria to improve relevance of the suggestion result. A profile matching the specified hint is ranked higher in the response. But not-matching the hint does not exclude a profile from the response as long as it matches the
name
field query.Properties ofhint
:-
uids
- (Optional, list of strings) A list of Profile UIDs to match against.
-
labels
-
(Optional, object)
A single key-value pair to match against the
labels
section of a profile. The key must be a string and the value must be either a string or a list of strings. A profile is considered matching if it matches at least one of the strings.
-
Response body
edit-
total
- (object) Metadata about the number of matching profiles.
-
took
- (integer) Milliseconds it took Elasticsearch to execute the request.
-
profiles
- (array of objects) List of profile documents, ordered by relevance, that match the search criteria.
Examples
editThe following request get suggestions for profile documents with name-related fields
matching jack
. It specifies both uids
and labels
hints for better relevance:
POST /_security/profile/_suggest { "name": "jack", "hint": { "uids": [ "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0", "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0" ], "labels": { "direction": ["north", "east"] } } }
A profile’s name-related fields must match |
|
The |
|
The |
The API returns:
{ "took": 30, "total": { "value": 3, "relation": "eq" }, "profiles": [ { "uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0", "user": { "username": "jacknich", "roles": [ "admin", "other_role1" ], "realm_name": "native", "email" : "jacknich@example.com", "full_name": "Jack Nicholson" }, "labels": { "direction": "north" }, "data": {} }, { "uid": "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0", "user": { "username": "jackspa", "roles": [ "user" ], "realm_name": "native", "email" : "jackspa@example.com", "full_name": "Jack Sparrow" }, "labels": { "direction": "south" }, "data": {} }, { "uid": "u_P_0BMHgaOK3p7k-PFWUCbw9dQ-UFjt01oWJ_Dp2PmPc_0", "user": { "username": "jackrea", "roles": [ "admin" ], "realm_name": "native", "email" : "jackrea@example.com", "full_name": "Jack Reacher" }, "labels": { "direction": "west" }, "data": {} } ] }
User |
|
User |
|
User |