getFormsDataByVectorSearch

Búsqueda semántica (vectorial) de datos de formularios.

Descripción

Este método realiza una búsqueda semántica (vectorial) de datos de formularios a partir de una consulta en lenguaje natural; se basa en el significado en lugar de en palabras clave exactas. Devuelve una Promesa que se resuelve en un objeto IFormsDataSearchResponse, que es un contenedor con items y total.

Los registros se devuelven como IFormDataSearchEntity, que, a diferencia del IFormDataEntity devuelto por getFormsDataByMarker(), también incluye los campos de moderación y remitente del registro original (status, ip, fingerprint, isUserAdmin, userIdentifier, entityIdentifier, parentId).

FormData.getFormsDataByVectorSearch(

body*, langCode, offset, limit

);

Esquema de parámetros

Esquema

body(required): IFormsDataVectorSearch
Cuerpo de búsqueda vectorial
ejemplo:

{ queryText: "order confirmation" }

body.queryText(required): string
Consulta de búsqueda en lenguaje natural.
ejemplo: "confirmación de pedido"

body.vectorDistanceThreshold: number
Anulación del umbral de distancia coseno (0..2).
ejemplo: 0.3

body.maxHits: number
Candidatos Top-K recuperados antes de la paginación. Predeterminado: 100. Máx: 500.
ejemplo: 10

body.debug: boolean
Cuando es verdadero, cada elemento devuelto obtiene un campo distance.
ejemplo: false

langCode: string
Código de idioma. Predeterminado: "en_US"
ejemplo: "en_US"

offset: number
Parámetro para paginación. Predeterminado: 0
ejemplo: 0

limit: number
Parámetro para paginación. Predeterminado: 30
ejemplo: 30

Ejemplos

Ejemplo mínimo

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

Ejemplo con atributos

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

Ejemplo de respuesta

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

Esquema: IFormsDataSearchResponse

items: IFormDataSearchEntity[]
Array de registros de datos de formularios encontrados.

items.id: number
El identificador único del registro de datos del formulario.
ejemplo: 12345

items.formIdentifier: string
Identificador de texto del formulario.
ejemplo: "contact_form"

items.time: Date | string
Fecha y hora en que se modificaron por última vez los datos del formulario.
ejemplo: "2023-02-12 10:56"

items.formData: FormDataType[]
Datos enviados por el formulario.
ejemplo:

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

items.userIdentifier: string | null
Identificador de texto del usuario que envió el formulario, o null para un envío anónimo.
ejemplo: null

items.entityIdentifier: string
Identificador de texto de la entidad a la que pertenece el registro.
ejemplo: "blog"

items.parentId: number | null
Identificador del registro de datos del formulario padre, o null para un registro de nivel superior.
ejemplo: null

items.ip: string
Dirección IP desde la que se envió el formulario.
ejemplo: "127.0.0.1"

items.fingerprint: string
Huella digital del dispositivo del remitente.
ejemplo: "UQ_123456_abcdef"

items.isUserAdmin: boolean
Si el registro fue enviado por un administrador.
ejemplo: false

items.status: FormDataStatus
Estado de moderación del registro.
ejemplo: "enviado"

items.formModuleId: number
Identificador del módulo de formulario al que pertenece el registro.
ejemplo: 2

items.distance: number
Distancia coseno a la consulta. Devuelto solo cuando se pasa debug: true en el cuerpo de búsqueda.
ejemplo: 0.12

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

ℹ️ La búsqueda semántica se basa en el significado, no en el texto literal. Para coincidencias de palabras clave en todos los tipos de entidades a la vez, utiliza globalSearch().

---