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.

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.