Funções de data e hora

Esta família de funções pode ser usada para construir, converter, extrair ou modificar dados de data, hora e carimbo de data/hora.

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 Partes de data e hora com suporte).

DAYNAME

EXTRACT

Alternativa para DATE_PART.

HOUR / MINUTE / SECOND

Alternativa para DATE_PART.

LAST_DAY

Aceita partes de data relevantes (consulte Partes de data e hora com suporte).

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 Partes de data e hora com suporte).

DATEDIFF

Aceita partes relevantes de data e hora (consulte Partes de data e hora com suporte).

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 Partes de data e hora com suporte).

TIME_SLICE

Permite que a hora seja “arredondada” até o início de um intervalo de tempo igualmente espaçado.

TRUNCATE, TRUNC

Alternativa para DATE_TRUNC.

Conversão

TO_DATE , DATE

Oferece suporte a conversões baseadas em cadeia de caracteres, carimbo de data/hora e expressões VARIANT. Oferece suporte a números inteiros para conversões baseadas no início da época Unix.

TO_TIME , TIME

Oferece suporte a conversões baseadas em cadeia de caracteres, carimbo de data/hora e expressões VARIANT. Oferece suporte a números inteiros para conversões baseadas no início da época Unix.

TO_TIMESTAMP / TO_TIMESTAMP_*

Oferece suporte a conversões baseadas em cadeia de caracteres, data, carimbo de data/hora e expressões VARIANT. Oferece suporte a expressões numéricas e inteiros para conversões baseadas no início da época Unix.

Fuso horário

CONVERT_TIMEZONE

Alertas*

LAST_SUCCESSFUL_SCHEDULED_TIME

SCHEDULED_TIME

Formatos de saída

Várias funções de data e hora retornam valores de data, hora e carimbo de data/hora. Os seguintes parâmetros de sessão determinam o formato da saída retornada por essas funções:

Para obter mais informações, consulte Formatos de entrada e saída de data e hora.

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 distinção entre maiúsculas e minúsculas) que você pode usar com essas 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

✔

dayofweek_iso [2]

dayofweekiso, weekday_iso, dow_iso, dw_iso

✔

dayofyear

yearday , doy , dy

✔

week [1]

w , wk , weekofyear , woy , wy

✔

✔

✔

✔

✔

week_iso [2]

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

LAST_DAY

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 do ano 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 data relacionadas à semana (e partes de dados equivalentes) cujo comportamento é consistente com a semântica da semana ISO: DAYOFWEEKISO, WEEKISO e 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 detalhes sobre como as outras funções de data relacionadas à semana são manipuladas, consulte as seguintes seções:

Primeiro dia da semana

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

Função

Parâmetro definido como 0 (comportamento padrão/legado)

Parâmetro definir como 1 – 7 (segunda a 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 legado do Snowflake (semântica ISO). No entanto, recomendamos alterar esse valor para controlar explicitamente o comportamento resultante das funções. O cenário mais comum é definir o parâmetro como 1.

Primeira e última semana 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. Isso significa que a primeira e a última semana do ano podem ter menos de 7 dias.

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

  • 0 ou 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 legado do Snowflake (semântica ISO). No entanto, recomendamos alterar esses valores para controlar explicitamente o comportamento resultante das funções. O cenário mais comum é definir ambos os parâmetros como 1.

Exemplos

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.

Os exemplos usam os seguintes dados:

CREATE OR REPLACE TABLE week_examples (d DATE);

INSERT INTO week_examples VALUES
  ('2016-12-30'),
  ('2016-12-31'),
  ('2017-01-01'),
  ('2017-01-02'),
  ('2017-01-03'),
  ('2017-01-04'),
  ('2017-01-05'),
  ('2017-12-30'),
  ('2017-12-31');
Copy

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;
Copy
+------------+-----+-----+------------+-----------+---------------+--------------+------------------------------------+
| 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;
Copy
+------------+-----+-----+------------+-----------+---------------+--------------+------------------------------------+
| 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 |
+------------+-----+-----+------------+-----------+---------------+--------------+------------------------------------+

  • 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;
Copy
+------------+-----+-----+------------+-----------+---------------+--------------+------------------------------------+
| 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 |
+------------+-----+-----+------------+-----------+---------------+--------------+------------------------------------+

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;
Copy
+------------+-----+-----+-----------+------+-----------+
| 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 |
+------------+-----+-----+-----------+------+-----------+

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;
Copy
+------------+-----+-----+-----------+------+-----------+
| 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 |
+------------+-----+-----+-----------+------+-----------+

  • 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;
Copy
+------------+-----+-----+-----------+------+-----------+
| 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;
Copy
+------------+-----+-----+-----------+------+-----------+
| 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 |
+------------+-----+-----+-----------+------+-----------+

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

    Esse cenário de uso geralmente é o mais comum.

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

Linguagem: Português