ALTER TABLE

Modifica as propriedades, colunas ou restrições de uma tabela existente.

Consulte também:

ALTER TABLE … ALTER COLUMN , CREATE TABLE , DROP TABLE , SHOW TABLES , DESCRIBE TABLE

Sintaxe

ALTER TABLE [ IF EXISTS ] <name> RENAME TO <new_table_name>

ALTER TABLE [ IF EXISTS ] <name> SWAP WITH <target_table_name>

ALTER TABLE [ IF EXISTS ] <name> { clusteringAction | tableColumnAction | constraintAction  }

ALTER TABLE [ IF EXISTS ] <name> dataGovnPolicyTagAction

ALTER TABLE [ IF EXISTS ] <name> extTableColumnAction

ALTER TABLE [ IF EXISTS ] <name> searchOptimizationAction

ALTER TABLE [ IF EXISTS ] <name> SET
  [ 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>' ]
  [ ENABLE_SCHEMA_EVOLUTION = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]

ALTER TABLE [ IF EXISTS ] <name> UNSET {
                                       DATA_RETENTION_TIME_IN_DAYS         |
                                       MAX_DATA_EXTENSION_TIME_IN_DAYS     |
                                       CHANGE_TRACKING                     |
                                       DEFAULT_DDL_COLLATION               |
                                       ENABLE_SCHEMA_EVOLUTION             |
                                       COMMENT                             |
                                       }
                                       [ , ... ]
Copy

Onde:

clusteringAction ::=
  {
     CLUSTER BY ( <expr> [ , <expr> , ... ] )
     /* RECLUSTER is deprecated */
   | RECLUSTER [ MAX_SIZE = <budget_in_bytes> ] [ WHERE <condition> ]
     /* { SUSPEND | RESUME } RECLUSTER is valid action */
   | { SUSPEND | RESUME } RECLUSTER
   | DROP CLUSTERING KEY
  }
Copy
tableColumnAction ::=
  {
     ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type>
        [
           {
              DEFAULT <default_value>
              | { AUTOINCREMENT | IDENTITY }
                 /* AUTOINCREMENT (or IDENTITY) is supported only for           */
                 /* columns with numeric data types (NUMBER, INT, FLOAT, etc.). */
                 /* Also, if the table is not empty (i.e. if the table contains */
                 /* any rows), only DEFAULT can be altered.                     */
                 [
                    {
                       ( <start_num> , <step_num> )
                       | START <num> INCREMENT <num>
                    }
                 ]
                 [  { ORDER | NOORDER } ]
           }
        ]
        [ inlineConstraint ]
        [ COLLATE '<collation_specification>' ]

   | RENAME COLUMN <col_name> TO <new_col_name>

   | ALTER | MODIFY [ ( ]
                            [ COLUMN ] <col1_name> DROP DEFAULT
                          , [ COLUMN ] <col1_name> SET DEFAULT <seq_name>.NEXTVAL
                          , [ COLUMN ] <col1_name> { [ SET ] NOT NULL | DROP NOT NULL }
                          , [ COLUMN ] <col1_name> [ [ SET DATA ] TYPE ] <type>
                          , [ COLUMN ] <col1_name> COMMENT '<string>'
                          , [ COLUMN ] <col1_name> UNSET COMMENT
                        [ , [ COLUMN ] <col2_name> ... ]
                        [ , ... ]
                    [ ) ]

   | DROP [ COLUMN ] [ IF EXISTS ] <col1_name> [, <col2_name> ... ]
  }

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

Para obter sintaxes detalhadas e exemplos de alteração de colunas, consulte ALTER TABLE … ALTER COLUMN. .

Para obter sintaxes detalhadas e exemplos de criação/alteração de restrições em linha, consulte CREATE | ALTER TABLE … CONSTRAINT.

dataGovnPolicyTagAction ::=
  {
      SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
    | UNSET TAG <tag_name> [ , <tag_name> ... ]
  }
  |
  {
      ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] )
    | DROP ROW ACCESS POLICY <policy_name>
    | DROP ROW ACCESS POLICY <policy_name> ,
        ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] )
    | DROP ALL ROW ACCESS POLICIES
  }
  |
  {
      SET AGGREGATION POLICY <policy_name> [ FORCE ]
      | UNSET AGGREGATION POLICY
  }
  |
  ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type>
    [ [ WITH ] MASKING POLICY <policy_name>
          [ USING ( <col1_name> , <cond_col_1> , ... ) ] ]
    [ [ WITH ] TAG ( <tag_name> = '<tag_value>'
          [ , <tag_name> = '<tag_value>' , ... ] ) ]
  |
  {
    { ALTER | MODIFY } [ COLUMN ] <col1_name>
        SET MASKING POLICY <policy_name>
          [ USING ( <col1_name> , <cond_col_1> , ... ) ] [ FORCE ]
      | UNSET MASKING POLICY
  }
  |
  {
    { ALTER | MODIFY } [ COLUMN ] <col1_name>
        SET PROJECTION POLICY <policy_name>
          [ FORCE ]
      | UNSET PROJECTION POLICY
  }
  |
  { ALTER | MODIFY } [ COLUMN ] <col1_name> SET TAG
      <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
      , [ COLUMN ] <col2_name> SET TAG
          <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
  |
  { ALTER | MODIFY } [ COLUMN ] <col1_name> UNSET TAG <tag_name> [ , <tag_name> ... ]
                   , [ COLUMN ] <col2_name> UNSET TAG <tag_name> [ , <tag_name> ... ]
Copy
extTableColumnAction ::=
  {
     ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type> AS ( <expr> )

   | RENAME COLUMN <col_name> TO <new_col_name>

   | DROP [ COLUMN ] [ IF EXISTS ] <col1_name> [, <col2_name> ... ]
  }
Copy
constraintAction ::=
  {
     ADD outoflineConstraint
   | RENAME CONSTRAINT <constraint_name> TO <new_constraint_name>
   | { ALTER | MODIFY } { CONSTRAINT <constraint_name> | PRIMARY KEY | UNIQUE | FOREIGN KEY } ( <col_name> [ , ... ] )
                         [ [ NOT ] ENFORCED ] [ VALIDATE | NOVALIDATE ] [ RELY | NORELY ]
   | DROP { CONSTRAINT <constraint_name> | PRIMARY KEY | UNIQUE | FOREIGN KEY } ( <col_name> [ , ... ] )
                         [ CASCADE | RESTRICT ]
  }

  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 obter sintaxes detalhadas e exemplos de criação/alteração de restrições fora de linha, consulte CREATE | ALTER TABLE … CONSTRAINT.

searchOptimizationAction ::=
  {
     ADD SEARCH OPTIMIZATION [
       ON <search_method_with_target> [ , <search_method_with_target> ... ]
     ]

   | DROP SEARCH OPTIMIZATION [
       ON { <search_method_with_target> | <column_name> | <expression_id> }
          [ , ... ]
     ]

  }
Copy

Para obter mais detalhes, consulte Ações de otimização de pesquisa (searchOptimizationAction).

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

Parâmetros

name

Identificador da tabela a ser alterada. Se o identificador contiver espaços ou caracteres especiais, toda a cadeia de caracteres deverá ser delimitada por aspas duplas. Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

RENAME TO new_table_name

Renomeia a tabela especificada com um novo identificador que não está sendo usado atualmente por nenhuma outra tabela no esquema.

Para obter mais detalhes sobre os identificadores de tabela, consulte Requisitos para identificadores.

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

Nota

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

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

Quando um objeto (tabela, coluna etc.) é renomeado, outros objetos que fazem referência a ele devem ser atualizados com o novo nome.

SWAP WITH target_table_name

A troca renomeia duas tabelas em uma única transação.

Observe que a troca de uma tabela permanente ou transitória por uma tabela temporária, existente apenas durante a sessão do usuário em que foi criada, não é permitida. Esta restrição evita um conflito de nomes que pode ocorrer quando uma tabela temporária é trocada por uma tabela permanente ou transitória, e uma tabela permanente ou transitória existente tem o mesmo nome que a tabela temporária. Para trocar uma tabela permanente ou transitória por uma tabela temporária, use três instruções ALTER TABLE ... RENAME TO: renomear tabela a como c, b como a e c como b.

Nota

Para renomear uma tabela ou trocar duas tabelas, a função usada para realizar a operação deve ter privilégios OWNERSHIP na(s) tabela(s). Além disso, a renomeação de uma tabela exige o privilégio CREATE TABLE no esquema da tabela.

SET ...

Especifica uma ou mais propriedades/parâmetros a serem definidos para a tabela (separados por espaços em branco, vírgulas ou novas linhas):

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

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

FORMAT_NAME = file_format_name

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

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

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

Especifica o tipo de arquivo a ser carregado/descarregado. Opções adicionais específicas de formato podem ser incluídas na cadeia de caracteres. Para obter mais detalhes, consulte Opções do tipo de formato (neste tópico).

Nota

As opções FORMAT_NAME e TYPE são mutuamente exclusivas; você só pode especificar uma ou outra para uma tabela.

STAGE_COPY_OPTIONS = ( ... )

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

DATA_RETENTION_TIME_IN_DAYS = integer

Parâmetro de nível de objeto que modifica o período de retenção da tabela do Time Travel. 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, bem como mais informações sobre parâmetros de objetos, 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

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 a habilitação ou desabilitação do rastreamento de alterações na tabela.

  • TRUE habilita o rastreamento de alterações na tabela. Essa opção adiciona algumas 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 desabilita o rastreamento de alterações na tabela. As colunas ocultas associadas são descartadas da tabela.

DEFAULT_DDL_COLLATION = 'collation_specification'

Determina uma especificação de agrupamento padrão para novas colunas adicionadas à tabela.

A definição do parâmetro não altera a especificação de agrupamento para qualquer coluna existente.

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

ENABLE_SCHEMA_EVOLUTION = { TRUE | FALSE }

Ativa ou desativa as alterações automáticas no esquema da tabela a partir dos dados carregados na tabela dos arquivos de origem, incluindo:

  • Colunas adicionadas.

    Por padrão, a evolução do esquema é limitada a um máximo de 10 colunas adicionadas por operação de carregamento. Para solicitar mais de 10 colunas adicionadas por operação de carga, entre em contato com o suporte Snowflake.

  • A restrição NOT NULL pode ser descartada de qualquer número de colunas ausentes em novos arquivos de dados.

Configurando como TRUE permite a evolução automática do esquema da tabela. O padrão FALSE desativa a evolução automática do esquema da tabela.

Nota

O carregamento de dados de arquivos evolui as colunas da tabela quando todas as condições a seguir forem verdadeiras:

  • A instrução COPY INTO <tabela> inclui a opção MATCH_BY_COLUMN_NAME.

  • A função usada para carregar os dados tem o privilégio EVOLVE SCHEMA ou OWNERSHIP na tabela.

Além disso, para a evolução do esquema com CSV, quando usado com MATCH_BY_COLUMN_NAME e PARSE_HEADER, ERROR_ON_COLUMN_COUNT_MISMATCH deve ser definido como falso.

COMMENT = 'string_literal'

Adiciona um comentário ou substitui o comentário existente da tabela.

UNSET ...

Especifica uma ou mais propriedades/parâmetros a serem desativados para a tabela, o que os restaura aos seus padrões:

  • DATA_RETENTION_TIME_IN_DAYS

  • MAX_DATA_EXTENSION_TIME_IN_DAYS

  • CHANGE_TRACKING

  • DEFAULT_DDL_COLLATION

  • ENABLE_SCHEMA_EVOLUTION

  • COMMENT

Nota

Você não pode usar UNSET para redefinir as opções de formato de arquivo e de cópia. Para redefinir essas opções, você deve usar SET.

Ações de clustering (clusteringAction)

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

Especifica (ou modifica) uma ou mais colunas de tabela ou expressões de coluna como a chave de clustering da tabela. No caso dessas colunas/expressões, o Clustering automático mantém o clustering.

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, consulte Explicação das estruturas de tabela do Snowflake.

RECLUSTER ...

Obsoleto

Executa o reclustering manual e incremental de uma tabela que tem uma chave de clustering definida:

MAX_SIZE = budget_in_bytes

Obsoleto — use um warehouse maior para obter um reclustering manual mais eficiente

Especifica o limite superior da quantidade de dados (em bytes) na tabela para reclustering.

WHERE condition

Especifica uma condição ou faixa na qual é feito o reclustering dos dados na tabela.

Nota

Somente funções com o privilégio OWNERSHIP ou INSERT em uma tabela podem fazer o reclustering da tabela.

SUSPEND | RESUME RECLUSTER

Habilita ou desabilita Clustering automático para a tabela.

DROP CLUSTERING KEY

Descarta a chave de clustering para a tabela.

Para obter mais informações sobre chaves de clustering e reclustering, consulte Explicação das estruturas de tabela do Snowflake.

Ações de coluna da tabela (tableColumnAction)

ADD [ COLUMN ] [ IF NOT EXISTS ] col_name col_data_type . [ DEFAULT default_value | AUTOINCREMENT ... ] . [ inlineConstraint ] [ COLLATE 'collation_specification' ] . [ [ WITH ] MASKING POLICY policy_name ] . [ [ WITH ] PROJECTION POLICY policy_name ] . [ [ WITH ] TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] ) ] [ , ...]

Adiciona uma nova coluna. Você pode especificar um valor padrão, uma restrição inline, uma especificação de agrupamento, uma política de mascaramento e/ou uma ou mais tags.

Um valor padrão para uma coluna que você está adicionando deve ser um valor literal; não pode ser uma expressão ou um valor retornado por uma função. Por exemplo, o comando a seguir retorna um erro esperado:

ALTER TABLE t1 ADD COLUMN c5 VARCHAR DEFAULT 12345::VARCHAR;
Copy
002263 (22000): SQL compilation error:
Invalid column default expression [CAST(12345 AS VARCHAR(16777216))]

Ao criar uma tabela pela primeira vez, você pode usar expressões como valores padrão, mas não ao adicionar colunas.

O valor padrão de uma coluna deve corresponder ao tipo de dados da coluna. Uma tentativa de definir um valor padrão com um tipo de dados não correspondente falha com um erro. Por exemplo:

ALTER TABLE t1 ADD COLUMN c6 DATE DEFAULT '20230101';
Copy
002023 (22000): SQL compilation error:
Expression type does not match column data type, expecting DATE but got VARCHAR(8) for column C6

Para obter detalhes adicionais sobre ações de coluna de tabela, consulte:

As operações ADD COLUMN podem ser realizadas em várias colunas no mesmo comando.

Se não tiver certeza se a coluna já existe, você poderá especificar IF NOT EXISTS ao adicionar a coluna. Se a coluna já existir, ADD COLUMN não terá efeito na coluna existente e não resultará em erro.

Nota

Você não poderá especificar IF NOT EXISTS se também estiver especificando qualquer uma das seguintes opções para a nova coluna:

  • DEFAULT, AUTOINCREMENT ou IDENTITY

  • UNIQUE, PRIMARY KEY ou FOREIGN KEY

RENAME COLUMN col_name to new_col_name

Renomeia a coluna especificada com um novo nome que atualmente não é usado para nenhuma outra coluna da tabela.

Você não pode renomear uma coluna que faz parte de uma chave de clustering.

Quando um objeto (tabela, coluna etc.) é renomeado, outros objetos que fazem referência a ele devem ser atualizados com o novo nome.

DROP COLUMN [ IF EXISTS ] col_name [ CASCADE | RESTRICT ]

Remove a coluna especificada da tabela.

Se não tiver certeza se a coluna já existe, você poderá especificar IF EXISTS ao descartar a coluna. Se a coluna não existir, DROP COLUMN não terá efeito e não resultará em erro.

O descarte de uma coluna é uma operação somente de metadados. Ele não regrava imediatamente a(s) micropartição(ões) e, portanto, não libera imediatamente o espaço utilizado pela coluna. Normalmente, o espaço dentro de uma micropartição individual é liberado na próxima vez em que a micropartição é regravada, o que normalmente ocorre quando uma gravação é feita devido a DML (INSERT, UPDATE, DELETE) ou a reclustering.

Ações de coluna da tabela externa (extTableColumnAction)

Para todas as outras modificações da tabela externa, consulte ALTER EXTERNAL TABLE.

ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type> AS ( <expr> ) [, ...]

Adiciona uma nova coluna à tabela externa.

Se não tiver certeza se a coluna já existe, você poderá especificar IF NOT EXISTS ao adicionar a coluna. Se a coluna já existir, ADD COLUMN não terá efeito na coluna existente e não resultará em erro.

Essa operação pode ser realizada em várias colunas no mesmo comando.

col_name

Cadeia de caracteres que 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.

col_type

Cadeia de caracteres (constante) que especifica o tipo de dados da coluna. O tipo de dados deve corresponder ao resultado de expr da coluna.

Para obter mais detalhes sobre os tipos de dados que podem ser especificados para colunas de tabela, consulte Referência de tipos de dados SQL.

expr

Cadeia de caracteres que especifica a expressão da coluna. Quando consultada, a coluna retorna resultados derivados dessa expressão.

As colunas da tabela externa são colunas virtuais, que são definidas usando uma expressão explícita. Adicione colunas virtuais como expressões usando a coluna VALUE e/ou a pseudocoluna METADATA$FILENAME:

VALUE:

Uma coluna do tipo VARIANT que representa uma única linha no arquivo externo.

CSV:

A coluna VALUE estrutura cada linha como um objeto com elementos identificados pela posição da coluna (ou seja, {c1: <valor_da_coluna_1>, c2: <valor_da_coluna_2>, c3: <valor_da_coluna_1> ...}).

Por exemplo, adicione uma coluna VARCHAR chamada mycol que faça referência à primeira coluna nos arquivos CSV preparados:

mycol varchar as (value:c1::varchar)
Copy
Dados semiestruturados:

Inclua os nomes e valores dos elementos entre aspas duplas. Percorra o caminho na coluna VALUE usando a notação de pontos.

Por exemplo, suponha que o seguinte represente uma única linha de dados semiestruturados em um arquivo preparado:

{ "a":"1", "b": { "c":"2", "d":"3" } }
Copy

Adicione uma coluna VARCHAR chamada mycol que faça referência ao elemento c repetido aninhado no arquivo preparado:

mycol varchar as (value:"b"."c"::varchar)
Copy
METADATA$FILENAME:

Uma pseudocoluna que identifica o nome de cada arquivo de dados preparado incluído na tabela externa, incluindo seu caminho no estágio.

RENAME COLUMN col_name to new_col_name

Renomeia a coluna especificada com um novo nome que atualmente não é usado para nenhuma outra coluna na tabela externa.

DROP COLUMN [ IF EXISTS ] col_name

Remove a coluna especificada da tabela externa.

Se não tiver certeza se a coluna já existe, você poderá especificar IF EXISTS ao descartar a coluna. Se a coluna não existir, DROP COLUMN não terá efeito e não resultará em erro.

Ações de restrição (constraintAction)

ADD CONSTRAINT

Adiciona uma restrição de integridade fora de linha a uma ou mais colunas da tabela. Para adicionar uma restrição em linha (para uma coluna), consulte Ações de coluna (neste tópico).

RENAME CONSTRAINT constraint_name TO new_constraint_name

Renomeia a restrição especificada.

ALTER | MODIFY CONSTRAINT ...

Altera as propriedades da restrição especificada.

DROP CONSTRAINT constraint_name | PRIMARY KEY | UNIQUE | FOREIGN KEY ( col_name [ , ... ] ) [ CASCADE | RESTRICT ]

Descarta a restrição especificada para a coluna ou o conjunto de colunas especificado.

Para sintaxes detalhadas e exemplos de adição ou alteração de restrições, consulte CREATE | ALTER TABLE … CONSTRAINT.

Política de governança de dados e ações de tag (dataGovnPolicyTagAction)

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 informações sobre como especificar tags em uma instrução, consulte Cotas de tags para objetos e colunas.

policy_name

Identificador da política; deve ser único para seu esquema.

As cláusulas a seguir se aplicam a todos os tipos de tabelas que suportam políticas de acesso a linhas, como, entre outras, tabelas, exibições e tabelas de eventos. Para simplificar, as cláusulas referem-se apenas a “tabela”.

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

Adiciona um política de acesso a linhas à tabela.

Pelo menos um nome de coluna deve ser especificado. Colunas adicionais podem ser especificadas com uma vírgula que separa cada nome de coluna. Use esta expressão para adicionar uma política de acesso a linhas tanto a uma tabela de eventos como a uma tabela externa.

DROP ROW ACCESS POLICY policy_name

Descarta uma política de acesso a linhas da tabela.

Use esta cláusula para descartar a política da tabela.

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

Descarta a política de acesso a linhas definida na tabela e adiciona uma política de acesso a linhas à mesma tabela em uma única instrução SQL.

DROP ALL ROW ACCESS POLICIES

Descarta todas as associações de política de acesso a linhas de uma tabela.

Esta expressão é útil quando uma política de acesso a linhas é descartada de um esquema antes de descartar a política de uma tabela de eventos. Use esta expressão para descartar as associações de política de acesso a linhas da tabela.

SET AGGREGATION POLICY policy_name [ FORCE ]

Atribui uma política de agregação à tabela. Use o parâmetro opcional FORCE para substituir atomicamente uma política de agregação existente pela nova política de agregação.

UNSET AGGREGATION POLICY

Desanexa uma política de agregação da tabela.

{ ALTER | MODIFY } [ COLUMN ] ...
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.

FORCE

Substitui uma política de mascaramento ou projeção que está atualmente definida em uma coluna por uma política diferente em uma única instrução.

Observe que a utilização da palavra-chave FORCE com uma política de mascaramento exige o tipo de dados da política na instrução ALTER TABLE (isto é, STRING) para corresponder ao tipo de dados da política de mascaramento atualmente definida na coluna (isto é, STRING).

Se uma política de mascaramento não estiver definida atualmente na coluna, a especificação dessa palavra-chave não tem efeito.

Para obter mais detalhes, consulte: Substituição de uma política de mascaramento em uma coluna ou Substituir uma política de projeção.

Ações de otimização de pesquisa (searchOptimizationAction)

ADD SEARCH OPTIMIZATION

Adiciona uma otimização de pesquisa para toda a tabela ou, se você especificar a cláusula opcional ON, para colunas específicas.

Nota:

  • A otimização de pesquisa pode ser de cara manutenção, especialmente se os dados na tabela mudam com frequência. Para obter mais informações, consulte Estimativa e gerenciamento de custos de otimização de pesquisa.

  • Se você tentar adicionar otimização de pesquisa em uma exibição materializada, o Snowflake retornará uma mensagem de erro.

ON search_method_with_target [, search_method_with_target ... ]

Especifica que você deseja configurar a otimização de pesquisa para colunas ou campos VARIANT específicos (e não para toda a tabela).

Para search_method_with_target, use uma expressão com a seguinte sintaxe:

<search_method>(<target> [, ...])
Copy

Onde:

  • search_method especifica um dos seguintes métodos que otimiza as consultas para um determinado tipo de predicado:

    Método de pesquisa

    Descrição

    EQUALITY

    Igualdade e predicados IN.

    SUBSTRING

    Predicados que correspondem a subcadeias de caracteres e expressões regulares (por exemplo, [ NOT ] LIKE, [ NOT ] ILIKE, [ NOT ] RLIKE, REGEXP_LIKE, etc.)

    GEO

    Predicados que usam tipos GEOGRAPHY.

  • target especifica a coluna, campo VARIANT ou um asterisco (*).

    Dependendo do valor de search_method, você pode especificar uma coluna ou campo VARIANT de um dos seguintes tipos:

    Método de pesquisa

    Alvos suportados

    EQUALITY

    Colunas de tipos de dados numéricos, cadeias de caracteres, binários e VARIANT, incluindo caminhos para campos em VARIANTs.

    Para especificar um campo VARIANT, use notação de ponto ou colchetes (por exemplo, my_column:my_field_name.my_nested_field_name ou my_column['my_field_name']['my_nested_field_name']). Você também pode usar um caminho delimitado por dois pontos para o campo (por exemplo, my_column:my_field_name:my_nested_field_name).

    Quando você especifica um campo VARIANT, a configuração se aplica a todos os campos aninhados sob esse campo. Por exemplo, se você especificar ON EQUALITY(src:a.b):

    • Essa configuração pode melhorar as consultas on src:a.b e em qualquer campo aninhado (por exemplo, src:a.b.c, src:a.b.c.d, etc.).

    • Essa configuração não afeta consultas que não utilizam o prefixo src:a.b (por exemplo, src:a, src:z, etc.).

    SUBSTRING

    Colunas de tipos de dados de cadeia de caracteres ou VARIANT, incluindo caminhos para campos em VARIANTs. Especifique caminhos para campos conforme descrito acima em EQUALITY; pesquisas em campos aninhados são melhoradas da mesma maneira.

    GEO

    Limitações do tipo de dados GEOGRAPHY

    Para especificar todas as colunas aplicáveis na tabela como alvos, use um asterisco (*).

    Note que você não pode especificar ao mesmo tempo um asterisco e nomes de colunas específicos para um determinado método de busca. Entretanto, você pode especificar um asterisco em diferentes métodos de busca.

    Por exemplo, você pode especificar as seguintes expressões:

    -- Allowed
    ON SUBSTRING(*)
    ON EQUALITY(*), SUBSTRING(*), GEO(*)
    
    Copy

    Você não pode especificar as seguintes expressões:

    -- Not allowed
    ON EQUALITY(*, c1)
    ON EQUALITY(c1, *)
    ON EQUALITY(v1:path, *)
    ON EQUALITY(c1), EQUALITY(*)
    
    Copy

Para especificar mais de um método de busca em um alvo, use uma vírgula para separar cada método seguinte do alvo:

ALTER TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1), EQUALITY(c2, c3);
Copy

Se você executar o comando ALTER TABLE … ADD SEARCH OPTIMIZATION ON … várias vezes na mesma tabela, cada comando seguinte será adicionado à configuração existente para a tabela. Por exemplo, suponha que você execute os seguintes comandos:

ALTER TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2);
ALTER TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c3, c4);
Copy

Isso acrescenta os predicados de igualdade para as colunas c1, c2, c3 e c4 à configuração da tabela. Isso é equivalente a executar o comando:

ALTER TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2, c3, c4);
Copy

Para exemplos, consulte Habilitação da otimização de pesquisa para colunas específicas.

DROP SEARCH OPTIMIZATION

Remove a otimização de pesquisa para toda a tabela ou, se você especificar a cláusula opcional ON, de colunas específicas.

Nota:

  • Se uma tabela tiver a propriedade de otimização de pesquisa, descartar a tabela e cancelar o descarte preservará a propriedade de otimização de pesquisa.

  • Remover a propriedade de otimização de pesquisa de uma tabela e voltar a adicioná-la incorre no mesmo custo que adicioná-la pela primeira vez.

ON search_method_with_target | column_name | expression_id [, ... ]

Especifica que você deseja remover a configuração de otimização de pesquisa para colunas ou campos VARIANT específicos (em vez de remover a otimização de pesquisa para toda a tabela).

Para identificar a configuração da coluna a ser removida, especifique uma das seguintes opções:

  • Para search_method_with_target, especifique um método para otimizar consultas para um ou mais alvos específicos, que podem ser colunas ou campos VARIANT. Use a sintaxe descrita anteriormente.

  • Para column_name, especifique o nome da coluna configurada para otimização de pesquisa. Especificar o nome da coluna remove todas as expressões para a coluna, incluindo expressões que utilizam campos VARIANT na coluna.

  • Para expression_id, especifique a ID para uma expressão listada na saída do comando DESCRIBE SEARCH OPTIMIZATION.

Para especificar mais de um deles, use uma vírgula entre os itens.

Você pode especificar qualquer combinação de métodos de pesquisa com alvos, nomes de colunas e IDs de expressão.

Para exemplos, consulte Descarte da otimização de pesquisa para colunas específicas.

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 prefixo 0x ou \x). Por exemplo, para registros delimitados por acento circunflexo (^), especifique o valor octal (\\136) ou hexadecimal (0x5e).

Caracteres multibyte:

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

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

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

Também aceita um valor de NONE.

Padrão:
Carregamento de dados:

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

Descarregamento de dados:

Caractere de nova linha (\n).

FIELD_DELIMITER = 'character' | NONE
Uso:

Carregamento de dados, descarregamento de dados e tabelas externas

Definição:

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

Caracteres de byte único:

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

Caracteres multibyte:

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

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

Nota

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

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

Também aceita um valor de NONE.

Padrão:

vírgula (,)

FILE_EXTENSION = 'string' | NONE
Uso:

Apenas descarregamento de dados

Definição:

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

Padrão:

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

Nota

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

PARSE_HEADER = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

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

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

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

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

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

Padrão: FALSE

SKIP_HEADER = integer
Uso:

Carregamento de dados e tabelas externas

Definição:

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

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

Padrão:

0

SKIP_BLANK_LINES = TRUE | FALSE
Uso:

Carregamento de dados e tabelas externas

Definição:

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

Padrão: FALSE

DATE_FORMAT = 'string' | AUTO
Uso:

Carregamento e descarregamento de dados

Definição:

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

Padrão:

AUTO

TIME_FORMAT = 'string' | AUTO
Uso:

Carregamento e descarregamento de dados

Definição:

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

Padrão:

AUTO

TIMESTAMP_FORMAT = string' | AUTO
Uso:

Carregamento e descarregamento de dados

Definição:

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

Padrão:

AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8
Uso:

Carregamento e descarregamento de dados

Definição:

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

Padrão:

HEX

ESCAPE = 'character' | NONE
Uso:

Carregamento e descarregamento de dados

Definição:

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

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

Carregamento de dados:

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

Nota

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

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

Descarregamento de dados:

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

Padrão:

NONE

ESCAPE_UNENCLOSED_FIELD = 'character' | NONE
Uso:

Carregamento de dados, descarregamento de dados e tabelas externas

Definição:

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

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

Carregamento de dados:

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

Nota

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

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

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

Descarregamento de dados:

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

Padrão:

barra invertida (\\)

TRIM_SPACE = TRUE | FALSE
Uso:

Carregamento de dados e tabelas externas

Definição:

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

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

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

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

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

Padrão:

FALSE

FIELD_OPTIONALLY_ENCLOSED_BY = 'character' | NONE
Uso:

Carregamento de dados, descarregamento de dados e tabelas externas

Definição:

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

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

A ""B"" C

Padrão:

NONE

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

Carregamento de dados, descarregamento de dados e tabelas externas

Definição:

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

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

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

    Por exemplo:

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

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

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

Padrão:

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

ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

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

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

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

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

Padrão:

TRUE

Nota

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

REPLACE_INVALID_CHARACTERS = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

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

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

Padrão:

FALSE

EMPTY_FIELD_AS_NULL = TRUE | FALSE
Uso:

Carregamento de dados, descarregamento de dados e tabelas externas

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

    Se definido como FALSE, o Snowflake tenta converter um campo vazio no tipo de coluna correspondente. Uma cadeia de caracteres vazia é inserida em colunas do tipo STRING. Para outros tipos de colunas, o comando COPY produz um erro.

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

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

Padrão:

TRUE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

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

Padrão:

TRUE

ENCODING = 'string'
Uso:

Carregamento de dados e tabelas externas

Definição:

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

Conjunto de caracteres

Valor ENCODING 

Linguagens suportadas

Notas

Big5

BIG5

Chinês Tradicional

EUC-JP

EUCJP

Japonês

EUC-KR

EUCKR

Coreano

GB18030

GB18030

Chinês

IBM420

IBM420

Árabe

IBM424

IBM424

Hebraico

IBM949

IBM949

Coreano

ISO-2022-CN

ISO2022CN

Chinês simplificado

ISO-2022-JP

ISO2022JP

Japonês

ISO-2022-KR

ISO2022KR

Coreano

ISO-8859-1

ISO88591

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

ISO-8859-2

ISO88592

Tcheco, Húngaro, Polonês, Romeno

ISO-8859-5

ISO88595

Russo

ISO-8859-6

ISO88596

Árabe

ISO-8859-7

ISO88597

Grego

ISO-8859-8

ISO88598

Hebraico

ISO-8859-9

ISO88599

Turco

ISO-8859-15

ISO885915

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

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

KOI8-R

KOI8R

Russo

Shift_JIS

SHIFTJIS

Japonês

UTF-8

UTF8

Todos os idiomas

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

UTF-16

UTF16

Todos os idiomas

UTF-16BE

UTF16BE

Todos os idiomas

UTF-16LE

UTF16LE

Todos os idiomas

UTF-32

UTF32

Todos os idiomas

UTF-32BE

UTF32BE

Todos os idiomas

UTF-32LE

UTF32LE

Todos os idiomas

windows-949

WINDOWS949

Coreano

windows-1250

WINDOWS1250

Tcheco, Húngaro, Polonês, Romeno

windows-1251

WINDOWS1251

Russo

windows-1252

WINDOWS1252

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

windows-1253

WINDOWS1253

Grego

windows-1254

WINDOWS1254

Turco

windows-1255

WINDOWS1255

Hebraico

windows-1256

WINDOWS1256

Árabe

Padrão:

UTF8

Nota

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

TYPE = JSON

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

Carregamento de dados e tabelas externas

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

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

Valores:

Valores suportados

Notas

AUTO

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

GZIP

BZ2

BROTLI

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

ZSTD

Zstandard v0.8 (e superior) é suportado.

DEFLATE

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

RAW_DEFLATE

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

NONE

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

Padrão:

AUTO

DATE_FORMAT = 'string' | AUTO
Uso:

Somente carregamento de dados

Definição:

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

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

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

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

Padrão:

AUTO

TIME_FORMAT = 'string' | AUTO
Uso:

Somente carregamento de dados

Definição:

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

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

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

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

Padrão:

AUTO

TIMESTAMP_FORMAT = string' | AUTO
Uso:

Somente carregamento de dados

Definição:

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

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

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

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

Padrão:

AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8
Uso:

Somente carregamento de dados

Definição:

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

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

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

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

Padrão:

HEX

TRIM_SPACE = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

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

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

Padrão:

FALSE

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

Somente carregamento de dados

Definição:

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

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

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

Por exemplo:

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

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

Padrão:

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

FILE_EXTENSION = 'string' | NONE
Uso:

Apenas descarregamento de dados

Definição:

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

Padrão:

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

ENABLE_OCTAL = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

Padrão:

FALSE

ALLOW_DUPLICATE = TRUE | FALSE
Uso:

Carregamento de dados e tabelas externas

Definição:

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

Padrão:

FALSE

STRIP_OUTER_ARRAY = TRUE | FALSE
Uso:

Carregamento de dados e tabelas externas

Definição:

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

Padrão:

FALSE

STRIP_NULL_VALUES = TRUE | FALSE
Uso:

Carregamento de dados e tabelas externas

Definição:

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

Antes

Depois

[null]

[]

[null,null,3]

[,,3]

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

{"c":123}

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

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

Padrão:

FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE
Uso:

Carregamento de dados e tabela externa

Definição:

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

Valores:

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

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

Padrão:

FALSE

IGNORE_UTF8_ERRORS = TRUE | FALSE
Uso:

Carregamento de dados e tabela externa

Definição:

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

Valores:

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

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

Padrão:

FALSE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

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

Padrão:

TRUE

TYPE = AVRO

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

Somente carregamento de dados

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

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

Valores:

Valores suportados

Notas

AUTO

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

GZIP

BROTLI

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

ZSTD

Zstandard v0.8 (e superior) é suportado.

DEFLATE

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

RAW_DEFLATE

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

NONE

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

Padrão:

AUTO.

Nota

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

TRIM_SPACE = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

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

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

Padrão:

FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE
Uso:

Carregamento de dados e tabela externa

Definição:

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

Valores:

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

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

Padrão:

FALSE

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

Somente carregamento de dados

Definição:

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

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

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

Por exemplo:

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

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

Padrão:

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

TYPE = ORC

TRIM_SPACE = TRUE | FALSE
Uso:

Carregamento de dados e tabelas externas

Definição:

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

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

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

Padrão:

FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE
Uso:

Carregamento de dados e tabela externa

Definição:

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

Valores:

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

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

Padrão:

FALSE

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

Carregamento de dados e tabelas externas

Definição:

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

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

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

Por exemplo:

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

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

Padrão:

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

TYPE = PARQUET

COMPRESSION = AUTO | LZO | SNAPPY | NONE
Uso:

Carregamento de dados, descarregamento de dados e tabelas externas

Definição:

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

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

Valores:

Valores suportados

Notas

AUTO

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

LZO

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

SNAPPY

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

NONE

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

Padrão:

AUTO

SNAPPY_COMPRESSION = TRUE | FALSE
Uso:

Apenas descarregamento de dados

Valores suportados

Notas

AUTO

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

SNAPPY

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

NONE

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

Definição:

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

Nota

Obsoleto. Em vez disso, use COMPRESSION = SNAPPY.

Limitações:

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

Padrão:

TRUE

BINARY_AS_TEXT = TRUE | FALSE
Uso:

Carregamento de dados e tabelas externas

Definição:

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

Padrão:

TRUE

Nota

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

TRIM_SPACE = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

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

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

Padrão:

FALSE

USE_LOGICAL_TYPE = TRUE | FALSE
Uso:

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

Definição:

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

Limitações:

Não há suporte para descarregamento de dados.

REPLACE_INVALID_CHARACTERS = TRUE | FALSE
Uso:

Carregamento de dados e tabela externa

Definição:

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

Valores:

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

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

Padrão:

FALSE

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

Somente carregamento de dados

Definição:

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

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

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

Por exemplo:

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

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

Padrão:

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

TYPE = XML

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

Somente carregamento de dados

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

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

Valores:

Valores suportados

Notas

AUTO

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

GZIP

BZ2

BROTLI

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

ZSTD

Zstandard v0.8 (e superior) é suportado.

DEFLATE

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

RAW_DEFLATE

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

NONE

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

Padrão:

AUTO

IGNORE_UTF8_ERRORS = TRUE | FALSE
Uso:

Carregamento de dados e tabela externa

Definição:

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

Valores:

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

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

Padrão:

FALSE

PRESERVE_SPACE = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

Padrão:

FALSE

STRIP_OUTER_ELEMENT = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

Padrão:

FALSE

DISABLE_SNOWFLAKE_DATA = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

Padrão:

FALSE

DISABLE_AUTO_CONVERT = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

Padrão:

FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE
Uso:

Carregamento de dados e tabela externa

Definição:

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

Valores:

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

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

Padrão:

FALSE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

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

Padrão:

TRUE

Opções de cópia (copyOptions)

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):

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

Somente carregamento de dados

Definição:

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

Importante

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

Valores:
  • CONTINUE

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

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

  • SKIP_FILE

    Ignorar um arquivo quando for encontrado um erro.

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

    Padrões adicionais:

    SKIP_FILE_num (por exemplo, SKIP_FILE_10)

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

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

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

  • ABORT_STATEMENT

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

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

Padrão:
Carregamento em massa utilizando COPY:

ABORT_STATEMENT

Snowpipe:

SKIP_FILE

SIZE_LIMIT = num
Uso:

Somente carregamento de dados

Definição:

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

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

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

Padrão:

nulo (sem limite de tamanho)

PURGE = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

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

Padrão:

FALSE

RETURN_FAILED_ONLY = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

Padrão:

FALSE

MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE
Uso:

Somente carregamento de dados

Definição:

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

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

  • JSON

  • Avro

  • ORC

  • Parquet

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

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

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

Valores:
CASE_SENSITIVE | CASE_INSENSITIVE

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

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

Nota

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

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

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

NONE

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

Nota

As seguintes limitações se aplicam atualmente:

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

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

Padrão:

NONE

ENFORCE_LENGTH = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

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

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

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

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

Nota

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

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

Padrão:

TRUE

TRUNCATECOLUMNS = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

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

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

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

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

Nota

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

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

Padrão:

FALSE

FORCE = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

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

Padrão:

FALSE

Notas de uso

  • As mudanças em uma tabela não são automaticamente propagadas para as exibições criadas sobre essa tabela. Por exemplo, se você descartar uma coluna em uma tabela, e uma exibição for definida para incluir essa coluna, a exibição torna-se inválida; a exibição não é ajustada para remover a coluna.

  • O descarte de uma coluna não libera o espaço de armazenamento da coluna de imediato.

    • O espaço em cada micropartição não é recuperado até que essa micropartição seja regravada. Operações de gravação (inserir, atualizar, excluir etc.) em 1 ou mais linhas nessa micropartição faz com que a micropartição seja regravada. Se quiser forçar a recuperação do espaço, você pode seguir estas etapas:

      1. Use uma instrução CREATE TABLE AS SELECT (CTAS) para criar uma nova tabela que contenha apenas as colunas da tabela antiga que você deseja manter.

      2. Defina o parâmetro DATA_RETENTION_TIME_IN_DAYS como 0 para a tabela antiga (opcional).

      3. Descarte a tabela antiga.

    • Se a tabela for protegida pelo recurso Time Travel, o espaço utilizado pelo armazenamento do Time Travel só será recuperado quando o período de retenção do Time Travel expirar.

  • Se uma nova coluna com um valor padrão for adicionada a uma tabela com linhas existentes, todas as linhas existentes serão preenchidas com o valor padrão.

  • Atualmente, não é possível adicionar uma nova coluna com um valor padrão que contenha uma função. O seguinte erro ocorre:

    Invalid column default expression (expr)

  • Para alterar uma tabela, você deve estar usando uma função que tenha privilégio de propriedade para a tabela.

  • Para adicionar clustering a uma tabela, você também deve ter privilégios USAGE ou OWNERSHIP para o esquema e o banco de dados que contém a tabela.

  • Para políticas de mascaramento:

    • A cláusula USING e a palavra-chave FORCE são ambas opcionais; nenhuma delas é necessária para definir uma política de mascaramento em uma coluna. A cláusula USING e a palavra-chave FORCE podem ser usadas separadamente ou em conjunto. Para obter mais detalhes, consulte:

    • 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 modificar uma ou mais colunas da tabela com uma política de mascaramento ou a própria tabela com uma política de acesso a linhas, use a função POLICY_CONTEXT para simular uma consulta na(s) coluna(s) protegida(s) por uma política de mascaramento e na tabela protegida por uma política de acesso a linhas.

  • Para políticas de acesso a linhas:

    • O Snowflake oferece suporte à adição e ao descarte de políticas de acesso a linhas em uma única instrução SQL.

      Por exemplo, para substituir uma política de acesso a linhas que já esteja definida em uma tabela por uma política diferente, primeiro descarte a política de acesso a linhas e depois adicione a nova política.

    • Para determinado recurso (ou seja, tabela ou exibição), para ADD ou DROP uma política de acesso a linhas, você deve ter o privilégio APPLY ROW ACCESS POLICY no esquema, ou o privilégio OWNERSHIP no recurso e o privilégio APPLY no recurso da política de acesso a linhas.

    • Uma tabela ou exibição só pode ser protegida por uma política de acesso a linhas de cada vez. A adição de uma política falhará se o corpo da política se referir a uma coluna de exibição ou tabela protegida por uma política de acesso a linhas ou à coluna protegida por uma política de mascaramento.

      Da mesma forma, a adição de uma política de mascaramento a uma coluna da tabela falhará se o corpo da política de mascaramento se referir a uma tabela protegida por uma política de acesso a linhas ou outra política de mascaramento.

    • As políticas de acesso a linhas não podem ser aplicadas a exibições do sistema ou funções de tabela.

    • Semelhante a outras operações DROP <objeto>, o Snowflake retornará um erro se tentar descartar uma política de acesso a linhas de um recurso que não tenha uma política de acesso a linhas adicionada a ele.

    • Se um objeto tiver uma política de acesso a linhas e uma ou mais políticas de mascaramento, a política de acesso a linhas será avaliada primeiro.

  • Se você criar uma chave estrangeira, as colunas da cláusula REFERENCES deverão ser listadas na mesma ordem em que as colunas foram listadas para a chave primária. Por exemplo:

    create table parent ... constraint primary_key_1 primary key (c_1, c_2) ...
    create table child  ... constraint foreign_key_1 foreign key (...) REFERENCES parent (c_1, c_2) ...
    
    Copy

    Em ambos os casos, a ordem das colunas é c_1, c_2. Se a ordem das colunas na chave estrangeira tivesse sido diferente (por exemplo, c_2, c_1), a tentativa de criar a chave estrangeira teria falhado.

  • 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.

  • ALTER TABLE … CHANGE_TRACKING = TRUE

    • Quando uma tabela é alterada para permitir o rastreamento de alterações, a tabela é bloqueada durante 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.

  • Índices em tabelas híbridas:

    • Quando você usa o comando ALTER TABLE para adicionar ou descartar uma restrição exclusiva ou de chave estrangeira em uma tabela híbrida, o índice correspondente também será criado ou descartado. Para obter mais informações sobre índices em uma tabela híbrida, consulte CREATE INDEX.

    • As restrições de chave estrangeira são suportadas apenas em tabelas híbridas armazenadas no mesmo banco de dados. A capacidade de mover uma tabela híbrida de um banco de dados para outro não é suportada. As restrições de chave primária, exclusiva e de chave estrangeira definidas em tabelas híbridas têm seu campo RELY marcado como TRUE.

    • Uma coluna usada por um índice não pode ser descartada antes que o índice correspondente seja descartado.

Exemplos

As seções a seguir fornecem exemplos de uso do comando ALTER COLUMN:

Renomeação de uma tabela

O seguinte cria uma tabela chamada t1:

CREATE OR REPLACE TABLE t1(a1 number);
Copy
SHOW TABLES LIKE 't1';
Copy
+-------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+-----------------+-------------+-------------------------+-----------------+----------+--------+
| created_on                    | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes | owner  | retention_time | change_tracking | is_external | enable_schema_evolution | owner_role_type | is_event | budget |
|-------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+-----------------+-------------+-------------------------+-----------------+----------+--------|
| 2023-10-19 10:37:04.858 -0700 | T1   | TESTDB        | MY_SCHEMA   | TABLE |         |            |    0 |     0 | PUBLIC | 1              | OFF             | N           | N                       | ROLE            | N        | NULL   |
+-------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+-----------------+-------------+-------------------------+-----------------+----------+--------+

A instrução a seguir altera o nome da tabela para tt1:

ALTER TABLE t1 RENAME TO tt1;
Copy
SHOW TABLES LIKE 'tt1';
Copy
+-------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+-----------------+-------------+-------------------------+-----------------+----------+--------+
| created_on                    | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes | owner  | retention_time | change_tracking | is_external | enable_schema_evolution | owner_role_type | is_event | budget |
|-------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+-----------------+-------------+-------------------------+-----------------+----------+--------|
| 2023-10-19 10:37:04.858 -0700 | TT1  | TESTDB        | MY_SCHEMA   | TABLE |         |            |    0 |     0 | PUBLIC | 1              | OFF             | N           | N                       | ROLE            | N        | NULL   |
+-------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+-----------------+-------------+-------------------------+-----------------+----------+--------+

Troca de tabelas

As instruções a seguir criam tabelas chamadas t1 e t2:

CREATE OR REPLACE TABLE t1(a1 NUMBER, a2 VARCHAR, a3 DATE);
CREATE OR REPLACE TABLE t2(b1 VARCHAR);
Copy
DESC TABLE t1;
Copy
+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type              | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| A1   | NUMBER(38,0)      | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A2   | VARCHAR(16777216) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A3   | DATE              | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
DESC TABLE t2;
Copy
+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type              | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| B1   | VARCHAR(16777216) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

A instrução a seguir troca a tabela t1 pela tabela t2:

ALTER TABLE t1 SWAP WITH t2;
Copy
DESC TABLE t1;
Copy
+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type              | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| B1   | VARCHAR(16777216) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
DESC TABLE t2;
Copy
+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type              | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| A1   | NUMBER(38,0)      | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A2   | VARCHAR(16777216) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A3   | DATE              | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

Adição de colunas

O seguinte cria uma tabela chamada t1:

CREATE OR REPLACE TABLE t1(a1 NUMBER);
Copy
DESC TABLE t1;
Copy
+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type         | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| A1   | NUMBER(38,0) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

A instrução a seguir adiciona uma coluna chamada a2 a esta tabela:

ALTER TABLE t1 ADD COLUMN a2 NUMBER;
Copy

A instrução a seguir adiciona uma coluna chamada a3 com uma restrição NOT NULL:

ALTER TABLE t1 ADD COLUMN a3 NUMBER NOT NULL;
Copy

A instrução a seguir adiciona uma coluna chamada a4 com um valor padrão e uma restrição NOT NULL:

ALTER TABLE t1 ADD COLUMN a4 NUMBER DEFAULT 0 NOT NULL;
Copy

A instrução a seguir adiciona uma coluna VARCHAR de nome a5 com uma especificação de agrupamento específica do idioma:

ALTER TABLE t1 ADD COLUMN a5 VARCHAR COLLATE 'en_US';
Copy
DESC TABLE t1;
Copy
+------+-----------------------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type                              | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+-----------------------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| A1   | NUMBER(38,0)                      | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A2   | NUMBER(38,0)                      | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A3   | NUMBER(38,0)                      | COLUMN | N     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A4   | NUMBER(38,0)                      | COLUMN | N     | 0       | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A5   | VARCHAR(16777216) COLLATE 'en_us' | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+-----------------------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

A instrução a seguir usa a cláusula IF NOT EXISTS para adicionar uma coluna chamada a2 somente se a coluna não existir. Existe uma coluna chamada a2. A especificação da cláusula IF NOT EXISTS evita que a instrução falhe com um erro.

ALTER TABLE t1 ADD COLUMN IF NOT EXISTS a2 NUMBER;
Copy

Conforme mostrado na saída do comando DESCRIBE TABLE, a instrução acima não tem efeito na coluna existente chamada a2:

DESC TABLE t1;
Copy
+------+-----------------------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type                              | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+-----------------------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| A1   | NUMBER(38,0)                      | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A2   | NUMBER(38,0)                      | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A3   | NUMBER(38,0)                      | COLUMN | N     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A4   | NUMBER(38,0)                      | COLUMN | N     | 0       | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A5   | VARCHAR(16777216) COLLATE 'en_us' | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+-----------------------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

Como renomear colunas

A instrução a seguir altera o nome da coluna a1 para b1:

ALTER TABLE t1 RENAME COLUMN a1 TO b1;
Copy
DESC TABLE t1;
Copy
+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type         | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| B1   | NUMBER(38,0) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A2   | NUMBER(38,0) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A3   | NUMBER(38,0) | COLUMN | N     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A4   | NUMBER(38,0) | COLUMN | N     | 0       | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

Descarte de colunas

A instrução a seguir descarta a coluna a2:

ALTER TABLE t1 DROP COLUMN a2;
Copy
DESC TABLE t1;
Copy
+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type         | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| B1   | NUMBER(38,0) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A3   | NUMBER(38,0) | COLUMN | N     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A4   | NUMBER(38,0) | COLUMN | N     | 0       | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

A instrução a seguir usa a cláusula IF EXISTS para descartar uma coluna chamada a2 somente se a coluna existir. Não existe nenhuma coluna chamada a2. A especificação da cláusula IF EXISTS evita que a instrução falhe com um erro.

ALTER TABLE t1 DROP COLUMN IF EXISTS a2;
Copy

Conforme mostrado na saída do comando DESCRIBE TABLE, a instrução acima não tem efeito na tabela existente:

+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type         | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| B1   | NUMBER(38,0) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A3   | NUMBER(38,0) | COLUMN | N     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A4   | NUMBER(38,0) | COLUMN | N     | 0       | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
Copy

Adição, renomeação e descarte de colunas em uma tabela externa

A instrução a seguir cria uma tabela externa chamada exttable1:

CREATE EXTERNAL TABLE exttable1
  LOCATION=@mystage/logs/
  AUTO_REFRESH = true
  FILE_FORMAT = (TYPE = PARQUET)
  ;
Copy
DESC EXTERNAL TABLE exttable1;
Copy
+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+
| name      | type              | kind      | null? | default | primary key | unique key | check | expression                                               | comment               |
|-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------|
| VALUE     | VARIANT           | COLUMN    | Y     | NULL    | N           | N          | NULL  | NULL                                                     | The value of this row |
+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+

A instrução a seguir adiciona uma nova coluna chamada a1 à tabela externa:

ALTER TABLE exttable1 ADD COLUMN a1 VARCHAR AS (value:a1::VARCHAR);
Copy
DESC EXTERNAL TABLE exttable1;
Copy
+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+
| name      | type              | kind      | null? | default | primary key | unique key | check | expression                                               | comment               |
|-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------|
| VALUE     | VARIANT           | COLUMN    | Y     | NULL    | N           | N          | NULL  | NULL                                                     | The value of this row |
| A1        | VARCHAR(16777216) | VIRTUAL   | Y     | NULL    | N           | N          | NULL  | TO_CHAR(GET(VALUE, 'a1'))                                | NULL                  |
+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+

A instrução a seguir altera o nome da coluna a1 para b1:

ALTER TABLE exttable1 RENAME COLUMN a1 TO b1;
Copy
DESC EXTERNAL TABLE exttable1;
Copy
+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+
| name      | type              | kind      | null? | default | primary key | unique key | check | expression                                               | comment               |
|-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------|
| VALUE     | VARIANT           | COLUMN    | Y     | NULL    | N           | N          | NULL  | NULL                                                     | The value of this row |
| B1        | VARCHAR(16777216) | VIRTUAL   | Y     | NULL    | N           | N          | NULL  | TO_CHAR(GET(VALUE, 'a1'))                                | NULL                  |
+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+

A instrução a seguir descarta a coluna chamada b1:

ALTER TABLE exttable1 DROP COLUMN b1;
Copy
DESC EXTERNAL TABLE exttable1;
Copy
+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+
| name      | type              | kind      | null? | default | primary key | unique key | check | expression                                               | comment               |
|-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------|
| VALUE     | VARIANT           | COLUMN    | Y     | NULL    | N           | N          | NULL  | NULL                                                     | The value of this row |
+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+

Alteração da ordem das chaves de clustering

A instrução a seguir cria uma tabela chamada t1 que é clusterizada pelas colunas id e date:

CREATE OR REPLACE TABLE T1 (id NUMBER, date TIMESTAMP_NTZ, name STRING) CLUSTER BY (id, date);
Copy
SHOW TABLES LIKE 'T1';
Copy
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
           created_on            | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes |    owner     | retention_time |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
 Tue, 21 Jun 2016 15:42:12 -0700 | T1   | TESTDB        | TESTSCHEMA  | TABLE |         | (ID,DATE)  | 0    | 0     | ACCOUNTADMIN | 1              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+

A instrução a seguir altera a ordem da chave de clustering:

ALTER TABLE t1 CLUSTER BY (date, id);
Copy
SHOW TABLES LIKE 'T1';
Copy
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
           created_on            | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes |    owner     | retention_time |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
 Tue, 21 Jun 2016 15:42:12 -0700 | T1   | TESTDB        | TESTSCHEMA  | TABLE |         | (DATE,ID)  | 0    | 0     | ACCOUNTADMIN | 1              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+

Adição e descarte das políticas de acesso a linhas

O exemplo seguinte adiciona uma política de acesso a linhas a uma tabela enquanto especifica uma única coluna. Após definir a política, você pode verificar o esquema de informação.

alter table t1 add row access policy rap_t1 on (empl_id);
Copy

O exemplo a seguir adiciona uma política de acesso a linhas ao mesmo tempo em que especifica duas colunas em uma única tabela.

alter table t1
  add row access policy rap_test2 on (cost, item);
Copy

O exemplo a seguir descarta uma política de acesso a linhas de uma tabela. Verifique se as políticas foram descartadas consultando o esquema de informação.

alter table t1 drop row access policy rap_v1;
Copy

O exemplo a seguir mostra como combinar a adição e a eliminação de políticas de acesso a linhas em uma única instrução SQL para uma tabela. Verifique os resultados conferindo o esquema de informação.

alter table t1
  drop row access policy rap_t1_version_1,
  add row access policy rap_t1_version_2 on (empl_id);
Copy