Robyn Page's SQL Server Date/Time Workbench

This is a showcase review for our sponsors at CodeProject. These reviews are intended to provide you with information on products and services that we consider useful and of value to developers.

• Download sourcecode - 8Kb

Introduction

I don't think I'm in a minority of people when I confess that I learn programming skills best by trying things out! As such this "workbench", on the use of dates and times in SQL Server is a bit of a departure from the "usual" articles you'll find on Simple-Talk. It is designed so that it can be pasted in its entirety into the Query Analyser, SSMS or other GUI and the individual examples executed.

This "workbench" on use of Dates and Times in SQL is structured so it can be pasted in its entirity into the Query Analyser, SSMS or other GUI and the individual examples executed. I don't think I'm in a minority of people when I confess that I learn programming skills best by trying things out!

It provides working examples that tackle all of the common date-related requirements and problems, including:

• Inputting and Outputting dates
• Using ISDATE to check for valid dates
• Extracting parts of a date
• Finding the difference between two dates
• Formatting Dates
• Calculating dates (e.g. Start of the month)
• Practical date usage (e.g. calculating a daily total)

It also tackles some of the more tricky problems such as converting a UNIX Timestamp to a DateTime and finding DATETIME of the start of the week.

I'd like to encourage you to experiment. One never fails to come up with surprises; for example, I'd never, before writing this, considered using 'LIKE' when searching DateTime fields, or using the { t '2:40'} in a stored procedure as a literal date.

Likewise, I always like to see as many examples as possible in any articles on SQL Server. There is nothing like it for getting ideas going. Formal descriptions are fine for those with strange lumps in their brains, but I'd prefer to see clear explanations peppered with examples!

If I have any general advice, it is to use the strengths of the DATETIME data type and never attempt to bypass its use, by storing dates or times in any other formats. I've never come across a circumstance where such a practice has provided any lasting benefit.

Contents

• Inputting Dates
• Inputting Times
• Outputting Dates
• Manipulating Dates
• Formatting Dates
• Calculating Dates
• Date Conversions
• Using Dates

Inputting dates

A user enters a date into form and you need to get it into a DATETIME data type in the Database. Dates can be assigned to DateTime variables or columns as strings but these are done according to the dateformat stored for the particular language that is current. The orderin which the month (m), day (d), and year (y) is written is different in other countries. US_English (mdy) is different from british (dmy). By explicitly setting the date format you can over-ride this.

You can check your current DateFormat, amongst other things by using...

DBCC USEROPTIONS

Now, to demonstrate that getting this wrong can cause unexpected errors.....

SET language british SELECT CAST('14/2/2006' AS datetime)
                                                   --2006-02-14 00:00:00.000
SET language us_english --Changed language setting to us_english.

SELECT CAST('14/2/2006' AS datetime) --**ERROR!***

--keep speaking American, but use the european date format
SET dateformat 'dmy' --to override the language default

SELECT CAST('14/2/2006' AS datetime) --2006-02-14 00:00:00.000

SET language british SELECT CAST('14/2/2006' AS datetime) 
                                                   --2006-02-14 00:00:00.000
SET language us_english --Changed language setting to us_english.

SELECT CAST('14/2/2006' AS datetime) --2006-02-14 00:00:00.000

So any date representation based on words (e.g. febbraio, fevereiro, february) will fail in any other language that uses a different word for the a given month. To see the current language settings, use

sp_HelpLanguage

To import foregn-language dates, you must change the language setting for the connection. e.g

SET language Italiano SELECT CAST('10 febbraio 2006' AS datetime)
--Changed language setting to Italiano.
--2006-02-10 00:00:00.000
--to see the current language settings, use
/* Otherwise SQL Server is fairly accomodating, and will do its best to make 
   sense of a date.*/

--all of the following return 2006-02-01 00:00:00.000
SET language british
SELECT CAST('1 feb 2006' AS datetime)--remember, this is language dependent
SELECT CAST('1 february 2006' AS datetime)--this too
SELECT CAST('01-02-06' AS datetime)
SELECT CAST('2006-02-01 00:00:00.000' AS datetime)
SELECT CAST('1/2/06' AS datetime)
SELECT CAST('1.2.06' AS datetime)
SELECT CAST('20060201' AS datetime)

--in SQL Server 2000 and 2005 you can specify dates in ISO 8601 format
SELECT CAST('2006-02-01T00:00:00' AS datetime)
SELECT CAST('2006-02-01T00:00:00.000' AS datetime)

--and you'll be able to enter in this format whatever the settings!

The ANSI standard date uses braces, the marker 'd' to designate the date, and a date string

SELECT { d '2006-02-01' }

The ANSI standard datetime uses 'ts' instead of 'd' and adds hours, minutes, and seconds to the date (using a 24-hour clock)

SELECT { ts '2006-02-01 00:00:00' }

If you use the CONVERT function, you can override the dateformat by choosing the correct CONVERT style (103 is the British/French format of dd/mm/yyyy (see later for a list of all the styles)

SET language us_english
SELECT CONVERT(DateTime,'25/2/2006',103) --works fine

--whereas the 100 style uses the default supplied by the dateformat.
SELECT CONVERT(DateTime,'25/2/2006',100) --error!

The IsDate function

The IsDate(expression) function is used for checking strings to see if they are valid dates. It is language-dependent.

ISDATE (Expression) returns 1 if the expression is a valid date (according to the language and dateformat mask) and 0 if it isn't

The following demonstration uses ISDATE to test out the input of strings as dates.

SET LANGUAGE british SET nocount ON
DECLARE @DateAsString VARCHAR(20),
@DateAsDateTime DateTime

SELECT @DateAsString='2 february 2002'
SELECT [input]=@DateAsString

IF (ISDATE(@DateAsString)=1)
BEGIN

   SELECT @DateAsDateTime=@DateAsString
   SELECT [the Date]=COALESCE(CONVERT(CHAR(17),@DateAsDateTime,113), 
          'unrecognised')
END
ELSE
   SELECT [the Date] ='That was not a date'

Inputting Times

Times can be input into SQL Server just as easily. There are no separate time and date data types for storing only times or only dates. It is not necessary. If only a time is specified when setting a datetime, the date is assumed to be the first of january 1900, the year of the start of the new millenium.

If only a date is specified, the time defaults to Midnight.

e.g.

SELECT CAST ('17:45' AS datetime) -- 1900-01-01 17:45:00.000
SELECT CAST ('13:20:25:850' AS datetime) -- 1900-01-01 13:20:25.850
SELECT CAST ('14:30:20.9' AS datetime) -- 1900-01-01 14:30:20.900
SELECT CAST ('3am' AS datetime) -- 1900-01-01 03:00:00.000
SELECT CAST ('10 PM' AS datetime) -- 1900-01-01 22:00:00.000
SELECT CAST ('02:50:20:500AM' AS datetime) -- 1900-01-01 02:50:20.500
SELECT CONVERT (DateTime,'02:50:20',108) -- 1900-01-01 02:50:20.000

--And times can be converted back from the DATETIME into the ascii VARCHAR 
--version as follows...
SELECT CONVERT(VARCHAR(20),GETDATE(),108) -- 15:08:52

--108 is the hh:mm:ss CONVERT style (See next section for the complete list)
SELECT LTRIM(RIGHT(CONVERT(CHAR(19),GETDATE(),100),7))-- 3:10PM
SELECT LTRIM(RIGHT(CONVERT(CHAR(26),GETDATE(),109),14)) -- 3:19:18:810PM

and so on.

You can input times a different way (note that the brackets are curly braces

SELECT { t '09:40:00' }

which unexpectedly gives 09.40 today, rather than 9:40 on the first of January 1900! (as one might expect from the other time input examples)

--this is valid in a stored procedure too
CREATE PROCEDURE #spExperiment AS
SELECT { t '09:40:00' }
GO

EXEC #spExperiment

Outputting dates

Dates can be output as strings in a number of ways using the CONVERT function and CONVERT styles These styles are numeric codes that correspond with the most popular date formats. You get much more versatility with the CONVERT function than the CAST function.

The CONVERT styles override the setting of the DATEFORMAT but use the current language setting where the date format uses the name of the month.

If you run the following code you will get a result that illustrates all the built-in formats , using the current date and time

DECLARE @types TABLE(
[2 digit year] INT NULL,
[4 digit year] INT NOT NULL, 
name VARCHAR(40))
SET LANGUAGE british SET nocount ON

--Each select statement is followed by an example of a string that uses the 
--style
INSERT INTO @types 
SELECT NULL,100,'Default'--Oct 17 2006 9:29PM
INSERT INTO @types 
SELECT 1,101, 'USA'--10/17/06 or 10/17/2006
INSERT INTO @types 
SELECT 2,102, 'ANSI'--06.10.17 or 2006.10.17
INSERT INTO @types 
SELECT 3,103, 'British/French'--17/10/06 or 17/10/2006
INSERT INTO @types 
SELECT 4,104, 'German'--17.10.06 or 17.10.2006
INSERT INTO @types 
SELECT 5,105, 'Italian'--17-10-06 or 17-10-2006
INSERT INTO @types 
SELECT 6,106, 'dd mon yy'--17 Oct 06 or 17 Oct 2006 
INSERT INTO @types 
SELECT 7,107, 'Mon dd, yy'--Oct 17, 06 or Oct 17, 2006
INSERT INTO @types 
SELECT 8,108, 'hh:mm:ss' --21:29:45 or 21:29:45
INSERT INTO @types 
SELECT NULL,109, 'Default + milliseconds'--Oct 17 2006 9:29:45:500PM
INSERT INTO @types 
SELECT 10,110,'USA' --10-17-06 or 10-17-2006
INSERT INTO @types 
SELECT 11,111,'JAPAN'--06/10/17 or 2006/10/17
INSERT INTO @types 
SELECT 12,112,'ISO'--061017 or 20061017
INSERT INTO @types 
SELECT NULL,113,'Europe default(24h) + milliseconds'--17 Oct 2006 21:29:45:500
INSERT INTO @types 
SELECT 14,114,'hh:mi:ss:mmm (24h)' --21:29:45:500 or 21:29:45:500
INSERT INTO @types 
SELECT NULL,120,'ODBC canonical (24h)'--2006-10-17 21:29:45
INSERT INTO @types 
SELECT NULL,121, 'ODBC canonical (24h)+ milliseconds' 
                                                   --2006-10-17 21:29:45.500
INSERT INTO @types 
SELECT NULL,126, 'ISO8601'--2006-10-17T21:29:45.500

--insert into @types Select null,127, 'ISO8601 with time zone' 
--SQL Server 2005 only!
INSERT INTO @types 
SELECT NULL,130, 'Hijri'--25 ????? 1427 9:33:21:340PM
INSERT INTO @types 
SELECT NULL,131, 'Hijri'--25/09/1427 9:29:45:500PM 
SELECT [name], [2 digit year]=COALESCE(CONVERT(VARCHAR(3),[2 digit year]),'-'), 
       [example]=CASE WHEN [2 digit year] IS NOT NULL 
                      THEN CONVERT(VARCHAR(30),GETDATE(),[2 digit year]) 
                       ELSE '-' END,
       [4 digit year]=COALESCE(CONVERT(VARCHAR(3),[4 digit year]),'-'), 
       [example]=CASE WHEN [4 digit year] IS NOT NULL 
                      THEN CONVERT(VARCHAR(30),GETDATE(),[4 digit year]) 
                      ELSE '-' END
FROM @types

Manipulating dates

Getting the CURRENT date can be done BY three functions:

SELECT GETDATE() --the local date and time
SELECT GETUTCDATE() --the UTC or GMT date and time

ELECT CURRENT_TIMESTAMP--synonymous with GetDate()

When extracting parts of a DateTime you have some handy functions that return integers DAY, MONTH, YEAR .. here we get the day, month and year as integers

SELECT DAY(GETDATE()),MONTH(GETDATE()),YEAR(GETDATE())

The functions DAY MONTH AND YEAR are shorthand for the equivalent DATEPART command but for more general use the DATEPART function is more versatile

SELECT DATEPART(DAY,GETDATE()),DATEPART(MONTH,GETDATE()),
       DATEPART(YEAR,GETDATE())

DATEADD

DATEADD will actually add a number of years, quarters, months,weeks,days, hours, minutes, seconds, or milliseconds to your specifced date

• year (yy or yyyy)
• quarter (qq or q)
• month (mm or m)
• week (wk or ww)
• Day (dayofyear, dy, y, day, dd, d, weekday or dw)
• hour (hh)
• minute (mi or n),
• second (ss or s)
• millisecond (ms)

in these examples we compare the date with the DATEADDed date so you can see the effect that the DATEADD is having to it

SELECT '2007-01-01 00:00:00.000', DATEADD(YEAR,100,'2007-01-01 00:00:00.000') 
SELECT '2007-01-01 00:00:00.000', DATEADD(quarteer,100,'2007-01-01 00:00:00.000') 
SELECT '2007-01-01 00:00:00.000', DATEADD(MONTH,100,'2007-01-01 00:00:00.000') 
SELECT '2007-01-01 00:00:00.000', 
       DATEADD(dayofyear,100,'2007-01-01 00:00:00.000') 
SELECT '2007-01-01 00:00:00.000', DATEADD(DAY,100,'2007-01-01 00:00:00.000') 
SELECT '2007-01-01 00:00:00.000', DATEADD(week,100,'2007-01-01 00:00:00.000') 
SELECT '2007-01-01 00:00:00.000', DATEADD(weekday,100,'2007-01-01 00:00:00.000') 
SELECT '2007-01-01 00:00:00.000', DATEADD(hour,100,'2007-01-01 00:00:00.000') 
SELECT '2007-01-01 00:00:00.000', DATEADD(minute,100,'2007-01-01 00:00:00.000') 
SELECT '2007-01-01 00:00:00.000', 
       DATEADD(second ,100,'2007-01-01 00:00:00.000') 
SELECT '2007-01-01 00:00:00.000', 
       DATEADD(millisecond,100,'2007-01-01 00:00:00.000')

getting the current date can be done by three functions

SELECT GETDATE() --the loval date and time
SELECT GETUTCDATE() --the UTC or GMT date and time
SELECT CURRENT_TIMESTAMP--synonymous with GetDate()

DATEDIFF

DATEDIFF returns an integer of the difference between two dates expressed in Years, quarters, Months,Weeks,Days,Hours,minutes,seconds or milliseconds (it counts the boundaries).

SELECT DATEDIFF(DAY,'1 feb 2006','1 mar 2006')--28
SELECT DATEDIFF(DAY,'1 feb 2008','1 mar 2008')--29. Hmm must be a leap year!

We will give some practical examples of its use later on in the workshop

DATENAME

Unlike DatePart, which returns an integer, DATENAME returns a NVarchar representing the Year,quarter,Month,Week,day of the week,Day of the year,Hour,minute,second or millisecond within the date. The Month and weekday are given in full from the value in the sysLanguages table.

SELECT DATENAME (YEAR,GETDATE()) --2006
SELECT DATENAME (quarter,GETDATE()) --4
SELECT DATENAME (MONTH,GETDATE()) --October
SELECT DATENAME (dayofyear,GETDATE()) --285
SELECT DATENAME (DAY,GETDATE()) --12
SELECT DATENAME (week,GETDATE()) --42
SELECT DATENAME (weekday,GETDATE()) --Thursday
SELECT DATENAME (hour,GETDATE()) --9
SELECT DATENAME (minute,GETDATE()) --32
SELECT DATENAME (second ,GETDATE()) --8
SELECT DATENAME (millisecond,GETDATE()) --875 

DATEPART

DATEPART returns an integer representing the part of the date requested in the 1st parameter. You can use year (yy or yyyy), quarter (qq or q), month (mm or m), dayofyear (dy or y) day (dd or d), week (wk or ww) , weekday (dw),hour (hh), minute (mi or n), second (ss or s), or millisecond (ms)

SELECT DATEPART(YEAR,GETDATE()) --2006
SELECT DATEPART(quarter,GETDATE()) --4
SELECT DATEPART(MONTH,GETDATE()) --10
SELECT DATEPART(dayofyear,GETDATE()) --285
SELECT DATEPART(DAY,GETDATE()) --12
SELECT DATEPART(week,GETDATE()) --42
SELECT DATEPART(weekday,GETDATE()) --4
SELECT DATEPART(hour,GETDATE()) --9
SELECT DATEPART(minute,GETDATE()) --32
SELECT DATEPART(second ,GETDATE()) --8
SELECT DATEPART(millisecond,GETDATE()) --875 

Formatting Dates

Examples of calculating and formatting dates

--To get the full Weekday name
SELECT DATENAME(dw,GETDATE())

--To get the abbreviated Weekday name (MON, TUE, WED etc)
SELECT LEFT(DATENAME(dw,GETDATE()),3)

--ISO-8601 Weekday number
SELECT DATEPART(dw,GETDATE())+(((@@Datefirst+3)%7)-4)

--Day of the month with leading zeros
SELECT RIGHT('00' + CAST(DAY(GETDATE()) AS VARCHAR),2)

--Day of the month without leading space
SELECT CAST(DAY(GETDATE()) AS VARCHAR)

--day of the year
SELECT DATEPART(dy,GETDATE())

--number of the week in the year
SELECT DATEPART(week,GETDATE())

--ISO-8601 number of the week of the year (monday as the first day of the week)
SET datefirst 1 SELECT DATEPART(week,GETDATE()) 

--you may need to preserve and restore the value
--full name of the month
SELECT DATENAME(MONTH,GETDATE())

--Abbreviated name of the month
SELECT LEFT(DATENAME(MONTH,GETDATE()),3)--not true of finnish or french!

--Number of the month with leading zeros
SELECT RIGHT('00' + CAST(MONTH(GETDATE()) AS VARCHAR),2)

--two-digit year
SELECT RIGHT(CAST(YEAR(GETDATE()) AS VARCHAR),2)

--four-digit year
SELECT CAST(YEAR(GETDATE()) AS VARCHAR)

--hour (00-23)
SELECT DATEPART(hour,GETDATE())

--Hour (01-12)
SELECT LEFT(RIGHT(CONVERT(CHAR(19),GETDATE(),100),7),2)

--minute
SELECT DATEPART(minute,GETDATE())

--second
SELECT DATEPART(second,GETDATE())

--PM/AM indicator
SELECT RIGHT(CONVERT(CHAR(19),GETDATE(),100),2)

--time in 24 hour notation
SELECT CONVERT(VARCHAR(8),GETDATE(),8)

--Time in 12 hour notation
SELECT RIGHT(CONVERT(CHAR(19),GETDATE(),100),7)

--timezone (or daylight-saving)
SELECT DATEDIFF(hour, GETDATE(), GETUTCDATE())

----ordinal suffix for the date
SELECT SUBSTRING('stndrdthththththththththththththththththstndrdthththththththst'
,(DATEPART(DAY,GETDATE())*2)-1,2)

--full date (the variations are infinite. Here is one example
SELECT DATENAME(dw,GETDATE())+', '+ STUFF(CONVERT(CHAR(11),GETDATE(),106),3,0,
SUBSTRING('stndrdthththththththththththththththththstndrdthththththththst'
,(DATEPART(DAY,GETDATE())*2)-1,2))

--e.g. Thursday, 12th Oct 2006

Calculating Dates by example

-- now
SELECT GETDATE()

-- Start of today (first thing)
SELECT CAST(CONVERT(CHAR(11),GETDATE(),113) AS datetime)

-- Start of tomorrow (first thing)
SELECT CAST(CONVERT(CHAR(11),DATEADD(DAY,1,GETDATE()),113) AS datetime)

-- Start of yesterday (first thing)
SELECT CAST(CONVERT(CHAR(11),DATEADD(DAY,-1,GETDATE()),113) AS datetime)

-- This time Next thursday (today if it is thursday)
SELECT DATEADD(DAY,((7-DATEPART(dw,GETDATE())+(((@@Datefirst+3)%7)+2)) % 7),
       GETDATE())

-- This time Last friday (today if it is friday)
SELECT DATEADD(DAY,-((7-DATEPART(dw,GETDATE())+(((@@Datefirst+3)%7)+3)) % 7),
       GETDATE())

-- Two hours time
SELECT DATEADD(hour,2,GETDATE())

-- Two hours ago
SELECT DATEADD(hour,-2,GETDATE())

-- Same date and time last month
SELECT DATEADD(MONTH,-1,GETDATE())

-- Start of the month
SELECT CAST('01 '+ RIGHT(CONVERT(CHAR(11),GETDATE(),113),8) AS datetime)

-- Start of last month
SELECT CAST('01 ' + RIGHT(CONVERT(CHAR(11),DATEADD(MONTH,-1,GETDATE()),113),8) 
            AS datetime)

-- Start of next month
SELECT CAST('01 '+ RIGHT(CONVERT(CHAR(11),DATEADD(MONTH,1,GETDATE()),113),8) 
            AS datetime)

-- Ten minutes ago
SELECT DATEADD(minute,-10,GETDATE())

-- Midnight last night
SELECT CAST(CONVERT(CHAR(11),GETDATE(),113) AS datetime)

-- Midnight tonight
SELECT CAST(CONVERT(CHAR(11),DATEADD(DAY,1,GETDATE()),113) AS datetime)

-- Three weeks ago
SELECT DATEADD(week,-3,GETDATE())

-- Start of the week (this depends on your @@DateFirst setting)
SELECT DATEADD(DAY, -(DATEPART(dw,GETDATE())-1),GETDATE())

-- last year
SELECT DATEADD(YEAR,-1,GETDATE())

-- new year, this year
SELECT CAST('01 Jan'+ DATENAME(YEAR,GETDATE()) AS datetime)

-- new year, last year
SELECT CAST('01 Jan'+ DATENAME(YEAR,DATEADD(YEAR,-1,GETDATE())) AS datetime)

-- next christmas
SELECT CASE WHEN DATEPART(dy,GETDATE()) < 
                         DATEPART(dy,'25 Dec' + DATENAME(YEAR,GETDATE()))
THEN CAST('25 Dec'+ + DATENAME(YEAR,GETDATE()) AS datetime)
ELSE CAST('25 Dec'+ CAST(DATEPART(YEAR,GETDATE())+1 AS VARCHAR) AS datetime) 
END

Date Conversions

The DATETIME data type stores the Date and time data from January 1, 1753 to December 31, 9999, to an accuracy of one 3.33 milliseconds. Values are rounded.

Values are stored as two 4-byte integers:

• . The first 4 bytes store the number of days +- from the base date, January 1, 1900. The base date is the system reference date.
• . The second 4 bytes store the time of day represented as the number of milliseconds after midnight.

Values for datetime earlier than January 1, 1753 are not permitted.

When converting from SQL Server dates to Unix timestamps, the dates are rounded to the nearest second (Unix timestamps are only accurate to the nearest second) SQL Server date to UNIX timestamp (based on seconds since standard epoch of 1/1/1970)

SELECT DATEDIFF(second,'1/1/1970',GETDATE())

-- UNIX timestamp to SQL Server
SELECT DATEADD(second, 1160986544, '1/1/1970')

Using dates

When storing dates, always us the datetime data type. Do not feel tempted to use tricks such as storing the year, month or day as integers, with the idea that this will help retrieval and aggregation for reports. It never does. The manipulation of datetimes is so critical to SQL Server's performance that it is highly optimised. indexes based on DateTimes work very well, sort properly, and allow fast partitioning on a variety of criteria such as week, month, year-to-date and so on. If, for example, you store a list of purchases by date in a table such as PURCHASES you can find the sum for the previous week by...

SELECT HERE purchaseDate LIKE '%9:40%'

--or all purchases in the month of february
SELECT COUNT(*) FROM [purchases]
WHERE purchaseDate LIKE '%feb%'

--all purchases where there is a 'Y' in the month (matches only May!)
SELECT DATENAME(MONTH, insertionDate), COUNT(*) FROM [purchases]
WHERE purchaseDate LIKE '%y%'
GROUP BY DATENAME(MONTH, purchaseDate)

This Like trick is of limited use and should be used with considerable caution as it uses artifice to get its results