Tutorial 1: Crie um banco de dados, esquema, tabela e warehouse¶

Introdução¶

Neste tutorial, você aprenderá os fundamentos para gerenciar objetos de recurso Snowflake usando o Snowflake Python APIs. Para começar a usar a API, você cria e gerencia um banco de dados Snowflake, um esquema, uma tabela e um warehouse virtual.

Criação de um banco de dados, esquema e tabela¶

É possível usar seu objeto root para criar um banco de dados, um esquema e uma tabela em sua conta Snowflake.

1. Para criar um banco de dados, na próxima célula de seu notebook, execute o seguinte código:

   database = root.databases.create(
     Database(
       name="PYTHON_API_DB"),
       mode=CreateMode.or_replace
     )
   

   Copy

   Este código, que é funcionalmente equivalente ao comando SQL CREATE OR REPLACE DATABASE PYTHON_API_DB, cria um banco de dados em sua conta nomeado PYTHON_API_DB. Este código segue um padrão comum para gerenciar objetos no Snowflake:

   • root.databases.create() cria um banco de dados no Snowflake. Ele aceita dois argumentos: um objeto Database e um modo.

   • Você passa um objeto Database usando Database(name="PYTHON_API_DB") e define o nome do banco de dados usando o argumento name. Lembre-se de que você importou Database na linha 3 do notebook.

   • Você especifica o modo de criação passando o argumento mode. Neste caso, você define como CreateMode.or_replace, mas os seguintes valores também são válidos:

     • CreateMode.if_not_exists: Funcionalmente equivalente a CREATE IF NOT EXISTS no SQL.

     • CreateMode.error_if_exists: Gera uma exceção se o objeto já existir no Snowflake. Este é o valor padrão se um modo não for especificado.

   • Você gerencia o banco de dados programaticamente armazenando uma referência ao banco de dados em um objeto que tenha criado, nomeado database.

   Para obter mais informações, consulte Gerenciamento de bancos de dados, esquemas, tabelas e exibições Snowflake com Python.

2. No Snowsight, navegue até a seção de bancos de dados de sua conta Snowflake. Se seu código for bem-sucedido, o banco de dados PYTHON_API_DB será listado.

   Dica

   Se você usa o VS Code, instale a extensão Snowflake para explorar todos os objetos Snowflake em seu editor.

3. Para criar um esquema no banco de dados PYTHON_API_DB, na próxima célula, execute o seguinte código:

   schema = database.schemas.create(
     Schema(
       name="PYTHON_API_SCHEMA"),
       mode=CreateMode.or_replace,
     )
   

   Copy

   Observe que você chama .schemas.create() no objeto database criado anteriormente.

4. Para criar uma tabela no esquema que acabou de criar, na próxima célula, execute o seguinte código:

   table = schema.tables.create(
     Table(
       name="PYTHON_API_TABLE",
       columns=[
         TableColumn(
           name="TEMPERATURE",
           datatype="int",
           nullable=False,
         ),
         TableColumn(
           name="LOCATION",
           datatype="string",
         ),
       ],
     ),
   mode=CreateMode.or_replace
   )
   

   Copy

   Este código cria uma tabela no esquema PYTHON_API_SCHEMA com duas colunas e seus tipos de dados especificados: TEMPERATURE como int e LOCATION como string.

   Esses dois últimos exemplos de código devem parecer familiares porque seguem o padrão da primeira etapa em que você criou o banco de dados PYTHON_API_DB.

5. Para confirmar que os objetos foram criados, retorne à sua conta Snowflake no Snowsight.

Recuperação de dados do objeto¶

É possível recuperar metadados sobre um objeto no Snowflake.

1. Para recuperar detalhes sobre a tabela PYTHON_API_TABLE criada anteriormente, na próxima célula do notebook, execute o seguinte código:

   table_details = table.fetch()
   

   Copy

   fetch() retorna um objeto TableModel.

2. É possível então chamar .to_dict() sobre o objeto resultante para exibir suas informações detalhadas.

   Para imprimir os detalhes da tabela, na próxima célula, execute o seguinte código:

   table_details.to_dict()
   

   Copy

   O notebook deve exibir um dicionário com metadados sobre a tabela PYTHON_API_TABLE, semelhante a este:

   {
       "name": "PYTHON_API_TABLE",
       "kind": "TABLE",
       "enable_schema_evolution": False,
       "change_tracking": False,
       "data_retention_time_in_days": 1,
       "max_data_extension_time_in_days": 14,
       "default_ddl_collation": "",
       "columns": [
           {"name": "TEMPERATURE", "datatype": "NUMBER(38,0)", "nullable": False},
           {"name": "LOCATION", "datatype": "VARCHAR(16777216)", "nullable": True},
       ],
       "created_on": datetime.datetime(
           2024, 5, 9, 8, 59, 15, 832000, tzinfo=datetime.timezone.utc
       ),
       "database_name": "PYTHON_API_DB",
       "schema_name": "PYTHON_API_SCHEMA",
       "rows": 0,
       "bytes": 0,
       "owner": "ACCOUNTADMIN",
       "automatic_clustering": False,
       "search_optimization": False,
       "owner_role_type": "ROLE",
   }
   

   Copy

   Conforme mostrado, este dicionário contém informações sobre a tabela PYTHON_API_TABLE criada anteriormente, com informações detalhadas sobre columns, owner, database, schema e muito mais.

Metadados de objeto são úteis quando se está criando lógica de negócios em seu aplicativo. Por exemplo, é possível criar uma lógica que seja executada dependendo de certas informações sobre um objeto. É possível usar fetch() para recuperar metadados de objeto em tais cenários.

Como alterar uma tabela programaticamente¶

É possível adicionar programaticamente uma coluna a uma tabela. A tabela PYTHON_API_TABLE atualmente tem duas colunas: TEMPERATURE e LOCATION. Neste cenário, você deseja adicionar uma nova coluna nomeada ELEVATION do tipo int e defini-la como a chave primária da tabela.

1. Na próxima célula, execute o seguinte código:

   table_details.columns.append(
       TableColumn(
         name="elevation",
         datatype="int",
         nullable=False,
         constraints=[PrimaryKey()],
       )
   )
   

   Copy

   Nota

   Este código não cria a coluna. Em vez disso, esta definição de coluna é anexada à matriz que representa as colunas da tabela em TableModel. Para exibir esta matriz, revise o valor de columns conforme descrito nas instruções para visualizar os metadados da tabela.

2. Para modificar a tabela e adicionar a coluna, na próxima célula, execute o seguinte código:

   table.create_or_alter(table_details)
   

   Copy

   Nesta linha, você chama create_or_alter() no objeto que representa PYTHON_API_TABLE e passa o valor atualizado de table_details. Esta linha adiciona a coluna ELEVATION a PYTHON_API_TABLE.

3. Para confirmar que a coluna foi adicionada, na próxima célula, execute o seguinte código:

   table.fetch().to_dict()
   

   Copy

   A saída deve ser semelhante a esta:

   {
       "name": "PYTHON_API_TABLE",
       "kind": "TABLE",
       "enable_schema_evolution": False,
       "change_tracking": False,
       "data_retention_time_in_days": 1,
       "max_data_extension_time_in_days": 14,
       "default_ddl_collation": "",
       "columns": [
           {"name": "TEMPERATURE", "datatype": "NUMBER(38,0)", "nullable": False},
           {"name": "LOCATION", "datatype": "VARCHAR(16777216)", "nullable": True},
           {"name": "ELEVATION", "datatype": "NUMBER(38,0)", "nullable": False},
       ],
       "created_on": datetime.datetime(
           2024, 5, 9, 8, 59, 15, 832000, tzinfo=datetime.timezone.utc
       ),
       "database_name": "PYTHON_API_DB",
       "schema_name": "PYTHON_API_SCHEMA",
       "rows": 0,
       "bytes": 0,
       "owner": "ACCOUNTADMIN",
       "automatic_clustering": False,
       "search_optimization": False,
       "owner_role_type": "ROLE",
       "constraints": [
           {"name": "ELEVATION", "column_names": ["ELEVATION"], "constraint_type": "PRIMARY KEY"}
       ]
   }
   

   Copy

   Revise o valor de columns e o valor de constraints, ambos os quais agora incluem a coluna ELEVATION.

4. Para confirmar a existência da nova coluna, retorne à sua conta Snowflake no Snowsight e inspecione a tabela.

Criação e gerenciamento de um warehouse¶

Também é possível gerenciar warehouses virtuais com o Snowflake Python APIs. Por exemplo, talvez seja necessário criar outro warehouse temporariamente para executar determinadas consultas. Neste cenário, é possível usar a API para criar, suspender ou descartar um warehouse.

1. Para recuperar a coleção de warehouses associados à sessão, na próxima célula, execute o seguinte código:

   warehouses = root.warehouses
   

   Copy

   Você gerencia warehouses em sua sessão usando o objeto warehouses resultante.

2. Para definir e criar um novo warehouse, na próxima célula, execute o seguinte código:

   python_api_wh = Warehouse(
       name="PYTHON_API_WH",
       warehouse_size="SMALL",
       auto_suspend=500,
   )
   
   warehouse = warehouses.create(python_api_wh,mode=CreateMode.or_replace)
   

   Copy

   Neste código, você define um novo warehouse instanciando Warehouse e especificando o nome, o tamanho e a política de suspensão automática do warehouse. O tempo limite de suspensão automática é em unidades de segundos. Neste caso, o warehouse será suspenso após 8,33 minutos de inatividade.

   Em seguida, você cria o warehouse chamando create() em sua coleção de warehouses. Você armazena a referência no objeto warehouse resultante.

3. Navegue até sua conta Snowflake no Snowsight e confirme se o warehouse foi criado.

4. Para recuperar informações sobre o warehouse, na próxima célula, execute o seguinte código:

   warehouse_details = warehouse.fetch()
   warehouse_details.to_dict()
   

   Copy

   Este código deve parecer familiar porque segue o mesmo padrão usado para buscar metadados da tabela em uma etapa anterior. A saída deve ser semelhante a esta:

   {
     'name': 'PYTHON_API_WH',
     'auto_suspend': 500,
     'auto_resume': 'true',
     'resource_monitor': 'null',
     'comment': '',
     'max_concurrency_level': 8,
     'statement_queued_timeout_in_seconds': 0,
     'statement_timeout_in_seconds': 172800,
     'tags': {},
     'warehouse_type': 'STANDARD',
     'warehouse_size': 'Small'
   }
   

   Copy

5. Opcional: Se você tiver vários warehouses em sua sessão, use a API para iterar por eles ou procurar um warehouse específico.

   Na próxima célula, execute o seguinte código:

   warehouse_list = warehouses.iter(like="PYTHON_API_WH")
   result = next(warehouse_list)
   result.to_dict()
   

   Copy

   Neste código, você chama iter() na coleção de warehouses e passa o argumento like, que retorna todos os warehouses cujos nomes correspondem à cadeia de caracteres especificada. Neste caso, você passa o nome do warehouse definido anteriormente, mas esse argumento geralmente é uma cadeia de caracteres que não diferencia maiúsculas de minúsculas e que funciona como um filtro, com suporte para caracteres curinga SQL como % e _.

   Após executar a célula, uma saída semelhante ao código a seguir mostra que você retornou com sucesso um warehouse correspondente:

   {
     'name': 'PYTHON_API_WH',
     'auto_suspend': 500,
     'auto_resume': 'true',
     'resource_monitor': 'null',
     'comment': '',
     'max_concurrency_level': 8,
     'statement_queued_timeout_in_seconds': 0,
     'statement_timeout_in_seconds': 172800,
     'tags': {},
     'warehouse_type': 'STANDARD',
     'warehouse_size': 'Small'
   }
   

   Copy

6. Para modificar programaticamente o warehouse alterando seu tamanho para LARGE, na próxima célula, execute o seguinte código:

   warehouse = root.warehouses.create(Warehouse(
       name="PYTHON_API_WH",
       warehouse_size="LARGE",
       auto_suspend=500,
   ), mode=CreateMode.or_replace)
   

   Copy

7. Para confirmar se o tamanho do warehouse foi atualizado para LARGE, faça um dos seguintes:

   • Na próxima célula, execute o seguinte código:

     warehouse.fetch().size
     

     Copy

   • Acesse sua conta Snowflake no Snowsight e confirme a alteração no tamanho do warehouse.

8. Opcional: Se não quiser continuar usando o warehouse, descarte-o. Na próxima célula, execute o seguinte código:

   warehouse.drop()
   

   Copy

9. Para confirmar a exclusão do warehouse, retorne à sua conta Snowflake no Snowsight.

Qual é o próximo passo?¶

Parabéns! Neste tutorial, você aprendeu os fundamentos para gerenciar objetos de recurso do Snowflake usando o Snowflake Python APIs.