App

Um app é uma aplicação de BI. Ele vive em apps/<slug>--<id>.yaml e reúne as tabelas do DW que o app enxerga, os relacionamentos entre elas, as expressões calculadas e os indicadores que ensinam a IA a responder sobre os dados.

O app não carrega dados. Crie antes os flows e as tabelas do DW, depois o app:

bash

lumo new app --name "Comercial"

Ligue o autocomplete no editor colando esta linha no topo do arquivo:

yaml

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

Os dashboards e os widgets moram em arquivos próprios, com kind: app-dashboard, validados pelo app-dashboard.schema.json. Esta página cobre o app.

Modelo de configuração

yaml

# ── header ────────────────────────────────────────────────
id: integer                        # obrigatório, >= 1
kind: app                          # obrigatório, literal "app"
lumo: v2                           # obrigatório, literal "v2"
tenantId: integer                  # obrigatório, >= 1
---
# ── body ──────────────────────────────────────────────────
nome: string                       # obrigatório, mínimo 1 caractere
descricao: string | null
icon: string | null
color: string | null               # hex: #RGB, #RRGGBB ou #RRGGBBAA
tags: [string]

config:                            # obrigatório
  show_last_loadedat: boolean      # exibe a data da última carga
  show_last_loadedat_tables: [integer]   # ids de tabela consideradas

tables:                            # tabelas do DW que o app enxerga
  - tableId: integer               # obrigatório
    tipo: string | null            # dimension | n2n | null. default: dimension
    nome_visualizacao: string | null   # renomeia a tabela SÓ neste app
    guid: string | null
    columns:                       # overlay por coluna, só neste app
      NOME_DA_COLUNA:
        visible: boolean           # false esconde do gerador de relatórios
        label: string | null       # renomeia a coluna só neste app

relationships:
  - from_table_id: integer         # obrigatório
    to_table_id: integer           # obrigatório
    column_left_id: integer        # obrigatório
    column_right_id: integer       # obrigatório
    relationshipType: string       # obrigatório: ONE_TO_ONE | ONE_TO_MANY | MANY_TO_ONE | MANY_TO_MANY
    from_column: string
    to_column: string
    ignoreTime: boolean            # ignora a hora ao casar colunas de data

facts:                             # indicadores (dicionário de negócio da IA)
  - nome: string                   # obrigatório
    primaryColumn: string          # obrigatório, formato "<columnId>:<AGREGACAO>"
    alternativeColumns: [string] | null
    dateColumnId: integer | null
    prompt: string | null
    filters: []

expressions: []                    # colunas calculadas do app
filtros: []                        # filtros pré-aplicados
dynamic_dimensions: []

tables[].tipo é legado do motor de BI: dimension cobre toda tabela normal, tanto fato quanto dimensão. Use n2n apenas em tabelas ponte de muitos-para-muitos. Os valores fact, dim e bridge não existem, e o servidor rejeita.

Configuração completa

yaml

# apps/comercial--13044.yaml
# yaml-language-server: $schema=https://docs.horusbi.com.br/schemas/v2/app.schema.json
id: 13044
kind: app
lumo: v2
tenantId: 853
---
nome: Comercial
descricao: Vendas por cliente, produto e região.
icon: mdi:chart-bar
color: "#10b981"

config:
  show_last_loadedat: true
  show_last_loadedat_tables: [44940]

tables:
  # Toda tabela normal usa tipo: dimension, inclusive a tabela fato.
  - tableId: 44940
    tipo: dimension
    columns:
      # visible: false só tira a coluna do gerador de relatórios do usuário
      # final. Ela continua utilizável em expressões e widgets: isso é
      # limpeza de interface, não controle de acesso.
      PEDIDO_ID:
        visible: false
  - tableId: 44650
    tipo: dimension
  - tableId: 44892
    tipo: dimension
    # Renomeia a tabela SÓ neste app. Depois disso, expressões e dataSources
    # precisam endereçá-la por este nome: [Vendedor]."NOME", não pelo nome
    # físico do DW.
    nome_visualizacao: Vendedor

relationships:
  # A dimensão calendário liga em muitos registros do fato.
  - from_table_id: 44650
    from_column: DATA
    column_left_id: 821860
    to_table_id: 44940
    to_column: DATA_EMISSAO
    column_right_id: 761306
    relationshipType: ONE_TO_MANY
    # A coluna do fato é DateTime e a do calendário é Date. Sem ignoreTime,
    # nenhuma linha casa.
    ignoreTime: true

  - from_table_id: 44892
    from_column: CLIENTE_ID
    column_left_id: 807839
    to_table_id: 44940
    to_column: CLIENTE_ID
    column_right_id: 761309
    relationshipType: ONE_TO_MANY
    ignoreTime: false

facts:
  # Os ids de coluna saem de: lumo info app:13044 --full
  - nome: Faturamento
    primaryColumn: "761310:SUM"
    dateColumnId: 761306
    prompt: >-
      Valor total vendido no período, somando o valor líquido dos itens.
      Agrupar por Cliente ou Produto para ver a concentração da carteira.
    filters: []

  - nome: Clientes Ativos
    primaryColumn: "761309:DCOUNT"
    dateColumnId: 761306
    prompt: Quantidade de clientes distintos com pedido no período.
    filters: []

tags: [comercial]

Especificação: header

`id`

Tipo: integer (>= 1) · Obrigatório: sim

`kind`

Tipo: string · Obrigatório: sim · Valor: app

`lumo`

Tipo: string · Obrigatório: sim · Valor: v2

`tenantId`

Tipo: integer (>= 1) · Obrigatório: sim

Especificação: body

`nome`

Tipo: string (mínimo 1 caractere) · Obrigatório: sim

Nome do app.

`config`

Tipo: object · Obrigatório: sim

Configuração de exibição do app.

Campo	Tipo	O que faz
`show_last_loadedat`	boolean	Exibe no app a data da última carga.
`show_last_loadedat_tables`	array de integer	Ids das tabelas consideradas nessa data.

yaml

config:
  show_last_loadedat: true
  show_last_loadedat_tables: [44940]

`descricao`

Tipo: string ou null · Obrigatório: não

`icon`

Tipo: string ou null · Obrigatório: não

Ícone do app, no formato conjunto:nome, como mdi:chart-bar.

`color`

Tipo: string ou null · Obrigatório: não · Formato: hex #RGB, #RRGGBB ou #RRGGBBAA

Cor de destaque do app. Qualquer outro formato é rejeitado.

yaml

color: "#10b981"

`tables`

Tipo: array de objetos · Obrigatório: não

Tabelas do DW que o app enxerga. Cada item exige tableId. Veja Especificação: table.

Uma tabela com table_type: cloud não pode entrar num app.

`relationships`

Tipo: array de objetos · Obrigatório: não

Ligações entre as tabelas do app. Veja Especificação: relationship.

`facts`

Tipo: array de objetos · Obrigatório: não

Indicadores: dicionário de negócio que a IA usa e que aparecem no cockpit de Indicadores. Veja Especificação: indicador.

`expressions`

Tipo: array · Obrigatório: não · Default: []

Colunas calculadas no escopo do app.

`filtros`

Tipo: array · Obrigatório: não · Default: []

Filtros pré-aplicados quando o app abre.

`dynamic_dimensions`

Tipo: array · Obrigatório: não · Default: []

`tags`

Tipo: array de string · Obrigatório: não · Default: []

Especificação: table

Cada item de tables.

`tableId`

Tipo: integer (>= 1) · Obrigatório: sim

Id da tabela do DW. Liste com lumo list table.

`tipo`

Tipo: string ou null · Obrigatório: não · Valores: dimension, n2n, null · Default: dimension

Papel da tabela dentro do app. O nome é legado do motor de BI e não corresponde ao conceito de star schema: dimension cobre toda tabela normal, tanto o fato de vendas quanto a dimensão de clientes. Reserve n2n para tabelas ponte de muitos-para-muitos.

`nome_visualizacao`

Tipo: string ou null · Obrigatório: não · Default: null

Renomeia a tabela apenas neste app. Tem efeito semântico: uma vez definido, expressões e dataSources precisam endereçar a tabela por este nome, na forma [Vendedor]."COLUNA", e não mais pelo nome físico do DW.

Omitir o campo mantém o nome físico. Omitir num push apaga um rename anterior, porque o arquivo é a verdade.

`columns`

Tipo: object · Obrigatório: não

Overlay por coluna, no escopo deste app. Chaveado por nome de coluna. Liste as colunas com lumo columns table:<id>.

Campo	Tipo	O que faz
`visible`	boolean	`false` esconde a coluna do gerador de relatórios do usuário final. A coluna continua utilizável em expressões e widgets. Serve para limpar a interface, e não para controlar acesso.
`label`	string ou null	Renomeia a coluna apenas neste app.

Liste apenas as colunas que fogem do padrão. Omitir columns preserva o overlay atual, e {} apaga todos os overrides. Só funciona em app em rascunho.

`guid`

Tipo: string ou null · Obrigatório: não

`appTableId`

Tipo: integer ou null · Obrigatório: não

Id da associação entre app e tabela, atribuído pelo servidor.

Especificação: relationship

Cada item de relationships.

`from_table_id`

Tipo: integer (>= 1) · Obrigatório: sim

Tabela de origem.

`to_table_id`

Tipo: integer (>= 1) · Obrigatório: sim

Tabela de destino.

`column_left_id`

Tipo: integer (>= 1) · Obrigatório: sim

Id da coluna de origem. Descubra com lumo columns table:<id>.

`column_right_id`

Tipo: integer (>= 1) · Obrigatório: sim

Id da coluna de destino.

`relationshipType`

Tipo: string · Obrigatório: sim · Valores: ONE_TO_ONE, ONE_TO_MANY, MANY_TO_ONE, MANY_TO_MANY

Cardinalidade. Uma dimensão ligando ao fato é ONE_TO_MANY.

`from_column`

Tipo: string · Obrigatório: não

Nome da coluna de origem.

`to_column`

Tipo: string · Obrigatório: não

Nome da coluna de destino.

`ignoreTime`

Tipo: boolean · Obrigatório: não · Default: false

Ignora a hora ao casar duas colunas de data. Ligue quando a coluna do fato for DateTime e a do calendário for Date. Sem isso, nenhuma linha casa.

Especificação: indicador (`facts`)

A chave YAML continua facts por herança do nome interno, mas o produto chama esse conceito de Indicador: cada item ensina a IA a mapear um termo de negócio para a coluna, a agregação e os filtros corretos, e controla como o indicador aparece no cockpit de Indicadores. Para o conceito do ponto de vista de quem usa a aplicação, veja Indicadores e Monitoramento: o vigia.

Um bloco ausente preserva o que está gravado no servidor. Um bloco presente é o estado desejado: uma chave omitida dentro dele remove o valor correspondente. A regra vale para apresentacao e monitoramento; meta é a exceção, descrita no campo dela.

`nome`

Tipo: string (mínimo 1 caractere) · Obrigatório: sim

O termo que o usuário fala, como Faturamento ou Clientes Ativos.

`primaryColumn`

Tipo: string · Obrigatório: sim · Formato: <columnId>:<AGREGACAO>

Coluna e agregação que respondem pelo indicador. Agregações: SUM, COUNT, AVG, MIN, MAX, DCOUNT. Os ids de coluna saem de lumo info app:<id> --full.

yaml

primaryColumn: "761310:SUM"

`alternativeColumns`

Tipo: array de string ou null · Obrigatório: não

Métricas relacionadas, que compartilham os mesmos filtros e a mesma data. Mesmo formato de primaryColumn.

`dateColumnId`

Tipo: integer ou null · Obrigatório: não

Coluna de data que o indicador usa para filtrar período.

`prompt`

Tipo: string ou null · Obrigatório: não

Contexto extra para a IA. Explique o que o conceito significa no negócio e como cortá-lo.

`filters`

Tipo: array · Obrigatório: não · Default: []

Filtros sempre aplicados ao indicador.

`defaultDatePeriod`

Tipo: string ou null · Obrigatório: não

Um destes 14 valores: Today, CurrentMonth, MonthToDate, PreviousMonth, Yesterday, CurrentYear, NextYear, DayBeforeYesterday, AllTime, PreviousYear, ThisWeek, PreviousWeek, NextWeek, Last7Days.

`apresentacao`

Tipo: object · Obrigatório: não

Como o indicador aparece no cockpit: ícone, cor, formato do número e direção de leitura. Nada aqui muda uma resposta da IA no chat.

Campo	Tipo	O que faz
`icone`	string ou null	Ícone do indicador, no formato `conjunto:nome`, como `ph:hand-coins`.
`cor`	string ou null	Cor de destaque do indicador, em hex, como `#2E7D32`.
`formato`	string ou null	`currency`, `percent`, `integer` ou `decimal`.
`direcao`	string ou null	Sentido que representa melhora: `up_good`, `down_good` ou `neutral`. Custo e inadimplência usam `down_good`.

yaml

apresentacao:
  icone: "ph:hand-coins"
  cor: "#2E7D32"
  formato: currency
  direcao: up_good

`monitoramento`

Tipo: object · Obrigatório: não

Grão da série, janela de histórico e farol de alerta do indicador. Mesma semântica de bloco de apresentacao.

Campo	Tipo	O que faz
`grao`	string ou null	Granularidade da série: `hour`, `day`, `week` ou `month`.
`janelaDias`	integer ou null	Dias de histórico mantidos, de 1 a 1095.
`farol`	string (`auto`) ou object	`auto` aplica uma banda estatística aprendida a partir do histórico. Para faixa manual, um objeto com `verde` e `ambar` juntos, em percentual: `{ verde: 5, ambar: 10 }`. `verde` precisa ser menor que `ambar`. O `lumo lint` não verifica essa ordem: um farol invertido passa validado e só aparece errado depois, no cockpit.

yaml

monitoramento:
  farol:
    verde: 5
    ambar: 10

`meta`

Tipo: number ou null · Obrigatório: não · Faixa: maior que 0 e menor que 1e14

Valor-alvo do indicador, para o período em defaultDatePeriod. Uma meta por indicador; trocar o período desvincula a meta anterior.

Exige dateColumnId preenchido no mesmo indicador quando meta é um número. Com meta: null essa exigência não vale.

meta não segue a semântica de bloco acima: é um campo solto. Ausente preserva o valor gravado, e null é a única forma de apagá-lo. Omitir a chave não apaga nada.

Seguir, fixar, notificar e promover um indicador são ações da pessoa usuária no cockpit, não do CLI. O CLI cria e mantém o indicador curado; o resto acontece na aplicação.

Campos gerenciados pelo servidor

Campo	O que é
`_state`	`draft`, `published` ou `inconsistent`.
`deskId`	Desk em que o app foi publicado. Mude com `lumo app publish`.
`version`	Versão do recurso.
`criado_em`, `criado_por`, `publicado_em`, `publicado_por`	Auditoria.

App ​

Modelo de configuração ​

Configuração completa ​

Especificação: header ​

id ​

kind ​

lumo ​

tenantId ​

Especificação: body ​

nome ​

config ​

descricao ​

icon ​

color ​

tables ​

relationships ​

facts ​

expressions ​

filtros ​

dynamic_dimensions ​

tags ​

Especificação: table ​

tableId ​

tipo ​

nome_visualizacao ​

columns ​

guid ​

appTableId ​

Especificação: relationship ​

from_table_id ​

to_table_id ​

column_left_id ​

column_right_id ​

relationshipType ​

from_column ​

to_column ​

ignoreTime ​

Especificação: indicador (facts) ​

nome ​

primaryColumn ​

alternativeColumns ​

dateColumnId ​

prompt ​

filters ​

defaultDatePeriod ​

apresentacao ​

monitoramento ​

meta ​

Campos gerenciados pelo servidor ​

App

Modelo de configuração

Configuração completa

Especificação: header

`id`

`kind`

`lumo`

`tenantId`

Especificação: body

`nome`

`config`

`descricao`

`icon`

`color`

`tables`

`relationships`

`facts`

`expressions`

`filtros`

`dynamic_dimensions`

`tags`

Especificação: table

`tableId`

`tipo`

`nome_visualizacao`

`columns`

`guid`

`appTableId`

Especificação: relationship

`from_table_id`

`to_table_id`

`column_left_id`

`column_right_id`

`relationshipType`

`from_column`

`to_column`

`ignoreTime`

Especificação: indicador (`facts`)

`nome`

`primaryColumn`

`alternativeColumns`

`dateColumnId`

`prompt`

`filters`

`defaultDatePeriod`

`apresentacao`

`monitoramento`

`meta`

Campos gerenciados pelo servidor