CREATE ICEBERG TABLE¶

Cria uma nova tabela Iceberg no esquema atual/especificado ou substitui uma tabela Iceberg existente. As tabelas Iceberg combinam recursos padrão nas tabelas Snowflake, como processamento de SQL rápido, segurança e autorização, além de governança de dados com armazenamento e metadados abertos do Apache Iceberg.

Além disso, este comando oferece suporte às seguintes variantes para tabelas Iceberg que usam Snowflake como catálogo:

CREATE ICEBERG TABLE … AS SELECT (cria uma tabela preenchida; também chamada de CTAS)
CREATE ICEBERG TABLE … LIKE (cria uma cópia vazia de uma tabela existente)

Este tópico refere-se às tabelas Iceberg simplesmente como “tabelas”, exceto onde a especificação de tabelas Iceberg evita confusão.

Nota

Antes de criar uma tabela, você deve criar o volume externo onde os metadados e os arquivos de dados do Iceberg são armazenados. Para obter instruções, consulte Configuração de um volume externo para tabelas Iceberg.

Se você usar um catálogo Iceberg externo ou nenhum catálogo, também deverá criar uma integração de catálogo para a tabela. Para saber mais, consulte Configuração de uma integração de catálogo para tabelas Iceberg.

Consulte também:: ALTER ICEBERG TABLE, DROP ICEBERG TABLE , SHOW ICEBERG TABLES , DESCRIBE ICEBERG TABLE

Neste tópico:

Snowflake como o catálogo Iceberg¶

-- Snowflake as the Iceberg catalog
CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name> (
    -- Column definition
    <col_name> <col_type>
      [ inlineConstraint ]
      [ NOT NULL ]
      [ COLLATE '<collation_specification>' ]
      [ { DEFAULT <expr>
          | { AUTOINCREMENT | IDENTITY }
            [ { ( <start_num> , <step_num> )
                | START <num> INCREMENT <num>
              } ]
        } ]
      [ [ WITH ] MASKING POLICY <policy_name> [ USING ( <col_name> , <cond_col1> , ... ) ] ]
      [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
      [ COMMENT '<string_literal>' ]

    -- Additional column definitions
    [ , <col_name> <col_type> [ ... ] ]

    -- Out-of-line constraints
    [ , outoflineConstraint [ ... ] ]
  )
  [ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ]
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = 'SNOWFLAKE' ]
  BASE_LOCATION = '<relative_path_from_external_volume>'
  [ STAGE_FILE_FORMAT = (
    { FORMAT_NAME = '<file_format_name>'
      | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ]
    } ) ]
  [ STAGE_COPY_OPTIONS = ( copyOptions ) ]
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ CHANGE_TRACKING = { TRUE | FALSE } ]
  [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
  [ COPY GRANTS ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , <col_name> ... ] ) ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

Copy

Onde:

inlineConstraint ::=
  [ CONSTRAINT <constraint_name> ]
  { UNIQUE
    | PRIMARY KEY
    | [ FOREIGN KEY ] REFERENCES <ref_table_name> [ ( <ref_col_name> ) ]
  }
  [ <constraint_properties> ]

Copy

Para detalhes adicionais de restrição em linha, consulte CREATE | ALTER TABLE … CONSTRAINT.

outoflineConstraint ::=
  [ CONSTRAINT <constraint_name> ]
  { UNIQUE [ ( <col_name> [ , <col_name> , ... ] ) ]
    | PRIMARY KEY [ ( <col_name> [ , <col_name> , ... ] ) ]
    | [ FOREIGN KEY ] [ ( <col_name> [ , <col_name> , ... ] ) ]
      REFERENCES <ref_table_name> [ ( <ref_col_name> [ , <ref_col_name> , ... ] ) ]
  }
  [ <constraint_properties> ]

Copy

Para detalhes adicionais de restrição fora de linha, consulte CREATE | ALTER TABLE … CONSTRAINT.

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

Catálogo Iceberg externo¶

-- External Iceberg catalog
CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  externalCatalogParams
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

Copy

Onde:

externalCatalogParams (for AWS Glue Data Catalog) ::=
  CATALOG_TABLE_NAME = '<catalog_table_name>'
  [ CATALOG_NAMESPACE = '<catalog_namespace>' ]

Copy

externalCatalogParams (for Iceberg files in object storage) ::=
  METADATA_FILE_PATH = '<metadata_file_path>'

Copy

Sintaxe da variante¶

A sintaxe de variante a seguir é suportada para a criação de tabelas Iceberg que usam Snowflake como catálogo.

CREATE TABLE … AS SELECT (também chamado de CTAS)¶

Cria uma nova tabela preenchida com os dados devolvidos por uma consulta:

CREATE [ OR REPLACE ] ICEBERG TABLE <table_name> [ ( <col_name> [ <col_type> ] , <col_name> [ <col_type> ] , ... ) ]
  [ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ]
  [ COPY GRANTS ]
  AS SELECT <query>
  [ ... ]

Copy

Uma política de mascaramento pode ser aplicada a uma coluna em uma instrução CTAS. Especifique a política de mascaramento após o tipo de dados da coluna. Da mesma forma, uma política de acesso a linhas pode ser aplicada à tabela. Por exemplo:

CREATE ICEBERG TABLE <table_name> ( <col1> <data_type> [ WITH ] MASKING POLICY <policy_name> [ , ... ] )
  ...
  [ WITH ] ROW ACCESS POLICY <policy_name> ON ( <col1> [ , ... ] )
  AS SELECT <query>
  [ ... ]

Copy

Nota

Em um CTAS, a cláusula COPY GRANTS é válida somente quando combinada com a cláusula OR REPLACE. COPY GRANTS copia os privilégios da tabela sendo substituída por CREATE OR REPLACE (se já existir), e não da(s) tabela(s) de origem sendo consultada(s) na instrução SELECT. CTAS com COPY GRANTS permite que você substitua uma tabela por um novo conjunto de dados enquanto mantém as concessões existentes nesta tabela.

Para obter mais detalhes sobre COPY GRANTS, consulte COPY GRANTS neste documento.

CREATE ICEBERG TABLE … LIKE¶

Cria uma nova tabela com as mesmas definições de coluna que uma tabela existente, mas sem copiar os dados da tabela existente. Os nomes das colunas, tipos, padrões e restrições são copiados para a nova tabela:

CREATE [ OR REPLACE ] ICEBERG TABLE <table_name> LIKE <source_table>
  [ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ]
  [ COPY GRANTS ]
  [ ... ]

Copy

Para obter mais detalhes sobre COPY GRANTS, consulte COPY GRANTS neste documento.

Nota

CREATE TABLE … LIKE para uma tabela com uma sequência de incremento automático acessada por meio de um compartilhamento de dados não é suportada no momento.

Parâmetros obrigatórios¶

table_name

Especifica o identificador (nome) da tabela; deve ser único para o esquema no qual a tabela é criada.

Além disso, o identificador deve começar com um caractere alfabético e não pode conter espaços ou caracteres especiais, a menos que toda a cadeia de caracteres do identificador esteja entre aspas duplas (por exemplo, "My object"). Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais detalhes, consulte Requisitos para identificadores.

col_name

Especifica o identificador da coluna (nome). Todos os requisitos de identificadores de tabela também se aplicam aos identificadores de coluna.

Para obter mais detalhes, consulte Requisitos para identificadores e Palavras-chave reservadas e limitadas.

Nota

Além das palavras-chave padrão reservadas, as seguintes palavras-chave não podem ser usadas como identificadores de coluna porque são reservadas para funções de contexto padrão ANSI:

CURRENT_DATE
CURRENT_ROLE
CURRENT_TIME
CURRENT_TIMESTAMP
CURRENT_USER

Para a lista de palavras-chave reservadas, consulte Palavras-chave reservadas e limitadas.

col_type

Especifica o tipo de dados para a coluna.

Para obter mais detalhes sobre os tipos de dados que podem ser especificados para colunas de tabela, consulte Tipos de dados da tabela Iceberg.

query: Subconsulta que chama a função INFER_SCHEMA e formata a saída como uma matriz.

Parâmetros opcionais¶

EXTERNAL_VOLUME = 'external_volume_name'

Especifica o identificador (nome) do volume externo onde a tabela Iceberg armazena seus arquivos de metadados e dados no formato Parquet. Os metadados e arquivos de manifesto do Iceberg armazenam o esquema da tabela, partições, instantâneos e outros metadados.

Se você não especificar esse parâmetro, o padrão da tabela Iceberg será o volume externo do esquema, banco de dados ou conta. O esquema tem precedência sobre o banco de dados e o banco de dados tem precedência sobre a conta.

CONSTRAINT ...

Define uma restrição em linha ou fora de linha para a(s) coluna(s) especificada(s) na tabela.

Para detalhes de sintaxe, consulte CREATE | ALTER TABLE … CONSTRAINT. Para obter mais informações sobre restrições, consulte Restrições.

COLLATE 'collation_specification'

Especifica o agrupamento a ser usado para operações de coluna, tais como comparação de cadeias de caracteres. Esta opção aplica-se somente às colunas de texto (VARCHAR, STRING, TEXT etc.). Para obter mais detalhes, consulte Especificações de agrupamento.

DEFAULT ... ou . AUTOINCREMENT ...

Especifica se um valor padrão é automaticamente inserido na coluna caso um valor não seja explicitamente especificado por uma instrução INSERT ou CREATE TABLE AS SELECT:

DEFAULT expr
O valor padrão da coluna é definido pela expressão especificada que pode ser qualquer uma das opções seguintes:

Valor constante.

Referência de sequência (seq_name.NEXTVAL).

Expressão simples que retorna um valor escalar.

A expressão simples pode incluir uma UDF (função definida pelo usuário) SQL se a UDF não for uma UDF segura.

Nota

Se uma expressão padrão se referir a uma UDF SQL, então a função será substituída por sua definição no momento da criação da tabela. Se a função definida pelo usuário for redefinida no futuro, isso não atualizará a expressão padrão da coluna.

A expressão simples não pode conter referências a:

Subconsultas.

Agregados.

Funções de janela.

UDFs seguras.

UDFs escritas em outras linguagens além de SQL (por exemplo, Java, JavaScript).

Funções externas.

{ AUTOINCREMENT | IDENTITY } [ { ( start_num , step_num ) | START num INCREMENT num } ]
AUTOINCREMENT e IDENTITY são sinônimos. Quando um ou outro é usado, o valor padrão para a coluna começa com um número especificado e cada valor sucessivo é incrementado automaticamente pelo valor especificado.

Cuidado

O Snowflake usa uma sequência para gerar os valores de uma coluna de incremento automático. As sequências têm limitações; consulte Semântica da sequência.

O valor padrão para o início e o passo/incremento é 1.

AUTOINCREMENT e IDENTITY podem ser usados somente para colunas com tipos de dados numéricos.

Padrão: sem valor (a coluna não tem valor padrão)

Nota

DEFAULT e AUTOINCREMENT são mutuamente exclusivos; apenas um deles pode ser especificado para uma coluna.

MASKING POLICY = policy_name

Especifica a política de mascaramento a ser definida em uma coluna.

COMMENT 'string_literal'

Especifica um comentário para a coluna.

(Observe que os comentários podem ser especificados no nível da coluna ou da tabela. A sintaxe de cada um é um pouco diferente).

USING ( col_name , cond_col_1 ... )

Especifica os argumentos para passar para a expressão SQL da política de mascaramento condicional.

A primeira coluna da lista especifica a coluna das condições da política para mascarar ou tokenizar os dados e deve corresponder à coluna para a qual a política de mascaramento é definida.

As colunas adicionais especificam as colunas a serem avaliadas para determinar se os dados em cada linha do resultado da consulta devem ser mascarados ou tokenizados quando uma consulta é feita na primeira coluna.

Se a cláusula USING for omitida, o Snowflake tratará a política de mascaramento condicional como uma política de mascaramento normal.

CLUSTER BY ( expr [ , expr , ... ] )

Especifica uma ou mais colunas ou expressões de colunas na tabela como a chave de clustering. Para obter mais detalhes, consulte Chaves de clustering e tabelas clusterizadas.

Padrão: sem valor (nenhuma chave de clustering está definida para a tabela)

Importante

As chaves de clustering não são destinadas ou recomendadas para todas as tabelas; elas normalmente são vantajosas para tabelas muito grandes (ou seja, com vários terabytes).

Antes de especificar uma chave de clustering para uma tabela, você deve entender as micropartições. Para obter mais informações, consulte Explicação das estruturas de tabela do Snowflake.

Especifica o formato padrão do arquivo da tabela (para carregamento e descarregamento de dados), que pode ser:

FORMAT_NAME = file_format_name
Especifica um formato de arquivo nomeado existente a ser usado para carregar/descarregar dados na tabela. O formato de arquivo nomeado determina o tipo de formato (CSV, JSON etc.), bem como quaisquer outras opções de formato, para arquivos de dados. Para obter mais detalhes, consulte CREATE FILE FORMAT.

TYPE = CSV | JSON | AVRO | ORC | PARQUET | XML [ ... ]
Especifica o tipo de arquivos a serem carregados/descarregados na tabela.

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

Padrão: TYPE = CSV

Nota

FORMAT_NAME e TYPE são mutuamente exclusivos; para evitar comportamentos involuntários, deve-se especificar apenas um ou outro ao criar uma tabela.

STAGE_COPY_OPTIONS = ( ... )

Especifica uma (ou mais) opções a serem usadas ao carregar dados na tabela. Para obter mais detalhes, consulte Opções de cópia (neste tópico).

DATA_RETENTION_TIME_IN_DAYS = integer

Especifica o período de retenção da tabela para que as ações do Time Travel (SELECT, CLONE, UNDROP) possam ser executadas nos dados históricos na tabela. Para obter mais detalhes, consulte Compreensão e uso do Time Travel e Como trabalhar com tabelas temporárias e transitórias.

Para uma descrição detalhada deste parâmetro de nível de objeto, bem como mais informações sobre parâmetros de objeto, consulte Parâmetros.

Valores:

Standard Edition: 0 ou 1

Enterprise Edition:

0 a 90 para tabelas permanentes

0 ou 1 para tabelas temporárias e transitórias

Padrão:

Standard Edition: 1

Enterprise Edition (ou superior): 1 (a menos que um valor padrão diferente tenha sido especificado no esquema, banco de dados ou nível de conta)

Nota

Um valor de 0 desabilita efetivamente o Time Travel para a tabela.

MAX_DATA_EXTENSION_TIME_IN_DAYS = integer

Parâmetro de objeto que especifica o número máximo de dias para os quais o Snowflake pode estender o período de retenção de dados da tabela para evitar que os fluxos na tabela se tornem obsoletos.

Para uma descrição detalhada deste parâmetro, consulte MAX_DATA_EXTENSION_TIME_IN_DAYS.

CHANGE_TRACKING = { TRUE | FALSE }

Especifica se deve permitir o rastreamento de alterações na tabela.

TRUE habilita o rastreamento de alterações na tabela. Esta configuração adiciona um par de colunas ocultas à tabela de origem e começa a armazenar os metadados de rastreamento de alterações nas colunas. Estas colunas consomem uma pequena quantidade de armazenamento.

Os metadados de rastreamento de alterações podem ser consultados usando a cláusula CHANGES para instruções SELECT ou criando e consultando um ou mais fluxos na tabela.
FALSE não permite o rastreamento de alterações na tabela.

Padrão: FALSE

DEFAULT_DDL_COLLATION = 'collation_specification'

Determina uma especificação de agrupamento padrão para as colunas da tabela, incluindo colunas adicionadas à tabela no futuro.

Para obter mais detalhes sobre o parâmetro, consulte DEFAULT_DDL_COLLATION.

COPY GRANTS

Especifica manter os privilégios de acesso da tabela original quando uma nova tabela é criada usando qualquer uma das seguintes variantes CREATE TABLE:

CREATE OR REPLACE TABLE

CREATE TABLE … LIKE

CREATE TABLE … CLONE

O parâmetro copia todos os privilégios, exceto OWNERSHIP, da tabela existente para a nova tabela. A nova tabela não herda as concessões futuras definidas para o tipo de objeto no esquema. Por padrão, a função que executa a instrução CREATE TABLE é a proprietária da nova tabela.

Se o parâmetro não estiver incluído na instrução CREATE ICEBERG TABLE, então a nova tabela não herdará nenhum privilégio de acesso explícito concedido na tabela original, mas herda qualquer concessão futura definida para o tipo de objeto no esquema.

Nota:

Com compartilhamento de dados:

Se a tabela existente foi compartilhada com outra conta, a tabela de substituição também será compartilhada.

Se a tabela existente foi compartilhada com sua conta como consumidor de dados, e o acesso foi ainda concedido a outras funções na conta (usando GRANT IMPORTED PRIVILEGES no banco de dados pai), o acesso também é concedido à tabela de substituição.

A saída SHOW GRANTS para a tabela de substituição relaciona o cessionário para os privilégios copiados como a função que executou a instrução CREATE ICEBERG TABLE, com o carimbo de data/hora atual quando a instrução foi executada.

A operação de cópia de concessões ocorre atomicamente no comando CREATE ICEBERG TABLE (isto é, dentro da mesma transação).

COMMENT = 'string_literal'

Especifica um comentário para a tabela.

Padrão: sem valor

(Observe que os comentários podem ser especificados no nível da coluna ou da tabela. A sintaxe de cada um é um pouco diferente).

ROW ACCESS POLICY policy_name ON ( col_name [ , col_name ... ] )

Especifica a política de acesso a linhas a ser definida em uma tabela.

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.

Parâmetros do catálogo Snowflake¶

CATALOG = 'SNOWFLAKE'

Especifica o Snowflake como o catálogo Iceberg. Snowflake cuida de toda a manutenção do ciclo de vida, como compactação, da tabela.

BASE_LOCATION = 'relative_path_from_external_volume'

Especifica um caminho relativo do local EXTERNAL_VOLUME da tabela até um diretório onde o Snowflake pode gravar dados e metadados da tabela.

Este parâmetro não pode ser alterado após a criação de uma tabela.

Parâmetros do catálogo externo (externalCatalogParams)¶

CATALOG = 'catalog_integration_name'

Especifica o identificador (nome) da integração do catálogo para esta tabela.

Se não for especificado, a tabela Iceberg assumirá como padrão a integração do catálogo para o esquema, banco de dados ou conta. O esquema tem precedência sobre o banco de dados e o banco de dados tem precedência sobre a conta.

AWS Glue

CATALOG_TABLE_NAME = 'catalog_table_name'

Especifica o nome da tabela conforme reconhecido pelo seu catálogo de dados do AWS Glue. Para ver um exemplo de uso de CATALOG_TABLE_NAME ao criar uma tabela Iceberg, consulte Exemplos (neste tópico). Este parâmetro não pode ser alterado após a criação da tabela.

CATALOG_NAMESPACE = 'catalog_namespace'

Opcionalmente, especifica o namespace (por exemplo, my_glue_database) para a origem do catálogo de dados do AWS Glue e substitui o namespace de catálogo padrão especificado com a integração do catálogo. Ao especificar um namespace no nível da tabela, você pode usar uma única integração de catálogo para o AWS Glue para criar tabelas Iceberg em diferentes bancos de dados.

Se não for especificado, a tabela usará o namespace de catálogo padrão associado à integração de catálogo.

Arquivos Iceberg no armazenamento de objetos

METADATA_FILE_PATH = 'metadata_file_path'

Especifica o caminho relativo do arquivo de metadados Iceberg a ser usado para definições de colunas. Por exemplo, se s3://mybucket_us_east_1/metadata/v1.metadata.json for o caminho completo para seu arquivo de metadados e o local de armazenamento do volume externo for s3://mybucket_us_east_1/, especifique metadata/v1.metadata.json como o valor de METADATA_FILE_PATH.

Antes da versão 7.34 do Snowflake, esse parâmetro era chamado de METADATA_FILE_NAME.

Nota

Antes da versão 7.34 do Snowflake, um parâmetro denominado BASE_LOCATION (também conhecido como FILE_PATH nas versões anteriores) era necessário para criar uma tabela a partir de arquivos Iceberg no armazenamento de objetos. O parâmetro especificou um caminho relativo do local EXTERNAL_VOLUME da tabela. Com as versões 7.34 e posteriores do Snowflake, você não especifica um BASE_LOCATION para criar uma tabela a partir de arquivos Iceberg no armazenamento de objetos.

Você pode continuar a executar um script ou instrução que usa a versão anterior da sintaxe CREATE ICEBERG TABLE. No entanto, isso afetará o valor especificado como metadata-file-relative-path ao atualizar a tabela. Para obter mais informações, consulte ALTER ICEBERG TABLE … REFRESH.

Opções de tipo de formato (`formatTypeOptions`)¶

As opções de tipo de formato são usadas para carregar dados e descarregar dados das tabelas.

Dependendo do tipo de formato de arquivo especificado (STAGE_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¶

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

Caracteres multibyte

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

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¶

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.

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

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¶

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.

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

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.

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.

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

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.

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.

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

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.

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¶

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`)¶

As opções de cópia são usadas para carregar dados para e descarregar dados de tabelas.

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

STAGE_COPY_OPTIONS = ( ... )

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

Requisitos de controle de acesso¶

Uma função usada para executar este comando SQL deve ter os seguintes privilégios no mínimo:

Privilégio	Objeto	Notas
CREATE ICEBERG TABLE	Esquema
CREATE EXTERNAL VOLUME	Conta	Necessário para criar um novo volume externo.
USAGE	Volume externo	Necessário para fazer referência a um volume externo existente.
CREATE INTEGRATION	Conta	Necessário para criar uma nova integração de catálogo.
USAGE	Integração de catálogo	Necessário para fazer referência a uma integração de catálogo existente.

Observe que operar em qualquer objeto de um esquema também requer o privilégio USAGE no banco de dados e esquema principais.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso¶

Um esquema não pode conter tabelas e/ou visualizações com o mesmo nome. Ao criar uma tabela:
- Se já existir uma visualização com o mesmo nome no esquema, um erro é emitido e a tabela não é criada.
- Se uma tabela com o mesmo nome já existir no esquema, um erro é emitido e a tabela não é criada, a menos que a palavra-chave opcional OR REPLACE esteja incluída no comando.
Instruções CREATE OR REPLACE <object> são atômicas. Ou seja, quando um objeto é substituído, o objeto antigo é excluído e o novo objeto é criado em uma única transação.

Isso significa que qualquer consulta concorrente com a operação CREATE OR REPLACE ICEBERG TABLE utiliza a versão da tabela antiga ou nova.
Assim como as palavras-chave reservadas, nomes de funções reservadas ANSI (CURRENT_DATE, CURRENT_TIMESTAMP etc.) não podem ser usados como nomes de colunas.
Recriar uma tabela (usando a palavra-chave opcional OR REPLACE) diminui seu histórico, o que torna qualquer fluxo na tabela obsoleto. Um fluxo obsoleto é ilegível.
Atualmente, as tabelas Iceberg entre nuvens e entre regiões não são suportadas quando você usa o Snowflake como o catálogo Iceberg. Se CREATE ICEBERG TABLE retornar uma mensagem de erro como "External volume <nome_do_volume> must have a STORAGE_LOCATION defined in the local region ...", certifique-se de que seu volume externo esteja usando um local de armazenamento ativo na mesma região que sua conta Snowflake.
Se você criou seu volume externo ou integração de catálogo usando um identificador entre aspas duplas, deverá especificar o identificador exatamente conforme criado (incluindo as aspas duplas) na instrução CREATE ICEBERG TABLE. A não inclusão das aspas pode resultar em um erro Object does not exist (ou um tipo similar de erro).

Para ver um exemplo, consulte a seção Exemplos (neste tópico).
Antes da versão 7.34 do Snowflake, um parâmetro denominado BASE_LOCATION (também conhecido como FILE_PATH nas versões anteriores) era necessário para criar uma tabela a partir de arquivos Iceberg no armazenamento de objetos. O parâmetro especificou um caminho relativo do local EXTERNAL_VOLUME da tabela. Com as versões 7.34 e posteriores do Snowflake, você não especifica um BASE_LOCATION para criar uma tabela a partir de arquivos Iceberg no armazenamento de objetos.

Você pode continuar a executar um script ou instrução que usa a versão anterior da sintaxe CREATE ICEBERG TABLE. No entanto, isso afetará o valor especificado como metadata-file-relative-path ao atualizar a tabela. Para obter mais informações, consulte ALTER ICEBERG TABLE … REFRESH.
CREATE TABLE … LIKE:
- Se a tabela de origem tiver chaves de clustering, então a nova tabela terá chaves de clustering. Por padrão, o Clustering automático não é suspenso para a nova tabela, mesmo que o Clustering automático tenha sido suspenso para a tabela de origem.
CREATE TABLE … AS SELECT (CTAS):
- Quando as chaves de clustering são especificadas em uma instrução CTAS:
  - As definições das colunas são necessárias e devem ser explicitamente especificadas na instrução.
  - Por padrão, o Clustering automático não é suspenso para a nova tabela – mesmo que o Clustering automático seja suspenso para a tabela de origem.
  A subcláusula ORDER BY em uma instrução CREATE TABLE não afeta a ordem das linhas devolvidas por futuras instruções SELECT naquela tabela. Para especificar a ordem das linhas nas futuras instruções SELECT, use uma subcláusula ORDER BY nessas instruções.
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¶

Criação de uma tabela Iceberg com Snowflake como catálogo

Este exemplo cria uma tabela Iceberg com Snowflake como catálogo Iceberg. A tabela resultante é gerenciada pelo Snowflake e oferece suporte ao acesso de leitura e gravação. A instrução especifica um valor para o parâmetro BASE_LOCATION. Isso informa ao Snowflake onde gravar dados e metadados da tabela no volume externo.

CREATE ICEBERG TABLE myTable  (amount NUMBER)
  CATALOG='SNOWFLAKE'
  EXTERNAL_VOLUME='myIcebergVolume'
  BASE_LOCATION='relative_path_from_external_volume';

Copy

Criação de uma tabela Iceberg com AWS Glue como catálogo

Este exemplo cria uma tabela Iceberg que usa o catálogo de dados do AWS Glue. Para substituir o namespace de catálogo padrão e definir um namespace de catálogo para a tabela, a instrução usa o parâmetro opcional CATALOG_NAMESPACE.

CREATE ICEBERG TABLE myGlueTable
  EXTERNAL_VOLUME='glueCatalogVolume'
  CATALOG='glueCatalogInt'
  CATALOG_TABLE_NAME='myGlueTable'
  CATALOG_NAMESPACE='icebergcatalogdb2';

Copy

Criação de uma tabela Iceberg a partir dos metadados Iceberg no armazenamento de objetos

Este exemplo cria uma tabela Iceberg a partir de metadados Iceberg armazenados em armazenamento externo em nuvem. Ele também especifica um caminho relativo para os metadados da tabela no volume externo.

CREATE ICEBERG TABLE myIcebergTable
  EXTERNAL_VOLUME='icebergMetadataVolume'
  CATALOG='icebergCatalogInt'
  METADATA_FILE_PATH='path/to/metadata/v1.metadata.json';

Copy

Especificação de um volume externo ou integração de catálogo com um identificador entre aspas duplas

Este exemplo cria uma tabela Iceberg com um volume externo e integração de catálogo cujos identificadores contêm aspas duplas. Os identificadores colocados entre aspas duplas diferenciam maiúsculas de minúsculas e geralmente contêm caracteres especiais.

Os identificadores "exvol_lower" e "catint_lower" são especificados exatamente como foram criados (incluindo as aspas duplas). A não inclusão das aspas pode resultar em um erro Object does not exist (ou um tipo similar de erro).

Para saber mais, consulte Identificadores entre aspas duplas.

CREATE OR REPLACE ICEBERG TABLE itable_with_quoted_catalog
  EXTERNAL_VOLUME = '"exvol_lower"'
  CATALOG = '"catint_lower"'
  METADATA_FILE_PATH='path/to/metadata/v1.metadata.json';

Copy

CREATE ICEBERG TABLE¶

Sintaxe¶

Snowflake como o catálogo Iceberg¶

Catálogo Iceberg externo¶

Sintaxe da variante¶

CREATE TABLE … AS SELECT (também chamado de CTAS)¶

CREATE ICEBERG TABLE … LIKE¶

Parâmetros obrigatórios¶

Parâmetros opcionais¶

Parâmetros do catálogo Snowflake¶

Parâmetros do catálogo externo (externalCatalogParams)¶

Opções de tipo de formato (formatTypeOptions)¶

TYPE = CSV¶

TYPE = JSON¶

TYPE = AVRO¶

TYPE = ORC¶

TYPE = PARQUET¶

TYPE = XML¶

Opções de cópia (copyOptions)¶

Requisitos de controle de acesso¶

Notas de uso¶

Exemplos¶

Opções de tipo de formato (`formatTypeOptions`)¶

Opções de cópia (`copyOptions`)¶