> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MySQL IN

> Como o operador IN do MySQL testa uma coluna contra uma lista de valores, em que o NOT IN difere e por que um NULL em qualquer lugar da lista faz o NOT IN não retornar nada.

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

`IN` testa uma coluna contra vários valores de uma vez. Ele diz o que uma cadeia de
`OR` diz, em uma cláusula, e é a cláusula que a maioria das pessoas usa quando um
filtro passa de 2 valores.

Abra o cliente com `mysql -u root -p sakila` antes de começar.

## Como o IN funciona

```sql theme={null}
SELECT COLUMN_LIST
FROM TABLE_NAME
WHERE COLUMN_NAME IN (FIRST_VALUE, SECOND_VALUE);
```

Substitua `COLUMN_NAME` pela coluna a testar, e `FIRST_VALUE` e
`SECOND_VALUE` pelos valores a aceitar.

A condição é verdadeira quando a coluna é igual a qualquer valor entre os parênteses. Separe
os valores com vírgulas, e use quantos precisar.

`x IN (a, b)` significa o mesmo que `x = a OR x = b`. Escreva o que ficar mais legível,
e espere que `IN` fique mais legível com mais de 2 valores.

## Exemplos

### Corresponder a qualquer um de vários valores

```sql theme={null}
SELECT title, rating
FROM film
WHERE rating IN ('G', 'PG')
ORDER BY title
LIMIT 5;
```

```text theme={null}
+------------------+--------+
| title            | rating |
+------------------+--------+
| ACADEMY DINOSAUR | PG     |
| ACE GOLDFINGER   | G      |
| AFFAIR PREJUDICE | G      |
| AFRICAN EGG      | G      |
| AGENT TRUMAN     | PG     |
+------------------+--------+
5 rows in set (0.00 sec)
```

### Não corresponder a nenhum deles

```sql theme={null}
SELECT title, rating
FROM film
WHERE rating NOT IN ('G', 'PG')
ORDER BY title
LIMIT 5;
```

```text theme={null}
+------------------+--------+
| title            | rating |
+------------------+--------+
| ADAPTATION HOLES | NC-17  |
| AIRPLANE SIERRA  | PG-13  |
| AIRPORT POLLOCK  | R      |
| ALABAMA DEVIL    | PG-13  |
| ALADDIN CALENDAR | NC-17  |
+------------------+--------+
5 rows in set (0.00 sec)
```

### Uma lista de números

```sql theme={null}
SELECT first_name, last_name
FROM actor
WHERE actor_id IN (1, 5, 10)
ORDER BY actor_id;
```

```text theme={null}
+------------+--------------+
| first_name | last_name    |
+------------+--------------+
| PENELOPE   | GUINESS      |
| JOHNNY     | LOLLOBRIGIDA |
| CHRISTIAN  | GABLE        |
+------------+--------------+
3 rows in set (0.00 sec)
```

Números não levam aspas. As linhas voltam na ordem de `actor_id` porque o
`ORDER BY` pediu isso, não porque a lista está nessa ordem.

### Uma lista que o servidor calcula sozinho

Os parênteses podem conter uma consulta em vez de uma lista. `film_actor` é a tabela que
emparelha cada filme com cada ator que aparece nele, então isto pede os filmes em que o ator 1
aparece, sem que você saiba nenhum id de filme.

```sql theme={null}
SELECT title
FROM film
WHERE film_id IN (SELECT film_id FROM film_actor WHERE actor_id = 1)
ORDER BY title
LIMIT 5;
```

```text theme={null}
+-----------------------+
| title                 |
+-----------------------+
| ACADEMY DINOSAUR      |
| ANACONDA CONFESSIONS  |
| ANGELS LIFE           |
| BULWORTH COMMANDMENTS |
| CHEAPER CLYDE         |
+-----------------------+
5 rows in set (0.00 sec)
```

Uma consulta escrita dentro de outra consulta é uma subconsulta. Uma seção posterior as cobre
de forma completa. Vale a pena conhecer uma aqui porque uma lista `IN` é onde a maioria das pessoas
escreve a primeira.

## Um NULL na lista quebra o NOT IN

`IN` e `NOT IN` não tratam um NULL na lista do mesmo jeito, e nenhum dos dois
avisa você.

Com `IN`, um NULL na lista é inofensivo. Uma linha que corresponde a um valor real é
mantida mesmo assim.

```sql theme={null}
SELECT title, rating
FROM film
WHERE rating IN ('G', NULL)
ORDER BY title
LIMIT 3;
```

```text theme={null}
+------------------+--------+
| title            | rating |
+------------------+--------+
| ACE GOLDFINGER   | G      |
| AFFAIR PREJUDICE | G      |
| AFRICAN EGG      | G      |
+------------------+--------+
3 rows in set (0.00 sec)
```

Com `NOT IN`, a mesma lista não retorna nada.

```sql theme={null}
SELECT title, rating
FROM film
WHERE rating NOT IN ('G', NULL)
ORDER BY title
LIMIT 3;
```

```text theme={null}
Empty set (0.01 sec)
```

Todo filme tem uma classificação, e 822 deles não são classificados como `G`, então um resultado vazio
é uma surpresa. A razão é que `NOT IN` pergunta se a coluna difere de
cada valor da lista, e nada pode ser mostrado como diferente de NULL.
Comparar qualquer coisa com NULL dá NULL em vez de verdadeiro ou falso, então a
condição inteira nunca é verdadeira e nenhuma linha sobrevive.

Isso importa mais quando a lista é uma subconsulta, porque uma subconsulta que você não
escreveu à mão pode retornar um NULL que você não esperava. Adicione
`WHERE COLUMN_NAME IS NOT NULL` dentro da subconsulta quando isso for possível. A
lição sobre [IS NULL](https://villagesql.com/docs/pt-BR/tutorial/is-null.md) cobre como NULL se compara.

## Resumo

* Use `IN` para testar uma coluna contra uma lista de valores em uma cláusula.
* Leia `x IN (a, b)` como `x = a OR x = b`.
* Coloque strings da lista entre aspas e deixe os números sem aspas.
* Coloque uma subconsulta entre os parênteses quando a lista for ela mesma uma resposta.
* Mantenha NULL fora de uma lista `NOT IN`, porque ela não retorna nenhuma linha.

## Veja também

* [AND, OR e NOT](https://villagesql.com/docs/pt-BR/tutorial/and-or-not.md) — a cadeia de OR que o IN substitui
* [IS NULL](https://villagesql.com/docs/pt-BR/tutorial/is-null.md) — por que comparar com NULL não é verdadeiro nem falso
* [BETWEEN](https://villagesql.com/docs/pt-BR/tutorial/between.md) — testando um intervalo em vez de uma lista
* [Subconsultas](https://villagesql.com/docs/pt-BR/tutorial/subqueries.md) — a forma de consulta usada no exemplo 4


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.