Categorias:: Funções de dados semiestruturados e estruturados (criação e manipulação de matrizes/objetos)

ARRAYS_ZIP¶

Retorna uma matriz de objetos, cada uma das quais contém pares chave-valor para um enésimo elemento nas matrizes de entrada. Por exemplo, na matriz retornada, o primeiro objeto contém pares chave-valor para cada primeiro elemento nas matrizes de entrada, o segundo objeto contém pares chave-valor para cada segundo elemento nas matrizes de entrada e assim por diante.

Sintaxe¶

ARRAYS_ZIP( <array> [ , <array> ... ] )

Copy

Argumentos¶

array

Uma matriz de entrada.

As matrizes de entrada podem ter comprimentos diferentes.

Se qualquer uma das matrizes de entrada for uma matriz estruturada, todas as matrizes de entrada deverão ser matrizes estruturadas.

Retornos¶

Retorna um valor de um dos seguintes tipos:

Se as matrizes de entrada forem matrizes semiestruturadas, a função retornará uma matriz semiestruturada de objetos estruturados.
Se as matrizes de entrada forem matrizes estruturadas, a função retornará uma matriz estruturada de objetos estruturados. A definição do objeto estruturado depende do número de matrizes de entrada e dos tipos de valores nas matrizes.
Se qualquer uma das matrizes de entrada for NULL, a função retornará NULL.

Cada objeto contém os pares chave-valor para os valores de um enésimo elemento nas matrizes de entrada. A chave ($1, $2, e assim por diante) representa a posição da matriz de entrada.

Por exemplo, suponha que você passe estas matrizes:

SELECT ARRAYS_ZIP(
  [1, 2, 3],
  ['first', 'second', 'third'],
  ['i', 'ii', 'iii']
) AS zipped_arrays;

Copy

A função retornará a seguinte matriz de objetos:

+---------------------+
| ZIPPED_ARRAYS       |
|---------------------|
| [                   |
|   {                 |
|     "$1": 1,        |
|     "$2": "first",  |
|     "$3": "i"       |
|   },                |
|   {                 |
|     "$1": 2,        |
|     "$2": "second", |
|     "$3": "ii"      |
|   },                |
|   {                 |
|     "$1": 3,        |
|     "$2": "third",  |
|     "$3": "iii"     |
|   }                 |
| ]                   |
+---------------------+

Na matriz retornada:

O primeiro objeto contém os primeiros elementos de todas as matrizes de entrada.
O segundo objeto contém os segundos elementos de todas as matrizes de entrada.
O terceiro objeto contém os terceiros elementos de todas as matrizes de entrada.

As chaves nos objetos identificam a matriz de entrada:

Os pares chave-valor $1 contêm os valores da primeira matriz de entrada.
Os pares chave-valor $2 contêm os valores da segunda matriz de entrada.
Os pares chave-valor $3 contêm os valores da terceira matriz de entrada.

Notas de uso¶

A matriz retornada é tão longa quanto a matriz de entrada mais longa. Se algumas matrizes de entrada forem menores, a função usará um nulo JSON para os elementos restantes ausentes nas matrizes menores.
Se a matriz de entrada incluir um elemento NULL, a função retornará um nulo JSON para esse elemento.

Exemplos¶

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

Matriz de entrada única
Múltiplas matrizes de entrada
Matrizes de entrada de diferentes comprimentos
NULL e manipulação de matriz vazia

Matriz de entrada única¶

O exemplo a seguir retorna uma matriz de objetos com o primeiro, o segundo e o terceiro elementos em uma única matriz:

SELECT ARRAYS_ZIP(
  [1, 2, 3]
) AS zipped_array;

Copy

+--------------+
| ZIPPED_ARRAY |
|--------------|
| [            |
|   {          |
|     "$1": 1  |
|   },         |
|   {          |
|     "$1": 2  |
|   },         |
|   {          |
|     "$1": 3  |
|   }          |
| ]            |
+--------------+

Múltiplas matrizes de entrada¶

O exemplo a seguir retorna uma matriz de objetos com o primeiro, o segundo e o terceiro elementos nas matrizes de entrada:

SELECT ARRAYS_ZIP(
  [1, 2, 3],
  [10, 20, 30],
  [100, 200, 300]
) AS zipped_array;

Copy

+---------------+
| ZIPPED_ARRAY  |
|---------------|
| [             |
|   {           |
|     "$1": 1,  |
|     "$2": 10, |
|     "$3": 100 |
|   },          |
|   {           |
|     "$1": 2,  |
|     "$2": 20, |
|     "$3": 200 |
|   },          |
|   {           |
|     "$1": 3,  |
|     "$2": 30, |
|     "$3": 300 |
|   }           |
| ]             |
+---------------+

Matrizes de entrada de diferentes comprimentos¶

O exemplo a seguir passa matrizes de entrada de diferentes comprimentos. Para os valores ausentes nas matrizes mais curtas, a função usa um nulo JSON no objeto.

SELECT ARRAYS_ZIP(
  [1, 2, 3],
  ['one'],
  ['I', 'II']
) AS zipped_array;

Copy

+------------------+
| ZIPPED_ARRAY     |
|------------------|
| [                |
|   {              |
|     "$1": 1,     |
|     "$2": "one", |
|     "$3": "I"    |
|   },             |
|   {              |
|     "$1": 2,     |
|     "$2": null,  |
|     "$3": "II"   |
|   },             |
|   {              |
|     "$1": 3,     |
|     "$2": null,  |
|     "$3": null   |
|   }              |
| ]                |
+------------------+

NULL e manipulação de matriz vazia¶

Conforme mostrado no exemplo a seguir, passar um NULL para qualquer matriz de entrada faz com que a função retorne um NULL SQL:

SELECT ARRAYS_ZIP(
  [1, 2, 3],
  NULL,
  [100, 200, 300]
) AS zipped_array;

Copy

+--------------+
| ZIPPED_ARRAY |
|--------------|
| NULL         |
+--------------+

No exemplo a seguir, todas as matrizes de entrada estão vazias, o que faz com que a função retorne um objeto vazio:

SELECT ARRAYS_ZIP(
  [], [], []
) AS zipped_array;

Copy

+--------------+
| ZIPPED_ARRAY |
|--------------|
| [            |
|   {}         |
| ]            |
+--------------+

No exemplo a seguir, alguns dos elementos nas matrizes de entrada são NULL. Nos objetos retornados, os valores para esses elementos são nulos JSON:

SELECT ARRAYS_ZIP(
  [1, NULL, 3],
  [NULL, 20, NULL],
  [100, NULL, 300]
) AS zipped_array;

Copy

+-----------------+
| ZIPPED_ARRAY    |
|-----------------|
| [               |
|   {             |
|     "$1": 1,    |
|     "$2": null, |
|     "$3": 100   |
|   },            |
|   {             |
|     "$1": null, |
|     "$2": 20,   |
|     "$3": null  |
|   },            |
|   {             |
|     "$1": 3,    |
|     "$2": null, |
|     "$3": 300   |
|   }             |
| ]               |
+-----------------+