Como usar calendários personalizados no Looker

Para dialetos que oferecem suporte a esse recurso, as agendas personalizadas no Looker permitem definir uma agenda personalizada no banco de dados, como uma agenda fiscal ou de varejo específica, e aplicar a agenda 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 agendas personalizadas, verifique se os seguintes pré-requisitos foram atendidos:

Como criar uma agenda personalizada

Para implementar uma agenda personalizada, siga estas etapas gerais descritas nas seções a seguir:

  1. Criar a tabela de agenda no banco de dados
  2. Definir a visualização da agenda personalizada no LookML
  3. Criar um grupo de dimensões de agenda personalizada

Criar uma tabela de agenda 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 padrão da agenda. O Looker une a tabela de agenda às tabelas de dados (como uma tabela orders) com base na coluna de data de referência.

Os nomes das colunas na tabela de agenda são flexíveis. Ao definir a visualização da agenda personalizada 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 agenda chamada fiscal_calendar_table.

Nome da coluna Tipo de dados Descrição
reference_date DATE A data padrão da agenda (como "2023-01-01"). Usada para unir. 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).

Para ilustrar, confira alguns exemplos de linhas 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 a visualização da agenda personalizada no LookML

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

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

  • O parâmetro sql_table_name que aponta para a tabela de agenda personalizada 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 agenda 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 detalhes sobre os parâmetros calendar_definition.

Criar um grupo de dimensões de agenda personalizada

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

Por exemplo, confira um arquivo de visualização chamado orders.view.lkml que define um grupo de dimensões de agenda personalizada.

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" e "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 agendas personalizadas.

Informações importantes

Observe as seguintes limitações com agendas personalizadas:

  • Medidas filtradas: as agendas personalizadas não são compatíveis com medidas filtradas. Não é possível referenciar uma dimensão de agenda personalizada no parâmetro filters de uma medida.
  • Filtros avançados: as agendas personalizadas não são compatíveis com filtros avançados. Não é possível referenciar uma dimensão de agenda personalizada 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 agenda personalizada.
  • Preenchimento de dimensões:o Looker não pode preencher dimensões de datas ausentes para dimensões de agenda personalizada.
  • Filtragem além dos limites da agenda:se um filtro for aplicado a um período personalizado que resulte em uma data que não esteja na agenda, 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 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 substituir esse comportamento especificando convert_tz: no para o grupo de dimensões de agenda personalizada.
  • Classificação padrão:o Looker aplica uma classificação padrão ao primeiro campo de data quando os campos de agenda personalizada são selecionados. O usuário pode então especificar uma classificação de dados diferente.
  • Filtros de agenda personalizada:as dimensões de agenda personalizada oferecem suporte a opções de filtro específicas, como está nos últimos três anos personalizados ou é este período personalizado. Para mais informações, consulte a seção Filtros de agenda personalizada da página de documentação Filtrar e limitar dados.

Dialetos de banco de dados compatíveis com agendas personalizadas

A tabela a seguir mostra quais dialetos oferecem suporte a agendas personalizadas 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