NULLIF (Transact-SQL)

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Azure Synapse Analytics PDW (Analytics Platform System) Ponto de extremidade de análise do SQL Warehouse no Microsoft Fabric

Retorna um valor nulo se as duas expressões especificadas forem iguais. Por exemplo, SELECT NULLIF(4,4) AS Same, NULLIF(5,7) AS Different; retorna NULL para a primeira coluna (4 e 4), pois os dois valores de entrada são os mesmos. A segunda coluna retorna o primeiro valor (5), porque os dois valores de entrada são diferentes.

Convenções de sintaxe de Transact-SQL

Sintaxe

NULLIF ( expression , expression )  

Argumentos

expressão
É qualquer expression escalar válida.

Tipos de retorno

Retorna o mesmo tipo que a primeira expression.

NULLIF retorna a primeira expression se as duas expressões não são iguais. Se as expressões forem iguais, NULLIF retornará um valor nulo do tipo da primeira expression.

Comentários

NULLIF é equivalente a uma expressão CASE pesquisada em que as duas expressões são iguais e a expressão resultante é NULL.

É recomendável não usar funções dependentes de tempo, como RAND(), dentro de uma função NULLIF. Isto pode fazer com que a função seja avaliada duas vezes e retorne resultados diferentes nas duas invocações.

Exemplos

a. Retornando valores de orçamento que não foram alterados

O exemplo a seguir cria uma tabela budgets para mostrar a um departamento (dept) seu orçamento atual (current_year) e seu orçamento anterior (previous_year). Para o ano atual, NULL é usado para departamentos com orçamentos que não foram alterados em relação ao ano anterior, e 0 é usado para orçamentos que ainda não foram determinados. Para descobrir a média somente dos departamentos que receberam um orçamento e para incluir o valor do orçamento do ano anterior (use o valor previous_year, em que o current_year é NULL), combine as funções NULLIF e COALESCE.

CREATE TABLE dbo.budgets  
(  
   dept            TINYINT   IDENTITY,  
   current_year    DECIMAL   NULL,  
   previous_year   DECIMAL   NULL  
);  
INSERT budgets VALUES(100000, 150000);  
INSERT budgets VALUES(NULL, 300000);  
INSERT budgets VALUES(0, 100000);  
INSERT budgets VALUES(NULL, 150000);  
INSERT budgets VALUES(300000, 250000);  
GO    
SET NOCOUNT OFF;  
SELECT AVG(NULLIF(COALESCE(current_year,  
   previous_year), 0.00)) AS [Average Budget]  
FROM budgets;  
GO  

Veja a seguir o conjunto de resultados.

Average Budget  
--------------  
212500.000000  
(1 row(s) affected)

B. Comparando NULLIF e CASE

Para mostrar a semelhança entre NULLIF e CASE, as consultas a seguir avaliam se os valores das colunas MakeFlag e FinishedGoodsFlag são os mesmos. A primeira consulta usa NULLIF. A segunda consulta usa a expressão CASE.

USE AdventureWorks2022;  
GO  
SELECT ProductID, MakeFlag, FinishedGoodsFlag,   
   NULLIF(MakeFlag,FinishedGoodsFlag) AS [Null if Equal]  
FROM Production.Product  
WHERE ProductID < 10;  
GO  
  
SELECT ProductID, MakeFlag, FinishedGoodsFlag, [Null if Equal] =  
   CASE  
       WHEN MakeFlag = FinishedGoodsFlag THEN NULL  
       ELSE MakeFlag  
   END  
FROM Production.Product  
WHERE ProductID < 10;  
GO  

C: Retornando valores de orçamento que não contêm dados

O exemplo a seguir cria uma tabela budgets, carrega dados e usa o NULLIF para retornar um valor nulo se current_year for nulo ou contiver os mesmos dados que previous_year.

Copy
CREATE TABLE budgets (  
   dept           TINYINT,  
   current_year   DECIMAL(10,2),  
   previous_year  DECIMAL(10,2)  
);  
  
INSERT INTO budgets VALUES(1, 100000, 150000);  
INSERT INTO budgets VALUES(2, NULL, 300000);  
INSERT INTO budgets VALUES(3, 0, 100000);  
INSERT INTO budgets VALUES(4, NULL, 150000);  
INSERT INTO budgets VALUES(5, 300000, 300000);  
  
SELECT dept, NULLIF(current_year,  
   previous_year) AS LastBudget  
FROM budgets;  

Veja a seguir o conjunto de resultados.

dept   LastBudget  
----   -----------  
1      100000.00  
2      null 
3      0.00  
4      null  
5      null

Confira também

CASE (Transact-SQL)
decimal e numeric (Transact-SQL)
Funções de sistema (Transact-SQL)