ALTER STAGE

Modifica as propriedades de um estágio nomeado interno ou externo existente.

Consulte também:

CREATE STAGE , DROP STAGE , SHOW STAGES , DESCRIBE STAGE

Sintaxe

ALTER STAGE [ IF EXISTS ] <name> RENAME TO <new_name>

ALTER STAGE [ IF EXISTS ] <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

ALTER STAGE <name> UNSET TAG <tag_name> [ , <tag_name> ... ]

-- Internal stage
ALTER STAGE [ IF EXISTS ] <name> SET
  { [ FILE_FORMAT = ( { FORMAT_NAME = '<file_format_name>' | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
    [ COPY_OPTIONS = ( copyOptions ) ]
    [ COMMENT = '<string_literal>' ] }

-- External stage
ALTER STAGE [ IF EXISTS ] <name> SET {
    [ externalStageParams ]
    [ FILE_FORMAT = ( { FORMAT_NAME = '<file_format_name>' | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
    [ COPY_OPTIONS = ( copyOptions ) ]
    [ COMMENT = '<string_literal>' ]
    }
Copy

Onde:

externalStageParams (for Amazon S3) ::=
  [ URL = 's3://<bucket>[/<path>/]' ]
  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( {  { AWS_KEY_ID = '<string>' AWS_SECRET_KEY = '<string>' [ AWS_TOKEN = '<string>' ] } | AWS_ROLE = '<string>'  } ) } ]
  [ ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] |
                   [ TYPE = 'AWS_SSE_S3' ] |
                   [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] |
                   [ TYPE = 'NONE' ] ) ]
Copy
externalStageParams (for Google Cloud Storage) ::=
  [ URL = 'gcs://<bucket>[/<path>/]' ]
  [ STORAGE_INTEGRATION = <integration_name> } ]
  [ ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] | [ TYPE = 'NONE' ] ) ]
Copy
externalStageParams (for Microsoft Azure) ::=
  [ URL = 'azure://<account>.blob.core.windows.net/<container>[/<path>/]' ]
  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( [ AZURE_SAS_TOKEN = '<string>' ] ) } ]
  [ ENCRYPTION = ( [ TYPE = { 'AZURE_CSE' | 'NONE' } ] [ MASTER_KEY = '<string>' ] ) ]
Copy
formatTypeOptions ::=
-- If TYPE = CSV
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     RECORD_DELIMITER = '<character>' | NONE
     FIELD_DELIMITER = '<character>' | NONE
     FILE_EXTENSION = '<string>'
     PARSE_HEADER = TRUE | FALSE
     SKIP_HEADER = <integer>
     SKIP_BLANK_LINES = TRUE | FALSE
     DATE_FORMAT = '<string>' | AUTO
     TIME_FORMAT = '<string>' | AUTO
     TIMESTAMP_FORMAT = '<string>' | AUTO
     BINARY_FORMAT = HEX | BASE64 | UTF8
     ESCAPE = '<character>' | NONE
     ESCAPE_UNENCLOSED_FIELD = '<character>' | NONE
     TRIM_SPACE = TRUE | FALSE
     FIELD_OPTIONALLY_ENCLOSED_BY = '<character>' | NONE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
     ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     EMPTY_FIELD_AS_NULL = TRUE | FALSE
     SKIP_BYTE_ORDER_MARK = TRUE | FALSE
     ENCODING = '<string>' | UTF8
-- If TYPE = JSON
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     DATE_FORMAT = '<string>' | AUTO
     TIME_FORMAT = '<string>' | AUTO
     TIMESTAMP_FORMAT = '<string>' | AUTO
     BINARY_FORMAT = HEX | BASE64 | UTF8
     TRIM_SPACE = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
     FILE_EXTENSION = '<string>'
     ENABLE_OCTAL = TRUE | FALSE
     ALLOW_DUPLICATE = TRUE | FALSE
     STRIP_OUTER_ARRAY = TRUE | FALSE
     STRIP_NULL_VALUES = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     IGNORE_UTF8_ERRORS = TRUE | FALSE
     SKIP_BYTE_ORDER_MARK = TRUE | FALSE
-- If TYPE = AVRO
     COMPRESSION = AUTO | GZIP | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     TRIM_SPACE = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
-- If TYPE = ORC
     TRIM_SPACE = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
-- If TYPE = PARQUET
     COMPRESSION = AUTO | LZO | SNAPPY | NONE
     SNAPPY_COMPRESSION = TRUE | FALSE
     BINARY_AS_TEXT = TRUE | FALSE
     USE_LOGICAL_TYPE = TRUE | FALSE
     TRIM_SPACE = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
-- If TYPE = XML
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     IGNORE_UTF8_ERRORS = TRUE | FALSE
     PRESERVE_SPACE = TRUE | FALSE
     STRIP_OUTER_ELEMENT = TRUE | FALSE
     DISABLE_SNOWFLAKE_DATA = TRUE | FALSE
     DISABLE_AUTO_CONVERT = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     SKIP_BYTE_ORDER_MARK = TRUE | FALSE
Copy
copyOptions ::=
     ON_ERROR = { CONTINUE | SKIP_FILE | SKIP_FILE_<num> | 'SKIP_FILE_<num>%' | ABORT_STATEMENT }
     SIZE_LIMIT = <num>
     PURGE = TRUE | FALSE
     RETURN_FAILED_ONLY = TRUE | FALSE
     MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE
     ENFORCE_LENGTH = TRUE | FALSE
     TRUNCATECOLUMNS = TRUE | FALSE
     FORCE = TRUE | FALSE
Copy

Sintaxe da tabela de diretório

ALTER STAGE [ IF EXISTS ] <name> SET DIRECTORY = ( { ENABLE = TRUE | FALSE } )

ALTER STAGE [ IF EXISTS ] <name> REFRESH [ SUBPATH = '<relative-path>' ]
Copy

Parâmetros

name

Especifica o identificador do estágio a ser alterado. Se o identificador contiver espaços ou caracteres especiais, toda a cadeia de caracteres deverá ser delimitada por aspas duplas. Os identificadores entre aspas duplas também diferenciam letras maiúsculas de minúsculas.

RENAME TO new_name

Especifica o novo identificador do estágio; ele deve ser único para o esquema.

Para obter mais detalhes, consulte Requisitos para identificadores.

Você pode mover o objeto para um banco de dados e/ou esquema diferente enquanto opcionalmente renomeia o objeto. Para isso, especifique um valor qualificado new_name que inclua o novo banco de dados e/ou nome do esquema no formulário db_name.schema_name.object_name ou schema_name.object_name, respectivamente.

Nota

  • O banco de dados e/ou esquema de destino já deve existir. Além disso, um objeto com o mesmo nome não pode já existir no banco de dados de destino; caso contrário, a instrução retorna um erro.

  • É proibido mover um objeto para um esquema de acesso gerenciado a menos que o proprietário do objeto (ou seja, a função que tem o privilégio OWNERSHIP sobre o objeto) também possua o esquema de destino.

SET ...

Especifica as opções/propriedades a serem definidas para o estágio:

URL = ' ... ' , . STORAGE_INTEGRATION = ... , . CREDENTIALS = ( ... ) , . ENCRYPTION = ( ... )

Modifica o URL específico da nuvem, a integração de armazenamento ou credenciais e/ou criptografia do estágio externo. Para obter mais detalhes, consulte Parâmetros do estágio externo (neste tópico).

FILE_FORMAT = ( FORMAT_NAME = 'file_format_name' ) ou . FILE_FORMAT = ( TYPE = CSV | JSON | AVRO | ORC | PARQUET | XML [ ... ] )

Modifica o formato do arquivo para o estágio, que pode ser qualquer uma das opções:

FORMAT_NAME = file_format_name

Especifica um objeto de formato de arquivo existente a ser usado para o estágio. O objeto de formato de arquivo especificado determina o tipo de formato (CSV, JSON etc.) e outras opções de formato para arquivos de dados.

Observe que nenhuma opção adicional de formato está especificada na cadeia de caracteres. Em vez disso, o objeto de formato de arquivo nomeado define as outras opções de formato de arquivo usadas para carregar/descarregar dados. Para obter mais informações, consulte CREATE FILE FORMAT.

TYPE = CSV | JSON | AVRO | ORC | PARQUET | XML [ ... ]

Especifica o tipo de formato de arquivo do estágio:

  • O carregamento de dados de um estágio (usando COPY INTO <tabela>) acomoda todos os tipos de formato de arquivo suportados.

  • O descarregamento de dados em um estágio (usando COPY INTO <local>) abrange CSV, JSON ou PARQUET.

Se um tipo de formato de arquivo for especificado, as opções adicionais específicas de formato podem ser modificadas. Para obter mais detalhes, consulte Opções do tipo de formato (neste tópico).

Nota

FORMAT_NAME e TYPE são mutuamente exclusivos; você só pode especificar um ou outro para um estágio.

COPY_OPTIONS = ( ... )

Modifica as opções de cópia para o formato de arquivo (separadas por espaços em branco, vírgulas ou novas linhas). Para obter mais detalhes, consulte Opções de cópia (neste tópico).

TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ]

Especifica o nome da tag e o valor da cadeia de caracteres dela.

O valor de tag é sempre uma cadeia de caracteres, e o número máximo de caracteres do valor da tag é 256.

Para obter mais detalhes sobre como especificar tags em uma instrução, consulte Cotas de tags para objetos e colunas.

COMMENT = 'string_literal'

Adiciona um comentário ou substitui um comentário existente para o estágio.

Parâmetros do estágio externo (externalStageParams)

URL = 'cloud_specific_url'

Se um estágio não tem um URL, ele é um estágio interno

Aviso

A modificação do parâmetro URL de um estágio pode quebrar a seguinte funcionalidade para objetos que dependem do estágio:

  • Objetos de canal que aproveitam as mensagens nas nuvens para acionar carregamentos de dados (ou seja, onde AUTO_INGEST = TRUE).

  • Tabelas externas que aproveitam as mensagens nas nuvens para acionar atualizações de metadados (ou seja, onde AUTO_REFRESH = TRUE).

Amazon S3

URL = 's3://bucket[/path/]'

Modifica o URL para o local externo (bucket S3 existente) usado para armazenar arquivos de dados para carregamento/descarregamento, onde:

  • bucket é o nome do bucket S3.

    Note que buckets S3 em regiões AWS não públicas, tais como regiões governamentais, não são suportados.

  • path é um caminho opcional que distingue letras maiúsculas de minúsculas para arquivos no local de armazenamento em nuvem (ou seja, os arquivos têm nomes que começam com uma cadeia de caracteres comum) que limita o carregamento do conjunto de arquivos. Os caminhos são chamados alternativamente de prefixos ou pastas por diferentes serviços de armazenamento em nuvem.

Google Cloud Storage

URL = 'gcs://bucket[/path/]'

Modifica o URL para o local externo (bucket GCS existente) usado para armazenar arquivos de dados para carregamento/descarregamento, onde:

  • bucket é o nome do bucket GCS.

  • path é um caminho opcional que distingue letras maiúsculas de minúsculas para arquivos no local de armazenamento em nuvem (ou seja, os arquivos têm nomes que começam com uma cadeia de caracteres comum) que limita o carregamento do conjunto de arquivos. Os caminhos são chamados alternativamente de prefixos ou pastas por diferentes serviços de armazenamento em nuvem.

Microsoft Azure

URL = 'azure://account.blob.core.windows.net/container[/path/]'

Modifica o URL para o local externo (contêiner Azure existente) utilizado para armazenar arquivos de dados para carregamento, onde:

  • account é o nome da conta Azure (por exemplo, myaccount). Use o ponto de extremidade blob.core.windows.net para todos os tipos com suporte de contas de armazenamento de blobs Azure, incluindo Data Lake Storage Gen2.

  • container é o nome do contêiner Azure (por exemplo, mycontainer).

  • path é um caminho opcional que distingue letras maiúsculas de minúsculas para arquivos no local de armazenamento em nuvem (ou seja, os arquivos têm nomes que começam com uma cadeia de caracteres comum) que limita o carregamento do conjunto de arquivos. Os caminhos são chamados alternativamente de prefixos ou pastas por diferentes serviços de armazenamento em nuvem.

STORAGE_INTEGRATION = integration_name ou . CREDENTIALS = ( cloud_specific_credentials )

Necessário apenas se o Amazon S3, Google Cloud Storage ou Microsoft Azure for privado; não necessário para buckets/contêineres públicos

Amazon S3

STORAGE_INTEGRATION = integration_name

Especifica o nome da integração de armazenamento utilizada para delegar a responsabilidade de autenticação do armazenamento em nuvem externo a uma entidade de gerenciamento de identidade e acesso (IAM) do Snowflake. Para obter mais detalhes, consulte CREATE STORAGE INTEGRATION.

Nota

Recomendamos fortemente o uso de integrações de armazenamento. Esta opção evita a necessidade de fornecer credenciais de armazenamento em nuvem usando o parâmetro CREDENTIALS ao criar estágios ou carregar dados.

CREDENTIALS = ( AWS_KEY_ID = 'string' AWS_SECRET_KEY = 'string' [ AWS_TOKEN = 'string' ] ) ou . CREDENTIALS = ( AWS_ROLE = 'string' )

Modifica as credenciais de segurança para conexão com AWS e acesso ao bucket privado S3 onde os arquivos de carregamento/descarregamento são preparados. Para obter mais informações, consulte Configuração de acesso seguro ao Amazon S3.

As credenciais especificadas dependerão da associação das permissões de acesso do Snowflake para o bucket com um usuário ou função do AWS IAM (Identity & Access Management):

  • Usuário IAM: as credenciais de IAM são necessárias. As credenciais temporárias (também conhecidas como «com escopo») são geradas por AWS Security Token Service (STS) e consiste em três componentes:

    • AWS_KEY_ID

    • AWS_SECRET_KEY

    • AWS_TOKEN

    Todos os três são obrigatórios para acessar um bucket privado. Após um período designado, as credenciais temporárias expiram e não podem mais ser utilizadas. Você deve então gerar um novo conjunto de credenciais temporárias válidas.

    Importante

    O comando COPY também permite o uso de credenciais permanentes (ou «de longo prazo»); no entanto, por razões de segurança, o Snowflake não recomenda o uso delas. Se você precisar usar credenciais permanentes, o Snowflake recomenda gerar periodicamente novas credenciais permanentes para estágios externos.

  • Função IAM: omitir as credenciais de segurança e chaves de acesso e, em vez disso, identificar a função usando AWS_ROLE e especificar a função AWS ARN (Amazon Resource Name).

    Importante

    A capacidade de usar uma função AWS IAM para acessar um bucket S3 privado para carregar ou descarregar dados está agora obsoleta (ou seja, o suporte será removido em um lançamento futuro, TBD). É altamente recomendável modificar qualquer estágio S3 existente que utilize este recurso para, em vez disso, fazer referência a objetos de integração de armazenamento. Para obter instruções, consulte Opção 1: Configuração de uma integração de armazenamento do Snowflake para acessar o Amazon S3.

Google Cloud Storage

STORAGE_INTEGRATION = integration_name

Especifica o nome da integração de armazenamento utilizada para delegar a responsabilidade de autenticação do armazenamento em nuvem externo a uma entidade de gerenciamento de identidade e acesso (IAM) do Snowflake. Para obter mais detalhes, consulte CREATE STORAGE INTEGRATION.

Microsoft Azure

STORAGE_INTEGRATION = integration_name

Especifica o nome da integração de armazenamento utilizada para delegar a responsabilidade de autenticação do armazenamento em nuvem externo a uma entidade de gerenciamento de identidade e acesso (IAM) do Snowflake. Para obter mais detalhes, consulte CREATE STORAGE INTEGRATION.

Nota

Recomendamos fortemente o uso de integrações de armazenamento. Esta opção evita a necessidade de fornecer credenciais de armazenamento em nuvem usando o parâmetro CREDENTIALS ao criar estágios ou carregar dados.

CREDENTIALS = ( AZURE_SAS_TOKEN = 'string' )

Modifica o token SAS (assinatura de acesso compartilhado) para se conectar ao Azure e acessar o contêiner privado onde os arquivos contendo os dados carregados são preparados. As credenciais são geradas pelo Azure.

ENCRYPTION = ( cloud_specific_encryption )

Necessário apenas para carregamento/descarregamento de arquivos criptografados; não necessário se o local de armazenamento e os arquivos não estiverem criptografados

Carregamento de dados

Modifica as configurações de criptografia usadas para descriptografar os arquivos criptografados no local de armazenamento e extrair dados.

Descarregamento de dados

Modifica as configurações de criptografia usadas para criptografar os arquivos descarregados no local de armazenamento.

Amazon S3

ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] | [ TYPE = 'AWS_SSE_S3' ] | [ TYPE = 'AWS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] | [ TYPE = 'NONE' ] )

TYPE = ...

Especifica o tipo de criptografia utilizado. Os valores possíveis são:

  • AWS_CSE: criptografia do lado do cliente (exige um valor MASTER_KEY). Atualmente, a chave mestra do lado do cliente que você fornece só pode ser uma chave simétrica. Note que, quando um valor MASTER_KEY é fornecido, o Snowflake assume TYPE = AWS_CSE (ou seja, quando um valor MASTER_KEY é fornecido, TYPE não é necessário).

  • AWS_SSE_S3: criptografia do lado do servidor que não exige configurações adicionais de criptografia.

  • AWS_SSE_KMS: criptografia do lado do servidor que aceita um valor opcional KMS_KEY_ID.

Para obter mais informações sobre os tipos de criptografia, consulte a documentação do AWS sobre criptografia do lado do cliente ou criptografia do lado do servidor.

  • NONE: sem criptografia.

MASTER_KEY = 'string' (aplica-se somente à criptografia AWS_CSE)

Especifica a chave mestra do lado do cliente utilizada para criptografar os arquivos no bucket. A chave mestra deve ser uma chave de 128 bits ou 256 bits na forma codificada em Base64.

KMS_KEY_ID = 'string' (aplica-se somente à criptografia AWS_SSE_KMS)

Opcionalmente especifica a ID para a chave AWS gerenciada por KMS usada para criptografar arquivos descarregados no bucket. Se nenhum valor for fornecido, sua ID de chave KMS é usada para criptografar arquivos ao descarregar.

Observe que este valor é ignorado para o carregamento de dados.

Google Cloud Storage

ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' | 'NONE' ] [ KMS_KEY_ID = 'string' ] )

TYPE = ...

Especifica o tipo de criptografia utilizado. Os valores possíveis são:

KMS_KEY_ID = 'string' (aplica-se somente à criptografia GCS_SSE_KMS)

Opcionalmente, especifica a ID da chave gerenciada por KMS da nuvem que é usada para criptografar arquivos descarregados no bucket. Se nenhum valor for fornecido, sua ID de chave padrão KMS definida no bucket é usada para criptografar arquivos ao descarregar.

Observe que este valor é ignorado para o carregamento de dados. A operação de carregamento deve ser bem sucedida se a conta de serviço tiver permissões suficientes para descriptografar os dados no bucket.

Microsoft Azure

ENCRYPTION = ( [ TYPE = 'AZURE_CSE' | 'NONE' ] [ MASTER_KEY = 'string' ] )

TYPE = ...

Especifica o tipo de criptografia utilizado. Os valores possíveis são:

MASTER_KEY = 'string' (aplica-se somente à criptografia AZURE_CSE)

Especifica a chave mestra do lado do cliente usada para criptografar ou descriptografar arquivos. A chave mestra deve ser uma chave de 128 bits ou 256 bits na forma codificada em Base64.

Parâmetros da tabela de diretório

ENABLE = TRUE | FALSE

Especifica se deve ser adicionada uma tabela de diretório ao estágio. Quando o valor é TRUE, uma tabela de diretório é adicionada ao estágio.

Nota

A definição deste parâmetro como TRUE não é suportado para estágios externos compatíveis com S3. Os metadados para estágios externos compatíveis com S3 não podem ser atualizados automaticamente.

Padrão: FALSE

REFRESH

Acessa os arquivos de dados preparados referenciados na definição da tabela de diretório e atualiza os metadados da tabela:

  • Novos arquivos no caminho são adicionados aos metadados da tabela.

  • As mudanças nos arquivos do caminho são atualizadas nos metadados da tabela.

  • Os arquivos que não estão mais no caminho são removidos dos metadados da tabela.

Atualmente, é necessário executar este comando cada vez que arquivos são adicionados ao estágio, atualizados ou descartados. Esta etapa sincroniza os metadados com o último conjunto de arquivos associados na definição do estágio para a tabela de diretório.

SUBPATH = '<relative-path>'

Opcionalmente, especifique um caminho relativo para atualizar os metadados de um subconjunto específico dos arquivos de dados.

Opções de tipo de formato (formatTypeOptions)

Dependendo do tipo de formato de arquivo especificado (FILE_FORMAT = ( TYPE = ... )), você pode incluir uma ou mais das seguintes opções de formato específicas (separadas por espaços em branco, vírgulas ou novas linhas):

TYPE = CSV

COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
Uso

Carregamento de dados, descarregamento de dados e tabelas externas

Definição
  • Ao carregar dados, especifica o algoritmo de compressão atual para o arquivo de dados. O Snowflake usa esta opção para detectar como um arquivo de dados já comprimido foi comprimido para que os dados comprimidos no arquivo possam ser extraídos para carregamento.

  • Ao descarregar os dados, comprime o arquivo de dados usando o algoritmo de compressão especificado.

Valores

Valores suportados

Notas

AUTO

Ao carregar dados, o algoritmo de compressão detectado automaticamente, exceto para arquivos comprimidos com Brotli, que atualmente não podem ser detectados automaticamente. Ao descarregar os dados, os arquivos são automaticamente comprimidos usando o padrão, que é o gzip.

GZIP

BZ2

BROTLI

Deve ser especificado ao carregar/descarregar arquivos comprimidos com Brotli.

ZSTD

Zstandard v0.8 (e superior) é suportado.

DEFLATE

Arquivos compactados Deflate (com cabeçalho zlib, RFC1950).

RAW_DEFLATE

Arquivos compactados Raw Deflate (sem cabeçalho, RFC1951).

NONE

Ao carregar dados, indica que os arquivos não foram comprimidos. Ao descarregar os dados, especifica que os arquivos descarregados não são comprimidos.

Padrão

AUTO

RECORD_DELIMITER = 'character' | NONE
Uso

Carregamento de dados, descarregamento de dados e tabelas externas

Definição

Um ou mais caracteres de byte único ou multibyte que separam registros em um arquivo de entrada (carregamento de dados) ou arquivo não carregado (descarregamento de dados). Aceita sequências de escape comuns ou os seguintes caracteres de byte único ou multibyte:

Caracteres de byte único

Valores octais (com prefixo \\) ou valores hexadecimais (com prefixo 0x ou \x). Por exemplo, para registros delimitados por acento circunflexo (^), especifique o valor octal (\\136) ou hexadecimal (0x5e).

Caracteres multibyte

Valores hexadecimais (com prefixo \x). Por exemplo, para registros delimitados pelo caractere de centavo (¢), especifique o valor hexadecimal (\xC2\xA2).

O delimitador para RECORD_DELIMITER ou FIELD_DELIMITER não pode ser um substrato do delimitador para a outra opção de formato do arquivo (por exemplo, FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb').

O delimitador especificado deve ser um caractere válido UTF-8 e não uma sequência aleatória de bytes. Observe também que o delimitador é limitado a um máximo de 20 caracteres.

Também aceita um valor de NONE.

Padrão
Carregamento de dados

Caractere de nova linha. Note que a “nova linha” é lógica de tal forma que \r\n será entendido como uma nova linha para arquivos em uma plataforma Windows.

Descarregamento de dados

Caractere de nova linha (\n).

FIELD_DELIMITER = 'character' | NONE
Uso

Carregamento de dados, descarregamento de dados e tabelas externas

Definição

Um ou mais caracteres de byte único ou multibyte que separam campos em um arquivo de entrada (carregamento de dados) ou arquivo não carregado (descarregamento de dados). Aceita sequências de escape comuns ou os seguintes caracteres de byte único ou multibyte:

Caracteres de byte único

Valores octais (com prefixo \\) ou valores hexadecimais (com prefixo 0x ou \x). Por exemplo, para registros delimitados por acento circunflexo (^), especifique o valor octal (\\136) ou hexadecimal (0x5e).

Caracteres multibyte

Valores hexadecimais (com prefixo \x). Por exemplo, para registros delimitados pelo caractere de centavo (¢), especifique o valor hexadecimal (\xC2\xA2).

O delimitador para RECORD_DELIMITER ou FIELD_DELIMITER não pode ser um substrato do delimitador para a outra opção de formato do arquivo (por exemplo, FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb').

Nota

Para caracteres não ASCII, você deve usar o valor da sequência de bytes hexadecimais para obter um comportamento determinístico.

O delimitador especificado deve ser um caractere válido UTF-8 e não uma sequência aleatória de bytes. Observe também que o delimitador é limitado a um máximo de 20 caracteres.

Também aceita um valor de NONE.

Padrão

vírgula (,)

FILE_EXTENSION = 'string' | NONE
Uso

Apenas descarregamento de dados

Definição

Especifica a extensão para arquivos descarregados em um estágio. Aceita qualquer extensão. O usuário é responsável por especificar uma extensão de arquivo que possa ser lida por qualquer software ou serviços desejados.

Padrão

nulo, ou seja, a extensão do arquivo é determinada pelo tipo de formato: .csv[compression], em que compression é a extensão adicionada pelo método de compressão, se COMPRESSION estiver definido.

Nota

Se a opção de cópia SINGLE for TRUE, então o comando COPY descarrega um arquivo sem uma extensão de arquivo por padrão. Para especificar uma extensão de arquivo, forneça um nome de arquivo e uma extensão no caminho internal_location ou external_location (por exemplo, copy into @stage/data.csv).

PARSE_HEADER = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se deve usar os cabeçalhos da primeira linha nos arquivos de dados para determinar os nomes das colunas.

Esta opção de formato de arquivo é aplicada apenas às seguintes ações:

  • Detecção automática de definições de coluna usando a função INFER_SCHEMA.

  • Carregamento de dados CSV em colunas separadas usando a função INFER_SCHEMA e a opção de cópia MATCH_BY_COLUMN_NAME.

Se a opção estiver definida como TRUE, os cabeçalhos da primeira linha serão usados para determinar os nomes das colunas. O valor padrão FALSE retornará os nomes das colunas como c , onde é a posição da coluna.

Observe que a opção SKIP_HEADER não é suportada com PARSE_HEADER = TRUE.

Padrão: FALSE

SKIP_HEADER = integer
Uso

Carregamento de dados e tabelas externas

Definição

Número de linhas no início do arquivo a ser pulado.

Observe que SKIP_HEADER não usa os valores RECORD_DELIMITER ou FIELD_DELIMITER para determinar o que é uma linha de cabeçalho; em vez disso, simplesmente ignora o número especificado de linhas delimitadas de CRLF (Carriage Return, Line Feed) no arquivo. RECORD_DELIMITER e FIELD_DELIMITER são então usados para determinar as linhas de dados a serem carregadas.

Padrão

0

SKIP_BLANK_LINES = TRUE | FALSE
Uso

Carregamento de dados e tabelas externas

Definição

Booleano que especifica ignorar quaisquer linhas em branco encontradas nos arquivos de dados; caso contrário, linhas em branco produzem um erro de fim de registro (comportamento padrão).

Padrão: FALSE

DATE_FORMAT = 'string' | AUTO
Uso

Carregamento e descarregamento de dados

Definição

Define o formato dos valores das datas nos arquivos de dados (carregamento de dados) ou tabela (descarregamento de dados). Se um valor não estiver especificado ou for AUTO, é usado o valor para o parâmetro DATE_INPUT_FORMAT (carregamento de dados) ou DATE_OUTPUT_FORMAT (descarregamento de dados).

Padrão

AUTO

TIME_FORMAT = 'string' | AUTO
Uso

Carregamento e descarregamento de dados

Definição

Define o formato dos valores de hora nos arquivos de dados (carregamento de dados) ou tabela (descarregamento de dados). Se um valor não estiver especificado ou for AUTO, é usado o valor para o parâmetro TIME_INPUT_FORMAT (carregamento de dados) ou TIME_OUTPUT_FORMAT (descarregamento de dados).

Padrão

AUTO

TIMESTAMP_FORMAT = string' | AUTO
Uso

Carregamento e descarregamento de dados

Definição

Define o formato dos valores ds carimbo de data/hora nos arquivos de dados (carregamento de dados) ou tabela (descarregamento de dados). Se um valor não estiver especificado ou for AUTO, é usado o valor para o parâmetro TIMESTAMP_INPUT_FORMAT (carregamento de dados) ou TIMESTAMP_OUTPUT_FORMAT (descarregamento de dados).

Padrão

AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8
Uso

Carregamento e descarregamento de dados

Definição

Define o formato de codificação para entrada ou saída binária. A opção pode ser usada ao carregar ou descarregar dados de colunas binárias em uma tabela.

Padrão

HEX

ESCAPE = 'character' | NONE
Uso

Carregamento e descarregamento de dados

Definição

Uma cadeia de caracteres de caractere de byte único usada como caractere de escape para valores de campo delimitados ou não delimitados. Um caractere de escape invoca uma interpretação alternativa em caracteres subsequentes em uma sequência de caracteres. Você pode usar o caractere ESCAPE para interpretar instâncias do caractere FIELD_OPTIONALLY_ENCLOSED_BY nos dados como literais.

Aceita sequências de escape comuns, valores octais ou valores hexadecimais.

Carregamento de dados

Especifica o caractere de escape somente para campos delimitados. Especifique o caractere usado para delimitar os campos definindo FIELD_OPTIONALLY_ENCLOSED_BY.

Nota

Esta opção de formato de arquivo oferece suporte somente a caracteres de byte único. Observe que a codificação de caractere UTF-8 representa caracteres ASCII de ordem superior como caracteres multibyte. Se seu arquivo de dados for codificado com o conjunto de caracteres UTF-8, você não poderá especificar um caractere ASCII de ordem superior como o valor da opção.

Além disso, se você especificar um caractere ASCII de ordem superior, recomendamos que você defina a opção de formato de arquivo ENCODING = 'string' como a codificação de caracteres para seus arquivos de dados para garantir que o caractere seja interpretado corretamente.

Descarregamento de dados

Se esta opção for definida, ela substitui o conjunto de caracteres de escape para ESCAPE_UNENCLOSED_FIELD.

Padrão

NONE

ESCAPE_UNENCLOSED_FIELD = 'character' | NONE
Uso

Carregamento de dados, descarregamento de dados e tabelas externas

Definição

Uma cadeia de caracteres de caractere de byte único usada como caractere de escape apenas para valores de campo não delimitados. Um caractere de escape invoca uma interpretação alternativa em caracteres subsequentes em uma sequência de caracteres. Você pode usar o caractere ESCAPE para interpretar instâncias dos caracteres FIELD_DELIMITER ou RECORD_DELIMITER nos dados como literais. O caractere de escape também pode ser usado para escapar de instâncias de si mesmo nos dados.

Aceita sequências de escape comuns, valores octais ou valores hexadecimais.

Carregamento de dados

Especifica o caractere de escape somente para campos não delimitados.

Nota

  • O valor padrão é \\. Se uma linha em um arquivo de dados terminar no caractere de barra invertida (\), este caractere escapa do caractere de linha nova ou de retorno de carro especificado para a opção de formato do arquivo RECORD_DELIMITER. Como resultado, a operação de carregamento trata esta linha e a próxima linha como uma única linha de dados. Para evitar este problema, defina o valor como NONE.

  • Esta opção de formato de arquivo oferece suporte somente a caracteres de byte único. Observe que a codificação de caractere UTF-8 representa caracteres ASCII de ordem superior como caracteres multibyte. Se seu arquivo de dados for codificado com o conjunto de caracteres UTF-8, você não poderá especificar um caractere ASCII de ordem superior como o valor da opção.

    Além disso, se você especificar um caractere ASCII de ordem superior, recomendamos que você defina a opção de formato de arquivo ENCODING = 'string' como a codificação de caracteres para seus arquivos de dados para garantir que o caractere seja interpretado corretamente.

Descarregamento de dados

Se ESCAPE estiver definido, o conjunto de caracteres de escape para aquela opção de formato de arquivo substitui esta opção.

Padrão

barra invertida (\\)

TRIM_SPACE = TRUE | FALSE
Uso

Carregamento de dados e tabelas externas

Definição

Booleano que especifica se é necessário remover o espaço em branco dos campos.

Por exemplo, se seu software de banco de dados externo delimita os campos com aspas, mas insere um espaço à esquerda, o Snowflake lê o espaço à esquerda em vez do caractere de abertura de aspas como o início do campo (ou seja, as aspas são interpretadas como parte da cadeia de caracteres de dados do campo). Defina esta opção como TRUE para remover espaços indesejáveis durante o carregamento de dados.

Como outro exemplo, se os espaços no início e no final das aspas que delimitam as cadeias de caracteres, você pode remover esses espaços usando esta opção e o caractere de aspas usando a opção FIELD_OPTIONALLY_ENCLOSED_BY. Note que quaisquer espaços entre as aspas são preservados. Por exemplo, considerando FIELD_DELIMITER = '|' e FIELD_OPTIONALLY_ENCLOSED_BY = '"':

|"Hello world"|    /* loads as */  >Hello world<
|" Hello world "|  /* loads as */  > Hello world <
| "Hello world" |  /* loads as */  >Hello world<
Copy

(os parênteses neste exemplo não são carregados; eles são usados para demarcar o início e o fim das cadeias de caracteres carregadas)

Padrão

FALSE

FIELD_OPTIONALLY_ENCLOSED_BY = 'character' | NONE
Uso

Carregamento de dados, descarregamento de dados e tabelas externas

Definição

Caractere usado para delimitar as cadeias de caracteres. O valor pode ser NONE, caractere de aspas simples (') ou caractere de aspas duplas ("). Para usar o caractere de aspas simples, use a representação octal ou hexadecimal (0x27) ou o escape de aspas simples dupla ('').

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 "B" C, aplique o escape das aspas duplas como segue:

A ""B"" C

Padrão

NONE

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

Carregamento de dados, descarregamento de dados e tabelas externas

Definição

Cadeia de caracteres usada para converter de e para SQL NULL:

  • Ao carregar dados, o Snowflake substitui estes valores na fonte de carregamento de dados por SQL NULL. Para especificar mais de uma cadeia de caracteres, coloque a lista de cadeias de caracteres entre parênteses e use vírgulas para separar cada valor.

    Observe que o Snowflake converte todas as instâncias do valor em NULL, independentemente do tipo de dados. Por exemplo, se 2 for especificado como um valor, todas as instâncias de 2 como uma cadeia de caracteres ou número são convertidas.

    Por exemplo:

    NULL_IF = ('\\N', 'NULL', 'NUL', '')

    Observe que esta opção pode incluir cadeias de caracteres vazias.

  • Ao descarregar dados, o Snowflake converte os valores SQL NULL para o primeiro valor da lista.

Padrão

\\N (ou seja, NULL, que considera que o valor ESCAPE_UNENCLOSED_FIELD é \\)

ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se deve gerar um erro de análise se o número de colunas delimitadas (isto é, campos) em um arquivo de entrada não corresponder ao número de colunas na tabela correspondente.

Se definido como FALSE, um erro não é gerado e o carregamento continua. Se o arquivo for carregado com sucesso:

  • Se o arquivo de entrada tiver registros com mais campos do que colunas na tabela, os campos correspondentes serão carregados em ordem de ocorrência no arquivo e os campos restantes não serão carregados.

  • Se o arquivo de entrada tiver registros com menos campos do que colunas na tabela, as colunas não correspondentes na tabela são carregadas com valores NULL.

Esta opção considera que todos os registros dentro do arquivo de entrada têm o mesmo comprimento (ou seja, um arquivo contendo registros de comprimento variável retorna um erro independentemente do valor especificado para este parâmetro).

Padrão

TRUE

Nota

Ao transformar dados durante o carregamento (isto é, usando uma consulta como fonte do comando COPY), esta opção é ignorada. Não há exigência de que seus arquivos de dados tenham o mesmo número e ordenação de colunas que sua tabela de destino.

REPLACE_INVALID_CHARACTERS = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode ().

Se definido como TRUE, o Snowflake substitui os caracteres inválidos UTF-8 pelo caractere de substituição Unicode.

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão

FALSE

EMPTY_FIELD_AS_NULL = TRUE | FALSE
Uso

Carregamento de dados, descarregamento de dados e tabelas externas

Definição
  • Ao carregar dados, especifica se deve inserir SQL NULL para campos vazios em um arquivo de entrada, que são representados por dois delimitadores sucessivos (por exemplo, ,,).

    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 STRING. Para outros tipos de colunas, o comando COPY produz um erro.

  • Ao descarregar os dados, esta opção é utilizada em combinação com FIELD_OPTIONALLY_ENCLOSED_BY. Quando FIELD_OPTIONALLY_ENCLOSED_BY = NONE, a definição de EMPTY_FIELD_AS_NULL = FALSE especifica para descarregar cadeias de caracteres vazias em tabelas para valores de cadeias de caracteres vazias sem aspas delimitando os valores de campo.

    Se definido como TRUE, FIELD_OPTIONALLY_ENCLOSED_BY deve especificar um caractere para delimitar cadeias de caracteres.

Padrão

TRUE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se deve ignorar o BOM (marca de ordem de byte), se presente em um arquivo de dados. Um BOM é um código de caracteres no início de um arquivo de dados que define a ordem de bytes e a forma de codificação.

Se definido como FALSE, o Snowflake reconhece qualquer BOM nos arquivos de dados, o que poderia resultar no BOM causando um erro ou sendo fundido na primeira coluna da tabela.

Padrão

TRUE

ENCODING = 'string'
Uso

Carregamento de dados e tabelas externas

Definição

Cadeia de caracteres (constante) que especifica o conjunto de caracteres dos dados de origem ao carregar dados em uma tabela.

Conjunto de caracteres

Valor ENCODING 

Linguagens suportadas

Notas

Big5

BIG5

Chinês Tradicional

EUC-JP

EUCJP

Japonês

EUC-KR

EUCKR

Coreano

GB18030

GB18030

Chinês

IBM420

IBM420

Árabe

IBM424

IBM424

Hebraico

IBM949

IBM949

Coreano

ISO-2022-CN

ISO2022CN

Chinês simplificado

ISO-2022-JP

ISO2022JP

Japonês

ISO-2022-KR

ISO2022KR

Coreano

ISO-8859-1

ISO88591

Alemão, Dinamarquês, Espanhol, Francês, Holandês, Inglês, Italiano, Norueguês, Português, Sueco

ISO-8859-2

ISO88592

Tcheco, Húngaro, Polonês, Romeno

ISO-8859-5

ISO88595

Russo

ISO-8859-6

ISO88596

Árabe

ISO-8859-7

ISO88597

Grego

ISO-8859-8

ISO88598

Hebraico

ISO-8859-9

ISO88599

Turco

ISO-8859-15

ISO885915

Alemão, Dinamarquês, Espanhol, Francês, Holandês, Inglês, Italiano, Norueguês, Português, Sueco

Idêntico a ISO-8859-1 exceto para 8 caracteres, incluindo o símbolo da moeda Euro.

KOI8-R

KOI8R

Russo

Shift_JIS

SHIFTJIS

Japonês

UTF-8

UTF8

Todos os idiomas

Para carregar dados de arquivos delimitados (CSV, TSV etc.), UTF-8 é o padrão. . . Para carregar dados de todos os outros formatos de arquivo suportados (JSON, Avro etc.), bem como descarregar dados, o UTF-8 é o único conjunto de caracteres suportado.

UTF-16

UTF16

Todos os idiomas

UTF-16BE

UTF16BE

Todos os idiomas

UTF-16LE

UTF16LE

Todos os idiomas

UTF-32

UTF32

Todos os idiomas

UTF-32BE

UTF32BE

Todos os idiomas

UTF-32LE

UTF32LE

Todos os idiomas

windows-949

WINDOWS949

Coreano

windows-1250

WINDOWS1250

Tcheco, Húngaro, Polonês, Romeno

windows-1251

WINDOWS1251

Russo

windows-1252

WINDOWS1252

Alemão, Dinamarquês, Espanhol, Francês, Holandês, Inglês, Italiano, Norueguês, Português, Sueco

windows-1253

WINDOWS1253

Grego

windows-1254

WINDOWS1254

Turco

windows-1255

WINDOWS1255

Hebraico

windows-1256

WINDOWS1256

Árabe

Padrão

UTF8

Nota

O Snowflake armazena todos os dados internamente no conjunto de caracteres UTF-8. Os dados são convertidos em UTF-8 antes de serem carregados no Snowflake.

TYPE = JSON

COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
Uso

Carregamento de dados e tabelas externas

Definição
  • Ao carregar dados, especifica o algoritmo de compressão atual para o arquivo de dados. O Snowflake usa esta opção para detectar como um arquivo de dados já comprimido foi comprimido para que os dados comprimidos no arquivo possam ser extraídos para carregamento.

  • Ao descarregar os dados, comprime o arquivo de dados usando o algoritmo de compressão especificado.

Valores

Valores suportados

Notas

AUTO

Ao carregar dados, o algoritmo de compressão detectado automaticamente, exceto para arquivos comprimidos com Brotli, que atualmente não podem ser detectados automaticamente. Ao descarregar os dados, os arquivos são automaticamente comprimidos usando o padrão, que é o gzip.

GZIP

BZ2

BROTLI

Deve ser especificado se carregar/descarregar arquivos comprimidos com Brotli.

ZSTD

Zstandard v0.8 (e superior) é suportado.

DEFLATE

Arquivos compactados Deflate (com cabeçalho zlib, RFC1950).

RAW_DEFLATE

Arquivos compactados Raw Deflate (sem cabeçalho, RFC1951).

NONE

Ao carregar dados, indica que os arquivos não foram comprimidos. Ao descarregar os dados, especifica que os arquivos descarregados não são comprimidos.

Padrão

AUTO

DATE_FORMAT = 'string' | AUTO
Uso

Somente carregamento de dados

Definição

Define o formato dos valores da cadeia de caracteres de data nos arquivos de dados. Se um valor não for especificado ou for AUTO, é usado o valor para o parâmetro DATE_INPUT_FORMAT.

Esta opção de formato de arquivo é aplicada apenas às seguintes ações:

  • Carregamento de dados JSON em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

  • Carregamento de dados JSON em colunas separadas especificando uma consulta na instrução COPY (isto é, transformação COPY).

Padrão

AUTO

TIME_FORMAT = 'string' | AUTO
Uso

Somente carregamento de dados

Definição

Define o formato dos valores da cadeia de caracteres de hora nos arquivos de dados. Se um valor não for especificado ou for AUTO, é usado o valor para o parâmetro TIME_INPUT_FORMAT.

Esta opção de formato de arquivo é aplicada apenas às seguintes ações:

  • Carregamento de dados JSON em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

  • Carregamento de dados JSON em colunas separadas especificando uma consulta na instrução COPY (isto é, transformação COPY).

Padrão

AUTO

TIMESTAMP_FORMAT = string' | AUTO
Uso

Somente carregamento de dados

Definição

Define o formato dos valores da cadeia de caracteres de carimbo de data/hora nos arquivos de dados. Se um valor não for especificado ou for AUTO, é usado o valor para o parâmetro TIMESTAMP_INPUT_FORMAT.

Esta opção de formato de arquivo é aplicada apenas às seguintes ações:

  • Carregamento de dados JSON em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

  • Carregamento de dados JSON em colunas separadas especificando uma consulta na instrução COPY (isto é, transformação COPY).

Padrão

AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8
Uso

Somente carregamento de dados

Definição

Define o formato de codificação dos valores binários da cadeia de caracteres nos arquivos de dados. A opção pode ser usada no carregamento de dados em colunas binárias em uma tabela.

Esta opção de formato de arquivo é aplicada apenas às seguintes ações:

  • Carregamento de dados JSON em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

  • Carregamento de dados JSON em colunas separadas especificando uma consulta na instrução COPY (isto é, transformação COPY).

Padrão

HEX

TRIM_SPACE = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se é necessário remover o espaço no início e no final das cadeias de caracteres.

Por exemplo, se seu software de banco de dados externo delimita os campos com aspas, mas insere um espaço à esquerda, o Snowflake lê o espaço à esquerda em vez do caractere de abertura de aspas como o início do campo (ou seja, as aspas são interpretadas como parte da cadeia de caracteres de dados do campo). Defina esta opção como TRUE para remover espaços indesejáveis durante o carregamento de dados.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar dados JSON em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Padrão

FALSE

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

Somente carregamento de dados

Definição

String usada para converter de e para SQL NULL. O Snowflake substitui estas cadeias de caracteres na origem do carregamento de dados por SQL NULL. Para especificar mais de uma cadeia de caracteres, coloque a lista de cadeias de caracteres entre parênteses e use vírgulas para separar cada valor.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar dados JSON em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Observe que o Snowflake converte todas as instâncias do valor em NULL, independentemente do tipo de dados. Por exemplo, se 2 for especificado como um valor, todas as instâncias de 2 como uma cadeia de caracteres ou número são convertidas.

Por exemplo:

NULL_IF = ('\\N', 'NULL', 'NUL', '')

Observe que esta opção pode incluir cadeias de caracteres vazias.

Padrão

\\N (ou seja, NULL, que considera que o valor ESCAPE_UNENCLOSED_FIELD é \\)

FILE_EXTENSION = 'string' | NONE
Uso

Apenas descarregamento de dados

Definição

Especifica a extensão para arquivos descarregados em um estágio. Aceita qualquer extensão. O usuário é responsável por especificar uma extensão de arquivo que possa ser lida por qualquer software ou serviços desejados.

Padrão

nulo, ou seja, a extensão do arquivo é determinada pelo tipo de formato: .json[compression], em que compression é a extensão adicionada pelo método de compressão, se COMPRESSION estiver definido.

ENABLE_OCTAL = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que permite a análise dos números octais.

Padrão

FALSE

ALLOW_DUPLICATE = TRUE | FALSE
Uso

Carregamento de dados e tabelas externas

Definição

Booleano que especifica permitir a duplicação de nomes de campos de objetos (somente o último será preservado).

Padrão

FALSE

STRIP_OUTER_ARRAY = TRUE | FALSE
Uso

Carregamento de dados e tabelas externas

Definição

Booleano que instrui o analisador JSON a remover parênteses externos (ou seja, [ ]).

Padrão

FALSE

STRIP_NULL_VALUES = TRUE | FALSE
Uso

Carregamento de dados e tabelas externas

Definição

Booleano que instrui o analisador JSON a remover campos de objetos ou elementos de matriz contendo valores null. Por exemplo, quando definido como TRUE:

Antes

Depois

[null]

[]

[null,null,3]

[,,3]

{"a":null,"b":null,"c":123}

{"c":123}

{"a":[1,null,2],"b":{"x":null,"y":88}}

{"a":[1,,2],"b":{"y":88}}

Padrão

FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE
Uso

Carregamento de dados e tabela externa

Definição

Booleano que especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (). Esta opção realiza uma substituição de caracteres um a um.

Valores

Se definido como TRUE, o Snowflake substitui os caracteres inválidos UTF-8 pelo caractere de substituição Unicode.

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão

FALSE

IGNORE_UTF8_ERRORS = TRUE | FALSE
Uso

Carregamento de dados e tabela externa

Definição

Booleano que especifica se os erros da codificação UTF-8 produzem condições de erro. É uma sintaxe alternativa para REPLACE_INVALID_CHARACTERS.

Valores

Se definido como TRUE, qualquer sequência inválida UTF-8 é silenciosamente substituída pelo caractere Unicode U+FFFD (ou seja, “caractere de substituição”).

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão

FALSE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se deve ignorar o BOM (marca de ordem de byte), se presente em um arquivo de dados. Um BOM é um código de caracteres no início de um arquivo de dados que define a ordem de bytes e a forma de codificação.

Se definido como FALSE, o Snowflake reconhece qualquer BOM nos arquivos de dados, o que poderia resultar no BOM causando um erro ou sendo fundido na primeira coluna da tabela.

Padrão

TRUE

TYPE = AVRO

COMPRESSION = AUTO | GZIP | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
Uso

Somente carregamento de dados

Definição
  • Ao carregar dados, especifica o algoritmo de compressão atual para o arquivo de dados. O Snowflake usa esta opção para detectar como um arquivo de dados já comprimido foi comprimido para que os dados comprimidos no arquivo possam ser extraídos para carregamento.

  • Ao descarregar os dados, comprime o arquivo de dados usando o algoritmo de compressão especificado.

Valores

Valores suportados

Notas

AUTO

Ao carregar dados, o algoritmo de compressão detectado automaticamente, exceto para arquivos comprimidos com Brotli, que atualmente não podem ser detectados automaticamente. Ao descarregar os dados, os arquivos são automaticamente comprimidos usando o padrão, que é o gzip.

GZIP

BROTLI

Deve ser especificado se carregar/descarregar arquivos comprimidos com Brotli.

ZSTD

Zstandard v0.8 (e superior) é suportado.

DEFLATE

Arquivos compactados Deflate (com cabeçalho zlib, RFC1950).

RAW_DEFLATE

Arquivos compactados Raw Deflate (sem cabeçalho, RFC1951).

NONE

Ao carregar dados, indica que os arquivos não foram comprimidos. Ao descarregar os dados, especifica que os arquivos descarregados não são comprimidos.

Padrão

AUTO.

Nota

Recomendamos que você use a opção padrão AUTO porque ela determinará a compactação do arquivo e do codec. A especificação de uma opção de compactação refere-se à compactação de arquivos, não à compactação de blocos (codecs).

TRIM_SPACE = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se é necessário remover o espaço no início e no final das cadeias de caracteres.

Por exemplo, se seu software de banco de dados externo delimita os campos com aspas, mas insere um espaço à esquerda, o Snowflake lê o espaço à esquerda em vez do caractere de abertura de aspas como o início do campo (ou seja, as aspas são interpretadas como parte da cadeia de caracteres de dados do campo). Defina esta opção como TRUE para remover espaços indesejáveis durante o carregamento de dados.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar dados Avro em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Padrão

FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE
Uso

Carregamento de dados e tabela externa

Definição

Booleano que especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (). Esta opção realiza uma substituição de caracteres um a um.

Valores

Se definido como TRUE, o Snowflake substitui os caracteres inválidos UTF-8 pelo caractere de substituição Unicode.

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão

FALSE

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

Somente carregamento de dados

Definição

String usada para converter de e para SQL NULL. O Snowflake substitui estas cadeias de caracteres na origem do carregamento de dados por SQL NULL. Para especificar mais de uma cadeia de caracteres, coloque a lista de cadeias de caracteres entre parênteses e use vírgulas para separar cada valor.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar dados Avro em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Observe que o Snowflake converte todas as instâncias do valor em NULL, independentemente do tipo de dados. Por exemplo, se 2 for especificado como um valor, todas as instâncias de 2 como uma cadeia de caracteres ou número são convertidas.

Por exemplo:

NULL_IF = ('\\N', 'NULL', 'NUL', '')

Observe que esta opção pode incluir cadeias de caracteres vazias.

Padrão

\\N (ou seja, NULL, que considera que o valor ESCAPE_UNENCLOSED_FIELD é \\)

TYPE = ORC

TRIM_SPACE = TRUE | FALSE
Uso

Carregamento de dados e tabelas externas

Definição

Booleano que especifica se é necessário remover o espaço no início e no final das cadeias de caracteres.

Por exemplo, se seu software de banco de dados externo delimita os campos com aspas, mas insere um espaço à esquerda, o Snowflake lê o espaço à esquerda em vez do caractere de abertura de aspas como o início do campo (ou seja, as aspas são interpretadas como parte da cadeia de caracteres de dados do campo). Defina esta opção como TRUE para remover espaços indesejáveis durante o carregamento de dados.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar dados Orc em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Padrão

FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE
Uso

Carregamento de dados e tabela externa

Definição

Booleano que especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (). Esta opção realiza uma substituição de caracteres um a um.

Valores

Se definido como TRUE, o Snowflake substitui os caracteres inválidos UTF-8 pelo caractere de substituição Unicode.

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão

FALSE

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

Carregamento de dados e tabelas externas

Definição

String usada para converter de e para SQL NULL. O Snowflake substitui estas cadeias de caracteres na origem do carregamento de dados por SQL NULL. Para especificar mais de uma cadeia de caracteres, coloque a lista de cadeias de caracteres entre parênteses e use vírgulas para separar cada valor.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar dados Orc em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Observe que o Snowflake converte todas as instâncias do valor em NULL, independentemente do tipo de dados. Por exemplo, se 2 for especificado como um valor, todas as instâncias de 2 como uma cadeia de caracteres ou número são convertidas.

Por exemplo:

NULL_IF = ('\\N', 'NULL', 'NUL', '')

Observe que esta opção pode incluir cadeias de caracteres vazias.

Padrão

\\N (ou seja, NULL, que considera que o valor ESCAPE_UNENCLOSED_FIELD é \\)

TYPE = PARQUET

COMPRESSION = AUTO | LZO | SNAPPY | NONE
Uso

Carregamento de dados, descarregamento de dados e tabelas externas

Definição

  • Ao carregar dados, especifica o algoritmo de compressão atual para as colunas nos arquivos Parquet.

  • Ao descarregar os dados, comprime o arquivo de dados usando o algoritmo de compressão especificado.

Valores

Valores suportados

Notas

AUTO

Ao carregar dados, o algoritmo de compressão é detectado automaticamente. Oferece suporte aos seguintes algoritmos de compressão: Brotli, gzip, Lempel-Ziv-Oberhumer (LZO), LZ4, Snappy ou Zstandard v0.8 (e superior). . Ao descarregar dados, os arquivos descarregados são comprimidos por padrão usando o algoritmo de compressão Snappy.

LZO

Ao descarregar os dados, os arquivos são comprimidos usando o algoritmo Snappy por padrão. Se o descarregamento de dados for feito para arquivos comprimidos por LZO, especifique este valor.

SNAPPY

Ao descarregar os dados, os arquivos são comprimidos usando o algoritmo Snappy por padrão. Opcionalmente, você pode especificar este valor.

NONE

Ao carregar dados, indica que os arquivos não foram comprimidos. Ao descarregar os dados, especifica que os arquivos descarregados não são comprimidos.

Padrão

AUTO

SNAPPY_COMPRESSION = TRUE | FALSE
Uso

Apenas descarregamento de dados

Valores suportados

Notas

AUTO

Os arquivos descarregados são comprimidos usando o algoritmo de compressão Snappy por padrão.

SNAPPY

Pode ser especificado se for descarregamento de arquivos comprimidos com Snappy.

NONE

Ao carregar dados, indica que os arquivos não foram comprimidos. Ao descarregar os dados, especifica que os arquivos descarregados não são comprimidos.

Definição

Booleano que especifica se o(s) arquivo(s) descarregado(s) é(são) comprimido(s) usando o algoritmo SNAPPY.

Nota

Obsoleto. Em vez disso, use COMPRESSION = SNAPPY.

Limitações

Só é suportado para operações de descarregamento de dados.

Padrão

TRUE

BINARY_AS_TEXT = TRUE | FALSE
Uso

Carregamento de dados e tabelas externas

Definição

Booleano que especifica se deve interpretar colunas sem tipo de dados lógicos definidos como texto UTF-8. Quando definido como FALSE, o Snowflake interpreta estas colunas como dados binários.

Padrão

TRUE

Nota

Snowflake recomenda que você defina BINARY_AS_TEXT como FALSE para evitar possíveis problemas de conversão.

TRIM_SPACE = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se é necessário remover o espaço no início e no final das cadeias de caracteres.

Por exemplo, se seu software de banco de dados externo delimita os campos com aspas, mas insere um espaço à esquerda, o Snowflake lê o espaço à esquerda em vez do caractere de abertura de aspas como o início do campo (ou seja, as aspas são interpretadas como parte da cadeia de caracteres de dados do campo). Defina esta opção como TRUE para remover espaços indesejáveis durante o carregamento de dados.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar os dados do Parquet em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Padrão

FALSE

USE_LOGICAL_TYPE = TRUE | FALSE
Uso

Carregamento de dados, consulta de dados em arquivos preparados e detecção de esquema.

Definição

Booleano que especifica se devem ser usados tipos lógicos Parquet. Com esta opção de formato de arquivo, Snowflake pode interpretar tipos lógicos Parquet durante o carregamento de dados. Para obter mais informações, consulte Definições do tipo lógico Parquet. Para ativar os tipos lógicos Parquet, defina USE_LOGICAL_TYPE como TRUE ao criar uma nova opção de formato de arquivo.

Limitações

Não há suporte para descarregamento de dados.

REPLACE_INVALID_CHARACTERS = TRUE | FALSE
Uso

Carregamento de dados e tabela externa

Definição

Booleano que especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (). Esta opção realiza uma substituição de caracteres um a um.

Valores

Se definido como TRUE, o Snowflake substitui os caracteres inválidos UTF-8 pelo caractere de substituição Unicode.

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão

FALSE

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

Somente carregamento de dados

Definição

String usada para converter de e para SQL NULL. O Snowflake substitui estas cadeias de caracteres na origem do carregamento de dados por SQL NULL. Para especificar mais de uma cadeia de caracteres, coloque a lista de cadeias de caracteres entre parênteses e use vírgulas para separar cada valor.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar os dados do Parquet em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Observe que o Snowflake converte todas as instâncias do valor em NULL, independentemente do tipo de dados. Por exemplo, se 2 for especificado como um valor, todas as instâncias de 2 como uma cadeia de caracteres ou número são convertidas.

Por exemplo:

NULL_IF = ('\\N', 'NULL', 'NUL', '')

Observe que esta opção pode incluir cadeias de caracteres vazias.

Padrão

\\N (ou seja, NULL, que considera que o valor ESCAPE_UNENCLOSED_FIELD é \\)

TYPE = XML

COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
Uso

Somente carregamento de dados

Definição
  • Ao carregar dados, especifica o algoritmo de compressão atual para o arquivo de dados. O Snowflake usa esta opção para detectar como um arquivo de dados já comprimido foi comprimido para que os dados comprimidos no arquivo possam ser extraídos para carregamento.

  • Ao descarregar os dados, comprime o arquivo de dados usando o algoritmo de compressão especificado.

Valores

Valores suportados

Notas

AUTO

Ao carregar dados, o algoritmo de compressão detectado automaticamente, exceto para arquivos comprimidos com Brotli, que atualmente não podem ser detectados automaticamente. Ao descarregar os dados, os arquivos são automaticamente comprimidos usando o padrão, que é o gzip.

GZIP

BZ2

BROTLI

Deve ser especificado se carregar/descarregar arquivos comprimidos com Brotli.

ZSTD

Zstandard v0.8 (e superior) é suportado.

DEFLATE

Arquivos compactados Deflate (com cabeçalho zlib, RFC1950).

RAW_DEFLATE

Arquivos compactados Raw Deflate (sem cabeçalho, RFC1951).

NONE

Ao carregar dados, indica que os arquivos não foram comprimidos. Ao descarregar os dados, especifica que os arquivos descarregados não são comprimidos.

Padrão

AUTO

IGNORE_UTF8_ERRORS = TRUE | FALSE
Uso

Carregamento de dados e tabela externa

Definição

Booleano que especifica se os erros da codificação UTF-8 produzem condições de erro. É uma sintaxe alternativa para REPLACE_INVALID_CHARACTERS.

Valores

Se definido como TRUE, qualquer sequência inválida UTF-8 é silenciosamente substituída pelo caractere Unicode U+FFFD (ou seja, “caractere de substituição”).

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão

FALSE

PRESERVE_SPACE = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se o analisador XML preserva espaços no início e no final no conteúdo de elementos.

Padrão

FALSE

STRIP_OUTER_ELEMENT = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se o analisador XML retira o elemento XML externo, expondo elementos de segundo nível como documentos separados.

Padrão

FALSE

DISABLE_SNOWFLAKE_DATA = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se o analisador XML desabilita o reconhecimento das tags de dados semiestruturados do Snowflake.

Padrão

FALSE

DISABLE_AUTO_CONVERT = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se o analisador XML desativa a conversão automática de valores numéricos e booleanos de texto para representação nativa.

Padrão

FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE
Uso

Carregamento de dados e tabela externa

Definição

Booleano que especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (). Esta opção realiza uma substituição de caracteres um a um.

Valores

Se definido como TRUE, o Snowflake substitui os caracteres inválidos UTF-8 pelo caractere de substituição Unicode.

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão

FALSE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se deve ignorar qualquer BOM (marca de ordem de byte) presente em um arquivo de entrada. Um BOM é um código de caracteres no início de um arquivo de dados que define a ordem de bytes e a forma de codificação.

Se definido como FALSE, o Snowflake reconhece qualquer BOM nos arquivos de dados, o que poderia resultar no BOM causando um erro ou sendo fundido na primeira coluna da tabela.

Padrão

TRUE

Opções de cópia (copyOptions)

Você pode especificar uma ou mais das seguintes opções de cópia (separadas por espaços em branco, vírgulas ou novas linhas):

ON_ERROR = CONTINUE | SKIP_FILE | SKIP_FILE_num | 'SKIP_FILE_num%' | ABORT_STATEMENT
Uso

Somente carregamento de dados

Definição

Cadeia de caracteres (constante) que especifica o tratamento do erro para a operação de carga.

Importante

Considere cuidadosamente o valor da opção de cópia ON_ERROR. O valor padrão é adequado em cenários comuns, mas nem sempre é a melhor opção.

Valores
  • CONTINUE

    Continuar a carregar o arquivo se forem encontrados erros. A instrução COPY retorna uma mensagem de erro para um máximo de um erro encontrado por arquivo de dados.

    Observe que a diferença entre os valores das colunas ROWS_PARSED e ROWS_LOADED representa o número de linhas que incluem os erros detectados. No entanto, cada uma dessas linhas poderia incluir vários erros. Para visualizar todos os erros nos arquivos de dados, use o parâmetro VALIDATION_MODE ou consulte a função VALIDATE.

  • SKIP_FILE

    Ignorar um arquivo quando for encontrado um erro.

    Observe que a ação SKIP_FILE armazena em buffer o arquivo inteiro, quer sejam ou não encontrados erros. Por este motivo, SKIP_FILE é mais lento que CONTINUE ou ABORT_STATEMENT. Ignorar arquivos grandes devido a um pequeno número de erros pode resultar em atrasos e desperdício de créditos. Ao carregar um grande número de registros de arquivos que não têm delimitação lógica (por exemplo, os arquivos foram gerados automaticamente em intervalos aproximados), considere especificar CONTINUE em vez disso.

    Padrões adicionais:

    SKIP_FILE_num (por exemplo, SKIP_FILE_10)

    Ignorar um arquivo quando o número de linhas de erro encontrado no arquivo for igual ou maior que o número especificado.

    'SKIP_FILE_num%' (por exemplo, 'SKIP_FILE_10%')

    Pular um arquivo quando a porcentagem de linhas de erro encontradas no arquivo exceder a porcentagem especificada.

  • ABORT_STATEMENT

    Abortar a operação de carregamento se algum erro for encontrado em um arquivo de dados.

    Observe que a operação de carregamento não é abortada se o arquivo de dados não puder ser encontrado (por exemplo, porque ele não existe ou não pode ser acessado), exceto quando arquivos de dados explicitamente especificados no parâmetro FILES não puderem ser encontrados.

Padrão
Carregamento em massa utilizando COPY

ABORT_STATEMENT

Snowpipe

SKIP_FILE

SIZE_LIMIT = num
Uso

Somente carregamento de dados

Definição

Número (> 0) que especifica o tamanho máximo (em bytes) dos dados a serem carregados para uma determinada instrução COPY. Quando o limite é excedido, a operação COPY interrompe o carregamento dos arquivos. Esta opção é comumente usada para carregar um grupo comum de arquivos usando múltiplas instruções COPY. Para cada instrução, o carregamento de dados continua até que o SIZE_LIMIT especificado seja excedido, antes de passar para a instrução seguinte.

Por exemplo, suponha que um conjunto de arquivos em um caminho do estágio tivesse um tamanho de 10 MB cada. Se múltiplas instruções COPY definissem SIZE_LIMIT como 25000000 (25 MB), cada uma carregaria 3 arquivos. Ou seja, cada operação COPY seria interrompida após o limite SIZE_LIMIT ter sido excedido.

Observe que pelo menos um arquivo é carregado independentemente do valor especificado para SIZE_LIMIT, a menos que não haja nenhum arquivo a ser carregado.

Padrão

nulo (sem limite de tamanho)

PURGE = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se os arquivos de dados devem ser removidos automaticamente do estágio depois que os dados forem carregados com sucesso.

Se esta opção for definida como TRUE, observe que é feito o melhor possível para remover arquivos de dados carregados com sucesso. Se a operação de limpeza falhar por qualquer motivo, nenhum erro é devolvido no momento. Recomendamos que você liste arquivos preparados periodicamente (usando LIST) e remova manualmente os arquivos carregados com sucesso, se houver algum.

Padrão

FALSE

RETURN_FAILED_ONLY = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica se devem ser devolvidos apenas os arquivos que não tenham sido carregados no resultado da instrução.

Padrão

FALSE

MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE
Uso

Somente carregamento de dados

Definição

Cadeia de caracteres que especifica se dados semiestruturados devem ser carregados em colunas na tabela de destino que correspondem às colunas representadas nos dados.

Esta opção de cópia é suportada para os seguintes formatos de dados:

  • JSON

  • Avro

  • ORC

  • Parquet

Para que uma coluna seja correspondente, os seguintes critérios devem ser verdadeiros:

  • A coluna representada nos dados deve ter exatamente o mesmo nome que a coluna da tabela. A opção de cópia oferece suporte à diferenciação de letras maiúsculas e minúsculas em nomes de colunas. A ordem das colunas não importa.

  • A coluna na tabela deve ter um tipo de dados compatível com os valores na coluna representada nos dados. Por exemplo, os valores da cadeia de caracteres, número e booleano podem ser todos carregados em uma coluna variante.

Valores
CASE_SENSITIVE | CASE_INSENSITIVE

Carregar dados semiestruturados em colunas da tabela de destino que correspondam às colunas representadas nos dados. Os nomes das colunas distinguem letras maiúsculas de minúsculas (CASE_SENSITIVE) ou não (CASE_INSENSITIVE).

A operação COPY verifica se pelo menos uma coluna na tabela de destino corresponde a uma coluna representada nos arquivos de dados. Se for encontrada uma correspondência, os valores nos arquivos de dados são carregados na coluna ou colunas. Se nenhuma correspondência for encontrada, um conjunto de valores NULL para cada registro nos arquivos é carregado na tabela.

Nota

  • Se colunas adicionais não correspondentes estiverem presentes nos arquivos de dados, os valores nestas colunas não serão carregados.

  • Se colunas adicionais não correspondentes estiverem presentes na tabela de destino, a operação COPY insere valores NULL nestas colunas. Estas colunas devem oferecer suporte a valores NULL.

  • A instrução COPY não permite especificar uma consulta para transformar ainda mais os dados durante a carga (ou seja, transformação de COPY).

NONE

A operação COPY carrega os dados semiestruturados em uma coluna variante ou, se uma consulta for incluída na instrução COPY, transforma os dados.

Nota

As seguintes limitações se aplicam atualmente:

  • MATCH_BY_COLUMN_NAME não pode ser usado com o parâmetro VALIDATION_MODE em uma instrução COPY para validar os dados preparados em vez de carregá-los na tabela de destino.

  • Somente dados Parquet. Quando MATCH_BY_COLUMN_NAME está definido como CASE_SENSITIVE ou CASE_INSENSITIVE, um valor de coluna vazio (por exemplo, "col1": "") produz um erro.

Padrão

NONE

ENFORCE_LENGTH = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Sintaxe alternativa para TRUNCATECOLUMNS com lógica reversa (para compatibilidade com outros sistemas)

Booleano que especifica se deve truncar cadeias de caracteres de texto que excedam o comprimento da coluna de destino:

  • Se TRUE, a instrução COPY produz um erro se uma cadeia de caracteres carregada exceder o comprimento da coluna alvo.

  • Se FALSE, as cadeias de caracteres são automaticamente truncadas para o comprimento da coluna de destino.

Esta opção de cópia oferece suporte a dados CSV, bem como valores de cadeia de caracteres em dados semiestruturados quando carregados em colunas separadas em tabelas relacionais.

Nota

  • Se o comprimento da coluna da cadeia de caracteres de destino for definido como o máximo (por exemplo, VARCHAR (16777216)), uma cadeia de caracteres de entrada não pode exceder este comprimento; caso contrário, o comando COPY produz um erro.

  • Este parâmetro é funcionalmente equivalente a TRUNCATECOLUMNS, mas tem o comportamento oposto. É fornecido para compatibilidade com outros bancos de dados. É necessário apenas incluir um destes dois parâmetros em uma instrução COPY para produzir a saída desejada.

Padrão

TRUE

TRUNCATECOLUMNS = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Sintaxe alternativa para ENFORCE_LENGTH com lógica reversa (para compatibilidade com outros sistemas)

Booleano que especifica se deve truncar cadeias de caracteres de texto que excedam o comprimento da coluna de destino:

  • Se TRUE, as cadeias de caracteres são automaticamente truncadas para o comprimento da coluna de destino.

  • Se FALSE, a instrução COPY produz um erro se uma cadeia de caracteres carregada exceder o comprimento da coluna alvo.

Esta opção de cópia oferece suporte a dados CSV, bem como valores de cadeia de caracteres em dados semiestruturados quando carregados em colunas separadas em tabelas relacionais.

Nota

  • Se o comprimento da coluna da cadeia de caracteres de destino for definido como o máximo (por exemplo, VARCHAR (16777216)), uma cadeia de caracteres de entrada não pode exceder este comprimento; caso contrário, o comando COPY produz um erro.

  • Este parâmetro é funcionalmente equivalente a ENFORCE_LENGTH, mas tem o comportamento oposto. É fornecido para compatibilidade com outros bancos de dados. É necessário apenas incluir um destes dois parâmetros em uma instrução COPY para produzir a saída desejada.

Padrão

FALSE

FORCE = TRUE | FALSE
Uso

Somente carregamento de dados

Definição

Booleano que especifica o carregamento de todos os arquivos, independentemente de terem sido carregados anteriormente e não terem mudado desde que foram carregados. Note que esta opção recarrega os arquivos, potencialmente duplicando dados em uma tabela.

Padrão

FALSE

Notas de uso

  • Em relação aos metadados:

    Atenção

    Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.

Exemplos

Renomear my_int_stage como new_int_stage:

ALTER STAGE my_int_stage RENAME TO new_int_stage;
Copy

Alterar my_ext_stage (criado nos exemplos CREATE STAGE) para alterar o URL para referenciar uma subpasta chamada new na pasta files. Se um comando COPY INTO <tabela> que referencia este estágio encontrar um erro de dados em qualquer um dos registros, ele ignora o arquivo. Todas as outras opções de cópia são definidas com os valores padrão:

ALTER STAGE my_ext_stage
SET URL='s3://loading/files/new/'
COPY_OPTIONS = (ON_ERROR='skip_file');
Copy

Alterar my_ext_stage para substituir as credenciais fornecidas por uma referência a uma integração de armazenamento chamada myint:

ALTER STAGE my_ext_stage SET STORAGE_INTEGRATION = myint;
Copy

Alterar my_ext_stage para especificar uma nova ID da chave de acesso e uma chave de acesso secreta para o estágio:

ALTER STAGE my_ext_stage SET CREDENTIALS=(AWS_KEY_ID='d4c3b2a1' AWS_SECRET_KEY='z9y8x7w6');
Copy

(os valores de credenciais usados no exemplo acima são apenas para fins ilustrativos)

Alterar my_ext_stage3 para mudar o tipo de criptografia para criptografia do lado do servidor AWS_SSE_S3 para o estágio:

ALTER STAGE my_ext_stage3 SET ENCRYPTION=(TYPE='AWS_SSE_S3');
Copy

Exemplos de tabelas de diretório

Adicione uma tabela de diretório a um estágio existente chamado mystage:

ALTER STAGE mystage SET DIRECTORY = ( ENABLE = TRUE );
Copy

Atualizar manualmente os metadados da tabela de diretório em um estágio chamado mystage:

ALTER STAGE mystage REFRESH;

+-------------------------+----------------+-------------------------------+
| file                    | status         | description                   |
|-------------------------+----------------+-------------------------------|
| data/json/myfile.json   | REGISTERED_NEW | File registered successfully. |
+-------------------------+----------------+-------------------------------+
Copy

Atualizar manualmente os metadados da tabela de diretório para os arquivos no caminho data em um estágio chamado mystage:

ALTER STAGE mystage REFRESH SUBPATH = 'data';
Copy