Referência de YAML

O workspace do Lumo é uma cópia espelho do tenant em arquivos YAML. Esta seção é o contrato desses arquivos: uma página por tipo de recurso, com todas as propriedades, os tipos, o que é obrigatório e o que cada restrição quebra quando você a ignora.

Toda chave documentada aqui existe nos schemas v2 que o próprio CLI usa para validar. O que não está no schema não aparece nestas páginas.

Recurso	Onde vive	Página
Flow	flows/<slug>--<id>.yaml	Flow
Tabela do DW	tables/<slug>--<id>.yaml	Table
App de BI	apps/<slug>--<id>.yaml	App
Credencial	credentials/<slug>--<id>.yaml	Credential
Agendamento	schedules/<slug>--<id>.yaml	Schedule
Desk	dw-desks/ e bi-desks/	Desk
Variáveis do tenant	variables.yaml	Variables

O formato do arquivo

Todo recurso é um arquivo com dois documentos YAML separados por ---.

id: 44531          # ─┐
kind: flow         #  │ header: identidade. imutável depois da criação.
lumo: v2           #  │
tenantId: 853      # ─┘
---
nome: Fato Vendas  # ─┐ body: o que você edita.
load_type: Total   # ─┘

O header identifica o recurso e nunca muda. O body é o conteúdo, e é o que você edita e sincroniza.

O nome do arquivo segue <slug>--<id>.yaml. O <id> no nome é o mesmo id do header. A exceção é variables.yaml, que é único no tenant e não tem id.

Autocomplete e validação no editor

Cole a linha do schema no topo do arquivo. Editores com YAML Language Server, como VS Code, passam a completar as chaves, mostrar os tipos e sublinhar o que estiver errado antes de você dar push.

# yaml-language-server: $schema=https://docs.horusbi.com.br/schemas/v2/flow.schema.json

Troque flow pelo kind do arquivo. Os schemas servidos:

• flow.schema.json
• table.schema.json
• app.schema.json
• app-dashboard.schema.json
• credential.schema.json
• schedule.schema.json
• dw-desk.schema.json
• bi-desk.schema.json
• variables.schema.json

O mesmo contrato roda localmente:

lumo lint                # valida o workspace inteiro
lumo lint flows/fato-vendas--44531.yaml

Como ler as páginas

Cada página tem três camadas.

1. Modelo de configuração. O esqueleto com todas as chaves, o tipo de cada uma e a restrição ao lado dela.
2. Configuração completa. Um exemplo que funciona, com o nome do arquivo declarado e as pegadinhas comentadas onde elas acontecem.
3. Especificação. Uma seção por propriedade, com tipo, obrigatoriedade, default e exemplo.

Descobrir o que já existe

O CLI imprime o modelo de qualquer recurso, direto do binário:

lumo scaffold flow                 # flow genérico
lumo scaffold flow postgresql      # flow de extração PostgreSQL
lumo scaffold node Join            # fragmento de um nó, com as options comentadas
lumo scaffold credential --variant postgres

E lista o que o tenant já tem, com os ids que você vai precisar referenciar:

lumo list flow
lumo list table
lumo list credential               # a chave da credencial, usada nos nós de extração
lumo columns table:44940           # os ids de coluna, usados em relationships e facts