Snowflake Python APIs: Allgemeine Konzepte¶
Das Programmiermodell von Snowflake Python APIs ist Ressourcen-basiert, d. h. APIs besteht aus einer Reihe von Objekten, die ihre jeweiligen Objekt-Gegenstücke in Snowflake darstellen. Einige grundlegenden Beispiele für Snowflake Ressourcen-Objekttypen sind die folgenden:
Datenbanken
Schemas
Tabellen
Ansichten
Alerts
Pipes
Stagingbereiche
Benutzer
Warehouses
Für jede unterstützte Ressource bietet die Python-API drei verschiedene Klassen, die Sie als Weboberfläche mit Folgendem verwenden können:
Einstiegspunkt: Das Root-Objekt¶
Das Root-Objekt ist der Einstiegspunkt für die Python-API. Sie erstellen eine Instanz von Root, die mit dem Snowflake-Kontext konfiguriert ist, in dem sie ausgeführt werden soll, indem Sie ein Python Konnektor Connection-Objekt oder ein Snowpark Session-Objekt verwenden.
Zum Beispiel instanziiert der folgende Code ein Root-Objekt mit einem Connection-Objekt namens my_connection:
from snowflake.core import Root
root = Root(my_connection)
Oder Sie können ein Root-Objekt mit einem Session-Objekt instanziieren. In einer Umgebung mit Notebooks oder einer gespeicherten Prozedur rufen Sie die Sitzung mit get_active_session() wie folgt ab:
from snowflake.core import Root
from snowflake.snowpark.context import get_active_session
session = get_active_session()
root = Root(session)
Konten-, Datenbank- und Schema-Bereiche (Scopes)¶
Mit einem Root-Objekt können Sie auf die Sammlungen von in den Bereich Konto fallende Objekten zugreifen, z. B. Warehouses (root.warehouses), Datenbanken (root.databases) und externe Datenträger (root.external_volumes).
Sie können auf in den Bereich Datenbank fallende Objekte unter einem DatabaseResource zugreifen, die Sie wiederum über das DatabaseCollection-Objekt unter Root abrufen können. Derzeit ist SchemaCollection der einzige Objekttyp, der im Bereich (Scope) der Datenbank verfügbar ist.
Sie können über das SchemaResource-Objekt auf in den Bereich Schema fallende Objekte wie Tabellen, Ansichten, Streams und Stagingbereiche zugreifen.
Der folgende Code greift zum Beispiel zuerst auf eine StageCollection und dann auf eine StageResource zu:
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-Klassendiagramm¶
Das folgende Diagramm zeigt einige grundlegende Klassen im snowflake.core-Paket und wie sie miteinander in Beziehung stehen, beginnend mit dem Root-Objekt.
Sammlungsklasse¶
Die Collection-Klassen entsprechen den Klassen, die <SnowflakeObjectType>Collection genannt werden.
Eine Collection-Klasse stellt die Menge eines bestimmten Objekttyps dar, die in einem bestimmten Kontext sichtbar ist. Bei Objekten, die in den Bereich des Schemas fallen (wie Tabellen, Ansichten, Funktionen und Streams), besteht die Sammlung aus allen Objekten dieses Typs innerhalb des gegebenen Schemas, die für die aktuelle Rolle oder den Benutzer sichtbar sind.
SchemaCollection-Objekte fallen in den Bereich Datenbank, und Objekte, die in den Bereich Konto fallen, wie z. B. WarehouseCollection, sind direkt über die Root-Instanz zugänglich.
Im Allgemeinen können Sie mit Sammlungen Folgendes tun:
Erstellen Sie ein Objekt im Schema, in der Datenbank oder im Konto (je nach Bereich (Scope) und Kontext wie zuvor beschrieben).
Iterieren Sie durch die Menge der in diesem Bereich (Scope) sichtbaren Objekte.
Der folgende Code erstellt zum Beispiel ein neues Warehouse mit einem WarehouseCollection-Objekt:
# my_wh is created from scratch
my_wh = Warehouse(name="my_wh", warehouse_size="X-Small")
root.warehouses.create(my_wh)
Abrufen eines Resource-Objekts aus einer Sammlung¶
Darüber hinaus bieten Sammlungen einen Einstiegspunkt zum Abrufen bestimmter Resource-Objekte in der zugrunde liegenden Snowflake-Datenbank, mit der API verbunden ist. Sie verwenden den Index-Operator in eckigen Klammern ([ ]) für eine Sammlung, um auf ein Snowflake-Objekt in dieser Sammlung zu verweisen oder eine Referenz darauf zu erhalten.
Der folgende Code ruft zum Beispiel eine Referenz auf ein bestehendes Warehouse namens my_wh in Ihrem Snowflake-Konto ab:
# 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"]
Modellklasse¶
Die Modellklassen haben einfach dieselben Namen wie die entsprechenden Ressourcen in Snowflake, z. B. Warehouse für Warehouses und Table für Tabellen.
Eine Modellklasse repräsentiert ein Snowflake-Objekt zusammen mit den zugehörigen Eigenschaften, wie z. B. dem Namen, der Datenbank und dem Schema, zu dem es gehört (falls zutreffend), und den für diesen Objekttyp spezifischen Attributen. Ein Modell für ein Warehouse zeigt zum Beispiel die Eigenschaften warehouse_size, type und auto_resume für dieses bestimmte Warehouse-Objekt an.
Modellobjekte enthalten eine „Eigenschaftstasche“ (eine Sammlung von Eigenschaften und deren Werten), die das Objekt insgesamt beschreibt. Sie können diese Eigenschaften verwenden, um entweder ein bestehendes Objekt in Snowflake zu beschreiben oder um die Spezifikation der Ressource bereitzustellen, mit der Sie ein bestehendes Objekt ändern möchten.
Das Abrufen eines Modellobjekts aus einer Resource¶
Um die Eigenschaftstasche eines Objekts so zurückzugeben, wie sie derzeit in Ihrer Snowflake-Datenbank vorhanden ist, führen Sie eine fetch()-Operation auf dem Resource-Objekt aus.
Der folgende Code veranschaulicht zum Beispiel einige Operationen, die Sie mit einem Modellobjekt durchführen können:
# 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)
Bemerkung
Diese Operation schlägt fehl, wenn das my_wh-Objekt nicht in Snowflake vorhanden ist.
Ressourcenklasse¶
Die Resource-Klassen entsprechen den Klassen, die <SnowflakeObjectType>Resource genannt werden.
Sie können ein Resource-Objekt als einen Zeiger oder eine Referenz auf ein zugrunde liegendes Snowflake-Objekt betrachten. Während die Modellklasse eine einfache Eigenschaftstasche ist, die die Eigenschaften oder Spezifikationen eines Objekts darstellt, ist die Resource-Klasse eine Referenz auf das tatsächliche Objekt in Ihrer Snowflake-Datenbank.
Um ein Resource-Objekt zu erhalten, beziehen Sie sich normalerweise über den Namen auf das entsprechende Collection, indem Sie den Index-Operator in eckigen Klammern verwenden ([ ]). Das folgende Codebeispiel ruft ein bestehendes Warehouse namens my_wh aus der Warehouse-Sammlung ab:
# 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()
Um ein Resource-Objekt in sein entsprechendes Modell umzuwandeln, führen Sie eine fetch() auf der Ressource aus – dadurch werden die Eigenschaften des entsprechenden Objekts in Snowflake abgerufen. Beachten Sie, dass diese Operation fehlschlägt, wenn das Objekt in Snowflake nicht existiert.
Durchführung von typspezifischen Operationen auf einem Resource-Objekt¶
Die Resource-Klasse implementiert auch die speziellen API-Operationen des Objekttyps. Sie verwenden z. B. ein WarehouseResource-Objekt, um ein Warehouse wieder aufzunehmen, oder ein StageResource-Objekt, um die Dateien in einem Stagingbereich aufzulisten.
Die folgenden Code-Beispiele zeigen, wie Sie diese typspezifischen Operationen mit den entsprechenden Resource-Objekten durchführen können:
# 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 fetched 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)
Verwenden der create_or_alter API¶
Resource-Objekte stellen auch die create_or_alter API-Methode zur Verfügung, wenn sie von der Ressource unterstützt wird. Mit dieser Methode können Sie, wie der Name schon sagt, Snowflake-Objekte erstellen oder verändern.
Bemerkung
Python-API verwendet diesen create-or-alter (COA)-Mechanismus zum Ändern von Objekten in Snowflake. Mit diesem Mechanismus soll sichergestellt werden, dass das Ergebnis einer COA-Operation dasselbe ist, unabhängig davon, ob das betreffende Objekt bereits in Ihrer Snowflake-Datenbank vorhanden war.
Mit anderen Worten: Wenn das Objekt noch nicht existierte, würde die COA-Operation eines mit der angegebenen Spezifikation erstellen. Wenn es bereits existierte, würde die Operation das vorhandene Objekt so ändern, dass es der angefragten Spezifikation entspricht. Mit dieser Logik können Sie Ressourcen mit einem einzigen Stück Code auf idempotente und atomare Weise erstellen oder ändern.
Konsistentes Muster für due Verwaltung von Ressourcen¶
Die Snowflake Python APIs haben ein einheitliches Muster, das Sie für die Verwaltung von Ressourcen in Snowflake verwenden. Nehmen wir ein Beispielszenario, in dem Sie ein bestehendes Warehouse-Objekt in Ihrem Konto ändern müssen. Die folgenden Schritte beschreiben, wie Sie typischerweise mit dem Designmuster der API arbeiten, indem Sie alle drei Klassentypen wie zuvor beschrieben verwenden.
1. Beziehen Sie eine WarehouseCollection von Root¶
Warehouses sind Objekte, die in den Bereich Konto fallen, auf die Sie direkt von Root aus zugreifen können:
my_warehouses = root.warehouses # my_warehouses is a WarehouseCollection
2. Beziehen Sie ein WarehouseResource-Objekt von WarehouseCollection¶
Um ein Resource-Objekt abzurufen, beginnen Sie in der Regel mit seiner Sammlung. Collection-Objekte bieten einen Einstiegspunkt, um bestimmte Ressourcen in der zugrunde liegenden Snowflake-Datenbank abzurufen, indem Sie den Index-Operator in eckigen Klammern verwenden ([ ]):
my_wh_ref = my_warehouses.warehouses["my_wh"] # my_wh_ref is a WarehouseResource
3. Rufen Sie das Modell Warehouse von WarehouseResource ab¶
Mit Hilfe des WarehouseResource-Objekts rufen Sie das entsprechende Warehouse-Modell und seine Eigenschaften aus Snowflake ab:
my_wh = my_wh_ref.fetch() # my_wh is a Warehouse model object
4. Ändern Sie eine Eigenschaft im Warehouse-Modell¶
Dann ändern Sie eine Eigenschaft, z. B. warehouse_size, in Ihrem Warehouse-Modell:
my_wh.warehouse_size = "X-Small"
5. Ändern Sie das bestehende Warehouse-Objekt in Snowflake¶
Schließlich ändern Sie das bestehende Warehouse-Objekt in Snowflake mit Hilfe Ihrer geänderten Spezifikation des Warehouse-Modells (oder Sie erstellen das Warehouse-Objekt, wenn es noch nicht existiert):
my_wh_ref.create_or_alter(my_wh) # Use the WarehouseResource to perform create_or_alter
Mit dieser my_wh_ref-Referenz können Sie auch andere Operationen mit dem Objekt in Snowflake durchführen, wie z. B. das Löschen des Objekts, falls erforderlich.
Vollständiges Code-Beispiel¶
Das folgende Code-Beispiel zeigt die Operation zum Erstellen oder Ändern von Warehouses vollständig von Anfang bis Ende:
# 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