チュートリアル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 オブジェクトとモードの2つです。

   • 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 データベースが表示されます。

   Tip

   VS Codeをお使いの場合は、 Snowflakeエクステンション をインストールすると、エディター内ですべてのSnowflakeオブジェクトを探索できます。

3. PYTHON_API_DB データベースにスキーマを作成するには、次のセルで次のコードを実行します。

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

   Copy

   .schemas.create() を先に作成した database で呼び出すことにご注意ください。

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 として、2つの列とそのデータ型を指定したテーブルを作成します。

   この最後の2つのコード例は、 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 の2つの列があります。このシナリオでは、 int 型の ELEVATION という新しい列を追加し、それをテーブルの主キーに設定します。

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 の更新値を渡しています。この行は PYTHON_API_TABLE に ELEVATION 列を追加します。

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 リソースオブジェクトを管理するための基礎を学びました。