Como usar calendários personalizados no Looker

Para dialetos compatíveis, o recurso de calendário personalizado do 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. Assim, os usuários podem criar consultas do recurso Detalhar usando seus períodos personalizados, como custom_week e 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 estas etapas gerais, descritas nas seções a seguir:

  1. Criar a tabela de calendário no banco de dados
  2. Definir sua visualização de calendário personalizada na 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 seu banco de dados que defina os períodos personalizados. Sua tabela precisa ter uma coluna de data de referência que use a data padrão do calendário. O Looker une sua 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 de calendário personalizada em LookML, você usará o bloco calendar_definition para mapear as colunas no banco de dados com nomes de período personalizado padrão.

Confira a seguir um exemplo de esquema de tabela de calendário chamado fiscal_calendar_table.

Nome da coluna Tipo de dados Descrição
reference_date DATE A data padrão do calendário (por exemplo, "2023-01-01"). sua participação. Precisa ser uma chave primária ou exclusiva.
fiscal_year VARCHAR O ano fiscal (por exemplo, "AF2023").
fiscal_year_num INTEGER O ano fiscal numérico (como 2023).
fiscal_quarter_of_year VARCHAR O trimestre fiscal (por exemplo, "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 "Inverno").
season_num INTEGER A temporada personalizada numérica (por exemplo, 1).

Para ilustrar, confira algumas linhas de exemplo da tabela fiscal_calendar_table:

reference_date fiscal_year fiscal_year_num fiscal_period fiscal_period_num
2023-12-25 FY2024 2024 P01 1
2023-12-26 FY2024 2024 P01 1
2024-01-01 FY2024 2024 P02 2
2024-01-02 FY2024 2024 P02 2

Definir sua visualização personalizada da agenda em LookML

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

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

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

Confira 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
    }
  }

  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 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 em LookML, é possível criar um grupo de dimensões de type: custom_calendar com base na visualização de calendário personalizada.

Por exemplo, aqui está uma visualização chamada 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 essa LookML, o Looker cria 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 análise detalhada, geração de relatórios e filtragem.

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

Informações importantes

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

  • Métricas filtradas: os calendários personalizados não são compatíveis com métricas filtradas. Não é possível referenciar uma dimensão de calendário personalizado no parâmetro filters de uma métrica.
  • 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 junção 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 consegue preencher datas ausentes para dimensões de calendário personalizadas.
  • Filtrar além dos limites do calendário:se um filtro for aplicado a um período personalizado que resulte em uma data fora do 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.
  • Comportamento da conversão de fuso horário:o Looker respeita 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 será aplicada. Se houver discordância, o Looker vai aplicar a conversão de fuso horário. Para substituir esse comportamento, especifique convert_tz: no no 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. Em seguida, o usuário pode especificar uma ordenação de dados diferente.

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

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
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