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'.

Ambos os argumentos devem ser ARRAYs estruturadas ou ARRAYs semiestruturadas.
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