Categorias:

Funções de expressão condicional

[ NOT ] IN

Testa se seu argumento é ou não um dos membros de uma lista explícita ou o resultado de uma subconsulta.

Nota

Na forma de subconsulta, IN é equivalente a = ANY e NOT IN é equivalente a <> ALL.

Dica

Você pode usar o serviço de otimização de pesquisa para melhorar o desempenho de consultas que chamam essa função. Para obter mais detalhes, consulte Serviço de otimização de pesquisa.

Sintaxe

Para comparar valores individuais:

<value> [ NOT ] IN ( <value_1> [ , <value_2> ...  ] )
Copy

Para comparar construtores ROW (listas de valores entre parênteses):

( <value_A> [, <value_B> ... ] ) [ NOT ] IN (  ( <value_1> [ , <value_2> ... ] )  [ , ( <value_3> [ , <value_4> ... ] )  ...  ]  )
Copy

Para comparar um valor com os valores retornados por uma subconsulta:

<value> [ NOT ] IN ( <subquery> )
Copy

Parâmetros

value

O valor a ser pesquisado.

value_A, value_B

Os elementos de um construtor ROW pelos quais procurar.

Certifique-se de que cada valor à direita de IN (por exemplo, (value3, value4)) tenha o mesmo número de elementos que o valor à esquerda de IN (por exemplo, (value_A, value_B)).

value_#

Um valor com o qual value deve ser comparado.

Se os valores a serem comparados são construtores ROW, então cada value_# é um elemento individual de um construtor ROW.

subquery

Uma subconsulta que retorna uma lista de valores aos quais value pode ser comparado.

Notas de uso

  • Como na maioria dos contextos, NULL não é igual a NULL. Se value for NULL, então o valor de retorno da função é NULL, quer a lista ou subconsulta contenha ou não NULL.

    Por exemplo, o seguinte retorna NULL, e não TRUE:

    SELECT NULL IN (1, 2, NULL) AS RESULT;
    
    Copy
  • Sintaticamente, IN é tratado como um operador e não como uma função. Este exemplo mostra a diferença entre usar IN como um operador e chamar f() como uma função:

    SELECT
        f(a, b),
        x IN (y, z) ...
    
    Copy

    Você não pode usar a sintaxe de função com IN. Por exemplo, você não pode reescrever o exemplo anterior como:

    SELECT
        f(a, b),
        IN(x, (y, z)) ...
    
    Copy
  • IN também é considerado um operador de subconsulta.

  • Em uma consulta que usa IN, você pode expandir uma matriz em uma lista de valores individuais usando o operador de propagação (**). Para obter mais informações e exemplos, consulte Operadores de expansão.

Detalhes do agrupamento

Arguments with collation specifications currently aren’t supported.

Exemplos

Os exemplos a seguir usam a função IN.

Uso de IN com literais simples

Os exemplos seguintes mostram como usar IN e NOT IN com literais simples:

SELECT 1 IN (1, 2, 3) AS RESULT;
Copy
+--------+
| RESULT |
|--------|
| True   |
+--------+
SELECT 4 NOT IN (1, 2, 3) AS RESULT;
Copy
+--------+
| RESULT |
|--------|
| True   |
+--------+

Uso de IN com uma subconsulta

Este exemplo mostra como usar IN em uma subconsulta.

SELECT 'a' IN (
  SELECT column1 FROM VALUES ('b'), ('c'), ('d')
  ) AS RESULT;
Copy
+--------+
| RESULT |
|--------|
| False  |
+--------+

Uso de IN com uma tabela

Estes exemplos mostram como usar IN com uma tabela. A instrução abaixo cria a tabela usada nos exemplos.

CREATE OR REPLACE TABLE in_function_demo (
  col_1 INTEGER,
  col_2 INTEGER,
  col_3 INTEGER);

INSERT INTO in_function_demo (col_1, col_2, col_3) VALUES
  (1, 1, 1),
  (1, 2, 3),
  (4, 5, NULL);
Copy

Este exemplo mostra como usar IN com uma única coluna de uma tabela:

SELECT col_1, col_2, col_3
  FROM in_function_demo
  WHERE (col_1) IN (1, 10, 100, 1000)
  ORDER BY col_1, col_2, col_3;
Copy
+-------+-------+-------+
| COL_1 | COL_2 | COL_3 |
|-------+-------+-------|
|     1 |     1 |     1 |
|     1 |     2 |     3 |
+-------+-------+-------+

Este exemplo mostra como usar IN com várias colunas de uma tabela:

SELECT col_1, col_2, col_3
  FROM in_function_demo
  WHERE (col_1, col_2, col_3) IN (
    (1,2,3),
    (4,5,6));
Copy
+-------+-------+-------+
| COL_1 | COL_2 | COL_3 |
|-------+-------+-------|
|     1 |     2 |     3 |
+-------+-------+-------+

Este exemplo mostra como usar IN com uma subconsulta que lê várias colunas de uma tabela:

SELECT (1, 2, 3) IN (
  SELECT col_1, col_2, col_3 FROM in_function_demo
  ) AS RESULT;
Copy
+--------+
| RESULT |
|--------|
| True   |
+--------+

Uso de NULL

Lembre-se de que NULL != NULL. Nenhuma das consultas seguintes retorna uma correspondência quando o valor à esquerda ou à direita de IN contém um NULL:

SELECT NULL IN (1, 2, NULL) AS RESULT;
Copy
+--------+
| RESULT |
|--------|
| NULL   |
+--------+
SELECT (4, 5, NULL) IN ( (4, 5, NULL), (7, 8, 9) ) AS RESULT;
Copy
+--------+
| RESULT |
|--------|
| NULL   |
+--------+