Formatos de entrada e saída de data e hora¶
Neste tópico:
Como o Snowflake determina o uso de formatos de entrada e saída¶
Para determinar os formatos de entrada e saída a serem usados para datas, horários e carimbos de data/hora, o Snowflake utiliza:
Parâmetros de sessão para datas, horas e carimbos de data/hora
Opções de formato de arquivo para carregar/descarregar datas, horas e carimbos de data e hora
Parâmetros de sessão para datas, horas e carimbos de data/hora¶
Um conjunto de parâmetros de sessão determina como os dados de data, hora e carimbo de data/hora são passados de e para o Snowflake, bem como o fuso horário usado nos formatos de hora e carimbo de data/hora que suportam fusos horários.
Os parâmetros podem ser definidos nos níveis de conta, usuário e sessão. Execute o comando SHOW PARAMETERS para visualizar as configurações de parâmetros atuais que se aplicam a todas as operações na sessão atual.
Formatos de entrada¶
Os parâmetros a seguir definem quais formatos de data, hora e carimbo de data/hora são reconhecidos para DML, incluindo operações COPY, INSERT e MERGE:
O padrão para todos os três parâmetros é AUTO. Quando o valor do parâmetro é definido como AUTO, o Snowflake tenta corresponder a data, a hora ou o carimbo de data/hora em qualquer expressão de entrada com um dos formatos listados em Formatos com suporte para detecção AUTO.
Se for encontrado um formato compatível, o Snowflake aceita a cadeia de caracteres.
Se não for encontrado um formato compatível, o Snowflake retorna um erro.
Formatos de saída¶
Os parâmetros a seguir definem os formatos de saída de data e hora do Snowflake:
Além disso, os seguintes parâmetros mapeiam o alias de tipo de dados TIMESTAMP para uma das três variações de TIMESTAMP_*:
Fuso horário¶
O parâmetro a seguir determina o fuso horário:
Opções de formato de arquivo para carregar/descarregar datas, horas e carimbos de data e hora¶
Separado dos parâmetros de formato de entrada e saída, o Snowflake fornece três opções de formato de arquivo para usar ao carregar ou descarregar dados das tabelas do Snowflake:
DATE_FORMAT
TIME_FORMAT
TIMESTAMP_FORMAT
As opções podem ser especificadas diretamente no comando COPY ou em um estágio nomeado ou objeto de formato de arquivo referenciado no comando COPY. Quando especificadas, estas opções substituem os formatos de entrada correspondentes (ao carregar dados) ou de saída (ao descarregar dados).
Carregamento de dados¶
Quando usadas no carregamento de dados, as opções especificam o formato das cadeias de caracteres de data, hora e carimbo de data/hora em seus arquivos de dados preparados. As opções substituem as configurações dos parâmetros DATE_INPUT_FORMAT, TIME_INPUT_FORMAT ou TIMESTAMP_INPUT_FORMAT.
O padrão para todas essas opções é AUTO, o que significa que o comando COPY INTO <tabela> tenta corresponder todas as cadeias de caracteres de data e carimbo de data/hora nos arquivos de dados preparados com um dos formatos listados em Formatos com suporte para detecção AUTO.
Se for encontrado um formato compatível, o Snowflake aceita a cadeia de caracteres.
Se nenhum formato correspondente for encontrado, o Snowflake retorna um erro e então executa a ação especificada para a opção de cópia ON_ERROR.
Aviso
O Snowflake suporta a detecção automática dos formatos mais comuns de data, hora e carimbo de data/hora (consulte as tabelas abaixo); entretanto, alguns formatos podem produzir resultados ambíguos, o que pode fazer com que o Snowflake aplique um formato incorreto ao usar AUTO para carregamento de dados.
Para garantir o carregamento correto dos dados, o Snowflake recomenda fortemente definir de forma explícita as opções de formato de arquivo para o carregamento de dados.
Descarregamento de dados¶
Quando usadas no descarregamento de dados, as opções especificam o formato aplicado às datas, horas e carimbos de data/hora descarregados nos arquivos no estágio especificado.
O padrão para todas estas opções é AUTO, significando que o Snowflake aplica a formatação especificada nos seguintes parâmetros:
DATE_OUTPUT_FORMAT
TIME_OUTPUT_FORMAT
TIMESTAMP_*_OUTPUT_FORMAT (dependendo da configuração TIMESTAMP_TYPE_MAPPING)
Sobre os elementos utilizados nos formatos de entrada e saída¶
Nos formatos de entrada e saída que você especifica em parâmetros, opções de formato de arquivo e funções de conversão, você pode usar os elementos listados na tabela abaixo.
As seções seguintes também utilizam esses elementos para descrever os formatos reconhecidos pelo Snowflake automaticamente.
Elemento de formato |
Descrição |
---|---|
|
Ano com quatro dígitos. |
|
Ano com dois dígitos, controlado pelo parâmetro de sessão TWO_DIGIT_CENTURY_START, por exemplo, quando definido como |
|
Mês com dois dígitos (01 = janeiro, etc.). |
|
Nome do mês completo ou abreviado. |
|
Nome completo do mês. |
|
Dia do mês com dois dígitos (01 até 31). |
|
Dia da semana abreviado. |
|
Hora com dois dígitos (00 até 23). Você não deve especificar |
|
Hora com dois dígitos (01 até 12). Você pode especificar |
|
Ante meridiem (am) / post meridiem (pm). Use isso somente com |
|
Minuto com dois dígitos (00 até 59). |
|
Segundo com dois dígitos (00 até 59). |
|
Fracionamento de segundos com precisão 0 (segundos) a 9 (nanossegundos), por exemplo |
|
Hora e minuto do fuso horário, ajustados em relação ao UTC. Pode ser prefixado por |
|
Ano de quatro dígitos no formato ISO, que são negativos para anos BCE. |
Nota
Quando se utiliza um formato somente de data, presume-se que a hora associada seja a meia-noite desse dia.
Qualquer elemento no formato entre aspas duplas ou elementos diferentes dos elementos acima é analisado/formatado sem ser interpretado.
Para obter mais detalhes sobre intervalos válidos, número de dígitos e práticas recomendadas, consulte Informações adicionais sobre o uso de formatos de data, hora e carimbo de data/hora.
Formatos com suporte para detecção AUTO¶
Se instruído para isso, o Snowflake detecta e processa automaticamente formatos específicos para cadeias de caracteres de entrada de data, hora e carimbo de data/hora. As seções seguintes descrevem os formatos compatíveis:
Atenção
Algumas cadeias de caracteres podem corresponder a múltiplos formatos. Por exemplo, “07-04-2016” é compatível com MM-DD-YYYY
e DD-MM-YYYY
, mas tem significados diferentes em cada formato (4 de julho ou 7 de abril). O fato de ser encontrado um formato correspondente não garante que a cadeia de caracteres seja analisada como o usuário pretendia.
Embora a detecção automática do formato da data seja conveniente, ela aumenta a possibilidade de que as datas sejam mal interpretadas. O Snowflake recomenda fortemente a especificação explícita do formato em vez de confiar na detecção automática da data.
Formatos de data¶
Para as descrições dos elementos utilizados nos formatos abaixo, consulte Sobre os elementos utilizados nos formatos de entrada e saída.
Formato |
Exemplo |
Notas |
---|---|---|
Formatos de data ISO |
||
YYYY-MM-DD |
|
|
Outros formatos de data |
||
DD-MON-YYYY |
|
|
MM/DD/YYYY |
|
Poderia produzir datas incorretas ao carregar ou operar em datas em formatos europeus comuns (ou seja, |
Ao utilizar a formatação de data AUTO, travessões e barras não são intercambiáveis. Barras implicam no formato MM/DD/YYYY
e travessões implicam no formato YYYY-MM-DD
. Cadeias de caracteres como “2019/01/02” ou “01-02-2019” não são interpretadas como você poderia esperar.
Formatos de hora¶
Para as descrições dos elementos utilizados nos formatos abaixo, consulte Sobre os elementos utilizados nos formatos de entrada e saída.
Formato |
Exemplo |
Notas |
---|---|---|
Formatos de hora ISO |
||
HH24:MI:SS.FFTZH:TZM |
|
|
HH24:MI:SS.FF |
|
|
HH24:MI:SS |
|
|
HH24:MI |
|
|
Formatos de hora de Internet (RFC) |
||
HH12:MI:SS.FF AM |
|
|
HH12:MI:SS AM |
|
|
HH12:MI AM |
|
O elemento de formato AM
permite valores com AM
ou PM
.
Nota
O elemento de formato AM
só deve ser usado com HH12
(não com HH24
).
Quando um deslocamento de fuso horário (por exemplo “0800”) ocorre imediatamente após um dígito em uma cadeia de caracteres de hora ou carimbo de data/hora, o deslocamento do fuso horário deve começar com +
ou -
. O sinal evita ambiguidade quando os segundos fracionários ou o deslocamento de fuso horário não contêm o número máximo de dígitos permitidos. Por exemplo, sem um separador entre o último dígito dos segundos fracionários e o primeiro dígito do fuso horário, o “1” na hora “04:04:04.321200” poderia ser ou o último dígito dos segundos fracionários (por exemplo, 321 milissegundos) ou o primeiro dígito do deslocamento do fuso horário (por exemplo, 12 horas à frente de UTC).
Formatos de carimbo de data/hora¶
Para as descrições dos elementos utilizados nos formatos abaixo, consulte Sobre os elementos utilizados nos formatos de entrada e saída.
Formato |
Exemplo |
Notas |
---|---|---|
Formatos de carimbo de data/hora ISO |
||
YYYY-MM-DD"T"HH24:MI:SS.FFTZH:TZM |
|
As aspas duplas ao redor do |
YYYY-MM-DD HH24:MI:SS.FFTZH:TZM |
|
|
YYYY-MM-DD HH24:MI:SS.FFTZH |
|
|
YYYY-MM-DD HH24:MI:SS.FF TZH:TZM |
|
|
YYYY-MM-DD HH24:MI:SS.FF TZHTZM |
|
|
YYYY-MM-DD HH24:MI:SS TZH:TZM |
|
|
YYYY-MM-DD HH24:MI:SS TZHTZM |
|
|
YYYY-MM-DD"T"HH24:MI:SS.FF |
|
As aspas duplas ao redor do |
YYYY-MM-DD HH24:MI:SS.FF |
|
|
YYYY-MM-DD"T"HH24:MI:SS |
|
As aspas duplas ao redor do |
YYYY-MM-DD HH24:MI:SS |
|
|
YYYY-MM-DD"T"HH24:MI |
|
As aspas duplas ao redor do |
YYYY-MM-DD HH24:MI |
|
|
YYYY-MM-DD"T"HH24 |
|
As aspas duplas ao redor do |
YYYY-MM-DD HH24 |
|
|
YYYY-MM-DD"T"HH24:MI:SSTZH:TZM |
|
As aspas duplas ao redor do |
YYYY-MM-DD HH24:MI:SSTZH:TZM |
|
|
YYYY-MM-DD HH24:MI:SSTZH |
|
|
YYYY-MM-DD"T"HH24:MITZH:TZM |
|
As aspas duplas ao redor do |
YYYY-MM-DD HH24:MITZH:TZM |
|
|
Formatos de carimbo de data/hora de Internet (RFC) |
||
DY, DD MON YYYY HH24:MI:SS TZHTZM |
|
|
DY, DD MON YYYY HH24:MI:SS.FF TZHTZM |
|
|
DY, DD MON YYYY HH12:MI:SS AM TZHTZM |
|
|
DY, DD MON YYYY HH12:MI:SS.FF AM TZHTZM |
|
|
DY, DD MON YYYY HH24:MI:SS |
|
|
DY, DD MON YYYY HH24:MI:SS.FF |
|
|
DY, DD MON YYYY HH12:MI:SS AM |
|
|
DY, DD MON YYYY HH12:MI:SS.FF AM |
|
|
Outros formatos de carimbo de data/hora |
||
MM/DD/YYYY HH24:MI:SS |
|
Poderia produzir datas incorretas ao carregar ou operar em datas em formatos europeus comuns (ou seja, |
DY MON DD HH24:MI:SS TZHTZM YYYY |
|
Quando um deslocamento de fuso horário (por exemplo “0800”) ocorre imediatamente após um dígito em uma cadeia de caracteres de hora ou carimbo de data/hora, o deslocamento do fuso horário deve começar com +
ou -
. O sinal evita ambiguidade quando os segundos fracionários ou o deslocamento de fuso horário não contêm o número máximo de dígitos permitidos. Por exemplo, sem um separador entre o último dígito dos segundos fracionários e o primeiro dígito do fuso horário, o “1” na hora “04:04:04.321200” poderia ser ou o último dígito dos segundos fracionários (por exemplo, 321 milissegundos) ou o primeiro dígito do deslocamento do fuso horário (por exemplo, 12 horas à frente de UTC).
Dica
Em alguns dos formatos de carimbo de data/hora, a letra T
é usada como separador entre a data e a hora (por exemplo, 'YYYY-MM-DD"T"HH24:MI:SS'
).
As aspas duplas ao redor do T
são opcionais. Entretanto, o Snowflake recomenda o uso de aspas duplas ao redor do T
(e outros literais) para evitar ambiguidade.
As aspas duplas devem ser usadas somente no especificador de formato, não nos valores reais. Por exemplo:
SELECT TO_TIMESTAMP('2019-02-28T23:59:59', 'YYYY-MM-DD"T"HH24:MI:SS');
Além disso, as aspas ao redor do T
devem ser duplas.
Informações adicionais sobre o uso de formatos de data, hora e carimbo de data/hora¶
As seções seguintes descrevem os requisitos e práticas recomendadas para campos individuais em datas, horas e carimbos de data/hora.
Intervalos de valores válidos para campos¶
Os intervalos de valores recomendados para cada campo são mostrados abaixo:
Campo |
Valores |
Notas |
---|---|---|
Anos |
|
Alguns valores fora desse intervalo podem ser aceitos em alguns contextos, mas o Snowflake recomenda o uso apenas de valores neste intervalo. Por exemplo, o ano 0000 é aceito, mas é incorreto porque no calendário gregoriano o ano 1 A.D. vem imediatamente após o ano 1 a.C.; não há ano 0. |
Meses |
|
|
Dias |
|
Em meses que têm menos de 31 dias, o máximo real é o número de dias do mês. |
Horas |
|
Ou |
Minutos |
|
|
Segundos |
|
O Snowflake não suporta segundos intercalares ou segundos intercalares adicionais; os valores |
Fração |
|
O número de dígitos após o ponto decimal depende em parte do especificador de formato exato (por exemplo, |
Uso do número correto de dígitos com elementos de formato¶
Para a maioria dos campos (ano, mês, dia, dia, hora, minuto e segundo), os elementos (YYYY
, MM
, DD
, etc.) do especificador do formato são dois ou quatro caracteres.
As seguintes regras dizem quantos dígitos você deve realmente especificar nos valores literais:
YYYY
: Você pode especificar 1, 2, 3 ou 4 dígitos do ano. Entretanto, o Snowflake recomenda especificar 4 dígitos. Se for necessário, preceda com zeros iniciais. Por exemplo, o ano 536 A.D. seria “0536”.YY
: Especifique 1 ou 2 dígitos do ano. Entretanto, o Snowflake recomenda especificar 2 dígitos. Se for necessário, preceda com um zero inicial.MM
: Especifique um ou dois dígitos. Por exemplo, janeiro pode ser representado como “01” ou “1”. O Snowflake recomenda o uso de dois dígitos.DD
: Especifique um ou dois dígitos. O Snowflake recomenda o uso de dois dígitos.HH12
eHH24
: especifique um ou dois dígitos. O Snowflake recomenda o uso de dois dígitos.MI
: Especifique um ou dois dígitos. O Snowflake recomenda o uso de dois dígitos.SS
: Especifique um ou dois dígitos. O Snowflake recomenda o uso de dois dígitos.FF9
: Especifique entre 1 e 9 dígitos (inclusive). O Snowflake recomenda especificar o número de dígitos significativos reais. Não são necessários zeros finais.TZH
: Especifique um ou dois dígitos. O Snowflake recomenda o uso de dois dígitos.TZM
: Especifique um ou dois dígitos. O Snowflake recomenda o uso de dois dígitos.
Para todos os campos (exceto os segundos fracionários), o Snowflake recomenda especificar o número máximo de dígitos. Use zeros iniciais, se necessário. Por exemplo, “0001-02-03 04:05:06 -07:00” segue o formato recomendado.
Para os segundos fracionários, zeros finais são opcionais. Em geral, é considerado boa prática especificar apenas o número de dígitos que são confiáveis e significativos. Por exemplo, se uma medição de hora for precisa até 3 casas decimais (milissegundos), então especificá-la como 9 dígitos (por exemplo “.123000000”) pode ser enganoso.
Espaço em branco em valores e especificadores de formato¶
O Snowflake adota a correspondência de espaços em branco em algumas situações, mas não todas. Por exemplo, a seguinte instrução gera um erro porque não há espaço entre os dias e as horas no valor especificado, mas há um espaço entre DD
e HH
no especificador de formato:
SELECT TO_TIMESTAMP('2019-02-2823:59:59 -07:00', 'YYYY-MM-DD HH24:MI:SS TZH:TZM');
Entretanto, a seguinte instrução não gera um erro, mesmo que o valor contenha um espaço em branco onde o especificador não tem:
SELECT TO_TIMESTAMP('2019-02-28 23:59:59.000000000 -07:00', 'YYYY-MM-DDHH24:MI:SS.FF TZH:TZM');
A razão da diferença é que, no primeiro caso, os valores seriam ambíguos se os campos não estivessem todos em sua largura máxima. Por exemplo, “213” poderia ser interpretado como 2 dias e 13 horas, ou como 21 dias e 3 horas. Entretanto, DDHH
é inequivocamente o mesmo que DD HH
(exceto o espaço em branco).
Dica
Embora algumas diferenças de espaço em branco sejam permitidas para lidar com dados de formato variável, o Snowflake recomenda que os valores e especificadores coincidam exatamente, incluindo os espaços.
Dependência de contexto¶
Nem todas as restrições são aplicadas igualmente em todos os contextos. Por exemplo, algumas expressões podem aceitar 31 de fevereiro e outras não.
Resumo das práticas recomendadas para especificar o formato¶
Estas práticas recomendadas minimizam ambiguidades e outros problemas potenciais em versões passadas, presentes e futuras do Snowflake:
Esteja ciente dos perigos de misturar dados de origens que usam formatos diferentes (por exemplo, misturar dados que seguem o formato comum dos EUA
MM-DD-YYYY
e o formato comum europeuDD-MM-YYYY
).Especifique o número máximo de dígitos para cada campo (exceto segundos fracionários). Por exemplo, use anos de 4 dígitos, especificando zeros iniciais, se necessário.
Especifique um espaço em branco ou a letra
T
entre a data e a hora em um carimbo de data/hora.O espaço em branco (e o separador opcional
T
entre a data e a hora) deve ser o mesmo em valores e no especificador de formato.Use aritmética intervalar se você precisar do equivalente a rollover.
Tenha cuidado ao utilizar a formatação AUTO. Quando possível, especifique o formato e garanta que os valores sempre correspondam ao formato especificado.
Especificar o formato no comando é mais seguro do que especificar o formato fora do comando; por exemplo, em um parâmetro como DATE_INPUT_FORMAT. (Consulte abaixo).
Ao mover scripts de um ambiente para outro, certifique-se de que os parâmetros relacionados à data, tais como DATE_INPUT_FORMAT, sejam os mesmos no novo ambiente que eram no ambiente antigo (assumindo que os valores também estejam no mesmo formato).
Funções de data e hora¶
O Snowflake fornece um conjunto de funções para construir, converter, extrair ou modificar dados de DATE/TIME/TIMESTAMP. Para obter mais informações, consulte Funções de data e hora.
Detecção AUTO de valores de data, hora e carimbo de data/hora armazenados como inteiros¶
Para inteiros de segundos ou milissegundos armazenados em uma cadeia de caracteres, o Snowflake tenta determinar a unidade de medida correta com base no comprimento do valor.
Nota
O uso de números inteiros cotados como entradas é obsoleto.
Por exemplo, para calcular o carimbo de data/hora equivalente a 1487654321 segundos desde o início da época Unix:
select to_timestamp('1487654321');
-------------------------------+
TO_TIMESTAMP('1487654321') |
-------------------------------+
2017-02-20 21:18:41.000000000 |
-------------------------------+
Aqui está um cálculo semelhante utilizando milissegundos desde o início da época:
select to_timestamp('1487654321321');
-------------------------------+
TO_TIMESTAMP('1487654321321') |
-------------------------------+
2017-02-20 21:18:41.321000000 |
-------------------------------+
Dependendo da magnitude do valor, o Snowflake usa uma unidade de medida diferente:
Depois que a cadeia de caracteres é convertida em um inteiro, o inteiro é tratado como um número de segundos, milissegundos, microssegundos ou nanossegundos após o início da época Unix (1970-01-01 00:00:00.000000000 UTC).
Se o número inteiro for inferior a 31536000000 (o número de milissegundos em um ano), então o valor é tratado como um número de segundos.
Se o valor for maior ou igual a 31536000000 e menor que 31536000000000, então o valor é tratado como milissegundos.
Se o valor for maior ou igual a 31536000000000 e menor que 31536000000000000, então o valor é tratado como microssegundos.
Se o valor for maior ou igual a 31536000000000000, então o valor é tratado como nanossegundos.
Nota
Aviso de descontinuação: Versões futuras do Snowflake podem interpretar automaticamente valores inteiros de cadeia de caracteres como segundos, em vez de milissegundos, microssegundos ou nanossegundos. O Snowflake recomenda chamar TO_DATE, TO_TIME ou TO_TIMESTAMP com cadeias de caracteres que contenham inteiros somente quando esses inteiros devam ser interpretados como segundos.
Se mais de uma linha for avaliada (por exemplo, se a entrada for o nome da coluna de uma tabela que contém mais de uma linha), cada valor será examinado independentemente para determinar se o valor representa segundos, milissegundos, microssegundos ou nanossegundos.
Nos casos em que inteiros e cadeias de caracteres formatadas em cadeias de caracteres são passados para a função, cada valor é convertido de acordo com o conteúdo da cadeia de caracteres. Por exemplo, se você passar uma cadeia de caracteres formatada com data e uma cadeia de caracteres contendo um número inteiro para TO_TIMESTAMP, a função interpreta cada valor corretamente de acordo com o que cada cadeia de caracteres contém:
select to_timestamp(column1) from values ('2013-04-05'), ('1487654321');
+-------------------------+
| TO_TIMESTAMP(COLUMN1) |
|-------------------------|
| 2013-04-05 00:00:00.000 |
| 2017-02-21 05:18:41.000 |
+-------------------------+
Práticas recomendadas do formato de função de data e hora¶
A detecção AUTO geralmente determina o formato de entrada correto; no entanto, há situações em que ela pode não ser capaz de fazer a determinação correta.
Para evitar isto, o Snowflake recomenda fortemente as seguintes práticas recomendadas (substitua TO_DATE , DATE ou TO_TIME , TIME por TO_TIMESTAMP, conforme o caso):
Evite usar o formato AUTO se houver alguma chance de resultados ambíguos. Em vez disso, especifique uma cadeia de caracteres de formato explícito:
Defina TIMESTAMP_INPUT_FORMAT e outros parâmetros de sessão para datas, carimbos de data/hora e horas. Consulte Parâmetros de sessão para datas, horas e carimbos de data/hora (neste tópico).
Especifique o formato usando a seguinte sintaxe:
TO_TIMESTAMP(<value>, '<format>')
Para cadeias de caracteres contendo valores inteiros, especifique a escala usando a seguinte sintaxe:
TO_TIMESTAMP(TO_NUMBER(<string_column>), <scale>)