> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuração de Indexação

> Como configurar chunking, max tokens, filtros estruturais e SLA para cada campo de uma Fonte Operacional no Knowledge.

Cada Fonte Operacional conectada ao Knowledge possui um **drawer de configuração** que define como os dados de cada campo são indexados no banco vetorial. As escolhas feitas aqui afetam diretamente a granularidade da busca semântica, o custo de embedding e o comportamento do agente ao consultar o contexto.

<Note>
  As configurações descritas nesta página são acessadas pelo ícone de engrenagem ao lado de cada Fonte Operacional na tela **Knowledge → Fontes Operacionais** do Console.
</Note>

***

## Campos indexáveis

Cada campo da fonte é listado com seu **formato** indicado por um badge ao lado do nome. O formato reflete o tipo do dado armazenado na tabela DuckDB correspondente e **não é editável pelo usuário** — ele é detectado automaticamente a partir do schema do conector.

| Badge          | Tipo do dado              | Exemplos típicos                 |
| -------------- | ------------------------- | -------------------------------- |
| **Texto**      | String plana              | `title`, `subject`, `name`       |
| **HTML**       | Markup HTML               | `description`, `body`, `content` |
| **JSON Array** | Lista serializada em JSON | `tags`, `labels`, `attachments`  |

Apenas os campos marcados como indexáveis podem ser configurados com estratégia de chunking. Campos de ID, timestamps e metadados numéricos são usados como **Filtros Estruturais** e não passam pelo pipeline de embedding.

***

## Chunking

O **chunking** define como o conteúdo de um campo é particionado antes de ser transformado em vetores. A escolha da estratégia depende do formato do campo e do tamanho típico do conteúdo.

<CardGroup cols={3}>
  <Card title="Completo" icon="rectangle-wide">
    Indexa o campo inteiro como um único chunk. Indicado para campos curtos onde preservar o texto integral é mais importante do que granularidade — como títulos, nomes de usuário ou status textuais. Evite para textos com mais de 512 tokens: o chunk excederá o limite de contexto e será truncado.
  </Card>

  <Card title="Semântico" icon="diagram-cells">
    Divide o texto em blocos menores preservando coerência semântica — parágrafos e seções são mantidos íntegros, sem cortes no meio de instruções ou argumentos. Indicado para campos HTML longos como `description` e `body`, onde fragmentos isolados mantêm significado autônomo. Esta é a estratégia padrão para campos com badge **HTML**.
  </Card>

  <Card title="Por Item" icon="list-ul">
    Para campos com badge **JSON Array**: cada elemento do array é indexado como um chunk independente. Indicado para campos como `tags`, `labels` ou `attachments`, onde cada item tem significado próprio e a busca deve ser capaz de recuperar itens individuais sem retornar o array completo.
  </Card>
</CardGroup>

### Guia de escolha por formato

| Formato do campo            | Estratégia recomendada | Observação                           |
| --------------------------- | ---------------------- | ------------------------------------ |
| Texto curto (\< 256 tokens) | Completo               | `title`, `subject`, `priority_label` |
| Texto longo ou HTML         | Semântico              | `description`, `body`, `content`     |
| JSON Array                  | Por Item               | `tags`, `labels`, `attachments`      |

<Warning>
  Usar **Completo** em campos HTML longos pode resultar em chunks acima do limite de tokens configurado. Nesses casos, o conteúdo é truncado e partes do campo ficam **fora do índice vetorial**, tornando-as inacessíveis para busca semântica.
</Warning>

***

## Max Tokens

O **Max Tokens** define o tamanho máximo de cada chunk em tokens antes da vetorização. Este parâmetro controla o trade-off entre granularidade da busca e custo de embedding.

| Valor    | Uso indicado                                                                                                                                                                   |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **256**  | Campos curtos: títulos, assuntos, labels. Chunks menores aumentam precisão em buscas por termos específicos.                                                                   |
| **512**  | Padrão para a maioria dos campos de texto. Equilibra granularidade e custo.                                                                                                    |
| **1024** | Textos longos como documentação técnica, descrições detalhadas ou corpos de e-mail. Preserva mais contexto por chunk, útil quando fragmentar o texto prejudica o entendimento. |

<Tip>
  Chunks menores aumentam a precisão da busca — o agente recebe trechos mais cirúrgicos. Chunks maiores preservam mais contexto por resultado, o que pode ser necessário quando o significado depende do parágrafo completo. Comece com 512 e ajuste com base nos resultados do Evals.
</Tip>

O Max Tokens só tem efeito prático nas estratégias **Semântico** e **Completo**. Na estratégia **Por Item**, o limite é aplicado por elemento do array.

***

## Filtros Estruturais

Os **Filtros Estruturais** são campos usados para restringir resultados durante a busca semântica — sem passar pelo pipeline de embedding. São derivados automaticamente do schema do conector e **não são editáveis**.

Exemplos típicos por conector:

| Conector | Filtros Estruturais comuns                                     |
| -------- | -------------------------------------------------------------- |
| Zendesk  | `status`, `priority`, `assignee_id`, `group_id`, `ticket_type` |
| HubSpot  | `pipeline_stage`, `owner_id`, `deal_type`                      |
| Jira     | `status`, `priority`, `assignee`, `issue_type`, `project_key`  |
| Linear   | `state`, `priority`, `assignee_id`, `team_id`, `label_ids`     |

Na busca via API, os filtros estruturais são passados como metadados para o Qdrant, permitindo que o agente restrinja a busca a subconjuntos específicos da base — por exemplo, apenas tickets com `status: open` ou deals em um `pipeline_stage` específico.

```bash theme={null}
POST /v1/knowledge/search
{
  "query": "erro de autenticação no fluxo OAuth",
  "source": "zendesk",
  "filters": {
    "status": "open",
    "priority": "high"
  },
  "top_k": 5
}
```

<Info>
  Filtros Estruturais não consomem tokens de embedding e não impactam o custo de indexação. Eles são armazenados como metadados escalares no Qdrant e usados apenas para filtragem pré-busca.
</Info>

***

## SLA (minutos)

O **SLA** define a frequência de sincronização esperada para a fonte, em minutos. Este valor não controla o agendamento da sync — ele define o **limite de tempo** após o qual o status da fonte é marcado como `em risco` no Console.

| Valor   | Interpretação                                                                                                               |
| ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `60`    | Espera-se que a fonte sincronize a cada hora. Se a última sync foi há mais de 60 minutos, o indicador muda para `em risco`. |
| `1440`  | Sincronização diária esperada (24h).                                                                                        |
| `10080` | Sincronização semanal esperada (7 dias).                                                                                    |

O status visual no Console reflete o estado atual da fonte em relação ao SLA configurado:

```
Última sync: 35 min atrás  | SLA: 60 min  →  ✅ Dentro do SLA
Última sync: 80 min atrás  | SLA: 60 min  →  ⚠️  Em risco
```

<Warning>
  Um status `em risco` indica que o contexto disponível para o agente pode estar desatualizado. Configure alertas no produto **Observability** para ser notificado quando o SLA de uma fonte for ultrapassado antes que o agente tome decisões com dados obsoletos.
</Warning>

O SLA não substitui o agendamento da sincronização, que é configurado no pipeline correspondente no **Data Pipelines**. Alinhe os dois valores para evitar falsos positivos: se o pipeline sincroniza a cada 120 minutos, defina o SLA como `120` ou superior.

***

## Tabela DuckDB

O campo **Tabela DuckDB** exibe o nome da tabela no data lake onde os dados brutos do conector são armazenados. Este campo é somente leitura e é determinado pelo pipeline de ingestão configurado no Data Pipelines.

O Knowledge Worker lê desta tabela para executar o pipeline de chunking e embedding. O formato do nome segue a convenção:

```
<schema>.<connector_slug>__<resource_name>
```

Exemplos:

| Conector | Recurso              | Tabela DuckDB               |
| -------- | -------------------- | --------------------------- |
| Zendesk  | Tickets              | `strattum.zendesk__tickets` |
| HubSpot  | Deals                | `strattum.hubspot__deals`   |
| Linear   | Issues               | `strattum.linear__issues`   |
| Postgres | Tabela personalizada | `strattum.postgres__orders` |

<Info>
  Se a tabela exibida estiver vazia ou ausente, significa que o pipeline de ingestão correspondente ainda não executou com sucesso. Verifique o status do pipeline em **Data Pipelines** antes de configurar a indexação.
</Info>

***

## Exemplo de configuração completa

A seguir, uma configuração típica para a Fonte Operacional **Zendesk Tickets**, onde o campo `description` é HTML longo e o campo `subject` é texto curto:

| Campo         | Formato    | Chunking          | Max Tokens |
| ------------- | ---------- | ----------------- | ---------- |
| `subject`     | Texto      | Completo          | 256        |
| `description` | HTML       | Semântico         | 512        |
| `tags`        | JSON Array | Por Item          | 256        |
| `status`      | —          | Filtro Estrutural | —          |
| `priority`    | —          | Filtro Estrutural | —          |
| `assignee_id` | —          | Filtro Estrutural | —          |

**SLA:** 60 minutos\
**Tabela DuckDB:** `strattum.zendesk__tickets`