getFormsDataByVectorSearch

Busca semântica (vetorial) para dados de formulários.

Descrição

Este método realiza uma busca semântica (vetorial) para dados de formulários a partir de uma consulta em linguagem natural - ele corresponde ao significado em vez de palavras-chave exatas. Retorna uma Promise que resolve para um objeto IFormsDataSearchResponse - um contêiner com items e total.

Os registros retornam como IFormDataSearchEntity, que - ao contrário do IFormDataEntity retornado por getFormsDataByMarker() - também contém os campos de moderação e remetente do registro bruto (status, ip, fingerprint, isUserAdmin, userIdentifier, entityIdentifier, parentId).

FormData.getFormsDataByVectorSearch(

body*, langCode, offset, limit

);

Esquema de parâmetros

Esquema

body(obrigatório): IFormsDataVectorSearch
Corpo da busca vetorial
exemplo:

{ queryText: "order confirmation" }

body.queryText(obrigatório): string
Consulta de busca em linguagem natural.
exemplo: "confirmação de pedido"

body.vectorDistanceThreshold: number
Substituição do limite de distância do cosseno (0..2).
exemplo: 0.3

body.maxHits: number
Candidatos Top-K buscados antes da paginação. Padrão: 100. Máx: 500.
exemplo: 10

body.debug: boolean
Quando verdadeiro, cada item retornado recebe um campo distance.
exemplo: false

langCode: string
Códig do idioma. Padrão: "en_US"
exemplo: "en_US"

offset: number
Parâmetro para paginação. Padrão: 0
exemplo: 0

limit: number
Parâmetro para paginação. Padrão: 30
exemplo: 30

Exemplos

Exemplo mínimo

const response = await FormData.getFormsDataByVectorSearch({ queryText: 'order confirmation' });

Exemplo com atributos

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

Exemplo de resposta

{
  "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
}

Esquema de resposta

Esquema: IFormsDataSearchResponse

items: IFormDataSearchEntity[]
Array de registros de dados de formulários encontrados.

items.id: number
O identificador único do registro de dados do formulário.
exemplo: 12345

items.formIdentifier: string
Identificador textual do formulário.
exemplo: "contact_form"

items.time: Date | string
Data e hora em que os dados do formulário foram alterados pela última vez.
exemplo: "2023-02-12 10:56"

items.formData: FormDataType[]
Dados submetidos pelo formulário.
exemplo:

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

items.userIdentifier: string | null
Identificador textual do usuário que submeteu o formulário, ou null para uma submissão anônima.
exemplo: null

items.entityIdentifier: string
Identificador textual da entidade à qual o registro pertence.
exemplo: "blog"

items.parentId: number | null
Identificador do registro de dados do formulário pai, ou null para um registro de nível superior.
exemplo: null

items.ip: string
Endereço IP de onde o formulário foi submetido.
exemplo: "127.0.0.1"

items.fingerprint: string
Impressão digital do dispositivo do remetente.
exemplo: "UQ_123456_abcdef"

items.isUserAdmin: boolean
Se o registro foi submetido por um administrador.
exemplo: false

items.status: FormDataStatus
Status de moderação do registro.
exemplo: "enviado"

items.formModuleId: number
Identificador do módulo de formulário ao qual o registro pertence.
exemplo: 2

items.distance: number
Distância cosseno em relação à consulta. Retornado apenas quando debug: true é passado no corpo da busca.
exemplo: 0.12

total: number
Número total de registros encontrados.
exemplo: 100

ℹ️ A busca semântica corresponde ao significado, não ao texto literal. Para correspondência de palavras-chave em todos os tipos de entidades de uma vez, use globalSearch().

---