Consultar Lakehouse

O nó Consultar Lakehouse lê dados de uma tabela do Datawarehouse diretamente dentro de um fluxo ETL. Útil para enriquecer dados de uma fonte externa com dados já processados no DW, ou para reprocessar dados existentes.

---

Parâmetros de Configuração

• Tabela — Tabela do Datawarehouse a ser consultada. A lista exibe todas as tabelas do tenant, incluindo as ainda não publicadas.
• Consulta declarativa (querySpec) — Projeção, filtros, agrupamento/agregações, colunas de janela, deduplicação e ordenação configurados de forma estruturada (sem SQL cru). Veja Consulta declarativa (querySpec) abaixo.
• Limite de linhas (Limit) — Número máximo de linhas retornadas. Use 0 para sem limite.

---

Consulta declarativa (querySpec)

Em vez de uma cláusula WHERE em SQL cru, o nó Consultar Lakehouse monta a consulta a partir de campos estruturados. Todos são opcionais (omitir = comportamento padrão).

Select

Lista de nomes de coluna a projetar. Se omitido, retorna todas as colunas da tabela.

Select: [SALE_ID, SALE_DATE, STATUS, TOTAL_AMOUNT]

Filtros (Filters)

Filters aceita duas formas equivalentes — use uma OU outra, nunca as duas juntas:

• Lista simples (v1) — array de condições { Column, Op, Value }, sempre combinadas com E (AND) entre si. Forma retrocompatível.
• Árvore and/or (v2) — estrutura aninhável de blocos { and: [...] } / { or: [...] }, onde cada item é outro bloco and/or ou uma folha { Column, Op, Value }. Permite combinar E e OU livremente, inclusive aninhado.

Op	Significado	Formato de Value
eq	igual	valor único
neq	diferente	valor único
gt	maior que	valor único
gte	maior ou igual	valor único
lt	menor que	valor único
lte	menor ou igual	valor único
in	está na lista	array de valores
between	entre dois valores (inclusive)	array [min, max]
is_null	é nulo	omitido
is_not_null	não é nulo	omitido
like_prefix	começa com (prefixo de texto)	string única

Forma v1 — lista simples (AND implícito):

Filters:
  - Column: STATUS
    Op: in
    Value: [ativo, pendente]
  - Column: DATA_ATUALIZACAO
    Op: gte
    Value: { var: LastDataPoint }

Forma v2 — árvore and/or (equivalente à lista acima, mais a possibilidade de OU):

Filters:
  and:
    - Column: DATA_ATUALIZACAO
      Op: gte
      Value: { var: LastDataPoint }
    - or:
        - Column: STATUS
          Op: eq
          Value: ativo
        - Column: PRIORIDADE
          Op: gte
          Value: 5

O exemplo acima equivale a DATA_ATUALIZACAO >= {LastDataPoint} AND (STATUS = 'ativo' OR PRIORIDADE >= 5). As colunas e operadores de cada folha seguem as mesmas regras de allowlist da forma v1; a árvore tem profundidade e número de folhas limitados (proteção anti-abuso).

Agrupamento e Agregações (GroupBy / Aggregations)

GroupBy é uma lista de colunas de agrupamento. Aggregations é uma lista de { Func, Column, As }, onde As é o nome da coluna de saída.

Funções (Func) disponíveis: min, max, sum, count, avg, count_distinct.

GroupBy: [STATUS]
Aggregations:
  - Func: min
    Column: SALE_DATE
    As: FIRST_SALE_DATE

Regra: ao usar Aggregations, toda coluna em Select precisa também estar em GroupBy (mesma regra do GROUP BY em SQL padrão).

Colunas de Janela (WindowColumns)

WindowColumns calcula colunas analíticas (window functions) e as projeta junto com o resultado — ao contrário de GroupBy/Aggregations, não colapsa linhas: o número de linhas de saída continua o mesmo da entrada.

Cada item é { As, Func, Column, PartitionBy, OrderBy, Offset }:

• As — nome da coluna de saída (obrigatório).
• Func — função da janela, uma das: row_number, rank, dense_rank, sum, avg, min, max, count, lag, lead.
• PartitionBy — lista de colunas que definem a "partição" (a chave dentro da qual a janela é calculada). Pode ser vazia = uma única janela sobre todo o resultado.
• OrderBy — lista de { Column, Dir } que define a ordem dentro de cada partição.
• Column — coluna de entrada da função.
• Offset — só para lag/lead: quantas linhas voltar/avançar (inteiro ≥ 1, padrão 1).

Os campos obrigatórios variam por função:

Func	Column	OrderBy	Offset	Observação
row_number, rank, dense_rank	não usa (proibido)	obrigatório	não usa	funções de ranking
sum, avg, min, max, count	obrigatório (sum/avg exigem coluna numérica)	opcional	não usa	agregação sobre a janela (acumulada, se houver OrderBy)
lag, lead	obrigatório	obrigatório	opcional (padrão 1)	valor de uma linha deslocada dentro da partição

WindowColumns:
  - As: RN
    Func: row_number
    PartitionBy: [DEAL_ID]
    OrderBy:
      - Column: UPDATED_AT
        Dir: desc
  - As: TOTAL_ACUMULADO
    Func: sum
    Column: VALUE
    PartitionBy: [DEAL_ID]
    OrderBy:
      - Column: IN_DATE
        Dir: asc
  - As: STATUS_ANTERIOR
    Func: lag
    Column: STATUS
    PartitionBy: [DEAL_ID]
    OrderBy:
      - Column: IN_DATE
        Dir: asc
    Offset: 1

Deduplicação (Dedupe)

Dedupe mantém apenas uma linha por chave — útil para pegar o estado mais recente (ou o mais antigo) de cada registro, por exemplo o status atual de cada DEAL_ID.

Campos: { PartitionBy, OrderBy, Keep }, todos obrigatórios:

• PartitionBy — lista de colunas que formam a chave de deduplicação.
• OrderBy — lista de { Column, Dir } que define qual linha é a "primeira"/"última" dentro de cada chave.
• Keep — first (mantém a primeira linha da ordenação) ou last (mantém a última).

Dedupe:
  PartitionBy: [DEAL_ID]
  OrderBy:
    - Column: UPDATED_AT
      Dir: desc
  Keep: first

O exemplo acima mantém, para cada DEAL_ID, apenas a linha com o UPDATED_AT mais recente (estado atual do deal).

Para obter "primeira e última linha" ao mesmo tempo, use WindowColumns (projete RN em ordem crescente e outra em ordem decrescente) e filtre em um nó posterior — Dedupe cobre o caso de manter apenas um lado (primeiro ou último).

Exclusividade mútua

Um nó Consultar Lakehouse pode usar no máximo um destes três mecanismos por consulta:

• GroupBy + Aggregations (agrupamento/agregação — colapsa linhas), ou
• WindowColumns (colunas de janela — projeta, não colapsa), ou
• Dedupe (deduplicação por chave).

Select, Filters, OrderBy e Limit são livres e podem ser combinados com qualquer um dos três acima. Configurar mais de um dos mecanismos exclusivos no mesmo nó é rejeitado na validação.

Ordenação (OrderBy)

Lista de { Column, Dir }, onde Dir é asc ou desc. Column pode ser uma coluna de Select/GroupBy ou o alias (As) de uma agregação.

OrderBy:
  - Column: SALE_DATE
    Dir: desc

Variáveis nos filtros

O valor de um filtro pode referenciar uma variável do fluxo em vez de um literal, usando { var: "NomeDaVariavel" }:

Variável	Resultado
{ var: "StartDate" }	início do período (modo Temporal)
{ var: "EndDate" }	fim do período (modo Temporal)
{ var: "LastDataPoint" }	último valor processado (modo Incremental)
{ var: "MinhaVariavel" }	qualquer variável do tenant ou de desenvolvimento
{ var: "VarDoConfigurator" }	qualquer variável produzida por um nó PythonConfigurator anterior no fluxo

Filters:
  - Column: DATA_VENDA
    Op: between
    Value: [{ var: "StartDate" }, { var: "EndDate" }]

Para transformar uma variável antes de usá-la no filtro (por exemplo, LastDataPoint menos 12 dias), crie uma variável derivada em um nó PythonConfigurator anterior no fluxo e referencie o resultado com { var: "NomeDerivado" }.

WhereClause (legado)

WhereClause — cláusula SQL livre (sem a palavra WHERE) — ainda é aceita por retrocompatibilidade em fluxos existentes, mas está descontinuada. Novos fluxos devem usar Filters. Não crie novos usos de WhereClause.

---

Comportamento

• Consulta o Lakehouse via Data-Inserter (caminho interno). Não usa credencial externa.
• O schema do nó é inferido automaticamente a partir da definição da tabela no DW.
• As colunas retornadas têm os mesmos tipos definidos na tabela (string, número, data).

---

Diferença: Consultar Lakehouse vs. Extrair Datalake

	Consultar Lakehouse	Extrair Datalake
Fonte	Tabelas do Datawarehouse	Arquivos Parquet no Datalake
Filtro	Consulta declarativa (querySpec: Select/Filters/GroupBy/Aggregations/WindowColumns/Dedupe/OrderBy)	Partição por data
Uso típico	Enriquecimento, reprocessamento de dados do DW	Reprocessamento de dados brutos/intermediários