Spouštění federovaných dotazů v Google BigQuery

Tato stránka ukazuje, jak nastavit „Lakehouse Federation“ pro spouštění federovaných dotazů na data BigQuery, která nespravuje Azure Databricks. Další informace o federaci Lakehouse najdete v tématu Připojení k externím databázím a katalogům.

Pokud se chcete připojit k databázi BigQuery pomocí Lakehouse Federation, musíte vytvořit následující v metastoru katalogu Azure Databricks Unity (pracovní prostory založené po 9. listopadu 2023 už mají automaticky zřízený metastore katalogu Unity):

Připojení k databázi BigQuery.
cizí katalog, který zrcadlí vaši databázi BigQuery v katalogu Unity, abyste mohli pomocí syntaxe dotazů katalogu Unity a nástrojů pro správu dat spravovat uživatelský přístup k databázi Azure Databricks.

Než začnete

Pokud chcete spouštět federované dotazy na BigQuery, vytvořte připojení k BigQuery a cizímu katalogu, který zrcadlí vaši databázi BigQuery. Pak můžete dotazovat a spravovat data BigQuery pomocí Azure Databricks a katalogu Unity. Další požadavky na oprávnění jsou uvedeny v následující části založené na úlohách.

Požadavky na pracovní prostor:

Pracovní prostor aktivován pro katalog Unity.

Požadavky na výpočetní prostředky:

Síťové připojení z clusteru Databricks Runtime nebo SQL Warehouse k cílovým databázovým systémům. Viz doporučení ohledně sítí pro Lakehouse Federation.
Clustery Azure Databricks musí používat Databricks Runtime 16.1 nebo vyšší a standardní nebo vyhrazený režim přístupu (dříve sdílený a jeden uživatel).
Sql Warehouse musí být Verze Pro nebo Bezserverová.

Požadavky na oprávnění:

Pokud chcete vytvořit připojení, musíte mít CREATE CONNECTION oprávnění k metastoru katalogu Unity připojenému k pracovnímu prostoru.
Chcete-li vytvořit cizí katalog, musíte mít oprávnění CREATE CATALOG k metastoru a být buď vlastníkem připojení, nebo mít oprávnění CREATE FOREIGN CATALOG pro připojení.

Vytvoření připojení

Připojení určuje cestu a přihlašovací údaje pro přístup k externímu databázovému systému. K vytvoření připojení můžete použít Průzkumníka katalogu nebo příkaz CREATE CONNECTION SQL v poznámkovém bloku Azure Databricks nebo editoru dotazů SQL Databricks.

Poznámka:

K vytvoření připojení můžete použít také rozhraní REST API Databricks nebo rozhraní příkazového řádku Databricks. Viz POST /api/2.1/unity-catalog/connections a příkazy katalogu Unity.

Požadovaná oprávnění: Správce metastoru nebo uživatel s oprávněním CREATE CONNECTION .

Průzkumník katalogu

V pracovním prostoru Azure Databricks klikněte na Katalog.
V horní části podokna Katalog klikněte na ikonu Přidat a v nabídce vyberte Vytvořit připojení .
Na stránce základy připojení průvodce Nastavení připojení zadejte uživatelsky přívětivý název připojení.
Vyberte typ připojení Google BigQuery a klikněte na tlačítko Další.
Na stránce Ověřování zadejte JSON klíč účtu Google služby pro instance BigQuery.

Jedná se o nezpracovaný objekt JSON, který slouží k zadání projektu BigQuery a poskytnutí ověřování. Tento objekt JSON můžete vygenerovat a stáhnout ho ze stránky podrobností účtu služby v Google Cloudu v části KLÍČE. Účet služby musí mít v BigQuery správná oprávnění, včetně user BigQuery a BigQuery Data Viewer. Například:
```
{
  "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"
}
```
Poznámka:

Google nastaví hodnoty URL ve formátu JSON účtu služby a můžou se lišit podle účtu. Používejte je přesně tak, jak se zobrazují ve stažených souborech JSON. Pokud nakonfigurujete pravidla proxy serveru sítě pro Azure Databricks pro přístup k rozhraním GOOGLE API, povolte obojí https://accounts.google.com i https://oauth2.googleapis.com.
(Volitelné) Zadejte ID projektu vaší instance BigQuery:

Toto je název projektu BigQuery, který se používá pro fakturaci pro všechny dotazy spuštěné v rámci tohoto připojení. Výchozí hodnota je ID projektu vašeho účtu služby. Služební účet musí mít pro tento projekt v BigQuery udělena příslušná oprávnění, včetně role BigQuery User. V tomto projektu se můžou vytvořit další datová sada používaná k ukládání dočasných tabulek pomocí BigQuery.
(Volitelné) Přidejte komentář.
Klikněte na Vytvořit připojení.
Na stránce základy katalogu zadejte název cizího katalogu. Cizí katalog zrcadlí databázi v externím datovém systému, abyste mohli dotazovat a spravovat přístup k datům v této databázi pomocí Azure Databricks a Unity Catalog.
(Volitelné) Kliknutím na Otestovat připojení potvrďte, že funguje.
Klikněte na Vytvořit katalog.
Na stránce Access vyberte pracovní prostory, ve kterých mají uživatelé přístup k vytvořenému katalogu. Můžete vybrat Všechny pracovní prostory mají přístup, nebo klepněte na Přiřadit k pracovním prostorům, vyberte pracovní prostory a potom klikněte na Přiřadit.
Změňte vlastníka , kteří budou moct spravovat přístup ke všem objektům v katalogu. Začněte psát uživatele nebo skupinu do textového pole a poté klikněte na vybraného uživatele nebo skupinu ve vrácených výsledcích.
Udělte oprávnění v katalogu. Klikněte na Odsouhlasit:
1. Zadejte principály, kteří budou mít přístup k objektům v katalogu. Začněte psát uživatele nebo skupinu do textového pole a poté klikněte na vybraného uživatele nebo skupinu ve vrácených výsledcích.
2. Vyberte přednastavení oprávnění , které se mají každému objektu zabezpečení udělit. Všichni uživatelé účtu mají ve výchozím nastavení udělené BROWSE.
  - V rozevírací nabídce vyberte Čtečka dat a udělte read oprávnění k objektům v katalogu.
  - Z rozevírací nabídky vyberte Datový editor a udělte read a modify oprávnění k objektům v katalogu.
  - Ručně vyberte oprávnění, která chcete udělit.
3. Klikněte na Udělit.
Klikněte na Další.
Na stránce Metadata zadejte páry klíč-hodnota tagů. Další informace najdete v tématu Použití značek pro zabezpečitelné objekty v Katalogu Unity.
(Volitelné) Přidejte komentář.
Klikněte na Uložit.

SQL

V poznámkovém bloku nebo editoru dotazů SQL Databricks spusťte následující příkaz. Nahraďte <GoogleServiceAccountKeyJson> nezpracovaným objektem JSON, který určuje projekt BigQuery a poskytuje ověřování. Tento objekt JSON můžete vygenerovat a stáhnout ho ze stránky podrobností účtu služby v Google Cloudu v části KLÍČE. Účet služby musí mít v BigQuery udělená správná oprávnění, včetně uživatele BigQuery a Prohlížeče dat BigQuery. Pro zobrazení příkladu objektu JSON navštivte na této stránce kartu Průzkumník katalogu.

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

Databricks doporučuje používat tajné kódy místo řetězců prostého textu pro citlivé hodnoty, jako jsou přihlašovací údaje. Příklad:

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

Informace o nastavení tajných kódů najdete v tématu Správa tajných kódů.

Vytvoření zahraničního katalogu

Poznámka:

Pokud k vytvoření připojení ke zdroji dat použijete uživatelské rozhraní, zahrne se vytvoření cizího katalogu a tento krok můžete přeskočit.

Cizí katalog zrcadlí databázi v externím datovém systému, abyste mohli dotazovat a spravovat přístup k datům v této databázi pomocí Azure Databricks a Unity Catalog. Chcete-li vytvořit cizí katalog, použijte připojení ke zdroji dat, který již byl definován.

K vytvoření cizího katalogu můžete použít Průzkumníka katalogu nebo CREATE FOREIGN CATALOG v poznámkovém bloku Azure Databricks nebo v editoru dotazů SQL Databricks. K vytvoření katalogu můžete použít také rozhraní REST API Databricks nebo rozhraní příkazového řádku Databricks. Viz POST /api/2.1/unity-catalog/catalogs nebo příkazy Unity Catalog .

Požadovaná oprávnění:CREATE CATALOG oprávnění k metastoru a vlastnictví připojení nebo CREATE FOREIGN CATALOG oprávnění k připojení.

Průzkumník katalogu

V pracovním prostoru Azure Databricks klikněte na Klikněte na Katalog pro otevření Průzkumníka katalogu.
V horní části podokna katalogu klikněte na ikonuIkona Přidat a z nabídky vyberte Přidat katalog.

Případně na stránce Rychlý přístup klikněte na tlačítko Katalogy a potom klikněte na tlačítko Vytvořit katalog.
(Volitelné) Zadejte následující vlastnost katalogu:

ID projektu dat: Název projektu BigQuery obsahujícího data, která budou mapována na tento katalog. Výchozí hodnota je ID fakturačního projektu nastaveného na úrovni připojení.
Postupujte podle pokynů pro vytváření cizích katalogů v Vytvořit katalogy.
(Volitelné) Zadejte následující možnosti katalogu:
- Materialization Dataset: Volitelný název datové sady BigQuery, který se má použít pro materializaci výsledků dotazu. Pokud není zadán, soubor materializačních dat se v případě potřeby automaticky zřídí. Další informace najdete v tématu Materializace .
- BIGNUMERIC Default Scale: Volitelná hodnota škálování pro mapování BigQuery BIGNUMERIC na Spark DecimalType. Další informace najdete v tématu Mapování datových typů .

SQL

V poznámkovém bloku nebo editoru SQL Databricks spusťte následující příkaz SQL. Položky v závorkách jsou volitelné. Nahraďte zástupné hodnoty.

<catalog-name>: Název katalogu v Azure Databricks.
<connection-name>: Objekt připojení , který určuje zdroj dat, cestu a přihlašovací údaje pro přístup.
<data-project-id>: Volitelné ID projektu BigQuery obsahující data, která se mají namapovat na tento katalog. Pokud není zadáno, použije se ID projektu nastavené na připojení a id projektu účtu služby.
<dataset-name>: Volitelný název datové sady BigQuery, který se má použít pro materializaci výsledků dotazu. Pokud není zadán, soubor materializačních dat se v případě potřeby automaticky zřídí. Další informace najdete v tématu Materializace .
<scale>: Volitelná hodnota škálování [0, 38] pro mapování BigQuery BIGNUMERIC na Spark DecimalType(38, scale). Výchozí hodnota je 38. Další informace najdete v tématu Mapování datových typů .

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

Zhmotnění

Na rozdíl od jiných federačních konektorů konektor BigQuery využívá rozhraní BIGQuery Storage API místo JDBC k lepšímu výkonu. Azure Databricks může číst z BigQuery přímo z úložiště nebo pomocí materializované datové sady. Přímé čtení nabízí lepší výkon pro velké skeny a podporuje propagaci filtrů a projekcí. Materializace před streamováním výsledků do Azure Databricks odesílá další operace (limit, agregace, spojení, řazení) do výpočetních prostředků BigQuery.

Zobrazení a externí tabulky jsou vždy materializovány. Všechny ostatní operace čtení ve výchozím nastavení používají přímé úložiště bez materializace.

Pokud potřebujete pokročilé optimalizace, čtete malé sady výsledků z velkých datových sad nebo meziregionální data, zvažte povolení materializace. Za materializaci se účtují další poplatky za výpočetní prostředky BigQuery. Pokud chcete povolit materializaci, nastavte následující konfiguraci Sparku:

SET spark.databricks.bigquery.enableMaterialization = true;

Poznámka:

Můžete nastavit spark.databricks.bigquery.enableMaterialization jenom na oprávněném clusteru. Informace o požadavcích na výpočetní prostředky naleznete v části Než začnete. Povolení materializace není podporováno v datových skladech SQL (Pro nebo Serverless).

Ve výchozím nastavení je sada materializačních dat v případě potřeby automaticky zřízena. Vlastní datovou sadu můžete zadat pomocí materializationDataset možnosti katalogu při vytváření nebo změně cizího katalogu. To je užitečné, pokud účet služby nemá oprávnění k vytváření datových sad nebo pokud chcete řídit, kde jsou uloženy dočasné materializační tabulky. Příklad:

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

Pokud chcete aktualizovat existující katalog, spusťte:

ALTER CATALOG my_catalog OPTIONS (materializationDataset 'my_materialization_dataset');

Čtení externích tabulek BigQuery

Externí tabulky BigQuery, včetně tabulek BigLake a tabulek podporovaných cloudovým úložištěm, můžete dotazovat přímo v rámci pracovního postupu. Tyto tabulky jsou automaticky materializovány před spuštěním dotazu, což umožňuje úplný přístup k jejich obsahu bez další konfigurace.

Podporované externí tabulky

Podporují se externí tabulky BigLake a cloudového úložiště.

Tabulky BigLake odkazují na data uložená v cloudovém úložišti a zahrnují jemně odstupňované řízení přístupu spravované prostřednictvím BigQuery.
Externí tabulky cloudového úložiště přímo odkazují na soubory pomocí identifikátorů URI.

Při dotazování těchto tabulek systém materializuje data, aby se váš dotaz spustil v integrovaném úložišti BigQuery pro zajištění plné podpory funkcí SQL a optimálního výkonu.

Další informace najdete v dokumentaci BigQuery pro tabulky BigLake a externí tabulky Cloud Storage.

Podporované odsdílení změn

Podpora pushdownu závisí na tom, zda je povolena materializace. Některé operace se automaticky provádějí ve výpočetní vrstvě BigQuery, zatímco jiné vyžadují materializaci.

Následující pushdowny jsou podporovány bez nutnosti materializace:

Filtry, předané jako omezení řádků rozhraní BigQuery Storage API (pouze jednoduché predikáty – porovnání sloupce s literálem, IN, IS NULL, LIKE a AND nebo OR jejich kombinace). Filtry odkazované na operátory nebo funkce uvedené níže vyžadují materializaci.
Projekce

Následující další pushdowny jsou podporovány při povolené materializaci. Při materializaci se filtry kompilují do SQL místo omezení řádků rozhraní API služby BigQuery Storage, takže můžou navíc obsahovat následující operátory a funkce:

Omezení
Posun při použití s limitem
Agregáty
Řazení při použití s limitem
Slučování (Databricks Runtime 16.1 nebo novější)
Porovnání, logické, bitové a aritmetické operátory (aritmetické operátory posunují dolů pouze v případě, že je povolený režim ANSI)
Matematické funkce (ABS, FLOOR) – částečná podpora, pouze výrazy filtru
Řetězcové funkce (CONCAT, UPPER, LOWER, LENGTH, TRIM, , , LTRIMRTRIM) – částečná podpora, pouze výrazy filtru
Contains, Startswith, Endswith
Funkce data, času a časového razítka (DATE_TRUNCa EXTRACT pro rok, čtvrtletí, měsíc, den, hodinu a minutu) – částečná podpora, pouze výrazy filtru
Různé funkce (COALESCE, Cast, CASE WHEN, IF a přístup k prvkům pole) – částečná podpora, pouze pro výrazy filtru

Následující pushdowny nejsou podporovány:

Funkce okna

Mapování datového typu

Následující tabulka ukazuje mapování datového typu BigQuery na Spark.

Typ BigQuery	Typ Spark
`BIGNUMERIC`, `NUMERIC`	`DecimalType`*
`INT64`	`LongType`
`FLOAT64`	`DoubleType`
`ARRAY`, `GEOGRAPHY`, `INTERVAL`, `JSON`, , `STRINGSTRUCT`	`VarcharType`
`BYTES`	`BinaryType`
`BOOL`	`BooleanType`
`DATE`	`DateType`
`DATETIME`	`TimestampNTZType`, s výjimkou `StringType` v Databricks Runtime 16.4 až 17.x**
`TIME`, `TIMESTAMP`	`TimestampType`/`TimestampNTZType`
Libovolný typ s režimem `REPEATED`	`ArrayType` příslušného typu Sparku***

* BigQuery BIGNUMERIC má přesnost až 76 číslic, což překračuje maximální DecimalType přesnost Sparku 38. Ve výchozím nastavení se BIGNUMERIC mapuje na DecimalType(38, 38). Ke konfiguraci škálování použijte bigNumericDefaultScale možnost katalogu. Povolené hodnoty jsou [0, 38]. Například bigNumericDefaultScale = '10' mapuje BIGNUMERIC na DecimalType(38, 10). BigQuery NUMERIC odpovídá jeho deklarované přesnosti a měřítku.

** Konektor začal používat rozhraní API služby BigQuery Storage v Databricks Runtime 16.4. V Databricks Runtime 16.4 až 17.x mapovalo Storage API BigQuery DATETIME na Spark StringType místo TimestampNTZType. Databricks Runtime 18.0 obnovuje mapování TimestampNTZType.

*** V BigQuery se sloupec s režimem REPEATED mapuje na typ Spark ArrayType, který obsahuje odpovídající typ Spark. Například sloupec BigQuery REPEATED STRING se mapuje na ArrayType(VarcharType) a sloupec BigQuery REPEATED INT64 se mapuje na ArrayType(LongType).

Při čtení z BigQuery se BigQuery Timestamp mapuje na Spark TimestampType , pokud preferTimestampNTZ = false (výchozí). BigQuery Timestamp je mapován na TimestampNTZType if preferTimestampNTZ = true.

Řešení problémů

Následující část popisuje běžnou chybu a její řešení při použití konektoru BigQuery.

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

Běžná příčina: Účet služby používaný připojením nemá roli uživatele BigQuery .

Usnesení:

Udělte roli uživatele BigQuery účtu služby používanému připojením. Tato role se vyžaduje k vytvoření datové sady materializace, která dočasně ukládá výsledky dotazu.
Znovu spusťte dotaz.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-07-08

Spouštění federovaných dotazů v Google BigQuery

Než začnete

Vytvoření připojení

Průzkumník katalogu

SQL

Vytvoření zahraničního katalogu

Průzkumník katalogu

SQL

Zhmotnění

Čtení externích tabulek BigQuery

Podporované externí tabulky

Podporované odsdílení změn

Mapování datového typu

Řešení problémů

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

Váš názor

Další materiály

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