Saltar para o conteúdo principal
A API de Search oferece duas formas de armazenar e recuperar texto:
  • Text Store — armazenamento vetorial pré-configurado com busca híbrida, deduplicação e agrupamento. Não requer configuração de esquema ou índice.
  • Tables — acesso de baixo nível ao banco de dados vetorial com controle total sobre esquema, índices, filtros e operações de busca.
Comece pelo Text Store para a maioria dos casos de uso. Use Tables quando precisar de esquemas personalizados, gerenciamento explícito de índices ou expressões de filtro avançadas. Se você precisa de um exemplo externo que mostra GraphRAG superando recuperação plana em um benchmark definido, consulte Avaliação de GraphRAG.

​
Criar um text store

Forneça um nome e a dimensão de embedding para seus vetores. 
import { SDK } from '@meetkai/mka1';

const mka1 = new SDK({ bearerAuth: '<mka1-api-key>' });

const response = await mka1.search.textStore.createStore(
  {
    storeName: 'product_catalog',
    dimension: 3,
  },
  { headers: { 'X-On-Behalf-Of': '<end-user-id>' } }
);

​
Adicionar textos a um text store

Adicione textos com seus vetores de embedding pré-computados. Textos duplicados são ignorados automaticamente. O campo group marca as entradas para que você possa excluí-las ou recuperá-las como um conjunto posteriormente. 
const response = await mka1.search.textStore.addTexts(
  {
    storeName: 'product_catalog',
    addTextsRequest: {
      texts: [
        'Noise-cancelling over-ear headphones with 30-hour battery.',
        'Compact wireless earbuds with active noise cancellation.',
        'Studio monitor headphones with flat frequency response.',
      ],
      vectors: [
        [0.16, -0.08, 0.29],
        [0.14, -0.06, 0.31],
        [0.09, -0.12, 0.22],
      ],
      group: 'headphones',
    },
  },
  { headers: { 'X-On-Behalf-Of': '<end-user-id>' } }
);

​
Pesquisar em um text store

Passe uma consulta de texto e seu vetor de embedding. O serviço executa uma busca híbrida combinando busca textual e similaridade vetorial. 
const response = await mka1.search.textStore.search(
  {
    storeName: 'product_catalog',
    searchTextsRequest: {
      query: 'noise-cancelling headphones',
      vector: [0.16, -0.08, 0.29],
      limit: 5,
    },
  },
  { headers: { 'X-On-Behalf-Of': '<end-user-id>' } }
);

​
Excluir texto de um text store

Remova entradas específicas pelos seus valores de texto exatos. 
const response = await mka1.search.textStore.deleteTexts(
  {
    storeName: 'product_catalog',
    deleteTextsRequest: {
      texts: [
        'Studio monitor headphones with flat frequency response.',
      ],
    },
  },
  { headers: { 'X-On-Behalf-Of': '<end-user-id>' } }
);

​
Excluir textos por grupo de um text store

Remova todas as entradas que pertencem a um ou mais grupos. 
const response = await mka1.search.textStore.deleteTexts(
  {
    storeName: 'product_catalog',
    deleteTextsRequest: {
      groups: ['headphones'],
    },
  },
  { headers: { 'X-On-Behalf-Of': '<end-user-id>' } }
);

​
Excluir um text store

Remova o store e todos os seus dados. 
const response = await mka1.search.textStore.deleteStore(
  { storeName: 'product_catalog' },
  { headers: { 'X-On-Behalf-Of': '<end-user-id>' } }
);

​
Uso avançado: Tables

Tables dão acesso direto ao banco de dados vetorial subjacente. Você define o esquema, escolhe quais campos indexar, insere linhas estruturadas e compõe operações de busca manualmente.

​
Campos do esquema

Cada campo em um esquema de tabela tem um name, type e propriedades opcionais.
TipoDescriçãoSuporte a índice
stringDados de textoFTS (busca textual)
intInteiro de 32 bitsBTREE, BITMAP, LABEL_LIST
floatPonto flutuante de 64 bitsBTREE, BITMAP, LABEL_LIST
datetimeTimestamp com fuso horário opcionalBTREE
vectorEmbedding de dimensão fixaIVF_FLAT, IVF_PQ, IVF_HNSW_PQ, IVF_HNSW_SQ
listLista de strings, ints ou floats—
Defina nullable como false para campos obrigatórios. Adicione "index": "FTS" em um campo string para habilitar busca textual no momento da criação. Campos vetoriais requerem uma propriedade dimensions que corresponda ao tamanho do seu embedding.

​
Criar uma tabela de busca

Defina uma tabela com um esquema que descreva seus registros. O exemplo abaixo cria uma base de conhecimento de suporte com um campo de texto indexado para busca textual e um campo vetorial para busca semântica. 
const response = await mka1.search.tables.create(
  {
    name: 'support_kb',
    schema: {
      fields: [
        { name: 'id', type: 'string', nullable: false },
        { name: 'content', type: 'string', nullable: false, index: 'FTS' },
        { name: 'category', type: 'string', nullable: false },
        { name: 'rating', type: 'float', nullable: true },
        { name: 'embedding', type: 'vector', nullable: false, dimensions: 3 },
      ],
    },
  },
  { headers: { 'X-On-Behalf-Of': '<end-user-id>' } }
);

​
Inserir linhas

Insira registros que correspondam ao esquema da tabela. Você pode enviar múltiplas linhas em uma única requisição. 
const response = await mka1.search.tables.insertData(
  {
    tableName: 'support_kb',
    insertDataRequest: {
      data: [
        {
          id: 'doc_001',
          content: 'Reset your password from the account settings page.',
          category: 'account',
          rating: 4.7,
          embedding: [0.13, -0.09, 0.41],
        },
        {
          id: 'doc_002',
          content: 'Use two-factor authentication for added account security.',
          category: 'security',
          rating: 4.9,
          embedding: [0.07, -0.02, 0.36],
        },
      ],
    },
  },
  { headers: { 'X-On-Behalf-Of': '<end-user-id>' } }
);

​
Operações de busca

A busca em tabelas permite compor múltiplas operações em uma única requisição. As operações são executadas em ordem — comece com uma busca primária e depois refine com filtros, limites ou offsets. Operações primárias inicializam o conjunto de resultados:
OperaçãoDescrição
vector_searchEncontra linhas mais próximas de um vetor de consulta. Suporta tipos de distância cosine, l2, dot e hamming.
ftsBusca textual por palavras-chave em um ou mais campos string.
Operações secundárias refinam os resultados:
OperaçãoDescrição
filterAplica uma expressão semelhante a SQL. Defina prefilter como true para filtrar antes do ranking.
limitLimita o número de linhas retornadas.
offsetPula as primeiras N linhas para paginação.
Use returnColumns para controlar quais campos retornam na resposta.

​
Pesquisar na tabela

O exemplo abaixo combina uma busca vetorial com um pré-filtro no campo category. 
const response = await mka1.search.tables.search(
  {
    tableName: 'support_kb',
    searchRequest: {
      operations: [
        {
          type: 'vector_search',
          field: 'embedding',
          vector: [0.11, -0.06, 0.37],
          distanceType: 'cosine',
          limit: 5,
        },
        {
          type: 'filter',
          expression: "category = 'security'",
          prefilter: true,
        },
      ],
      returnColumns: ['id', 'content', 'category', 'rating'],
    },
  },
  { headers: { 'X-On-Behalf-Of': '<end-user-id>' } }
);

​
Excluir linhas

Remova linhas de uma tabela usando uma expressão de filtro. 
const response = await mka1.search.tables.deleteData(
  {
    tableName: 'support_kb',
    deleteDataRequest: {
      filter: "id IN ('doc_001', 'doc_002')",
    },
  },
  { headers: { 'X-On-Behalf-Of': '<end-user-id>' } }
);

​
Excluir uma tabela

Remova a tabela e todos os seus dados. 
const response = await mka1.search.tables.delete(
  { tableName: 'support_kb' },
  { headers: { 'X-On-Behalf-Of': '<end-user-id>' } }
);