Ausführen von Verbundabfragen für Google BigQuery

Auf dieser Seite wird beschrieben, wie Sie lakehouse Federation einrichten, um Verbundabfragen für BigQuery-Daten auszuführen, die nicht von Azure Databricks verwaltet werden. Weitere Informationen zur Lakehouse Federation finden Sie unter Was ist Lakehouse Federation?

Um eine Verbindung mit Ihrer BigQuery-Datenbank mithilfe der Lakehouse Federation herzustellen, müssen Sie Folgendes in Ihrem Azure Databricks Unity Catalog-Metastore erstellen. Arbeitsbereiche, die nach dem 9. November 2023 erstellt wurden, verfügen bereits automatisch über einen Unity Catalog-Metastore.

• Eine Verbindung mit Ihrer BigQuery-Datenbank.
• Einen Fremdkatalog, der Ihre BigQuery-Datenbank in Unity Catalog spiegelt, sodass Sie die Abfragesyntax und Datengovernancetools von Unity Catalog zum Verwalten des Azure Databricks-Benutzerzugriffs auf die Datenbank verwenden können.

Vorbereitung

Anforderungen an den Arbeitsbereich:

• Der Arbeitsbereich muss für Unity Catalog aktiviert sein.

Computeanforderungen:

• Netzwerkkonnektivität zwischen Ihrem Databricks Runtime-Cluster oder SQL-Warehouse und den Zieldatenbanksystemen. Weitere Informationen finden Sie unter Netzwerkempfehlungen für Lakehouse Federation.
• Azure Databricks-Cluster müssen Databricks Runtime 16.1 oder höher sowie den Standard- oder dedizierten Zugriffsmodus (ehemals gemeinsam genutzt und einzelner Benutzer) verwenden.
• SQL-Warehouses müssen „Pro“ oder serverlos sein.

Erforderliche Berechtigungen:

• Um eine Verbindung zu erstellen, müssen Sie über die CREATE CONNECTION Berechtigung für den Unity-Katalog-Metastore verfügen, der an den Arbeitsbereich angefügt ist.
• Um einen Fremdkatalog zu erstellen, müssen Sie über die Berechtigung „CREATE CATALOG“ für den Metastore verfügen und entweder der Besitzer der Verbindung sein oder über die Berechtigung „CREATE FOREIGN CATALOG“ für die Verbindung verfügen.

In jedem folgenden aufgabenbasierten Abschnitt werden zusätzliche Berechtigungsanforderungen angegeben.

Erstellen einer Verbindung

Eine Verbindung gibt einen Pfad und Anmeldeinformationen für den Zugriff auf ein externes Datenbanksystem an. Zum Erstellen einer Verbindung können Sie den Katalog-Explorer oder den SQL-Befehl „CREATE CONNECTION“ in einem Azure Databricks-Notebook oder im Databricks SQL-Abfrage-Editor verwenden.

Erforderliche Berechtigungen: Metastore-Admin oder Benutzer mit der Berechtigung CREATE CONNECTION.

Catalog-Explorer

1. Klicken Sie im Azure Databricks-Arbeitsbereich auf das Katalog.

2. Klicken Sie oben im Katalogbereich auf das hinzufügen ", und wählen Sie im Menü " Verbindung erstellen " aus.

3. Geben Sie auf der Seite Verbindungsgrundlagen des Assistenten zum Einrichten der Verbindung einen benutzerfreundlichen Verbindungsnamen ein.

4. Wählen Sie einen Verbindungstyp von Google BigQuery aus, und klicken Sie dann auf Weiter.

5. Geben Sie auf der Seite Authentication den Google Service Account Key json für Ihre BigQuery-Instanz ein.

   Dies ist ein unformatiertes JSON-Objekt, das verwendet wird, um das BigQuery-Projekt anzugeben und die Authentifizierung bereitzustellen. Sie können dieses JSON-Objekt generieren und von der Seite mit den Details des Dienstkontos in Google Cloud unter "KEYS" herunterladen. Das Dienstkonto muss über die erforderlichen Berechtigungen in BigQuery verfügen, einschließlich BigQuery User und BigQuery Data Viewer. Im Folgenden finden Sie ein Beispiel.

   {
     "type": "service_account",
     "project_id": "PROJECT_ID",
     "private_key_id": "KEY_ID",
     "private_key": "PRIVATE_KEY",
     "client_email": "SERVICE_ACCOUNT_EMAIL",
     "client_id": "CLIENT_ID",
     "auth_uri": "https://accounts.google.com/o/oauth2/auth",
     "token_uri": "https://accounts.google.com/o/oauth2/token",
     "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
     "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/SERVICE_ACCOUNT_EMAIL",
     "universe_domain": "googleapis.com"
   }
   

6. (Optional) Geben Sie die Projekt-ID für Ihre BigQuery-Instanz ein:

   Dies ist ein Name für das BigQuery-Projekt, das für die Abrechnung für alle Abfragen verwendet wird, die unter dieser Verbindung ausgeführt werden. Standardmäßig die Projekt-ID Ihres Dienstkontos. Das Dienstkonto muss über die erforderlichen Berechtigungen für dieses Projekt in BigQuery verfügen, einschließlich BigQuery User. In diesem Projekt können zusätzliche Datasets erstellt werden, die zum Speichern temporärer Tabellen von BigQuery verwendet werden.

7. (Optional) Fügen Sie einen Kommentar hinzu.

8. Klicken Sie auf Create connection (Verbindung erstellen).

9. Geben Sie auf der Seite Kataloggrundlagen einen Namen für den Fremdkatalog ein. Ein Fremdkatalog spiegelt eine Datenbank in einem externen Datensystem, sodass Sie Abfragen und die Verwaltung des Zugriffs auf Daten in dieser Datenbank mithilfe von Azure Databricks und Unity Catalog steuern können.

10. (Optional) Klicken Sie auf Verbindung testen, um zu überprüfen, ob sie funktioniert.

11. Klicken Sie auf Katalog erstellen.

12. Wählen Sie auf der Seite Zugriff die Arbeitsbereiche aus, in denen Benutzende auf den von Ihnen erstellten Katalog zugreifen können. Sie können Alle Arbeitsbereiche haben Zugriff oder Arbeitsbereichen zuweisen, anschließend die Arbeitsbereiche und dann Zuweisen auswählen.

13. Ändern Sie den Eigentümer, der in der Lage sein wird, den Zugriff auf alle Objekte im Katalog zu verwalten. Beginnen Sie mit der Eingabe eines Prinzipals im Textfeld, und wählen Sie den Prinzipal dann in den zurückgegebenen Ergebnissen aus.

14. Gewähren Sie Berechtigungen für den Katalog. Klicken Sie auf Gewähren:

    1. Geben Sie die Prinzipale an, die Zugriff auf die Objekte im Katalog haben werden. Beginnen Sie mit der Eingabe eines Prinzipals im Textfeld, und wählen Sie den Prinzipal dann in den zurückgegebenen Ergebnissen aus.
    2. Wählen Sie die Berechtigungsvoreinstellungen aus, die den einzelnen Prinzipalen gewährt werden sollen. Standardmäßig wird allen Kontobenutzenden die Berechtigung BROWSE gewährt.
       • Wählen Sie Data Reader aus dem Dropdown-Menü aus, um read Berechtigungen für Objekte im Katalog zu gewähren.
       • Wählen Sie im Dropdownmenü Daten-Editor aus, um read- und modify-Berechtigungen für Objekte im Katalog zu gewähren.
       • Wählen Sie manuell die Berechtigungen aus, die Sie vergeben möchten.
    3. Klicken Sie auf Gewähren.

15. Klicken Sie auf Next.

16. Geben Sie auf der Seite Metadaten Schlüssel-Wert-Paare für Tags an. Weitere Informationen finden Sie unter Anwenden von Tags auf sicherbare Unity-Katalog-Objekte.

17. (Optional) Fügen Sie einen Kommentar hinzu.

18. Klicken Sie auf Speichern.

SQL

Führen Sie in einem Notebook oder im Databricks SQL-Abfrage-Editor den folgenden Befehl aus. Ersetzen Sie <GoogleServiceAccountKeyJson> durch ein unformatiertes JSON-Objekt, das das BigQuery-Projekt angibt und Authentifizierung bereitstellt. Sie können dieses JSON-Objekt generieren und von der Seite mit den Details des Dienstkontos in Google Cloud unter "KEYS" herunterladen. Das Dienstkonto muss über die erforderlichen Berechtigungen in BigQuery verfügen, einschließlich BigQuery-Benutzer und BigQuery Data Viewer. Ein Beispiel für ein JSON-Objekt finden Sie auf der Registerkarte Katalog-Explorer auf dieser Seite.

CREATE CONNECTION <connection-name> TYPE bigquery
OPTIONS (
  GoogleServiceAccountKeyJson '<GoogleServiceAccountKeyJson>'
);

Es wird empfohlen, Azure Databricks-Geheimnisse anstelle von Klartext-Zeichenfolgen für vertrauliche Werte wie Anmeldeinformationen zu verwenden. Zum Beispiel:

CREATE CONNECTION <connection-name> TYPE bigquery
OPTIONS (
  GoogleServiceAccountKeyJson secret ('<secret-scope>','<secret-key-user>')
)

Informationen zum Einrichten von Geheimnissen finden Sie unter Verwaltung von Geheimnissen.

Erstellen eines Fremdkatalogs

Ein Fremdkatalog spiegelt eine Datenbank in einem externen Datensystem, sodass Sie Abfragen und die Verwaltung des Zugriffs auf Daten in dieser Datenbank mithilfe von Azure Databricks und Unity Catalog steuern können. Um einen Fremdkatalog zu erstellen, verwenden Sie eine Verbindung mit der bereits definierten Datenquelle.

Zum Erstellen eines fremden Katalogs können Sie den Katalog-Explorer oder CREATE FOREIGN CATALOG in einem Azure Databricks-Notebook oder im Databricks SQL-Abfrage-Editor verwenden. Sie können auch die Databricks REST-API oder die Databricks CLI verwenden, um einen Katalog zu erstellen. Siehe POST /api/2.1/unity-catalog/catalogs oder Unity Catalog-Befehle.

Erforderliche Berechtigungen:CREATE CATALOG Berechtigung auf dem Metastore und entweder die Eigentümerschaft an der Verbindung oder die CREATE FOREIGN CATALOG Berechtigung auf der Verbindung.

Catalog-Explorer

1. Klicken Sie im Azure Databricks-Arbeitsbereich auf das Katalog zum Öffnen des Katalog-Explorers.

2. Klicken Sie oben im Bereich Katalog auf das Symbol Hinzufügen und wählen Sie im Menü Katalog hinzufügen.

   Klicken Sie alternativ auf der Seite Schnellzugriff auf die Schaltfläche Kataloge, und klicken Sie dann auf die Schaltfläche Katalog erstellen.

3. (Optional) Geben Sie die folgende Katalogeigenschaft ein:

   Datenprojekt-ID: Ein Name für das BigQuery-Projekt, das Daten enthält, die diesem Katalog zugeordnet werden. Standardmäßig wird die Abrechnungsprojekt-ID auf Verbindungsebene festgelegt.

4. Befolgen Sie die Anweisungen zum Erstellen von Fremdkataloge unter Erstellen von Katalogen.

5. (Optional) Geben Sie die folgenden Katalogoptionen an:

   • Materialization Dataset: Ein optionaler BigQuery-Datensatzname, der für die Materialisierung von Abfrageergebnissen verwendet werden soll. Wenn nicht angegeben, wird ein Materialisierungsdatensatz bei Bedarf automatisch bereitgestellt. Weitere Informationen finden Sie unter Materialisierung .
   • BIGNUMERIC Default Scale: Ein optionaler Skalierungswert zum Zuordnen von BigQuery BIGNUMERIC zu Spark DecimalType. Weitere Informationen finden Sie unter Datentypzuordnungen .

SQL

Führen Sie den folgenden SQL-Befehl in einem Notebook oder im Databricks-SQL-Editor aus. Elemente in Klammern sind optional. Ersetzen Sie die folgenden Platzhalterwerte.

• <catalog-name>: Name für den Katalog in Azure Databricks.
• <connection-name>: Das Verbindungsobjekt, das die Datenquelle, den Pfad und die Anmeldeinformationen angibt.
• <data-project-id>: Eine optionale Projekt-ID des BigQuery-Projekts, das Daten enthält, die diesem Katalog zugeordnet werden sollen. Wenn nicht angegeben, wird die für die Verbindung festgelegte Projekt-ID verwendet, gefolgt von der Projekt-ID des Dienstkontos.
• <dataset-name>: Ein optionaler BigQuery-Datensatzname, der für die Materialisierung von Abfrageergebnissen verwendet werden soll. Wenn nicht angegeben, wird ein Materialisierungsdatensatz bei Bedarf automatisch bereitgestellt. Weitere Informationen finden Sie unter Materialisierung .
• <scale>: Ein optionaler Skalierungswert [0, 38] zum Zuordnen von BigQuery BIGNUMERIC zu Spark DecimalType(38, scale). Der Standardwert ist 38. Weitere Informationen finden Sie unter Datentypzuordnungen .

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
[OPTIONS (dataProjectId '<data-project-id>', materializationDataset '<dataset-name>', bigNumericDefaultScale '<scale>')];

Materialisation

Im Gegensatz zu anderen Verbundconnectors verwendet der BigQuery-Connector die BigQuery Storage-APIs anstelle von JDBC für eine verbesserte Leistung. Azure Databricks können aus BigQuery direkt aus dem Speicher lesen oder ein materialisiertes Dataset verwenden. Direktes Lesen bietet eine bessere Leistung für große Scans und unterstützt Filter- und Projektions-Pushdowns. Die Materialisierung verschiebt zusätzliche Vorgänge wie Limitierung, Aggregation, Joins und Sortierung an die BigQuery-Compute-Ressourcen, bevor die Ergebnisse nach Azure Databricks gestreamt werden.

Ansichten und externe Tabellen sind immer materialisiert. Alle anderen Lesevorgänge verwenden standardmäßig den direkten Speicher ohne Materialisierung.

Erwägen Sie die Aktivierung der Materialisierung, wenn Sie erweiterte Pushdowns benötigen, kleine Resultsets aus großen Datasets lesen oder regionsübergreifende Daten lesen. Die Materialisierung verursacht zusätzliche Gebühren für BigQuery-Berechnungen. Um die Materialisierung zu aktivieren, legen Sie die folgende Spark-Konfiguration fest:

SET spark.databricks.bigquery.enableMaterialization = true;

Standardmäßig wird ein Materialisierungsdatensatz bei Bedarf automatisch bereitgestellt. Sie können einen benutzerdefinierten Datensatz mithilfe der materializationDataset Katalogoption angeben, wenn Sie den fremden Katalog erstellen oder ändern. Dies ist nützlich, wenn das Dienstkonto nicht über berechtigungen zum Erstellen von Datensätzen verfügt oder wenn Sie steuern möchten, wo temporäre Materialisierungstabellen gespeichert werden. Zum Beispiel:

CREATE FOREIGN CATALOG my_catalog USING CONNECTION my_bq_connection
OPTIONS (materializationDataset 'my_materialization_dataset');

Führen Sie Folgendes aus, um einen vorhandenen Katalog zu aktualisieren:

ALTER CATALOG my_catalog OPTIONS (materializationDataset 'my_materialization_dataset');

Unterstützte Pushdowns

Die folgenden Pushdowns werden ohne Materialisierung unterstützt:

• Filter
• Projektionen

Die folgenden zusätzlichen Pushdowns werden mit aktivierter Materialisierung unterstützt:

• Begrenzung
• Funktionen (teilweise Unterstützung, Filterausdrücke nur: Zeichenfolgenfunktionen, mathematische Funktionen, Datum, Uhrzeit und Zeitstempelfunktionen und andere verschiedene Funktionen wie Alias, Cast, SortOrder)
• Aggregate
• Sortierung bei Verwendung mit einem Grenzwert
• Joins (Databricks Runtime 16.1 oder höher)

Die folgenden Pushdowns werden nicht unterstützt:

• Fensterfunktionen

Datentypzuordnungen

Die folgende Tabelle enthält die Zuordnung von BigQuery- zu Spark-Datentypen.

* BigQuery BIGNUMERIC hat eine Genauigkeit von bis zu 76 Ziffern, die die maximale DecimalType Genauigkeit von Spark von 38 überschreitet. Standardmäßig wird BIGNUMERICDecimalType(38, 38) zugeordnet. Verwenden Sie die bigNumericDefaultScale Katalogoption, um die Skalierung zu konfigurieren. Zulässige Werte sind [0, 38]. Beispiel: bigNumericDefaultScale = '10' ordnet BIGNUMERICDecimalType(38, 10) zu. BigQuery NUMERIC ordnet seine deklarierte Genauigkeit und Skalierung zu.

Wenn Sie aus BigQuery lesen, wird BigQuery Timestamp Spark TimestampType zugeordnet wenn preferTimestampNTZ = false (Standard). BigQuery Timestamp wird TimestampNTZType zugeordnet, wenn preferTimestampNTZ = true.

Problembehandlung

Error creating destination table using the following query [<query>]

Häufige Ursache: Das von der Verbindung verwendete Dienstkonto verfügt nicht über die BigQuery-Benutzerrolle .

Lösung:

1. Gewähren Sie dem Dienstkonto, das von der Verbindung verwendet wird, die BigQuery-Benutzerrolle. Diese Rolle ist erforderlich, um das Materialisierungsdatenset zu erstellen, das abfrageergebnisse vorübergehend speichert.
2. Führen Sie die Abfrage erneut aus.