Funções de data e hora¶

Esta família de funções pode ser usada para construir, converter, extrair ou modificar dados DATE/TIME/TIMESTAMP.

Neste tópico:

Lista de funções¶

Subcategoria	Função	Notas
Construção	DATE_FROM_PARTS
	TIME_FROM_PARTS
	TIMESTAMP_FROM_PARTS
Extração	DATE_PART	Aceita todas as partes de data e hora (consulte a próxima seção para detalhes).
	DAYNAME
	EXTRACT	Alternativa para DATE_PART.
	HOUR / MINUTE / SECOND	Alternativa para DATE_PART.
	LAST_DAY	Aceita partes relevantes de datas (consulte a próxima seção para detalhes).
	MONTHNAME
	NEXT_DAY
	PREVIOUS_DAY
	YEAR* / DAY* / WEEK* / MONTH / QUARTER	Alternativa para DATE_PART.
Adição/Subtração	ADD_MONTHS
	DATEADD	Aceita partes relevantes de data e hora (consulte a próxima seção para detalhes).
	DATEDIFF	Aceita partes relevantes de data e hora (consulte a próxima seção para detalhes).
	MONTHS_BETWEEN
	TIMEADD	Alias para DATEADD.
	TIMEDIFF	Alias para DATEDIFF.
	TIMESTAMPADD	Alias para DATEADD.
	TIMESTAMPDIFF	Alias para DATEDIFF.
Truncamento**	DATE_TRUNC	Aceita partes relevantes de data e hora (consulte a próxima seção para detalhes).
	TIME_SLICE	Permite que a hora seja “arredondada” até o início de um intervalo de tempo igualmente espaçado.
	TRUNC	Alternativa para DATE_TRUNC.
Conversão	TO_DATE , DATE
	TO_TIME , TIME
	TO_TIMESTAMP / TO_TIMESTAMP_*
Fuso horário	CONVERT_TIMEZONE
Alertas*	LAST_SUCCESSFUL_SCHEDULED_TIME
Alertas*	SCHEDULED_TIME

Partes de data e hora com suporte¶

Algumas funções (assim como aliases e alternativas apropriadas) aceitam como argumento uma parte da data ou hora. As duas tabelas a seguir listam as partes (sem diferenciar maiúsculas e minúsculas) que podem ser usadas com estas funções.

Partes de data	Abreviações/Variações	DATEADD	DATEDIFF	DATE_PART	DATE_TRUNC	LAST_DAY
`year`	`y` , `yy` , `yyy` , `yyyy` , `yr` , `years` , `yrs`	✔	✔	✔	✔	✔
`month`	`mm` , `mon` , `mons` , `months`	✔	✔	✔	✔	✔
`day`	`d` , `dd` , `days`, `dayofmonth`	✔	✔	✔	✔
`dayofweek` ^[1]	`weekday` , `dow` , `dw`			✔
`dayofweekiso` ^[2]	`weekday_iso` , `dow_iso` , `dw_iso`			✔
`dayofyear`	`yearday` , `doy` , `dy`			✔
`week` ^[1]	`w` , `wk` , `weekofyear` , `woy` , `wy`	✔	✔	✔	✔	✔
`weekiso` ^[2]	`week_iso` , `weekofyeariso` , `weekofyear_iso`			✔
`quarter`	`q` , `qtr` , `qtrs` , `quarters`	✔	✔	✔	✔	✔
`yearofweek` ^[1]				✔
`yearofweekiso` ^[2]				✔

_{[1] Para detalhes de uso, consulte a próxima seção, que descreve como o Snowflake trata semanas do calendário e dias úteis.}

_{[2] Não controlado pelos parâmetros de sessão WEEK_START e WEEK_OF_YEAR_POLICY, conforme descrito na próxima seção.}

Partes de hora	Abreviações/Variações	DATEADD	DATEDIFF	DATE_PART	DATE_TRUNC
`hour`	`h` , `hh` , `hr` , `hours` , `hrs`	✔	✔	✔	✔
`minute`	`m` , `mi` , `min` , `minutes` , `mins`	✔	✔	✔	✔
`second`	`s` , `sec` , `seconds` , `secs`	✔	✔	✔	✔
`millisecond`	`ms` , `msec` , `milliseconds`	✔	✔		✔
`microsecond`	`us` , `usec` , `microseconds`	✔	✔		✔
`nanosecond`	`ns` , `nsec` , `nanosec` , `nsecond` , `nanoseconds` , `nanosecs` , `nseconds`	✔	✔	✔	✔
`epoch_second`	`epoch` , `epoch_seconds`			✔
`epoch_millisecond`	`epoch_milliseconds`			✔
`epoch_microsecond`	`epoch_microseconds`			✔
`epoch_nanosecond`	`epoch_nanoseconds`			✔
`timezone_hour`	`tzh`			✔
`timezone_minute`	`tzm`			✔

Semanas de calendário e dias úteis¶

O comportamento das funções relacionadas à semana no Snowflake é controlado pelos parâmetros de sessão WEEK_START e WEEK_OF_YEAR_POLICY. Um aspecto importante para entender como esses parâmetros interagem é o conceito de semanas ISO.

Semanas ISO¶

Como definido na norma ISO 8601 (para formatos de datas e horas), as semanas ISO sempre começam na segunda-feira e “pertencem” ao ano que contém a quinta-feira daquela semana. Isto significa que um dia em um ano pode pertencer a uma semana em um ano diferente:

Para dias no início de janeiro, o valor WOY (semana do ano) pode ser 52 ou 53 (ou seja, o dia pertence à última semana do ano anterior).
Para dias no final de dezembro, o valor WOY pode ser 1 (ou seja, o dia pertence à primeira semana do ano seguinte).

O Snowflake fornece um conjunto especial de funções de datas relacionadas à semana (e partes de datas equivalentes) cujo comportamento é consistente com a semântica da semana ISO: DAYOFWEEKISO , WEEKISO , YEAROFWEEKISO.

Essas funções (e partes de datas) desconsideram os parâmetros de sessão (ou seja, sempre seguem a semântica ISO).

Para obter mais detalhes sobre como todas as outras funções de datas relacionadas à semana são tratadas, consulte as seções seguintes (neste tópico).

Primeiro dia da semana¶

A maioria das funções relacionadas à semana são controladas apenas pelo parâmetro de sessão WEEK_START. Observe que os resultados da função diferem dependendo de como o parâmetro é definido:

Função	Parâmetro definido como `0` (comportamento padrão/herdado)	Parâmetro ajustado para `1` - `7` (segunda-feira - domingo)
DAYOFWEEK	Retorna `0` (domingo) a `6` (sábado).	Retorna `1` (primeiro dia definido da semana) a `7` (último dia da semana em relação ao primeiro dia definido).
DATE_TRUNC (com uma parte `WEEK`)	Trunca a semana de entrada para começar na segunda-feira.	Trunca a semana de entrada para começar no primeiro dia definido da semana.
LAST_DAY (com uma parte `WEEK`)	Retorna o domingo da semana de entrada.	Retorna o último dia da semana de entrada em relação ao primeiro dia definido da semana.
DATEDIFF (com uma parte `WEEK`)	Calculado usando semanas que começam na segunda-feira.	Calculado usando semanas que começam no primeiro dia definido da semana.

Dica

O valor padrão para o parâmetro é 0, que preserva o comportamento herdado do Snowflake (semântica similar ao ISO); entretanto, recomendamos alterar este valor para controlar explicitamente o comportamento resultante das funções. Com base no feedback que recebemos, o cenário mais comum é definir o parâmetro para 1.

Primeiras/últimas semanas do ano¶

O parâmetro de sessão WEEK_OF_YEAR_POLICY controla como as funções WEEK e YEAROFWEEK se comportam. O parâmetro pode ter dois valores:

0: as funções afetadas relacionadas à semana usam uma semântica semelhante à semântica ISO, na qual uma semana pertence a um determinado ano se pelo menos 4 dias dessa semana estiverem nesse ano. Isto significa que todas as semanas têm 7 dias, mas os primeiros dias de janeiro e os últimos dias de dezembro podem pertencer a uma semana em um ano diferente. Por isso, as funções YEAROFWEEK e YEAROFWEEKISO podem fornecer o ano ao qual a semana pertence.
1: 1.º de janeiro sempre inicia a primeira semana do ano e 31 de dezembro está sempre na última semana do ano. Isto significa que a primeira semana e a última semana do ano podem ter menos de 7 dias.

Note que esse comportamento também é influenciado pelo dia de início da semana, como controlado pelo valor definido para o parâmetro de sessão WEEK_START:

0 , 1: o comportamento é equivalente à semântica da semana ISO, com a semana começando na segunda-feira.
2 a 7: a lógica de “4 dias” é mantida, mas o primeiro dia da semana é diferente.

Dica

O valor padrão para ambos os parâmetros é 0, o que preserva o comportamento herdado do Snowflake (semântica similar ao ISO); entretanto, recomendamos alterar estes valores para controlar explicitamente o comportamento resultante das funções. Com base no feedback que recebemos, o cenário mais comum é definir ambos os parâmetros para 1.

Exemplos¶

Nota

Estes exemplos consultam o mesmo conjunto de funções de data, mas com valores diferentes definidos para os parâmetros de sessão WEEK_OF_YEAR_POLICY e WEEK_START para ilustrar como eles influenciam os resultados das funções.

Controle do primeiro dia da semana¶

A configuração WEEK_START como 0 (comportamento herdado) ou 1 (segunda-feira) não tem um efeito significativo, como ilustrado nos dois exemplos a seguir:

ALTER SESSION SET WEEK_START = 0;

SELECT d "Date", DAYNAME(d) "Day",
       DAYOFWEEK(d) "DOW",
       DATE_TRUNC('week', d) "Trunc Date",
       DAYNAME("Trunc Date") "Trunc Day",
       LAST_DAY(d, 'week') "Last DOW Date",
       DAYNAME("Last DOW Date") "Last DOW Day",
       DATEDIFF('week', '2017-01-01', d) "Weeks Diff from 2017-01-01 to Date"
FROM week_examples;

+------------+-----+-----+------------+-----------+---------------+--------------+------------------------------------+
| Date       | Day | DOW | Trunc Date | Trunc Day | Last DOW Date | Last DOW Day | Weeks Diff from 2017-01-01 to Date |
|------------+-----+-----+------------+-----------+---------------+--------------+------------------------------------|
| 2016-12-30 | Fri |   5 | 2016-12-26 | Mon       | 2017-01-01    | Sun          |                                  0 |
| 2016-12-31 | Sat |   6 | 2016-12-26 | Mon       | 2017-01-01    | Sun          |                                  0 |
| 2017-01-01 | Sun |   0 | 2016-12-26 | Mon       | 2017-01-01    | Sun          |                                  0 |
| 2017-01-02 | Mon |   1 | 2017-01-02 | Mon       | 2017-01-08    | Sun          |                                  1 |
| 2017-01-03 | Tue |   2 | 2017-01-02 | Mon       | 2017-01-08    | Sun          |                                  1 |
| 2017-01-04 | Wed |   3 | 2017-01-02 | Mon       | 2017-01-08    | Sun          |                                  1 |
| 2017-01-05 | Thu |   4 | 2017-01-02 | Mon       | 2017-01-08    | Sun          |                                  1 |
| 2017-12-30 | Sat |   6 | 2017-12-25 | Mon       | 2017-12-31    | Sun          |                                 52 |
| 2017-12-31 | Sun |   0 | 2017-12-25 | Mon       | 2017-12-31    | Sun          |                                 52 |
+------------+-----+-----+------------+-----------+---------------+--------------+------------------------------------+

ALTER SESSION SET WEEK_START = 1;

SELECT d "Date", DAYNAME(d) "Day",
       DAYOFWEEK(d) "DOW",
       DATE_TRUNC('week', d) "Trunc Date",
       DAYNAME("Trunc Date") "Trunc Day",
       LAST_DAY(d, 'week') "Last DOW Date",
       DAYNAME("Last DOW Date") "Last DOW Day",
       DATEDIFF('week', '2017-01-01', d) "Weeks Diff from 2017-01-01 to Date"
FROM week_examples;

+------------+-----+-----+------------+-----------+---------------+--------------+------------------------------------+
| Date       | Day | DOW | Trunc Date | Trunc Day | Last DOW Date | Last DOW Day | Weeks Diff from 2017-01-01 to Date |
|------------+-----+-----+------------+-----------+---------------+--------------+------------------------------------|
| 2016-12-30 | Fri |   5 | 2016-12-26 | Mon       | 2017-01-01    | Sun          |                                  0 |
| 2016-12-31 | Sat |   6 | 2016-12-26 | Mon       | 2017-01-01    | Sun          |                                  0 |
| 2017-01-01 | Sun |   7 | 2016-12-26 | Mon       | 2017-01-01    | Sun          |                                  0 |
| 2017-01-02 | Mon |   1 | 2017-01-02 | Mon       | 2017-01-08    | Sun          |                                  1 |
| 2017-01-03 | Tue |   2 | 2017-01-02 | Mon       | 2017-01-08    | Sun          |                                  1 |
| 2017-01-04 | Wed |   3 | 2017-01-02 | Mon       | 2017-01-08    | Sun          |                                  1 |
| 2017-01-05 | Thu |   4 | 2017-01-02 | Mon       | 2017-01-08    | Sun          |                                  1 |
| 2017-12-30 | Sat |   6 | 2017-12-25 | Mon       | 2017-12-31    | Sun          |                                 52 |
| 2017-12-31 | Sun |   7 | 2017-12-25 | Mon       | 2017-12-31    | Sun          |                                 52 |
+------------+-----+-----+------------+-----------+---------------+--------------+------------------------------------+

Copy

Com WEEK_START definido como 0, o DOW para domingo é 0.
Com WEEK_START definido como 1, o DOW para domingo é 7.

Os resultados diferem mais significativamente se WEEK_START for definido como qualquer dia que não seja segunda-feira. Por exemplo, definir o parâmetro para 3 (quarta-feira) altera os resultados de todas as funções relacionadas à semana (colunas 3 a 8):

ALTER SESSION SET WEEK_START = 3;

SELECT d "Date", DAYNAME(d) "Day",
       DAYOFWEEK(d) "DOW",
       DATE_TRUNC('week', d) "Trunc Date",
       DAYNAME("Trunc Date") "Trunc Day",
       LAST_DAY(d, 'week') "Last DOW Date",
       DAYNAME("Last DOW Date") "Last DOW Day",
       DATEDIFF('week', '2017-01-01', d) "Weeks Diff from 2017-01-01 to Date"
FROM week_examples;

+------------+-----+-----+------------+-----------+---------------+--------------+------------------------------------+
| Date       | Day | DOW | Trunc Date | Trunc Day | Last DOW Date | Last DOW Day | Weeks Diff from 2017-01-01 to Date |
|------------+-----+-----+------------+-----------+---------------+--------------+------------------------------------|
| 2016-12-30 | Fri |   3 | 2016-12-28 | Wed       | 2017-01-03    | Tue          |                                  0 |
| 2016-12-31 | Sat |   4 | 2016-12-28 | Wed       | 2017-01-03    | Tue          |                                  0 |
| 2017-01-01 | Sun |   5 | 2016-12-28 | Wed       | 2017-01-03    | Tue          |                                  0 |
| 2017-01-02 | Mon |   6 | 2016-12-28 | Wed       | 2017-01-03    | Tue          |                                  0 |
| 2017-01-03 | Tue |   7 | 2016-12-28 | Wed       | 2017-01-03    | Tue          |                                  0 |
| 2017-01-04 | Wed |   1 | 2017-01-04 | Wed       | 2017-01-10    | Tue          |                                  1 |
| 2017-01-05 | Thu |   2 | 2017-01-04 | Wed       | 2017-01-10    | Tue          |                                  1 |
| 2017-12-30 | Sat |   4 | 2017-12-27 | Wed       | 2018-01-02    | Tue          |                                 52 |
| 2017-12-31 | Sun |   5 | 2017-12-27 | Wed       | 2018-01-02    | Tue          |                                 52 |
+------------+-----+-----+------------+-----------+---------------+--------------+------------------------------------+

Copy

Controle do ano e dos dias para as primeiras/últimas semanas do ano¶

O exemplo a seguir define ambos os parâmetros como 0 para seguir a semântica similar ao ISO (ou seja, a semana começa na segunda-feira e todas as semanas têm 7 dias):

ALTER SESSION SET WEEK_OF_YEAR_POLICY=0, WEEK_START=0;

SELECT d "Date", DAYNAME(d) "Day",
       WEEK(d) "WOY",
       WEEKISO(d) "WOY (ISO)",
       YEAROFWEEK(d) "YOW",
       YEAROFWEEKISO(d) "YOW (ISO)"
FROM week_examples;

+------------+-----+-----+-----------+------+-----------+
| Date       | Day | WOY | WOY (ISO) |  YOW | YOW (ISO) |
|------------+-----+-----+-----------+------+-----------|
| 2016-12-30 | Fri |  52 |        52 | 2016 |      2016 |
| 2016-12-31 | Sat |  52 |        52 | 2016 |      2016 |
| 2017-01-01 | Sun |  52 |        52 | 2016 |      2016 |
| 2017-01-02 | Mon |   1 |         1 | 2017 |      2017 |
| 2017-01-03 | Tue |   1 |         1 | 2017 |      2017 |
| 2017-01-04 | Wed |   1 |         1 | 2017 |      2017 |
| 2017-01-05 | Thu |   1 |         1 | 2017 |      2017 |
| 2017-12-30 | Sat |  52 |        52 | 2017 |      2017 |
| 2017-12-31 | Sun |  52 |        52 | 2017 |      2017 |
+------------+-----+-----+-----------+------+-----------+

Copy

O próximo exemplo ilustra o efeito de manter WEEK_OF_YEAR_POLICY como 0, mas mudar WEEK_START para 3 (quarta-feira):

ALTER SESSION SET WEEK_OF_YEAR_POLICY=0, WEEK_START=3;

SELECT d "Date", DAYNAME(d) "Day",
       WEEK(d) "WOY",
       WEEKISO(d) "WOY (ISO)",
       YEAROFWEEK(d) "YOW",
       YEAROFWEEKISO(d) "YOW (ISO)"
FROM week_examples;

+------------+-----+-----+-----------+------+-----------+
| Date       | Day | WOY | WOY (ISO) |  YOW | YOW (ISO) |
|------------+-----+-----+-----------+------+-----------|
| 2016-12-30 | Fri |  53 |        52 | 2016 |      2016 |
| 2016-12-31 | Sat |  53 |        52 | 2016 |      2016 |
| 2017-01-01 | Sun |  53 |        52 | 2016 |      2016 |
| 2017-01-02 | Mon |  53 |         1 | 2016 |      2017 |
| 2017-01-03 | Tue |  53 |         1 | 2016 |      2017 |
| 2017-01-04 | Wed |   1 |         1 | 2017 |      2017 |
| 2017-01-05 | Thu |   1 |         1 | 2017 |      2017 |
| 2017-12-30 | Sat |  52 |        52 | 2017 |      2017 |
| 2017-12-31 | Sun |  52 |        52 | 2017 |      2017 |
+------------+-----+-----+-----------+------+-----------+

Copy

2016 agora tem 53 semanas (em vez de 52).
WOY como 1.º de jan, 2017 passa para a semana 53 (de 52).
WOY como 2 e 3 de jan, 2017 passa para a semana 53 (de 1).
YOW como 2 e 3 de jan, 2017 passa para 2016 (de 2017).
WOY (ISO) e YOW (ISO) não são afetados pela mudança de parâmetro.

Os dois últimos exemplos definem WEEK_OF_YEAR_POLICY como 1 e definem WEEK_START primeiro como 1 (segunda-feira) e depois como 3 (quarta-feira):

ALTER SESSION SET WEEK_OF_YEAR_POLICY=1, WEEK_START=1;

SELECT d "Date", DAYNAME(d) "Day",
       WEEK(d) "WOY",
       WEEKISO(d) "WOY (ISO)",
       YEAROFWEEK(d) "YOW",
       YEAROFWEEKISO(d) "YOW (ISO)"
FROM week_examples;

+------------+-----+-----+-----------+------+-----------+
| Date       | Day | WOY | WOY (ISO) |  YOW | YOW (ISO) |
|------------+-----+-----+-----------+------+-----------|
| 2016-12-30 | Fri |  53 |        52 | 2016 |      2016 |
| 2016-12-31 | Sat |  53 |        52 | 2016 |      2016 |
| 2017-01-01 | Sun |   1 |        52 | 2017 |      2016 |
| 2017-01-02 | Mon |   2 |         1 | 2017 |      2017 |
| 2017-01-03 | Tue |   2 |         1 | 2017 |      2017 |
| 2017-01-04 | Wed |   2 |         1 | 2017 |      2017 |
| 2017-01-05 | Thu |   2 |         1 | 2017 |      2017 |
| 2017-12-30 | Sat |  53 |        52 | 2017 |      2017 |
| 2017-12-31 | Sun |  53 |        52 | 2017 |      2017 |
+------------+-----+-----+-----------+------+-----------+

alter session set week_of_year_policy=1, week_start=3;

SELECT d "Date", DAYNAME(d) "Day",
       WEEK(d) "WOY",
       WEEKISO(d) "WOY (ISO)",
       YEAROFWEEK(d) "YOW",
       YEAROFWEEKISO(d) "YOW (ISO)"
FROM week_examples;

+------------+-----+-----+-----------+------+-----------+
| Date       | Day | WOY | WOY (ISO) |  YOW | YOW (ISO) |
|------------+-----+-----+-----------+------+-----------|
| 2016-12-30 | Fri |  53 |        52 | 2016 |      2016 |
| 2016-12-31 | Sat |  53 |        52 | 2016 |      2016 |
| 2017-01-01 | Sun |   1 |        52 | 2017 |      2016 |
| 2017-01-02 | Mon |   1 |         1 | 2017 |      2017 |
| 2017-01-03 | Tue |   1 |         1 | 2017 |      2017 |
| 2017-01-04 | Wed |   2 |         1 | 2017 |      2017 |
| 2017-01-05 | Thu |   2 |         1 | 2017 |      2017 |
| 2017-12-30 | Sat |  53 |        52 | 2017 |      2017 |
| 2017-12-31 | Sun |  53 |        52 | 2017 |      2017 |
+------------+-----+-----+-----------+------+-----------+

Copy

Com WEEK_OF_YEAR_POLICY definida como 1 e WEEK_START definido como 1 (segunda-feira):
- WOY para 2017-01-01 é 1.
- A semana 1 consiste em 1 dia.
- A semana 2 começa na Mon.
Note que este é o cenário de uso mais comum, com base no feedback que recebemos.
Com WEEK_OF_YEAR_POLICY definida como 1 e WEEK_START definido como 3 (quarta-feira):
- WOY para 2017-01-01 ainda é 1.
- A semana 1 consiste em 3 dias.
- A semana 2 começa na Wed.

Em ambos os exemplos, WOY (ISO) e YOW (ISO) não são afetados pela mudança de parâmetro.