grupo_dimensão

Uso

visualizar: view_name {
dimension_group: nome_do_campo { ... }
}
Hierarquia
view
dimension_group
Aceita
Um identificador do Looker (para servir como a primeira parte do nome para cada dimensão criada pelo grupo de dimensões)

Regras especiais
  • O type pode ser time ou duration.
  • Normalmente usado com um parâmetro timeframes ou intervals
  • Use um parâmetro datatype se o grupo de dimensões não for baseado em um campo de data/hora.
  • Para grupos de dimensões de type: time, use um parâmetro convert_tz se você quiser impedir a conversão automática do fuso horário.

Definição

O parâmetro dimension_group é usado de uma só vez para criar um conjunto de dimensões com base no tempo ou na duração. Você define o grupo de dimensões, e o grupo de dimensões cria um conjunto de dimensões individuais para intervalos ou períodos diferentes. Por exemplo, é possível especificar um grupo de dimensões de type: time com base em uma coluna de carimbo de data/hora. O grupo de dimensões criará dimensões correspondentes para expressar os dados por data, hora, semana, hora, trimestre e ano.

A forma e a função do grupo de dimensões são diferentes, dependendo do valor type do grupo de dimensões:

Tipo de duração

A type: duration é usada em conjunto com uma dimension_group para calcular um conjunto de dimensões de duração com base em intervalos.

A forma de um grupo de dimensões de type: duration é:

dimension_group: dimension_group_name {
  type: duration
  sql_start: SQL expression ;;  # often this is a single database column
  sql_end: SQL expression ;;  # often this is a single database column
  intervals: [interval, interval, …] # valid intervals described below
}

Para grupos de dimensões de type: duration:

  • Os parâmetros sql_start e sql_end fornecem expressões SQL que definem os horários de início e término da duração. Consulte a seção Definir o início e o fim de uma duração nesta página para mais detalhes.

  • O parâmetro intervals especifica uma ou mais unidades de intervalo que vão ser usadas para medir a diferença de horário. As opções disponíveis estão listadas na seção Opções de intervalo desta página.

  • Os valores de duração são transferidos com o número inteiro mais próximo.

  • O parâmetro datatype é opcional. Se o grupo de dimensões não for baseado em uma data e hora, você poderá especificar um formato de época, carimbo de data/hora, data ou aaaammdd. Para grupos de dimensões de type: duration, o parâmetro datatype se aplica aos parâmetros sql_start e sql_end. Portanto, verifique se sql_start e sql_end são do tipo de dados especificado. O parâmetro datatype é descrito com mais detalhes na seção Como especificar o banco de dados datatype desta página.

Embora não estejam listados aqui, muitos dos parâmetros no nível do campo também podem ser usados com grupos de dimensões.

Por exemplo, se você tem colunas para enrollment_date e graduation_date, é possível criar um grupo de dimensões de duração para ver quanto tempo os estudantes passaram na escola, calculados em intervalos de semana e ano:

dimension_group: enrolled {
  type: duration
  intervals: [week, year]
  sql_start: ${TABLE}.enrollment_date ;;
  sql_end: ${TABLE}.graduation_date ;;
}

Na IU do Explorar, um grupo de dimensões chamado Duração da inscrição seria gerado, com as dimensões individuais Semanas inscritas e Anos registrados.

Opções de intervalo

O parâmetro intervals informa ao grupo de dimensões quais unidades de intervalo devem ser usadas para medir a diferença de horário entre sql_start e sql_end. O parâmetro intervals é compatível apenas com grupos de dimensões de type: duration.

Se intervals não estiver incluído, o grupo de dimensões incluirá todos os intervalos possíveis.

As opções do parâmetro intervals são:

Intervalo Descrição Exemplo de saída
day Calcula uma diferença de horário em dias. 9 days
hour Calcula uma diferença de horário em horas. 171 hours
minute Calcula uma diferença de horário em minutos. 10305 minutes
month Calcula uma diferença de horário em meses. 3 months
quarter Calcula uma diferença de tempo em trimestres do ano. 2 quarters
second Calcula uma diferença de horário em segundos. 606770 seconds
week Calcula uma diferença de horário em semanas. 6 weeks
year Calcula uma diferença de horário em anos. 2 years

Definir o início e o fim de uma duração

Para grupos de dimensões de type: duration, os parâmetros sql_start e sql_end fornecem as informações de início e término usadas para calcular uma diferença de horário. Esses campos podem ter qualquer expressão SQL válida que contenha dados em formato de carimbo de data/hora, data e hora, data, época ou aaaammdd. Os campos sql_start e sql_end podem ser qualquer um destes:

  • Uma referência a um período de raw de um grupo de dimensões de type: time
  • Uma referência a uma dimensão de type: date_raw
  • Uma expressão SQL que é um carimbo de data/hora, como uma referência a uma coluna SQL que é um carimbo de data/hora
  • Uma expressão SQL que extrai um horário do seu banco de dados, usando a expressão apropriada para o seu dialeto
  • Uma referência de campo LookML usando a referência de tipo de campo ::datetime ou ::date

Por exemplo, suponha que você tenha uma dimensão chamada faa_event_date_raw que contém informações de data e hora:

dimension: faa_event_date_raw {
  type: date_raw
  sql: ${TABLE}.event_date ;;
}

É possível criar um grupo de dimensões de type: duration que calcule a quantidade de tempo decorrido desde a data do evento da FAA. Para isso, use a dimensão faa_event_date_raw como horário de início para o cálculo. Depois, use a expressão SQL do dialeto para o horário de término. Este exemplo é de um banco de dados MySQL:

dimension_group: since_event {
  type: duration
  intervals: [hour, day]
  sql_start: ${faa_event_date_raw} ;;
  sql_end: CURRENT_TIMESTAMP();;
}

Na IU do Explorar, isso geraria um grupo de dimensões chamado Duração desde o evento, com dimensões individuais chamadas Horas desde o evento e Dias desde o evento.

Como fazer referência a intervalos de outro campo LookML

Para referenciar um valor interval em um dimension_group de type: duration, use a sintaxe ${interval_fieldname} com a versão plural do valor interval. Por exemplo, no exemplo LookML a seguir, a medida average_days_since_event usa ${days_since_event} para fazer referência ao intervalo day no grupo de dimensões since_event:


dimension_group: since_event {
  type: duration
  intervals: [hour, day, week, month, quarter, year]
  sql_start: ${faa_event_date_raw} ;;
  sql_end: CURRENT_TIMESTAMP();;
}

measure: average_days_since_event {
  type: average
  sql: ${days_since_event} ;;
}

Como usar referências de tipo de campo LookML com campos de duração

Para criar um campo de duração personalizado, especifique um tipo de referência ::date ou ::datetime para as dimensões referenciadas nos parâmetros sql_start e sql_end de um grupo de dimensões de type: duration. A sintaxe view_name.field_name::type, descrita na página Como incorporar SQL e objetos do LookML, permite criar uma versão ::date ou ::datetime de um campo sem transmitir as referências a essas dimensões para strings.

Por exemplo, suponha que você tenha um grupo de dimensões created de type: time com períodos de time, date, week, month e raw, definidos da seguinte maneira:


dimension_group: created {
  type: time
  timeframes: [time, date, week, month, raw]
  sql: ${TABLE}.created_at ;;
}

Usando as dimensões created_month e created_time, é possível criar um grupo de dimensões de type: duration que calcula o tempo entre uma data do campo created_date e o primeiro dia do mês em que essa data ocorreu, medida em semanas, dias e horas:


dimension_group: since_first_of_month {
  type: duration
  intervals: [week, day, hour]
  sql_start: ${created_month::datetime} ;;
  sql_end: ${created_time::datetime} ;;
}

Na IU do Explore, isso cria um grupo de dimensões chamado Duração desde o primeiro mês, com as dimensões individuais Semanas desde o primeiro dia do mês, Dias desde o primeiro mês e Horas desde o primeiro mês. Especificar o tipo de referência ::datetime para os campos referenciados nos parâmetros sql_start e sql_end permite que as dimensões created_month e created_time sejam tratadas como carimbos de data/hora no SQL gerado.

Por exemplo, suponha que um usuário selecione as dimensões Data de criação e Dias desde o primeiro dia do mês no seletor de campos. Se um dos valores retornados para Created Date for 2019-03-10, o valor retornado para Days Since First Month será 9 days.

Tipo hora

A type: time é usada em conjunto com um parâmetro dimension_group e o parâmetro timeframes para criar um conjunto de dimensões com base no tempo. Por exemplo, é possível criar facilmente uma dimensão de data, semana e mês com base em uma única coluna de carimbo de data/hora.

A forma de um grupo de dimensões de type: time é:

dimension_group: dimension_group_name {
  type: time
  timeframes: [timeframe, timeframe, …] # valid timeframes described below
  sql: SQL expression ;;  # often this is a single database column
  datatype: epoch| timestamp | datetime | date | yyyymmdd # defaults to datetime
  convert_tz: yes | no   # defaults to yes
}

Para grupos de dimensões de type: time:

  • O parâmetro timeframes é opcional, mas raramente é ignorado. Ela especifica um ou mais períodos que devem ser gerados pelo grupo de dimensões. Se timeframes não for incluído, todas as opções de período serão adicionadas ao grupo de dimensões. As opções disponíveis estão listadas na seção Opções de período nesta página.

  • O parâmetro sql para grupos de dimensões type: time pode usar qualquer expressão SQL válida que contenha dados em formato de carimbo de data/hora, data e hora, data, época ou aaaammdd.

  • O parâmetro datatype é opcional. Se o grupo de dimensões não for baseado em uma data e hora, você poderá especificar um formato de época, carimbo de data/hora, data ou aaaammdd. Ele é descrito com mais detalhes na seção Como especificar o datatype do banco de dados nesta página.

  • O parâmetro convert_tz é opcional e permite evitar a conversão automática de fuso horário. Ele é descrito com mais detalhes na seção Conversões de fuso horário e convert_tz nesta página.

Embora não estejam listados aqui, muitos dos parâmetros no nível do campo também podem ser usados com grupos de dimensões.

Por exemplo, suponha que você tenha uma coluna chamada created_at que contém informações de data e hora. Você quer criar uma dimensão de data, semana e mês com base nessa data e hora. Você pode usar:

dimension_group: created {
  type: time
  timeframes: [date, week, month]
  sql: ${TABLE}.created_at ;;
}

Na IU do Explore, isso geraria três dimensões com os nomes Created Date, Created Week e Created Month. Observe como o nome dimension_group é combinado com os prazos para gerar os nomes das dimensões.

Opções de período

O parâmetro timeframes é compatível apenas com grupos de dimensões de type: time. Para grupos de dimensões de type: duration, use o parâmetro intervals.

O parâmetro timeframes informa ao grupo de dimensões quais dimensões ele deve produzir. As opções são:

Períodos especiais

Período Descrição Exemplo de saída
raw O valor bruto do seu banco de dados, sem conversão ou conversão de fuso horário. raw só pode ser acessado no LookML e não será exibido na página Explorar. O período raw retorna um carimbo de data/hora, ao contrário da maioria dos outros que retornam uma string formatada. Ela é usada principalmente para realizar operações de data em um campo. 2014-09-03
17:15:00 +0000
yesno Uma dimensão yesno, retornando "Yes" se a data e hora tiver um valor. Caso contrário, será "No". Diferentemente de outros períodos, ao se referir a uma dimensão de período yesno de outro campo, não inclua o período na referência. Por exemplo, para se referir a um período de yesno no dimension_group: created, use a sintaxe ${created}, não ${created_yesno}. Yes

Períodos

Período Descrição Exemplo de saída
time Data e hora do campo subjacente (alguns dialetos SQL mostram a mesma precisão do banco de dados, enquanto outros mostram apenas o segundo) 2014-09-03 17:15:00
time_of_day Hora do dia 17:15
hour Data e hora truncadas para a hora mais próxima 2014-09-03 17
hour_of_day Hora do dia inteira do campo subjacente 17
hourX Divide cada dia em intervalos com o número especificado de horas. Veja uma explicação abaixo. Veja abaixo
minute Data e hora truncadas para o minuto mais próximo 2014-09-03 17:15
minuteX Divide a cada hora em intervalos com o número especificado de minutos. Veja uma explicação abaixo. Veja abaixo
second Data e hora truncadas para o segundo mais próximo 2014-09-03 17:15:00
millisecond Data/hora truncada para o milissegundo mais próximo (consulte a seção Disparar o suporte para milissegundos e microssegundos nesta página para ver informações sobre a compatibilidade com dialeto). 2014-09-03 17:15:00.000
millisecondX Divide cada segundo em intervalos com o número especificado de milissegundos. Consulte a seção Suporte ao dialeto para milissegundos e microssegundos nesta página para ver informações sobre o suporte ao dialeto. Veja uma explicação abaixo. Veja abaixo
microsecond Data e hora truncadas para o microssegundo mais próximo. Consulte a seção Disparar o suporte para milissegundos e microssegundos nesta página para ver informações sobre a compatibilidade com dialeto. 2014-09-03 17:15:00.000000

Períodos de data

Período Descrição Exemplo de saída
date Data do campo subjacente 2017-09-03

Períodos de semana

Período Descrição Exemplo de saída
week Data da semana que começa em uma segunda-feira da data e hora subjacente 2017-09-01
day_of_week Só na semana Wednesday
day_of_week_index Índice da semana (0 = segunda-feira, 6 = domingo) 2

Períodos de mês

Período Descrição Exemplo de saída
month Ano e mês da data e hora subjacentes 2014-09
month_num Número inteiro do mês da data e hora subjacente 9
fiscal_month_num Número inteiro do mês fiscal da data e hora subjacente 6
month_name Nome do mês September
day_of_month Dia do mês 3

Para usar os períodos de fiscal_month_num, o parâmetro fiscal_month_offset precisa ser definido no modelo.

Períodos do trimestre

Período Descrição Exemplo de saída
quarter Ano e trimestre da data e hora subjacentes 2017-Q3
fiscal_quarter Ano e trimestre fiscal da data e hora subjacentes 2017-Q3
quarter_of_year Trimestre do ano precedido por um "Q" Q3
fiscal_quarter_of_year Trimestre fiscal do ano precedido por "Q" Q3

Para usar os períodos fiscal_quarter e fiscal_quarter_of_year, o parâmetro fiscal_month_offset precisa ser definido no modelo.

Períodos dos anos

Período Descrição Exemplo de saída
year Ano inteiro da data e hora subjacente 2017
fiscal_year Ano fiscal inteiro da data e hora subjacente FY2017
day_of_year Dia do ano 143
week_of_year Semana do ano em número 17

Para usar o período fiscal_year, o parâmetro fiscal_month_offset precisa ser definido no modelo.

Como usar hourX

No hourX, o X é substituído por 2, 3, 4, 6, 8 ou 12.

Isso será dividido a cada dia em intervalos com o número especificado de horas. Por exemplo, hour6 será dividido diariamente em segmentos de seis horas, como neste exemplo:

  • 2014-09-01 00:00:00
  • 2014-09-01 06:00:00
  • 2014-09-01 12:00:00
  • 2014-09-01 18:00:00

Para dar um exemplo, uma linha com um time de 2014-09-01 08:03:17 teria um hour6 de 2014-09-01 06:00:00.

Como usar minuteX

No minuteX, o X é substituído por 2, 3, 4, 5, 6, 10, 12, 15, 20 ou 30.

Isso será dividido a cada hora em intervalos com o número especificado de minutos. Por exemplo, minute15 será dividido a cada hora em segmentos de 15 minutos, que serão exibidos da seguinte maneira:

  • 2014-09-01 01:00:00
  • 2014-09-01 01:15:00
  • 2014-09-01 01:30:00
  • 2014-09-01 01:45:00

Para dar um exemplo, uma linha com um time de 2014-09-01 01:17:35 teria um minute15 de 2014-09-01 01:15:00.

Como usar millisecondX

No millisecondX, o X é substituído por 2, 4, 5, 8, 10, 20, 25, 40, 50, 100, 125, 200, 250 ou 500.

Isso vai ser dividido em segundos com o número especificado de milissegundos. Por exemplo, millisecond250 dividirá cada segundo em 250 milissegundos, que serão exibidos da seguinte forma:

  • 2014-09-01 01:00:00.000
  • 2014-09-01 01:00:00.250
  • 2014-09-01 01:00:00.500
  • 2014-09-01 01:00:00.750

Para dar um exemplo, uma linha com um time de 2014-09-01 01:00:00.333 teria um millisecond250 de 2014-09-01 01:00:00.250.

Conversões de fuso horário e convert_tz

Em geral, os cálculos de tempo (diferenças, durações etc.) só funcionam corretamente quando você opera em valores de horário convertidos no mesmo fuso horário. Por isso, é importante ter em mente os fusos horários ao criar LookML.

O Looker tem várias configurações de fuso horário que convertem dados com base no horário entre diferentes fusos horários. Por padrão, o Looker faz a conversão de fuso horário. O parâmetro convert_tz é compatível com grupos de dimensões de type: time. Se você não quiser que o Looker faça uma conversão de fuso horário para uma dimensão ou um grupo de dimensões específico, use o parâmetro convert_tz descrito na página de documentação de parâmetros convert_tz.

Suporte à dialeto para milissegundos e microssegundos

O Looker é compatível com a precisão de tempo até microssegundos. No entanto, alguns bancos de dados são compatíveis com a precisão apenas de segundos. Se um banco de dados encontrar um período mais preciso do que ele consegue suportar, ele será arredondado para segundos.

Na versão mais recente do Looker, os seguintes dialetos são compatíveis com milissegundos:

Na versão mais recente do Looker, os dialetos a seguir são compatíveis com microssegundos:

Como especificar o banco de dados datatype

O parâmetro datatype permite especificar o tipo de dados de tempo na tabela do banco de dados que você está fornecendo ao grupo de dimensões, o que pode melhorar o desempenho da consulta.

Para grupos de dimensões de type: time, o parâmetro datatype se aplica ao parâmetro sql do grupo de dimensões.

Para grupos de dimensões de type: duration, o parâmetro datatype se aplica aos parâmetros sql_start e sql_end. Portanto, verifique se sql_start e sql_end são do tipo de dados especificado.

O parâmetro datatype aceita os seguintes valores:

  • epoch: um campo de época SQL (ou seja, um número inteiro que representa o número de segundos da época Unix).
  • date: um campo de data do SQL (ou seja, um que não contém informações de horário).
  • datetime: um campo de data e hora SQL.
  • timestamp: um campo de carimbo de data/hora SQL.
  • yyyymmdd: um campo SQL que contém um número inteiro que representa uma data no formato YYYYMMDD.

O valor padrão de datatype é timestamp.

Examples

Suponha que você tenha uma coluna chamada created_at que continha informações de data e hora. Você quer criar uma dimensão de data, semana e mês com base nessa data e hora. Você pode usar:

dimension_group: created {
  type: time
  timeframes: [date, week, month]
  sql: ${TABLE}.created_at ;;
}

-

Na IU do Explore, isso geraria três dimensões com os nomes Created Date, Created Week e Created Month. Observe como o nome dimension_group é combinado com os prazos para gerar os nomes das dimensões.

Considerações

Os grupos de dimensões precisam ser referenciados pelas dimensões individuais deles

Como um grupo de dimensões representa um grupo de dimensões, em vez de apenas uma, não é possível fazer referência a ele diretamente no LookML. Em vez disso, você precisará consultar as dimensões criadas.

Por exemplo, considere este grupo de dimensões:

dimension_group: created {
  type: time
  timeframes: [date, week, month]
  sql: ${TABLE}.created_at ;;
}

-

Para se referir a uma dessas dimensões em outro campo LookML, use a referência ${created_date}, ${created_week} ou {$created_month}. Se você tentar usar apenas ${created}, o Looker não vai saber a que intervalo de tempo você está se referindo, o que resultará em um erro.

Por esse mesmo motivo, não use o parâmetro primary_key em um grupo de dimensões se você especificar mais de um timeframe.

Dica da equipe do Chat: perguntamos com frequência sobre erros de validação que ocorrem ao usar o primary_key em um dimension_group com mais de um timeframe. Para mais informações, confira este tópico da Comunidade.

Dados de carimbo de data/hora que incluem informações de fuso horário

Alguns dialetos de banco de dados têm opções de carimbo de data/hora que incluem informações de fuso horário. Isso permite armazenar dados de carimbo de data/hora em um único campo que pode ter vários fusos horários. Uma linha de dados pode ser armazenada em UTC, outra linha no Horário do Leste. Por exemplo, consulte a documentação do carimbo de data/hora TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ de floco de neve para saber mais sobre as opções de carimbo de data/hora do dialeto Snowflake.

Nesse caso, quando o Looker realiza conversões de fuso horário, podem ocorrer erros. Para evitar isso, é necessário transmitir explicitamente os dados do carimbo de data/hora para um tipo de carimbo de data/hora que não faz a conversão de fuso horário no parâmetro sql da dimensão. Por exemplo, no dialeto Snowflake, é possível usar a função TO_TIMESTAMP para transmitir os dados de carimbo de data/hora.

É possível criar dimensões de tempo ou duração individuais

É possível criar uma dimensão para cada período ou duração individual que você quiser incluir, em vez de gerar todas elas em uma única dimension_group. Em geral, é possível evitar a criação de dimensões individuais, a menos que você queira alterar a convenção de nomenclatura do período do Looker ou se já tiver pré-calculado colunas de tempo no seu banco de dados. Para mais informações, consulte a página de documentação Tipos de dimensão, filtro e parâmetro.

Você pode mudar o primeiro dia da semana

Por padrão, as semanas do Looker começam na segunda-feira. É possível mudar isso usando o parâmetro week_start_day no nível do modelo.

O week_start_day não funciona com o período week_of_year, porque ele se baseia no padrão ISO, que usa semanas de segunda-feira.

Filtros e campos personalizados não são compatíveis com todos os períodos.

No momento, os períodos day_of_week, fiscal_quarter_of_year, millisecond, millisecondX, microsecond, month_name, quarter_of_year e time_of_day não são compatíveis com filtros personalizados ou campos personalizados.

Intervalos de mês, trimestre e ano contam apenas períodos completos

O intervalo month em um grupo de dimensões duration considera apenas um mês como passado se o dia final for maior ou igual ao dia inicial. Exemplo:

  • A diferença em meses entre 26 de setembro e 25 de outubro do mesmo ano é 0.
  • A diferença em meses entre 26 de setembro e 26 de outubro do mesmo ano é 1.

Os intervalos quarter e year seguem a mesma lógica.