Oracle NULLIF Function

Summary: in this tutorial, you will learn how to use the Oracle NULLIF() function by practical examples.

Introduction to Oracle NULLIF() function

The Oracle NULLIF() function accepts two arguments. It returns a null value if the two arguments are equal. In case the arguments are not equal, the NULLIF() function returns the first argument.

The following illustrates the syntax of the Oracle NULLIF() function:

NULLIF(e1, e2);
Code language: SQL (Structured Query Language) (sql)

In this syntax, the e1 cannot be a literal NULL.

If both expressions evaluates to numeric values, then Oracle determines the argument with the higher numeric precedence, implicitly converts the other argument to that data type, and returns a value of that data type.

In case both expressions evaluate to non-numeric values, then they must be of the same data type, otherwise, Oracle issues an error.

For example, the following statement returns a null value because the first argument equals the second one.

SELECT
  NULLIF(100,100) -- null
FROM
  dual;
Code language: SQL (Structured Query Language) (sql)

However, the following example returns the first value (100) because the two arguments are different:

SELECT
  NULLIF(100,200) -- 0
FROM
  dual;
Code language: SQL (Structured Query Language) (sql)

The following example causes an error because the first argument is literal NULL:

SELECT
  NULLIF(NULL,100)
FROM
  dual;
Code language: SQL (Structured Query Language) (sql)

Here is the error:

ORA-00932: inconsistent datatypes: expected - got CHAR  
Code language: SQL (Structured Query Language) (sql)

The following statement also causes an error because the data types of arguments are different.

SELECT
  NULLIF(10,'20')
FROM
  dual;
Code language: SQL (Structured Query Language) (sql)

The error is:

ORA-00932: inconsistent datatypes: expected NUMBER got CHAR
Code language: SQL (Structured Query Language) (sql)

To fix it, we use the TO_CHAR() function to convert the first argument to a value of character data type:

SELECT
  NULLIF(TO_CHAR(10),'20') -- 10
FROM
  dual;
Code language: SQL (Structured Query Language) (sql)

The NULLIF() function is logically equivalent to the following searched CASE expression:

CASE
WHEN e1 = e2 THEN
  NULL
ELSE
  e1
END
Code language: SQL (Structured Query Language) (sql)

Oracle NULLIF() function example

The following statement creates a table named budgets that stores sales employees and their current and previous year sales budgets.

CREATE TABLE budgets
(
    salesman_id   NUMBER NOT NULL,
    fiscal_year SMALLINT,
    current_year  NUMBER,
    previous_year NUMBER
);
Code language: SQL (Structured Query Language) (sql)

If a budget has not been determined, it is null. The following statements insert budgets for some sales employees:

INSERT INTO budgets VALUES(54,2017,120000, 100000);  
INSERT INTO budgets VALUES(55,2017,200000, 200000);  
INSERT INTO budgets VALUES(56,2017,NULL, 150000);  
INSERT INTO budgets VALUES(57,2017,175000, 175000);  
INSERT INTO budgets VALUES(59,2017,220000, 200000);
Code language: SQL (Structured Query Language) (sql)

The following query retrieves the sales employees and their current year’s budgets. If the current year’s budget is the same as the previous year’s one, it returns a literal string “Same as last year”:

SELECT
  salesman_id,
  COALESCE(TO_CHAR(NULLIF(current_year, previous_year)), 'Same as last year') budget
FROM
  budgets
WHERE
  current_year IS NOT NULL;
Code language: SQL (Structured Query Language) (sql)

The following statement is equivalent to the one above but uses the CASE expression instead.

SELECT
  salesman_id,
  CASE
    WHEN current_year = previous_year
    THEN 'Same as last year'
    ELSE TO_CHAR(current_year)
  END
FROM
  budgets
WHERE
  current_year IS NOT NULL;
Code language: SQL (Structured Query Language) (sql)

In this tutorial, you have learned how to use the Oracle NULLIF() function to return a null if the first argument equals the second one.