Considerações sobre o descarregamento de dados¶

Cadeias de caracteres vazias e valores NULL¶

Uma cadeia de caracteres vazia é uma cadeia com comprimento zero ou sem caracteres, enquanto os valores NULL representam uma ausência de dados. Em arquivos CSV, um valor NULL é normalmente representado por dois delimitadores sucessivos (por exemplo, ,,) para indicar que o campo não contém dados; entretanto, é possível usar valores de cadeia de caracteres para denotar NULL (por exemplo, null) ou qualquer cadeia de caracteres única. Uma cadeia de caracteres vazia é normalmente representada por uma cadeia vazia entre aspas (por exemplo, '') para indicar que contém zero caracteres.

As seguintes opções de formato de arquivo permitem diferenciar entre cadeia de caracteres vazias e valores NULL ao descarregar ou carregar dados. Para obter mais informações sobre estes formatos de arquivo, consulte CREATE FILE FORMAT:

FIELD_OPTIONALLY_ENCLOSED_BY = 'character' | NONE

Use esta opção para incluir cadeias de caracteres no caractere especificado: aspas simples ('), aspas duplas (") ou NONE.

Incluir valores de cadeia de caracteres entre aspas enquanto se descarrega os dados não é necessário. O comando de localização COPY INTO pode descarregar valores de cadeia de caracteres vazias sem incluir aspas, com a opção EMPTY_FIELD_AS_NULL definida como FALSE. Se a opção EMPTY_FIELD_AS_NULL for TRUE (o que é proibido), então cadeias de caracteres vazias e valores NULL são indistinguíveis no arquivo de saída.

Quando um campo contém este caractere, aplique o escape usando o mesmo caractere. Por exemplo, se o valor for o caractere de aspas duplas e um campo tiver a cadeia de caracteres "A", aplique o escape das aspas duplas como segue: ""A"".

Padrão: NONE

EMPTY_FIELD_AS_NULL = TRUE | FALSE

• Ao descarregar dados de cadeias de caracteres vazias das tabelas, escolha uma das seguintes opções:

  • Preferido: Inclua as cadeias de caracteres entre aspas definindo a opção FIELD_OPTIONALLY_ENCLOSED_BY, para distinguir as cadeias de caracteres vazias de NULLs nos arquivos de saída CSV.

  • Deixe os campos de cadeia de caracteres sem aspas definindo a opção FIELD_OPTIONALLY_ENCLOSED_BY como NONE (padrão), e defina o valor EMPTY_FIELD_AS_NULL como FALSE para descarregar as cadeias de caracteres vazias como campos vazios.

    Importante

    Se você escolher esta opção, certifique-se de especificar uma cadeia de caracteres substituta para dados NULL usando a opção NULL_IF, para distinguir valores NULL das cadeias de caracteres vazias no arquivo de saída. Se mais tarde você optar por carregar dados dos arquivos de saída, você especificará o mesmo valor NULL_IF para identificar os valores NULL nos arquivos de dados.

• Ao carregar dados em tabelas, use esta opção para especificar se deve inserir SQL NULL para campos vazios em um arquivo de entrada. Se definido como FALSE, o Snowflake tenta converter um campo vazio no tipo de coluna correspondente. Uma cadeia de caracteres vazia é inserida em colunas do tipo de dados STRING. Para outros tipos de colunas, o comando COPY produz um erro.

Padrão: TRUE

NULL_IF = ( 'string1' [ , 'string2' ... ] )

Ao descarregar os dados das tabelas: o Snowflake converte os valores SQL NULL para o primeiro valor da lista. Tenha o cuidado de especificar um valor que você deseja que seja interpretado como NULL. Por exemplo, se você estiver descarregando dados para um arquivo que será lido por outro sistema, certifique-se de especificar um valor que será interpretado como NULL por esse sistema.

Padrão: \\N (ou seja, NULL, que considera que o valor ESCAPE_UNENCLOSED_FIELD é \\ (padrão))

-- Source table (null_empty1) contents
+---+------+--------------+
| i | V    | D            |
|---+------+--------------|
| 1 | NULL | NULL value   |
| 2 |      | Empty string |
+---+------+--------------+

-- Create a file format that describes the data and the guidelines for processing it
create or replace file format my_csv_format
  field_optionally_enclosed_by='0x27' null_if=('null');

-- Unload table data into a stage
copy into @mystage
  from null_empty1
  file_format = (format_name = 'my_csv_format');

-- Output the data file contents
1,'null','NULL value'
2,'','Empty string'

-- Load data from the staged file into the target table (null_empty2)
copy into null_empty2
    from @mystage/data_0_0_0.csv.gz
    file_format = (format_name = 'my_csv_format');

select * from null_empty2;

+---+------+--------------+
| i | V    | D            |
|---+------+--------------|
| 1 | NULL | NULL value   |
| 2 |      | Empty string |
+---+------+--------------+

-- Source table (null_empty1) contents
+---+------+--------------+
| i | V    | D            |
|---+------+--------------|
| 1 | NULL | NULL value   |
| 2 |      | Empty string |
+---+------+--------------+

-- Create a file format that describes the data and the guidelines for processing it
create or replace file format my_csv_format
  empty_field_as_null=false null_if=('null');

-- Unload table data into a stage
copy into @mystage
  from null_empty1
  file_format = (format_name = 'my_csv_format');

-- Output the data file contents
1,null,NULL value
2,,Empty string

-- Load data from the staged file into the target table (null_empty2)
copy into null_empty2
    from @mystage/data_0_0_0.csv.gz
    file_format = (format_name = 'my_csv_format');

select * from null_empty2;

+---+------+--------------+
| i | V    | D            |
|---+------+--------------|
| 1 | NULL | NULL value   |
| 2 |      | Empty string |
+---+------+--------------+

Descarregamento em um único arquivo¶

Por padrão, instruções de localização COPY INTO separam os dados da tabela em um conjunto de arquivos de saída para tirar proveito de operações paralelas. O tamanho máximo para cada arquivo é definido usando a opção de cópia MAX_FILE_SIZE. O valor padrão é 16777216 (16 MB), mas pode ser aumentado para acomodar arquivos maiores. O tamanho de arquivo máximo com suporte é 5 GB para estágios de Amazon S3, Google Cloud Storage ou Microsoft Azure.

Para descarregar dados em um único arquivo de saída (ao custo potencial de redução de desempenho), especifique a opção de cópia SINGLE = true em sua instrução. Opcionalmente, você pode especificar um nome para o arquivo no caminho.

Por exemplo, descarregue os dados da tabela mytable para um único arquivo chamado myfile.csv em um estágio nomeado. Aumente o limite MAX_FILE_SIZE para acomodar o grande conjunto de dados:

copy into @mystage/myfile.csv.gz from mytable
file_format = (type=csv compression='gzip')
single=true
max_file_size=4900000000;

Descarregamento de uma tabela relacional em JSON¶

Você pode usar a função OBJECT_CONSTRUCT combinada com o comando COPY para converter as linhas de uma tabela relacional em uma única coluna VARIANT e descarregar as linhas em um arquivo.

Por exemplo:

-- Create a table
CREATE OR REPLACE TABLE mytable (
 id number(8) NOT NULL,
 first_name varchar(255) default NULL,
 last_name varchar(255) default NULL,
 city varchar(255),
 state varchar(255)
);

-- Populate the table with data
INSERT INTO mytable (id,first_name,last_name,city,state)
 VALUES
 (1,'Ryan','Dalton','Salt Lake City','UT'),
 (2,'Upton','Conway','Birmingham','AL'),
 (3,'Kibo','Horton','Columbus','GA');

-- Unload the data to a file in a stage
COPY INTO @mystage
 FROM (SELECT OBJECT_CONSTRUCT('id', id, 'first_name', first_name, 'last_name', last_name, 'city', city, 'state', state) FROM mytable)
 FILE_FORMAT = (TYPE = JSON);

-- The COPY INTO location statement creates a file named data_0_0_0.json.gz in the stage.
-- The file contains the following data:

{"city":"Salt Lake City","first_name":"Ryan","id":1,"last_name":"Dalton","state":"UT"}
{"city":"Birmingham","first_name":"Upton","id":2,"last_name":"Conway","state":"AL"}
{"city":"Columbus","first_name":"Kibo","id":3,"last_name":"Horton","state":"GA"}

Descarregamento de uma tabela relacional no Parquet com várias colunas¶

Você pode descarregar dados de uma tabela relacional em um arquivo Parquet de várias colunas usando uma instrução SELECT como entrada para a instrução COPY. A instrução SELECT especifica os dados da coluna na tabela relacional a serem incluídos no arquivo descarregado. Use a opção de cópia HEADER = TRUE para incluir os cabeçalhos das colunas nos arquivos de saída.

Por exemplo, descarregue as linhas de três colunas (id, name, start_date) da tabela mytable em um ou mais arquivos que tenham o formato de nomenclatura myfile.parquet:

COPY INTO @mystage/myfile.parquet FROM (SELECT id, name, start_date FROM mytable)
  FILE_FORMAT=(TYPE='parquet')
  HEADER = TRUE;

Conversão explícita de colunas numéricas em tipos de dados Parquet¶

Por padrão, quando os dados da tabela são descarregados em arquivos Parquet, as colunas com número de ponto fixo são descarregadas como colunas DECIMAL, enquanto as colunas com número de ponto flutuante são descarregadas como colunas DOUBLE.

Para escolher os tipos de dados Parquet para conjuntos de dados descarregados, chame a função CAST , :: na instrução COPY INTO <local> para converter colunas específicas da tabela em tipos de dados explícitos. Uma consulta em uma instrução COPY INTO <local> permite selecionar colunas específicas para descarregar e aceita funções de conversão SQL para transformar os dados da coluna.

Consultas em instruções COPY INTO <local> suportam a sintaxe e semântica das instruções SELECT para consultar colunas específicas da tabela Snowflake a descarregar. Converta os dados em colunas numéricas para tipos de dados específicos usando a função CAST , ::.

A tabela a seguir mapeia os tipos de dados numéricos do Snowflake para os tipos de dados físicos e lógicos do Parquet:

O exemplo a seguir mostra uma instrução COPY INTO <local> que converte os dados numéricos em cada coluna descarregada para um tipo de dados diferente para escolher explicitamente os tipos de dados nos arquivos Parquet:

COPY INTO @mystage
FROM (SELECT CAST(C1 AS TINYINT) ,
             CAST(C2 AS SMALLINT) ,
             CAST(C3 AS INT),
             CAST(C4 AS BIGINT) FROM mytable)
FILE_FORMAT=(TYPE=PARQUET);

Números de ponto flutuante truncados¶

Quando as colunas com número de ponto flutuante são descarregadas em arquivos CSV ou JSON, o Snowflake trunca os valores para aproximadamente (15,9).

Os valores não são truncados ao descarregar colunas com números de ponto flutuante em arquivos Parquet.