CREATE CATALOG INTEGRATION (Snowflake Open Catalog)¶

Erstellt eine neue Katalogintegration für Apache Iceberg™-Tabellen, die mit Snowflake Open Catalog im Konto integriert sind, oder ersetzt eine bestehende Katalogintegration.

Sie können diesen Befehl auch verwenden, um eine Katalogintegration für Iceberg-Tabellen in Apache Polaris™ zu erstellen.

Siehe auch:: ALTER CATALOG INTEGRATION , DROP CATALOG INTEGRATION , SHOW CATALOG INTEGRATIONS, DESCRIBE CATALOG INTEGRATION

Syntax¶

CATALOG_API_TYPE: PUBLIC¶

Verwenden Sie diese Katalogintegration, um Snowflake über das öffentliche Internet mit Open Catalog zu verbinden. Die Vorgabe für den Parameter CATALOG_API_TYPE ist PUBLIC, sodass Sie diesen Parameter nicht angeben müssen.

CREATE [ OR REPLACE ] CATALOG INTEGRATION [ IF NOT EXISTS ]
  <name>
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  [ CATALOG_NAMESPACE = '<open_catalog_namespace>' ]
  REST_CONFIG = (
    CATALOG_URI = '<open_catalog_account_url>'
    [ CATALOG_API_TYPE = PUBLIC ]
    CATALOG_NAME = '<open_catalog_catalog_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_secret>'
    OAUTH_ALLOWED_SCOPES = ('<scope 1>', '<scope 2>')
  )
  ENABLED = { TRUE | FALSE }
  [ REFRESH_INTERVAL_SECONDS = <value> ]
  [ COMMENT = '<string_literal>' ]

Copy

CATALOG_API_TYPE: PRIVATE¶

Wenn Sie private Konnektivität für den eingehenden Netzwerk-Datenverkehr in Snowflake Open Catalog verwenden, nutzen Sie diese Katalogintegration, um Snowflake über eine private IP-Adresse mit Open Catalog zu verbinden.

CREATE [ OR REPLACE ] CATALOG INTEGRATION [ IF NOT EXISTS ]
  <name>
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  [ CATALOG_NAMESPACE = '<open_catalog_namespace>' ]
  REST_CONFIG = (
    CATALOG_URI = '<open_catalog_account_url>'
    CATALOG_API_TYPE = PRIVATE
    CATALOG_NAME = '<open_catalog_catalog_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_secret>'
    OAUTH_ALLOWED_SCOPES = ('<scope 1>', '<scope 2>')
  )
  ENABLED = { TRUE | FALSE }
  [ REFRESH_INTERVAL_SECONDS = <value> ]
  [ COMMENT = '<string_literal>' ]

Copy

Erforderliche 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 = POLARIS

Gibt Snowflake Open Catalog als Katalogquelle an.

TABLE_FORMAT = ICEBERG

Legt Apache Iceberg™ als das vom Katalog gelieferte Tabellenformat fest.

REST_CONFIG = ( ... )

Gibt Informationen über Ihr Open Catalog-Konto und den Katalognamen an.

CATALOG_URI = 'https://open_catalog_account_url'
Ihre Open Catalog-Konto-URL. Folgende Werte werden unterstützt:

https://<open_catalog_account_identifier>.snowflakecomputing.com/polaris/api/catalog: Wenn CATALOG_API_TYPE = PUBLIC. Beispielwerte:

https://<orgname>-<my-snowflake-open-catalog-account-name>.snowflakecomputing.com/polaris/api/catalog

https://<Konto-Locator>.<ID_der_Cloudregion>.<Cloud>.snowflakecomputing.com/polaris/api/catalog

Bemerkung

Um Ihren Snowflake-Organisationsnamen (<orgname>) zu finden, folgen Sie den Schritten unter Suchen von Organisations- und Kontonamen eines Kontos.

Um <my-snowflake-open-catalog-account-name zu finden, siehe Den Kontonamen für ein Snowflake Open Catalog-Konto finden in der Dokumentation Snowflake Open Catalog.

Ihre(n) <account_locator>, <cloud_region_id> und <cloud> finden Sie unter Format 2: Konto-Locator in einer Region.

https://<open_catalog_privatelink_account_url>/polaris/api/catalog: Wenn CATALOG_API_TYPE = PRIVATE.

Bemerkung

Für <open_catalog_privatelink_account_url> geben Sie einen der folgenden Werte ein:

PrivateLink-Konto-URL

URL für regionenloses PrivateLink-Konto

Um diese Werte zu erhalten, rufen Sie die Einstellungen Ihres Open Catalog-Kontos für private Konnektivität ab. Einzelheiten finden Sie in den Anweisungen für die Cloud-Plattform, auf der Ihr Open Catalog-Konto gehostet wird:

AWS

Azure

CATALOG_API_TYPE = { PRIVATE | PUBLIC }
Gibt den Katalog-API-Typ an. Wenn Ihre Verbindung zwischen Snowflake und Open Catalog über das öffentliche Internet geleitet werden soll, ist dieser Parameter optional.

PRIVATE: Wenn Sie die private Konnektivität für den eingehenden Netzwerk-Datenverkehr in Snowflake Open Catalog verwenden, wird Snowflake über eine private IP-Adresse mit Open Catalog verbunden.

PUBLIC: Stellt eine Verbindung zwischen Snowflake und Open Catalog über das öffentliche Internet her.

Standard: PUBLIC

CATALOG_NAME = 'open_catalog_name'
Gibt den Namen des Katalogs an, der in Open Catalog verwendet werden soll.

REST_AUTHENTICATION = ( ... )

Gibt die Authentifizierung an, die Snowflake für die Verbindung mit Open Catalog verwendet.

TYPE = OAUTH: Gibt OAuth als Typ der zu verwendenden Authentifizierung an.
OAUTH_CLIENT_ID = 'oauth_client_id': Die Client-ID der Anmeldeinformationen von OAuth2, die mit Ihrer Open Catalog-Dienstverbindung verbunden sind.
OAUTH_CLIENT_SECRET = 'oauth_secret': Das Geheimnis der OAuth2-Anmeldeinformationen, die mit Ihrer Open Catalog-Dienstverbindung verbunden sind.
OAUTH_ALLOWED_SCOPES = ( 'scope_1', 'scope_2'): Der Bereich des OAuth-Tokens. In der Iceberg REST API-Spezifikation ist nur ein Bereich enthalten, aber Kataloge können mehr als einen Bereich in ihrer Implementierung unterstützen.

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. Vorhandene Iceberg-Tabellen, die auf diese Integration verweisen, funktionieren normal.

FALSE verhindert, dass Benutzer neue Iceberg-Tabelle erstellen, die auf diese Integration verweisen. Bestehende Iceberg-Tabellen, die auf diese Integration verweisen, können nicht auf den Katalog in der Tabellendefinition zugreifen.

Optionale Parameter¶

CATALOG_NAMESPACE = 'open_catalog_namespace'

Wenn Sie die Katalogintegration erstellen, um eine Tabelle in Snowflake Open Catalog mit Snowflake abzufragen, können Sie optional den Namespace von Open Catalog angeben. Snowflake verwendet diesen Namespace für alle Iceberg-Tabellen, die Sie mit dieser Katalogintegration verknüpfen.

Falls angegeben, können Sie diesen Wert auf Tabellenebene überschreiben, wenn Sie eine Tabelle erstellen. Falls nicht angegeben, müssen Sie einen Namespace auf Tabellenebene festlegen, wenn Sie eine Tabelle erstellen.
Wenn Sie die Katalogintegration erstellen, um eine von Snowflake verwaltete Tabelle mit Snowflake Open Catalog zu synchronisieren, hat dieser Parameter keinen Einfluss darauf, wie Sie die Tabelle mit Open Catalog synchronisieren. Snowflake synchronisiert die Tabelle mit dem externen Katalog in Open Catalog, den Sie in der Katalogintegration mithilfe einer vordefinierten Regel angeben.

Wenn Sie beispielsweise eine db1.public.table1-Iceberg-Tabelle in Snowflake registriert haben und catalog1 in der Katalogintegration angeben, synchronisiert Snowflake die Tabelle mit Open Catalog und verwendet den folgenden vollqualifizierten Namen: catalog1.db1.public.table1.

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.

Gibt für Delta-basierte Tabellen die Anzahl der Sekunden an, die Snowflake zwischen den Versuchen wartet, Ihren externen Cloud-Speicher nach neuen Metadaten abzufragen.

Werte: 30 bis einschließlich 86.400

Standard: 30 Sekunden.

COMMENT = 'string_literal'

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

Standard: Kein Wert

Anforderungen an die Zugriffssteuerung¶

Eine Rolle, die zur Ausführung dieser Operation verwendet wird, muss mindestens die folgenden Berechtigungen haben:

Berechtigung	Objekt	Anmerkungen
CREATE INTEGRATION	Konto	Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

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¶

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 „User“), sensible Daten, exportkontrollierte Daten oder andere regulierte Daten als Metadaten eingegeben werden. Weitere Informationen dazu finden Sie unter Metadatenfelder in Snowflake.

Die OR REPLACE- und IF NOT EXISTS-Klauseln schließen sich gegenseitig aus. Sie können nicht beide in derselben Anweisung verwendet werden.
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.

Informationen zur Behebung von Problemen bei der Erstellung einer Katalogintegration finden Sie unter Sie können keine Katalogintegration für Open Catalog erstellen.

Beispiele¶

Im folgenden Beispiel wird eine Katalogintegration für Open Catalog für einen bestimmten Namespace in einem internen Katalog in Open Catalog erstellt, um Tabellen abzufragen, die unter diesem Namespace in Snowflake gruppiert sind. Weitere Informationen zu internen Katalogen in Open Catalog finden Sie unter Katalogtypen in der Dokumentation Open Catalog.

CREATE OR REPLACE CATALOG INTEGRATION open_catalog_int
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_catalog_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://my_org_name-my_snowflake_open_catalog_account_name.snowflakecomputing.com/polaris/api/catalog'
    CATALOG_NAME = 'my_catalog_name'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = 'my_client_id'
    OAUTH_CLIENT_SECRET = 'my_client_secret'
    OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL')
  )
  ENABLED = TRUE;

Copy

Das folgende Beispiel erstellt eine Katalogintegration für Open Catalog, um von Snowflake verwaltete Tabellen mit dem Katalog customers in Open Catalog zu synchronisieren, der ein externer Katalog ist. Weitere Informationen zu externen Katalogen in Open Catalog finden Sie unter Katalogtypen in der Open Catalog-Dokumentation.

CREATE OR REPLACE CATALOG INTEGRATION open_catalog_int2
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_URI = 'https://my_org_name-my_snowflake_open_catalog_account_name.snowflakecomputing.com/polaris/api/catalog'
    CATALOG_NAME = 'customers'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = 'my_client_id'
    OAUTH_CLIENT_SECRET = 'my_client_secret'
    OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL')
  )
  ENABLED = TRUE;

Copy