Documentação do Lumo
Buscar K

Aparência

Abrir no Claude Abrir no ChatGPT

table ​

Tipo
Referência
Para
Desenvolvedor, Engenharia de dados

O arquivo tables/<slug>--<id>.yaml controla uma tabela do HorusDW: o modelo de chave e os rótulos, máscaras e descrições das colunas. Os tipos de tabela estão em tipos de tabela.

O esquema (nomes e tipos de coluna) pertence ao Dataflow que alimenta a tabela. Por isso a tabela nasce de um nó do Dataflow:

bash
lumo new table --from-flow flow:5101 --node ext_pedidos --name "fato_vendas"

Campos ​

  • fileName
    string · opcional · valores: regex ^[a-z0-9-]+--\d+\.yaml$
  • header
    object · obrigatório
  • header.id
    integer · obrigatório · valores: ≥ 1
  • header.kind
    string · obrigatório · valores: table (fixo)
  • header.lumo
    string · obrigatório · valores: v2 (fixo)
  • header.tenantId
    integer · obrigatório · valores: ≥ 1
  • header.appId
    integer · opcional · valores: ≥ 1
  • header.dashboardId
    integer · opcional · valores: ≥ 1
  • body
    object · obrigatório
  • body.criado_em
    string ou null · opcional · valores: regex ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$
    Somente leitura: o servidor preenche.
  • body.criado_por
    string ou integer ou null · opcional
    Somente leitura: o servidor preenche.
  • body.publicado_em
    string ou null · opcional · valores: regex ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$
    Somente leitura: o servidor preenche.
  • body.publicado_por
    string ou integer ou null · opcional
    Somente leitura: o servidor preenche.
  • body.nome
    string · obrigatório · valores: não vazio
  • body._state
    string · opcional · valores: draft, published, inconsistent
    Somente leitura: o servidor preenche. Derived lifecycle state. draft=deskId null (work-in-progress, owner-only). published=deskId set (live, readonly, shared). inconsistent=domain invariant violated (e.g. published flow ↔ draft table); treat as 'stop and ask'. Server-computed; edits are ignored on push.
  • body.deskId
    integer ou null · opcional · valores: ≥ 1
    Somente leitura: o servidor preenche. Server-managed publish state; change through publish commands, not declarative push.
  • body.originFlowId
    integer ou null · opcional · valores: ≥ 1
  • body.version
    integer ou null · opcional · valores: ≥ 0
    Somente leitura: o servidor preenche. Server-managed resource version.
  • body.icon
    string ou null · opcional
  • body.description
    string ou null · opcional
    Descrição da tabela, lida pela IA (dw_table.human_description).
  • body.table_type
    string · obrigatório · valores: table, file, cloud
    table=normal DW table fed by a flow's InsertDatawarehouse (Datawarehouse mode) - usable in apps. file=static, fed by Excel uploads via the DW UI, no flow - usable in apps. cloud=datalake/parquet output of InsertDatawarehouse (Datalake mode) - only consumable as an ExtractDatalake input by other flows, never inside apps.
  • body.key_type
    string · opcional · valores: duplicate, unique
    Doris key-model. duplicate=rows accumulate on every load (append-only). unique=rows sharing the same key_columns are deduplicated (last write wins / upsert). Only for Doris-backed tables (table_type table/file) - not allowed for cloud. NOTE: this is the physical key-model of the Doris table. It is the ONLY thing that dedups at rest - the InsertDatawarehouse node has no equivalent on the Doris path. Changing key_type is STRUCTURAL: it forces a destructive DROP+CREATE of the physical Doris table (rows are lost; re-run the flow to reload). lumo push refuses such a change on a table that already has data unless you pass --force-recreate.
  • body.key_columns
    array de string · opcional
    Column names that form the Doris key - the dedup key when key_type=unique, the sort/prefix key when duplicate. Each name must match a physical column (schema comes from the flow). Changing this set is STRUCTURAL - same recreate rules as key_type. Doris-backed tables only.
  • body.partition_column
    string ou null · opcional
    Column name used as the Doris partition, or null for none. Must match a physical column. Structural - changing it forces a recreate. Doris-backed tables only.
  • body.columns
    object · obrigatório
    Physical columns as a cosmetic overlay, keyed by "COLUMN_NAME (DataType)". The key is read-only identity (schema is owned by the flow); only the value fields are editable. To change column name/type/schema, clone the flow that feeds this table.
  • body.columns.<chave>.label
    string · opcional
  • body.columns.<chave>.mask
    string ou null · opcional
  • body.columns.<chave>.human_description
    string ou null · opcional
    Obsoleto.
  • body.columns.<chave>.description
    string ou null · opcional
    O que a coluna é, escrito para a IA ler: qual data é qual (emissão, vencimento, pagamento), o que um código significa, a grafia exata de um sim/não. Coluna óbvia fica sem. Gravado como human_description.
  • body.columns.<chave>.defaultBehavior
    string · opcional
  • body.columns.<chave>.semantic_role
    string ou null · opcional
    Obsoleto. Nome antigo, ainda aceito; use role. Semantic role: what the column IS. One of identificador, nome, pessoa, categoria, data, dinheiro, quantidade, saldo, medida_media, texto_livre; null clears it. Validated by the server (unknown values are ignored), so new roles need no CLI update. A role set here counts as a human choice: the AI never overwrites it.
  • body.columns.<chave>.role
    string ou null · opcional
    Role: what the column IS. One of identificador, nome, pessoa, categoria, data, dinheiro, quantidade, saldo, medida_media, texto_livre; null clears it. Validated by the server (unknown values are ignored), so new roles need no CLI update. A role set here counts as a human choice: the AI never overwrites it.
  • body.expressions
    array de object · opcional
  • body.expressions[].id
    integer · opcional · valores: ≥ 1
  • body.expressions[].label
    string · obrigatório
  • body.expressions[].data_type
    string · obrigatório · valores: Number, String, Date, Boolean, DateTime, Time, Json
  • body.expressions[].expression
    string ou null · opcional
  • body.expressions[].human_description
    string ou null · opcional
    Obsoleto.
  • body.expressions[].description
    string ou null · opcional
    O que a coluna é, escrito para a IA ler: qual data é qual (emissão, vencimento, pagamento), o que um código significa, a grafia exata de um sim/não. Coluna óbvia fica sem. Gravado como human_description.
  • body.expressions[].mask
    string ou null · opcional
  • body.expressions[].semantic_role
    string ou null · opcional
    Obsoleto. Nome antigo, ainda aceito; use role. Semantic role: what the column IS. One of identificador, nome, pessoa, categoria, data, dinheiro, quantidade, saldo, medida_media, texto_livre; null clears it. Validated by the server (unknown values are ignored), so new roles need no CLI update. A role set here counts as a human choice: the AI never overwrites it.
  • body.expressions[].role
    string ou null · opcional
    Role: what the column IS. One of identificador, nome, pessoa, categoria, data, dinheiro, quantidade, saldo, medida_media, texto_livre; null clears it. Validated by the server (unknown values are ignored), so new roles need no CLI update. A role set here counts as a human choice: the AI never overwrites it.

Exemplo ​

yaml
# tables/fato-vendas--6230.yaml
# yaml-language-server: $schema=https://docs.horusbi.com.br/schemas/v2/table.schema.json
id: 6230
kind: table
lumo: v2
tenantId: 1200
---
nome: fato_vendas
table_type: table
description: Pedidos de venda, um por linha, pela data de emissão.
# unique: linha com a mesma chave é substituída. Mudar a chave recria a tabela.
key_type: unique
key_columns: [PEDIDO_ID]
partition_column: null
# A chave de cada coluna é "NOME (Tipo)" e vem do Dataflow. Só os valores mudam.
columns:
  PEDIDO_ID (Number):
    label: Pedido
    mask: N0
    role: identificador
  CLIENTE_ID (Number):
    label: Cliente
    mask: N0
  DATA_EMISSAO (Date):
    label: Data de emissão
    role: data
  VALOR_TOTAL (Number):
    label: Valor total
    mask: MOEDA
    description: Valor do pedido já com desconto, sem frete.
    role: dinheiro

Limites ​

  • key_type, key_columns e partition_column são estruturais: mudar qualquer um apaga e recria a tabela física, e as linhas se perdem. O push recusa a mudança numa tabela com dados, a menos que você passe --force-recreate. Depois, rode o Dataflow de novo.
  • key_type: duplicate acumula linhas a cada carga. Numa carga que recarrega uma janela sem apagá-la antes, as linhas se repetem; unique substitui pela chave.
  • A chave de cada item de columns ("VALOR_TOTAL (Number)") é só identificação. Acrescentar uma chave não cria coluna. Para mudar nome ou tipo, edite o nó do Dataflow, rode o nó e dê lumo fetch table:<id>.
  • Tabela table_type: cloud (Datalake) não aceita key_type, key_columns nem partition_column.
  • Os itens de expressions não levam column_name, column_type nem display_order: o servidor deriva a identidade do label.
  • description e role de uma coluna são lidos pela IA. Papel escrito no YAML conta como escolha humana e a sugestão automática não o troca. Os nomes antigos human_description e semantic_role ainda são aceitos.
  • Valores de mask: N0 a N4 (casas decimais), MOEDA e MOEDA0 (real), MOEDA$ e MOEDA$0 (dólar), MOEDALB e MOEDALB0 (libra), PCT0 a PCT4, SEGUNDOS, MINUTOS, FILE_SIZE e NONE.
  • Tabela publicada aceita push só em rótulo, máscara, defaultBehavior, descrição e papel das colunas, e na edição de expressões que já existem. Para criar ou remover expressão, clone o Dataflow que alimenta a tabela e publique de novo.
  • Não existe clone de tabela pelo CLI: clone o Dataflow que a alimenta.