- 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:
Sintaxe¶
ARRAY_EXCEPT( <source_array> , <array_of_elements_to_exclude> )
Argumentos¶
source_arrayUma matriz que contém elementos a serem incluídos no novo ARRAY.
array_of_elements_to_excludeUma 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_EXCEPTcompara matrizes usando semântica de múltiplos conjuntos (às vezes chamados de “semântica de saco”). Sesource_arrayincluir várias cópias de um valor, a função remove apenas o número de cópias desse valor que estão especificadas emarray_of_elements_to_exclude.Em outras palavras, se
source_arraytiver N cópias de um valor earray_of_elements_to_excludetiver 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_arraycontiver 5 elementos com o valor'A'earray_of_elements_to_excludecontiver 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" |
| ] |
+--------------------------------------+
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" |
| ] |
+-------------------------------------------+
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" |
| ] |
+------------------------------------------------+
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']) |
|--------------------------------------|
| [] |
+--------------------------------------+
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 |
| ] |
+----------------------------------------------+
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" |
| ] |
+----------------------------------------------------+
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 |
| ] |
+------------------------------------------------------------+
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 |
+--------------------------------+