Esegui query su database esterni usando la funzione remote_query

Importante

Questa funzionalità è in Anteprima Pubblica.

La remote_query funzione con valori di tabella (TVF) consente di eseguire query SQL direttamente su database esterni e data warehouse dall'interno di Azure Databricks, usando la sintassi SQL nativa del sistema remoto. Questa funzione offre un'alternativa flessibile alla federazione delle query, consentendo di eseguire query scritte nel dialetto del database remoto senza dover convertirle in Databricks SQL.

remote_query rispetto alla federazione delle query

La tabella seguente riepiloga le differenze principali tra la funzione e la federazione delle remote_query query:

Attribute	Funzione remote_query	Federazione di query
Sintassi delle query	Scrivere query usando il dialetto SQL nativo del database remoto, ad esempio Oracle PL/SQL, BigQuery SQL.	Scrivere query usando la sintassi SQL di Databricks. Databricks traduce e invia operazioni compatibili al database remoto.
Caso d'uso	Sono presenti query SQL esistenti scritte nel dialetto del database remoto che si desidera eseguire senza alcuna modifica. È necessario usare funzioni o sintassi specifiche del database che potrebbero non essere disponibili in Databricks SQL. Si vuole accedere ad hoc ai dati remoti senza creare cataloghi stranieri.	Si vuole eseguire query su dati esterni usando la sintassi SQL di Databricks. È necessario un modello di accesso ai dati a lungo termine con accesso regolamentato tramite cataloghi stranieri di Unity Catalog. Si vogliono combinare dati da più origini in una singola query usando una sintassi coerente. Si vuole usare l'assistente Genie per la scrittura di query.
Controllo di accesso	Gli utenti devono disporre USE CONNECTION dei privilegi per la connessione. L'autorizzazione può essere delegata tramite visualizzazioni.	Gli utenti devono disporre di privilegi a livello di tabella per gli oggetti del catalogo esterno. Controllo con granularità fine.

Prima di iniziare

Requisiti dell'area di lavoro:

• Area di lavoro attivata per il catalogo Unity.

Requisiti di calcolo:

• Connettività di rete dal cluster Databricks Runtime o dal warehouse SQL ai sistemi di database di destinazione. Vedi Raccomandazioni sulla rete per Lakehouse Federation.
• I cluster di Azure Databricks devono usare Databricks Runtime 17.3 o versione successiva.
• I warehouse SQL devono essere Pro o Serverless e usare la versione 2025.35 o successiva.

Autorizzazioni necessarie:

• Per creare una connessione, è necessario avere il CREATE CONNECTION privilegio per il metastore del catalogo Unity.
• Per usare la funzione remote_query, è necessario avere il privilegio USE CONNECTION sulla connessione o il privilegio SELECT su una visualizzazione che esegue il wrapping della funzione. I cluster a utente singolo richiedono anche l'autorizzazione MANAGE per la connessione.

Creazione di una connessione

Per usare la remote_query funzione, è prima necessario creare una connessione del catalogo Unity al database esterno. Se è già stata creata una connessione per la federazione di query, è possibile riutilizzarla.

La remote_query funzione supporta le connessioni ai tipi di connessione seguenti:

• MySQL
• PostgreSQL
• Teradata
• Oracle
• Amazon Redshift
• Snowflake
• Microsoft SQL Server
• Google BigQuery

Per informazioni sulla gestione delle connessioni esistenti, vedere Gestione delle connessioni per Lakehouse Federation.

Concedere l'accesso alla connessione

Per usare la remote_query funzione, è necessario avere il USE CONNECTION privilegio per la connessione (o il MANAGE privilegio nei cluster a utente singolo).

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

Usare la remote_query funzione

La remote_query funzione esegue una query sul database remoto e restituisce i risultati come tabella che è possibile usare nelle query SQL di Databricks.

Sintassi

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

Parametri obbligatori

• connection-name: nome della connessione al catalogo Unity da usare.

Tutti gli altri parametri obbligatori variano in base al tipo di connessione. Per informazioni dettagliate, vedere Opzioni specifiche del connettore .

Opzioni specifiche del connettore

Le opzioni disponibili variano in base al tipo di connessione. Le tabelle seguenti descrivono le opzioni per ogni connettore.

MySQL, PostgreSQL, SQL Server, Redshift e Teradata

Parametro	Obbligatorio	Description
database	Yes	Nome del database nel sistema remoto.
query	Sì (o dbtable)	Stringa di query SQL da eseguire nel database remoto. Non è possibile usare con dbtable.
dbtable	Sì (o query)	Nome della tabella da interrogare. Non è possibile usare con query.
fetchsize	NO	Numero di righe da recuperare per viaggio di andata e ritorno. I valori più grandi possono migliorare le prestazioni, ma usare più memoria. Impostazione predefinita: 0 (usare l'impostazione predefinita del driver).
partitionColumn	NO	Colonna con valori distribuiti uniformemente da utilizzare per il recupero di dati paralleli. Deve essere usato con lowerBound, upperBounde numPartitions. Non è possibile utilizzare con l'opzione query .
lowerBound	NO	Valore minimo della colonna di partizione. Deve essere usato con partitionColumn, upperBounde numPartitions.
upperBound	NO	Valore massimo della colonna della partizione. Deve essere usato con partitionColumn, lowerBounde numPartitions.
numPartitions	NO	Numero di connessioni parallele da utilizzare per il recupero dei dati. Non impostare questo valore troppo alto (centinaia). Deve essere usato con partitionColumn, lowerBounde upperBound.

Annotazioni

Quando si usano parametri di partizione, tutti e quattro i parametri (, , , ) devono essere specificati insieme ed è necessario usare l'opzione partitionColumn anziché lowerBound. upperBoundnumPartitionsdbtablequery

Oracle

Parametro	Obbligatorio	Description
service_name	Yes	Nome del servizio Oracle (usato invece di database).
query	Sì (o dbtable)	Stringa di query SQL da eseguire nel database remoto. Non è possibile usare con dbtable.
dbtable	Sì (o query)	Nome della tabella da interrogare. Non è possibile usare con query.
fetchsize	NO	Numero di righe da recuperare per viaggio di andata e ritorno. I valori più grandi possono migliorare le prestazioni, ma usare più memoria. Impostazione predefinita: 0 (usare l'impostazione predefinita del driver).
partitionColumn	NO	Colonna con valori distribuiti uniformemente da utilizzare per il recupero di dati paralleli. Deve essere usato con lowerBound, upperBounde numPartitions. Non è possibile utilizzare con l'opzione query .
lowerBound	NO	Valore minimo della colonna di partizione. Deve essere usato con partitionColumn, upperBounde numPartitions.
upperBound	NO	Valore massimo della colonna della partizione. Deve essere usato con partitionColumn, lowerBounde numPartitions.
numPartitions	NO	Numero di connessioni parallele da utilizzare per il recupero dei dati. Non impostare questo valore troppo alto (centinaia). Deve essere usato con partitionColumn, lowerBounde upperBound.

Annotazioni

Quando si usano parametri di partizione, tutti e quattro i parametri (, , , ) devono essere specificati insieme ed è necessario usare l'opzione partitionColumn anziché lowerBound. upperBoundnumPartitionsdbtablequery

Snowflake

Parametro	Obbligatorio	Description
database	Yes	Nome del database in Snowflake.
query	Sì (o dbtable)	Stringa di query SQL da eseguire nel database remoto. Non è possibile usare con dbtable.
dbtable	Sì (o query)	Nome della tabella su cui eseguire una query (nome a parte singola o nome in più parti). Non è possibile usare con query.
schema	NO	Nome dello schema in Snowflake. Impostazione predefinita: public.
query_timeout	NO	Limite di tempo della query in secondi. Impostazione predefinita: 0 (nessun timeout).
partition_size_in_mb	NO	Dimensioni della partizione previste in megabyte per il recupero di dati paralleli. Impostazione predefinita: 100 MB.

BigQuery

Parametro	Obbligatorio	Description
query	Sì (o dbtable)	Stringa di query SQL da eseguire nel database remoto. Non è possibile usare con dbtable.
dbtable	Sì (o query)	Nome della tabella da interrogare. Non è possibile usare con query.
materializationDataset	Sì se è necessaria la materializzazione dei risultati. La materializzazione è necessaria se query è specificato e se dbtable punta a una vista.	Nome del set di dati BigQuery in cui vengono materializzate le tabelle temporanee. La durata (TTL) predefinita delle tabelle temporanee è di 24 ore.
materializationProject	NO	L'ID del progetto BigQuery per la materializzazione. Il valore predefinito è il progetto specificato nella connessione.
materializationEnabled	NO	Indica se abilitare la materializzazione per le query. Impostare il valore a true per interrogare le viste. Impostazione predefinita: false se dbtable è specificato, true se query specificato.
parentProject	NO	ID progetto padre ai fini della fatturazione.

Importante

Tutti i parametri BigQuery fanno distinzione tra maiuscole e minuscole.

Opzioni aggiuntive per il controllo del pushdown

È possibile combinare la funzione remote_query con le operazioni SQL di Databricks e anche la maggior parte di queste operazioni può essere eseguita in push. È anche possibile controllare quali operazioni SQL di Databricks possono essere ottimizzate. Queste opzioni si applicano a tutti i tipi di connessione e non fanno distinzione tra maiuscole e minuscole.

Parametro	Impostazione predefinita	Description
pushdown.limit.enabled	true	Abilitare o disabilitare il push delle clausole down LIMIT nel database remoto.
pushdown.offset.enabled	true	Abilitare o disabilitare il push delle clausole down OFFSET nel database remoto.
pushdown.filters.enabled	true	Abilitare o disabilitare l'applicazione dei filtri WHERE al database remoto.
pushdown.aggregates.enabled	true	Abilitare o disabilitare l'invio delle funzioni di aggregazione (COUNT, SUM, AVG, MAX, MIN) al database remoto.
pushdown.sortLimit.enabled	true	Abilitare o disabilitare il push delle query Top-N (combinazione di ORDER BY e LIMIT) al database remoto.

Per impostazione predefinita, tutti i pushdown sono abilitati. È possibile disabilitare i pushdown specifici, se necessario per la risoluzione dei problemi o risolvere i problemi di compatibilità con database remoti specifici.

Delegare l'accesso tramite visualizzazioni

È possibile delegare l'accesso ai dati remoti senza concedere privilegi diretti USE CONNECTION agli utenti eseguendo il wrapping della remote_query funzione in una visualizzazione. Questo approccio presenta i seguenti vantaggi:

• Controllo di accesso semplificato: concedere SELECT privilegi per la visualizzazione invece di gestire USE CONNECTION i privilegi.
• Sicurezza dei dati: controllare quali colonne e righe gli utenti possono accedere definendo la query di visualizzazione.
• Traccia derivazione: tenere traccia dell'accesso ai dati tramite la derivazione della visualizzazione anziché l'utilizzo diretto della connessione.

Per delegare l'accesso tramite una visualizzazione:

1. Creare una vista che chiama la funzione remote_query

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

2. Concedere SELECT privilegi per la visualizzazione a utenti o gruppi:

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

3. Gli utenti possono ora eseguire query sulla vista senza dover disporre dei USE CONNECTION privilegi:

   SELECT * FROM sales_data_view WHERE region = 'US';
   

Importante

Il proprietario della visualizzazione deve disporre USE CONNECTION del privilegio per la connessione. Quando gli utenti eseguono query sulla visualizzazione, il controllo di accesso alla connessione viene eseguito usando i privilegi del proprietario della visualizzazione, non i privilegi dell'utente che esegue query.

Esempi

Esecuzione di query di base

Eseguire una query su un database PostgreSQL.

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

Eseguire query su una tabella specifica

Eseguire direttamente una query su una tabella MySQL:

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

Oracle con nome del servizio

Eseguire query su un database Oracle:

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

Query BigQuery

Fai una query su 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)'
);

Query Snowflake

Query Snowflake:

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

Ottimizzazione delle prestazioni con il partizionamento

Recuperare i dati in parallelo da una tabella di SQL Server:

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

Combinare con le operazioni SQL di Databricks

Applicare filtri e trasformazioni aggiuntivi:

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;

Creare una visualizzazione per l'accesso delegato

Creare una vista che racchiude la funzione remote_query. Gli utenti con SELECT privilegi nella vista possono eseguire query sui dati senza dover disporre USE CONNECTION dei privilegi per la connessione sottostante:

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>;

Controllare il comportamento di pushdown

Quando si usa la funzione remote_query, Databricks può trasmettere operazioni aggiuntive al database remoto oltre alla query specificata. Questa funzionalità è utile quando si esegue una query su una vista che usa la remote_query funzione .

È possibile eseguire il push delle operazioni seguenti:

• Filtri: WHERE clausole applicate al risultato della query remota
• Proiezioni: selezione di colonne (SELECT colonne specifiche)
• Limite: LIMIT clausole per limitare il numero di righe restituite
• Offset: OFFSET clausole per saltare le righe
• Aggregazioni: funzioni di aggregazione come COUNT, SUM, AVG, MAX, MIN
• Top-N: combinazione di ORDER BY e LIMIT per le query top/bottom N

Il supporto per il pushdown varia in base alla sorgente dati. Per informazioni dettagliate, vedere la documentazione relativa al tipo di connessione specifico.

Disabilitare i pushdown specifici per la risoluzione dei problemi o la compatibilità:

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

Limitazioni

• Operazioni di sola lettura: la remote_query funzione supporta solo SELECT query. Le operazioni di modifica dei dati (INSERT, UPDATE, DELETE, MERGE), le operazioni DDL (CREATE, DROP, ALTER) e le stored procedure non sono supportate.

• Convalida delle query: la query specificata viene eseguita direttamente nel database remoto. Databricks convalida che la query è di sola lettura eseguendo l'ispezione dello schema, ma la sintassi e la convalida semantica vengono eseguite dal database remoto.

Risoluzione dei problemi

Errori di autorizzazione

Se viene visualizzato un errore di autorizzazione, verificare che:

1. Si dispone del USE CONNECTION privilegio per la connessione o del SELECT privilegio su una vista che incapsula la funzione.
2. Le credenziali nella connessione dispongono delle autorizzazioni appropriate per il database remoto.

Errore di esempio:

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

Risoluzione:

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

Parametri non supportati

Se viene visualizzato un errore relativo ai parametri non supportati, verificare di usare i parametri corretti per il tipo di connessione. Il messaggio di errore elenca i parametri consentiti.

Errore di esempio:

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'.

Soluzione: rimuovere il parametro non supportato e usare i parametri corretti per il tipo di connessione.

Operazioni DML non supportate

La remote_query funzione supporta solo query di sola SELECT lettura.

Errore di esempio:

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

Soluzione: Rimuovere qualsiasi istruzione INSERT, UPDATE, DELETE o DDL dalla query. Usare solo le istruzioni SELECT.

Risorse aggiuntive

• Che cos'è la federazione di interrogazioni?
• Gestire le connessioni per la Federazione Lakehouse
• Raccomandazioni sulle prestazioni di Lakehouse Federation
• Gestire i privilegi nel catalogo unity