Categorias:

Funções de dados semiestruturados e estruturados (Matriz/objeto)

ARRAY_EXCEPT

Retorna um novo ARRAY que contém os elementos de um ARRAY de entrada que não estão em outro ARRAY de entrada.

A função é NULL-safe, ou seja, trata NULLs como valores conhecidos para comparar a igualdade.

Consulte também:

ARRAY_INTERSECTION

Sintaxe

ARRAY_EXCEPT( <source_array> , <array_of_elements_to_exclude> )
Copy

Argumentos

source_array

Uma matriz que contém elementos a serem incluídos no novo ARRAY.

array_of_elements_to_exclude

Uma matriz que contém elementos a serem excluídos do novo ARRAY.

Retornos

Esta função retorna um ARRAY que contém os elementos de source_array que não estão em array_of_elements_to_exclude.

Se nenhum elemento permanecer após excluir os elementos em array_of_elements_to_exclude de source_array, a função retorna um ARRAY vazio.

Se um ou ambos os argumentos forem NULL, a função retorna NULL.

A ordem dos valores dentro da matriz retornada não está especificada.

Notas de uso

  • Quando você compara dados do tipo OBJECT, os objetos devem ser idênticos para serem considerados compatíveis. Para obter mais detalhes, consulte Exemplos (neste tópico).

  • No Snowflake, as matrizes são conjuntos múltiplos, não conjuntos. Em outras palavras, as matrizes podem conter várias cópias do mesmo valor.

    ARRAY_EXCEPT compara matrizes usando semântica de múltiplos conjuntos (às vezes chamados de “semântica de saco”). Se source_array incluir várias cópias de um valor, a função remove apenas o número de cópias desse valor que estão especificadas em array_of_elements_to_exclude.

    Em outras palavras, se source_array tiver N cópias de um valor e array_of_elements_to_exclude tiver M cópias do mesmo valor, a função exclui M cópias do valor da matriz retornada. O número de cópias do valor na matriz retornada é N - M ou, se M for maior que N, 0.

    Por exemplo, se source_array contiver 5 elementos com o valor 'A' e array_of_elements_to_exclude contiver 2 elementos com o valor 'A', a matriz retornada terá 3 elementos com o valor 'A'.

  • Se você estiver passando uma ARRAY estruturada:

    • A ARRAY no segundo argumento deve ser comparável à ARRAY no primeiro argumento.

    • A função retorna uma ARRAY estruturada do mesmo tipo que ARRAY no primeiro argumento.

Exemplos

Os exemplos nesta seção usam constantes ARRAY e constantes OBJECT para especificar ARRAYs e OBJECTs.

Os exemplos a seguir demonstram como utilizar a função:

SELECT ARRAY_EXCEPT(['A', 'B'], ['B', 'C']);

+--------------------------------------+
| ARRAY_EXCEPT(['A', 'B'], ['B', 'C']) |
|--------------------------------------|
| [                                    |
|   "A"                                |
| ]                                    |
+--------------------------------------+
Copy

O exemplo seguinte adiciona o elemento 'C' a source_array. A ARRAY retornada exclui 'C' porque 'C' também é especificado em array_of_elements_to_exclude.

SELECT ARRAY_EXCEPT(['A', 'B', 'C'], ['B', 'C']);

+-------------------------------------------+
| ARRAY_EXCEPT(['A', 'B', 'C'], ['B', 'C']) |
|-------------------------------------------|
| [                                         |
|   "A"                                     |
| ]                                         |
+-------------------------------------------+
Copy

No exemplo a seguir, source_array contém 3 elementos com o valor 'B'. Como array_of_elements_to_exclude contém apenas 1 elemento 'B', a função excluirá apenas 1 elemento 'B' e retorna um ARRAY contendo os outros 2 elementos 'B'.

SELECT ARRAY_EXCEPT(['A', 'B', 'B', 'B', 'C'], ['B']);

+------------------------------------------------+
| ARRAY_EXCEPT(['A', 'B', 'B', 'B', 'C'], ['B']) |
|------------------------------------------------|
| [                                              |
|   "A",                                         |
|   "B",                                         |
|   "B",                                         |
|   "C"                                          |
| ]                                              |
+------------------------------------------------+
Copy

No exemplo a seguir, nenhum elemento permanece depois de excluir os elementos em array_of_elements_to_exclude de source_array. Como resultado, a função retorna um ARRAY vazio.

SELECT ARRAY_EXCEPT(['A', 'B'], ['A', 'B']);

+--------------------------------------+
| ARRAY_EXCEPT(['A', 'B'], ['A', 'B']) |
|--------------------------------------|
| []                                   |
+--------------------------------------+
Copy

O exemplo a seguir demonstra como a função trata elementos NULL como valores conhecidos. Como explicado anteriormente, como source_array contém um elemento NULL a mais do que array_of_elements_to_exclude, o ARRAY retornado exclui apenas um elemento NULL e inclui o outro (que é impresso como undefined).

SELECT ARRAY_EXCEPT(['A', NULL, NULL], ['B', NULL]);

+----------------------------------------------+
| ARRAY_EXCEPT(['A', NULL, NULL], ['B', NULL]) |
|----------------------------------------------|
| [                                            |
|   "A",                                       |
|   undefined                                  |
| ]                                            |
+----------------------------------------------+
Copy

No exemplo a seguir, source_array e array_of_elements_to_exclude contêm o mesmo número de elementos NULL, portanto o ARRAY retornado exclui os elementos NULL.

SELECT ARRAY_EXCEPT(['A', NULL, NULL], [NULL, 'B', NULL]);

+----------------------------------------------------+
| ARRAY_EXCEPT(['A', NULL, NULL], [NULL, 'B', NULL]) |
|----------------------------------------------------|
| [                                                  |
|   "A"                                              |
| ]                                                  |
+----------------------------------------------------+
Copy

O exemplo a seguir demonstra como especificar o mesmo objeto em source_array e array_of_elements_to_exclude exclui esse objeto do ARRAY retornado:

SELECT ARRAY_EXCEPT([{'a': 1, 'b': 2}, 1], [{'a': 1, 'b': 2}, 3]);

+------------------------------------------------------------+
| ARRAY_EXCEPT([{'A': 1, 'B': 2}, 1], [{'A': 1, 'B': 2}, 3]) |
|------------------------------------------------------------|
| [                                                          |
|   1                                                        |
| ]                                                          |
+------------------------------------------------------------+
Copy

O exemplo a seguir demonstra que a passagem em NULL resulta no retorno da função NULL.

SELECT ARRAY_EXCEPT(['A', 'B'], NULL);

+--------------------------------+
| ARRAY_EXCEPT(['A', 'B'], NULL) |
|--------------------------------|
| NULL                           |
+--------------------------------+
Copy