CREATE CATALOG INTEGRATION (Apache Iceberg™ REST)¶

Syntax¶

CREATE [ OR REPLACE ] CATALOG INTEGRATION [ IF NOT EXISTS ] <name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<namespace>'
  REST_CONFIG = (
    restConfigParams
  )
  REST_AUTHENTICATION = (
    restAuthenticationParams
  )
  ENABLED = { TRUE | FALSE }
  [ REFRESH_INTERVAL_SECONDS = <value> ]
  [ COMMENT = '<string_literal>' ]

Wobei:

restConfigParams ::=

  CATALOG_URI = '<rest_api_endpoint_url>'
  PREFIX = '<prefix>'
  WAREHOUSE = '<warehouse_name>'
  CATALOG_API_TYPE = { PUBLIC | AWS_API_GATEWAY | AWS_PRIVATE_API_GATEWAY }

Abhängig von Ihrer Authentifizierungsmethode finden Sie unter restAuthenticationParams folgende Informationen:

OAuth

restAuthenticationParams (for OAuth) ::=

  TYPE = OAUTH
  OAUTH_TOKEN_URI = 'https://<token_server_uri>'
  OAUTH_CLIENT_ID = '<oauth_client_id>'
  OAUTH_CLIENT_SECRET = '<oauth_client_secret>'
  OAUTH_ALLOWED_SCOPES = ('<scope_1>', '<scope_2>')

Bearer-Token

restAuthenticationParams (for Bearer token) ::=

  TYPE = BEARER
  BEARER_TOKEN = '<bearer_token>'

SigV4

restAuthenticationParams (for SigV4) ::=

  TYPE = SIGV4
  SIGV4_IAM_ROLE = '<iam_role_arn>'
  SIGV4_SIGNING_REGION = '<region>'

Parameter¶

name

Zeichenfolge, die den Bezeichner (den Namen) für die Katalogintegration angibt. Muss in Ihrem Konto eindeutig sein.

Darüber hinaus muss der Bezeichner mit einem Buchstaben beginnen und darf keine Leer- oder Sonderzeichen enthalten, es sei denn, die gesamte Bezeichnerzeichenfolge wird in doppelte Anführungszeichen gesetzt (z. B. "My object"). Bei Bezeichnern, die in doppelte Anführungszeichen eingeschlossen sind, ist auch die Groß-/Kleinschreibung zu beachten.

Weitere Informationen dazu finden Sie unter Anforderungen an Bezeichner.

CATALOG_SOURCE = ICEBERG_REST

Gibt an, dass die Katalogquelle ein REST-Katalog ist, der mit der Apache Iceberg-REST-Spezifikation konform ist.

TABLE_FORMAT = ICEBERG

Gibt ICEBERG als das vom Katalog bereitgestellte Tabellenformat an.

CATALOG_NAMESPACE = 'namespace'

Gibt den Namespace im externen Katalog an. Snowflake verwendet diesen Namespace für alle Iceberg-Tabellen, die mit dieser Katalogintegration verbunden.

Sie können diesen Wert außer Kraft setzen, indem Sie einen Namespace auf Tabellenebene angeben, wenn Sie eine Tabelle erstellen.

ENABLED = { TRUE | FALSE }

Gibt an, ob die Katalogintegration für Iceberg-Tabellen verwendet werden kann.

• TRUE ermöglicht Benutzern das Erstellen neuer Iceberg-Tabelle, die auf diese Integration verweisen.

• FALSE verhindert, dass Benutzer neue Iceberg-Tabelle erstellen, die auf diese Integration verweisen.

REFRESH_INTERVAL_SECONDS = value

Legt die Anzahl der Sekunden fest, die Snowflake zwischen den Versuchen wartet, den externen Iceberg-Katalog nach Aktualisierungen der Metadaten für die automatische Aktualisierung abzufragen.

Werte: 30 bis einschließlich 86.400

Standard: 30 Sekunden.

Vorschaufunktion

Verfügbar bei allen Konten.

COMMENT = 'string_literal'

Zeichenfolge (Literal), die einen Kommentar zur Integration enthält.

Standard: Kein Wert

REST Parameter für die Authentifizierung (restAuthenticationParams)¶

Anforderungen an die Zugriffssteuerung¶

Eine Rolle, die zur Ausführung dieses SQL-Befehls verwendet wird, muss mindestens die folgenden Berechtigungen haben:

Eine Anleitung zum Erstellen einer kundenspezifischen Rolle mit einer bestimmten Gruppe von Berechtigungen finden Sie unter Erstellen von kundenspezifischen Rollen.

Allgemeine Informationen zu Rollen und Berechtigungen zur Durchführung von SQL-Aktionen auf sicherungsfähigen Objekten finden Sie unter Übersicht zur Zugriffssteuerung.

Nutzungshinweise¶

• Katalogintegrationen bieten einen schreibgeschützten Zugriff auf externe Iceberg-Kataloge.

• Sie können eine bestehende Katalogintegration nicht ändern; verwenden Sie stattdessen eine CREATE OR REPLACE CATALOG INTEGRATION-Anweisung.

• Sie können eine Katalogintegration nicht löschen oder ersetzen, wenn eine oder mehrere Apache Iceberg™-Tabellen mit der Katalogintegration verbunden sind.

  Um die Tabellen anzuzeigen, die von einer Katalogintegration abhängen, können Sie den Befehl SHOW ICEBERG TABLES und eine Abfrage mit RESULT_SCAN verwenden, die nach der Spalte catalog_name filtert.

  Bemerkung

  Beim Spaltenbezeichner (catalog_name) wird zwischen Groß- und Kleinschreibung unterschieden. Geben Sie den Spaltenbezeichner genau so an, wie er in der Ausgabe von SHOW ICEBERG TABLES erscheint.

  Beispiel:

  SHOW ICEBERG TABLES;
  
  SELECT * FROM TABLE(
    RESULT_SCAN(
        LAST_QUERY_ID()
      )
    )
    WHERE "catalog_name" = 'my_catalog_integration_1';
  

  Copy

• Metadaten:

  Achtung

  Kunden müssen sicherstellen, dass bei der Nutzung des Snowflake-Dienstes keine personenbezogenen Daten (außer für ein Objekt „Benutzer“), sensible Daten, exportkontrollierte Daten oder andere regulierte Daten als Metadaten eingegeben werden. Weitere Informationen dazu finden Sie unter Metadatenfelder in Snowflake.

• CREATE OR REPLACE <Objekt>-Anweisungen sind atomar. Das heißt, wenn ein Objekt ersetzt wird, erfolgt das Löschen des alten Objekts und das Erstellen des neuen Objekts in einer einzigen Transaktion.

Beispiele¶

Das folgende Beispiel erstellt eine REST-Katalogintegration, die OAuth zur Verbindung mit Tabular verwendet.

CREATE OR REPLACE CATALOG INTEGRATION tabular_catalog_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'default'
  REST_CONFIG = (
    CATALOG_URI = 'https://api.tabular.io/ws'
    WAREHOUSE = '<tabular_warehouse_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://api.tabular.io/ws/v1/oauth/tokens'
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_client_secret>'
    OAUTH_ALLOWED_SCOPES = ('catalog')
  )
  ENABLED = TRUE;