Uruchamianie zapytań federacyjnych w usłudze Google BigQuery

Na tej stronie opisano sposób konfigurowania federacji lakehouse w celu uruchamiania zapytań federacyjnych na danych BigQuery, które nie są zarządzane przez usługę Azure Databricks. Aby dowiedzieć się więcej o federacji Lakehouse, zobacz Co to jest Federacja Lakehouse?

Aby nawiązać połączenie z bazą danych BigQuery przy użyciu Lakehouse Federation, musisz utworzyć następujące elementy w magazynie metadanych Azure Databricks Unity Catalog (obszary robocze utworzone po 9 listopada 2023 r. mają już automatycznie aprowizowany Unity Catalog):

Połączenie do bazy danych BigQuery.
zagraniczny katalog, który dubluje bazę danych BigQuery w Unity Catalog, dzięki czemu można użyć składni zapytań Unity Catalog i narzędzi zarządzania ładem danych w celu zarządzania dostępem użytkowników do bazy danych Azure Databricks.

Zanim rozpoczniesz

Wymagania dotyczące obszaru roboczego:

Obszar roboczy z włączonym Katalogiem Unity.

Wymagania dotyczące obliczeń:

Łączność sieciowa z klastra środowiska Databricks Runtime lub usługi SQL Warehouse z docelowymi systemami baz danych. Zobacz Zalecenia dotyczące sieci dla usługi Lakehouse Federation.
Klastry usługi Azure Databricks muszą używać środowiska Databricks Runtime 16.1 lub nowszego oraz standardowego lub dedykowanego trybu dostępu (wcześniej znanego jako tryb udostępniony i tryb pojedynczego użytkownika).
Magazyny SQL muszą być typu Pro lub Serverless.

Wymagane uprawnienia:

Aby utworzyć połączenie, musisz mieć CREATE CONNECTION uprawnienia do magazynu metadanych Unity Catalog, który jest przypięty do obszaru roboczego.
Aby utworzyć katalog obcy, musisz mieć uprawnienie CREATE CATALOG w metastore i być właścicielem połączenia lub mieć uprawnienie CREATE FOREIGN CATALOG do połączenia.

Dodatkowe wymagania dotyczące uprawnień są określone w każdej sekcji odnoszącej się do zadań.

Tworzenie połączenia

Połączenie wskazuje ścieżkę i poświadczenia potrzebne do uzyskania dostępu do zewnętrznego systemu bazy danych. Aby utworzyć połączenie, możesz użyć Eksploratora wykazu lub polecenia CREATE CONNECTION SQL w notesie usługi Azure Databricks lub edytorze zapytań SQL usługi Databricks.

Uwaga

Do utworzenia połączenia można również użyć interfejsu API REST usługi Databricks lub interfejsu wiersza polecenia usługi Databricks. Zobacz POST /api/2.1/unity-catalog/connections i polecenia katalogu Unity.

Wymagane uprawnienia: administrator magazynu metadanych lub użytkownik z uprawnieniami CREATE CONNECTION .

Eksplorator wykazu

W obszarze roboczym usługi Azure Databricks kliknij Wykaz.
W górnej części okienka Wykaz kliknij Ikona Dodaj i wybierz pozycję Utwórz połączenie z menu.
Na stronie Podstawy połączenia kreatora Konfigurowanie połączenia wprowadź przyjazną dla użytkownika nazwę połączenia .
Wybierz typ połączenia Google BigQuery, a następnie kliknij przycisk Dalej.

Na stronie Uwierzytelniania wprowadź plik json klucza konta usługi Google dla instancji usługi BigQuery.

Jest to surowy obiekt JSON, który służy do określenia projektu BigQuery i zapewnienia uwierzytelniania. Możesz wygenerować ten obiekt JSON i pobrać go ze strony szczegółów konta usługi w usłudze Google Cloud w obszarze "KLUCZE". Konto usługi musi mieć odpowiednie uprawnienia przyznane w BigQuery, w tym użytkownika BigQuery i Podgląd danych BigQuery . Poniżej przedstawiono przykład.

{
  "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"
}

(Opcjonalnie) Wprowadź identyfikator projektu dla wystąpienia BigQuery:

Jest to nazwa projektu BigQuery używanego do rozliczeń dla wszystkich zapytań uruchamianych w ramach tego połączenia. Domyślnie jest to identyfikator projektu konta usługi. Konto usługi musi mieć odpowiednie uprawnienia przyznane dla tego projektu w BigQuery, w tym uprawnienia użytkownika BigQuery. W tym projekcie można utworzyć dodatkowy zestaw danych używany do przechowywania tabel tymczasowych przez funkcję BigQuery.
(Opcjonalnie) Dodaj komentarz.
Kliknij Utwórz połączenie.
Na stronie Catalog basics (Podstawy wykazu) wprowadź nazwę katalogu zagranicznego. Wykaz obcy odzwierciedla bazę danych w zewnętrznym systemie danych, dzięki czemu można wykonywać zapytania o dostęp do danych w tej bazie danych i zarządzać nimi przy użyciu usług Azure Databricks i Unity Catalog.
(Opcjonalnie) Kliknij pozycję Testuj połączenie, aby potwierdzić, że działa.
Kliknij Utwórz katalog.
Na stronie Access wybierz obszary robocze, w których użytkownicy mogą uzyskiwać dostęp do utworzonego katalogu. Możesz wybrać Wszystkie obszary robocze mają dostęplub kliknij Przypisz do obszarów roboczych, wybierz obszary robocze, a następnie kliknij Przypisz.
Zmień właściciela , który będzie mógł zarządzać dostępem do wszystkich obiektów w wykazie. Zacznij wpisywać nazwę lub podmiot w polu tekstowym, a następnie kliknij tę nazwę lub podmiot w zwróconych wynikach.
Udziel przywilejów w katalogu. Kliknij przycisk Udziel:
1. Określ podmioty główne, które będą miały dostęp do obiektów w katalogu. Zacznij wpisywać nazwę lub podmiot w polu tekstowym, a następnie kliknij tę nazwę lub podmiot w zwróconych wynikach.
2. Wybierz ustawienia wstępne uprawnień , aby przyznać każdemu użytkownikowi. Wszyscy użytkownicy konta otrzymują domyślnie BROWSE.
  - Wybierz Czytnik danych z menu rozwijanego, aby przyznać read uprawnienia do obiektów w katalogu.
  - Wybierz pozycję Edytor danych z menu rozwijanego, aby przyznać read i modify uprawnienia do obiektów w wykazie.
  - Ręcznie wybierz uprawnienia do udzielenia.
3. Kliknij i udziel.
Kliknij przycisk Dalej.
Na stronie Metadane określ pary tagów klucz-wartość. Aby uzyskać więcej informacji, zobacz Zastosuj tagi do obiektów z zabezpieczeniami w katalogu Unity.
(Opcjonalnie) Dodaj komentarz.
Kliknij Zapisz.

SQL

Uruchom następujące polecenie w notesie lub edytorze zapytań SQL usługi Databricks. Zastąp <GoogleServiceAccountKeyJson> element nieprzetworzonym obiektem JSON, który określa projekt BigQuery i zapewnia uwierzytelnianie. Możesz wygenerować ten obiekt JSON i pobrać go ze strony szczegółów konta usługi w usłudze Google Cloud w obszarze "KLUCZE". Konto usługi musi mieć odpowiednie uprawnienia przyznane w BigQuery, w tym BigQuery User i BigQuery Data Viewer. Aby zapoznać się z przykładowym obiektem JSON, spójrz na kartę Catalog Explorer na tej stronie.

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

Zalecamy używanie tajnych wpisów w Azure Databricks zamiast ciągów w postaci zwykłego tekstu dla wartości poufnych, takich jak poświadczenia. Na przykład:

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

Aby uzyskać informacje na temat konfigurowania wpisów tajnych, zobacz Zarządzanie wpisami tajnymi.

Tworzenie wykazu obcego

Uwaga

Jeśli używasz interfejsu użytkownika do utworzenia połączenia ze źródłem danych, tworzenie zewnętrznego katalogu zostanie uwzględnione i możesz pominąć ten krok.

Wykaz obcy odzwierciedla bazę danych w zewnętrznym systemie danych, dzięki czemu można wykonywać zapytania o dostęp do danych w tej bazie danych i zarządzać nimi przy użyciu usług Azure Databricks i Unity Catalog. Aby utworzyć wykaz obcy, użyj połączenia ze źródłem danych, które zostało już zdefiniowane.

Aby utworzyć wykaz obcy, możesz użyć Eksploratora wykazu lub CREATE FOREIGN CATALOG w notesie usługi Azure Databricks lub edytorze zapytań SQL usługi Databricks. Do utworzenia katalogu można również użyć interfejsu API REST usługi Databricks lub interfejsu wiersza polecenia usługi Databricks. Zobacz POST /api/2.1/unity-catalog/catalogs lub polecenia Unity Catalog .

Wymagane uprawnienia:CREATE CATALOG uprawnienie do magazynu metadanych i własność połączenia lub CREATE FOREIGN CATALOG uprawnienia do połączenia.

Eksplorator wykazu

W obszarze roboczym usługi Azure Databricks kliknij Wykaz do otwierania Eksploratora wykazu.
Na górze okienka Katalog kliknij ikonę Dodaj i wybierz Dodaj katalog z menu.

Alternatywnie, na stronie Strona szybkiego dostępu, kliknij przycisk Katalogi, a następnie kliknij przycisk Utwórz katalog.
(Opcjonalnie) Wprowadź następującą właściwość wykazu:

Identyfikator projektu danych: nazwa projektu BigQuery zawierającego dane, które zostaną przypisane do tego wykazu. Domyślnie używany jest identyfikator projektu rozliczeniowego ustawiony na poziomie połączenia.
Postępuj zgodnie z instrukcjami dotyczącymi tworzenia katalogów obcych w Tworzenie katalogów.
(Opcjonalnie) Określ następujące opcje wykazu:
- Materialization Dataset: opcjonalna nazwa zestawu danych BigQuery używana do materializowania wyników zapytania. Jeśli nie zostanie określony, zestaw danych do materializacji zostanie automatycznie przydzielony, kiedy to konieczne. Aby uzyskać więcej informacji, zobacz Materialization.
- BIGNUMERIC Default Scale: opcjonalna wartość skalowania dla mapowania BigQuery BIGNUMERIC na Spark DecimalType. Aby uzyskać więcej informacji, zobacz Mapowania typów danych .

SQL

Uruchom następujące polecenie SQL w notesie lub edytorze SQL usługi Databricks. Elementy w nawiasach kwadratowych są opcjonalne. Zastąp wartości zastępcze.

<catalog-name>: nazwa wykazu w usłudze Azure Databricks.
<connection-name>: obiekt połączenia określający źródło danych, ścieżkę i poświadczenia dostępu.
<data-project-id>: opcjonalny identyfikator projektu BigQuery zawierający dane, które mają być mapowane na ten katalog. Jeśli nie zostanie określony, zostanie użyty identyfikator projektu ustawiony na połączeniu, a następnie identyfikator projektu konta usługi.
<dataset-name>: opcjonalna nazwa zestawu danych BigQuery używana do materializowania wyników zapytania. Zestaw danych materializacji zostanie automatycznie tworzony w razie potrzeby, jeśli nie zostanie określony. Aby uzyskać więcej informacji, zobacz Materialization.
<scale>: opcjonalna wartość skalowania [0, 38] dla mapowania bigquery BIGNUMERIC na platformę Spark DecimalType(38, scale). Wartość domyślna to 38. Aby uzyskać więcej informacji, zobacz Mapowania typów danych .

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

Materializacja

W przeciwieństwie do innych łączników federacyjnych łącznik BigQuery używa interfejsów API BigQuery Storage zamiast JDBC w celu zwiększenia wydajności. Usługa Azure Databricks może odczytywać dane z BigQuery bezpośrednio z pamięci masowej lub przy użyciu zmaterializowanego zestawu danych. Operacje odczytu bezpośredniego oferują lepszą wydajność dla dużych skanowań oraz obsługują przesunięcia filtrów i projekcji. Materializacja wypycha dodatkowe operacje (limit, agregacje, sprzężenia, sortowanie) do obliczeń BigQuery przed przesyłaniem strumieniowych wyników do usługi Azure Databricks.

Widoki i tabele zewnętrzne są zawsze materializowane. Wszystkie pozostałe odczyty domyślnie używają bezpośredniej pamięci masowej bez materializacji.

Rozważ włączenie materializacji, jeśli potrzebujesz zaawansowanych zrzutów do bazy, odczytujesz małe zbiory wyników z dużych zbiorów danych lub odczytujesz dane między regionami. Materializacja wiąże się z dodatkowymi opłatami za obliczenia w BigQuery. Aby włączyć materializację, ustaw następującą konfigurację platformy Spark:

SET spark.databricks.bigquery.enableMaterialization = true;

Domyślnie zestaw danych do materializacji jest automatycznie tworzony, gdy jest to potrzebne. Niestandardowy zestaw danych można określić przy użyciu materializationDataset opcji wykazu podczas tworzenia lub zmieniania wykazu obcego. Jest to przydatne, jeśli konto usługi nie ma uprawnień do tworzenia zestawów danych lub chcesz kontrolować miejsce przechowywania tymczasowych tabel materializacji. Na przykład:

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

Aby zaktualizować istniejący wykaz, uruchom polecenie:

ALTER CATALOG my_catalog OPTIONS (materializationDataset 'my_materialization_dataset');

Obsługiwane wypychania

Następujące wypychania są obsługiwane bez materializacji:

Filtry
Projekcje

Następujące dodatkowe wypychania są obsługiwane z włączoną materializacją:

Ograniczenie
Funkcje (częściowe wsparcie tylko dla wyrażeń filtrów: funkcje ciągów znaków, funkcje matematyczne, funkcje daty, godziny i znacznika czasu oraz inne różne funkcje, takie jak Alias, Cast, KolejnośćSortowania)
Agregacje
Sortowanie z użyciem limitu
Łączenia (środowisko Databricks Runtime w wersji 16.1 lub nowszej)

Następujące wypychania nie są obsługiwane:

Funkcje okna

Mapowanie typu danych

W poniższej tabeli przedstawiono mapowanie typu danych BigQuery na Spark.

Typ BigQuery	Typ Spark
BIGNUMERIC, NUMERIC	Typ dziesiętny*
INT64	LongType
FLOAT64	PodwójnyTyp
ARRAY, GEOGRAPHY, INTERVAL, JSON, STRING, STRUKTURA	Typ Varchar
BAJTÓW	Typ binarny
bool	Typ Boolean
DATE	Typ daty
DATETIME, TIME, TIMESTAMP	TimestampType/TimestampNTZType

* BigQuery BIGNUMERIC ma precyzję do 76 cyfr, która przekracza maksymalną DecimalType precyzję platformy Spark wynoszącą 38. Domyślnie BIGNUMERIC mapuje na DecimalType(38, 38). Aby skonfigurować skalę, użyj bigNumericDefaultScale opcji katalogu. Dozwolone wartości to [0, 38]. Na przykład bigNumericDefaultScale = '10' mapuje BIGNUMERIC na DecimalType(38, 10). BigQuery NUMERIC mapuje na zadeklarowaną precyzję i skalę.

Podczas odczytywania z BigQuery, BigQuery Timestamp jest mapowany na Spark TimestampType jeśli preferTimestampNTZ = false (wartość domyślna). Funkcja BigQuery Timestamp jest mapowana na TimestampNTZType jeśli preferTimestampNTZ = true.

Rozwiązywanie problemów

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

Typowa przyczyna: Konto usługi używane w połączeniu nie ma przypisanej roli BigQuery User.

Rozwiązanie:

Przyznaj użytkownikowi BigQuery rolę konta usługi używanego przez połączenie. Ta rola jest wymagana do utworzenia zestawu danych materializacji, który tymczasowo przechowuje wyniki zapytań.
Uruchom ponownie zapytanie.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-04-04

Udostępnij za pośrednictwem

Uruchamianie zapytań federacyjnych w usłudze Google BigQuery

Zanim rozpoczniesz

Tworzenie połączenia

Eksplorator wykazu

SQL

Tworzenie wykazu obcego

Eksplorator wykazu

SQL

Materializacja

Obsługiwane wypychania

Mapowanie typu danych

Rozwiązywanie problemów

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

Opinia

Dodatkowe zasoby

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