SQL Server Reference Guide

In previous tutorials, I've covered the data types a SQL Server table has available. This defines the format of the data in a column. In our last two tutorials, I covered views and stored procedures. These provide a view of data or a computation/result of data. Now that you have that information, we can move on to this week's topic.

In this tutorial, we'll see how Microsoft has combined these two concepts into a really useful construct: the User Defined Function (UDF).

A User Defined Function really brings together the view and the stored procedure. When you create a User Defined Function, you can specify that it accepts one or more parameters, or none. The User Defined Function will always return some kind of value, and therein lies the tale, as they say.

A User Defined Function is another of the text objects, such as views or stored procedures, which can accept an input, perform some work, and then return data. You might be thinking that you can do that with a view, and to some extent you can. You might also think that you can do the same thing with a stored procedure, and to some extent you can. So what's the big advantage to User Defined Functions?

Well, for starters, stored procedures can't be part of a SELECT statement, except to set a variable. A User Defined Function can. You can include it right there in the SELECT statement just like a column.

Views doesn't support recursion, but User Defined Functions do. In addition, a main benefit is the numerous places that a User Defined Function fits. You can break out complex work into reusable segments; then the developers or end users can get at the resulting recordset without having to know all that logic. This also allows you to create object-style databases, so that the User Defined Function can change and the calling code doesn't have to.

We need to cover some important concepts before we create our first User Defined Function. Let's take a look at the basic creation syntax:

CREATE FUNCTION [OWNER].[FUNCTION NAME] (PARAMETER LIST) 
RETURNS return_type_spec AS 
BEGIN 
 -DO WORK HERE- 
RETURN 
END

Let's break that down a bit. First we have the line

CREATE FUNCTION [OWNER].[FUNCTION NAME] (@PARAMETER, @PARAMETER) 

CREATE FUNCTION looks pretty normal, that just starts the command. Yes, the [OWNER]. bit is important; you won't be able to use the function later unless you call it with that preface.

You follow that by the parameters you want to be able to pass the function, in parentheses. Note that you preface the variables with an @ symbol. You don't have to have any variables on the way in, but you do still use the parentheses.

The next bit is part of the magic I wanted to show you:

RETURNS return_type_spec AS 

The RETURNS statement sets the kind of data that will come back to the caller. There are two main categories of things that will come back to the user.

The first type of return value is a scalar value. Remember your high school math classes, when you learned about functions? No? Well, a scalar value (in this case, anyway) means a single item. So the first kind of value you can get from calling a User Defined Function is a single result, such as a string, a Boolean value, or a number.

Next, you can return an entire table. Actually, you can return two kinds of tables. The first is an inline table. This means that you're just doing a fairly straightforward SELECT FROM WHERE statement. In this case, the table's structure will automatically set itself up. You don't have to set up anything else.

The second type of table that you can get is called a multistatement table. This type of table is a bit more complex, meaning that there may be subselects or other logic rather than just a simple SELECT statement. In this case, you have to set up the structure, in parenthesis, right after the RETURNS statement. I'll show you one of those in a minute.

Next, we have the

BEGIN 
-DO WORK HERE- 
RETURN 
END

block. The BEGIN starts the block, and then you do your work. What kind of work? Well, that depends on what you're returning. If you're returning a scalar value, you need to make sure that you only send one result back, whether that's a single field or the result of some programming logic.

Notice the RETURN statement. It's different than that RETURNS clause we saw a moment ago. The RETURN statement passes the value(s) from the code block to the calling program. You can just include a RETURN, or you can also specify a RETURN @VariableName if that's what the calling program expects.

For an inline table to be returned, the format changes a bit. In place of the BEGIN and END lines, here's what the format looks like:

RETURN( 
SELECT 
FROM
WHERE
)

Notice that the RETURN moves up to define the SELECT statements. The code block should have a simple SELECT FROM WHERE format. On the other hand, if you're doing a multistatement table return, you can get a bit more elaborate. There are restrictions here, which we'll get to in a moment.

You'll also handle the returns from a table type differently than the scalar type. I'll show you those in the examples section.

Now that we have the concept well in hand, let's create a a few UDFs.

First, we'll create a User Defined Function that returns a simple scalar value to the caller. Let's make this one do something useful, like returning the date of a database's last backup:

CREATE FUNCTION dbo.ufn_DBBackupDate
 ( @dbname varchar(50) )
RETURNS varchar(10)
AS
BEGIN
 DECLARE @budate varchar(10)
 SELECT @budate = 
 ISNULL(Convert(char(10), MAX(backup_finish_date), 101), 'Never') 
 FROM master.dbo.sysdatabases B 
    LEFT OUTER JOIN msdb.dbo.backupset A 
    ON A.database_name = B.name 
    AND A.type = 'D' 
 WHERE B.Name = @dbname
 RETURN (@budate)
END
GO

You've seen the other parts before, but the bits between the BEGIN and END might take a little investigation. All this does is use the data stored in the master database to probe when the last backup was taken. To get at the results of a scalar function, you can call the User Defined Function like this:

SELECT dbo.ufn_DBBackupDate('pubs')
GO

Hmm. Making that a return a Boolean value would let you perform some magic for a backup script, or you could include the current version in a view, so the users aren't bothered with the logic behind it, or even as a column in a table. There are many uses you'll find for this kind of script.

OK, how about another example, this time a table? Let's make a function that gets a list of all the authors from the pubs database that have written a book, and actually sold it!

CREATE FUNCTION dbo.ufn_GetAuthorsWhoSoldBooks()
RETURNS table
AS
RETURN(
 SELECT distinct au_fname, au_lname 
 FROM authors a 
 INNER JOIN titleauthor b
 ON a.au_id = b.au_id
 INNER JOIN sales c
 ON b.title_id = c.title_id
)
GO

Notice the change in the RETURN statement. You also access this type of function differently. When you want the results from this function, treat it just like a table:

SELECT * FROM dbo.ufn_GetAuthorsWhoSoldBooks()
GO

But because it's a function, you could just as easily have declared a variable to perform your selects with, and allowed the table to change the return, just like a view!

Finally, there's the multistatement table. This one is a bit more complex, because you have to declare the table layout for the return. This simple example returns a table composed of a SELECT statement using a self-join, showing the books that have multi-authors:

CREATE FUNCTION dbo.ufn_MultiAuthors ()
RETURNS @MultiAuthors table (
 author_id char(11),
 title_id char(6))
AS
BEGIN
    INSERT @MultiAuthors
        SELECT DISTINCT a.au_id, a.title_id
        FROM titleauthor a 
           INNER JOIN titleauthor b 
           ON a.title_id = b.title_id
        WHERE a.au_id <> b.au_id
    RETURN
END

While the example isn't particularly useful, its structure is simple enough to show you how it works. You can see that it all begins just as the other types of UDFs do, with the CREATE FUNCTION statement. The next line, however, declares a variable and sets it to a table type. Just after that, the structure of the table is created to hold the results.

Next, you see the BEGIN and END statements again. In between them in the work block, you begin the block with an insertion routine for the table.

Just after the INSERT command comes the data that will be inserted. This is a simple self-join, but you get the idea. You can get quite a bit more elaborate here as your needs dictate.

You end the work block with the RETURN statement, and then end the entire section with END – and there you have it!

You'll want to play with your select statements to ensure the field order is the same as the table structure you built in the first part of the function.

There are a few limitations to keep in mind when you design a User Defined Function. First: text, ntext, image and timestamp data types are not supported in UDFs.

Also, you can't create non-deterministic functions. This means that your functions need to return the save value if provided with the same parameters. Non-deterministic functions produce different results each time they are called, even if any supplied parameters are the same.

You can't use Statements that update, insert, or delete tables or views in your User Defined Function, and you can't use Cursor fetch operations that return data to the client.

Other than these restrictions, you can use UDFs for some pretty cool things. I highly recommend that you work your way through the links at the end of this article. See you next week!

Online Resources: Database Objects, User Defined Functions

The SQLTeam asks - What are the benefits of User-Defined Functions?

Data Points: SQL Server User-defined Functions – from MSDN Magazine, John Papa

Explore User-Defined Functions in SQL Server 2000 (Note: subscription required).

Easily Create Microsoft SQL Server User-Defined Scalar Functions – Excel Tool!

Some Useful User-Defined Functions for SQL Server 2000

More useful functions from Microsoft are here

SQL Server 2000's user-defined functions add flexibility, cut coding time – find out more here!

Create User Defined Functions in SQL Server 2000.

SQL Server 2000 User-Defined Functions White Paper

Define Your Own Functions in SQL Server 2000

User Defined Functions Introduction from easy-sql

15 Seconds: Introduction to Transact SQL User-Defined Functions

InformIT Articles and Sample Chapters: Database Objects, User Defined Functions

SQL Server User-Defined Functions (UDFs) MAY 2, 2003 by Baya Pavliashvili