Dotazování externích databází pomocí `remote_query` funkce

Důležité

Funkce s návratovou tabulkou remote_query (TVF) umožňuje spouštět dotazy SQL přímo na externí databáze a datové sklady z prostředí Azure Databricks pomocí nativní syntaxe SQL vzdáleného systému. Tato funkce poskytuje flexibilní alternativu k federaci dotazů, takže můžete spouštět dotazy napsané v dialektu vzdálené databáze, aniž byste je museli překládat do Databricks SQL.

`remote_query` ve srovnání s federací dotazů

Následující tabulka shrnuje klíčové rozdíly mezi remote_query funkcí a federací dotazů:

Vlastnost	`remote_query` Funkce	Federace dotazů
Syntaxe dotazu	Zapisujte dotazy pomocí nativního dialektu SQL vzdálené databáze (například Oracle PL/SQL, BigQuery SQL).	Zápis dotazů pomocí syntaxe SQL Databricks Databricks překládá a odesílá do vzdálené databáze kompatibilní operace.
Případ použití	Máte existující dotazy SQL napsané v dialektu vzdálené databáze, který chcete spustit bez úprav. Potřebujete použít funkce nebo syntaxi specifické pro databázi, které nemusí být v Databricks SQL dostupné. Chcete ad hoc přístup ke vzdáleným datům bez vytváření cizích katalogů.	Chcete dotazovat externí data pomocí syntaxe SQL Databricks. Potřebujete dlouhodobý model přístupu k datům s řízeným přístupem prostřednictvím cizích katalogů Katalogu Unity. Chcete zkombinovat data z více zdrojů v jednom dotazu pomocí konzistentní syntaxe. Chcete použít asistenta Genie k psaní dotazů.
Řízení přístupu	Uživatelé potřebují `USE CONNECTION` oprávnění k připojení. Oprávnění je možné delegovat prostřednictvím zobrazení.	Uživatelé potřebují oprávnění na úrovni tabulky pro objekty cizího katalogu. Jemné řízení.

Než začnete

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. Podívejte se na doporučení pro síťování pro Lakehouse Federation.
Clustery Azure Databricks musí používat Databricks Runtime 17.3 nebo vyšší.
SQL sklady musí být verze Profi nebo Serverless a musí používat verzi 2025.35 nebo vyšší.

Požadovaná oprávnění:

Pokud chcete vytvořit připojení, musíte mít CREATE CONNECTION oprávnění k metastoru katalogu Unity.
Abyste mohli používat funkci remote_query, musíte mít oprávnění USE CONNECTION pro připojení nebo oprávnění SELECT pro zobrazení, které funkci obsahuje. Clustery s jedním uživatelem také vyžadují MANAGE oprávnění k připojení.

Vytvořit připojení

Abyste mohli funkci použít remote_query , musíte nejprve vytvořit připojení katalogu Unity k externí databázi. Pokud už máte vytvořené připojení pro federaci dotazů, můžete ho znovu použít.

Funkce remote_query podporuje připojení k následujícím typům připojení:

Informace o správě existujících připojení naleznete v tématu Správa připojení proLakehouse Federation .

Udělení přístupu k připojení

Abyste mohli používat funkci remote_query, musíte mít oprávnění USE CONNECTION k připojení (nebo oprávnění MANAGE na clusteru s jedním uživatelem).

GRANT USE CONNECTION ON CONNECTION <connection-name> TO <user-or-group>;

Použijte funkci `remote_query`

Funkce remote_query spustí dotaz na vzdálenou databázi a vrátí výsledky jako tabulku, kterou můžete použít v dotazech SQL Databricks.

Syntaxe

SELECT * FROM remote_query(
  '<connection-name>',
  <option-key> => '<option-value>'
  [, <option-key> => '<option-value>' ...]
)

Požadované parametry

connection-name: Název připojení ke katalogu Unity, které se má použít.

Všechny ostatní požadované parametry se liší podle typu připojení. Podrobnosti najdete v tématu Možnosti specifické pro konektory .

Možnosti specifické pro konektory

Dostupné možnosti se liší podle typu připojení. Následující tabulky popisují možnosti jednotlivých konektorů.

MySQL, PostgreSQL, SQL Server, Redshift a Teradata

Parameter	Povinné	Description
`database`	Ano	Název databáze ve vzdáleném systému.
`query`	Ano (nebo `dbtable`)	Řetězec dotazu SQL, který se má spustit ve vzdálené databázi. Nelze použít s `dbtable`.
`dbtable`	Ano (nebo `query`)	Název tabulky pro dotazování. Nelze použít s `query`.
`fetchsize`	Ne	Počet řádků, které se mají načíst na zpáteční cestu. Větší hodnoty můžou zvýšit výkon, ale využívat více paměti. Výchozí hodnota: 0 (použít výchozí nastavení ovladače).
`partitionColumn`	Ne	Sloupec s jednotně distribuovanými hodnotami, který se má použít pro paralelní načítání dat. Musí se používat s `lowerBound`, `upperBound`a `numPartitions`. Nelze použít s možností `query`.
`lowerBound`	Ne	Minimální hodnota sloupce oddílu. Musí se používat s `partitionColumn`, `upperBound`a `numPartitions`.
`upperBound`	Ne	Maximální hodnota sloupce oddílu. Musí se používat s `partitionColumn`, `lowerBound`a `numPartitions`.
`numPartitions`	Ne	Počet paralelních připojení k použití pro načítání dat. Nenastavujte to příliš vysoko (stovky). Musí se používat s `partitionColumn`, `lowerBound`a `upperBound`.

Poznámka:

Při použití parametrů oddílu musí být všechny čtyři parametry (partitionColumn, lowerBound, upperBound, numPartitions) zadány společně a musíte použít možnost dbtable místo query.

Oracle

Parameter	Povinné	Description
`service_name`	Ano	Název služby Oracle (používá se místo `database`).
`query`	Ano (nebo `dbtable`)	Řetězec dotazu SQL, který se má spustit ve vzdálené databázi. Nelze použít s `dbtable`.
`dbtable`	Ano (nebo `query`)	Název tabulky pro dotazování. Nelze použít s `query`.
`fetchsize`	Ne	Počet řádků, které se mají načíst na zpáteční cestu. Větší hodnoty můžou zvýšit výkon, ale využívat více paměti. Výchozí hodnota: 0 (použít výchozí nastavení ovladače).
`partitionColumn`	Ne	Sloupec s jednotně distribuovanými hodnotami, který se má použít pro paralelní načítání dat. Musí se používat s `lowerBound`, `upperBound`a `numPartitions`. Nelze použít s možností `query`.
`lowerBound`	Ne	Minimální hodnota sloupce oddílu. Musí se používat s `partitionColumn`, `upperBound`a `numPartitions`.
`upperBound`	Ne	Maximální hodnota sloupce oddílu. Musí se používat s `partitionColumn`, `lowerBound`a `numPartitions`.
`numPartitions`	Ne	Počet paralelních připojení k použití pro načítání dat. Nenastavujte to příliš vysoko (stovky). Musí se používat s `partitionColumn`, `lowerBound`a `upperBound`.

Poznámka:

Snowflake

Parameter	Povinné	Description
`database`	Ano	Název databáze v rámci Snowflake.
`query`	Ano (nebo `dbtable`)	Řetězec dotazu SQL, který se má spustit ve vzdálené databázi. Nelze použít s `dbtable`.
`dbtable`	Ano (nebo `query`)	Název tabulky, která se má dotazovat (název jedné části nebo název více částí). Nelze použít s `query`.
`schema`	Ne	Název schématu Snowflake. Výchozí hodnota: `public`.
`query_timeout`	Ne	Časový limit dotazu v sekundách. Výchozí hodnota: 0 (bez časového limitu).
`partition_size_in_mb`	Ne	Očekávaná velikost oddílu v megabajtech pro paralelní načítání dat. Výchozí hodnota: 100 MB.

BigQuery

Parameter	Povinné	Description
`query`	Ano (nebo `dbtable`)	Řetězec dotazu SQL, který se má spustit ve vzdálené databázi. Nelze použít s `dbtable`.
`dbtable`	Ano (nebo `query`)	Název tabulky pro dotazování. Nelze použít s `query`.
`materializationDataset`	Ano, pokud je potřeba materializace výsledků. Materializace je nutná, pokud `query` je zadána a pokud `dbtable` odkazuje na zobrazení.	Název datové sady BigQuery, kde jsou dočasné tabulky materializovány. Výchozí hodnota TTL (Time to Live) dočasných tabulek je 24 hodin.
`materializationProject`	Ne	ID projektu BigQuery pro proces materializace. Ve výchozím nastavení se automaticky vybere projekt zadaný v připojení.
`materializationEnabled`	Ne	Zda povolit materializaci pro dotazy. Nastavte na `true`, abyste mohli dotazovat zobrazení. Výchozí hodnota: `false` pokud `dbtable` je zadána, `true` pokud `query` je zadána.
`parentProject`	Ne	ID nadřazeného projektu pro účely fakturace.

Důležité

Všechny parametry BigQuery rozlišují malá a velká písmena.

JDBC

Připojení JDBC jsou obecná a můžou se připojit k jakékoli databázi pomocí ovladače JDBC. Databricks doporučuje použít připojení JDBC pouze v případě, že vaše databáze není podporována jedním z dalších předdefinovaných typů připojení, protože integrované typy připojení nabízejí lepší výkon. Na rozdíl od ostatních předdefinovaných typů připojení nemá typ připojení JDBC žádnou integrovanou sadu povolených možností doby dotazu. Aby bylo možné nastavit možnost při spuštění dotazu, musí ji vlastník připojení přidat do parametru externalOptionsAllowList u připojení. Pokud externalOptionsAllowList není nastavená, nelze v době dotazu předat žádné možnosti.

Poznámka:

Možnosti definované pro připojení nelze v době dotazu přepsat. Parametry připojení host, port, serverName, portNumber a instanceName nelze nikdy nastavit v době zadání dotazu, bez ohledu na externalOptionsAllowList. Podrobnosti najdete v tématu Připojení JDBC .

Další možnosti ovládacího prvku pushdown

Funkci remote_query můžete kombinovat s operacemi SQL Databricks a většinu těchto operací lze také přenést. Můžete také určit, které operace SQL v rámci Databricks je možné posunout dolů. Tyto možnosti platí pro všechny typy připojení a nerozlišují malá a velká písmena.

Parameter	Výchozí	Description
`pushdown.limit.enabled`	`true`	Povolte nebo zakažte vkládání `LIMIT` klauzulí do vzdálené databáze.
`pushdown.offset.enabled`	`true`	Povolte nebo zakažte vkládání `OFFSET` klauzulí do vzdálené databáze.
`pushdown.filters.enabled`	`true`	Povolte nebo zakažte propagaci `WHERE` filtrů na vzdálenou databázi.
`pushdown.aggregates.enabled`	`true`	Povolte nebo zakažte delegování agregačních funkcí (`COUNT`, `SUM`, `AVG`, `MAX`, `MIN`) do vzdálené databáze.
`pushdown.sortLimit.enabled`	`true`	Povolte nebo zakažte přenášení top-N dotazů (kombinace `ORDER BY` a `LIMIT`) do vzdálené databáze.

Ve výchozím nastavení jsou povoleny všechny podmíněné operace. Můžete zakázat konkrétní optimalizace databázového výkonu, pokud je to potřebné pro řešení potíží nebo pro překonání kompatibility s některými vzdálenými databázemi.

Delegování přístupu prostřednictvím zobrazení

Přístup ke vzdáleným datům lze delegovat bez udělení přímých oprávnění USE CONNECTION uživatelům tím, že funkci remote_query zabalíte do zobrazení. Tento přístup má následující výhody:

Zjednodušené řízení přístupu: Udělte SELECT oprávnění v zobrazení místo správy USE CONNECTION oprávnění.
Zabezpečení dat: Určením dotazu zobrazení můžete určit, ke kterým sloupcům a řádkům mají uživatelé přístup.
Sledování linie: Sledujte přístup k datům prostřednictvím linií zobrazení místo přímého využití připojení.

Delegování přístupu prostřednictvím zobrazení:

Vytvořte zobrazení, které volá remote_query funkci:

CREATE VIEW sales_data_view AS
SELECT * FROM remote_query(
  'my_connection',
  database => 'sales_db',
  query => 'SELECT region, product, revenue FROM sales'
);

Udělení SELECT oprávnění k zobrazení uživatelům nebo skupinám:
```
GRANT SELECT ON VIEW sales_data_view TO <user-or-group>;
```
Uživatelé teď můžou dotazovat zobrazení, aniž by potřebovali USE CONNECTION oprávnění:
```
SELECT * FROM sales_data_view WHERE region = 'US';
```

Důležité

Vlastník zobrazení musí mít USE CONNECTION oprávnění k připojení. Když se uživatelé dotazují na zobrazení, provede se kontrola přístupu k připojení pomocí oprávnění vlastníka zobrazení, nikoli pomocí dotazů na oprávnění uživatele.

Examples

Základní spouštění dotazů

Spusťte dotaz na databázi PostgreSQL:

SELECT * FROM remote_query(
  'my_postgres_connection',
  database => 'sales_db',
  query => 'SELECT * FROM orders WHERE order_date > CURRENT_DATE - INTERVAL \'30 days\''
);

Dotazování na konkrétní tabulku

Dotazování přímo na tabulku MySQL:

SELECT * FROM remote_query(
  'my_mysql_connection',
  database => 'inventory',
  dbtable => 'my_schema.products'
);

Oracle s názvem služby

Dotazování databáze Oracle:

SELECT * FROM remote_query(
  'my_oracle_connection',
  service_name => 'ORCL',
  query => 'SELECT * FROM customers WHERE ROWNUM <= 1000'
);

Dotaz BigQuery

Provedení dotazu v Google BigQuery:

SELECT * FROM remote_query(
  'my_bigquery_connection',
  materializationDataset => 'analytics',
  query => 'SELECT * FROM `project.dataset.table` WHERE created_date > DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)'
);

Dotaz ve Snowflake

Dotazování ve Snowflake

SELECT * FROM remote_query(
  'my_snowflake_connection',
  database => 'ANALYTICS_DB',
  query => 'SELECT * FROM SALES WHERE SALE_DATE >= DATEADD(day, -30, CURRENT_DATE())'
);

Dotaz JDBC

Dotazování databáze pomocí připojení JDBC:

SELECT * FROM remote_query(
  'my_jdbc_connection',
  query => 'SELECT * FROM customers WHERE active = 1'
);

Ladění výkonu a partitionování

Paralelní načítání dat z tabulky SQL Serveru:

SELECT * FROM remote_query(
  'my_sqlserver_connection',
  database => 'sales',
  dbtable => 'transactions',
  partitionColumn => 'transaction_id',
  lowerBound => '0',
  upperBound => '1000000',
  numPartitions => '10',
  fetchsize => '1000'
);

Kombinování s operacemi SQL Databricks

Použijte další filtry a transformace:

SELECT customer_id, SUM(amount) as total_amount
FROM remote_query(
  'my_postgres_connection',
  database => 'orders_db',
  query => 'SELECT customer_id, amount, order_date FROM orders'
)
WHERE order_date >= '2025-01-01'
GROUP BY customer_id
HAVING total_amount > 1000
ORDER BY total_amount DESC
LIMIT 100;

Vytvoření zobrazení pro delegovaný přístup

Vytvořte zobrazení, která zabalí funkci remote_query. Uživatelé s SELECT oprávněním v zobrazení můžou dotazovat data bez nutnosti USE CONNECTION oprávnění k podkladovému připojení:

CREATE VIEW sales_summary AS
SELECT * FROM remote_query(
  'my_mysql_connection',
  database => 'sales',
  query => 'SELECT region, product, SUM(revenue) as total_revenue FROM sales_data GROUP BY region, product'
);

GRANT SELECT ON VIEW sales_summary TO <user-or-group>;

Řízení chování při posunu

Když použijete remote_query funkci, Databricks může do vzdálené databáze za zadaný dotaz odesílat další operace. Tato funkce je užitečná, když dotazujete zobrazení používající funkci remote_query.

Následující operace je možné přenést dolů:

Filtry: WHERE Klauzule použité na výsledek vzdáleného dotazu
Projekce: Výběr sloupce (SELECT konkrétní sloupce)
Limit: LIMIT klauzule pro omezení počtu vrácených řádků
Posun: OFFSET klauzule pro přeskočení řádků
Agregace: Agregační funkce jako COUNT, SUM, AVG, MAX, MIN
Top-N: Kombinace dotazů pro vrchní/spodní N pomocí ORDER BY a LIMIT

Podpora pushdown se liší podle zdroje dat. Podrobnosti najdete v dokumentaci ke konkrétnímu typu připojení.

Zakažte konkrétní funkce pro odstraňování problémů nebo zajištění kompatibility.

SELECT * FROM remote_query(
  'my_postgres_connection',
  database => 'analytics',
  query => 'SELECT * FROM complex_view',
  `pushdown.aggregates.enabled` => 'false',
  `pushdown.filters.enabled` => 'false'
);

Omezení

Operace jen pro čtení: Funkce remote_query podporuje SELECT pouze dotazy. Operace úprav dat (INSERT, , UPDATEDELETE, MERGE), operace DDL (CREATE, DROP, ALTER) a uložené procedury nejsou podporovány.
Ověření dotazu: Zadaný dotaz se spustí přímo ve vzdálené databázi. Databricks ověří, jestli je dotaz jen pro čtení, a to provedením kontroly schématu, ale vzdálená databáze provádí syntaxi a sémantické ověřování.

Řešení problémů

Chyby oprávnění

Pokud se zobrazí chyba oprávnění, ověřte, že:

USE CONNECTION Máte oprávnění pro připojení nebo SELECT oprávnění v zobrazení, které obsahuje funkci.
Přihlašovací údaje v připojení mají příslušná oprávnění ke vzdálené databázi.

Příklad chyby:

PERMISSION_DENIED: User does not have USE CONNECTION on Connection 'my_connection'

Usnesení:

GRANT USE CONNECTION ON CONNECTION my_connection TO <user-or-group>;

Nepodporované parametry

Pokud se zobrazí chyba týkající se nepodporovaných parametrů, zkontrolujte, jestli pro váš typ připojení používáte správné parametry. Chybová zpráva obsahuje seznam povolených parametrů.

Příklad chyby:

REMOTE_QUERY_FUNCTION_UNSUPPORTED_CONNECTOR_PARAMETERS: The following parameters are not supported for connection type 'postgresql': 'materializationDataset'. Allowed parameters for this connection type are: 'database', 'query', 'dbtable', 'fetchsize', 'partitionColumn', 'lowerBound', 'upperBound', 'numPartitions'.

Řešení: Odeberte nepodporovaný parametr a použijte správné parametry pro váš typ připojení.

Operace DML nejsou podporovány

Funkce remote_query podporuje pouze dotazy pro čtení SELECT.

Příklad chyby:

DML_OPERATIONS_NOT_SUPPORTED_FOR_REMOTE_QUERY_FUNCTION: Data modification operations are not supported in remote_query function.

Řešení: Odeberte z dotazu všechny příkazy `INSERT`, `UPDATE`, DELETE nebo DDL. Používejte pouze příkazy SELECT.

Dodatečné zdroje

Váš názor

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

Last updated on 2026-05-18

Dotazování externích databází pomocí remote_query funkce

remote_query ve srovnání s federací dotazů

Než začnete

Vytvořit připojení

Udělení přístupu k připojení

Použijte funkci remote_query

Syntaxe

Požadované parametry

Možnosti specifické pro konektory

MySQL, PostgreSQL, SQL Server, Redshift a Teradata

Oracle

Snowflake

BigQuery

JDBC

Další možnosti ovládacího prvku pushdown

Delegování přístupu prostřednictvím zobrazení

Examples

Základní spouštění dotazů

Dotazování na konkrétní tabulku

Oracle s názvem služby

Dotaz BigQuery

Dotaz ve Snowflake

Dotaz JDBC

Ladění výkonu a partitionování

Kombinování s operacemi SQL Databricks

Vytvoření zobrazení pro delegovaný přístup

Řízení chování při posunu

Omezení

Řešení problémů

Chyby oprávnění

Nepodporované parametry

Operace DML nejsou podporovány

Dodatečné zdroje

Váš názor

Další materiály

Dotazování externích databází pomocí `remote_query` funkce

`remote_query` ve srovnání s federací dotazů

Použijte funkci `remote_query`