教程 1：创建数据库、架构、表和仓库¶

简介¶

在本教程中，您将学习使用 Snowflake Python APIs 管理 Snowflake 资源对象的基础知识。要开始使用 API，您需要创建和管理 Snowflake 数据库、架构、表和虚拟仓库。

创建数据库、架构和表¶

您可以使用 root 对象在 Snowflake 账户中创建数据库、架构和表。

1. 要创建一个数据库，请在笔记本的下一个单元格中运行以下代码：

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

   Copy

   这段代码在功能上等同于 SQL 命令 CREATE OR REPLACE DATABASE PYTHON_API_DB，会在账户中创建名为 PYTHON_API_DB 的数据库。此代码遵循在 Snowflake 中管理对象的常见模式：

   • root.databases.create() 在 Snowflake 中创建数据库。它接受两个实参：一个 Database 对象和一个模式。

   • 通过使用 Database(name="PYTHON_API_DB") 传递 Database 对象，并通过使用 name 实参设置数据库的名称。请记得在笔记本的第 3 行已经导入了 Database。

   • 您通过传递 mode 实参来指定创建模式。在这种情况下，您将其设置为 CreateMode.or_replace，但以下值也是有效的：

     • CreateMode.if_not_exists：在功能上等同于 SQL 中的 CREATE IF NOT EXISTS。

     • CreateMode.error_if_exists：如果对象已经存在于 Snowflake 中，则会引发异常。如果未指定模式，则此为默认值。

   • 您可以通过在您创建的名为 database 的对象中存储对数据库的引用来以编程方式管理数据库。

2. 在 Snowsight 中，导航到 Snowflake 账户的数据库部分。如果代码成功执行，将会列出 PYTHON_API_DB 数据库。

   小技巧

   如果您使用 VS 代码，请安装 Snowflake 扩展 (https://marketplace.visualstudio.com/items?itemName=snowflake.snowflake-vsc)，以便在您的编辑器中探索所有 Snowflake 对象。

3. 要在 PYTHON_API_DB 数据库中创建架构，请在下一个单元格中运行以下代码：

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

   Copy

   请注意，在之前创建的 database 对象上调用 .schemas.create()。

4. 要在刚创建的架构中创建一个表，请在下一个单元格中运行以下代码：

   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

   这段代码在 PYTHON_API_SCHEMA 架构中创建了一个表，其中包含两列及其指定的数据类型：TEMPERATURE 指定为 int，LOCATION 指定为 string。

   这最后两个代码示例应该看起来很熟悉，因为它们遵循了在第一步中创建 PYTHON_API_DB 数据库的模式。

5. 要确认已创建的对象，请在 Snowsight 中返回您的 Snowflake 账户。

检索对象数据¶

您可以检索有关 Snowflake 中对象的元数据。

1. 要检索您之前创建的 PYTHON_API_TABLE 表的详细信息，请在下一个笔记本单元格中运行以下代码：

   table_details = table.fetch()
   

   Copy

   fetch() 返回一个 TableModel 对象。

2. 然后您可以在生成的对象上调用 .to_dict() 以查看其详细信息。

   要打印表详细信息，请在下一个单元格中运行以下代码：

   table_details.to_dict()
   

   Copy

   笔记本应显示一个包含有关 PYTHON_API_TABLE 表的元数据的字典，如下所示：

   {
       "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

   如图所示，此字典包含您之前创建的 PYTHON_API_TABLE 表的相关信息，以及有关 columns、owner、database、schema 等内容的详细信息。

在您构建应用程序中的业务逻辑时，对象元数据非常有用。例如，您可能会构建根据对象的某些信息运行的逻辑。在这种情况下，您可以使用 fetch() 来检索对象元数据。

以编程方式更改表¶

您可以通过编程方式向表中添加列。PYTHON_API_TABLE 表目前有两列：TEMPERATURE 和 LOCATION。在这种情况下，您想添加一个名为 ELEVATION、类型为 int 的新列，并将其设置为表的主键。

1. 请在下一个单元格中运行以下代码：

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

   Copy

   备注

   这段代码不会创建列。相反，这个列定义被追加到表示 TableModel 中表列的数组中。要查看此数组，请按照查看表元数据的说明查看 columns 的值。

2. 要修改表并添加列，请在下一个单元格中运行以下代码：

   table.create_or_alter(table_details)
   

   Copy

   在这一行中，您对表示 PYTHON_API_TABLE 的对象调用 create_or_alter()，并传递 table_details 的更新值。这一行将 ELEVATION 列添加到 PYTHON_API_TABLE。

3. 要确认列已添加，请在下一个单元格中运行以下代码：

   table.fetch().to_dict()
   

   Copy

   输出应类似于以下内容：

   {
       "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

   查看 columns 和 constraints 的值，这两个值现在都在 ELEVATION 列中。

4. 要确认新列的存在，请在 Snowsight 中返回 Snowflake 账户并检查表。

创建和管理仓库¶

您还可以使用 Snowflake Python APIs 管理虚拟仓库。例如，您可能需要临时创建另一个仓库以运行某些查询。在这种情况下，您可以使用 API 来创建、暂停或删除仓库。

1. 要检索与会话相关的仓库集合，请在下一个单元格中运行以下代码：

   warehouses = root.warehouses
   

   Copy

   您在会话中使用生成的 warehouses 对象管理仓库。

2. 要定义和创建一个新仓库，请在下一个单元格中运行以下代码：

   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

   在这段代码中，您通过实例化 Warehouse 并指定仓库的名称、大小和自动暂停策略来定义新仓库。自动暂停超时以秒为单位。在这种情况下，仓库将在闲置 8.33 分钟后暂停。

   然后通过调用仓库集合中的 create() 来创建仓库。将引用存储在生成的 warehouse 对象中。

3. 在 Snowsight 中导航到 Snowflake 账户，并确认仓库已创建。

4. 要检索有关仓库的信息，请在下一个单元格中运行以下代码：

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

   Copy

   这段代码应该看起来很熟悉，因为它采用了在之前的步骤中提取表元数据时使用的模式。输出应类似于以下内容：

   {
     '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. 可选：如果在会话中有多个仓库，请使用 API 来对其循环访问或搜索特定仓库。

   请在下一个单元格中运行以下代码：

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

   Copy

   这段代码中，在仓库集合上调用 iter()，并传递 like 实参，从而返回任何名称与指定字符串匹配的仓库。在这种情况下，您传递之前定义的仓库名称，但此实参通常是不区分大小写的字符串，将用作筛选器，支持 SQL 通配符，如 % 和 _。

   在运行单元格后，类似以下代码的输出表明您成功返回了匹配的仓库：

   {
     '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. 要以编程方式修改仓库，将其大小更改为 LARGE，请在您的下一个单元格中运行以下代码：

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

   Copy

7. 要确认仓库大小已更新为 LARGE，请执行以下某项操作：

   • 请在下一个单元格中运行以下代码：

     warehouse.fetch().size
     

     Copy

   • 在 Snowsight 中导航到 Snowflake 账户，并确认仓库大小方面的更改。

8. 可选：如果您不想继续使用仓库，请将其删除。请在下一个单元格中运行以下代码：

   warehouse.drop()
   

   Copy

9. 要确认仓库是否删除，请在 Snowsight 中返回 Snowflake 账户。

下一步是什么？¶

恭喜！在本教程中，您学习了使用 Snowflake Python APIs 管理 Snowflake 资源对象的基础知识。