Documentação Orbi

Consultas SQL e TOTVS RM

O Orbi pode importar dados de uma consulta SQL — seja uma consulta cadastrada no TOTVS RM, seja uma conexão SQL — e a mesma consulta pode trazer, de uma vez, indicadores, medições e metas. O que define isso é o formato do retorno: o Orbi olha para os nomes das colunas de cada linha.

Esta página descreve exatamente como esse retorno precisa ser.

A ideia central: a coluna kind

Cada linha do resultado é classificada por uma coluna kind, que diz o que aquela linha representa:

kind O que a linha cria/atualiza
measurement uma medição (um ponto na série do indicador) — é o padrão se kind for omitido
indicator a definição de um indicador (nome, unidade, direção…)
target uma meta do indicador num período (valor-alvo + limiares)

Você pode ter uma consulta só devolvendo linhas de tipos diferentes, ou uma consulta por tipo — o que for mais simples de manter.

Em todas as linhas, a coluna key identifica o indicador (o mesmo key usado no protocolo).

Nomes das colunas: maiúsculas e prefixo ORBI_

O Orbi reconhece os nomes de coluna de forma insensível a maiúsculas/minúsculas e aceita um prefixo ORBI_ opcional. Ou seja, todas estas formas são equivalentes e mapeiam para o campo key:

key        KEY        Key        orbi_key        ORBI_KEY

O mesmo vale para as dimensões: dim_filial, DIM_FILIAL e ORBI_DIM_FILIAL viram, todas, a dimensão filial (o nome da dimensão é sempre normalizado para minúsculas).

Quando usar o prefixo ORBI_ (recomendado no TOTVS RM e no Oracle):

  • Oracle devolve os nomes de coluna em MAIÚSCULAS quando você não usa aspas (SELECT vlr AS value vira a coluna VALUE). Sem o reconhecimento case-insensitive isso quebraria; com o prefixo ORBI_ fica explícito.
  • key, value e kind são palavras reservadas em SQL. Em vez de escapá-las (AS [key] no SQL Server, AS "key" no Oracle), use AS ORBI_KEY — sem aspas, sem colisão.
  • O prefixo separa as colunas do protocolo das colunas de dados da própria sentença. Se a sua consulta já tem uma coluna chamada value (de negócio) e você precisa enviar outra para o Orbi, use ORBI_VALUE: quando as duas formas aparecem na mesma linha, a prefixada vence.

Nas tabelas abaixo, cada coluna <nome> aceita também a forma ORBI_<NOME>.

Colunas por tipo

measurement (medição)

Coluna Obrigatória Descrição
key sim identificador do indicador (ex.: fin.receita)
value sim o número medido
ts sim data/hora da medição (ver Datas e fuso)
external_ref não chave de idempotência (ver Reprocessar)
dim_<nome> não uma dimensão (recorte). Ex.: dim_filial vira a dimensão filial

indicator (definição)

Coluna Obrigatória Descrição
key sim identificador do indicador
name não nome de exibição
unit não count, currency_brl, percent, ms, ratio
value_type não integer, decimal, percent, duration_ms, money
direction não up_is_better, down_is_better, neutral
aggregation não sum, avg, last, min, max
default_period não minute, hour, day, week, month

Declarar o indicador é opcional: se uma medição chegar com um key novo, o indicador é criado automaticamente (em estado descoberto) para você revisar.

target (meta)

Coluna Obrigatória Descrição
key sim indicador a que a meta pertence
period_start sim início do período (AAAA-MM-DD)
period_end sim fim do período (AAAA-MM-DD)
target_value sim valor-alvo
threshold_warn não limiar do amarelo (atenção)
threshold_bad não limiar do vermelho (crítico)

Datas e fuso

A coluna ts aceita data/hora com fuso (ex.: 2026-06-09T18:00:00-03:00). Se você devolver uma data/hora sem fuso (ex.: 2026-06-09 18:00:00 ou só 2026-06-09), o Orbi assume o horário de Brasília (-03:00). Ou seja: a sua consulta pode devolver um DATETIME normal, sem se preocupar com formatação de fuso.

Reprocessar sem duplicar

Reexecutar a consulta não duplica dados:

  • Medições são idempotentes por key + external_ref. Use um external_ref estável (ex.: o período: 2026-06 ou 2026-06-09) para que reprocessar corrija o valor em vez de criar outro.
  • Metas são idempotentes por indicador + período (period_start/period_end).
  • Definições de indicador são atualizadas no lugar.

Exemplos

Só medições, com dimensão

SELECT
    'measurement'                          AS kind,
    'fin.receita'                          AS [key],
    SUM(VALORLIQUIDO)                      AS value,
    CONVERT(varchar, GETDATE(), 120)       AS ts,        -- AAAA-MM-DD HH:MM:SS
    '2026-06'                              AS external_ref,
    FILIAL                                 AS dim_filial
FROM faturamento
GROUP BY FILIAL

Uma consulta trazendo indicador + medição + meta

-- definição
SELECT 'indicator'  AS kind, 'fin.receita' AS [key], 'Receita' AS name,
       'currency_brl' AS unit, 'up_is_better' AS direction, 'sum' AS aggregation,
       NULL AS value, NULL AS ts, NULL AS target_value, NULL AS period_start, NULL AS period_end
UNION ALL
-- medição do mês
SELECT 'measurement', 'fin.receita', NULL, NULL, NULL, NULL,
       SUM(VALORLIQUIDO), CONVERT(varchar, GETDATE(), 120), NULL, NULL, NULL
FROM faturamento
UNION ALL
-- meta do trimestre
SELECT 'target', 'fin.receita', NULL, NULL, NULL, NULL,
       NULL, NULL, 2000000, '2026-04-01', '2026-06-30'

As colunas precisam bater por nome em todas as partes do UNION (mantenha a mesma ordem e preencha com NULL o que não se aplica àquele tipo de linha).

Com prefixo ORBI_ (Oracle / TOTVS RM)

No Oracle (e em sentenças RM sobre Oracle) prefira o prefixo ORBI_: ele dispensa aspas em palavras reservadas e é imune ao folding de maiúsculas do banco.

SELECT
    'measurement'        AS ORBI_KIND,
    'fin.receita'        AS ORBI_KEY,
    SUM(VALORLIQUIDO)    AS ORBI_VALUE,
    SYSDATE              AS ORBI_TS,        -- sem fuso → assume -03:00
    '2026-06'            AS ORBI_EXTERNAL_REF,
    FILIAL               AS ORBI_DIM_FILIAL
FROM FATURAMENTO
GROUP BY FILIAL

TOTVS RM

No RM, o fluxo é:

  1. Cadastre a consulta no próprio RM como uma sentença SQL, seguindo a convenção de colunas acima. Ela é executada somente leitura. Em bases Oracle, use o prefixo ORBI_ nos aliases (ex.: AS ORBI_KEY) para evitar aspas em palavras reservadas e o folding de maiúsculas do banco.
  2. No Orbi, crie a origem do tipo RM informando apenas código da coligada, código do sistema e código da sentença. O Orbi chama essa sentença periodicamente e ingere o resultado.

Você não cola SQL no Orbi: ele apenas executa a consulta que já está cadastrada no RM, pelos três códigos. Assim o controle da consulta permanece no RM.

Próximos passos