Snowflake Python APIs: 一般概念

Snowflake Python APIs のプログラミングモデルは、 リソースベース です。つまり、 APIs は、Snowflake の各オブジェクトに対応するオブジェクトのセットで構成されています。Snowflakeリソース・オブジェクト・タイプの基本的な例には、以下のようなものがあります。

  • データベース

  • スキーマ

  • テーブル

  • ビュー

  • アラート

  • パイプ

  • ステージ

  • ユーザー

  • ウェアハウス

サポートされるリソースごとに、Python API はオブジェクトの作成と管理に使用できる3つの異なるクラスを提供します：

エントリポイント: Root オブジェクト

Root オブジェクトは、Python API のエントリポイントです。実行する Snowflake コンテキストで構成された Root のインスタンスを作成するには、Python Connector Connection オブジェクトまたは Snowpark Session オブジェクトを使用します。

例えば、次のコードは Root オブジェクトを my_connection という Connection オブジェクトでインスタンス化します。

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 クラスダイアグラム

次の図は、 Root オブジェクトから始まる、 snowflake.core パッケージの基本的なクラスと、それらの相互関係を示しています。

snowflake.coreパッケージのいくつかの基本的なクラスと、それらがどのように互いに関連しているかを示す図。

コレクションクラス

Collection クラスは、 <SnowflakeObjectType>Collection という名前のクラスに対応します。

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モデルは、その特定のWarehouseオブジェクトの warehouse_size、 type、 auto_resume プロパティを示します。

Modeling オブジェクトは、オブジェクトを記述する プロパティバッグ （プロパティとその値のコレクション）を含んでいます。これらのプロパティを使用して、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)

注釈

my_wh オブジェクトが Snowflake に存在しない場合、この取得操作は失敗します。

リソースクラス

Resource クラスは、 <SnowflakeObjectType>Resource という名前のクラスに対応します。

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 オブジェクトは、リソースがサポートされていれば、 create_or_alter API メソッドも公開します。このメソッドでは、その名の通り、Snowflake・オブジェクトを作成したり、変更したりすることができます。

注釈

Python API は、Snowflake のオブジェクトを変更するために、この作成または変更（COA）メカニズムを使用します。このメカニズムの目的は、特定のオブジェクトがSnowflakeデータベースに既に存在するかどうかにかかわらず、 COA 操作の結果が同じになるようにすることです。

言い換えると、オブジェクトが存在しない場合、 COA オペレーションは指定された仕様でオブジェクトを作成します。オブジェクトがすでに存在する場合、オペレーションは既存のオブジェクトをリクエストされた仕様に合うように変更します。このロジックにより、べき等かつアトミックな方法で、1つのコードでリソースを作成または変更することができます。

リソースを管理する一貫したデザイン・パターン

Snowflake Python APIs には、Snowflake でリソースを管理するために使用する一貫したデザインパターンがあります。例えば、アカウント内の既存のウェアハウスオブジェクトを変更する必要がある場合を考えてみましょう。次のステップでは、 APIのデザイン・パターンを使って、前述の 3 つのクラス・タイプをすべて使用する方法について説明します。

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 オブジェクトを使用して、対応する Warehouse モデルとそのプロパティを Snowflake から取得します。

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