CREATE DATABASE¶

Sintaxe¶

Banco de dados padrão

CREATE [ OR REPLACE ] [ TRANSIENT ] DATABASE [ 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 ] ]
    [ 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 } ]
    [ COMMENT = '<string_literal>' ]
    [ CATALOG_SYNC = '<snowflake_open_catalog_integration_name>' ]
    [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

Banco de dados padrão (de uma listagem)

CREATE DATABASE <name> FROM LISTING '<listing_global_name>'

Banco de dados compartilhado (de um compartilhamento)

CREATE DATABASE <name> FROM SHARE <provider_account>.<share_name>

Banco de dados secundário (Replicação de banco de dados)

CREATE DATABASE <name>
    AS REPLICA OF <account_identifier>.<primary_db_name>
    [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]

Sintaxe da variante¶

CREATE OR ALTER [ TRANSIENT ] DATABASE <name>
    [ 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>' ]

Parâmetros obrigatórios¶

name

Especifica o identificador do banco de dados; deve ser único para sua conta.

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.

Importante

Como prática recomendada para Replicação e failover do banco de dados, recomendamos dar a cada banco de dados secundário o mesmo nome de seu banco de dados primário. Esta prática oferece suporte a fazer referência a objetos totalmente qualificados (ou seja, '<bd>.<esquema>.<objeto>') por outros objetos no mesmo banco de dados, como a consulta de um nome de tabela totalmente qualificado em uma exibição.

Se um banco de dados secundário tiver um nome diferente do banco de dados primário, então estas referências de objetos seriam desfeitas no banco de dados secundário.

Parâmetros opcionais¶

TRANSIENT

Especifica um banco de dados como transitório. Os bancos de dados 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, todos os esquemas (e consequentemente todas as tabelas) criados em um banco de dados transitório são transitórios. Para obter mais informações sobre tabelas transitórias, consulte CREATE TABLE.

Padrão: sem valor (ou seja, banco de dados é permanente)

CLONE source_db

Especifica a criação de um clone do banco de dados da fonte especificada. Para obter mais detalhes sobre a clonagem de um banco de dados, consulte CREATE <objeto> … CLONE.

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

Ao clonar um banco de dados, a cláusula AT | BEFORE especifica o uso de Time Travel para clonar o banco de dados em ou antes de um ponto específico no passado. Se a hora do Time Travel especificada for no momento ou antes do momento em que o banco de dados foi criado, a operação de clonagem falhará com um erro.

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 banco de dados com tabelas híbridas. O banco de dados clonado inclui outros objetos, mas ignora tabelas híbridas.

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

DATA_RETENTION_TIME_IN_DAYS = integer

Especifica o número de dias para os quais as ações de Time Travel (CLONE e UNDROP) podem ser executadas no banco de dados, bem como especifica o tempo padrão de retenção do Time Travel para todos os esquemas criados no banco de dados. 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.

Valores:

• Standard Edition: 0 ou 1

• Enterprise Edition:

  • 0 a 90 para bancos de dados permanentes

  • 0 ou 1 para bancos de dados 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 da conta)

Nota

Um valor de 0 efetivamente desabilita o Time Travel para o banco de dados.

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 banco de dados 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'

Determina uma especificação de agrupamento padrão para todos os esquemas e tabelas adicionados ao banco de dados. O padrão pode ser anulado no nível do esquema e 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 log, 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

COMMENT = 'string_literal'

Especifica um comentário para o banco de dados.

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 banco de dados 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:

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 banco de dados o define automaticamente como o banco de dados ativo/atual para a sessão atual (equivalente a usar o comando USE DATABASE para o banco de dados).

• Se já existir um banco de dados com o mesmo nome, um erro será retornado e o banco de dados não é criado, a menos que a palavra-chave opcional OR REPLACE seja especificada no comando.

  Importante

  Usar OR REPLACE é o equivalente a usar DROP DATABASE no banco de dados existente e depois criar um novo banco de dados com o mesmo nome; entretanto, o banco de dados descartado não é permanentemente removido do sistema. Em vez disso, ela fica retida no Time Travel. Isto é importante porque os bancos de dados 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.

• A criação de um novo banco de dados cria automaticamente dois esquemas no banco de dados:

  • PUBLIC: esquema padrão para o banco de dados.

  • INFORMATION_SCHEMA: esquema que contém exibições e funções de tabela que podem ser usadas para consultar metadados sobre os objetos do banco de dados, bem como sobre todos os objetos da conta.

• Os bancos de dados criados a partir de compartilhamentos diferem dos bancos de dados padrão nas seguintes formas:

  • Eles não têm os esquemas PUBLIC ou INFORMATION_SCHEMA, a menos que estes esquemas tenham sido explicitamente concedidos ao compartilhamento.

  • Eles não podem ser clonados.

  • Propriedades, como TRANSIENT e DATA_RETENTION_TIME_IN_DAYS, não se aplicam.

• Quando um banco de dados está ativo/atual, o esquema PUBLIC também estará ativo/atual por padrão, a menos que um esquema diferente seja usado ou que o esquema PUBLIC tenha sido descartado.

• 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 DATABASE¶

• Todas as limitações do comando ALTER DATABASE se aplicam.

• Esse comando é compatível com as propriedades e a sintaxe que se sobrepõem aos comandos CREATE DATABASE e ALTER DATABASE. Por esse motivo, os seguintes itens não são compatíveis:

  • Troca de bancos de dados usando o parâmetro SWAP WITH.

  • Renomeação de um banco de dados usando o parâmetro RENAME TO.

  • Criação de um clone de um banco de dados 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 banco de dados TRANSIENT em um banco de dados nãoTRANSIENT ou vice-versa.

  • Criação de um banco de dados a partir de um compartilhamento usando CREATE OR ALTER DATABASE … FROM SHARE.

  • Criação de um banco de dados secundário (réplica) usando CREATE OR ALTER DATABASE … AS REPLICA OF.

Notas de uso da replicação de banco de dados¶

• A replicação do banco de dados utiliza recursos computacionais fornecidos pelo Snowflake em vez de seu próprio warehouse virtual para copiar objetos e dados. Entretanto, o parâmetro STATEMENT_TIMEOUT_IN_SECONDS de sessão/objeto ainda controla por quanto tempo uma instrução é executada antes de ser cancelada. O valor padrão é 172800 (2 dias). Como a replicação inicial de um banco de dados primário pode levar mais do que 2 dias para ser concluída (dependendo da quantidade de metadados no banco de dados, assim como a quantidade de dados nos objetos de banco de dados), recomendamos aumentar o valor de STATEMENT_TIMEOUT_IN_SECONDS para 604800 (7 dias, o valor máximo) para a sessão em que se executa a operação de replicação.

  Execute a seguinte instrução ALTER SESSION antes de executar a instrução ALTER DATABASE secondary_db_name REFRESH na mesma sessão:

  ALTER SESSION SET STATEMENT_TIMEOUT_IN_SECONDS = 604800;
  

  Copy

  Observe que o parâmetro STATEMENT_TIMEOUT_IN_SECONDS também se aplica ao warehouse ativo em uma sessão. O parâmetro honra o valor mais baixo definido no nível da sessão ou do warehouse. Se você tiver um warehouse ativo na sessão atual, defina também STATEMENT_TIMEOUT_IN_SECONDS como 604800 para este warehouse (usando ALTER WAREHOUSE).

  Por exemplo:

  -- determine the active warehouse in the current session (if any)
  SELECT CURRENT_WAREHOUSE();
  
  +---------------------+
  | CURRENT_WAREHOUSE() |
  |---------------------|
  | MY_WH               |
  +---------------------+
  
  -- change the STATEMENT_TIMEOUT_IN_SECONDS value for the active warehouse
  
  ALTER WAREHOUSE my_wh SET STATEMENT_TIMEOUT_IN_SECONDS = 604800;
  

  Copy

  Você pode redefinir o valor do parâmetro para o padrão depois que a operação de replicação for concluída:

  ALTER WAREHOUSE my_wh UNSET STATEMENT_TIMEOUT_IN_SECONDS;
  

  Copy

• O método preferido para identificar a conta que armazena o banco de dados primário usa o nome da organização e o nome da conta como o identificador da conta. Se você decidir usar o localizador de contas legado, consulte Identificadores de conta para replicação e failover.

• O comando CREATE DATABASE … AS REPLICA não oferece suporte para a cláusula WITH TAG.

  Esta cláusula não é suportada porque o banco de dados secundário é somente leitura. Se seu banco de dados primário especificar a cláusula WITH TAG, remova a cláusula antes de criar o banco de dados secundário. Para verificar se seu banco de dados tem a cláusula WITH TAG, chame a função GET_DDL em sua conta Snowflake e especifique o banco de dados primário no argumento da função. Se uma tag for definida no banco de dados, a saída da função incluirá uma instrução ALTER DATABASE … SET TAG.

  Para obter mais informações, consulte Replicação e tags.

Exemplos¶

Criar dois bancos de dados permanentes, um com um período de retenção de dados de 10 dias:

CREATE DATABASE mytestdb;

CREATE DATABASE mytestdb2 DATA_RETENTION_TIME_IN_DAYS = 10;

SHOW DATABASES LIKE 'my%';

+---------------------------------+------------+------------+------------+--------+----------+---------+---------+----------------+
| created_on                      | name       | is_default | is_current | origin | owner    | comment | options | retention_time |
|---------------------------------+------------+------------+------------+--------+----------+---------+---------+----------------|
| Tue, 17 Mar 2016 16:57:04 -0700 | MYTESTDB   | N          | N          |        | PUBLIC   |         |         | 1              |
| Tue, 17 Mar 2016 17:06:32 -0700 | MYTESTDB2  | N          | N          |        | PUBLIC   |         |         | 10             |
+---------------------------------+------------+------------+------------+--------+----------+---------+---------+----------------+

Criar um banco de dados transitório:

CREATE TRANSIENT DATABASE mytransientdb;

SHOW DATABASES LIKE 'my%';

+---------------------------------+---------------+------------+------------+--------+----------+---------+-----------+----------------+
| created_on                      | name          | is_default | is_current | origin | owner    | comment | options   | retention_time |
|---------------------------------+---------------+------------+------------+--------+----------+---------+-----------+----------------|
| Tue, 17 Mar 2016 16:57:04 -0700 | MYTESTDB      | N          | N          |        | PUBLIC   |         |           | 1              |
| Tue, 17 Mar 2016 17:06:32 -0700 | MYTESTDB2     | N          | N          |        | PUBLIC   |         |           | 10             |
| Tue, 17 Mar 2015 17:07:51 -0700 | MYTRANSIENTDB | N          | N          |        | PUBLIC   |         | TRANSIENT | 1              |
+---------------------------------+---------------+------------+------------+--------+----------+---------+-----------+----------------+

Criar um banco de dados a partir de um compartilhamento fornecido pela conta ab67890:

CREATE DATABASE snow_sales FROM SHARE ab67890.sales_s;

Para exemplos mais detalhados da criação de um banco de dados a partir de um compartilhamento, consulte Consumo de dados importados.

Exemplos de replicação de banco de dados¶

Para obter um exemplo de criação de um grupo de replicação para replicar um único banco de dados para uma conta de destino, consulte Replicação de um único banco de dados.

Exemplos de CREATE OR ALTER DATABASE¶

CREATE OR ALTER DATABASE db1;

CREATE OR ALTER DATABASE db1
  DATA_RETENTION_TIME_IN_DAYS = 5
  DEFAULT_DDL_COLLATION = 'de';

CREATE OR ALTER DATABASE db1
  DEFAULT_DDL_COLLATION = 'de';

Interfaces alternativas¶

• Snowflake REST APIs

  • Criação de um banco de dados

  • Criação de um banco de dados a partir de um compartilhamento

  • Clonagem de um banco de dados

• Snowflake Python APIs

  • Método database.DatabaseCollection.create

• Snowflake CLI

  • Comando snow object create