Uso
view: view_name {
dimension_group: field_name { ... }
}
|
Hierarquia
dimension_group |
Aceita
Um identificador do Looker (para servir como a primeira parte do nome de cada dimensão criada pelo grupo de dimensões)
Regras especiais
|
Definição
O parâmetro dimension_group é usado para criar um conjunto de dimensões com base em tempo ou duração de uma só vez. Você define o grupo de dimensões, que cria um conjunto de dimensões individuais para diferentes intervalos ou períodos. Por exemplo, é possível especificar um grupo de dimensões de type: time com base em uma coluna de carimbo de data/hora. Assim, o grupo cria dimensões correspondentes para expressar os dados em tempo, data, semana, hora, trimestre e ano.
A forma e a função do grupo de dimensões variam de acordo com o valor type:
Grupos de dimensões de tipo de duração
type: duration é usado com um 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, …] # see following explanation for valid intervals
}
Para grupos de dimensões de type: duration:
Os parâmetros
sql_startesql_endfornecem expressões SQL que definem o horário de início e de término da duração. Consulte a seção Como definir o início e o fim de uma duração nesta página para mais detalhes.O parâmetro
intervalsespecifica uma ou mais unidades de intervalo que devem ser usadas para medir a diferença de tempo. As opções possíveis estão listadas na seção Opções de intervalo desta página.Os valores de duração são arredondados para baixo até 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, especifique uma época, um carimbo de data/hora, uma data ou um formato aaaammdd. Para grupos de dimensões detype: duration, o parâmetrodatatypese aplica aos parâmetrossql_startesql_end. Portanto, verifique sesql_startesql_endsão do tipo de dados especificado. O parâmetrodatatypeé descrito com mais detalhes na seção Especificar odatatypedo banco de dados 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, se você tiver colunas para enrollment_date e graduation_date, poderá criar um grupo de dimensões de duração para saber quanto tempo os estudantes passaram na escola, calculado 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 interface "Explorar", isso geraria um grupo de dimensões chamado Duração da inscrição, com dimensões individuais chamadas Semanas de inscrição e Anos de inscrição.
Opções de intervalo
O parâmetro intervals informa ao grupo de dimensões quais unidades de intervalo ele deve usar para medir a diferença de tempo entre os horários sql_start e sql_end. O parâmetro intervals é compatível apenas com grupos de dimensões de type: duration.
Se intervals não for incluído, o grupo de dimensões vai incluir todos os intervalos possíveis.
As opções para o parâmetro intervals são:
| Intervalo | Descrição | Exemplo de resposta |
|---|---|---|
day |
Calcula uma diferença de tempo em dias. | 9 days |
hour |
Calcula uma diferença de tempo em horas. | 171 hours |
minute |
Calcula uma diferença de tempo em minutos. | 10305 minutes |
month |
Calcula uma diferença de tempo em meses. | 3 months |
quarter |
Calcula uma diferença de tempo em trimestres do ano. | 2 quarters |
second |
Calcula uma diferença de tempo em segundos. | 606770 seconds |
week |
Calcula uma diferença de tempo em semanas. | 6 weeks |
year |
Calcula uma diferença de tempo 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 fim usadas para calcular uma diferença de tempo. Esses campos podem receber qualquer expressão SQL válida que contenha dados em um formato de carimbo de data/hora, data/hora, data, época ou aaaammdd. Os campos sql_start e sql_end podem ser qualquer um dos seguintes:
- Uma referência a um período
rawde um grupo de dimensõestype: 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 adequada para seu dialeto
- Uma referência de campo do LookML usando a referência de tipo de campo
::datetimeou::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 ;;
}
Você pode criar um grupo de dimensões de type: duration que calcula o tempo decorrido desde a data do evento da FAA. Para isso, use a dimensão faa_event_date_raw como o horário de início do cálculo e a expressão SQL do seu dialeto para o horário atual como o horário de término. Este exemplo é para 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 interface "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.
Referenciar intervalos de outro campo da LookML
Para fazer referência a um valor interval em um dimension_group de type: duration, use a sintaxe ${interval_fieldname}, usando a versão no plural do valor interval. Por exemplo, no exemplo de LookML a seguir, a métrica average_days_since_event usa ${days_since_event} para referenciar o 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 do LookML com campos de duração
Para criar um campo de duração personalizada, 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 de documentação Incorporar SQL e referenciar objetos do LookML, permite criar uma versão ::date ou ::datetime de um campo sem converter as referências a essas dimensões em 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, você pode criar um grupo de dimensões type: duration que calcula o período entre uma data do campo created_date e o primeiro dia do mês em que essa data ocorreu, medido 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 interface de análise detalhada, isso cria um grupo de dimensões chamado Duração desde o primeiro dia do mês, com dimensões individuais Semanas desde o primeiro dia do mês, Dias desde o primeiro dia do mês e Horas desde o primeiro dia do 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 Data de criação for 2019-03-10, o valor retornado para Dias desde o primeiro dia do mês será 9 dias.
Grupos de dimensões de tipo de tempo
O type: time é usado com um dimension_group e o parâmetro timeframes para criar um conjunto de dimensões baseadas em tempo. Por exemplo, é fácil criar 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, …] # see following explanation for valid timeframes
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. Ele especifica um ou mais períodos que devem ser gerados pelo grupo de dimensões. Setimeframesnão estiver incluído, todas as opções de período serão adicionadas ao grupo de dimensões. As opções possíveis estão listadas na seção Opções de período desta página.O parâmetro
sqlpara grupos de dimensõestype: timepode usar qualquer expressão SQL válida que contenha dados em um carimbo de data/hora, data/hora, data, época ou formato aaaammdd.O parâmetro
datatypeé opcional. Se o grupo de dimensões não for baseado em uma data e hora, especifique uma época, um carimbo de data/hora, uma data ou um formato aaaammdd. Ele é descrito em mais detalhes na seção Especificar o banco de dadosdatatypenesta página.O parâmetro
convert_tzé opcional e permite evitar a conversão automática de fuso horário. Ela é descrita em mais detalhes na seção Conversões de fuso horário econvert_tznesta 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 contenha informações de data e hora. Você quer criar uma dimensão de data, semana e mês com base nessa data e hora. É possível usar:
dimension_group: created {
type: time
timeframes: [date, week, month]
sql: ${TABLE}.created_at ;;
}
Na interface do recurso "Explorar", isso geraria três dimensões com os nomes Data de criação, Semana de criação e Mês de criação. Observe como o nome dimension_group é combinado com os períodos 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 gerar e inclui as seguintes opções:
- Períodos especiais
- Períodos
- Períodos
- Períodos semanais
- Períodos mensais
- Períodos trimestrais
- Períodos anuais
hourXperíodosminuteXperíodosmillisecondXperíodos
Períodos especiais
Períodos
| Período | Descrição | Exemplo de resposta |
|---|---|---|
time |
Data e hora do campo subjacente. Alguns dialetos SQL mostram a mesma precisão que o banco de dados, enquanto outros mostram apenas até 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 inteira do dia do campo subjacente | 17 |
hourX |
Divide cada dia em intervalos com o número especificado de horas. | Consulte Como usar hourX. |
minute |
Data e hora truncadas para o minuto mais próximo | 2014-09-03 17:15 |
minuteX |
Divide cada hora em intervalos com o número especificado de minutos. | Consulte Como usar minuteX. |
second |
Data e hora truncadas para o segundo mais próximo | 2014-09-03 17:15:00 |
millisecond |
Data e hora truncadas para o milissegundo mais próximo. Consulte a seção Suporte a dialetos para milissegundos e microssegundos nesta página para mais informações. | 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 a dialetos para milissegundos e microssegundos nesta página para mais informações. | Consulte Como usar millisecondX. |
microsecond |
Data e hora truncadas para o microssegundo mais próximo. Consulte a seção Suporte a dialetos para milissegundos e microssegundos nesta página para mais informações. | 2014-09-03 17:15:00.000000 |
Períodos de data e hora
| Período | Descrição | Exemplo de resposta |
|---|---|---|
date |
Data do campo subjacente | 2017-09-03 |
Períodos semanais
Períodos mensais
Para usar os períodos fiscal_month_num, o parâmetro fiscal_month_offset precisa ser definido no modelo.
Períodos trimestrais
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 anuais
Para usar o período fiscal_year, o parâmetro fiscal_month_offset precisa ser definido no modelo.
Como usar o hourX
Em hourX, o X é substituído por 2, 3, 4, 6, 8 ou 12.
Isso vai dividir cada dia em intervalos com o número especificado de horas. Por exemplo, hour6 divide cada dia em segmentos de 6 horas, que aparecem da seguinte forma:
2014-09-01 00:00:002014-09-01 06:00:002014-09-01 12:00:002014-09-01 18:00:00
Por 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 o minuteX
Em minuteX, X é substituído por 2, 3, 4, 5, 6, 10, 12, 15, 20 ou 30.
Isso vai dividir cada hora em intervalos com o número especificado de minutos. Por exemplo, minute15 divide cada hora em segmentos de 15 minutos, que aparecem da seguinte forma:
2014-09-01 01:00:002014-09-01 01:15:002014-09-01 01:30:002014-09-01 01:45:00
Por 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 o millisecondX
Em millisecondX, X é substituído por 2, 4, 5, 8, 10, 20, 25, 40, 50, 100, 125, 200, 250 ou 500.
Isso vai dividir cada segundo em intervalos com o número especificado de milissegundos. Por exemplo, millisecond250 divide cada segundo em segmentos de 250 milissegundos, que aparecem da seguinte forma:
2014-09-01 01:00:00.0002014-09-01 01:00:00.2502014-09-01 01:00:00.5002014-09-01 01:00:00.750
Por 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 tempo que são convertidos para o mesmo fuso horário. Por isso, é importante ter fusos horários em mente ao escrever LookML.
O Looker tem várias configurações de fuso horário que convertem dados com base em tempo entre diferentes fusos horários. O Looker faz a conversão de fuso horário por padrão. 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 determinada dimensão ou grupo de dimensões, use o parâmetro convert_tz descrito na página de documentação do parâmetro convert_tz.
Suporte a dialetos para milissegundos e microssegundos
O Looker é compatível com a precisão de período até microssegundos, mas alguns bancos de dados só aceitam precisão até o segundo. Se um banco de dados encontrar um período mais preciso do que ele pode oferecer suporte, ele vai arredondar para segundos.
Na versão mais recente do Looker, os seguintes dialetos são compatíveis com milissegundos:
| 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+ | |
| 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 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 |
Na versão mais recente do Looker, os seguintes dialetos são compatíveis com microssegundos:
| 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+ | |
| 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 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 |
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 aumentar 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 desde a época do Unix).date: um campo de data SQL (ou seja, um que não contém informações de hora do dia).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 AAAAMMDD.
O valor padrão de datatype é timestamp.
Exemplos
Suponha que você tenha uma coluna chamada created_at que contenha informações de data e hora. Você quer criar uma dimensão de data, semana e mês com base nessa data e hora. É possível usar:
dimension_group: created {
type: time
timeframes: [date, week, month]
sql: ${TABLE}.created_at ;;
}
-
Na interface do recurso "Explorar", isso geraria três dimensões com os nomes Data de criação, Semana de criação e Mês de criação. Observe como o nome dimension_group é combinado com os períodos para gerar os nomes das dimensões.
Informações importantes
Os grupos de dimensões precisam ser referenciados pelas dimensões individuais
Como um grupo de dimensões representa um grupo de dimensões, e não apenas uma, não é possível se referir a ele diretamente em LookML. Em vez disso, consulte as dimensões que ele cria.
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 do LookML, use a referência ${created_date}, ${created_week} ou ${created_month}. Se você tentar usar apenas ${created}, o Looker não saberá a que período você está se referindo, e um erro vai ocorrer.
Pelo mesmo motivo, não use o parâmetro primary_key em um grupo de dimensões se especificar mais de um timeframe.
Dica da equipe de chat: recebemos muitas perguntas sobre o erro de validação que pode ocorrer se você estiver usando
primary_keyem umdimension_groupcom mais de umtimeframe. Para mais informações, confira a postagem na comunidade Períodos e grupos de dimensões no Looker .
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 e outra no horário do leste. Por exemplo, consulte a documentação de carimbo de data/hora TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ do Snowflake para informações sobre as opções de carimbo de data/hora do dialeto do Snowflake.
Nesse caso, quando o Looker realiza conversões de fuso horário, podem ocorrer erros. Para evitar isso, no parâmetro sql da dimensão, converta explicitamente os dados de carimbo de data/hora para um tipo que não faça a conversão de fuso horário. Por exemplo, no dialeto Snowflake, é possível usar a função TO_TIMESTAMP para converter os dados de carimbo de data/hora.
É possível criar dimensões individuais de tempo ou duração
É possível criar uma dimensão para cada período ou duração que você quer incluir, em vez de gerar todas em um único dimension_group. Em geral, é possível evitar a criação de dimensões individuais, a menos que você queira mudar a convenção de nomenclatura de período do Looker ou já tenha colunas de tempo pré-calculadas no banco de dados. Para mais informações, consulte a página de documentação Tipos de dimensões, filtros e parâmetros.
É possível mudar o primeiro dia da semana
Por padrão, as semanas no Looker começam na segunda-feira. Para mudar isso, use o parâmetro week_start_day no nível do modelo.
Lembre-se de que week_start_day não funciona com o período week_of_year porque ele se baseia no norma ISO, que usa semanas de segunda-feira.
Os filtros e campos personalizados não são compatíveis com todos os períodos
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 nem campos personalizados.
Os intervalos de mês, trimestre e ano só contam períodos completos
O intervalo month em um grupo de dimensões duration só considera que um mês se passou se o dia de término for maior ou igual ao dia de início.
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.