Datasets
Schema tipado, normalização, campos calculados, evolução do schema e consulta de registros.
Um dataset é uma base de registros com schema fixo. Os tipos e as normalizações são aplicados uma vez, na ingestão, e as regras de conciliação são validadas contra esse schema antes de cada job.
Criar um dataset
curl -s -X POST https://nexus-v2.openi.com.br/v1/datasets \
-H "Authorization: Bearer $NEXUS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"name": "notas-fiscais",
"external_id": "numero_nf",
"fields": [
{"name": "numero_nf", "type": "string", "required": true},
{"name": "doc_tomador", "type": "string", "required": true, "normalize": ["digits"], "index": true},
{"name": "razao_social", "type": "string", "normalize": ["trim", "upper", "unaccent"]},
{"name": "valor", "type": "decimal", "scale": 2, "required": true},
{"name": "vencimento", "type": "date", "required": true}
],
"computed": [
{"name": "doc_raiz", "from": "doc_tomador", "normalize": ["cnpj_root"], "index": true}
]
}'| Atributo | Regra |
|---|---|
name | Único no tenant. Letras minúsculas, dígitos, - e _, começando por letra ou dígito, até 100 caracteres |
external_id | Nome do campo que identifica cada registro. Precisa ser um campo string ou integer obrigatório |
fields | Pelo menos um campo. Nomes em minúsculas, dígitos e _, começando por letra, até 63 caracteres |
computed | Opcional. Campos derivados de um campo string (ver Campos calculados) |
Um dataset tem no máximo 200 campos, somando fields e computed.
Tipos
type | Na ingestão | Nas regras (CEL) |
|---|---|---|
string | Texto | string |
integer | Número inteiro ou string com dígitos (64 bits) | int |
decimal | Número ou string com ponto decimal, sem separador de milhar, com no máximo scale casas: "1234.56". Nada é arredondado | int, em unidades mínimas (100.50 com scale: 2 vira 10050) |
boolean | true/false, ou as strings "true", "false", "1", "0" | bool |
date | YYYY-MM-DD | timestamp |
timestamp | RFC 3339 com fuso: 2026-09-24T15:04:05-03:00 | timestamp |
decimal exige scale (0 a 9). O valor é guardado como inteiro em unidades mínimas, então somas e comparações de dinheiro são exatas. Nas regras, tolerâncias de valor também são em unidades mínimas: closeness(left.valor, right.valor, 100) tolera R$ 1,00 com scale: 2.
Normalização
normalize vale só para campos string e aplica as operações na ordem da lista, uma vez, na ingestão. O valor gravado (e visto pelas regras e pela API) já é o normalizado.
| Operação | Efeito | Exemplo |
|---|---|---|
trim | Remove espaços nas pontas | " ACME " → "ACME" |
upper | Maiúsculas | "Acme" → "ACME" |
lower | Minúsculas | "Acme" → "acme" |
unaccent | Remove acentos | "José" → "Jose" |
digits | Mantém só dígitos | "12.345.678/0001-90" → "12345678000190" |
alnum | Mantém só letras e dígitos | "NF-001/A" → "NF001A" |
cnpj_root | Raiz do CNPJ: os 8 primeiros caracteres alfanuméricos, em maiúsculas | "12.345.678/0001-90" → "12345678" |
Normalize as chaves de comparação na ingestão, e não nas regras: dois documentos só casam por igualdade se chegarem ao mesmo formato.
Campos calculados
Um campo em computed é derivado de um campo string (from) com uma lista de normalizações, e é sempre string. Use para ter duas formas do mesmo dado: o documento completo e a raiz do CNPJ, por exemplo. O Nexus preenche o campo calculado a partir do campo de origem. Não envie campos calculados na ingestão: eles são rejeitados como campo fora do schema.
Índices
index: true cria um índice no campo. Marque os campos usados como chave de blocking e de group_by na composição; eles definem quais registros o job carrega e compara.
Evoluir o schema
O schema só cresce. PATCH /v1/datasets/{id} renomeia o dataset e adiciona campos, sempre opcionais:
curl -s -X PATCH https://nexus-v2.openi.com.br/v1/datasets/<id> \
-H "Authorization: Bearer $NEXUS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"add_fields": [{"name": "centro_custo", "type": "string", "normalize": ["upper"]}]}'Campos existentes não mudam de tipo nem são removidos, e registros já carregados ficam com o campo novo vazio. Para mudar a estrutura, crie outro dataset.
Registros
Registros são imutáveis: uma vez carregados, não são alterados nem apagados pela API. Carregar de novo o mesmo external_id não sobrescreve o registro (ver duplicados).
Listar
GET /v1/datasets/{id}/records lista na ordem de carga, com filtros combinados por E:
| Parâmetro | Filtra |
|---|---|
q | Prefixo do external_id, sem diferenciar maiúsculas |
filter | campo:operador:valor. Pode repetir |
state | open (sem match efetivo) ou reconciled (com match efetivo). Com ruleset_id, considera só aquele ruleset; sem, qualquer ruleset |
ingestion_id | Só os registros carregados por uma ingestão |
ingested_from, ingested_to | Dia da carga, YYYY-MM-DD, inclusivos |
Operadores de filter:
| Operador | Tipos | Exemplo |
|---|---|---|
eq, ne | Todos | status:eq:EMITIDA |
contains, prefix | string, sem diferenciar maiúsculas | razao_social:contains:acme |
gt, gte, lt, lte | integer, decimal, date, timestamp | valor:gte:1000.00 |
empty, present | Todos | centro_custo:empty |
curl -s -G https://nexus-v2.openi.com.br/v1/datasets/<id>/records \
-H "Authorization: Bearer $NEXUS_API_KEY" \
--data-urlencode 'filter=vencimento:gte:2026-09-01' \
--data-urlencode 'filter=valor:gt:500' \
--data-urlencode 'state=open'{
"data": [
{
"id": 184467,
"external_id": "NF-1",
"ingestion_id": 912,
"ingested_on": "2026-10-08",
"values": {
"numero_nf": "NF-1",
"doc_tomador": "12345678000190",
"razao_social": "ACME LTDA",
"valor": "100.50",
"vencimento": "2026-09-30",
"doc_raiz": "12345678"
}
}
],
"next_cursor": 184467,
"total": 1342
}Detalhar
GET /v1/datasets/{id}/records/{record_id} devolve o registro e todos os matches de que ele participa, em qualquer ruleset e status.
Datasets derivados
Datasets com kind: "derived" são criados por etapas de workflow que projetam seus matches. Eles têm source_job_id e expiram em 30 dias (expires_at).
Retenção
Registros ficam disponíveis por 13 meses, contados pelo mês de carga, e matches por 13 meses a partir do mês em que foram criados. Depois disso, o mês inteiro é arquivado e sai da API. record_count conta só os registros ainda disponíveis.

