Tipos de dados estruturados

Um tipo estruturado é uma ARRAY, OBJECT ou MAP que contém elementos ou pares chave-valor com tipos de dados Snowflake específicos. A seguir estão exemplos de tipos estruturados:

  • Uma ARRAY de elementos INTEGER.

  • Um OBJECT com pares chave-valor VARCHAR e NUMBER.

  • Um MAP que associa uma chave VARCHAR a um valor DOUBLE.

Você pode usar tipos estruturados das seguintes maneiras:

  • Você pode definir uma coluna de tipo estruturado em uma tabela Iceberg.

    Os tipos de dados Iceberg list, struct e map correspondem aos tipos estruturados de ARRAY, OBJECT e MAP no Snowflake.

    Uma coluna de tipo estruturado suporta no máximo 1000 subcolunas.

  • Você usa tipos estruturados ao acessar dados de uma coluna de tipo estruturado em uma tabela Iceberg.

  • Você pode converter um ARRAY, OBJECT ou VARIANT semiestruturado em um tipo estruturado correspondente (por exemplo, uma ARRAY em uma ARRAY de elementos INTEGER). Você também pode converter um tipo estruturado de um tipo semiestruturado.

Nota

Atualmente, outras tabelas além das tabelas Iceberg não oferecem suporte a tipos estruturados. Você não pode adicionar uma coluna de tipo estruturado a uma tabela normal.

Este tópico explica como usar tipos estruturados no Snowflake.

Como especificar um tipo estruturado

Ao definir uma coluna de tipo estruturado ou converter um valor em um tipo estruturado, use a sintaxe descrita nas seções a seguir:

Como especificar uma ARRAY estruturada

Para especificar uma ARRAY estruturada, use a seguinte sintaxe:

ARRAY( <element_type> [ NOT NULL ] )
Copy

Onde:

  • element_type é o tipo de dados Snowflake dos elementos nesta ARRAY.

    Você também pode especificar uma ARRAY estruturada, um OBJECT estruturado ou um MAP como o tipo do elemento.

    Nota

    Na definição de uma coluna da tabela Iceberg, não é possível especificar uma VARIANT, ARRAY semiestruturada ou OBJECT semiestruturado como o tipo do elemento ARRAY.

  • NOT NULL especifica que ARRAY não pode conter nenhum elemento que seja NULL.

Por exemplo, compare os tipos retornados pela função SYSTEM$TYPEOF na instrução a seguir:

  • A expressão da primeira coluna converte uma ARRAY semiestruturada em uma ARRAY estruturada (uma ARRAY de elementos NUMBER).

  • A expressão da segunda coluna especifica uma ARRAY semiestruturada.

SELECT
  SYSTEM$TYPEOF(
    [1, 2, 3]::ARRAY(NUMBER)
  ) AS structured_array,
  SYSTEM$TYPEOF(
    [1, 2, 3]
  ) AS semi_structured_array;
Copy
+-------------------------------+-----------------------+
| STRUCTURED_ARRAY              | SEMI_STRUCTURED_ARRAY |
|-------------------------------+-----------------------|
| ARRAY(NUMBER(38,0))[LOB]      | ARRAY[LOB]            |
+-------------------------------+-----------------------+

Como especificar um OBJECT estruturado

Para especificar um OBJECT estruturado, use a seguinte sintaxe:

OBJECT(
  [
    <key> <value_type> [ NOT NULL ]
    [ , <key> <value_type> [ NOT NULL ] ]
    [ , ... ]
  ]
)
Copy

Onde:

  • key especifica uma chave para o OBJECT.

    • Cada key em uma definição de objeto deve ser único.

    • A ordem das chaves faz parte da definição do objeto. Não é permitido comparar dois OBJECTs que possuem as mesmas chaves em uma ordem diferente. (Ocorre um erro de tempo de compilação.)

    • Se você não especificar nenhuma chave, mas especificar os parênteses (ou seja, se usar OBJECT()), o tipo resultante será um OBJECT estruturado que não contém chaves. Um OBJECT estruturado sem chaves é diferente de um OBJECT semiestruturado.

  • value_type é o tipo de dados Snowflake do valor correspondente à chave.

    Você também pode especificar uma ARRAY estruturada, um OBJECT estruturado ou um MAP como o tipo de valor.

    Nota

    Na definição de uma coluna da tabela Iceberg, você não pode especificar VARIANT, ARRAY semiestruturada ou OBJECT semiestruturado como o tipo de valor correspondente à chave OBJECT.

  • NOT NULL especifica que o valor correspondente à chave não pode ser NULL.

Por exemplo, compare os tipos retornados pela função SYSTEM$TYPEOF na instrução a seguir:

  • A expressão da primeira coluna converte um OBJECT semiestruturado em um OBJECT estruturado que contém as seguintes chaves e valores:

    • Uma chave chamada str com um valor VARCHAR que não é NULL.

    • Uma chave chamada num com um valor NUMBER.

  • A expressão da segunda coluna especifica um OBJECT semiestruturado.

SELECT
  SYSTEM$TYPEOF(
    {
      'str': 'test',
      'num': 1
    }::OBJECT(
      str VARCHAR NOT NULL,
      num NUMBER
    )
  ) AS structured_object,
  SYSTEM$TYPEOF(
    {
      'str': 'test',
      'num': 1
    }
  ) AS semi_structured_object;
Copy
+----------------------------------------------------------------+------------------------+
| STRUCTURED_OBJECT                                              | SEMI_STRUCTURED_OBJECT |
|----------------------------------------------------------------+------------------------|
| OBJECT(str VARCHAR(16777216), num NUMBER(38,0) NOT NULL )[LOB] | OBJECT[LOB]            |
+----------------------------------------------------------------+------------------------+

Como especificar um MAP

Para especificar um MAP, use a seguinte sintaxe:

MAP( <key_type> , <value_type> [ NOT NULL ] )
Copy

Onde:

  • key_type é o tipo de dados Snowflake da chave do mapa. Você deve usar um dos seguintes tipos de chaves:

    • VARCHAR

    • NUMBER com a escala 0

    Você não pode usar um tipo de dados de ponto flutuante como tipo de chave.

    Observe que as chaves do mapa não podem ser NULL.

  • value_type é o tipo de dados Snowflake dos valores no mapa.

    Você também pode especificar uma ARRAY estruturada, um OBJECT estruturado ou um MAP como o tipo de valores.

    Nota

    Na definição de uma coluna da tabela Iceberg, não é possível especificar uma VARIANT, ARRAY semiestruturada ou OBJECT semiestruturado como o tipo de valor no MAP.

  • NOT NULL especifica que o valor correspondente à chave não pode ser NULL. NOT NULL especifica que o valor não pode ser NULL.

O exemplo a seguir converte um OBJECT semiestruturado em um MAP e usa a função SYSTEM$TYPEOF para imprimir o tipo resultante do objeto. O MAP associa chaves VARCHAR a valores VARCHAR.

SELECT
  SYSTEM$TYPEOF(
    {
      'a_key': 'a_val',
      'b_key': 'b_val'
    }::MAP(VARCHAR, VARCHAR)
  ) AS map_example;
Copy
+------------------------------------------------+
| MAP_EXAMPLE                                    |
|------------------------------------------------|
| map(VARCHAR(16777216), VARCHAR(16777216))[LOB] |
+------------------------------------------------+

Uso de tipos estruturados em tipos semiestruturados

Você não pode usar um MAP, um OBJECT estruturado ou uma ARRAY estruturada em um VARIANT, um OBJECT semiestruturado ou uma ARRAY semiestruturada. Um erro ocorre nas seguintes situações:

  • Você usa um MAP, um OBJECT estruturado ou uma ARRAY estruturada em uma constante de OBJECT ou de ARRAY.

  • Você passa um MAP, um OBJECT estruturado ou uma ARRAY estruturada para uma função construtora de um OBJECT ou uma ARRAY.

Conversão de tipos estruturados e semiestruturados

A tabela a seguir resume as regras para converter OBJECTs estruturados, ARRAYs estruturadas e MAPs em OBJECTs, ARRAYs e VARIANTs semiestruturados (e vice-versa).

Tipo de dados de origem

Tipo de dados de destino

Conversível

Coercível

ARRAY semiestruturada

ARRAY estruturada

OBJECT semiestruturado

  • OBJECT estruturado

  • MAP

VARIANT semiestruturada

  • ARRAY estruturada

  • OBJECT estruturado

  • MAP

ARRAY estruturada

ARRAY semiestruturada

  • OBJECT estruturado

  • MAP

OBJECT semiestruturado

  • ARRAY estruturada

  • OBJECT estruturado

  • MAP

VARIANT semiestruturada

As seções seguintes explicam essas regras com mais detalhes.

Conversão explícita de um tipo semiestruturado em um tipo estruturado

Para converter explicitamente um objeto semiestruturado em um tipo estruturado, você pode chamar a função CAST ou usar o operador ::.

Nota

TRY_CAST não é suportado para tipos estruturados.

Você só pode converter os seguintes objetos semiestruturados no tipo estruturado correspondente; caso contrário, ocorrerá um erro de tempo de execução.

Tipo semiestruturado

Tipo estruturado no qual você pode converter

ARRAY

ARRAY estruturada

OBJECT

MAP ou OBJECT estruturado

VARIANT

MAP ou ARRAY ou OBJECT estruturado

As próximas seções fornecem mais detalhes sobre como os tipos são convertidos:

Conversão de ARRAYs e VARIANTs semiestruturadas para ARRAYs estruturadas

As etapas a seguir demonstram como converter uma ARRAY ou VARIANT semiestruturada em uma ARRAY de elementos NUMBER:

SELECT
  SYSTEM$TYPEOF(
    CAST ([1,2,3] AS ARRAY(NUMBER))
  ) AS array_cast_type,
  SYSTEM$TYPEOF(
    CAST ([1,2,3]::VARIANT AS ARRAY(NUMBER))
  ) AS variant_cast_type;
Copy

Ou:

SELECT
  SYSTEM$TYPEOF(
    [1,2,3]::ARRAY(NUMBER)
  ) AS array_cast_type,
  SYSTEM$TYPEOF(
    [1,2,3]::VARIANT::ARRAY(NUMBER)
  ) AS variant_cast_type;
Copy
+--------------------------+--------------------------+
| ARRAY_CAST_TYPE          | VARIANT_CAST_TYPE        |
|--------------------------+--------------------------|
| ARRAY(NUMBER(38,0))[LOB] | ARRAY(NUMBER(38,0))[LOB] |
+--------------------------+--------------------------+

Ao converter uma ARRAY ou VARIANT semiestruturada em uma ARRAY estruturada, observe o seguinte:

  • Cada elemento da ARRAY é convertido no tipo especificado da ARRAY.

    Converter a coluna da ARRAY em ARRAY(VARCHAR) converte cada valor em VARCHAR:

    SELECT
      CAST ([1,2,3] AS ARRAY(VARCHAR)) AS varchar_array,
      SYSTEM$TYPEOF(varchar_array) AS array_cast_type;
    
    Copy
    +---------------+-------------------------------+
    | VARCHAR_ARRAY | ARRAY_CAST_TYPE               |
    |---------------+-------------------------------|
    | [             | ARRAY(VARCHAR(16777216))[LOB] |
    |   "1",        |                               |
    |   "2",        |                               |
    |   "3"         |                               |
    | ]             |                               |
    +---------------+-------------------------------+
    
  • Se o elemento não puder ser convertido no tipo especificado (por exemplo, conversão de ['a', 'b', 'c'] em ARRAY(NUMBER)), a conversão falhará.

  • Se a ARRAY contiver elementos NULL e o tipo da ARRAY especificar NOT NULL (por exemplo, conversão de [1, NULL, 3] em ARRAY(NUMBER NOT NULL), a conversão falhará.

  • Elementos que são valores JSON nulos são convertidos em NULL, se o tipo de elemento de destino não suportar JSON nulos (ou seja, o tipo de destino não é uma ARRAY, OBJECT ou VARIANT semiestruturado).

    Por exemplo, se você estiver convertendo em ARRAY(NUMBER), valores JSON nulos serão convertidos em NULL porque NUMBER não oferece suporte a JSON nulos.

    Por outro lado, se você estiver convertendo em ARRAY(VARIANT), valores JSON nulos não serão convertidos em NULL porque VARIANT oferece suporte a JSON nulos.

Conversão de OBJECTs e VARIANTs semiestruturados em OBJECTs estruturados

As etapas a seguir demonstram como converter um OBJECT ou VARIANT semiestruturado em um OBJECT estruturado contendo os pares chave-valor city e state (que são valores VARCHAR):

SELECT
  SYSTEM$TYPEOF(
    CAST ({'city':'San Mateo','state':'CA'} AS OBJECT(city VARCHAR, state VARCHAR))
  ) AS object_cast_type,
  SYSTEM$TYPEOF(
    CAST ({'city':'San Mateo','state':'CA'}::VARIANT AS OBJECT(city VARCHAR, state VARCHAR))
  ) AS variant_cast_type;
Copy

Ou:

SELECT
  SYSTEM$TYPEOF(
     {'city':'San Mateo','state':'CA'}::OBJECT(city VARCHAR, state VARCHAR)
  ) AS object_cast_type,
  SYSTEM$TYPEOF(
     {'city':'San Mateo','state':'CA'}::VARIANT::OBJECT(city VARCHAR, state VARCHAR)
  ) AS variant_cast_type;
Copy
+--------------------------------------------------------------+--------------------------------------------------------------+
| OBJECT_CAST_TYPE                                             | VARIANT_CAST_TYPE                                            |
|--------------------------------------------------------------+--------------------------------------------------------------|
| OBJECT(city VARCHAR(16777216), state VARCHAR(16777216))[LOB] | OBJECT(city VARCHAR(16777216), state VARCHAR(16777216))[LOB] |
+--------------------------------------------------------------+--------------------------------------------------------------+

Ao converter um OBJECT ou VARIANT semiestruturado em um OBJECT estruturado, observe o seguinte:

  • O OBJECT não deve conter chaves adicionais que não sejam especificadas no tipo OBJECT.

    Se houver chaves adicionais, a conversão falhará.

  • Se faltar em OBJECT uma chave especificada no tipo OBJECT, a conversão falhará.

  • O valor de cada chave em OBJECT é convertido no tipo especificado para essa chave.

    Se um valor não puder ser convertido para o tipo especificado, a conversão falhará.

  • Se o valor de uma chave for um valor JSON nulo, o valor será convertido em NULL, se o tipo de valor de destino não suportar JSON nulos (ou seja, o tipo de destino não ARRAY, OBJECT ou VARIANT semiestruturado).

    Por exemplo, se você estiver convertendo em OBJECT(cidade VARCHAR), os valores JSON nulos serão convertidos em NULL porque VARCHAR não oferece suporte a JSON nulos.

    Por outro lado, se você estiver convertendo em OBJECT(cidade VARIANT), os valores JSON nulos não serão convertidos em NULL porque VARIANT oferece suporte a JSON nulos.

Conversão de OBJECTs e VARIANTs semiestruturados em MAPs

As instruções a seguir demonstram como converter um OBJECT ou VARIANT semiestruturado em um MAP que associa uma chave VARCHAR a um valor VARCHAR:

SELECT
  SYSTEM$TYPEOF(
    CAST ({'my_key':'my_value'} AS MAP(VARCHAR, VARCHAR))
  ) AS map_cast_type,
  SYSTEM$TYPEOF(
    CAST ({'my_key':'my_value'} AS MAP(VARCHAR, VARCHAR))
  ) AS variant_cast_type;
Copy

Ou:

SELECT
  SYSTEM$TYPEOF(
    {'my_key':'my_value'}::MAP(VARCHAR, VARCHAR)
  ) AS map_cast_type,
  SYSTEM$TYPEOF(
    {'my_key':'my_value'}::VARIANT::MAP(VARCHAR, VARCHAR)
  ) AS variant_cast_type;
Copy
+------------------------------------------------+------------------------------------------------+
| MAP_CAST_TYPE                                  | VARIANT_CAST_TYPE                              |
|------------------------------------------------+------------------------------------------------|
| map(VARCHAR(16777216), VARCHAR(16777216))[LOB] | map(VARCHAR(16777216), VARCHAR(16777216))[LOB] |
+------------------------------------------------+------------------------------------------------+

Ao converter um OBJECT ou VARIANT semiestruturado em um MAP, observe o seguinte:

  • Se as chaves e os valores não corresponderem aos tipos especificados, as chaves e os valores serão convertidos nos tipos especificados.

  • Se as chaves e os valores não puderem ser convertidos nos tipos especificados, a conversão falhará.

  • Se o valor de uma chave for um valor JSON nulo, o valor será convertido em NULL, se o tipo de valor de destino não suportar JSON nulos (ou seja, o tipo de destino não ARRAY, OBJECT ou VARIANT semiestruturado).

    Por exemplo, se você estiver convertendo em MAP(VARCHAR, VARCHAR), valores JSON nulos serão convertidos em NULL porque VARCHAR não oferece suporte a JSON nulos.

    Por outro lado, se você estiver convertendo em MAP(VARCHAR, VARIANT), valores JSON nulos não serão convertidos em NULL porque VARIANT oferece suporte a JSON nulos.

Conversão explícita de um tipo estruturado em um tipo semiestruturado

Para converter explicitamente um tipo estruturado em um tipo semiestruturado, você pode chamar a função CAST, usar o operador :: ou chamar uma das funções de conversão (por exemplo, TO_ARRAY, TO_OBJECT ou TO_VARIANT).

Nota

TRY_CAST não é compatível com tipos estruturados.

Tipo estruturado

Tipo semiestruturado no qual você pode converter

ARRAY estruturada

ARRAY

MAP ou OBJECT estruturado

OBJECT

MAP, ARRAY estruturada ou OBJECT estruturado

VARIANT

Por exemplo:

  • Se col_structured_array for ARRAY(VARCHAR):

    • CAST(col_structured_array AS ARRAY) retorna uma ARRAY semiestruturada.

    • CAST(col_structured_array AS VARIANT) retorna uma VARIANT que contém uma ARRAY semiestruturada.

  • Se col_structured_object for OBJECT(nome VARCHAR, estado VARCHAR):

    • CAST(col_structured_object AS OBJECT) retorna um OBJECT semiestruturado.

    • CAST(col_structured_object AS VARIANT) retorna uma VARIANT que contém um OBJECT semiestruturado.

  • Se col_map for MAP(VARCHAR, VARCHAR):

    • CAST(col_map AS OBJECT) retorna um OBJECT semiestruturado.

    • CAST(col_map AS VARIANT) retorna uma VARIANT que contém um OBJECT semiestruturado.

Observe o seguinte:

  • Ao converter em um OBJECT semiestruturado, a ordem das chaves no OBJECT estruturado não é preservada.

  • Ao converter um OBJECT ou MAP estruturado em um OBJECT ou VARIANT semiestruturado, quaisquer valores NULL são convertidos em valores JSON nulos.

    Se você estiver convertendo uma ARRAY estruturada em uma VARIANT, os valores NULL serão preservados como estão.

    SELECT [1,2,NULL,3]::ARRAY(INTEGER)::VARIANT;
    
    Copy
    +---------------------------------------+
    | [1,2,NULL,3]::ARRAY(INTEGER)::VARIANT |
    |---------------------------------------|
    | [                                     |
    |   1,                                  |
    |   2,                                  |
    |   undefined,                          |
    |   3                                   |
    | ]                                     |
    +---------------------------------------+
    
  • Se você estiver convertendo um MAP que usa um tipo NUMBER para chaves, as chaves MAP serão convertidas em cadeias de caracteres no OBJECT retornado.

Conversão implícita de um valor (coerção)

As regras a seguir se aplicam à conversão implícita (coerção) de um tipo estruturado em outro tipo estruturado:

  • Um tipo estruturado pode ser forçado a outro tipo estruturado se os dois tipos básicos de objetos forem iguais:

    • Uma ARRAY de um tipo pode ser forçada para uma ARRAY de outro tipo, desde que o primeiro tipo de elemento seja coercível para o segundo tipo de elemento.

      Um tipo de elemento pode ser forçado a outro tipo de elemento em qualquer um dos seguintes casos:

      • Ambos os tipos são numéricos. Os seguintes casos são suportados:

        • Ambos usam o mesmo tipo numérico, mas possivelmente diferem em precisão e/ou escala.

        • Como forçar NUMBER a FLOAT (e vice-versa).

      • Ambos os tipos são carimbos de data/hora. Os seguintes casos são suportados:

        • Ambos usam o mesmo tipo, mas possivelmente diferem em precisão.

        • Como forçar TIMESTAMP_LTZ a TIMESTAMP_TZ (e vice-versa).

      Por exemplo:

      • Uma ARRAY(NUMBER) pode ser forçada a uma ARRAY(DOUBLE).

      • Uma ARRAY(DATE) não pode ser forçada a uma ARRAY(NUMBER).

    • Um OBJECT com uma definição de tipo pode ser forçado a um OBJECT com outra definição de tipo somente se todas as afirmações a seguir forem verdadeiras:

      • Ambos os tipos de OBJECT têm o mesmo número de chaves.

      • Ambos os tipos de OBJECT usam os mesmos nomes para chaves.

      • As chaves em ambos os tipos de OBJECT estão na mesma ordem.

      • O tipo de cada valor em um tipo de OBJECT pode ser forçado para o tipo do valor correspondente no outro tipo de OBJECT.

        Como é o caso dos tipos de elementos em ARRAYs estruturadas, você pode forçar o tipo de um valor para outro tipo somente se:

        • Ambos os tipos são numéricos. Os seguintes casos são suportados:

          • Ambos usam o mesmo tipo numérico, mas possivelmente diferem em precisão e/ou escala.

          • Como forçar NUMBER a FLOAT (e vice-versa).

        • Ambos os tipos são carimbos de data/hora. Os seguintes casos são suportados:

          • Ambos usam o mesmo tipo, mas possivelmente diferem em precisão.

          • Como forçar TIMESTAMP_LTZ a TIMESTAMP_TZ (e vice-versa).

      Por exemplo:

      • Um OBJECT(cidade VARCHAR, CEP NUMBER) puder ser forçado a um OBJECT(cidade VARCHAR, CEP DOUBLE).

      • Um OBJECT(cidade VARCHAR, CEP NUMBER) não puder ser forçado a um OBJECT(cidade VARCHAR, CEP DATE).

    • Um MAP com um tipo de valor pode ser forçado a um MAP com um tipo de valor diferente se:

      • Ambos os tipos de valor forem numéricos. Os seguintes casos são suportados:

        • Ambos usam o mesmo tipo numérico, mas possivelmente diferem em precisão e/ou escala.

        • Como forçar NUMBER a FLOAT (e vice-versa).

      • Ambos os tipos de valor forem carimbos de data/hora. Os seguintes casos são suportados:

        • Ambos usam o mesmo tipo, mas possivelmente diferem em precisão.

        • Como forçar TIMESTAMP_LTZ a TIMESTAMP_TZ (e vice-versa).

      Por exemplo, um MAP(VARCHAR, NUMBER) pode ser forçado a um MAP(VARCHAR, DOUBLE).

    • Um MAP com um tipo de chave pode ser forçado a um MAP com um tipo de chave diferente se ambos os tipos de chave usarem o mesmo tipo NUMERIC inteiro que difere apenas na precisão.

      Por exemplo, um MAP(VARCHAR, NUMBER) não pode ser forçado a um MAP(NUMBER, NUMBER).

  • Um tipo estruturado não pode ser forçado a um objeto semiestruturado (e vice-versa).

  • Um valor VARCHAR não pode ser forçado a um tipo estruturado.

Conversão de um tipo estruturado em outro

Você pode chamar a função CAST ou usar o operador :: para converter um tipo estruturado em outro. Você pode converter de e nos seguintes tipos estruturados:

Nota

TRY_CAST não é compatível com tipos estruturados.

Se não for possível converter os valores de um tipo em outro, a conversão falhará. Por exemplo, a tentativa de converter uma ARRAY(BOOLEAN) em uma ARRAY(DATE) falha.

Exemplo: conversão de um tipo de ARRAY em outro

O exemplo a seguir converte uma ARRAY(NUMBER) em uma ARRAY(VARCHAR):

SELECT CAST(
  CAST([1,2,3] AS ARRAY(NUMBER))
  AS ARRAY(VARCHAR)
);
Copy

Exemplo: como alterar a ordem dos pares chave-valor em um OBJECT

O exemplo a seguir altera a ordem dos pares chave-valor em um OBJECT estruturado:

SELECT CAST(
  {'city': 'San Mateo','state': 'CA'}::OBJECT(city VARCHAR, state VARCHAR)
  AS OBJECT(state VARCHAR, city VARCHAR)
);
Copy

Exemplo: como alterar os nomes da chave em um OBJECT

Para alterar os nomes das chaves em um OBJECT estruturado, especifique as palavras-chave RENAME FIELDS no fim de CAST. Por exemplo:

SELECT CAST({'city':'San Mateo','state': 'CA'}::OBJECT(city VARCHAR, state VARCHAR)
  AS OBJECT(city_name VARCHAR, state_name VARCHAR) RENAME FIELDS);
Copy
+------------------------------------------------------------------------------+
| CAST({'CITY':'SAN MATEO','STATE': 'CA'}::OBJECT(CITY VARCHAR, STATE VARCHAR) |
|   AS OBJECT(CITY_NAME VARCHAR, STATE_NAME VARCHAR) RENAME FIELDS)            |
|------------------------------------------------------------------------------|
| {                                                                            |
|   "city_name": "San Mateo",                                                  |
|   "state_name": "CA"                                                         |
| }                                                                            |
+------------------------------------------------------------------------------+

Exemplo: como adicionar chaves a um OBJECT

Se o tipo no qual você está convertendo tiver pares chave-valor adicionais que não estão presentes no objeto estruturado original, especifique as palavras-chave ADD FIELDS no fim de CAST. Por exemplo:

SELECT CAST({'city':'San Mateo','state': 'CA'}::OBJECT(city VARCHAR, state VARCHAR)
  AS OBJECT(city VARCHAR, state VARCHAR, zipcode NUMBER) ADD FIELDS);
Copy
+------------------------------------------------------------------------------+
| CAST({'CITY':'SAN MATEO','STATE': 'CA'}::OBJECT(CITY VARCHAR, STATE VARCHAR) |
|   AS OBJECT(CITY VARCHAR, STATE VARCHAR, ZIPCODE NUMBER) ADD FIELDS)         |
|------------------------------------------------------------------------------|
| {                                                                            |
|   "city": "San Mateo",                                                       |
|   "state": "CA",                                                             |
|   "zipcode": null                                                            |
| }                                                                            |
+------------------------------------------------------------------------------+

Os valores das chaves recém-adicionadas serão definidos como NULL. Se você quiser atribuir um valor a essas chaves, chame a função OBJECT_INSERT.

Como criar ARRAYs estruturadas, OBJECTs estruturados e MAPs

As seções a seguir explicam como criar ARRAYs estruturadas, OBJECTs estruturados e MAPs.

Como usar funções SQL para criar ARRAYs e OBJECTs estruturados

As seguintes funções criam ARRAYs semiestruturadas:

As seguintes funções criam OBJECTs semiestruturados:

Para criar uma ARRAY ou OBJECT estruturado, use essas funções e converta explicitamente o valor de retorno da função. Por exemplo:

SELECT ARRAY_CONSTRUCT(10, 20, 30)::ARRAY(NUMBER);
Copy
SELECT OBJECT_CONSTRUCT(
  'name', 'abc',
  'created_date', '2020-01-18'::DATE
)::OBJECT(
  name VARCHAR,
  created_date DATE
);
Copy

Para obter mais detalhes, consulte Conversão explícita de um tipo semiestruturado em um tipo estruturado.

Nota

Você não pode passar ARRAYs estruturadas, OBJECTs estruturados ou MAPs para essas funções. Fazer isso resultaria na conversão implícita de um tipo estruturado em um tipo semiestruturado, o que não é permitido (conforme observado em Conversão implícita de um valor (coerção)).

Uso de constantes de ARRAY e OBJECT para criar ARRAYs e OBJECTs estruturados

Ao especificar uma constante de ARRAY ou uma constante de OBJECT, você está especificando uma ARRAY ou um OBJECT semiestruturado.

Para criar uma ARRAY ou um OBJECT estruturado, você deve converter explicitamente a expressão. Por exemplo:

SELECT [10, 20, 30]::ARRAY(NUMBER);
Copy
SELECT {
  'name': 'abc',
  'created_date': '2020-01-18'::DATE
}::OBJECT(
  name VARCHAR,
  created_date DATE
);
Copy

Para obter mais detalhes, consulte Conversão explícita de um tipo semiestruturado em um tipo estruturado.

Como criar um MAP

Para criar um MAP, crie um objeto semiestruturado e converta o OBJECT em um MAP.

Por exemplo, as instruções a seguir produzem MAP {'city'->'San Mateo','state'->'CA'}:

SELECT OBJECT_CONSTRUCT(
  'city', 'San Mateo',
  'state', 'CA'
)::MAP(
  VARCHAR,
  VARCHAR
);
Copy
SELECT {
  'city': 'San Mateo',
  'state': 'CA'
}::MAP(
  VARCHAR,
  VARCHAR
);
Copy

A instrução a seguir produz o MAP {-10->'CA',-20->'OR'}:

SELECT {
  '-10': 'CA',
  '-20': 'OR'
}::MAP(
  NUMBER,
  VARCHAR
)
Copy

Para obter mais detalhes, consulte Conversão de OBJECTs e VARIANTs semiestruturados em MAPs.

Como trabalhar com chaves, valores e elementos em tipos estruturados

As seções a seguir explicam como usar valores e elementos em tipos estruturados.

Como obter a lista de chaves de um OBJECT estruturado

Para obter a lista de chaves em um OBJECT estruturado, chame a função OBJECT_KEYS:

SELECT OBJECT_KEYS({'city':'San Mateo','state':'CA'}::OBJECT(city VARCHAR, state VARCHAR));
Copy

Se o valor de entrada for um OBJECT estruturado, a função retornará uma ARRAY(VARCHAR) contendo as chaves. Se o valor de entrada for um OBJECT semiestruturado, a função retornará uma ARRAY.

Como obter a lista de chaves de um MAP

Para obter a lista de chaves em um MAP, chame a função MAP_KEYS:

SELECT MAP_KEYS({'my_key':'my_value'}::MAP(VARCHAR,VARCHAR));
Copy

Acesso aos valores e elementos de tipos estruturados

Você pode usar os seguintes métodos para acessar valores e elementos de ARRAYs estruturadas, OBJECTs estruturados e MAPs:

Os valores e elementos retornados têm o tipo especificado para o objeto, em vez de VARIANT.

O exemplo a seguir passa o primeiro elemento de uma ARRAY semiestruturada e uma ARRAY(VARCHAR) para a função SYSTEM$TYPEOF para retornar o tipo de dados desse elemento:

SELECT
  SYSTEM$TYPEOF(
    ARRAY_CONSTRUCT('San Mateo')[0]
  ) AS semi_structured_array_element,
  SYSTEM$TYPEOF(
    CAST(
      ARRAY_CONSTRUCT('San Mateo') AS ARRAY(VARCHAR)
    )[0]
  ) AS structured_array_element;
Copy
+-------------------------------+-----------------------------+
| SEMI_STRUCTURED_ARRAY_ELEMENT | STRUCTURED_ARRAY_ELEMENT    |
|-------------------------------+-----------------------------|
| VARIANT[LOB]                  | VARCHAR(16777216)[LOB]      |
+-------------------------------+-----------------------------+

Observe o seguinte:

  • Ao passar um OBJECT estruturado para a função GET ou GET_IGNORE_CASE, você deve especificar uma constante para a chave.

    Você não precisa especificar uma constante se estiver passando um MAP ou uma ARRAY estruturada para a função GET.

    Você também não precisa especificar uma constante se estiver passando um MAP para a função GET_IGNORE_CASE.

  • Ao passar um OBJECT estruturado, ARRAY estruturada ou MAP para a função GET_PATH, você deve especificar uma constante para o nome do caminho.

  • Para um objeto estruturado, se você usar uma chave OBJECT ou um caminho que não existe, ocorrerá um erro em tempo de compilação.

    Por outro lado, quando você usa um índice, chave ou caminho que não existe com um objeto semiestruturado, a função retorna NULL.

Como determinar o tamanho de uma ARRAY estruturada

Para determinar o tamanho de uma ARRAY estruturada, passe a ARRAY para a função ARRAY_SIZE:

SELECT ARRAY_SIZE([1,2,3]::ARRAY(NUMBER));
Copy

Como determinar o tamanho de um MAP

Para determinar o tamanho de um MAP, passe o MAP para a função MAP_SIZE:

SELECT MAP_SIZE({'my_key':'my_value'}::MAP(VARCHAR,VARCHAR));
Copy

Como procurar elementos em uma ARRAY estruturada

Para determinar se um elemento está presente em uma ARRAY estruturada, chame a função ARRAY_CONTAINS. Por exemplo:

SELECT ARRAY_CONTAINS(10, [1, 10, 100]::ARRAY(NUMBER));
Copy

Para determinar a posição de um elemento em uma ARRAY estruturada, chame a função ARRAY_POSITION. Por exemplo:

SELECT ARRAY_POSITION(10, [1, 10, 100]::ARRAY(NUMBER));
Copy

Nota

Para ambas as funções, use um elemento de um tipo que seja comparável ao tipo da ARRAY.

Não converta a expressão do elemento em VARIANT.

Como determinar se um MAP contém uma chave

Para determinar se MAP contém uma chave, chame a função MAP_CONTAINS_KEY:

Por exemplo:

SELECT MAP_CONTAINS_KEY('key_to_find', my_map);
Copy
SELECT MAP_CONTAINS_KEY(10, my_map);
Copy

Comparação de objetos

As seções a seguir explicam como comparar objetos:

Comparação de objetos estruturados com objetos semiestruturados

Você não pode comparar uma ARRAY estruturada, OBJECT estruturado ou MAP com uma ARRAY, OBJECT ou VARIANT semiestruturado.

Comparação de objetos estruturados com outros objetos estruturados

Você pode comparar dois objetos do mesmo tipo (por exemplo, duas ARRAYs estruturadas, dois OBJECTs estruturados ou dois MAPs).

Atualmente, os seguintes operadores de comparação são suportados para comparar tipos estruturados:

  • =

  • !=

  • <

  • <=

  • >=

  • >

Ao comparar dois objetos estruturados quanto à igualdade, observe o seguinte:

  • Se um tipo não puder ser forçado para outro tipo, a comparação falhará.

  • Ao comparar MAPs que possuem chaves numéricas, as chaves são comparadas como números (não como valores VARCHAR).

Ao comparar dois objetos estruturados usando <, <=, >= ou >, os campos do objeto estruturado são comparados em ordem alfabética. Por exemplo, o seguinte objeto:

{'a':2,'b':1}::OBJECT(b INTEGER,a INTEGER)
Copy

é maior que:

{'a':1,'b':2}::OBJECT(b INTEGER,a INTEGER)
Copy

Como determinar se duas ARRAYs se sobrepõem

Se você precisar determinar se os elementos de duas ARRAYs estruturadas se sobrepõem, chame a função ARRAYS_OVERLAP. Por exemplo:

SELECT ARRAYS_OVERLAP(numeric_array, other_numeric_array);
Copy

As ARRAYs devem ser de tipos comparáveis.

Observe que você não pode passar uma ARRAY semiestruturada e uma ARRAY estruturada para esta função. Ambas ARRAYs devem ser estruturadas ou semiestruturadas.

Transformação de tipos estruturados

As seções a seguir explicam como transformar ARRAYs estruturadas, OBJECTs estruturados e MAPs:

Transformação de ARRAYs estruturadas

Ao passar uma ARRAY estruturada para essas funções, as funções retornam uma ARRAY estruturada do mesmo tipo:

As próximas seções explicam como essas funções funcionam com ARRAYs estruturadas.

Funções que adicionam elementos a matrizes

As funções a seguir adicionam elementos a uma ARRAY:

Para essas funções, o tipo do elemento deve ser coercível ao tipo de ARRAY.

Por exemplo, a chamada a seguir é bem-sucedida porque NUMBER pode ser forçado a DOUBLE (o tipo de ARRAY):

SELECT ARRAY_APPEND( [1,2]::ARRAY(DOUBLE), 3::NUMBER );
Copy

A chamada a seguir foi bem-sucedida porque VARCHAR pode ser forçado a DOUBLE:

SELECT ARRAY_APPEND( [1,2]::ARRAY(DOUBLE), '3' );
Copy

A chamada a seguir falha porque DATE não pode ser forçado a NUMBER:

SELECT ARRAY_APPEND( [1,2]::ARRAY(NUMBER), '2022-02-02'::DATE );
Copy

Funções que aceitam várias ARRAYs como entrada

As funções a seguir aceitam várias ARRAYs como argumentos de entrada:

Ao chamar essas funções, ambos os argumentos devem ser ARRAYs estruturadas ou ARRAYs semiestruturadas. Por exemplo, as chamadas a seguir falham porque um argumento é uma ARRAY estruturada e o outro argumento é uma ARRAY semiestruturada:

SELECT ARRAY_CAT( [1,2]::ARRAY(NUMBER), ['3','4'] );
Copy
SELECT ARRAY_CAT( [1,2], ['3','4']::ARRAY(VARCHAR) );
Copy

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

As funções ARRAY_CAT e ARRAY_INTERSECTION retornam uma ARRAY de um tipo que pode acomodar ambos os tipos de entrada.

Por exemplo, a seguinte chamada para ARRAY_CAT passa em duas ARRAYs estruturadas:

  • A primeira ARRAY estruturada não permite NULLs e contém valores NUMBER com a escala de 0. (NUMBER é NUMBER(38, 0).)

  • A segunda ARRAY estruturada contém um NULL e um número que tem a escala de 1.

A ARRAY retornada por ARRAY_CAT permite NULLs e contém valores NUMBER com a escala de 1.

SELECT
  ARRAY_CAT(
    [1, 2, 3]::ARRAY(NUMBER NOT NULL),
    [5.5, NULL]::ARRAY(NUMBER(2, 1))
  ) AS concatenated_array,
  SYSTEM$TYPEOF(concatenated_array);
Copy
+--------------------+-----------------------------------+
| CONCATENATED_ARRAY | SYSTEM$TYPEOF(CONCATENATED_ARRAY) |
|--------------------+-----------------------------------|
| [                  | ARRAY(NUMBER(38,1))[LOB]          |
|   1,               |                                   |
|   2,               |                                   |
|   3,               |                                   |
|   5.5,             |                                   |
|   undefined        |                                   |
| ]                  |                                   |
+--------------------+-----------------------------------+

Para a função ARRAY_CAT, a ARRAY no segundo argumento deve ser coercível ao tipo no primeiro argumento.

Para as funções ARRAY_EXCEPT e ARRAY_INTERSECTION, a ARRAY no segundo argumento deve ser comparável à ARRAY no primeiro argumento.

Por exemplo, a chamada a seguir é bem-sucedida porque ARRAY(NUMBER) é comparável a ARRAY(DOUBLE):

SELECT ARRAY_EXCEPT( [1,2]::ARRAY(NUMBER), [2,3]::ARRAY(DOUBLE) );
Copy

A chamada a seguir falha porque ARRAY(NUMBER) não é comparável a ARRAY(VARCHAR):

SELECT ARRAY_EXCEPT( [1,2]::ARRAY(NUMBER), ['2','3']::ARRAY(VARCHAR) );
Copy

Transformação de OBJECTs estruturados

As seções a seguir explicam como retornar um OBJECT estruturado que foi transformado de outro OBJECT:

Se você precisar alterar a ordem dos pares chave-valor, renomear chaves ou adicionar chaves sem especificar valores, use a função CAST ou operador ::. Para obter mais detalhes, consulte Conversão de um tipo estruturado em outro.

Remoção dos pares chave-valor

Para retornar um novo objeto que contém os pares chave-valor de um objeto existente com pares chave-valor específicos removidos, chame a função OBJECT_DELETE.

Ao chamar esta função, observe o seguinte:

  • Para os argumentos que são chaves, você deve especificar constantes.

  • Se a chave especificada não fizer parte da definição do tipo OBJECT, a chamada falhará. Por exemplo, a chamada a seguir falha porque OBJECT não contém a chave especificada zip_code:

    SELECT OBJECT_DELETE( {'city':'San Mateo','state':'CA'}::OBJECT(city VARCHAR,state VARCHAR), 'zip_code' );
    
    Copy
    093201 (23001): Function OBJECT_DELETE: expected structured object to contain field zip_code but it did not.
    
  • A função retorna um OBJECT estruturado. O tipo de OBJECT exclui a chave excluída. Por exemplo, suponha que você remova a chave city:

    SELECT
      OBJECT_DELETE(
        {'city':'San Mateo','state':'CA'}::OBJECT(city VARCHAR,state VARCHAR),
        'city'
      ) AS new_object,
      SYSTEM$TYPE_OF(new_object);
    
    Copy

    A função retorna um OBJECT do tipo OBJECT(state VARCHAR), que não inclui a chave city.

    +-----------------+--------------------------------------+
    | NEW_OBJECT      | SYSTEM$TYPEOF(NEW_OBJECT)            |
    |-----------------+--------------------------------------|
    | {               | OBJECT(state VARCHAR(16777216))[LOB] |
    |   "state": "CA" |                                      |
    | }               |                                      |
    +-----------------+--------------------------------------+
    
  • Se a função remover todas as chaves do objeto, a função retornará um OBJECT estruturado vazio do tipo OBJECT().

    SELECT
      OBJECT_DELETE(
        {'state':'CA'}::OBJECT(state VARCHAR),
        'state'
      ) AS new_object,
      SYSTEM$TYPEOF(new_object);
    
    Copy
    +------------+---------------------------+
    | NEW_OBJECT | SYSTEM$TYPEOF(NEW_OBJECT) |
    |------------+---------------------------|
    | {}         | OBJECT()[LOB]             |
    +------------+---------------------------+
    

    Quando o tipo de um OBJECT estruturado inclui pares chave-valor, os nomes e tipos desses pares são incluídos entre parênteses no tipo (por exemplo, OBJECT(cidade VARCHAR)). Como um OBJECT estruturado vazio não contém pares chave-valor, os parênteses estão vazios.

Inserção de pares chave-valor e atualização de valores

Para retornar um novo objeto que contém os pares chave-valor de um objeto existente com pares chave-valor adicionais ou novos valores para chaves, chame a função OBJECT_INSERT.

Ao chamar esta função, observe o seguinte:

  • Para os argumentos que são chaves, você deve especificar constantes.

  • Quando o argumento updateFlag é FALSE (quando você está inserindo um novo par chave-valor):

    • Se você especificar uma chave que já existe em OBJECT, ocorrerá um erro.

      SELECT OBJECT_INSERT(
        {'city':'San Mateo','state':'CA'}::OBJECT(city VARCHAR,state VARCHAR),
        'city',
        'San Jose',
        false
      );
      
      Copy
      093202 (23001): Function OBJECT_INSERT:
        expected structured object to not contain field city but it did.
      
    • A função retorna um OBJECT estruturado. O tipo de OBJECT inclui a chave recém-inserida. Por exemplo, suponha que você adicione a chave zipcode com o valor DOUBLE 94402:

      SELECT
        OBJECT_INSERT(
          {'city':'San Mateo','state':'CA'}::OBJECT(city VARCHAR,state VARCHAR),
          'zip_code',
          94402::DOUBLE,
          false
        ) AS new_object,
        SYSTEM$TYPEOF(new_object);
      
      Copy

      A função retorna um OBJECT do tipo OBJECT(cidade VARCHAR, estado VARCHAR, CEP DOUBLE):

      +-------------------------------------+---------------------------------------------------------------------------------------+
      | NEW_OBJECT                          | SYSTEM$TYPEOF(NEW_OBJECT)                                                             |
      |-------------------------------------+---------------------------------------------------------------------------------------|
      | {                                   | OBJECT(city VARCHAR(16777216), state VARCHAR(16777216), zip_code FLOAT NOT NULL)[LOB] |
      |   "city": "San Mateo",              |                                                                                       |
      |   "state": "CA",                    |                                                                                       |
      |   "zip_code": 9.440200000000000e+04 |                                                                                       |
      | }                                   |                                                                                       |
      +-------------------------------------+---------------------------------------------------------------------------------------+
      

      O tipo do valor inserido determina o tipo adicionado à definição de tipo OBJECT. Nesse caso, o valor de zipcode é um valor convertido em DOUBLE, portanto, o tipo de zipcode é DOUBLE.

  • Quando o argumento updateFlag é TRUE (quando você está substituindo um par chave-valor existente):

    • Se você especificar uma chave que não existe em OBJECT, ocorrerá um erro.

    • A função retorna um OBJECT estruturado do mesmo tipo.

    • O tipo do valor inserido é imposto ao tipo da chave existente.

Seleção de pares chave-valor de um OBJECT existente

Para retornar um novo objeto que contém pares chave-valor selecionados de um objeto existente, chame a função OBJECT_PICK.

Ao chamar esta função, observe o seguinte:

  • Para os argumentos que são chaves, você deve especificar constantes.

  • Você não pode passar uma ARRAY de chaves como segundo argumento. Você deve especificar cada chave como um argumento separado.

  • A função retorna um OBJECT estruturado. O tipo de OBJECT inclui as chaves na ordem em que são especificadas.

    Por exemplo, suponha que você selecione as chaves state e city nesta ordem:

    SELECT
      OBJECT_PICK(
        {'city':'San Mateo','state':'CA','zip_code':94402}::OBJECT(city VARCHAR,state VARCHAR,zip_code DOUBLE),
        'state',
        'city') AS new_object,
      SYSTEM$TYPEOF(new_object);
    
    Copy

    A função retorna um OBJECT do tipo OBJECT(state VARCHAR, city VARCHAR).

    +-----------------------+--------------------------------------------------------------+
    | NEW_OBJECT            | SYSTEM$TYPEOF(NEW_OBJECT)                                    |
    |-----------------------+--------------------------------------------------------------|
    | {                     | OBJECT(state VARCHAR(16777216), city VARCHAR(16777216))[LOB] |
    |   "state": "CA",      |                                                              |
    |   "city": "San Mateo" |                                                              |
    | }                     |                                                              |
    +-----------------------+--------------------------------------------------------------+
    

Transformação de MAPs

Para transformar MAPs, use as seguintes funções:

Como trabalhar com tipos estruturados

As seções a seguir explicam como usar diferentes funções SQL e definir operadores com objetos de tipos estruturados:

Como usar a função FLATTEN com tipos estruturados

Você pode passar ARRAYs estruturadas, OBJECTs estruturados e MAPs para a função FLATTEN. Como é o caso dos tipos de dados semiestruturados, você pode usar o argumento PATH para especificar o valor que está sendo nivelado.

  • Se o valor que estiver sendo nivelado for uma ARRAY estruturada e o argumento RECURSIVE for FALSE, a coluna value conterá um valor do mesmo tipo que ARRAY.

    Por exemplo:

    SELECT value, SYSTEM$TYPEOF(value)
      FROM TABLE(FLATTEN(INPUT => [1.08, 2.13, 3.14]::ARRAY(DOUBLE)));
    
    Copy
    +-------+----------------------+
    | VALUE | SYSTEM$TYPEOF(VALUE) |
    |-------+----------------------|
    |  1.08 | FLOAT[DOUBLE]        |
    |  2.13 | FLOAT[DOUBLE]        |
    |  3.14 | FLOAT[DOUBLE]        |
    +-------+----------------------+
    
  • Se o valor que estiver sendo nivelado for MAP e o argumento RECURSIVE for FALSE, a coluna key conterá uma chave do mesmo tipo que a chave MAP e a coluna value conterá um valor do mesmo tipo que o valor MAP.

    Por exemplo:

    SELECT key, SYSTEM$TYPEOF(key), value, SYSTEM$TYPEOF(value)
      FROM TABLE(FLATTEN(INPUT => {'my_key': 'my_value'}::MAP(VARCHAR, VARCHAR)));
    
    Copy
    +--------+------------------------+----------+------------------------+
    | KEY    | SYSTEM$TYPEOF(KEY)     | VALUE    | SYSTEM$TYPEOF(VALUE)   |
    |--------+------------------------+----------+------------------------|
    | my_key | VARCHAR(16777216)[LOB] | my_value | VARCHAR(16777216)[LOB] |
    +--------+------------------------+----------+------------------------+
    
  • Caso contrário, as colunas key e value terão o tipo VARIANT.

Para MAPs, a ordem das chaves e dos valores retornados é indeterminada.

Uso da função PARSE_JSON

Observe que a função PARSE_JSON não retorna tipos estruturados.

Uso de tipos estruturados com operadores de conjunto e expressões CASE

Você pode usar ARRAYs estruturadas, OBJECTs estruturados e MAPs em:

Para operadores de conjunto, se diferentes tipos forem usados nas diferentes expressões (por exemplo, se um tipo for ARRAY(NUMBER) e o outro for ARRAY(DOUBLE)), um tipo será forçado para o outro.

Como trabalhar com outras funções semiestruturadas

As funções a seguir não aceitam uma ARRAY estruturada, OBJECT estruturado ou MAP como argumento de entrada:

Passar um tipo estruturado como entrada resulta em um erro.

Acesso a tipos estruturados em aplicativos usando drivers

Em aplicativos que usam drivers (por exemplo, o driver ODBC ou JDBC, o Conector Snowflake para Python etc.), os valores de tipo estruturado são retornados como tipos semiestruturados. Por exemplo:

  • Uma coluna de ARRAY estruturada é retornada como ARRAY semiestruturada para o aplicativo cliente.

  • Uma coluna de OBJECT estruturado ou MAP é retornada como um OBJECT semiestruturado para o aplicativo cliente.

Uso de tipos estruturados com funções definidas pelo usuário (UDFs) e procedimentos armazenados

Ao criar uma função definida pelo usuário (UDF), uma função de tabela definida pelo usuário (UDTF) ou um procedimento armazenado em SQL ou Script Snowflake, você pode usar tipos estruturados nos argumentos e valores de retorno. Por exemplo:

CREATE OR REPLACE FUNCTION my_udf(
    location OBJECT(city VARCHAR, zipcode NUMBER, val ARRAY(BOOLEAN)))
  RETURNS VARCHAR
  AS
  $$
    ...
  $$;
Copy
CREATE OR REPLACE FUNCTION my_udtf(check BOOLEAN)
  RETURNS TABLE(col1 ARRAY(VARCHAR))
  AS
  $$
  ...
  $$;
Copy
CREATE OR REPLACE PROCEDURE my_procedure(values ARRAY(INTEGER))
  RETURNS ARRAY(INTEGER)
  LANGUAGE SQL
  AS
  $$
    ...
  $$;
Copy

Nota

Os tipos estruturados ainda não são suportados em UDFs, UDTFs e procedimentos armazenados em outras linguagens (Java, JavaScript, Python e Scala).

Exibição de informações sobre tipos estruturados

As seções a seguir descrevem as exibições e os comandos que podem ser usados para visualizar informações sobre tipos estruturados:

Uso do comando SHOW COLUMNS para visualizar informações de tipo estruturado

Na saída do comando SHOW COLUMNS, a coluna data_type inclui informações sobre os tipos de elementos, chaves e valores.

Uso dos comandos DESCRIBE e outros SHOW para visualizar informações de tipo estruturado

A saída dos comandos a seguir inclui informações sobre tipos estruturados:

Por exemplo, na saída DESCRIBE RESULT, a linha de uma coluna MAP(VARCHAR, VARCHAR) contém o seguinte valor na coluna type:

map(VARCHAR(16777216), VARCHAR(16777216))
Copy

A linha de uma coluna ARRAY(NUMBER) contém o seguinte valor na coluna type:

ARRAY(NUMBER(38,0))
Copy

Exibição de informações sobre os tipos estruturados usados em um banco de dados

Para colunas de tipos estruturados, INFORMATION_SCHEMA Exibição COLUMNS fornece apenas informações sobre o tipo de dados básico da coluna (ARRAY, OBJECT ou MAP).

Por exemplo, a coluna data_type contém apenas “ARRAY”, “OBJECT” ou “MAP”. A coluna não inclui os tipos de elementos, chaves ou valores.

Para visualizar informações sobre os tipos de elementos, chaves e valores, use as seguintes exibições: