CREATE SCHEMA¶

Cria um novo esquema no banco de dados atual.

Esse comando é compatível com as seguintes variantes:

CREATE OR ALTER SCHEMA: cria um esquema se ele não existir ou altera um esquema existente.
CREATE SCHEMA … CLONE: cria um clone de um esquema existente, seja em seu estado atual ou em um momento/ponto específico no passado (usando o Time Travel). Para obter mais informações sobre clonagem de um esquema, consulte Considerações sobre clonagem.

Consulte também:

ALTER SCHEMA , DESCRIBE SCHEMA , DROP SCHEMA , SHOW SCHEMAS , UNDROP SCHEMA

Sintaxe¶

CREATE [ OR REPLACE ] [ TRANSIENT ] SCHEMA [ IF NOT EXISTS ] <name>
  [ CLONE <source_schema>
      [ { AT | BEFORE } ( { TIMESTAMP => <timestamp> | OFFSET => <time_difference> | STATEMENT => <id> } ) ]
      [ IGNORE TABLES WITH INSUFFICIENT DATA RETENTION ]
      [ IGNORE HYBRID TABLES ] ]
  [ WITH MANAGED ACCESS ]
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ EXTERNAL_VOLUME = <external_volume_name> ]
  [ CATALOG = <catalog_integration_name> ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
  [ STORAGE_SERIALIZATION_POLICY = { COMPATIBLE | OPTIMIZED } ]
  [ CLASSIFICATION_PROFILE = '<classification_profile>' ]
  [ COMMENT = '<string_literal>' ]
  [ CATALOG_SYNC = '<snowflake_open_catalog_integration_name>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

Copy

Sintaxe da variante¶

CREATE OR ALTER SCHEMA¶

Cria um novo esquema se ele ainda não existir ou transforma um esquema existente no esquema definido na instrução. Uma instrução CREATE OR ALTER SCHEMA segue as regras de sintaxe de uma instrução CREATE SCHEMA e tem as mesmas limitações de uma instrução ALTER SCHEMA.

Para obter mais informações, consulte Notas de uso de CREATE OR ALTER SCHEMA.

CREATE OR ALTER [ TRANSIENT ] SCHEMA <name>
  [ WITH MANAGED ACCESS ]
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ EXTERNAL_VOLUME = <external_volume_name> ]
  [ CATALOG = <catalog_integration_name> ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
  [ LOG_LEVEL = '<log_level>' ]
  [ TRACE_LEVEL = '<trace_level>' ]
  [ STORAGE_SERIALIZATION_POLICY = { COMPATIBLE | OPTIMIZED } ]
  [ COMMENT = '<string_literal>' ]

Copy

CREATE SCHEMA … CLONE¶

Cria um novo esquema com os mesmos valores de parâmetro:

CREATE [ OR REPLACE ] SCHEMA [ IF NOT EXISTS ] <name> CLONE <source_schema>
  [ ... ]

Copy

Para obter mais detalhes, consulte CREATE <objeto> … CLONE.

Parâmetros obrigatórios¶

name

Especifica o identificador do esquema; deve ser único para o banco de dados no qual o esquema é criado.

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

Para obter mais detalhes, consulte Requisitos para identificadores.

Parâmetros opcionais¶

TRANSIENT

Especifica um esquema como transitório. Os esquemas transitórios não têm um período de Fail-safe, de modo que não incorrem em custos adicionais de armazenamento uma vez que saem do Time Travel; no entanto, isto significa que também não estão protegidos pelo Fail-safe no caso de perda de dados. Para obter mais informações, consulte Explicação e visualização do Fail-safe.

Além disso, por definição, todas as tabelas criadas em um esquema transitório são transitórias. Para obter mais informações sobre tabelas transitórias, consulte CREATE TABLE.

Padrão: sem valor (ou seja, o esquema é permanente)

CLONE source_schema

Especifica a criação de um clone do esquema de origem especificado. Para obter mais detalhes sobre a clonagem de um esquema, consulte CREATE <objeto> … CLONE.

AT | BEFORE ( TIMESTAMP => timestamp | OFFSET => time_difference | STATEMENT => id )

Ao clonar um esquema, a cláusula AT | BEFORE especifica o uso do Time Travel para clonar o esquema em ou antes de um ponto específico no passado.

IGNORE TABLES WITH INSUFFICIENT DATA RETENTION

Ignore tabelas que não possuem mais dados históricos disponíveis no Time Travel para clonar. Se a hora no passado especificada na cláusula AT | BEFORE ultrapassar o período de retenção de dados para qualquer tabela filho em um banco de dados ou esquema, ignore a operação de clonagem da tabela filho. Para obter mais informações, consulte Objetos filhos e tempo de retenção de dados.

IGNORE HYBRID TABLES

Ignore tabelas híbridas, que não serão clonadas. Use esta opção para clonar um esquema com tabelas híbridas. O esquema clonado inclui outros objetos, mas ignora tabelas híbridas.

Se você não usar esta opção e seu esquema contiver uma ou mais tabelas híbridas, o comando ignorará as tabelas híbridas silenciosamente. Entretanto, o tratamento de erro para esquemas com tabelas híbridas mudará em um lançamento futuro; portanto, talvez você queira adicionar esse parâmetro aos seus comandos preventivamente.

WITH MANAGED ACCESS

Especifica um esquema administrado. Os esquemas de acesso gerenciados centralizam a gestão de privilégios com o proprietário do esquema.

Em esquemas regulares, o proprietário de um objeto (ou seja, a função que tem o privilégio OWNERSHIP no objeto) pode conceder outros privilégios em seus objetos a outras funções. Em esquemas administrados, o proprietário do esquema administra todas as concessões de privilégios, incluindo futuras concessões, nos objetos no esquema. Os proprietários dos objetos retêm os privilégios OWNERSHIP nos objetos; entretanto, somente o proprietário do esquema pode administrar as concessões de privilégios nos objetos.

DATA_RETENTION_TIME_IN_DAYS = integer

Especifica o número de dias para os quais as ações do Time Travel (CLONE e UNDROP) podem ser executadas no esquema, bem como especifica o tempo padrão de retenção do Time Travel para todas as tabelas criadas no esquema. Para obter mais detalhes, consulte Compreensão e uso do Time Travel.

Para uma descrição detalhada deste parâmetro de nível de objeto, bem como mais informações sobre parâmetros de objeto, consulte Parâmetros. Para obter mais informações sobre o tempo de retenção em nível de tabela, consulte CREATE TABLE e Compreensão e uso do Time Travel.

Valores:

Standard Edition: 0 ou 1

Enterprise Edition:

0 a 90 para esquemas permanentes

0 ou 1 para esquemas transitórios

Padrão:

Standard Edition: 1

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

Nota

Um valor de 0 efetivamente desabilita o Time Travel para o esquema.

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 das tabelas no esquema para evitar que os fluxos nas tabelas se tornem obsoletos.

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

EXTERNAL_VOLUME = external_volume_name

O parâmetro de objeto que especifica o volume externo padrão a ser usado para Tabelas Apache Iceberg™.

Para obter mais informações sobre este parâmetro, consulte EXTERNAL_VOLUME.

CATALOG = catalog_integration_name

O parâmetro de objeto que especifica a integração de catálogo padrão a ser usada para Tabelas Apache Iceberg™.

Para obter mais informações sobre este parâmetro, consulte CATALOG.

REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }

Especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (�) nos resultados da consulta para uma tabela Iceberg. Você só pode definir esse parâmetro para tabelas que usam um catálogo Iceberg externo.

TRUE substitui os caracteres UTF-8 inválidos pelo caractere de substituição Unicode.
FALSE deixa caracteres UTF-8 inválidos inalterados. O Snowflake retorna uma mensagem de erro do usuário quando encontra caracteres UTF-8 inválidos em um arquivo de dados Parquet.

Padrão: FALSE

DEFAULT_DDL_COLLATION = 'collation_specification'

Especifica a especificação de agrupamento padrão para todas as tabelas adicionadas ao esquema. O padrão pode ser anulado no nível da tabela individual.

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

LOG_LEVEL = 'log_level'

Especifica o nível de gravidade das mensagens que devem ser ingeridas e disponibilizadas na tabela de eventos ativos. As mensagens no nível especificado (e em níveis mais graves) são ingeridas.

Para obter mais informações sobre os níveis, consulte LOG_LEVEL. Para obter informações sobre como configurar o nível de registro, consulte Definição de níveis para registro, métricas e rastreamento.

TRACE_LEVEL = 'trace_level'

Controla como os eventos de rastreamento são ingeridos na tabela de eventos.

Para obter informações sobre níveis, consulte TRACE_LEVEL. Para obter informações sobre como configurar o nível de rastreamento, consulte Definição de níveis para registro, métricas e rastreamento.

STORAGE_SERIALIZATION_POLICY = { COMPATIBLE | OPTIMIZED }

Especifica a política de serialização de armazenamento para Tabelas Apache Iceberg™ que usam o Snowflake como catálogo.

COMPATIBLE: o Snowflake realiza a codificação e a compactação de arquivos de dados, o que garante a interoperabilidade com mecanismos de computação de terceiros.
OPTIMIZED: o Snowflake realiza a codificação e a compactação de arquivos de dados, o que garante o melhor desempenho de tabela no Snowflake.

Padrão: OPTIMIZED

CLASSIFICATION_PROFILE = 'classification_profile'

Associa o esquema a um perfil de classificação para que os dados confidenciais no esquema sejam classificados automaticamente.

COMMENT = 'string_literal'

Especifica um comentário para o esquema.

Padrão: sem valor

CATALOG_SYNC = 'snowflake_open_catalog_integration_name'

Especifica o nome de uma integração de catálogo configurada para o Snowflake Open Catalog. Se especificado, o Snowflake sincroniza as tabelas Apache Iceberg™ gerenciadas pelo Snowflake no esquema com um catálogo externo em sua conta Snowflake Open Catalog. Para obter mais informações sobre a sincronização de tabelas Iceberg gerenciadas pelo Snowflake com o Open Catalog, consulte Sincronizar uma tabela gerenciada pelo Snowflake com Snowflake Open Catalog.

Para obter mais informações sobre este parâmetro, consulte CATALOG_SYNC.

Padrão: sem valor

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.

Requisitos de controle de acesso¶

A função usada para executar essa operação deve ter, no mínimo, os seguintes privilégios:

Privilégio	Objeto	Notas
CREATE SCHEMA	Banco de dados	Pode criar esquemas de acesso regular e gerenciado.
CREATE SCHEMA … CLONE … WITH MANAGED ACCESS	Opções	Os privilégios necessários dependem de o esquema de origem ser gerenciado ou não: Gerenciado: OWNERSHIP no esquema de origem. Não gerenciado: MANAGE GRANTS ON ACCOUNT e USAGE no esquema de origem.
USAGE	Volume externo, integração de catálogo	Obrigatório ao definir os parâmetros do objeto `EXTERNAL_VOLUME` ou `CATALOG`, respectivamente.
MODIFY LOG LEVEL	Conta	Necessário para definir o LOG_LEVEL para um esquema.
MODIFY TRACE LEVEL	Conta	Necessário para definir o TRACE_LEVEL para um esquema.
OWNERSHIP	Esquema	Necessário somente ao executar uma instrução CREATE OR ALTER SCHEMA para um esquema existente. OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).

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

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

Notas de uso geral¶

A criação de um esquema o define automaticamente como o esquema ativo/atual para a sessão atual (equivalente a usar o comando USE SCHEMA para o esquema).
Se um esquema com o mesmo nome já existir no banco de dados, um erro será retornado e o esquema não será criado, a menos que a palavra-chave opcional OR REPLACE seja especificada no comando.

Importante

Usar OR REPLACE é o equivalente a usar DROP SCHEMA no esquema existente e depois criar um novo esquema com o mesmo nome; no entanto, o esquema descartado não será permanentemente removido do sistema. Em vez disso, ela fica retida no Time Travel. Isto é importante porque os esquemas descartados no Time Travel contribuem para o armazenamento de dados de sua conta. Para obter mais informações, consulte Custos de armazenamento para Time Travel e Fail-safe.
Instruções CREATE OR REPLACE <object> são atômicas. Ou seja, quando um objeto é substituído, o objeto antigo é excluído e o novo objeto é criado em uma única transação.
Em um esquema de acesso gerenciado, o proprietário do esquema gerencia concessões nos objetos contidos (por exemplo, tabelas ou exibições), mas não tem outros privilégios (USAGE, SELECT, DROP etc.) nos objetos.
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.

Notas de uso de CREATE OR ALTER SCHEMA¶

Todas as limitações do comando ALTER SCHEMA se aplicam.
Esse comando não é compatível com o seguinte:
- Troca de esquemas usando o parâmetro SWAP WITH.
- Renomeação de um esquema usando o parâmetro RENAME TO.
- Criação de um clone de um esquema usando o parâmetro CLONE.
- Adicionar ou alterar tags e políticas. Todas as tags e políticas existentes são preservadas.
- Conversão de um esquema TRANSIENT em um esquema não TRANSIENT ou vice-versa.

Exemplos¶

Criar um esquema permanente:

CREATE SCHEMA myschema;

SHOW SCHEMAS;

+-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+---------+----------------+
| created_on                    | name               | is_default | is_current | database_name | owner        | comment                                                   | options | retention_time |
|-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+---------+----------------|
| 2018-12-10 09:34:02.127 -0800 | INFORMATION_SCHEMA | N          | N          | MYDB          |              | Views describing the contents of schemas in this database |         | 1              |
| 2018-12-10 09:33:56.793 -0800 | MYSCHEMA           | N          | Y          | MYDB          | PUBLIC       |                                                           |         | 1              |
| 2018-11-26 06:08:24.263 -0800 | PUBLIC             | N          | N          | MYDB          | PUBLIC       |                                                           |         | 1              |
+-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+---------+----------------+

Copy

Criar um esquema transitório:

CREATE TRANSIENT SCHEMA tschema;

SHOW SCHEMAS;

+-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+-----------+----------------+
| created_on                    | name               | is_default | is_current | database_name | owner        | comment                                                   | options   | retention_time |
|-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+-----------+----------------|
| 2018-12-10 09:34:02.127 -0800 | INFORMATION_SCHEMA | N          | N          | MYDB          |              | Views describing the contents of schemas in this database |           | 1              |
| 2018-12-10 09:33:56.793 -0800 | MYSCHEMA           | N          | Y          | MYDB          | PUBLIC       |                                                           |           | 1              |
| 2018-11-26 06:08:24.263 -0800 | PUBLIC             | N          | N          | MYDB          | PUBLIC       |                                                           |           | 1              |
| 2018-12-10 09:35:32.326 -0800 | TSCHEMA            | N          | Y          | MYDB          | PUBLIC       |                                                           | TRANSIENT | 1              |
+-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+-----------+----------------+

Copy

Criar um esquema de acesso gerenciado:

CREATE SCHEMA mschema WITH MANAGED ACCESS;

SHOW SCHEMAS;

+-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+----------------+----------------+
| created_on                    | name               | is_default | is_current | database_name | owner        | comment                                                   | options        | retention_time |
|-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+----------------+----------------|
| 2018-12-10 09:34:02.127 -0800 | INFORMATION_SCHEMA | N          | N          | MYDB          |              | Views describing the contents of schemas in this database |                | 1              |
| 2018-12-10 09:36:47.738 -0800 | MSCHEMA            | N          | Y          | MYDB          | ROLE1        |                                                           | MANAGED ACCESS | 1              |
| 2018-12-10 09:33:56.793 -0800 | MYSCHEMA           | N          | Y          | MYDB          | PUBLIC       |                                                           |                | 1              |
| 2018-11-26 06:08:24.263 -0800 | PUBLIC             | N          | N          | MYDB          | PUBLIC       |                                                           |                | 1              |
| 2018-12-10 09:35:32.326 -0800 | TSCHEMA            | N          | Y          | MYDB          | PUBLIC       |                                                           | TRANSIENT      | 1              |
+-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+----------------+----------------+

Copy

Exemplos de CREATE OR ALTER SCHEMA¶

Criação de um esquema simples¶

Crie um esquema nomeado s1:

CREATE OR ALTER SCHEMA s1;

Copy

Crie ou altere o esquema s1 e defina propriedades e parâmetros:

CREATE OR ALTER SCHEMA s1
  WITH MANAGED ACCESS
  DATA_RETENTION_TIME_IN_DAYS = 5
  DEFAULT_DDL_COLLATION = 'de';

Copy

Remoção da definição prévia de um parâmetro no esquema¶

A ausência de um parâmetro definido anteriormente na definição do esquema modificado resulta em sua remoção. No exemplo a seguir, desative o acesso gerenciado para o esquema s1 criado no exemplo anterior:

CREATE OR ALTER SCHEMA s1
  DATA_RETENTION_TIME_IN_DAYS = 5
  DEFAULT_DDL_COLLATION = 'de';

Copy