Snowflake Python APIs：一般概念

Snowflake Python APIs 采用 基于资源的 编程模型，这意味着 APIs 由一组对象组成，这些对象在 Snowflake 中分别代表其对应的对象。Snowflake 资源对象类型的一些基本示例包括：

  • 数据库

  • 架构

  • 表

  • 视图

  • 警报

  • 管道

  • 暂存区

  • 用户

  • 仓库

对于每种支持的资源，Python API 提供了三个不同的类，可用于创建和管理对象：

入口点：Root 对象

Root 对象是 Python API 的入口点。要创建一个通过 Root 将在其中运行的 Snowflake 上下文配置的该对象实例，您需要使用 Python Connector Connection 对象或 Snowpark Session 对象。

例如，以下代码使用名为 my_connection 的 Connection 对象实例化了 Root 对象：

from snowflake.core import Root

root = Root(my_connection)

您也可以使用 Session 对象实例化 Root 对象。在笔记本环境或存储过程中，可以使用 get_active_session() 检索会话，如下所示：

from snowflake.core import Root
from snowflake.snowpark.context import get_active_session

session = get_active_session()
root = Root(session)

账户、数据库和架构范围

使用 Root 对象，您可以访问 账户范围 对象的集合，例如仓库 (root.warehouses)、数据库 (root.databases) 和外部卷 (root.external_volumes)。

您可以访问 DatabaseResource 下的 数据库范围内的 对象，进而可以通过 Root 下的 DatabaseCollection 对象进行检索。目前，SchemaCollection 是数据库范围内唯一可用的对象类型。

您可以通过 SchemaResource 对象访问 架构范围内的 对象，例如表、视图、流和暂存区。

例如，以下代码首先访问 StageCollection，然后访问 StageResource：

root = Root(my_connection)
stages = root.databases["my_db"].schemas["my_schema"].stages
my_stage = stages["my_stage"] # Access the "my_stage" StageResource

snowflake.core 类图

下图显示了 snowflake.core 包中的一些基本类以及它们之间的关系，首先是 Root 对象：

此图显示了 snowflake.core 包中的一些基本类以及它们之间的关系

集合类

Collection 类对应于名为 <SnowflakeObjectType>集合 的类。

Collection 类表示在给定上下文中可见的特定对象类型的集合。对于架构范围内的对象（如表、视图、函数和流），集合由给定架构中当前角色或用户可见的所有该类型的对象组成。

SchemaCollection 对象的范围限定于一个数据库。诸如 DatabaseCollection 和 WarehouseCollection 这样的账户范围的对象可以直接通过 Root 实例访问。

通常，集合允许您执行以下操作：

  • 在架构、数据库或账户中创建对象（视范围和上下文而定，如前所述）。

  • 循环访问该范围内可见的对象集。

例如，以下代码使用 WarehouseCollection 对象创建新仓库：

# my_wh is created from scratch
my_wh = Warehouse(name="my_wh", warehouse_size="X-Small")
root.warehouses.create(my_wh)

从集合中检索 Resource 对象

此外，集合提供了一个入口点，用于检索 API 所连接的底层 Snowflake 数据库中特定的 Resource 对象。您可以使用集合上的方括号索引运算符 ([ ]) 来“指向”或获取该集合内 Snowflake 对象的引用。

例如，以下代码会检索 Snowflake 账户中名为 my_wh 的现有仓库的引用：

# my_wh_ref is retrieved from an existing warehouse
# This returns a WarehouseResource object, which is a reference to a warehouse named "my_wh" in your Snowflake account
my_wh_ref = root.warehouses["my_wh"]

模型类

模型类与 Snowflake 中等效资源的名称完全相同，例如 Warehouse 对应仓库，Table 对应表。

模型类表示 Snowflake 对象及其关联属性，例如对象的名称、所属的数据库和架构（如适用）以及特定于该对象类型的属性。例如，仓库模型表示该特定仓库对象的 warehouse_size、type 和 auto_resume 属性。

模型对象包含描述该对象的 *属性包*（属性及其值的集合）。您可以使用这些属性来描述 Snowflake 中的现有对象，也可以提供更改现有对象所用的资源的规范。

从 Resource 提取模型对象

要返回 Snowflake 数据库中当前存在的对象的属性包，需要对 Resource 对象运行 fetch() 操作。

例如，以下代码演示了您可以使用模型对象执行的一些操作：

# my_wh is fetched from an existing warehouse
my_wh = root.warehouses["my_wh"].fetch()
print(my_wh.name, my_wh.auto_resume)

# my_wh is fetched from an existing warehouse
my_wh = root.warehouses["my_wh"].fetch()
my_wh.warehouse_size = "X-Small"
root.warehouses["my_wh"].create_or_alter(my_wh)

备注

如果 Snowflake 中不存在该 my_wh 对象，则此提取操作将失败。

资源类

Resource 类对应于名为 <SnowflakeObjectType>资源 的类。

您可以将 Resource 对象视为指向底层 Snowflake 对象的指针或引用。模型类是代表对象属性或规范的简单属性包，而 Resource 类是对 Snowflake 数据库中实际对象的引用。

要获取 Resource 对象，通常需要从其对应的 Collection 中通过名称引用它，并使用方括号索引运算符 ([ ])。以下代码示例从仓库集合中检索一个名为 my_wh 的现有仓库：

# my_wh_ref is retrieved from an existing warehouse
# This returns a WarehouseResource object, which is a reference to a warehouse named "my_wh" in your Snowflake account
my_wh_ref = root.warehouses["my_wh"]

# Fetch returns the properties of the object (returns a "Model" Warehouse object that represents that warehouse's properties)
wh_properties = my_wh_ref.fetch()

要将 Resource 对象转换为其相应的模型，请在资源上执行 fetch()，检索 Snowflake 中相应对象的属性。如果 Snowflake 中不存在该对象，则此提取操作将失败。

对 Resource 对象执行特定类型的操作

Resource 类还实施了对象类型的专属 API 操作。例如，您可以使用 WarehouseResource 对象来恢复仓库，或使用 StageResource 对象来列出暂存区的文件。

以下代码示例显示了如何使用相应的 Resource 对象执行这些特定类型的操作：

# my_wh_ref is retrieved from an existing warehouse
my_wh_ref = root.warehouses["my_wh"]

# Resume a warehouse using a WarehouseResource object
my_wh_ref.resume()

# my_stage is retrieved from an existing stage
stage_ref = root.databases["my_db"].schemas["my_schema"].stages["my_stage"]

# Print file names and their sizes on a stage using a StageResource object
for file in stage_ref.list_files():
  print(file.name, file.size)

使用 create_or_alter API

如果资源支持，Resource 对象也会公开 :code:`create_or_alter`API 方法。顾名思义，此方法让您能够创建或更改 Snowflake 对象。

备注

Python API 使用这种创建或更改 (COA) 机制来修改 Snowflake 中的对象。此机制旨在确保无论特定对象是否已存在于 Snowflake 数据库中，COA 操作结果都是相同的。

换句话说，如果对象不存在，则 COA 操作会使用提供的规范创建一个对象；如果该对象存在，则该操作会更改现有对象以匹配所请求的规范。此逻辑使您能够通过使用一段代码，以幂等和原子方式创建或更改资源。

管理资源的统一设计模式

Snowflake Python APIs 具有一致的设计模式，可用于管理 Snowflake 中的资源。以一个示例场景为例，您需要更改账户中现有的仓库对象。以下步骤概述了您通常如何使用前面描述的三种类类型，按照 API 的设计模式进行操作。

1. 从 Root 中获取 WarehouseCollection

仓库是账户范围内的对象，您可以直接通过 Root 访问：

my_warehouses = root.warehouses # my_warehouses is a WarehouseCollection

2. 从 WarehouseCollection 中获取 WarehouseResource 对象

要检索 Resource 对象，通常从其集合开始。Collection 对象为您提供了一个入口点，让您可以使用方括号索引运算符 ([ ]) 检索底层 Snowflake 数据库中的特定资源

my_wh_ref = my_warehouses.warehouses["my_wh"] # my_wh_ref is a WarehouseResource

3. 从 WarehouseResource 中提取 Warehouse 模型

使用 WarehouseResource 对象，您可以从 Snowflake 中提取相应的 Warehouse 模型及其属性：

my_wh = my_wh_ref.fetch() # my_wh is a Warehouse model object

4. 修改 Warehouse 模型中的属性

修改仓库模型中的属性，例如 warehouse_size：

my_wh.warehouse_size = "X-Small"

5. 更改 Snowflake 中的现有仓库对象

最后，使用修改后的仓库模型规范，更改 Snowflake 中的现有仓库对象（如果不存在，则创建仓库对象）：

my_wh_ref.create_or_alter(my_wh) # Use the WarehouseResource to perform create_or_alter

使用此 my_wh_ref 引用，还可以在 Snowflake 中对该对象执行其他操作，例如根据需要将其删除。

完整代码示例

以下代码示例展示了从开始到结束完整的创建或更改仓库操作：

# my_wh is fetched from an existing warehouse
my_warehouses = root.warehouses # my_warehouses is a WarehouseCollection
my_wh_ref = my_warehouses.warehouses["my_wh"] # my_wh_ref is a WarehouseResource
my_wh = my_wh_ref.fetch() # my_wh is a Warehouse model object
my_wh.warehouse_size = "X-Small"

my_wh_ref.create_or_alter(my_wh) # Use the WarehouseResource perform create_or_alter