Como usar calendários personalizados no Looker

Para dialetos que oferecem suporte a esse recurso, o calendário personalizado do Looker permite definir um calendário personalizado no banco de dados, como um calendário fiscal ou de varejo específico, e aplicá-lo a um grupo de dimensões com base em datas no modelo do LookML. Os usuários podem criar consultas do Explorar usando períodos personalizados, como custom_week e custom_period, como se fossem períodos padrão.

Pré-requisitos

Antes de usar calendários personalizados, verifique se os seguintes pré-requisitos foram atendidos:

• Você precisa ter uma conexão do Looker com um dialeto que oferece suporte a calendários personalizados.
• Você precisa criar uma tabela de calendário no banco de dados que possa ser modelada como uma visualização no Looker. O Looker usa a tabela de calendário no banco de dados para calcular períodos personalizados. Consulte a seção Criar uma tabela de calendário no banco de dados para mais informações.
• O projeto do LookML precisa usar o novo ambiente de execução do LookML. Se o recurso legado Usar o ambiente de execução do LookML legado estiver ativado na sua instância, adicione a instrução new_lookml_runtime: yes ao arquivo de manifesto do projeto.

Como criar um calendário personalizado

Para implementar um calendário personalizado, siga estas etapas gerais descritas nas seções a seguir:

1. Criar a tabela de calendário no banco de dados
2. Definir a visualização do calendário personalizado no LookML
3. Criar um grupo de dimensões de calendário personalizado

Criar uma tabela de calendário no banco de dados

Para calcular datas de calendários personalizados, o Looker precisa de uma tabela de calendário dedicada no banco de dados que defina os períodos personalizados. A tabela precisa ter uma coluna de data de referência que use a data padrão do calendário. O Looker une a tabela de calendário às tabelas de dados (como uma tabela orders) com base na coluna de data de referência.

Os nomes das colunas na tabela de calendário são flexíveis. Ao definir a visualização do calendário personalizado no LookML, você usará o bloco calendar_definition para mapear as colunas no banco de dados para nomes de períodos personalizados padrão.

Confira a seguir um exemplo de esquema de tabela para uma tabela de calendário chamada fiscal_calendar_table.

Nome da coluna	Tipo de dados	Descrição
reference_date	DATE	A data padrão do calendário (como "2023-01-01"). Usada para junção. Precisa ser uma chave exclusiva ou primária.
fiscal_year	VARCHAR	O ano fiscal (como "FY2023").
fiscal_year_num	INTEGER	O ano fiscal numérico (como 2023).
fiscal_quarter_of_year	VARCHAR	O trimestre fiscal (como "FQ1").
fiscal_quarter_of_year_num	INTEGER	O trimestre fiscal numérico (como 1).
fiscal_week_of_year	VARCHAR	A semana fiscal do ano (como "Week01", "FW01").
fiscal_week_of_year_num	INTEGER	A semana fiscal numérica do ano (como 1).
fiscal_period_of_year	VARCHAR	Um nome de período personalizado (como "P01").
fiscal_period_of_year_num	INTEGER	O período personalizado numérico (como 1).
season	VARCHAR	Um nome de temporada personalizado (como "Winter").
season_num	INTEGER	A temporada personalizada numérica (como 1).
prev_week_num	INTEGER	O valor ordinal da semana anterior (como 52 ou 53). O Looker precisa desse valor para calcular medidas de período a período nos casos em que a semana atual é 1 e a semana anterior no calendário não é 52. O uso de prev_week_num é necessário apenas se você quiser usar medidas de período a período com calendários personalizados e somente se o calendário personalizado não tiver 52 semanas.
prev_day_num	INTEGER	O valor ordinal do dia anterior (como 364 ou 371). O Looker precisa desse valor para calcular medidas de período a período nos casos em que o dia atual é 1 e o dia anterior no calendário não é 364. O uso de prev_day_num é necessário apenas se você quiser usar medidas de período a período com calendários personalizados e somente se o calendário personalizado não tiver 364 dias.

Para ilustrar, confira alguns exemplos de linhas da tabela fiscal_calendar_table:

reference_date	fiscal_year	fiscal_year_num	fiscal_period	fiscal_period_num	prev_week_num	prev_day_num
2023-12-25	FY2024	2024	P01	1	51	358
2023-12-26	FY2024	2024	P01	1	51	359
2024-01-01	FY2024	2024	P02	2	52	364
2024-01-02	FY2024	2024	P02	2	52	1

Definir a visualização do calendário personalizado no LookML

Depois de criar uma tabela de calendário no banco de dados, você precisa criar uma visualização do LookML para modelar a tabela de calendário do banco de dados.

Dica: a maneira mais fácil de criar o arquivo de visualização é usar a opção Criar visualização da tabela no IDE do Looker para que o Looker modele automaticamente os campos da tabela. Depois que o Looker criar o arquivo de visualização, você poderá adicionar o bloco de parâmetros calendar_definition, modificar qualquer uma das dimensões criadas automaticamente e adicionar outras definições de dimensão necessárias.

O arquivo de visualização do calendário personalizado precisa incluir o seguinte:

• O parâmetro sql_table_name que aponta para a tabela de calendário personalizado no banco de dados.
• O calendar_definition bloco para mapear as colunas da tabela para os tipos de período personalizado do Looker.
• dimension parâmetros para modelar as colunas da tabela de calendário personalizado no banco de dados.

Confira a seguir um exemplo de arquivo de visualização chamado fiscal_calendar.view.lkml que modela o exemplo fiscal_calendar_table:

view: fiscal_calendar {
  sql_table_name: fiscal_calendar_table ;;
  calendar_definition: {
    reference_date: reference_date
    timeframe_mapping: {
      custom_year: fiscal_year
      custom_quarter: fiscal_quarter_of_year
      custom_date: fiscal_date
      custom_week: fiscal_week_of_year
      custom_period: fiscal_period_of_year
      custom_season: season
    }
    timeframe_ordinal_mapping: {
      custom_year: fiscal_year_num
      custom_quarter: fiscal_quarter_of_year_num
      custom_date: fiscal_date_num
      custom_week: fiscal_week_of_year_num
      custom_period: fiscal_period_of_year_num
      custom_season: season_num
    }
    previous_ordinal_mapping: {
      custom_week: prev_week_num
      custom_date: prev_day_num
    }
  }

  dimension: reference_date {
    type: date
    primary_key: yes
    sql: ${TABLE}.reference_date ;; # Assuming column name is reference_date
  }

  dimension: fiscal_date {
  type: string
  sql: FORMAT_TIMESTAMP('%Y-%m-%d', ${TABLE}.reference_date) ;;
}

  dimension: fiscal_year {
    type: string
    sql: ${TABLE}.fiscal_year ;;
  }

  dimension: fiscal_year_num {
    type: number
    sql: ${TABLE}.fiscal_year_num ;;
  }

  # ... other dimensions for quarters, weeks, periods, seasons, etc. ...

  # Example placeholder dimensions for unused timeframes
  dimension: season {
    type: string
    sql: 'N/A' ;;
    hidden: yes
  }
  dimension: season_num {
    type: number
    sql: 0 ;;
    hidden: yes
  }
}

Consulte a página de parâmetros calendar_definition para detalhes sobre os parâmetros calendar_definition.

Criar um grupo de dimensões de calendário personalizado

Depois de criar uma tabela de calendário no banco de dados e modelar a tabela de calendário do banco de dados no LookML, você pode criar um grupo de dimensões de type: custom_calendar com base na visualização do calendário personalizado.

Por exemplo, confira um arquivo de visualização chamado orders.view.lkml que define um grupo de dimensões de calendário personalizado.

include: "/views/fiscal_calendar.view"

view: orders {
  sql_table_name: public.orders ;;

  dimension_group: created {
    type: custom_calendar

    # Optional list of allowed timeframes
    custom_timeframes: [
      custom_date,
      custom_week,
      custom_year
    ]
    sql: ${TABLE}.created_at ;;
    based_on_calendar: fiscal_calendar  # This links to your calendar view
  }
}

Com esse LookML, o Looker vai criar automaticamente um novo conjunto de períodos personalizados para o grupo de dimensões created (como "Ano personalizado criado", "Semana personalizada criada"). Os usuários podem usar esses campos para explorar, gerar relatórios e filtrar.

Consulte a página de documentação dimension_group para detalhes sobre como criar um grupo de dimensões para calendários personalizados.

Informações importantes

Observe as seguintes limitações com calendários personalizados:

• Medidas filtradas: os calendários personalizados não são compatíveis com medidas filtradas. Não é possível referenciar uma dimensão de calendário personalizado no parâmetro filters de uma medida.
• Filtros avançados: os calendários personalizados não são compatíveis com filtros avançados. Não é possível referenciar uma dimensão de calendário personalizado em expressões de filtro do Looker.
• Agregações simétricas: em alguns cenários de junção complexos, as agregações simétricas podem não ser totalmente compatíveis com consultas que envolvem dimensões de calendário personalizado.
• Preenchimento de dimensões:o Looker não pode preencher datas ausentes para dimensões de calendário personalizado.
• Filtragem além dos limites do calendário:se um filtro for aplicado a um período personalizado que resulte em uma data que não esteja no calendário, resultados inesperados poderão ser retornados. Isso tem a ver com a aritmética ordinal usada para calcular o início de um período.
• Filtros OR:os filtros OR não são compatíveis com consultas com calendários personalizados.
• Comportamento de conversão de fuso horário:o Looker respeita a semântica de conversão de fuso horário atual. Ou seja, se o banco de dados e o fuso horário da consulta forem iguais, nenhuma conversão de fuso horário será aplicada. Se eles não concordarem, o Looker vai aplicar a conversão de fuso horário. É possível modificar esse comportamento especificando convert_tz: no para o grupo de dimensões de calendário personalizado.
• Classificação padrão:o Looker aplica uma classificação padrão ao primeiro campo de data quando os campos de calendário personalizado são selecionados. O usuário pode então especificar uma classificação de dados diferente.
• Filtros de calendário personalizado:as dimensões de calendário personalizado oferecem suporte a opções de filtro específicas, como está nos últimos 3 anos personalizados ou é este período personalizado. Para mais informações, consulte a seção Filtros de calendário personalizado da página de documentação Filtrar e limitar dados.

Dialetos de banco de dados compatíveis com calendários personalizados

A tabela a seguir mostra quais dialetos oferecem suporte a calendários personalizados na versão mais recente do Looker:

Dialeto	Compatível?
Actian Avalanche
Amazon Athena
Amazon Aurora MySQL
Amazon Redshift
Amazon Redshift 2.1+
Amazon Redshift Serverless 2.1+
Apache Druid
Apache Druid 0.13.x - 0.17.x
Apache Druid 0.18+
Apache Hive 2.3+
Apache Hive 3.1.2+
Apache Spark 3+
ClickHouse
Cloudera Impala 3.1+
Cloudera Impala 3.1+ with Native Driver
Cloudera Impala with Native Driver
DataVirtuality
Databricks
Denodo 7
Denodo 8 & 9
Dremio
Dremio 11+
Exasol
Google BigQuery Legacy SQL
Google BigQuery Standard SQL
Google Cloud AlloyDB for PostgreSQL
Google Cloud PostgreSQL
Google Cloud SQL
Google Spanner
Greenplum
HyperSQL
IBM Netezza
MariaDB
Microsoft Azure PostgreSQL
Microsoft Azure SQL Database
Microsoft Azure Synapse Analytics
Microsoft SQL Server 2008+
Microsoft SQL Server 2012+
Microsoft SQL Server 2016
Microsoft SQL Server 2017+
MongoBI
MySQL
MySQL 8.0.12+
Oracle
Oracle ADWC
PostgreSQL 9.5+
PostgreSQL pre-9.5
PrestoDB
PrestoSQL
SAP HANA
SAP HANA 2+
SingleStore
SingleStore 7+
Snowflake
Teradata
Trino
Vector
Vertica