CREATE TABLE¶
Cria uma nova tabela no esquema atual/especificado ou substitui uma tabela existente. Uma tabela pode ter várias colunas, com cada definição de coluna consistindo de um nome, tipo de dados e, opcionalmente, se a coluna:
Exige um valor (NOT NULL).
Tem um valor padrão.
Tem qualquer restrição de integridade referencial (chave primária, chave estrangeira etc.).
Além disso, este comando oferece suporte às seguintes variantes:
CREATE TABLE … AS SELECT (cria uma tabela preenchida; também referida como CTAS)
CREATE TABLE … USING TEMPLATE (cria uma tabela com as definições das colunas derivadas de um conjunto de arquivos preparados)
CREATE TABLE … LIKE (cria uma cópia vazia de uma tabela existente)
CREATE TABLE … CLONE (cria um clone de uma tabela existente)
- Consulte também:
Sintaxe¶
CREATE [ OR REPLACE ]
[ { [ LOCAL | GLOBAL ] TEMP[ORARY] | VOLATILE } | TRANSIENT ]
TABLE [ IF NOT EXISTS ] <table_name>
( <col_name> <col_type>
[ COLLATE '<collation_specification>' ]
/* COLLATE is supported only for text data types (VARCHAR and synonyms) */
[ COMMENT '<string_literal>' ]
[ { DEFAULT <expr>
| { AUTOINCREMENT | IDENTITY } [ { ( <start_num> , <step_num> ) | START <num> INCREMENT <num> } ] } ]
/* AUTOINCREMENT (or IDENTITY) is supported only for numeric data types (NUMBER, INT, FLOAT, etc.) */
[ NOT NULL ]
[ [ WITH ] MASKING POLICY <policy_name> [ USING ( <col_name> , <cond_col1> , ... ) ] ]
[ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
[ inlineConstraint ]
[ , <col_name> <col_type> [ ... ] ]
[ , outoflineConstraint ]
[ , ... ] )
[ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ]
[ 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 ]
[ [ WITH ] ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , <col_name> ... ] ) ]
[ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
[ COMMENT = '<string_literal>' ]
Onde:
inlineConstraint ::= [ CONSTRAINT <constraint_name> ] { UNIQUE | PRIMARY KEY | { [ FOREIGN KEY ] REFERENCES <ref_table_name> [ ( <ref_col_name> ) ] } } [ <constraint_properties> ]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> ]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>' 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 NULL_IF = ( '<string>' [ , '<string>' ... ] ) -- If TYPE = ORC TRIM_SPACE = TRUE | FALSE NULL_IF = ( '<string>' [ , '<string>' ... ] ) -- If TYPE = PARQUET COMPRESSION = AUTO | LZO | SNAPPY | NONE SNAPPY_COMPRESSION = TRUE | FALSE BINARY_AS_TEXT = TRUE | FALSE TRIM_SPACE = 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 SKIP_BYTE_ORDER_MARK = TRUE | FALSEcopyOptions ::= 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
Sintaxe da variante¶
CREATE TABLE … AS SELECT (também chamado de CTAS)¶
Cria uma nova tabela preenchida com os dados devolvidos por uma consulta:
CREATE [ OR REPLACE ] TABLE <table_name> [ ( <col_name> [ <col_type> ] , <col_name> [ <col_type> ] , ... ) ] [ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ] [ COPY GRANTS ] AS SELECT <query> [ ... ]
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 TABLE <table_name> ( <col1> <data_type> [ with ] masking policy <policy_name> [ , ... ] ) ... [ WITH ] ROW ACCESS POLICY <policy_name> ON ( <col1> [ , ... ] ) AS SELECT <query> [ ... ]
Nota
Em um CTAS, a cláusula COPY GRANTS é válida somente quando combinada com a cláusula OR REPLACE. COPY GRANTS copia as permissões 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 TABLE … USING TEMPLATE¶
Cria uma nova tabela com as definições das colunas derivadas de um conjunto de arquivos preparados contendo dados semiestruturados. Este recurso está atualmente limitado aos arquivos Apache Parquet, Apache Avro e ORC.
CREATE [ OR REPLACE ] TABLE <table_name> [ COPY GRANTS ] USING TEMPLATE <query> [ ... ]
Nota
Se a instrução estiver substituindo uma tabela existente com o mesmo nome, então as concessões são copiadas da tabela que está sendo substituída. Se não existir uma tabela com esse nome, então as concessões são copiadas da tabela de origem que está sendo clonada.
Para obter mais detalhes sobre COPY GRANTS, consulte COPY GRANTS neste documento.
CREATE 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 ] TABLE <table_name> LIKE <source_table> [ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ] [ COPY GRANTS ] [ ... ]
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.
CREATE TABLE … CLONE¶
Cria uma nova tabela com as mesmas definições de coluna e contendo todos os dados existentes da tabela de origem, sem realmente copiar os dados. Esta variante também pode ser usada para clonar uma tabela em um momento/ponto específico no passado (usando Time Travel):
CREATE [ OR REPLACE ] TABLE <name> CLONE <source_table> [ { AT | BEFORE } ( { TIMESTAMP => <timestamp> | OFFSET => <time_difference> | STATEMENT => <id> } ) ] [ COPY GRANTS ] [ ... ]
Nota
Se a instrução estiver substituindo uma tabela existente com o mesmo nome, então as concessões são copiadas da tabela que está sendo substituída. Se não existir uma tabela com esse nome, então as concessões são copiadas da tabela de origem que está sendo clonada.
Para obter mais detalhes sobre COPY GRANTS, consulte COPY GRANTS neste documento.
Para obter mais detalhes sobre clonagem, consulte CREATE <objeto> … CLONE.
Parâmetros obrigatórios¶
name
Especifica o identificador (ou seja, 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 (ou seja, o 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.
query
- Necessário se estiver usando USING TEMPLATE
Subconsulta que chama a função INFER_SCHEMA e formata a saída como uma matriz.
Alternativamente,
USING TEMPLATE
aceita a saída INFER_SCHEMA como uma cadeia de caracteres literal ou variável.
Parâmetros opcionais¶
TEMP[ORARY] | LOCAL TEMP[ORARY] | GLOBAL TEMP[ORARY] | VOLATILE
Especifica que a tabela é temporária. Uma tabela temporária existe apenas pela duração da sessão do usuário na qual foi criada e não é visível para os outros usuários. Uma tabela temporária e todo o seu conteúdo são descartados no final da sessão.
Os sinônimos e abreviações para
TEMPORARY
(por exemplo,GLOBAL TEMPORARY
) são fornecidos para compatibilidade com outros bancos de dados (por exemplo, para evitar erros ao migrar instruções CREATE TABLE). As tabelas criadas com qualquer uma destas palavras-chave aparecem e se comportam de forma idêntica às tabelas criadas usandoTEMPORARY
.Padrão: sem valor. Se uma tabela não for declarada como
TRANSIENT
ouTEMPORARY
, a tabela é permanente.Nota
As tabelas temporárias têm algumas considerações de uso adicionais com relação a conflitos de nomes que podem ocorrer com outras tabelas que têm o mesmo nome no mesmo esquema.
Além disso, as tabelas temporárias têm algumas considerações de armazenamento.
Para obter mais informações sobre estas e outras considerações ao decidir sobre a criação de tabelas temporárias ou transitórias, consulte Como trabalhar com tabelas temporárias e transitórias e Custos de armazenamento para Time Travel e Fail-safe.
TRANSIENT
Especifica que a tabela é transitória.
Assim como uma tabela permanente, uma tabela transitória existe até ser descartada explicitamente e fica visível para qualquer usuário com os privilégios correspondentes. No entanto, as tabelas transitórias têm um nível de proteção de dados inferior às tabelas permanentes, o que significa que os dados em uma tabela transitória podem ser perdidos no caso de uma falha do sistema. Como tal, tabelas transitórias devem ser usadas somente para dados que possam ser recriados fora do Snowflake.
Padrão: sem valor. Se uma tabela não for declarada como
TRANSIENT
ouTEMPORARY
, a tabela é permanente.Nota
As tabelas transitórias têm algumas considerações de armazenamento.
Para obter mais informações sobre estas e outras considerações ao decidir sobre a criação de tabelas temporárias ou transitórias, consulte Como trabalhar com tabelas temporárias e transitórias e Custos de armazenamento para Time Travel e Fail-safe.
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.
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).
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
eIDENTITY
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
eIDENTITY
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
eAUTOINCREMENT
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.
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.
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.
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, leia Explicação das estruturas de tabela do Snowflake.
STAGE_FILE_FORMAT = ( FORMAT_NAME = 'file_format_name' )
ou .STAGE_FILE_FORMAT = ( TYPE = CSV | JSON | AVRO | ORC | PARQUET | XML [ ... ] )
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
eTYPE
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 Parameters.
Valores:
Standard Edition:
0
ou1
Enterprise Edition:
0
a90
para tabelas permanentes0
ou1
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 TABLE, então a nova tabela não herda qualquer 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:
Se a instrução CREATE TABLE fizer referência a mais de uma tabela (por exemplo,
create or replace table TABLE1 clone TABLE2;
), a cláusulaCOPY GRANTS
copia as concessões da tabela que está sendo substituída (por exemplo,TABLE1
neste exemplo).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çãoCREATE 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 TABLE (ou seja, dentro da mesma transação).
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 detalhes sobre como especificar tags em uma instrução, consulte Cotas de tags para objetos e colunas.
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).
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¶
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 prefixo0x
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 prefixo0x
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 quecompression
é a extensão adicionada pelo método de compressão, seCOMPRESSION
estiver definido.
Nota
Se a opção de cópia
SINGLE
forTRUE
, 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 caminhointernal_location
ouexternal_location
(por exemplo,copy into @stage/data.csv
).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
ouRECORD_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 arquivoRECORD_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 comoNONE
.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, considerandoFIELD_DELIMITER = '|'
eFIELD_OPTIONALLY_ENCLOSED_BY = '"'
:|"Hello world"| /* loads as */ >Hello world< |" Hello world "| /* loads as */ > Hello world < | "Hello world" | /* loads as */ >Hello world<
(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 de2
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 valorESCAPE_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
. QuandoFIELD_OPTIONALLY_ENCLOSED_BY = NONE
, a definição deEMPTY_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
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-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 de2
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 valorESCAPE_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 quecompression
é a extensão adicionada pelo método de compressão, seCOMPRESSION
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 comoTRUE
: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
Somente carregamento de dados
- Definição
Booleano que especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (
�
). A opção de cópia 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
Somente carregamento de dados
- Definição
Booleano que especifica se os erros da codificação UTF-8 produzem condições de erro. Se definido como
TRUE
, qualquer sequência inválida UTF-8 é silenciosamente substituída pelo caractere UnicodeU+FFFD
(ou seja, “caractere de substituição”).Nota
Esta opção de cópia remove todos os caracteres nãoUTF-8 durante o carregamento de dados, mas não há garantia de uma substituição de caracteres um a um. Recomendamos utilizar a opção de cópia REPLACE_INVALID_CHARACTERS em seu lugar.
- 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
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
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 de2
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 valorESCAPE_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
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 de2
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 valorESCAPE_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
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
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 de2
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 valorESCAPE_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
Somente carregamento de dados
- Definição
Booleano que especifica se os erros da codificação UTF-8 produzem condições de erro. Se definido como
TRUE
, qualquer sequência inválida de UTF-8 é silenciosamente substituída pelo caractere UnicodeU+FFFD
(ou seja, “caractere de substituição”).- 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
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 queCONTINUE
ouABORT_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 especificarCONTINUE
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 limiteSIZE_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
ouCASE_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 TABLE |
Esquema |
Note que a criação de uma tabela temporária não requer o privilégio CREATE TABLE. |
SELECT |
Tabela, tabela externa, exibição |
Necessário em tabelas e/ou exibições consultadas somente ao clonar uma tabela ou executar instruções CTAS. |
APPLY |
Política de mascaramento, política de acesso a linhas, tag |
Necessário somente ao aplicar uma política de mascaramento, política de acesso a linhas, tags de objetos ou qualquer combinação dessas recursos de governança ao criar tabelas. |
USAGE |
Formato do arquivo |
Necessário somente ao especificar um formato de arquivo nomeado no parâmetro |
USAGE (estágio externo) ou READ (estágio interno) |
Estágio |
Necessário para derivar definições de colunas da tabela a partir de arquivos preparados usando instruções CREATE TABLE … USING TEMPLATE. |
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.
Importante
Usar
OR REPLACE
é o equivalente a usar DROP TABLE na tabela existente e depois criar uma nova tabela com o mesmo nome; no entanto, a tabela descartada não é permanentemente removida do sistema. Em vez disso, ela fica retida no Time Travel. Isto é importante notar porque as tabelas descartadas no Time Travel podem ser recuperadas, mas elas também contribuem para o armazenamento de dados de sua conta. Para obter mais informações, consulte Custos de armazenamento para Time Travel e Fail-safe.Instruções CREATE OR REPLACE <object> são atômicas. Ou seja, quando o objeto é substituído, a exclusão do objeto antigo e a criação do novo objeto são processadas em uma única transação.
Isso significa que qualquer consulta concorrente com a operação CREATE OR REPLACE TABLE utiliza a versão da tabela antiga ou nova.
A recriação ou troca de uma tabela descarta seus dados de alteração. Qualquer fluxo na tabela se torna obsoleto. Além disso, qualquer fluxo em uma visualização que tenha esta tabela como uma tabela subjacente, torna-se obsoleto. Um fluxo obsoleto é ilegível.
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.
CREATE TABLE … CLONE:
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 é suspenso para a nova tabela – mesmo que o Clustering automático não tenha sido suspenso para a tabela de origem.
CREATE TABLE … CHANGE_TRACKING = TRUE
Quando o rastreamento da alterações é ativado, a tabela é bloqueada durante toda a operação. Os bloqueios podem causar latência com algumas operações associadas DDL/DML. Para obter mais informações, consulte Bloqueio de recursos.
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):
Se os aliases para os nomes das colunas na lista SELECT forem colunas válidas, então as definições das colunas não são exigidas na instrução CTAS; se omitidos, os nomes e tipos das colunas são inferidos a partir da consulta subjacente:
CREATE TABLE <table_name> AS SELECT ...
Alternativamente, os nomes podem ser explicitamente especificados usando a seguinte sintaxe:
CREATE TABLE <table_name> ( <col1_name> , <col2_name> , ... ) AS SELECT ...
O número de nomes de colunas especificados deve corresponder ao número de itens da lista SELECT na consulta; os tipos das colunas são inferidos a partir dos tipos produzidos pela consulta.
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.
Se você quiser que a tabela seja criada com linhas em uma ordem específica, então use uma subcláusula ORDER BY na cláusula SELECT do CTAS. Especificar CLUSTER BY não agrupa os dados no momento em que a tabela é criada; em vez disso, CLUSTER BY depende do clustering automático para reter os dados ao longo do tempo.
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.
Dentro de uma transação, qualquer instrução DDL (incluindo CREATE TEMPORARY/TRANSIENT TABLE) executa a transação antes de executar a própria instrução DDL. A instrução DDL é então executada em sua própria transação. A próxima instrução após a instrução DDL inicia uma nova transação. Portanto, você não pode criar, usar e descartar uma tabela temporária ou transitória dentro de uma única transação. Se você quiser usar uma tabela temporária ou transitória dentro de uma transação, então crie a tabela antes da transação, e descarte a tabela após a transação.
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.Uma única política de mascaramento que utilize colunas condicionais pode ser aplicada a várias tabelas, desde que a estrutura de colunas da tabela corresponda às colunas especificadas na política.
Ao criar uma tabela com uma política de mascaramento em uma ou mais colunas da tabela, ou uma política de acesso a linhas adicionada à tabela, use a função POLICY_CONTEXT para simular uma consulta na(s) coluna(s) protegida(s) por uma política de mascaramento e a tabela protegida por uma política de acesso a linhas.
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¶
Criar uma tabela simples no banco de dados atual e inserir uma linha na tabela:
CREATE TABLE mytable (amount NUMBER); +-------------------------------------+ | status | |-------------------------------------| | Table MYTABLE successfully created. | +-------------------------------------+ INSERT INTO mytable VALUES(1); SHOW TABLES like 'mytable'; +---------------------------------+---------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+ | created_on | name | database_name | schema_name | kind | comment | cluster_by | rows | bytes | owner | retention_time | |---------------------------------+---------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------| | Mon, 11 Sep 2017 16:32:28 -0700 | MYTABLE | TESTDB | PUBLIC | TABLE | | | 1 | 1024 | ACCOUNTADMIN | 1 | +---------------------------------+---------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+ DESC TABLE mytable; +--------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+ | name | type | kind | null? | default | primary key | unique key | check | expression | comment | |--------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------| | AMOUNT | NUMBER(38,0) | COLUMN | Y | NULL | N | N | NULL | NULL | NULL | +--------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+
Criar uma tabela simples e especificar comentários tanto para a tabela quanto para a coluna na tabela:
CREATE TABLE example (col1 number comment 'a column comment') COMMENT='a table comment'; +-------------------------------------+ | status | |-------------------------------------| | Table EXAMPLE successfully created. | +-------------------------------------+ SHOW TABLES like 'example'; +---------------------------------+---------+---------------+-------------+-------+-----------------+------------+------+-------+--------------+----------------+ | created_on | name | database_name | schema_name | kind | comment | cluster_by | rows | bytes | owner | retention_time | |---------------------------------+---------+---------------+-------------+-------+-----------------+------------+------+-------+--------------+----------------| | Mon, 11 Sep 2017 16:35:59 -0700 | EXAMPLE | TESTDB | PUBLIC | TABLE | a table comment | | 0 | 0 | ACCOUNTADMIN | 1 | +---------------------------------+---------+---------------+-------------+-------+-----------------+------------+------+-------+--------------+----------------+ DESC TABLE example; +------+--------------+--------+-------+---------+-------------+------------+-------+------------+------------------+ | name | type | kind | null? | default | primary key | unique key | check | expression | comment | |------+--------------+--------+-------+---------+-------------+------------+-------+------------+------------------| | COL1 | NUMBER(38,0) | COLUMN | Y | NULL | N | N | NULL | NULL | a column comment | +------+--------------+--------+-------+---------+-------------+------------+-------+------------+------------------+
Criar uma tabela selecionando de uma tabela existente:
CREATE TABLE mytable_copy (b) AS SELECT * from mytable; DESC TABLE mytable_copy; +------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+ | name | type | kind | null? | default | primary key | unique key | check | expression | comment | |------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------| | B | NUMBER(38,0) | COLUMN | Y | NULL | N | N | NULL | NULL | NULL | +------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+ CREATE TABLE mytable_copy2 AS SELECT b+1 AS c FROM mytable_copy; DESC TABLE mytable_copy2; +------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+ | name | type | kind | null? | default | primary key | unique key | check | expression | comment | |------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------| | C | NUMBER(39,0) | COLUMN | Y | NULL | N | N | NULL | NULL | NULL | +------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+ SELECT * FROM mytable_copy2; +---+ | C | |---| | 2 | +---+
Exemplo mais avançado de criação de uma tabela selecionando de uma tabela existente; neste exemplo, os valores na coluna summary_amount
da nova tabela são derivados de duas colunas na tabela de origem:
CREATE TABLE testtable_summary (name, summary_amount) AS SELECT name, amount1 + amount2 FROM testtable;
Criar uma tabela selecionando colunas de um arquivo de dados preparado do Parquet:
CREATE OR REPLACE TABLE parquet_col ( custKey number default NULL, orderDate date default NULL, orderStatus varchar(100) default NULL, price varchar(255) ) AS SELECT $1:o_custkey::number, $1:o_orderdate::date, $1:o_orderstatus::text, $1:o_totalprice::text FROM @my_stage; +-----------------------------------------+ | status | |-----------------------------------------| | Table PARQUET_COL successfully created. | +-----------------------------------------+ DESC TABLE parquet_col; +-------------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+ | name | type | kind | null? | default | primary key | unique key | check | expression | comment | |-------------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------| | CUSTKEY | NUMBER(38,0) | COLUMN | Y | NULL | N | N | NULL | NULL | NULL | | ORDERDATE | DATE | COLUMN | Y | NULL | N | N | NULL | NULL | NULL | | ORDERSTATUS | VARCHAR(100) | COLUMN | Y | NULL | N | N | NULL | NULL | NULL | | PRICE | VARCHAR(255) | COLUMN | Y | NULL | N | N | NULL | NULL | NULL | +-------------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+
Criar uma tabela com as mesmas definições de coluna que outra tabela, mas sem linhas:
CREATE TABLE mytable (amount NUMBER); INSERT INTO mytable VALUES(1); SELECT * FROM mytable; +--------+ | AMOUNT | |--------| | 1 | +--------+ CREATE TABLE mytable_2 LIKE mytable; DESC TABLE mytable_2; +--------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+ | name | type | kind | null? | default | primary key | unique key | check | expression | comment | |--------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------| | AMOUNT | NUMBER(38,0) | COLUMN | Y | NULL | N | N | NULL | NULL | NULL | +--------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+ SELECT * FROM mytable_2; +--------+ | AMOUNT | |--------| +--------+
Criar uma tabela com uma chave de clustering de várias colunas:
CREATE TABLE mytable (date timestamp_ntz, id number, content variant) CLUSTER BY (date, id); SHOW TABLES LIKE 'mytable'; +---------------------------------+---------+---------------+-------------+-------+---------+------------------+------+-------+--------------+----------------+ | created_on | name | database_name | schema_name | kind | comment | cluster_by | rows | bytes | owner | retention_time | |---------------------------------+---------+---------------+-------------+-------+---------+------------------+------+-------+--------------+----------------| | Mon, 11 Sep 2017 16:20:41 -0700 | MYTABLE | TESTDB | PUBLIC | TABLE | | LINEAR(DATE, ID) | 0 | 0 | ACCOUNTADMIN | 1 | +---------------------------------+---------+---------------+-------------+-------+---------+------------------+------+-------+--------------+----------------+
Especificar o agrupamento para colunas em uma tabela:
CREATE TABLE collation_demo ( uncollated_phrase VARCHAR, utf8_phrase VARCHAR COLLATE 'utf8', english_phrase VARCHAR COLLATE 'en', spanish_phrase VARCHAR COLLATE 'sp' ); INSERT INTO collation_demo (uncollated_phrase, utf8_phrase, english_phrase, spanish_phrase) VALUES ('pinata', 'pinata', 'pinata', 'piñata');
Criar uma tabela onde as definições das colunas sejam derivadas de um conjunto de arquivos preparados que contenham dados Avro, Parquet ou ORC.
Observe que o estágio mystage
e o formato de arquivo my_parquet_format
mencionados na instrução já devem existir. Um conjunto de arquivos já deve ser preparado no local de armazenamento em nuvem referenciado na definição do estágio.
O exemplo a seguir cria uma tabela usando o esquema detectado a partir de arquivos preparados e ordena as colunas por ORDER_ID. Isso se baseia em um exemplo no tópico INFER_SCHEMA.
CREATE TABLE mytable USING TEMPLATE ( SELECT ARRAY_AGG(OBJECT_CONSTRUCT(*)) WITHIN GROUP (ORDER BY ORDER_ID) FROM TABLE( INFER_SCHEMA( LOCATION=>'@mystage', FILE_FORMAT=>'my_parquet_format' ) ));
Observe que a ordenação das colunas por ORDER_ID só se aplica se todos os arquivos preparados compartilharem um único esquema. Se o conjunto de arquivos de dados preparados incluir vários esquemas com nomes de colunas compartilhadas, a ordem representada na coluna ORDER_ID pode não corresponder a nenhum arquivo único.
Criar uma tabela temporária que é automaticamente descartada no fim da sessão:
create temporary table demo_temporary (i integer); create temp table demo_temp (i integer);Para compatibilidade com outros fornecedores, o Snowflake também oferece suporte ao uso das palavras-chave abaixo como sinônimos para TEMPORARY:
create local temporary table demo_local_temporary (i integer); create local temp table demo_local_temp (i integer); create global temporary table demo_global_temporary (i integer); create global temp table demo_global_temp (i integer); create volatile table demo_volatile (i integer);