Tutorial: Erstellen Sie Ihre erste Apache Iceberg™-Tabelle¶

Lerninhalte¶

In diesem Tutorial lernen Sie Folgendes:

• Eine externes Volume für Snowflake-verwaltete Iceberg-Tabellen erstellen und konfigurieren. Zu Demonstrationszwecken erstellt das Tutorial ein externes Volume für Amazon S3.

• Erstellen Sie zwei Iceberg-Tabellen, die Snowflake als Iceberg-Katalog verwenden (Snowflake-verwaltete Tabellen).

• Daten in die Iceberg-Tabellen einfügen.

• Iceberg-Tabellen abfragen.

• Löschen Sie Zeilen aus einer Iceberg-Tabelle.

Voraussetzungen¶

Bevor Sie beginnen, sollten Sie mit den folgenden Punkten vertraut sein:

• Objektbezeichner in Snowflake und deren Anforderungen.

• Apache Iceberg und Iceberg-Tabellen in Snowflake. Weitere Informationen dazu finden Sie unter Apache Iceberg™-Tabellen.

• Cloud-Objektspeicher.

• Wenn Sie S3 verwenden, sollten Sie mit AWS Identity and Access Management (IAM) und IAM-Richtlinienelemente vertraut sein.

Sie benötigen:

• Snowflake-Benutzer mit einer Rolle, die die Berechtigungen hat, die folgenden Aktionen auszuführen:

  • CREATE WAREHOUSE

  • CREATE DATABASE

  • CREATE EXTERNAL VOLUME

  • CREATE ICEBERG TABLE

  Bei Verwendung eines 30-Tage-Testkontos können Sie sich als der Benutzer anmelden, der für das Konto erstellt wurde. Dieser Benutzer hat die Rolle mit den Berechtigungen, die zum Erstellen der Objekte erforderlich sind.

  Wenn Sie keinen Benutzer mit den erforderlichen Berechtigungen haben, bitten Sie jemanden, der über die erforderlichen Berechtigungen verfügt, einen Benutzer für Sie zu erstellen. Benutzer mit der Rolle ACCOUNTADMIN können neue Benutzer erstellen und ihnen die erforderlichen Berechtigungen erteilen.

• Administrator-Zugriff für Ihren Cloudspeicher-Anbieter, um ein externes Volume zu konfigurieren.

• Speicher-Bucket (oder Container) bei demselben Cloudanbieter (in derselben Region), der Ihr Snowflake-Konto hostet.

• Zugriff auf die Datenbank SNOWFLAKE_SAMPLE_DATA in Ihrem Konto. Snowflake erstellt die Beispieldatenbank standardmäßig in neuen Konten. Wenn die Datenbank nicht in Ihrem Konto erstellt wurde, finden Sie weitere Informationen unter Verwenden der Beispieldatenbank.

IAM-Richtlinie erstellen, die Zugriff auf den S3-Speicherort gewährt¶

Um die Zugriffsberechtigungen für Snowflake in der AWS-Managementkonsole zu konfigurieren, gehen Sie wie folgt vor:

1. Melden Sie sich bei der AWS Management Console an.

2. Suchen Sie auf dem Home-Dashboard nach IAM, und wählen Sie es aus.

3. Wählen Sie im linken Navigationsbereich Account settings aus.

4. Unter Security Token Service (STS) in der Liste Endpoints finden Sie die Snowflake-Region, in der sich Ihr Konto befindet. Wenn STS status inaktiv ist, stellen Sie den Umschalter auf Active.

5. Wählen Sie im linken Navigationsbereich Policies aus.

6. Wählen Sie Create Policy aus.

   

7. Wählen Sie unter Policy editor die Option JSON aus.

8. Fügen Sie eine Richtlinie hinzu, um Snowflake mit den erforderlichen Berechtigungen zum Lesen und Schreiben von Daten an Ihrem S3-Speicherort auszustatten.

   Die folgende Beispielrichtlinie gewährt Zugriff auf alle Speicherorte im angegebenen Bucket.

   Bemerkung

   • Ersetzen Sie my_bucket durch den tatsächlichen Namen Ihres Buckets. Sie können auch einen Pfad im Bucket angeben, zum Beispiel my_bucket/path.

   • Wenn Sie die Bedingung "s3:prefix": auf ["*"] setzen, erhalten Sie Zugriff auf alle Präfixe im angegebenen Bucket, und wenn Sie die Bedingung auf ["path/*"] setzen, erhalten Sie Zugriff auf einen bestimmten Pfad im Bucket.

   • Für Buckets in Regionen für Regierungsbehörden wird für die Bucket-ARNs das Präfix arn:aws-us-gov:s3::: verwendet.

   {
      "Version": "2012-10-17",
      "Statement": [
            {
               "Effect": "Allow",
               "Action": [
                  "s3:PutObject",
                  "s3:GetObject",
                  "s3:GetObjectVersion",
                  "s3:DeleteObject",
                  "s3:DeleteObjectVersion"
               ],
               "Resource": "arn:aws:s3:::<my_bucket>/*"
            },
            {
               "Effect": "Allow",
               "Action": [
                  "s3:ListBucket",
                  "s3:GetBucketLocation"
               ],
               "Resource": "arn:aws:s3:::<my_bucket>",
               "Condition": {
                  "StringLike": {
                        "s3:prefix": [
                           "*"
                        ]
                  }
               }
            }
      ]
   }
   

   Copy

9. Wählen Sie Next aus.

10. Geben Sie unter Policy name den Namen der Richtlinie (z. B. snowflake_access) und unter Description eine optionale Beschreibung ein.

11. Wählen Sie Create policy aus.

-IAM Rolle erstellen¶

Erstellen Sie eine AWS-IAM-Rolle, um Berechtigungen für den S3-Bucket mit Ihren Datendateien zu vergeben.

1. Wählen Sie im linken Navigationsbereich des Identity and Access Management (IAM)-Dashboards die Option Roles aus.

2. Wählen Sie Create role aus.

3. Wählen Sie für den Typ der vertrauenswürdigen Entität AWS account.

4. Wählen Sie unter An AWS account die Option This account aus. In einem späteren Schritt ändern Sie die Vertrauensstellung und gewähren Snowflake Zugriff.

5. Wählen Sie die Option Require external ID aus. Geben Sie eine externe ID Ihrer Wahl ein. Beispiel: iceberg_table_external_id.

   Eine externe ID wird verwendet, um einer dritten Partei wie Snowflake Zugriff auf Ihre AWS-Ressourcen (wie S3-Buckets) zu gewähren.

   

6. Wählen Sie Next aus.

7. Wählen Sie die Richtlinie, die Sie für das externe Volume erstellt haben, und wählen Sie dann Next.

8. Geben Sie unter Role name einen Namen und eine Beschreibung für die Rolle ein, und wählen Sie zum Erstellen Create role aus.

   Sie haben nun eine IAM-Richtlinie für einen S3-Speicherort erstellt, eine IAM-Rolle erstellt und die Richtlinie an die Rolle angehängt.

9. Wählen Sie View role, um die Rollenübersichtsseite anzuzeigen. Suchen Sie den ARN (Amazon Resource Name) für die Rolle, und notieren Sie sich den Wert.

   

Externes Volume in Snowflake erstellen¶

Erstellen Sie mit dem Befehl CREATE EXTERNAL VOLUME ein externes Volume. Im folgenden Beispiel wird ein externes Volume namens iceberg_external_volume erstellt, das einen Amazon S3-Speicherort mit Verschlüsselung definiert:

CREATE OR REPLACE EXTERNAL VOLUME iceberg_external_volume
   STORAGE_LOCATIONS =
      (
         (
            NAME = 'my-s3-us-west-2'
            STORAGE_PROVIDER = 'S3'
            STORAGE_BASE_URL = 's3://<my_bucket>/'
            STORAGE_AWS_ROLE_ARN = '<arn:aws:iam::123456789012:role/myrole>'
            STORAGE_AWS_EXTERNAL_ID = 'iceberg_table_external_id'
         )
      );

Das Beispiel gibt die externe ID (iceberg_table_external_id) an, die mit der IAM-Rolle verbunden ist, die Sie für das externe Volume erstellt haben. Durch das Angeben einer externen ID können Sie dieselbe IAM-Rolle (und externe ID) für mehrere externe Volumes verwenden.

AWS-IAM-Benutzer für Ihr Snowflake-Konto abrufen¶

1. Um den ARN für den AWS-IAM-Benutzer abzurufen, der automatisch für Ihr Snowflake-Konto erstellt wurde, verwenden Sie den Befehl DESCRIBE EXTERNAL VOLUME. Geben Sie den Namen Ihres externen Volumes an.

   Im folgenden Beispiel wird ein externes Volume namens iceberg_external_volume beschrieben:

   DESC EXTERNAL VOLUME iceberg_external_volume;
   

   Copy

2. Notieren Sie sich den Wert der Eigenschaft STORAGE_AWS_IAM_USER_ARN, der dem für Ihr Snowflake-Konto erstellten AWS-IAM-Benutzer entspricht, z. B. arn:aws:iam::123456789001:user/abc1-b-self1234.

   Snowflake stellt genau einen IAM-Benutzer für Ihr gesamtes Snowflake-Konto bereit. Dieser IAM-Benutzer wird von allen externen S3-Volumes in Ihrem Konto verwendet.

   Bemerkung

   Wenn Sie beim Erstellen eines externen Volumes keine externe ID (STORAGE_AWS_EXTERNAL_ID) angegeben haben, generiert Snowflake eine ID, die Sie verwenden können. Notieren Sie sich den Wert, damit Sie Ihre IAM-Rollen-Vertrauensrichtlinie mit der generierten externen ID aktualisieren können.

IAM-Benutzerberechtigungen für den Zugriff auf Bucket-Objekte erteilen¶

In diesem Schritt konfigurieren Sie Berechtigungen, die dem IAM-Benutzer Ihres Snowflake-Kontos den Zugriff auf Objekte in Ihrem S3-Bucket ermöglichen.

1. Melden Sie sich bei der AWS Management Console an.

2. Suchen Sie auf dem Home-Dashboard nach IAM, und wählen Sie es aus.

3. Wählen Sie im linken Navigationsbereich Roles aus.

4. Wählen Sie die IAM-Rolle aus, die Sie für Ihr externes Volume erstellt haben.

5. Wählen Sie die Registerkarte Trust relationships aus.

6. Wählen Sie Edit trust policy aus.

7. Ändern Sie das Richtliniendokument mit den DESC EXTERNAL VOLUME-Ausgabewerten, die Sie sich notiert haben.

   

   Richtliniendokument für die IAM-Rolle

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "AWS": "<snowflake_user_arn>"
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "sts:ExternalId": "<iceberg_table_external_id>"
           }
         }
       }
     ]
   }
   

   Copy

   Wobei:

   • snowflake_user_arn ist der von Ihnen notierte STORAGE_AWS_IAM_USER_ARN-Wert.

   • iceberg_table_external_id ist Ihre externe ID. Wenn Sie bereits beim Erstellen der Rolle eine externe ID angegeben haben und dieselbe ID zum Erstellen Ihres externen Volumes verwendet haben, lassen Sie den Wert unverändert. Andernfalls aktualisieren Sie sts:ExternalId mit dem Wert, den Sie sich notiert haben.

   Bemerkung

   Sie müssen dieses Richtliniendokument aktualisieren, wenn Sie ein neues externes Volume erstellen (oder ein vorhandenes externes Volume mit der CREATE OR REPLACE EXTERNAL VOLUME-Syntax erneut erstellen) und keine eigene externe ID bereitstellen. Aus Sicherheitsgründen hat ein neues oder neu erstelltes externes Volume eine andere externe ID und kann die Vertrauensstellung nur auflösen, wenn Sie diese Vertrauensrichtlinie aktualisieren.

8. Wählen Sie Update policy aus, um Ihre Änderungen zu speichern.

Erstellen Sie eine Tabelle mit der Standardsyntax¶

Erstellen Sie zunächst eine Iceberg-Tabelle mit der Standard-Syntax CREATE ICEBERG TABLE.

Geben Sie CATALOG = 'SNOWFLAKE' an, damit die Tabelle Snowflake als Iceberg-Katalog verwendet.

Um Snowflake mitzuteilen, wohin Tabellendaten und Metadaten geschrieben werden sollen, geben Sie einen Wert für den Parameter BASE_LOCATION an. Das Beispiel legt den Tabellennamen (customer_iceberg) als BASE_LOCATION fest. Auf diese Weise schreibt Snowflake Daten und Metadaten in ein Verzeichnis, das denselben Namen wie die Tabelle am Speicherort des externen Volumes hat.

CREATE OR REPLACE ICEBERG TABLE customer_iceberg (
    c_custkey INTEGER,
    c_name STRING,
    c_address STRING,
    c_nationkey INTEGER,
    c_phone STRING,
    c_acctbal INTEGER,
    c_mktsegment STRING,
    c_comment STRING
)
    CATALOG = 'SNOWFLAKE'
    EXTERNAL_VOLUME = 'iceberg_external_volume'
    BASE_LOCATION = 'customer_iceberg';

Im weiteren Verlauf des Tutorials laden Sie Daten aus der Tabelle snowflake_sample_data.tpch_sf1.customer der Datenbank SNOWFLAKE_SAMPLE_DATA in diese Tabelle. Die Spaltendefinitionen in der CREATE ICEBERG TABLE-Anweisung stimmen mit der Beispieltabelle überein.

Legen Sie die Katalogintegration und das externe Volume für die Datenbank fest¶

Legen Sie als Nächstes die Parameter CATALOG und EXTERNAL_VOLUME für die Datenbank iceberg_tutorial_db fest, die Sie in diesem Tutorial erstellt haben. Durch das Einstellen der Parameter wird Snowflake angewiesen, den von Ihnen gewählten Katalog und das externe Volume für alle Iceberg-Tabellen zu verwenden, die nach der Änderung erstellt werden.

ALTER DATABASE iceberg_tutorial_db SET CATALOG = 'SNOWFLAKE';
ALTER DATABASE iceberg_tutorial_db SET EXTERNAL_VOLUME = 'iceberg_external_volume';

Überprüfen Sie dazu die Parameter für die aktuelle Datenbank (iceberg_tutorial_db):

SHOW PARAMETERS IN DATABASE ;

Erstellen Sie eine Tabelle mit CTAS¶

Erstellen Sie schließlich eine zweite Iceberg-Tabelle namens nation_iceberg unter Verwendung der CREATE ICEBERG TABLE … AS SELECT-Syntax. Als Grundlage für die neue Tabelle dient die Tabelle snowflake_sample_data.tpch_sf1.nation der Snowflake-Beispieldatenbank.

CREATE OR REPLACE ICEBERG TABLE nation_iceberg (
  n_nationkey INTEGER,
  n_name STRING
)
  BASE_LOCATION = 'nation_iceberg'
  AS SELECT
    N_NATIONKEY,
    N_NAME
  FROM snowflake_sample_data.tpch_sf1.nation;