AT TIME ZONE (Transact-SQL)

Aplica-se a: SQL Server 2016 (13.x) e posterior Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Azure Synapse Analytics Ponto de extremidade de análise de SQL no Microsoft Fabric Warehouse no Microsoft Fabric

Converte um inputdate para o valor de datetimeoffset correspondente no fuso horário de destino. Quando inputdate é fornecido sem as informação de diferença, a função aplica a diferença do fuso horário considerando que inputdate está no fuso horário de destino. Se inputdate for fornecido como um valor de datetimeoffset, a cláusula AT TIME ZONE o converterá no fuso horário de destino usando regras de conversão de fuso horário.

A implementação de AT TIME ZONE depende de um mecanismo do Windows para converter os valores de datetime entre fusos horários.

Convenções de sintaxe de Transact-SQL

Sintaxe

inputdate AT TIME ZONE timezone

Argumentos

inputdate

Uma expressão que pode ser resolvida para um valor smalldatetime, datetime, datetime2 ou datetimeoffset.

timezone

Nome do fuso horário de destino. O SQL Server baseia-se nos fusos horários armazenados no Registro do Windows. Os fusos horários instalados no computador são armazenados no seguinte hive do Registro: KEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Time Zones. Uma lista de fusos horários instalados também é exposta por meio do modo de exibição sys.time_zone_info .

Para obter mais informações sobre fusos horários para SQL Server em Linux, confira Configurar o fuso horário para SQL Server 2022 no Linux.

Tipos de retorno

Retorna o tipo de dados de datetimeoffset.

Retornar valor

O valor de datetimeoffset no fuso horário de destino.

Comentários

AT TIME ZONE aplica regras específicas para converter os valores de entrada nos tipos de dados smalldatetime, datetime e datetime2, que caem em um intervalo afetado por uma alteração de horário de verão:

  • Quando o relógio está adiantado, há uma lacuna na hora local igual à duração do ajuste do relógio. Esta duração é geralmente de 1 hora, mas pode ser de 30 ou 45 minutos, dependendo do fuso horário. Os pontos no tempo que pertencem a essa diferença são convertidos com a diferença depois da alteração do horário de verão.

    /*
      Moving to DST in "Central European Standard Time" zone:
      offset changes from +01:00 -> +02:00
      Change occurred on March 27th, 2022 at 02:00:00.
      Adjusted local time became 2022-03-27 03:00:00.
    */
    
    --Time before DST change has standard time offset (+01:00)
    SELECT CONVERT(DATETIME2(0), '2022-03-27T01:01:00', 126)
    AT TIME ZONE 'Central European Standard Time';
    --Result: 2022-03-27 01:01:00 +01:00
    
    /*
      Adjusted time from the "gap interval" (between 02:00 and 03:00)
      is moved 1 hour ahead and presented with the summer time offset
      (after the DST change)
    */
    SELECT CONVERT(DATETIME2(0), '2022-03-27T02:01:00', 126)
    AT TIME ZONE 'Central European Standard Time';
    --Result: 2022-03-27 03:01:00 +02:00
    --Time after 03:00 is presented with the summer time offset (+02:00)
    SELECT CONVERT(DATETIME2(0), '2022-03-27T03:01:00', 126)
    AT TIME ZONE 'Central European Standard Time';
    --Result: 2022-03-27 03:01:00 +02:00
    
  • Quando o relógio for alterado novamente, 2 horas da hora local serão sobrepostas em uma hora. Nesse caso, os pontos no tempo que pertencem ao intervalo sobreposto são apresentados com a diferença antes da alteração do relógio:

    /*
        Moving back from DST to standard time in
        "Central European Standard Time" zone:
        offset changes from +02:00 -> +01:00.
        Change occurred on October 30th, 2022 at 03:00:00.
        Adjusted local time became 2022-10-30 02:00:00
    */
    
    --Time before the change has DST offset (+02:00)
    SELECT CONVERT(DATETIME2(0), '2022-10-30T01:01:00', 126)
    AT TIME ZONE 'Central European Standard Time';
    --Result: 2022-10-30 01:01:00 +02:00
    
    /*
      Time from the "overlapped interval" is presented with DST offset (before the change)
    */
    SELECT CONVERT(DATETIME2(0), '2022-10-30T02:00:00', 126)
    AT TIME ZONE 'Central European Standard Time';
    --Result: 2022-10-30 02:00:00 +02:00
    
    --Time after 03:00 is regularly presented with the standard time offset (+01:00)
    SELECT CONVERT(DATETIME2(0), '2022-10-30T03:01:00', 126)
    AT TIME ZONE 'Central European Standard Time';
    --Result: 2022-10-30 03:01:00 +01:00
    

Como algumas informações (como as regras de fuso horário) são mantidas fora do SQL Server e estão sujeitas a alterações ocasionais, a função AT TIME ZONE é classificada como não determinísticas.

Embora não haja suporte para datetimeoffset no data warehouse no Microsoft Fabric, AT TIME ZONE ele ainda pode ser usado com datetime2, como no exemplo a seguir.

Exemplos

a. Adicionar uma diferença de fuso horário de destino para datetime sem informação de diferença

Use AT TIME ZONE para adicionar uma diferença com base nas regras de fuso horário quando você souber que os valores de datetime originais são fornecidos no mesmo fuso horário:

USE AdventureWorks2022;
GO

SELECT SalesOrderID, OrderDate,
    OrderDate AT TIME ZONE 'Pacific Standard Time' AS OrderDate_TimeZonePST
FROM Sales.SalesOrderHeader;

B. Converter valores entre fusos horários diferentes

O exemplo a seguir converte os valores entre fusos horários diferentes. Os OrderDate valores são datetime e não são armazenados com um deslocamento, mas são conhecidos por serem o Horário Padrão do Pacífico. A primeira etapa é atribuir o deslocamento conhecido e, em seguida, converter para o novo fuso horário:

USE AdventureWorks2022;
GO

SELECT SalesOrderID, OrderDate,
    --Assign the known offset only
    OrderDate AT TIME ZONE 'Pacific Standard Time' AS OrderDate_TimeZonePST,
    --Assign the known offset, then convert to another time zone
    OrderDate AT TIME ZONE 'Pacific Standard Time' AT TIME ZONE 'Central European Standard Time' AS OrderDate_TimeZoneCET
FROM Sales.SalesOrderHeader;

Você também pode substituir em uma variável local que contém o fuso horário:

USE AdventureWorks2022;
GO

DECLARE @CustomerTimeZone nvarchar(128) = 'Central European Standard Time';

SELECT SalesOrderID, OrderDate,
    --Assign the known offset only
    OrderDate AT TIME ZONE 'Pacific Standard Time' AS OrderDate_TimeZonePST,
    --Assign the known offset, then convert to another time zone
    OrderDate AT TIME ZONE 'Pacific Standard Time' AT TIME ZONE @CustomerTimeZone AS OrderDate_TimeZoneCustomer
FROM Sales.SalesOrderHeader;

C. Consultar tabelas temporárias usando um fuso horário específico

O exemplo a seguir seleciona os dados de uma tabela temporal usando a Hora Padrão do Pacífico.

USE AdventureWorks2022;
GO

DECLARE @ASOF DATETIMEOFFSET;

SET @ASOF = DATEADD(MONTH, -1, GETDATE()) AT TIME ZONE 'UTC';

-- Query state of the table a month ago projecting period
-- columns as Pacific Standard Time
SELECT BusinessEntityID,
    PersonType,
    NameStyle,
    Title,
    FirstName,
    MiddleName,
    ValidFrom AT TIME ZONE 'Pacific Standard Time'
FROM Person.Person_Temporal
FOR SYSTEM_TIME AS OF @ASOF;