Usar COPY para carregar dados em colunas SUPER - Amazon Redshift
Copiar dados de JSON e AvroCopiar dados de texto e CSVCopiar dados de Parquet e ORC em formato de coluna

O Amazon Redshift não permitirá mais a criação de funções definidas pelo usuário (UDFs) do Python a partir de 1.º de novembro de 2025. Se quiser usar UDFs do Python, você deve criá-las antes dessa data. As UDFs do Python existentes continuarão a funcionar normalmente. Para ter mais informações, consulte a publicação de blog .

Usar COPY para carregar dados em colunas SUPER

Nas seções a seguir, você pode aprender sobre diferentes maneiras de usar o comando COPY para carregar dados JSON no Amazon Redshift. Para obter informações sobre os parâmetros de formato de dados que o Amazon Redshift usa para analisar JSON em comandos COPY, leia a descrição do parâmetro JSON format for COPY em Parâmetros de formato de dados.

Copiar dados de JSON e Avro

O Amazon Redshift fornece os seguintes métodos para ingerir um documento JSON usando COPY, mesmo com uma estrutura JSON totalmente ou parcialmente desconhecida:

  • Armazene os dados derivados de um documento JSON em uma única coluna de dados SUPER usando a opção noshred. Este método é útil quando o esquema não é conhecido ou é esperado para mudar. Assim, este método torna mais fácil armazenar toda a tupla em uma única coluna SUPER.

  • Destruir o documento JSON em várias colunas do Amazon Redshift usando o método auto ou a opção jsonpaths. Os atributos podem ser escalares do Amazon Redshift ou valores SUPER.

Você pode usar essas opções com os formatos JSON ou Avro. Para obter mais informações sobre opções JSON como noshred, auto, e jsonpaths, consulte JSON format for COPY.

O tamanho máximo de um objeto JSON no Amazon Redshift é 4 MB, o que se aplica antes de qualquer fragmentação ou análise.

Método 1: copiar um documento JSON em uma única coluna de dados SUPER usando noshred

Você pode copiar documentos JSON inteiros em colunas de dados SUPER únicas usando a opção noshred no comando COPY. Considere o seguinte exemplo:

  1. Crie uma tabela com uma única coluna de dados SUPER.

    CREATE TABLE region_nations_noshred (rdata SUPER);

  2. Copie os dados do Amazon S3 na única coluna de dados SUPER. Para ingerir os dados de origem JSON em uma única coluna de dados SUPER, especifique a propriedade noshred na cláusula FORMAT JSON.

    COPY region_nations_noshred FROM 's3://redshift-downloads/semistructured/tpch-nested/data/json/region_nation'
REGION 'us-east-1' IAM_ROLE 'arn:aws:iam::xxxxxxxxxxxx:role/Redshift-S3'
FORMAT JSON 'noshred';

    Depois que COPY ingeriu com êxito o JSON, sua tabela tem uma coluna rdata de dados SUPER que contém os dados de todo o objeto JSON. Os dados ingeridos mantêm todas as propriedades da hierarquia JSON. No entanto, as folhas são convertidas para tipos escalares do Amazon Redshift para processamento eficiente de consultas.

  3. Use a consulta a seguir para recuperar a string JSON original.

    SELECT rdata FROM region_nations_noshred;

    Quando o Amazon Redshift gera uma coluna de dados SUPER, ela se torna acessível usando JDBC como uma string por meio da serialização JSON. Para obter mais informações, consulte Serializar JSON aninhado complexo.

Método 2: copiar um documento JSON em múltiplas colunas de dados SUPER

Você pode fragmentar um documento JSON em várias colunas que podem ser colunas de dados SUPER ou tipos escalares do Amazon Redshift. O Amazon Redshift espalha diferentes partes do objeto JSON em colunas diferentes. Considere o seguinte exemplo:

  1. Crie uma tabela com várias colunas para armazenar o JSON fragmentado.

    CREATE TABLE region_nations
(
 r_regionkey smallint
 ,r_name varchar
 ,r_comment varchar
 ,r_nations super
 );

  2. Para copiar JSON para a tabela region_nations, especifique a opção AUTO na cláusula FORMAT JSON para dividir o valor JSON em várias colunas. COPY corresponde aos atributos JSON de nível superior com nomes de coluna e permite que valores aninhados sejam ingeridos como valores SUPER, como matrizes e objetos JSON. 

    COPY region_nations FROM 's3://redshift-downloads/semistructured/tpch-nested/data/json/region_nation'
REGION 'us-east-1' IAM_ROLE 'arn:aws:iam::xxxxxxxxxxxx:role/Redshift-S3'
FORMAT JSON 'auto';

    Quando os nomes de atributo JSON estiverem em maiúsculas e minúsculas mistas, especifique a propriedade auto ignorecase na cláusula FORMAT JSON. Para obter mais informações sobre o uso do comando COPY, consulte Carregar de dados JSON usando a opção "auto ignorecase".

Em alguns casos, há uma incompatibilidade entre nomes de coluna e atributos JSON ou o atributo a ser carregado é aninhado mais do que um nível profundo. Em caso afirmativo, use um arquivo jsonpaths para mapear manualmente atributos JSON para colunas do Amazon Redshift. Considere o seguinte exemplo:

  1. Crie uma tabela com várias colunas para armazenar o JSON fragmentado.

    CREATE TABLE region_nations
(
 r_regionkey smallint
 ,r_name varchar
 ,r_comment varchar
 ,r_nations super
 );

  2. Nesse caso, os nomes das colunas não correspondem aos atributos JSON. Você pode criar um arquivo jsonpaths que mapeia os caminhos dos atributos para as colunas da tabela por sua posição no array jsonpaths como o seguinte:

    {"jsonpaths": [
       "$.r_regionkey",
       "$.r_name",
       "$.r_comment",
       "$.r_nations
    ]
}

  3. Use o local do arquivo jsonpaths como argumento para a opção FORMAT JSON em COPY.

    COPY nations FROM 's3://redshift-downloads/semistructured/tpch-nested/data/json/region_nation'
REGION 'us-east-1' IAM_ROLE 'arn:aws:iam::xxxxxxxxxxxx:role/Redshift-S3'
FORMAT JSON 's3://redshift-downloads/semistructured/tpch-nested/data/jsonpaths/nations_jsonpaths.json';

  4. Use a consulta a seguir para acessar a tabela que mostra a dispersão de dados para várias colunas. As colunas de dados SUPER são impressas usando o formato JSON.

    SELECT r_regionkey,r_name,r_comment,r_nations[0].n_nationkey FROM region_nations ORDER BY 1,2,3 LIMIT 1;

Arquivos jsonpaths mapeiam campos no documento JSON para colunas de tabela. É possível extrair outras colunas, como chaves de distribuição e classificação, enquanto ainda carrega o documento completo como uma coluna SUPER. A consulta a seguir carrega o documento completo na coluna nations. A coluna name é a chave de classificação, e a coluna regionkey é a chave de distribuição. Considere o seguinte exemplo:

  1. Crie uma tabela com várias colunas para armazenar o JSON fragmentado.

    CREATE TABLE nations_sorted (
    regionkey smallint,
    name varchar,
    nations super
) DISTKEY(regionkey) SORTKEY(name);

  2. Mapeie o jsonpath raiz “$” para a raiz do documento da seguinte maneira:

    {"jsonpaths": [
       "$.r_regionkey",
       "$.r_name",
       "$"
    ]
}

  3. Use o local do arquivo jsonpaths como argumento para a opção FORMAT JSON em COPY.

    COPY nations_sorted FROM 's3://redshift-downloads/semistructured/tpch-nested/data/json/region_nation'
REGION 'us-east-1' IAM_ROLE 'arn:aws:iam::xxxxxxxxxxxx:role/Redshift-S3'
FORMAT JSON 's3://redshift-downloads/semistructured/tpch-nested/data/jsonpaths/nations_sorted_jsonpaths.json';

Para obter mais informações sobre como usar o jsonpaths, consulte COPY no formato JSON.

Copiar dados de texto e CSV

O Amazon Redshift representa colunas SUPER em formatos de texto e CSV como JSON serializado. A formatação JSON válida é necessária para que as colunas SUPER sejam carregadas com as informações do tipo correto. Tire aspas de que objetos, matrizes, números, boolianos e valores nulos. Quebre valores de strings entre aspas duplas. As colunas SUPER usam regras de escape padrão para formatos de texto e CSV.

Ao copiar de CSV, os delimitadores usam caracteres de escape de acordo com o padrão CSV. Considere o seguinte exemplo: 

CREATE TABLE region_nations
(
 r_regionkey smallint
 ,r_name varchar
 ,r_comment varchar
 ,r_nations super
 );
 
 COPY region_nations FROM 's3://redshift-downloads/semistructured/tpch-nested/data/csv/region_nation'
REGION 'us-east-1' IAM_ROLE 'arn:aws:iam::xxxxxxxxxxxx:role/Redshift-S3'
FORMAT CSV;

Ao copiar de texto, quando o delimitador escolhido também pode aparecer em um campo SUPER, use a opção ESCAPE durante COPY e UNLOAD. Considere o seguinte exemplo:

CREATE TABLE region_nations
(
 r_regionkey smallint
 ,r_name varchar
 ,r_comment varchar
 ,r_nations super
 );
 
COPY region_nations FROM 's3://redshift-downloads/semistructured/tpch-nested/data/text/region_nation'
REGION 'us-east-1' IAM_ROLE 'arn:aws:iam::xxxxxxxxxxxx:role/Redshift-S3'
DELIMITER ','
ESCAPE;

Copiar dados de Parquet e ORC em formato de coluna

Se seus dados semiestruturados ou aninhados já estiverem disponíveis no formato Apache Parquet ou Apache ORC, você pode usar o comando COPY para ingerir dados no Amazon Redshift.

A estrutura da tabela do Amazon Redshift deve corresponder ao número de colunas e aos tipos de dados da coluna dos arquivos Parquet ou ORC. Especificando SERIALIZETOJSON no comando COPY, você pode carregar qualquer tipo de coluna no arquivo que se alinha com uma coluna SUPER na tabela como SUPER. Isso inclui tipos de estrutura e array.

O exemplo a seguir usa um formato Parquet.

COPY region_nations FROM 's3://redshift-downloads/semistructured/tpch-nested/data/parquet/region_nation'
REGION 'us-east-1' IAM_ROLE 'arn:aws:iam::xxxxxxxxxxxx:role/Redshift-S3'
FORMAT PARQUET SERIALIZETOJSON;

O exemplo a seguir usa um formato ORC.

COPY region_nations FROM 's3://redshift-downloads/semistructured/tpch-nested/data/orc/region_nation'
IAM_ROLE 'arn:aws:iam::xxxxxxxxxxxx:role/Redshift-S3'
FORMAT ORC SERIALIZETOJSON;

Quando os atributos dos tipos de dados de data ou hora estão no ORC, o Amazon Redshift os converte em varchar ao codificá-los em SUPER.