NULL-Related Functions (NVL, DECODE, NVL2, COALESCE, NULLIF, LNNVL, NANVL, SYS_O _!

A _NONNULL"
This article provides a summary of the functions available for handling null values. For a more detailed description follow the links are the bottom of the article. Background NVL D !"D NVL# !"$L %! N&LL'F LNNVL N$NVL %(%)"*)+$*)N"NN&LL

#ac$%&ound
+ost of the e,amples in this article re-uire the following table. DROP TABLE null_test_tab; CREATE TABLE null_test_tab ( id NUMBER, col1 ARC!AR"(1#$, col" ARC!AR"(1#$, col% ARC!AR"(1#$, col& ARC!AR"(1#$ $; 'N(ERT 'NTO 'N(ERT 'NTO 'N(ERT 'NTO 'N(ERT 'NTO COMM'T; null_test_tab null_test_tab null_test_tab null_test_tab )alues )alues )alues )alues (1, (", (%, (&, *ONE*, *T+O*, *T!REE*, *,OUR*$; NULL, *T+O*, *T!REE*, *,OUR*$; NULL, NULL, *T!REE*, *,OUR*$; NULL, NULL, *T!REE*, *T!REE*$;

'f we -uery the data in the table we see the following output. (-L. (ELECT / ,ROM null_test_tab ORDER B0 id; 'D COL1 1111111111 1111111111 1 ONE " % & COL" 1111111111 T+O T+O COL% 1111111111 T!REE T!REE T!REE T!REE COL& 1111111111 ,OUR ,OUR ,OUR T!REE

& 2o3s selected4 (-L. .emember/ comparisons against null always result in null/ so -ueries can0t use regular comparison operators like 121 or 1321. (-L. (ELECT / ,ROM null_test_tab +!ERE col1 5 NULL ORDER B0 id; no 2o3s selected (-L. 'nstead they must use the '( NULL or '( NOT NULL operators. (-L. (ELECT / ,ROM null_test_tab +!ERE col1 '( NULL ORDER B0 id; 'D COL1 COL" 1111111111 1111111111 1111111111 " T+O % & % 2o3s selected4 (-L. COL% 1111111111 T!REE T!REE T!REE COL& 1111111111 ,OUR ,OUR T!REE

NVL
The N L function allows you to replace null values with a default value. 'f the value in the first parameter is null/ the function returns the value in the second parameter. 'f the first parameter is any value other than null/ it is returned unchanged. 4e know that !"L5 in the test table contains null in all rows e,cept the first. &sing the N L function we replace the null values with 06 ."0. (-L. (ELECT id, N L(col1, *6ERO*$ A( out7ut ,ROM null_test_tab ORDER B0 id; 'D 1111111111 1 " % & OUTPUT 1111111111 ONE 6ERO 6ERO 6ERO

& 2o3s selected4 (-L.

DECODE

The DECODE function is not specifically for handling null values/ but it can be used in a similar way to the N L function/ as shown by the following e,ample. (-L. (ELECT id, DECODE(col1, NULL, *6ERO*, col1$ A( out7ut ,ROM null_test_tab ORDER B0 id; 'D 1111111111 1 " % & OUTPUT 1111111111 ONE 6ERO 6ERO 6ERO

& 2o3s selected4 (-L.

NVL2
The N L" function accepts three parameters. 'f the first parameter value is not null it returns the value in the second parameter. 'f the first parameter value is null/ it returns the third parameter. The following -uery shows N L" in action. (-L. (ELECT id, N L"(col1, col", col%$ A( out7ut ,ROM null_test_tab ORDER B0 id; 'D 1111111111 1 " % & OUTPUT 1111111111 T+O T!REE T!REE T!REE

& 2o3s selected4 (-L. The first row in the test table has a not null value in !"L5/ so the value of !"L# is returned. $ll other rows contains null in !"L5/ so the value of !"L7 is returned.

COALESCE
The COALE(CE function was introduced in "racle 8i. 't accepts two or more parameters and returns the first non9null value in a list. 'f all parameters contain null values/ it returns null. (-L. (ELECT id, COALE(CE(col1, col", col%$ A( out7ut ,ROM null_test_tab ORDER B0 id; 'D 1111111111 1 " OUTPUT 1111111111 ONE T+O

% T!REE & T!REE & 2o3s selected4 (-L.

NULLIF
The NULL', function was introduced in "racle 8i. 't accepts two parameters and returns null if both parameters are e-ual. 'f they are not e-ual/ the first parameter value is returned. 'n our test table the values of !"L7 and !"L: are e-ual in row :/ so we would only e,pect null returned for that row using the following -uery. (-L. (ELECT id, NULL',(col%, col&$ A( out7ut ,ROM null_test_tab ORDER B0 id; 'D 1111111111 1 " % & OUTPUT 1111111111 T!REE T!REE T!REE

& 2o3s selected4 (-L.

LNNVL
The LNN L function has been available since at least "racle 8i/ but was undocumented until "racle 55g. 't is used in a where clause to evaluate a condition. 'f this condition evaluates to false or unknown/ it returns true. 'f the condition evaluates to true/ it returns false. (-L. (ELECT id, col% ,ROM null_test_tab +!ERE LNN L(col1 '( NULL$ ORDER B0 id; 'D COL% 1111111111 1111111111 1 T!REE 1 2o3 selected4 (-L. (ELECT id, col% ,ROM null_test_tab +!ERE LNN L(col" 5 *T+O*$ ORDER B0 id; 'D 1111111111 % & COL% 1111111111 T!REE T!REE

" 2o3s selected4

(-L. (ELECT id, col% ,ROM null_test_tab +!ERE LNN L(col" 85 *T+O*$ ORDER B0 id; 'D 1111111111 1 " % & COL% 1111111111 T!REE T!REE T!REE T!REE

& 2o3s selected4 (-L.

NANVL
The NAN L function was introduced in "racle 5;g for use with the B'NAR0_,LOAT and B'NAR0_DOUBLE datatypes/ which can contain a special 1Not a Number1 or 1NaN1 value. The function is similar to N L/ but rather than testing for null it tests for 1NaN1 values. The following table will be used to demonstrate it. DROP TABLE nan)l_test_tab; CREATE TABLE nan)l_test_tab ( id NUMBER, col1 B'NAR0_DOUBLE $; 'N(ERT 'NTO 'N(ERT 'NTO 'N(ERT 'NTO 'N(ERT 'NTO COMM'T; nan)l_test_tab nan)l_test_tab nan)l_test_tab nan)l_test_tab ALUE( ALUE( ALUE( ALUE( (1, (", (%, (&, 1"%&49:;<$; *'N,*$; *1'N,*$; *NaN*$;

'f we -uery the table we see the following data. (ELECT / ,ROM nan)l_test_tab ORDER B0 id; 'D COL1 1111111111 1111111111 1 14"%9E=##% " 'n> % 1'n> & Nan & 2o3s selected4 (-L. Ne,t/ we -uery the data again/ but convert any 1NaN1 values to 1;1 using the NAN L function. (ELECT id, col1, NAN L(col1, #$ A( out7ut ,ROM nan)l_test_tab;

'D COL1 OUTPUT 1111111111 1111111111 1111111111 1 14"%9E=##% 14"%9E=##% " 'n> 'n> % 1'n> 1'n> & Nan # & 2o3s selected4 (-L.

SYS_O _!A _NONNULL

4e have seen that a comparison of 1N&LL 2 N&LL1 will always return false/ but sometimes you want it to return true. 't is possible to make this happen using the N L and DECODE functions/ but this relies on you converting the null value to another value that you hope will never be present in the column or variable. (ELECT id, *col15col"* ,ROM null_test_tab +!ERE N L(col1, *8null8*$ 5 N L(col", *8null8*$; 'D 1111111111 % & *COL15COL 111111111 col15col" col15col"

" 2o3s selected4 (-L. (ELECT id, *col15col"* ,ROM null_test_tab +!ERE DECODE(col1, NULL, *8null8*, col1$ 5 DECODE(col", NULL, *8null8*, col"$; 'D 1111111111 % & *COL15COL 111111111 col15col" col15col"

" 2o3s selected4 (-L. $n alternative is to use the undocumented (0(_OP_MAP_NONNULL function to allow null matches. (ELECT id, *col15col"* ,ROM null_test_tab +!ERE (0(_OP_MAP_NONNULL(col1$ 5 (0(_OP_MAP_NONNULL(col"$; 'D *COL15COL 1111111111 111111111

% col15col" & col15col" " 2o3s selected4 (-L.

NVL, NVL2 or COALESCE?

In Oracle, as in other RDBMSs, nulls should be given a special treatment. In Oracle, there are three (maybe more? !unctions that deal "ith nulls, #$%, #$%& and 'O(%)S'). I "ould li*e to as* you a +uestion, but !irst, let me +uic*ly re!resh my memory, #$% ( e-pr. , e-pr& I! e-pr. is null, then #$% returns e-pr&. I! e-pr. is not null, then #$% returns e-pr.. #$%& ( e-pr. , e-pr& , e-pr/ I! e-pr. is null, then #$%& returns e-pr/. I! e-pr. is not null, then #$%& returns e-pr&. 'O(%)S')(e-pr0,e-pr12 Returns the !irst non3null e-pr in the e-pression list. I can also use '(S) and D)'OD) to deal "ith nulls. (ll o! the !ollo"ing +ueries return the same result, 4sing #$%,

!R?@E. select n)l(coAAission_7ct,#$ " >2oA eA7loBees % 3Ce2e coAAission_7ct is null & and 2o3nuA 5 1; N L(COMM'(('ON_PCT,#$ 111111111111111111111 #
4sing #$%&,

!R?@E. select n)l"(coAAission_7ct,coAAission_7ct,#$ " >2oA eA7loBees % 3Ce2e coAAission_7ct is null & and 2o3nuA 5 1; N L"(COMM'(('ON_PCT,COMM'(('ON_PCT,#$ 1111111111111111111111111111111111111 #
4sing 'O(%)S'),

!R?@E. select COALE(CE(coAAission_7ct,#$ " >2oA eA7loBees

% &

3Ce2e coAAission_7ct is null and 2o3nuA 5 1;

COALE(CE(COMM'(('ON_PCT,#$ 11111111111111111111111111 #
4sing '(S),

!R?@E. select " case % 3Cen coAAission_7ct is null tCen # & else coAAission_7ct 9 end coAAission_7ct : >2oA eA7loBees ; 3Ce2e coAAission_7ct is null < and 2o3nuA 5 1; COMM'(('ON_PCT 11111111111111 #
4sing D)'OD),

!R?@E. select " decode(coAAission_7ct,null, #, % coAAission_7ct$ coAAission_7ct & >2oA eA7loBees 9 3Ce2e coAAission_7ct is null : and 2o3nuA 5 1; COMM'(('ON_PCT 11111111111111 #

I have al"ays used #$% to chec* !or null values. 5o"ever, it loo*s li*e 'O(%)S') is more generic (can chec* more than one e-pression !or null and also 'O(%)S') is a standard and "or*s !or all RDBMS6s. So should I brea* my habit o! using #$% and start using 'O(%)S')? 7hat say you?

Question: 7hen should I use the nvl !unction as opposed to the nvl& !unction. 7hat is the di!!erence bet"een nvl and nvl&?

Answer: 8he nvl !unction only has t"o parameters "hile the nvl parameter has three arguments. 8he nvl2 li*e li*e combining an nvl "ith a decode because you can trans!orm a value,

NVL ( expr1 , expr2 ): I! e-pr. is null, then #$% returns e-pr&. I! e-pr. is not null, then #$% returns e-pr.. NVL2 ( expr1 , expr2 , expr3 ): I! e-pr. is null, then #$%& returns e-pr/. I! e-pr. is not null, then #$%& returns e-pr&

(s "e see, the vanilla nvl trans!ormation ta*es a #4%% value and replaces it "ith a printable, useable value, such as a 9ero or spaces,
select n)l(b4bu>>e2_Dets,#$ E N L 2e7laces a NULL )alue 3itC a Fe2o select n)l(cu22ent_status, GNot disclosedH$ E N L 2e7laces a NULL )alue 3itC a st2inD

'onversely, the #$%& clause accepts three arguments, but (%7(:S trans!orms the input argument.
select N L"(su77lie2_citB, *CoA7leted*, *nIa*$ >2oA su77lie2s;

In this e-ample, these statements are e+uivalent because the nvl& re3sets the input argument bac* to the original value,
select n)l(coAAission_7ct,#$ " >2oA eA7loBees; select n)l"(coAAission_7ct,coAAission_7ct,#$ " >2oA eA7loBees;

DECODE:

S'nta(
The synta, for the decode )unction is< decode( expression , search , result [, search , result]... [, default] ) expression is the value to compare. search is the value that is compared against expression. result is the value returned/ if expression is e-ual to search. default is optional. 'f no matches are found/ the decode will return default. 'f default is omitted/ then the decode statement will return null =if no matches are found>.

u&*ose
compares expr to each search value one by one. 'f expr is e-ual to a search/ then "racle Database returns the corresponding result. 'f no match is found/ then "racle returns default. 'f default is omitted/ then "racle returns null.
DECODE

The arguments can be any of the numeric types =NUMBER/ B'NAR0_,LOAT/ or B'NAR0_DOUBLE> or character types.

'f expr and search are character data/ then "racle compares them using nonpadded comparison semantics. expr/ search/ and result can be any of the datatypes C!AR/ ARC!AR"/ NC!AR/ or N ARC!AR". The string returned is of ARC!AR" datatype and is in the same character set as the first resultparameter. 'f the first search-result pair are numeric/ then "racle compares all searchresult e,pressions and the first expr to determine the argument with the highest numeric precedence/ implicitly converts the remaining arguments to that datatype/ and returns that datatype.

The search/ result/ and default values can be derived from e,pressions. "racle Database uses s+o&t-ci&cuit e,aluation. That is/ the database evaluates each search value only before comparing it to expr/ rather than evaluating all search values before comparing any of them with expr. !onse-uently/ "racle never evaluates a search if a previous search is e-ual to expr. "racle automatically converts expr and each search value to the datatype of the first search value before comparing. "racle automatically converts the return value to the same datatype as the first result. 'f the first result has the datatype C!AR or if the first result is null/ then "racle converts the return value to the datatype ARC!AR". 'n a DECODE function/ "racle considers two nulls to be e-uivalent. 'f "racle returns the result of the first search that is also null. The ma,imum number of components in the DECODE function/ including expr/ searches/ results/ and default/ is #??.
select decode ( 2eDion, JNK,KNo2tCK, J(K,K(outCK, JEK,KEastK, J+K,K+estK,
expr

is null/ then

JUNLNO+NK $ >2oA custoAe2;

O&acle- LS.L/ NULLIF Function

'n "racle@*L%AL/ the NULLIF )unction compares expr1 and expr2. 'f expr1 and expr2 are e-ual/ the NULLIF )unction returns N&LL. "therwise/ it returns expr1.

S'nta(
The synta, for the NULLIF )unction is< NULLIF( expr1, expr2 ) expr1 and expr2 must be either numeric values or values that are of the same datatype.

Note
expr1 can be an e,pression that evaluates to N&LL/ but it can not be the literal N&LL.

A**lies 0o
"racle 55g/ "racle 5;g/ "racle 8i

u&*ose

compares expr1 and expr2. 'f they are e-ual/ then the function returns null. 'f they are not e-ual/ then the function returns expr1. (ou cannot specify the literal NULL for expr1. 'f both arguments are numeric datatypes/ then "racle Database determines the argument with the higher numeric precedence/ implicitly converts the other argument to that datatype/ and returns that datatype. 'f the arguments are not numeric/ then they must be of the same datatype/ or "racle returns an error.
NULL',

The NULL', function is logically e-uivalent to the following

CA(E +!EN eM721 5 eM72 " T!EN NULL EL(E eM721 END

CA(E

e,pression<

Fo& E(a1*le
NULLIF(12, 12) NULLIF(12, 13) NULLIF( apples , apples ) NULLIF( apples , oran!es ) NULLIF(NULL, 12) would return N&LL would return 5# would return N&LL would return 0apples0 would return an ".$9;;87# error because expr1 can not be the literal N&LL