getFormsDataByVectorSearch

Semantic (vector) search for form data.

Description

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

The records come back as IFormDataSearchEntity, which - unlike the IFormDataEntity returned by getFormsDataByMarker() - also carries the moderation and sender fields of the raw record (status, ip, fingerprint, isUserAdmin, userIdentifier, entityIdentifier, parentId).

FormData.getFormsDataByVectorSearch(

body*, langCode, offset, limit

);

Parameters schema

Schema

body(required): IFormsDataVectorSearch
Vector search body
example:

{ queryText: "order confirmation" }

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

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 FormData.getFormsDataByVectorSearch({ queryText: 'order confirmation' });

Example with attributes

const response = await FormData.getFormsDataByVectorSearch(
  {
    queryText: 'order confirmation',
    vectorDistanceThreshold: 0.3,
    maxHits: 50,
    debug: true,
  },
  'en_US',
  0,
  30,
);

Example response

{
  "items": [
    {
      "id": 8426,
      "formIdentifier": "test-form",
      "time": "2026-08-23T20:20:37.568Z",
      "formData": [
        {
          "marker": "name",
          "type": "string",
          "value": "Test"
        }
      ],
      "userIdentifier": "test@test.ru",
      "entityIdentifier": "blog",
      "parentId": null,
      "ip": "31.31.109.247",
      "fingerprint": "UQ_1ca96f07-cb2f-403f-850a-4c3b76c022ce",
      "isUserAdmin": false,
      "status": "sent",
      "formModuleId": 2
    },
    {
      "id": 8409,
      "formIdentifier": "test-form",
      "time": "2026-08-23T17:47:58.472Z",
      "formData": [
        {
          "marker": "name",
          "type": "string",
          "value": "Test"
        }
      ],
      "userIdentifier": null,
      "entityIdentifier": "blog",
      "parentId": null,
      "ip": "31.31.109.247",
      "fingerprint": "UQ_3c2e0387-2ceb-4b76-a64f-cb6ba0e655b2",
      "isUserAdmin": false,
      "status": "sent",
      "formModuleId": 2
    },
    {
      "id": 8392,
      "formIdentifier": "test-form",
      "time": "2026-08-23T14:37:47.250Z",
      "formData": [
        {
          "marker": "name",
          "type": "string",
          "value": "Test"
        }
      ],
      "userIdentifier": null,
      "entityIdentifier": "blog",
      "parentId": null,
      "ip": "31.31.109.247",
      "fingerprint": "UQ_125c6a79-1f43-4d42-89b0-3872fedfc9ed",
      "isUserAdmin": false,
      "status": "sent",
      "formModuleId": 2
    },
    "..."
  ],
  "total": 100
}

Response schema

Schema: IFormsDataSearchResponse

items: IFormDataSearchEntity[]
Array of found form data records.

items.id: number
The unique identifier of the form data record.
example: 12345

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

items.time: Date | string
Date and time the form data was last changed.
example: "2023-02-12 10:56"

items.formData: FormDataType[]
Data submitted by the form.
example:

[
  {
    "marker": "name",
    "type": "string",
    "value": "Test"
  }
]

items.userIdentifier: string | null
Text identifier of the user who submitted the form, or null for an anonymous submission.
example: null

items.entityIdentifier: string
Text identifier of the entity the record belongs to.
example: "blog"

items.parentId: number | null
Identifier of the parent form data record, or null for a top-level record.
example: null

items.ip: string
IP address the form was submitted from.
example: "127.0.0.1"

items.fingerprint: string
Device fingerprint of the sender.
example: "UQ_123456_abcdef"

items.isUserAdmin: boolean
Whether the record was submitted by an admin.
example: false

items.status: FormDataStatus
Moderation status of the record.
example: "sent"

items.formModuleId: number
Identifier of the form module the record belongs to.
example: 2

items.distance: number
Cosine distance to the query. Returned only 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().

---