Tutorial 1: Eine Datenbank, ein Schema, eine Tabelle und ein Warehouse erstellen¶

Einführung¶

In diesem Tutorial lernen Sie die Grundlagen für das Management von Snowflake-Ressourcenobjekten mit Hilfe von Snowflake Python APIs kennen. Um mit API zu beginnen, erstellen und verwalten Sie eine Snowflake-Datenbank, ein Schema, eine Tabelle und ein virtuelles Warehouse.

Eine Datenbank, ein Schema und eine Tabelle erstellen¶

Sie können Ihr root-Objekt verwenden, um eine Datenbank, ein Schema und eine Tabelle in Ihrem Snowflake-Konto zu erstellen.

1. Um eine Datenbank zu erstellen, führen Sie in der nächsten Zelle Ihres Notebooks den folgenden Code aus:

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

   Copy

   Dieser Code, der in seiner Funktion dem Befehl SQL CREATE OR REPLACE DATABASE PYTHON_API_DB entspricht, erstellt eine Datenbank in Ihrem Konto mit dem Namen PYTHON_API_DB. Dieser Code folgt einem gängigen Muster für die Verwaltung von Objekten in Snowflake:

   • root.databases.create() erstellt eine Datenbank in Snowflake. Sie akzeptiert zwei Argumente: ein Database Objekt und einen Modus.

   • Mit Database(name="PYTHON_API_DB") übergeben Sie ein Objekt Database, und mit dem Argument name legen Sie den Namen der Datenbank fest. Sie erinnern sich, dass Sie Database in Zeile 3 des Notebooks importiert haben.

   • Sie geben den Modus für die Erstellung an, indem Sie das mode-Argument übergeben. In diesem Fall stellen Sie ihn auf CreateMode.or_replace ein, aber die folgenden Werte sind ebenfalls gültig:

     • CreateMode.if_not_exists: Funktional gleichwertig zu CREATE IF NOT EXISTS in SQL.

     • CreateMode.error_if_exists: Löst eine Ausnahme aus, wenn das Objekt bereits in Snowflake existiert. Dies ist der Standardwert, wenn kein Modus angegeben ist.

   • Sie verwalten die Datenbank programmgesteuert, indem Sie eine Referenz auf die Datenbank in einem von Ihnen erstellten Objekt namens database speichern.

2. Navigieren Sie unter Snowsight zum Datenbankabschnitt Ihres Snowflake-Kontos. Wenn Ihr Code erfolgreich war, wird die PYTHON_API_DB-Datenbank aufgelistet.

   Tipp

   Wenn Sie VS Code verwenden, installieren Sie die Snowflake-Erweiterung, um alle Snowflake-Objekte in Ihrem Editor zu erkunden.

3. Um ein Schema in der PYTHON_API_DB-Datenbank zu erstellen, führen Sie in Ihrer nächsten Zelle den folgenden Code aus:

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

   Copy

   Beachten Sie, dass Sie .schemas.create() für das zuvor erstellte database-Objekt aufrufen.

4. Um eine Tabelle in dem soeben erstellten Schema zu erstellen, führen Sie in Ihrer nächsten Zelle den folgenden Code aus:

   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

   Dieser Code erstellt eine Tabelle im PYTHON_API_SCHEMA-Schema mit zwei Spalten und ihren angegebenen Datentypen: TEMPERATURE als int und LOCATION als string.

   Diese beiden letzten Code-Beispiele sollten Ihnen bekannt vorkommen, denn sie folgen dem Muster aus dem ersten Schritt, in dem Sie die PYTHON_API_DB-Datenbank erstellt haben.

5. Um zu bestätigen, dass die Objekte erstellt wurden, kehren Sie zu Ihrem Snowflake-Konto unter Snowsight zurück.

Objektdaten abrufen¶

Sie können Metadaten über ein Objekt in Snowflake abrufen.

1. Um Details über die PYTHON_API_TABLE-Tabelle abzurufen, die Sie zuvor erstellt haben, führen Sie in der nächsten Notebookzelle den folgenden Code aus:

   table_details = table.fetch()
   

   Copy

   fetch() gibt ein TableModel-Objekt zurück.

2. Sie können dann .to_dict() für das resultierende Objekt aufrufen, um dessen detaillierte Informationen anzuzeigen.

   Um die Details der Tabelle zu drucken, führen Sie in der nächsten Zelle den folgenden Code aus:

   table_details.to_dict()
   

   Copy

   Das Notebook sollte ein Dictionary anzeigen, das Metadaten über die PYTHON_API_TABLE-Tabelle enthält, ähnlich wie hier:

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

   Wie gezeigt, enthält dieses Dictionary Informationen über die PYTHON_API_TABLE-Tabelle, die Sie zuvor erstellt haben, mit detaillierten Informationen über columns, owner, database, schema und mehr.

Objektmetadaten sind nützlich, wenn Sie die Geschäftslogik in Ihrer Anwendung aufbauen. Sie können zum Beispiel eine Logik erstellen, die in Abhängigkeit von bestimmten Informationen über ein Objekt ausgeführt wird. Sie können fetch() verwenden, um Objektmetadaten in solchen Szenarien abzurufen.

Programmgesteuert eine Tabelle ändern¶

Sie können programmgesteuert eine Spalte zu einer Tabelle hinzufügen. Die Tabelle PYTHON_API_TABLE hat derzeit zwei Spalten: TEMPERATURE und LOCATION. In diesem Szenario möchten Sie eine neue Spalte namens ELEVATION vom Typ int hinzufügen und diese als Primärschlüssel der Tabelle festlegen.

1. Führen Sie in Ihrer nächsten Zelle den folgenden Code aus:

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

   Copy

   Bemerkung

   Mit diesem Code wird die Spalte nicht erstellt. Stattdessen wird diese Spaltendefinition an das Array angehängt, das die Spalten der Tabelle in TableModel darstellt. Um dieses Array anzuzeigen, überprüfen Sie den Wert von columns, wie in den Anweisungen zum Anzeigen der Metadaten der Tabelle beschrieben.

2. Um die Tabelle zu ändern und die Spalte hinzuzufügen, führen Sie in der nächsten Zelle den folgenden Code aus:

   table.create_or_alter(table_details)
   

   Copy

   In dieser Zeile rufen Sie create_or_alter() auf dem Objekt auf, das PYTHON_API_TABLE repräsentiert, und übergeben den aktualisierten Wert von table_details. Diese Zeile fügt die Spalte ELEVATION zu PYTHON_API_TABLE hinzu.

3. Um zu bestätigen, dass die Spalte hinzugefügt wurde, führen Sie in Ihrer nächsten Zelle den folgenden Code aus:

   table.fetch().to_dict()
   

   Copy

   Die Ausgabe sollte in etwa so aussehen:

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

   Überprüfen Sie den Wert von columns und den Wert von constraints, die beide jetzt die ELEVATION-Spalte enthalten.

4. Um die Existenz der neuen Spalte zu bestätigen, kehren Sie zu Ihrem Snowflake-Konto unter Snowsight zurück, und sehen Sie sich die Tabelle an.

Erstellen und verwalten Sie ein Warehouse¶

Sie können virtuelle Warehouses auch mit dem Snowflake Python APIs verwalten. Es kann zum Beispiel sein, dass Sie vorübergehend ein anderes Warehouse erstellen müssen, um bestimmte Abfragen durchzuführen. In diesem Szenario können Sie die API verwenden, um ein Warehouse zu erstellen, auszusetzen oder zu löschen.

1. Um die Sammlung der Warehouses abzurufen, die mit Ihrer Sitzung verbunden sind, führen Sie in der nächsten Zelle den folgenden Code aus:

   warehouses = root.warehouses
   

   Copy

   Sie verwalten Warehouses in Ihrer Sitzung mit dem daraus resultierenden warehouses-Objekt.

2. Um ein neues Warehouse zu definieren und zu erstellen, führen Sie in Ihrer nächsten Zelle den folgenden Code aus:

   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

   In diesem Code definieren Sie ein neues Warehouse, indem Sie Warehouse instanziieren und den Namen, die Größe und die Auto-Suspend-Richtlinie des Warehouses angeben. Der Timeout für die automatische Unterbrechung wird in Sekunden angegeben. In diesem Fall wird das Warehouse nach 8,33 Minuten der Inaktivität ausgesetzt.

   Anschließend erstellen Sie das Warehouse, indem Sie create() für Ihre Warehouse-Sammlung aufrufen. Sie speichern die Referenz in dem resultierenden warehouse-Objekt.

3. Navigieren Sie zu Ihrem Snowflake-Konto auf Snowsight, und bestätigen Sie, dass das Warehouse erstellt wurde.

4. Um Informationen über das Warehouse abzurufen, führen Sie in Ihrer nächsten Zelle den folgenden Code aus:

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

   Copy

   Dieser Code sollte Ihnen bekannt vorkommen, da er dem gleichen Muster folgt, das Sie in einem früheren Schritt zum Abrufen von Metadaten der Tabelle verwendet haben. Die Ausgabe sollte in etwa so aussehen:

   {
     '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. Optional: Wenn Sie mehrere Warehouses in Ihrer Sitzung haben, verwenden Sie API, um diese durchzugehen oder um nach einem bestimmten Warehouse zu suchen.

   Führen Sie in Ihrer nächsten Zelle den folgenden Code aus:

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

   Copy

   In diesem Code rufen Sie iter() für die Warehouse-Sammlung auf und übergeben das like-Argument, das alle Warehouses zurückgibt, deren Namen mit der angegebenen Zeichenfolge übereinstimmen. In diesem Fall übergeben Sie den Namen des Warehouse, den Sie zuvor definiert haben, aber dieses Argument ist in der Regel eine Zeichenfolge ohne Berücksichtigung der Groß- und Kleinschreibung, die als Filter fungiert, mit Unterstützung für SQL-Platzhalterzeichen wie % und _.

   Nachdem Sie die Zelle ausgeführt haben, zeigt eine Ausgabe ähnlich dem folgenden Code, dass Sie erfolgreich ein passendes Warehouse gefunden haben:

   {
     '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. Um das Warehouse programmgesteuert zu ändern, indem Sie seine Größe in LARGE ändern, führen Sie in der nächsten Zelle den folgenden Code aus:

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

   Copy

7. Um zu bestätigen, dass die Warehouse-Größe auf LARGE aktualisiert wurde, führen Sie einen der folgenden Schritte aus:

   • Führen Sie in Ihrer nächsten Zelle den folgenden Code aus:

     warehouse.fetch().size
     

     Copy

   • Navigieren Sie zu Ihrem Snowflake-Konto auf Snowsight, und bestätigen Sie die Änderung der Warehouse-Größe.

8. Optional: Wenn Sie das Warehouse nicht weiter verwenden möchten, löschen Sie es. Führen Sie in Ihrer nächsten Zelle den folgenden Code aus:

   warehouse.drop()
   

   Copy

9. Um die Löschung des Warehouses zu bestätigen, kehren Sie zu Ihrem Snowflake-Konto auf Snowsight zurück.

Nächste Schritte¶

Herzlichen Glückwunsch! In diesem Tutorial haben Sie die Grundlagen für das Management von Snowflake-Ressourcenobjekten mit Hilfe von Snowflake Python APIs kennengelernt.