Como usar calendários personalizados no Looker

Para dialetos compatíveis, o recurso de calendário personalizado no Looker permite definir um calendário personalizado no seu 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 seu modelo do LookML. Os usuários podem criar consultas de análise usando seus períodos personalizados, como custom_week, custom_period, como se fossem períodos padrão.

Pré-requisitos

Antes de usar agendas personalizadas, verifique se os seguintes pré-requisitos foram atendidos:

Como criar uma agenda personalizada

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

  1. Criar a tabela de calendário no banco de dados
  2. Definir a visualização personalizada da agenda 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 agendas personalizadas, o Looker precisa de uma tabela de agenda 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 do calendário padrão. O Looker mescla a tabela de calendário com as 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 de calendário personalizado no LookML, use o bloco calendar_definition para mapear as colunas do banco de dados para nomes de períodos personalizados padrão.

Veja 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"). Usado para mesclagem. Precisa ser uma chave exclusiva ou primária.
fiscal_day_num INTEGER A data personalizada numérica ou o dia ordinal do ano (como 1).
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 estação personalizado (como "Inverno").
season_num INTEGER A estação 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 as medições 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 só é necessário se você quiser usar medidas de período a período com agendas personalizadas e se a agenda personalizada 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 as 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 só é necessário se você quiser usar medidas de período a período com agendas personalizadas e se a agenda personalizada não tiver 364 dias.

Para ilustrar, veja algumas linhas de amostra da tabela fiscal_calendar_table:

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

Definir a visualização personalizada da agenda 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.

O arquivo de visualização personalizada da agenda precisa incluir o seguinte:

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

Veja 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_day_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_day_num {
    type: number
    sql: ${TABLE}.fiscal_day_num ;;
  }

  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 mais 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, crie um grupo de dimensões de type: custom_calendar com base na visualização de calendário personalizada.

Por exemplo, veja 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 fiscal", "Semana fiscal"). Os usuários podem usar esses campos para explorar, gerar relatórios e filtrar.

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

Informações importantes

Observe as seguintes limitações com agendas personalizadas:

  • Medições filtradas: os calendários personalizados não são compatíveis com medições filtradas. Não é possível referenciar uma dimensão de calendário personalizado no parâmetro filters de uma medição.
  • 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.
  • Conjuntos simétricos:em alguns cenários de mesclagem complexos, os conjuntos simétricos podem não ser totalmente compatíveis com consultas que envolvem dimensões de calendário personalizadas.
  • Preenchimento de dimensão:o Looker não pode preencher as datas ausentes para dimensões de calendário personalizadas.
  • 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 está 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 que usam agendas personalizadas.
  • Comportamento de conversão de fuso horário:o Looker segue a semântica de conversão de fuso horário atual. Ou seja, se o fuso horário do banco de dados e da consulta forem iguais, nenhuma conversão de fuso horário será aplicada. Se eles forem diferentes, o Looker vai aplicar a conversão de fuso horário. Para modificar esse comportamento, especifique 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 personalizados são selecionados. O usuário pode especificar uma classificação de dados diferente.
  • Filtros de calendário personalizados:as dimensões de calendário personalizadas são compatíveis com 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 personalizados da página de documentação Como filtrar e limitar dados.

Dialetos de banco de dados compatíveis com agendas personalizadas

A tabela a seguir mostra quais dialetos são compatíveis com 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
ClickHouse 26+
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+
Dremio 26+ with Arrow Flight SQL
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
MongoSQL
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