Pular para o conteúdo
ingestia.ioingestia.io
Ingestia AcademyProgresso
ACD-310 — Modelo semântico e modelagem dimensionalPreview

Calendário; fiscal, 4-4-5, fuso

Aula 6 de 108 minOperarAtualizada em 2026-10-04

Vídeo em produção

A gravação desta aula está no lote de produção. O objetivo, o exercício e a documentação já valem. Duração-alvo: 8 min.

Objetivo: Criar calendário e marcar `dateTable`

Selo de estado: Preview (teto atual do produto) · Curso ACD-310 — Modelo semântico e modelagem dimensional · Aula 6 de 10 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai configurar a dimensão calendario da Aurora Varejo — fuso, locale, ano fiscal e, se precisar, o calendário 4-4-5 de varejo — e marcá-la como a tabela de datas do modelo.

Vídeo#

Identificador no manifesto: acd-310-06-tabela-calendario-e-calendarios-fiscais · duração-alvo 8 min · tela do produto: /dashboards.

Roteiro:

  1. 00:00–01:00 — Por que uma coluna de data no fato não basta · tela: /dashboards/[id] (tentativa de YTD sem calendário ligado)
  2. 01:00–02:30 — Confirmando a relação vendas.data → calendario.data · tela: /dashboards/[id] (diagrama do modelo)
  3. 02:30–04:00 — Fuso America/Sao_Paulo e o caso dos 31/12 às 22h · tela: /dashboards/[id] (propriedades da dimensão de calendário)
  4. 04:00–05:30 — Ano fiscal começando em abril: o que muda no rótulo do período · tela: /dashboards/[id] (configuração de ano fiscal)
  5. 05:30–07:00 — Calendário 4-4-5 de varejo (regra NRF, 53ª semana) · tela: /dashboards/[id] (alternando modo 4-4-5)
  6. 07:00–08:00 — Validando com um visual "receita por ano fiscal" usando ACUM_ANO · tela: /dashboards/[id] (visual com YTD)

Conteúdo#

Uma coluna de data dentro do fato vendas serve para filtrar, mas não "sabe" o que é um trimestre, um ano fiscal ou "a mesma semana do ano passado". É para isso que existe uma dimensão de tempo dedicada: a tabela calendario, com uma linha por dia do período, descrita em Tutorial: criar uma tabela calendário.

Por que uma dimensão de tempo dedicada

A inteligência de tempo — acumulado no ano, mesmo período do ano anterior, mês anterior inteiro — precisa de atributos como ano, trimestre, mês e semana já calculados, não derivados na hora. É o que calendario traz, e é o que a habilita como eixo dessas comparações (ver Contexto de linha e de filtro).

Pré-requisito: o modelo precisa ter o fato ligado a uma coluna de data — na Aurora, a relação vendas.data → calendario.data (N-1, single) que você criou na aula 3.

Fuso: data civil, nunca UTC

O primeiro ajuste é o fuso. Configurado como America/Sao_Paulo (o padrão), o motor trabalha com data civil, nunca UTC — isso evita um bug clássico: uma venda registrada às 22h de 31 de dezembro, no fuso de São Paulo, precisa cair no ano civil correto (o ano que está terminando), não "vazar" para o ano seguinte por causa de uma conversão para UTC que já cruzou a meia-noite em outro fuso.

Locale pt-BR

Selecionar locale pt-BR traz nomes de mês e dia da semana em português nos visuais ("julho", "quinta-feira"). A tabela de locale é fixa (não vem de Intl do navegador) de propósito: isso garante que o motor puro (TypeScript) e o SQL gerado para o BigQuery produzam exatamente os mesmos bytes de rótulo — se dependesse de Intl, motor e SQL poderiam divergir sutilmente entre ambientes.

Ano fiscal (opcional)

Se a empresa não fecha o ano em dezembro, configure o mês de início do ano fiscal. O ano fiscal é rotulado pelo ano civil em que começa: com início em 1º de abril, o ano fiscal 2026 cobre 01/04/2026 → 31/03/2027 — um visual "receita por ano fiscal" agrupa julho/2026 e março/2027 no mesmo ano fiscal 2026, mesmo estando em anos civis diferentes.

Calendário 4-4-5 de varejo (opcional)

Empresas de varejo que fecham por semanas (não por dia do mês) podem ativar o modo 4-4-5: cada trimestre é dividido em três períodos de 4, 4 e 5 semanas. A regra usada é a "closest" (padrão NRF), e a 53ª semana, quando ocorre, vai inteira para o último período do ano — nunca é dividida ou descartada.

Validando com inteligência de tempo

Depois de configurado, qualquer medida ganha as funções de tempo do catálogo de fórmulas de graça, porque elas dependem só da relação com calendario:

formula
ACUM_ANO(SOMA(valor); data)

Essa medida mostra o acumulado de valor desde o início do ano (civil ou fiscal, conforme sua configuração) até a data do ponto atual do visual — e reinicia sozinha na virada do ano, sem fórmula extra.

Maturidade

Os calendários configuráveis estão em Preview: o motor puro (TypeScript) é coberto por um conjunto de testes de referência, mas a equivalência exata entre esse motor e o SQL executado num BigQuery de produção real nunca foi medida — por isso o selo não sobe a GA-candidato aqui, diferente de boa parte do resto do motor de relações.

Como isso aparece no produto

No editor do dashboard (/dashboards/[id]), a configuração do calendário vive nas propriedades da dimensão marcada como tabela de datas: fuso, locale, início do ano fiscal e o alternador do modo 4-4-5 ficam todos ali, num único lugar — não há uma tela separada de "administração de calendário".

Erros comuns

  • Usar uma coluna de data qualquer como se fosse a dimensão de tempo. Sem a relação vendas.data → calendario.data marcada corretamente, as funções de inteligência de tempo não têm sobre o que operar.
  • Esquecer o fuso e "perder" a virada do ano. Se o fuso estiver errado, uma venda de véspera de ano novo pode aparecer no ano civil errado — o sintoma típico é um "31 de dezembro" que não bate com o fechamento esperado.
  • Confundir ano fiscal com ano civil no rótulo. Lembre-se: o ano fiscal é nomeado pelo ano em que começa, não pelo ano em que termina.
  • Ordenar mês alfabeticamente. "Abril" vem antes de "Agosto" em ordem alfabética, mas não é a ordem certa do calendário — use sort-by-column (ordenar o nome do mês pelo seu número), descrito em Modelo semântico e retomado na aula 7.

Faça você mesmo#

No workspace de treino Aurora Varejo (abra /dashboards no console, editor de um painel, aba do modelo):

  1. Confirme a relação vendas.data → calendario.data (N-1, single) — se não existir, crie-a como na aula 3.
  2. Abra as propriedades da dimensão calendario e confirme o fuso America/Sao_Paulo.
  3. Selecione o locale pt-BR.
  4. Configure o ano fiscal começando em abril (mês 4).
  5. Crie a medida ACUM_ANO(SOMA(valor); data) e jogue-a num visual "receita acumulada por mês".
  6. Confirme que o acumulado cresce mês a mês e reinicia na virada do ano fiscal (abril), não em janeiro.
  7. (Opcional) Ative o modo 4-4-5 e observe como os períodos do visual mudam de "mês" para "período de 4/4/5 semanas".

Você terminou quando o visual de acumulado mostrar o reinício exatamente no mês de início do seu ano fiscal configurado, e você conseguir explicar por que isso não seria verdade sem a dimensão calendario configurada.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

Capacidades ensinadas#

C05.5 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".

Carregando seu progresso…