Idioma

Dados de data e hora

SQL Server 2008 introduziu tipos de dados separados para data e hora e expandiu tipos de dados com maior alcance, precisão e suporte a fuso horário. Use o pacote NuGet Microsoft.Data.SqlClient para acessar esses tipos de dados a partir de aplicativos cliente. Para os exemplos neste artigo, importe Microsoft.Data.SqlClient e System.Data em C# ou Visual Basic. Os tipos comuns de valor SQL permanecem em System.Data.SqlTypes.

As versões do SQL Server anteriores ao SQL Server 2008 tinham apenas dois tipos de dados para trabalhar com valores de data e temporal: datetime e smalldatetime. Ambos os tipos de dados contêm o valor de data e um valor temporal, o que dificulta o trabalho apenas com valores de data ou temporal. Além disso, esses tipos de dados apenas são compatíveis com datas que ocorrem após a introdução do calendário gregoriano, na Inglaterra, em 1753. Outra limitação é que esses tipos de dados mais antigos não têm reconhecimento de fuso horário, o que dificulta o trabalho usando dados provenientes de vários fusos horários.

Para obter mais informações sobre tipos de data e hora no SQL Server, consulte Tipos e Funções de Dados de Data e Hora.

Tipos de dados de data/hora introduzidos no SQL Server 2008

A tabela a seguir descreve os novos tipos de dados de data e hora.

Tipos de dados do SQL Server Descrição
date O tipo de dados date tem um intervalo de 1º de janeiro de 01 a 31 de dezembro de 9999 com precisão de um dia. O valor padrão é 1º de janeiro de 1900. O tamanho do armazenamento é 3 bytes.
time O tipo de dados time armazena somente valores temporais, com base em um relógio de 24 horas. O tipo de dados time tem um intervalo de 00:00:00.0000000 a 23:59:59,9999999 com precisão de 100 nanossegundos. O valor padrão é 00:00:00.0000000 (meia-noite). O tipo de dados time dá suporte à precisão de fração de segundo definida pelo usuário. O tamanho do armazenamento varia de 3 a 6 bytes, com base na precisão especificada.
datetime2 O tipo de dados datetime2 combina o intervalo e a precisão dos tipos de dados date e time em um tipo de dados.

Os valores padrão e os formatos literais de cadeia de caracteres são os mesmos que os definidos nos tipos de dados date e time.
datetimeoffset O tipo de dados datetimeoffset tem todos os recursos de datetime2 com um deslocamento de fuso horário adicional. O deslocamento de fuso horário é representado como [+|-] HH:MM. HH equivale a dois dígitos, variando de 00 a 14, que representam o número de horas no deslocamento de fuso horário. MM equivale a dois dígitos, variando de 00 a 59, que representam o número de minutos adicionais no deslocamento de fuso horário. Os formatos de hora são compatíveis com 100 nanossegundos. O sinal + ou - obrigatório indica se o deslocamento de fuso horário é adicionado ou subtraído do UTC (Tempo Universal Coordenado) ou do GMT (Hora de Greenwich) para obter a hora local.

Observação

Para obter mais informações sobre o uso da palavra-chave Type System Version, confira ConnectionString.

Formato de data e ordem de data

O modo como o SQL Server analisa os valores de data e temporal não depende apenas da versão do sistema do tipo e da versão do servidor, mas também das configurações de formato e idioma padrão do servidor. Uma cadeia de caracteres de data que funciona para os formatos de data de um idioma poderá ser irreconhecível se a consulta for executada por uma conexão que usa uma configuração diferente de idioma e formato de data.

A instrução Transact-SQL SET LANGUAGE define implicitamente o DATEFORMAT que determina a ordem das partes da data. Você pode usar a SET DATEFORMAT instrução Transact-SQL em uma conexão para desambiguar valores de data ordenando as partes de data em MDY, DMY, YMD, YDM, MYDou DYM ordem.

Se você não especificar nenhum DATEFORMAT para a conexão, SQL Server usará o idioma padrão associado à conexão. Por exemplo, uma string de data '01/02/03' seria interpretada como MDY (2 de janeiro de 2003) em um servidor com o idioma definido como inglês dos Estados Unidos e como DMY (1° de fevereiro de 2003) em um servidor com o idioma definido como inglês britânico. O ano é determinado usando a regra de ano limiar do SQL Server, que define a data limiar para atribuir o valor do século. Para obter mais informações, consulte Opção de corte de ano de dois dígitos.

Observação

Não há suporte para o formato de data YDM ao converter de um formato de cadeia de caracteres para date, time, datetime2 ou datetimeoffset.

Para obter mais informações sobre como o SQL Server interpreta dados de data e hora, consulte Uso de Dados de Data e Hora.

Parâmetros e tipos de dados de data/hora

As enumerações a seguir foram adicionadas ao SqlDbType para dar suporte aos novos tipos de dados de data e hora.

  • SqlDbType.Date

  • SqlDbType.Time

  • SqlDbType.DateTime2

  • SqlDbType.DateTimeOffset

Para especificar o tipo de dados para o objeto SqlParameter, use um dos valores de enumeração SqlDbType anteriores.

Observação

Não é possível definir a propriedade DbType de um SqlParameter como SqlDbType.Date.

Para especificar o tipo de parâmetro genericamente, defina a propriedade DbType como o valor de enumeração DbType. Os seguintes valores DbType suportam os tipos de dados datetime2 e datetimeoffset:

  • DbType.DateTime2

  • DbType.DateTimeOffset

Essas novas enumerações suplementam as enumerações Date, Time e DateTime, que existiam em versões anteriores do .NET Framework.

O tipo do provedor de dados do .NET Framework de um objeto de parâmetro é inferido do tipo do .NET Framework do valor do objeto de parâmetro ou do DbType do objeto de parâmetro. Nenhum tipo novo de dados System.Data.SqlTypes foi introduzido para dar suporte aos novos tipos de dados de data e hora. A tabela a seguir descreve os mapeamentos entre os tipos de dados de data e hora do SQL Server 2008 e os tipos de dados do CLR.

Tipos de dados do SQL Server Tipo de .NET Framework System.Data.SqlDbType System.Data.DbType
date System.DateTime Date Date
time System.TimeSpan Time Time
datetime2 System.DateTime DateTime2 DateTime2
datetimeoffset System.DateTimeOffset DateTimeOffset DateTimeOffset
datetime System.DateTime DateTime DateTime
smalldatetime System.DateTime DateTime DateTime

Propriedades do SqlParameter

A tabela a seguir descreve as propriedades SqlParameter que são relevantes para os tipos de dados de data e hora.

Propriedade Descrição
IsNullable Obtém ou define se um valor é anulável. Quando você envia um valor de parâmetro nulo para o servidor, deve especificar DBNull, não null (Nothing no Visual Basic). Para obter mais informações sobre nulos de banco de dados, confira Como Lidar com Valores Nulos.
Precision Obtém ou define o número máximo de dígitos usados para representar o valor. Essa configuração é ignorada para tipos de dados de data e hora.
Scale Obtém ou define a precisão de segundo fracionário para Time, DateTime2e DateTimeOffset. Se você não definir explicitamente a escala, o driver enviará a escala 7. Definir explicitamente a escala como 0 solicita zero dígitos de segundo fracionário.
Size Ignorado para tipos de dados de data e hora.
Value Obtém ou define o valor do parâmetro.
SqlValue Obtém ou define o valor do parâmetro.

Observação

Valores temporais menores que zero ou maiores ou iguais a 24 horas gerarão um ArgumentException.

Criar parâmetros

Crie SqlParameter objetos com o construtor ou chame o método Add na coleção Parameters do comando. O método Add aceita argumentos do construtor ou um objeto de parâmetro existente.

As próximas seções neste tópico fornecem exemplos de como especificar parâmetros de data e hora. Para obter exemplos adicionais de trabalho com parâmetros, consulte Configurar Parâmetros e Tipos de Dados de Parâmetro e Parâmetros DataAdapter .

Exemplo de data

O fragmento de código a seguir demonstra como especificar um parâmetro date.

SqlParameter parameter = new SqlParameter();
parameter.ParameterName = "@Date";
parameter.SqlDbType = SqlDbType.Date;
parameter.Value = "2007/12/1";
Dim parameter As New SqlParameter()
parameter.ParameterName = "@Date"
parameter.SqlDbType = SqlDbType.Date
parameter.Value = "2007/12/1"

Exemplo de Tempo

O fragmento de código a seguir demonstra como especificar um parâmetro time.

SqlParameter parameter = new SqlParameter();
parameter.ParameterName = "@time";
parameter.SqlDbType = SqlDbType.Time;
parameter.Value = DateTime.Parse("23:59:59").TimeOfDay;
Dim parameter As New SqlParameter()
parameter.ParameterName = "@Time"
parameter.SqlDbType = SqlDbType.Time
parameter.Value = DateTime.Parse("23:59:59").TimeOfDay

Exemplo de Datetime2

O fragmento de código a seguir demonstra como especificar um parâmetro datetime2 com as partes de data e hora.

SqlParameter parameter = new SqlParameter();
parameter.ParameterName = "@Datetime2";
parameter.SqlDbType = SqlDbType.DateTime2;
parameter.Value = DateTime.Parse("1666-09-02 1:00:00");
Dim parameter As New SqlParameter()
parameter.ParameterName = "@Datetime2"
parameter.SqlDbType = SqlDbType.DateTime2
parameter.Value = DateTime.Parse("1666-09-02 1:00:00")

Exemplo de DateTimeOffSet

O fragmento de código a seguir demonstra como especificar um parâmetro DateTimeOffset com uma data, uma hora e um deslocamento de fuso horário de 0.

SqlParameter parameter = new SqlParameter();
parameter.ParameterName = "@DateTimeOffSet";
parameter.SqlDbType = SqlDbType.DateTimeOffset;
parameter.Value = DateTimeOffset.Parse("1666-09-02T01:00:00+00:00");
Dim parameter As New SqlParameter()
parameter.ParameterName = "@DateTimeOffSet"
parameter.SqlDbType = SqlDbType.DateTimeOffset
parameter.Value = DateTimeOffset.Parse("1666-09-02T01:00:00+00:00")

AddWithValue

Para fornecer parâmetros, você também pode chamar AddWithValue na coleção Parameters do comando, conforme mostrado no seguinte fragmento de código. No entanto, AddWithValue não permite que você especifique o DbType ou SqlDbType do parâmetro.

command.Parameters.AddWithValue(
    "@date", DateTimeOffset.Parse("1666-09-02T01:00:00+00:00"));
command.Parameters.AddWithValue( _
    "@date", DateTimeOffset.Parse("1666-09-02T01:00:00+00:00"))

Para esse DateTimeOffset valor, AddWithValue infere SqlDbType.DateTimeOffset. Para direcionar um tipo de data ou hora SQL Server diferente, defina a propriedade do SqlDbType parâmetro explicitamente.

A seguinte tabela mostra quais SqlDbTypes são derivados de quais tipos do CLR:

Tipo CLR Inferido SqlDbType
DateTime SqlDbType.DateTime
TimeSpan SqlDbType.Time
DateTimeOffset SqlDbType.DateTimeOffset

Recuperando dados de data e hora

A tabela a seguir descreve os métodos que são usados para recuperar os valores de data e hora do SQL Server 2008.

Método SqlClient Descrição
GetDateTime Recupera o valor da coluna especificada como DateTime.
GetDateTimeOffset Recupera o valor da coluna especificado como DateTimeOffset.
GetProviderSpecificFieldType Retorna o tipo que é o tipo específico do provedor subjacente para o campo. Retorna os mesmos tipos que GetFieldType para novos tipos de data e hora.
GetProviderSpecificValue Recupera o valor da coluna especificada. Retorna os mesmos tipos que GetValue para novos tipos de data e hora.
GetProviderSpecificValues Recupera os valores na matriz especificada.
GetSqlString Recupera o valor da coluna na forma de SqlString. O método lança InvalidCastException se os dados não puderem ser expressos como SqlString.
GetSqlValue Recupera os dados da coluna como seu SqlDbType padrão. Retorna os mesmos tipos que GetValue para novos tipos de data e hora.
GetSqlValues Recupera os valores na matriz especificada.
GetString Recupera o valor da coluna como uma cadeia de caracteres se a versão do sistema do tipo está definida como SQL Server 2005. O método gera InvalidCastException se os dados não puderem ser expressos como uma cadeia de caracteres.
GetTimeSpan Recupera o valor da coluna especificada como TimeSpan.
GetValue Recupera o valor da coluna especificada como seu tipo CLR subjacente.
GetValues Recupera valores de coluna em uma matriz.
GetSchemaTable Retorna os metadados do conjunto de resultados no DataTable objeto.

Observação

A nova data e hora SqlDbTypes não são suportadas para código que está executando em processo no SQL Server. Uma exceção será gerada se um desses tipos for passado para o servidor.

Especificando valores de data e hora como literais

Você pode especificar tipos de dados de data e hora usando uma variedade de diferentes formatos de cadeia de caracteres literais, que o SQL Server avalia em runtime, convertendo-os em estruturas internas de data/hora. O SQL Server reconhece dados de data e hora que estão entre aspas simples ('). Os seguintes exemplos demonstram alguns formatos:

  • Formatos de datas alfabéticos, como 'October 15, 2006'.

  • Formatos de datas numéricos, como '10/15/2006'.

  • Formatos de cadeia de caracteres não separados, como '20061015', que serão interpretados como 15 de outubro de 2006 se você estiver usando o formato de data padrão ISO.

Valores temporais menores que zero ou maiores ou iguais a 24 horas gerarão um ArgumentException.

Recursos de documentos do SQL Server

Para obter mais informações sobre como trabalhar com valores de data e hora no SQL Server, consulte os artigos a seguir.

Artigo Descrição
tipos de dados e funções de data e hora (Transact-SQL) Fornece uma visão geral de todos os tipos de dados e as funções de data e hora do Transact-SQL.
Usando dados de data e hora Fornece informações sobre as funções e os tipos de dados de data e hora e exemplos de como usá-los.
Tipos de dados (Transact-SQL) Descreve os tipos de dados de sistema no SQL Server.

Confira também