getUsersByVectorSearch

Semantic (vector) search for users. 🔐 This method requires authorization.

Description

This method performs a semantic (vector) search for users from a natural-language query - it matches on meaning rather than exact keywords. It returns a Promise that resolves to an IUsersResponse object - a container with items (the users) and total.

Users.getUsersByVectorSearch(

body*, langCode, offset, limit

);

Parameters schema

Schema

body(required): IUsersVectorSearch
Vector search body
example:

{ queryText: "john" }

body.queryText(required): string
Natural-language search query.
example: "john"

body.vectorDistanceThreshold: number
Override of the cosine distance threshold (0..2).
example: 0.3

body.maxHits: number
Top-K candidates fetched before pagination. Default: 100. Max: 500.
example: 10

body.debug: boolean
When true, each returned item gets a distance field.
example: false

langCode: string
Language code. Default: "en_US"
example: "en_US"

offset: number
Parameter for pagination. Default: 0
example: 0

limit: number
Parameter for pagination. Default: 30
example: 30

Examples

Minimal example

const response = await Users.getUsersByVectorSearch({ queryText: 'john' });

Example with attributes

const response = await Users.getUsersByVectorSearch(
  {
    queryText: 'john',
    vectorDistanceThreshold: 0.3,
    maxHits: 50,
    debug: true,
  },
  'en_US',
  0,
  30,
);

Example response

{
  "items": [
    {
      "id": 8,
      "total": "1",
      "identifier": "test@test.ru",
      "authProviderIdentifier": "email",
      "formData": [
        {
          "marker": "name_reg",
          "type": "string",
          "value": "Ivan"
        },
        {
          "marker": "phone_reg",
          "type": "string",
          "value": "+19258382556"
        }
      ],
      "formIdentifier": "reg",
      "groups": [
        1
      ],
      "state": {},
      "rating": {},
      "moduleFormConfigs": []
    }
  ],
  "total": 1
}

Response schema

Schema: IUsersResponse

items: IUserEntity[]
Array of found user objects.

items.id: number
Object identifier.
example: 12345

items.identifier: string
Text identifier for record field.
example: "user_12345"

items.authProviderIdentifier: string
Text identifier of the authentication provider.
example: "auth_provider_12345"

items.formData: FormDataType[]
Array of data form objects with the following values.
example:

[
  {
    "marker": "last_name",
    "type": "string",
    "value": "Username"
  }
]

items.formIdentifier: string
Text identifier of the form.
example: "form_12345"

items.total: string
Total value.
example: "0"

items.groups: Array<string | number>
Array of user groups.
example:

[
  "group_1",
  "group_2"
]

items.state: object
Object containing additional user state information.
example:

{
  "key": "value"
}

items.moduleFormConfigs: Array<IFormConfig>
Optional array of form configuration objects associated with the user.

items.rating: IRating
Rating data.

items.distance: number
Cosine distance to the query. Returned only by the semantic (vector) search endpoint when debug: true is passed in the search body.
example: 0.12

total: number
Total number of found records.
example: 100

ℹ️ Semantic search matches on meaning, not on the literal text. For keyword matching across every entity type at once use globalSearch().

---