Idioma

Dados de data e hora

O SQL Server 2008 introduziu tipos de dados separados para data e hora, e expandiu os tipos de dados com maior alcance, precisão e consciência do fuso horário. Use o pacote NuGet Microsoft.Data.SqlClient para aceder a estes tipos de dados a partir das aplicações clientes. Para os exemplos deste artigo, importe Microsoft.Data.SqlClient e System.Data em C# ou Visual Basic. Os tipos de valor SQL comuns mantêm-se 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 hora: datetime e smalldatetime. Ambos os tipos de dados contêm o valor de data e um valor de hora, o que dificulta o trabalho apenas com valores de data ou hora. Além disso, esses tipos de dados suportam apenas 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 reconhecem fuso horário, o que dificulta o trabalho com dados originários de vários fusos horários.

Para obter mais informações sobre tipos de data e hora no SQL Server, consulte Tipos de dados de data e hora e funções.

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.

Tipo de dados do SQL Server Descrição
date O date tipo de dados tem um intervalo de 1 de janeiro de 01 a 31 de dezembro de 9999 com uma precisão de 1 dia. O valor padrão é 1º de janeiro de 1900. O tamanho do armazenamento é de 3 bytes.
time O time tipo de dados armazena apenas valores de tempo, com base em um relógio de 24 horas. O time tipo de dados tem um intervalo de 00:00:00.0000000 até 23:59:59.9999999 com uma precisão de 100 nanossegundos. O valor padrão é 00:00:00.0000000 (meia-noite). O time tipo de dados suporta precisão de segundo fracionária definida pelo usuário e o tamanho do armazenamento varia de 3 a 6 bytes, com base na precisão especificada.
datetime2 O datetime2 tipo de dados combina o intervalo e a precisão dos tipos de dados date e time num único tipo de dados.

Os valores padrão e os formatos literais de cadeia de caracteres são os mesmos definidos nos date tipos de dados e time .
datetimeoffset O tipo de dados datetimeoffset tem todas as funcionalidades de datetime2, com um deslocamento de fuso horário adicional. O deslocamento de fuso horário é representado como [+|-] HH:MM. HH são 2 dígitos que variam de 00 a 14 que representam o número de horas no deslocamento de fuso horário. MM são 2 dígitos que variam de 00 a 59 que representam o número de minutos adicionais no deslocamento de fuso horário. Os formatos de tempo são suportados até 100 nanossegundos. O sinal obrigatório + ou - indica se o deslocamento de fuso horário é adicionado ou subtraído do UTC (Universal Time Coordinate ou Greenwich Mean Time) para obter a hora local.

Nota

Para obter mais informações sobre como usar a Type System Version palavra-chave, consulte ConnectionString.

Formato de data e ordem de data

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

A instrução Transact-SQL SET LANGUAGE define implicitamente o DATEFORMAT que determina a ordem das partes da data/hora. Pode usar a SET DATEFORMAT instrução Transact-SQL numa ligação para desambiguar valores de data, ordenando as partes da data pela ordem MDY, DMY, YMD, YDM, MYD ou DYM.

Se não especificar nenhuma DATEFORMAT para a ligação, o SQL Server usa a linguagem padrão associada à ligação. Por exemplo, uma sequência de datas '01/02/03' seria interpretada como MDY (2 de janeiro de 2003) num servidor com a definição de idioma Estados Unidos English, e como DMY (1 de fevereiro de 2003) num servidor com a definição de idioma British English. O ano é determinado usando a regra de ano de corte do SQL Server, que define a data de corte para atribuir o valor do século. Para obter mais informações, consulte Opção de corte de ano de dois dígitos.

Nota

O YDM formato de data não é suportado ao converter de um formato string para date, time, datetime2, ou datetimeoffset.

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

Tipos de dados e parâmetros de data/hora

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

  • SqlDbType.Date

  • SqlDbType.Time

  • SqlDbType.DateTime2

  • SqlDbType.DateTimeOffset

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

Nota

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

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

  • DbType.DateTime2

  • DbType.DateTimeOffset

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

O tipo de provedor de dados do .NET Framework de um objeto de parâmetro é inferido com base no tipo .NET Framework do valor desse objeto ou a partir de DbType associado ao objeto de parâmetro. Não foram introduzidos novos System.Data.SqlTypes tipos de dados para suportar os 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 CLR.

Tipo de dados do SQL Server Tipo do .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

SqlParameter Propriedades

A tabela a seguir descreve SqlParameter as propriedades 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, você deve especificar DBNull, em vez de null (Nothing no Visual Basic). Para obter mais informações sobre nulos de banco de dados, consulte Manipulando 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 precisão fracionária de segundo para Time, DateTime2, e DateTimeOffset. Se não definires explicitamente a escala, o driver envia a escala 7. Definir explicitamente a escala para 0 pede zero dígitos fracionários de segundo.
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.

Nota

Valores de tempo inferiores a zero ou superiores ou iguais a 24 horas gerarão um ArgumentException.

Criação de parâmetros

Crie objetos SqlParameter 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 deste tópico fornecem exemplos de como especificar parâmetros de data e hora. Para obter exemplos adicionais de como trabalhar com parâmetros, consulte Configuração de Parâmetros e Tipos de Dados de Parâmetros e Parâmetros do DataAdapter.

Exemplo de data

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

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 Horário

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

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 datetime2 parâmetro 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 DateTimeOffset parâmetro 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, também pode chamar AddWithValue na coleção Parameters do comando, como mostrado no seguinte fragmento de código. No entanto, AddWithValue não permite especificar o DbType ou SqlDbType para o 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 este DateTimeOffset valor, AddWithValue infere SqlDbType.DateTimeOffset. Para direcionar um tipo diferente de data ou hora do SQL Server, defina explicitamente a propriedade do SqlDbType parâmetro.

A tabela a seguir mostra quais SqlDbTypes são inferidos a partir de quais tipos de 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 métodos usados para recuperar 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 os 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 dados da coluna como padrão SqlDbType. Retorna os mesmos tipos que GetValue para os 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 de Tipo estiver definida como SQL Server 2005. O método lança InvalidCastException se os dados não puderem ser expressos como uma cadeia de caracteres.
GetTimeSpan Recupera o valor da coluna especificada como TimeSpan.
GetValue Obtém o valor da coluna especificada como o seu tipo CLR subjacente.
GetValues Recupera valores de coluna em uma matriz.
GetSchemaTable Devolve os metadados do conjunto de resultados no objeto DataTable.

Nota

Não há suporte para a nova data e hora SqlDbTypes para o código que está sendo executado 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

Pode especificar tipos de dados de data e hora usando uma variedade de formatos literais de string, que o SQL Server depois avalia em tempo de execução, convertendo-os para estruturas internas de data/hora. O SQL Server reconhece dados de data e hora entre aspas simples ('). Os exemplos a seguir demonstram alguns formatos:

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

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

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

Valores de tempo inferiores a zero ou superiores 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 seguintes artigos.

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 funções de data e hora do Transact-SQL.
Usando dados de data e hora Fornece informações sobre os tipos de dados de data e hora e funções e exemplos de como usá-los.
Tipos de dados (Transact-SQL) Descreve os tipos de dados do sistema no SQL Server.

Consulte também

  • Última atualização a