Suggest user profile API

edit

This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.

Get suggestions for user profiles that match specified search criteria.

Request

edit

GET /_security/profile/_suggest

POST /_security/profile/_suggest

Prerequisites

edit

To use this API, you must have the manage_user_profile cluster privilege.

Query parameters

edit
data
(Optional, string) Comma-separated list of filters for the data field of the profile document. To return all content, use data=*. To return a subset of content, use data=<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 and email.
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 the data 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 of hint:
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

edit

The 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 jack for it to be included in the response.

The uids hint include profile UIDs for both user jackspa and jacknich.

The labels hint ranks profiles higher if their direction label matches either north or east.

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" : "[email protected]",
        "full_name": "Jack Nicholson"
      },
      "labels": {
        "direction": "north"
      },
      "data": {}
    },
    {
      "uid": "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
      "user": {
        "username": "jackspa",    
        "roles": [ "user" ],
        "realm_name": "native",
        "email" : "[email protected]",
        "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" : "[email protected]",
        "full_name": "Jack Reacher"
      },
      "labels": {
        "direction": "west"
      },
      "data": {}
    }
  ]
}

User jacknich is ranked highest because the profile matches both the uids and labels hints

User jackspa is ranked second because the profile matches only the uids hint

User jackrea is ranked lowest because the profile does not match any hints. However, it is not excluded from the response because it matches the name query.