Federatieve query's uitvoeren op Google BigQuery

Op deze pagina wordt beschreven hoe u Lakehouse Federation instelt voor het uitvoeren van federatieve query's op BigQuery-gegevens die niet worden beheerd door Azure Databricks. Zie Verbinding maken met externe databases en catalogi voor meer informatie over Lakehouse Federation

Als u verbinding wilt maken met uw BigQuery-database met behulp van Lakehouse Federation, moet u het volgende maken in uw Azure Databricks Unity Catalog-metastore (werkruimten die zijn gemaakt na 9 november 2023, zijn al automatisch een Unity Catalog-metastore ingericht):

Een verbinding met uw BigQuery-database.
Een refererende catalogus die uw BigQuery-database weerspiegelt in Unity Catalog, zodat u de Unity Catalog-querysyntaxis en gegevensbeheerhulpprogramma's kunt gebruiken om Azure Databricks-gebruikerstoegang tot de database te beheren.

Voordat u begint

Als u federatieve query's wilt uitvoeren op BigQuery, maakt u een verbinding met BigQuery en een refererende catalogus die overeenkomt met uw BigQuery-database. Vervolgens kunt u BigQuery-gegevens opvragen en beheren met behulp van Azure Databricks en Unity Catalog. Aanvullende machtigingsvereisten worden opgegeven in elke sectie op basis van taken die volgt.

Vereisten voor werkruimte:

Werkruimte geactiveerd voor Unity Catalog.

Rekenvereisten:

Netwerkconnectiviteit van uw Databricks Runtime-cluster of SQL Warehouse naar de doeldatabasesystemen. Zie De aanbevelingen voor netwerken voor Lakehouse Federation.
Azure Databricks-clusters moeten Gebruikmaken van Databricks Runtime 16.1 of hoger en de standaard- of toegewezen toegangsmodus (voorheen gedeeld en één gebruiker).
SQL-warehouses moeten Pro of Serverless zijn.

Machtigingsvereisten:

Als u een verbinding wilt maken, moet u beschikken over de CREATE CONNECTION bevoegdheid voor de Unity Catalog-metastore die is gekoppeld aan de werkruimte.
Als u een buitenlandse catalogus wilt maken, moet u de machtiging CREATE CATALOG hebben voor de metastore en ofwel de eigenaar van de verbinding zijn of het privilege CREATE FOREIGN CATALOG voor de verbinding hebben.

Een verbinding maken

Een verbinding geeft een pad en referenties op voor toegang tot een extern databasesysteem. Als u een verbinding wilt maken, kunt u Catalog Explorer of de CREATE CONNECTION SQL-opdracht gebruiken in een Azure Databricks-notebook of de Databricks SQL-queryeditor.

Notitie

U kunt ook de Databricks REST API of de Databricks CLI gebruiken om een verbinding te maken. Zie POST /api/2.1/unity-catalog/connections en Unity Catalog-opdrachten.

Vereiste machtigingen: Metastore-beheerder of gebruiker met de CREATE CONNECTION bevoegdheid.

Catalogusverkenner

Klik in uw Azure Databricks-werkruimte op Catalogus.
Klik boven aan het deelvenster Catalogus op het en selecteer Een verbinding maken in het menu.
Op de pagina Verbindingsbeginselen van de wizard Verbinding instellen, voer een gebruiksvriendelijke verbindingsnaamin.
Selecteer een verbindingstype van Google BigQuery-en klik vervolgens op Volgende.
Voer op de pagina Authentication de Google-serviceaccountssleutel-json - in voor uw BigQuery-exemplaar.

Dit is een onbewerkt JSON-object dat wordt gebruikt om het BigQuery-project op te geven en verificatie te bieden. U kunt dit JSON-object genereren en downloaden op de pagina met serviceaccountgegevens in Google Cloud onder SLEUTELS. Het serviceaccount moet over de juiste machtigingen beschikken in BigQuery, waaronder BigQuery User en BigQuery Data Viewer. Hier volgt een voorbeeld.
```
{
  "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://oauth2.googleapis.com/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"
}
```
Notitie

Google stelt de URL-waarden in de JSON van het serviceaccount in en ze kunnen per account verschillen. Gebruik ze precies zoals ze worden weergegeven in uw gedownloade JSON-bestand. Als u proxyregels voor het netwerk configureert zodat Azure Databricks toegang krijgt tot Google-API's, sta dan zowel https://accounts.google.com als https://oauth2.googleapis.com toe.
(Optional) Voer de project-ID in voor uw BigQuery-exemplaar:

Dit is een naam voor het BigQuery-project dat wordt gebruikt voor facturering voor alle query's die worden uitgevoerd onder deze verbinding. De standaardinstelling is de project-id van uw serviceaccount. Het serviceaccount moet over de juiste machtigingen beschikken voor dit project in BigQuery, inclusief BigQuery User. In dit project kunnen extra gegevenssets worden gemaakt die worden gebruikt voor het opslaan van tijdelijke tabellen door BigQuery.
(Optioneel) Voeg een opmerking toe.
Klik op Verbinding maken.
Voer op de pagina Catalogus Basis een naam in voor de buitenlandse catalogus. Een refererende catalogus spiegelt een database in een extern gegevenssysteem, zodat u de toegang tot gegevens in die database kunt opvragen en beheren met behulp van Azure Databricks en Unity Catalog.
(Optioneel) Klik op Verbinding testen om te bevestigen dat deze werkt.
Klik op Maak de catalogus.
Selecteer op de pagina Access de werkruimten waarin gebruikers toegang hebben tot de catalogus die u hebt gemaakt. U kunt Alle werkruimten hebben toegangselecteren of klikken op Toewijzen aan werkruimten, de werkruimten selecteren en vervolgens op Toewijzenklikken.
Wijzig de eigenaar die in staat zal zijn de toegang tot alle objecten in de catalogus te beheren. Begin een hoofdgebruikersnaam in het tekstvak te typen en klik vervolgens op de hoofdgebruikersnaam in de weergegeven resultaten.
Verleent privileges aan de catalogus. Klik op Toestaan:
1. Geef de Principals op die toegang hebben tot objecten in de catalogus. Begin een hoofdgebruikersnaam in het tekstvak te typen en klik vervolgens op de hoofdgebruikersnaam in de weergegeven resultaten.
2. Selecteer de vooraf ingestelde bevoegdheden om aan elke principal toe te kennen. Alle accountgebruikers krijgen standaard BROWSE toegekend.
  - Selecteer Gegevenslezer in de vervolgkeuzelijst om read bevoegdheden te verlenen voor objecten in de catalogus.
  - Selecteer Gegevenseditor in de vervolgkeuzelijst om read en modify bevoegdheden voor objecten in de catalogus toe te kennen.
  - Selecteer handmatig de bevoegdheden die u wilt verlenen.
3. Klik op Toestaan.
Klik op Volgende.
Specificeer op de pagina Metagegevens de sleutel-waardeparen van de tags. Zie Tags toepassen op beveiligbare objecten van Unity Catalogvoor meer informatie.
(Optioneel) Voeg een opmerking toe.
Klik op Opslaan.

SQL

Voer de volgende opdracht uit in een notebook of de Sql-query-editor van Databricks. Vervang <GoogleServiceAccountKeyJson> door een onbewerkt JSON-object dat het BigQuery-project aangeeft en verificatie biedt. U kunt dit JSON-object genereren en downloaden op de pagina met serviceaccountgegevens in Google Cloud onder SLEUTELS. Het serviceaccount moet over de juiste machtigingen beschikken die zijn verleend in BigQuery, waaronder BigQuery User en BigQuery Data Viewer. Bekijk voor een voorbeeld van een JSON-object het tabblad Catalog Explorer op deze pagina.

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

Databricks raadt u aan geheimen te gebruiken in plaats van tekenreeksen zonder opmaak voor gevoelige waarden, zoals referenties. Voorbeeld:

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

Zie Geheimbeheer voor informatie over het instellen van geheimen.

Een buitenlandse catalogus maken

Notitie

Als u de UI gebruikt om een verbinding met de gegevensbron te maken, is de creatie van een buitenlandse catalogus inbegrepen en kunt u deze stap overslaan.

Een refererende catalogus spiegelt een database in een extern gegevenssysteem, zodat u de toegang tot gegevens in die database kunt opvragen en beheren met behulp van Azure Databricks en Unity Catalog. Als u een buitenlandse catalogus wilt maken, gebruikt u een verbinding met de gegevensbron die al is gedefinieerd.

Als u een externe catalogus wilt maken, kunt u Catalog Explorer of CREATE FOREIGN CATALOG gebruiken in een Azure Databricks-notebook of in de Databricks SQL-queryeditor. U kunt ook de Databricks REST API of de Databricks CLI gebruiken om een catalogus te maken. Zie POST /api/2.1/unity-catalog/catalogs of Unity Catalog-opdrachten.

Vereiste machtigingen:CREATE CATALOG machtiging voor de metastore en eigendom van de verbinding of de CREATE FOREIGN CATALOG bevoegdheid voor de verbinding.

Catalogusverkenner

Klik in uw Azure Databricks-werkruimte op Catalogus om Catalog Explorer te openen.
Klik bovenaan het deelvenster Catalogus op het pictogram toevoegen en selecteer Een catalogus toevoegen in het menu.

U kunt ook op de pagina Snelle toegang op de knop Catalogi klikken en vervolgens op de knop Catalogus maken klikken.
(Optioneel) Voer de volgende cataloguseigenschap in:

Gegevensproject-id: een naam voor het BigQuery-project met gegevens die aan deze catalogus worden toegewezen. Standaard wordt de factureringsproject-id op verbindingsniveau ingesteld.
Volg de instructies voor het maken van buitenlandse catalogi in Catalogi maken.
(Optioneel) Geef de volgende catalogusopties op:
- Materialization Dataset: Een optionele bigQuery-gegevenssetnaam die moet worden gebruikt voor het materialiseren van queryresultaten. Indien niet opgegeven, wordt een materialisatiegegevensset automatisch ingericht wanneer dat nodig is. Zie Materialisatie voor meer informatie.
- BIGNUMERIC Default Scale: Een optionele schaalwaarde voor het toewijzen van BigQuery BIGNUMERIC aan Spark DecimalType. Zie Toewijzingen van gegevenstypen voor meer informatie.

SQL

Voer de volgende SQL-opdracht uit in een notebook of de Databricks SQL-editor. Items tussen haakjes zijn optioneel. Vervang de waarden van de tijdelijke aanduidingen.

<catalog-name>: naam voor de catalogus in Azure Databricks.
<connection-name>: het verbindingsobject waarmee de gegevensbron, het pad en de toegangsreferenties worden opgegeven.
<data-project-id>: Een optionele project-id van het BigQuery-project met gegevens die aan deze catalogus moeten worden toegewezen. Als dit niet is opgegeven, wordt de project-id die voor de verbinding is ingesteld, gebruikt, gevolgd door de project-id van het serviceaccount.
<dataset-name>: Een optionele bigQuery-gegevenssetnaam die moet worden gebruikt voor het materialiseren van queryresultaten. Indien niet opgegeven, wordt een materialisatiegegevensset automatisch ingericht wanneer dat nodig is. Zie Materialisatie voor meer informatie.
<scale>: Een optionele schaalwaarde [0, 38] voor het toewijzen van BigQuery BIGNUMERIC aan Spark DecimalType(38, scale). De standaardinstelling is 38. Zie Toewijzingen van gegevenstypen voor meer informatie.

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

Materialisatie

In tegenstelling tot andere federatieconnectors gebruikt de BigQuery-connector de BigQuery Storage-API in plaats van JDBC voor verbeterde prestaties. Azure Databricks kan rechtstreeks vanuit BigQuery lezen vanuit de opslag of met behulp van een materiële gegevensset. Directe leesbewerkingen bieden betere prestaties voor grote scans en ondersteunt filter- en projectie-pushdowns. Materialisatie verplaatst extra bewerkingen (limiet, aggregaties, joins, sortering) naar BigQuery-rekenkracht voordat er streamingresultaten naar Azure Databricks worden verzonden.

Weergaven en externe tabellen zijn altijd gematerialiseerd. Alle andere leesbewerkingen maken standaard gebruik van directe opslag zonder materialisatie.

Overweeg om materialisatie in te schakelen als u geavanceerde pushdowns nodig hebt, kleine resultaatsets van grote gegevensverzamelingen uitleest, of als u regio overschrijdende gegevens uitleest. Voor materialisatie worden er extra rekenkosten voor BigQuery in rekening gebracht. Als u materialisatie wilt inschakelen, stelt u de volgende Spark-configuratie in:

SET spark.databricks.bigquery.enableMaterialization = true;

Notitie

U kunt spark.databricks.bigquery.enableMaterialization alleen instellen op een hiervoor in aanmerking komend cluster. Zie Voordat u begint voor de vereisten voor rekenkracht. Het inschakelen van materialisatie wordt niet ondersteund in SQL Warehouses (Pro of Serverless).

Standaard wordt een materialisatiegegevensset automatisch ingericht wanneer dat nodig is. U kunt een aangepaste gegevensset opgeven met behulp van de materializationDataset catalogusoptie bij het maken of wijzigen van de buitenlandse catalogus. Dit is handig als het serviceaccount geen machtigingen heeft om gegevenssets te maken of als u wilt bepalen waar tijdelijke materialisatietabellen worden opgeslagen. Voorbeeld:

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

Als u een bestaande catalogus wilt bijwerken, voert u het volgende uit:

ALTER CATALOG my_catalog OPTIONS (materializationDataset 'my_materialization_dataset');

Externe BigQuery-tabellen lezen

U kunt rechtstreeks vanuit uw werkstroom query's uitvoeren op externe BigQuery-tabellen, inclusief tabellen met biglake- en cloudopslag. Deze tabellen worden automatisch gerealiseerd voordat query's worden uitgevoerd, waardoor volledige toegang tot hun inhoud zonder extra configuratie mogelijk is.

Ondersteunde externe tabellen

Externe tabellen voor BigLake en cloudopslag worden ondersteund.

BigLake-tabellen verwijzen naar gegevens die zijn opgeslagen in cloudopslag en bevatten gedetailleerd toegangsbeheer dat wordt beheerd via BigQuery.
Externe tabellen voor cloudopslag verwijzen rechtstreeks naar bestanden met behulp van URI's.

Wanneer u query's uitvoert op deze tabellen, materialiseert het systeem de gegevens zodat uw query wordt uitgevoerd op ingebouwde BigQuery-opslag voor volledige ondersteuning van SQL-functies en optimale prestaties.

Zie de BigQuery-documentatie voor BigLake-tabellen en externe cloudopslagtabellen voor meer informatie.

Ondersteunde pushdowns

Pushdown-ondersteuning is afhankelijk van of materialisatie is ingeschakeld. Sommige bewerkingen worden automatisch doorgestuurd naar de BigQuery-rekenlaag, terwijl voor andere bewerkingen materialisatie is vereist.

De volgende pushdowns worden ondersteund zonder materialisatie:

Filters, doorgegeven als rijbeperkingen in de BigQuery Storage API (alleen eenvoudige predicaten — vergelijkingen tussen kolommen en letterlijke waarden, IN, IS NULL, LIKE en AND of OR-combinaties daarvan). Filters die verwijzen naar de operators of functies die hieronder worden vermeld, vereisen materialisatie.
Projecties

De volgende extra pushdown-bewerkingen worden ondersteund wanneer materialisatie is ingeschakeld. Met materialisatie worden filters gecompileerd naar SQL in plaats van rijbeperkingen voor BigQuery Storage-API, zodat ze ook de volgende operators en functies kunnen bevatten:

Grens
Offset, indien gebruikt met limiet
Aggregaties
Sorteren, bij gebruik met limiet
Joins (Databricks Runtime 16.1 of hoger)
Vergelijkings-, Booleaanse, bitsgewijze en rekenkundige operatoren (rekenkundige operatoren pushen alleen omlaag wanneer de ANSI-modus is ingeschakeld)
Wiskundige functies (ABS, FLOOR) - gedeeltelijke ondersteuning, alleen filterexpressies
Tekenreeksfuncties (CONCAT, UPPER, LOWER, LENGTH, TRIM, , LTRIM) RTRIM— gedeeltelijke ondersteuning, alleen filterexpressies
Contains, Startswith, Endswith
Datum-, tijd- en tijdstempelfuncties (DATE_TRUNCen EXTRACT voor jaar, kwartaal, maand, dag, uur en minuut) — gedeeltelijke ondersteuning, alleen filterexpressies
Diverse functies (COALESCE, Cast, CASE WHEN, en IFtoegang tot matrixelementen) - gedeeltelijke ondersteuning, alleen filterexpressies

De volgende pushdowns worden niet ondersteund:

Vensterfuncties

Toewijzingen van gegevenstypen

In de volgende tabel ziet u de toewijzing van BigQuery- naar Spark-gegevenstypen.

BigQuery-type	Sparktype
`BIGNUMERIC`, `NUMERIC`	`DecimalType`*
`INT64`	`LongType`
`FLOAT64`	`DoubleType`
`ARRAY`, `GEOGRAPHY`, `INTERVAL`, `JSON`, `STRING`, `STRUCT`	`VarcharType`
`BYTES`	`BinaryType`
`BOOL`	`BooleanType`
`DATE`	`DateType`
`DATETIME`	`TimestampNTZType`, behalve `StringType` in Databricks Runtime 16.4 tot en met 17.x**
`TIME`, `TIMESTAMP`	`TimestampType`/`TimestampNTZType`
Elk type met `REPEATED` modus	`ArrayType` van het bijbehorende Spark-type***

* BigQuery BIGNUMERIC heeft een precisie van maximaal 76 cijfers, die de maximale DecimalType precisie van Spark van 38 overschrijdt. Bij standaardinstelling wordt BIGNUMERIC toegewezen aan DecimalType(38, 38). Gebruik de bigNumericDefaultScale catalogusoptie om de schaal te configureren. Toegestane waarden zijn [0, 38]. Bijvoorbeeld: bigNumericDefaultScale = '10' wijst BIGNUMERIC toe aan DecimalType(38, 10). BigQuery NUMERIC komt overeen met de gedeclareerde precisie en schaal.

** De connector maakt sinds Databricks Runtime 16.4 gebruik van de BigQuery Storage API. Van Databricks Runtime 16.4 tot en met 17.x heeft de Storage-API BigQuery DATETIME toegewezen aan Spark StringType in plaats van TimestampNTZType. Databricks Runtime 18.0 herstelt de TimestampNTZType toewijzing.

*** In BigQuery wordt een kolom met de modus REPEATED omgezet in een Spark ArrayType dat het overeenkomstige Spark-type bevat. Een BigQuery-kolom REPEATED STRING wordt bijvoorbeeld toegewezen aan ArrayType(VarcharType)en een BigQuery-kolom REPEATED INT64 wordt toegewezen aan ArrayType(LongType).

Wanneer u van BigQuery leest, wordt BigQuery Timestamp toegewezen aan Spark TimestampType als preferTimestampNTZ = false (standaard). BigQuery Timestamp wordt toegewezen aan TimestampNTZType if preferTimestampNTZ = true.

Probleemoplossingsproces

In de volgende sectie worden een veelvoorkomende fout en de oplossing ervan beschreven bij het gebruik van de BigQuery-connector.

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

Veelvoorkomende oorzaak: het serviceaccount dat door de verbinding wordt gebruikt, heeft niet de rol BigQuery-gebruiker .

Resolutie:

Verdeel de rol BigQuery-gebruiker aan het serviceaccount dat door de verbinding wordt gebruikt. Deze rol is vereist om de materialisatiegegevensset te maken waarmee queryresultaten tijdelijk worden opgeslagen.
Voer de query opnieuw uit.

Feedback

Is deze pagina nuttig?

Last updated on 2026-07-08

Federatieve query's uitvoeren op Google BigQuery

Voordat u begint

Een verbinding maken

Catalogusverkenner

SQL

Een buitenlandse catalogus maken

Catalogusverkenner

SQL

Materialisatie

Externe BigQuery-tabellen lezen

Ondersteunde externe tabellen

Ondersteunde pushdowns

Toewijzingen van gegevenstypen

Probleemoplossingsproces

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

Feedback

Aanvullende resources

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