Eseguire query federate su Oracle

Questa pagina descrive come configurare Lakehouse Federation per eseguire query federate sui dati Oracle non gestiti da Azure Databricks. Per altre informazioni sulla federazione lakehouse, vedere Connettersi a database e cataloghi esterni

Per connettersi al database Oracle usando Lakehouse Federation, è necessario creare quanto segue nel metastore del catalogo Unity di Azure Databricks (le aree di lavoro create dopo il 9 novembre 2023 hanno già effettuato automaticamente il provisioning di un metastore del catalogo Unity):

• Una connessione al database Oracle.
• Un catalogo esterno che rispecchia il database Oracle in Unity Catalog in modo da poter usare la sintassi delle query di Unity Catalog e gli strumenti di governance dei dati per gestire l'accesso utente di Azure Databricks al database.

Requirements

Prima di iniziare, verificare di soddisfare i requisiti in questa sezione.

Requisiti di Databricks

Requisiti dell'area di lavoro:

• Area di lavoro attivata per il catalogo Unity. Le aree di lavoro create dopo il 9 novembre 2023 sono abilitate automaticamente per il catalogo Unity, compreso il provisioning automatico del metastore. Non è necessario creare manualmente un metastore a meno che l'area di lavoro non precedi l'abilitazione automatica e non sia stata abilitata per Unity Catalog. Consulta Introduzione al Catalogo Unity.

Requisiti di calcolo:

• Connettività di rete dalla risorsa di calcolo ai sistemi di database di destinazione. Consultare Raccomandazioni per la rete per Lakehouse Federation.
• Il calcolo di Azure Databricks deve usare Databricks Runtime 16.1 o versione successiva e la modalità di accesso Standard o Dedicato .
• I warehouse SQL devono essere pro o serverless e devono usare la versione 2024.50 o successiva.

Autorizzazioni necessarie:

• Per creare una connessione, è necessario essere un amministratore del metastore o un utente con il privilegio CREATE CONNECTION nel metastore del catalogo Unity collegato all'area di lavoro. Nelle aree di lavoro abilitate automaticamente per Unity Catalog gli amministratori dell'area di lavoro hanno il CREATE CONNECTION privilegio per impostazione predefinita.
• Per creare un catalogo esterno, è necessario disporre dell'autorizzazione CREATE CATALOG per il metastore e essere il proprietario della connessione o disporre del privilegio CREATE FOREIGN CATALOG per la connessione. Nelle aree di lavoro abilitate automaticamente per Unity Catalog gli amministratori dell'area di lavoro hanno il CREATE CATALOG privilegio per impostazione predefinita.

In ogni sezione basata su attività che segue vengono specificati requisiti di autorizzazione aggiuntivi.

Requisiti Oracle

Per le connessioni che usano La crittografia di rete nativa, è necessario abilitare almeno il livello NNE lato server.ACCEPTED Vedere Configuring Network Data Encryption nella documentazione di Oracle. Questo non si applica alle connessioni che usano TLS.

Creare una connessione di Azure Databricks

Una connessione specifica un percorso e le credenziali per l'accesso a un sistema di database esterno. Per creare una connessione, è possibile usare Esplora cataloghi o il comando SQL CREATE CONNECTION in un notebook di Azure Databricks o nell'editor di query SQL di Databricks.

Autorizzazioni necessarie: amministratore o utente del metastore con il privilegio CREATE CONNECTION.

Esploratore di cataloghi

1. Nell'area di lavoro di Azure Databricks fare clic Catalogo.
2. Fare clic sull'icona , quindi su Connetti, e infine su Connessioni.
3. Fare clic sul pulsante Crea connessione .
4. Nella pagina Connessione di base della Configurazione guidata connessione, immettere un descrittivo nome di connessione .
5. Selezionare un tipo di connessione di Oracle.
6. (Facoltativo) Aggiungere un commento.
7. Fare clic su Avanti.
8. Nella pagina Autenticazione, inserisci quanto segue per l'istanza di Oracle:
   • Host: Ad esempio, oracle-demo.123456.rds.amazonaws.com
   • porta: ad esempio, 1521
   • Utente: per esempio, oracle_user
   • password: ad esempio, password123
   • Protocollo di crittografia: Native Network Encryption (impostazione predefinita) o Transport Layer Security
   • Certificato server fornito dall'utente: facoltativo. Il certificato pubblico codificato in PEM della tua istanza Oracle, usato per verificare l'identità del server durante la stretta TLS. Forniscilo quando il tuo server presenta un certificato di un'autorità di certificazione privata o interna che non si trova nel trust store predefinito. Un certificato server fornito dall'utente richiede il protocollo di crittografiaTransport Layer Security. La verifica del nome host viene eseguita come parte dell'handshake TLS. La connessione fallisce se il nome host sul certificato non corrisponde a quello richiesto.
   • Fuso orario come area geografica: Opzionale. Abilitata per impostazione predefinita. Controlla se la connessione riporta il fuso orario della sessione a Oracle come regione nominata (abilitata) o come offset UTC fisso (disabilitato). Disabilitalo solo per aggirare l'errore timezone region not found . Vedi ORA-01882: regione del fuso orario non trovata.
9. Fare clic su Crea connessione.
10. Nella pagina informazioni di base del catalogo immettere un nome per il catalogo esterno. Un catalogo esterno esegue il mirroring di un database in un sistema di dati esterno in modo da poter eseguire query e gestire l'accesso ai dati in tale database usando Azure Databricks e Unity Catalog.
11. (Facoltativo) Fare clic su Test di connessione per verificare che funzioni.
12. Fare clic su Crea il catalogo.
13. Nella pagina Access selezionare le aree di lavoro in cui gli utenti possono accedere al catalogo creato. È possibile selezionare Tutte le aree di lavoro hanno accessooppure fare clic su Assegna alle aree di lavoro, selezionare le aree di lavoro e quindi fare clic su Assegna.
14. Modificare il Proprietario che sarà in grado di gestire l'accesso a tutti gli oggetti nel catalogo. Inizia a digitare un principale nella casella di testo e quindi fai clic sul principale nei risultati visualizzati.
15. Concedi privilegi sul catalogo. Fare clic su Concedi:
    1. Specificare il Principals che avranno accesso agli oggetti nel catalogo. Inizia a digitare un principale nella casella di testo e quindi fai clic sul principale nei risultati visualizzati.
    2. Selezionare i set di impostazioni Privilegi da concedere a ogni soggetto. Tutti gli utenti dell'account vengono concessi BROWSE per impostazione predefinita.
       • Selezionare Data Reader dal menu a tendina per concedere read privilegi sugli oggetti nel catalogo.
       • Selezionare Editor dati dal menu a discesa per concedere i privilegi read e modify sugli oggetti nel catalogo.
       • Selezionare manualmente i privilegi da concedere.
    3. Fare clic su "Concedi".
16. Fare clic su Avanti.
17. Nella pagina metadati, specificare le coppie chiave-valore dei tag. Per ulteriori informazioni, vedere Applicare tag agli oggetti sicurizzabili del catalogo Unity.
18. (Facoltativo) Aggiungere un commento.
19. Fare clic su Salva.

SQL

Eseguire il comando seguente in un notebook o nell'editor di query SQL di Databricks:

CREATE CONNECTION <connection-name> TYPE oracle
OPTIONS (
  host '<hostname>',
  port '<port>',
  user '<user>',
  password '<password>',
  encryption_protocol '<protocol>', -- optional
  timezone_as_region '<true-or-false>' -- optional
);

timezone_as_region controlla se la connessione riporta il fuso orario della sessione a Oracle come una regione nominata come America/Los_Angeles (true, il predefinito) o come un offset UTC fisso come -08:00 (false). Impostalo su false solo per aggirare l'errore timezone region not found . Vedi ORA-01882: regione del fuso orario non trovata.

Databricks consiglia di usare Azure Databricks segreti anziché stringhe di testo non crittografato per valori sensibili come le credenziali. Per esempio:

CREATE CONNECTION <connection-name> TYPE oracle
OPTIONS (
  host '<hostname>',
  port '<port>',
  user secret ('<secret-scope>','<secret-key-user>'),
  password secret ('<secret-scope>','<secret-key-password>'),
  encryption_protocol '<protocol>' -- optional
)

Per verificare l'identità del server durante la stretta TLS (ad esempio, quando il tuo server Oracle presenta un certificato da un'autorità di certificazione privata o interna che non si trova nel trust store predefinito), passa il certificato PEM del server nell'opzione userProvidedServerCertificate . Un certificato server fornito dall'utente richiede encryption_protocol di essere impostato su TLS.

CREATE CONNECTION <connection-name> TYPE oracle
OPTIONS (
  host '<hostname>',
  port '<port>',
  user secret ('<secret-scope>','<secret-key-user>'),
  password secret ('<secret-scope>','<secret-key-password>'),
  encryption_protocol 'TLS',
  userProvidedServerCertificate '<pem-encoded-certificate>'
)

Se è necessario usare stringhe di testo non crittografato nei comandi SQL del notebook, evitare di troncare la stringa eliminando caratteri speciali come $ con \. Ad esempio: \$.

Per informazioni sulla configurazione dei segreti, vedere Gestione dei segreti.

Creare un catalogo esterno

Un catalogo esterno esegue il mirroring di un database in un sistema di dati esterno in modo da poter eseguire query e gestire l'accesso ai dati in tale database usando Azure Databricks e Unity Catalog. Per creare un catalogo esterno, si utilizza una connessione all'origine dati già definita.

Per creare un catalogo esterno, è possibile usare Esplora cataloghi o il comando SQL CREATE FOREIGN CATALOG in un notebook di Azure Databricks o nell'editor di query SQL. È anche possibile usare l'API REST di Databricks o l'interfaccia della riga di comando di Databricks per creare un catalogo. Consulta POST /api/2.1/unity-catalog/catalogs e comandi Unity Catalog.

Autorizzazioni necessarie: l'autorizzazioneCREATE CATALOG sul metastore e la proprietà della connessione o il privilegio CREATE FOREIGN CATALOG sulla connessione.

Esploratore di cataloghi

1. Nell'area di lavoro di Azure Databricks fare clic Catalogo per aprire Esplora cataloghi.

2. Nella parte superiore del riquadro catalogo fare clic sull'icona Aggiungi o più Icona Aggiungi e selezionare Aggiungi un catalogo dal menu.

   In alternativa, nella pagina accesso rapido, fare clic sul pulsante Cataloghi e quindi sul pulsante Crea catalogo.

3. Seguire le istruzioni per creare cataloghi esteri in Creare cataloghi.

SQL

Eseguire il comando SQL seguente in un notebook o in un editor di query SQL. Gli elementi tra parentesi quadrate sono opzionali. Sostituire i valori segnaposto:

• <catalog-name>: Nome del catalogo in Azure Databricks.
• <connection-name>: oggetto connessione che specifica l'origine dati, il percorso e le credenziali di accesso.
• <service-name>: nome del servizio che vuoi rispecchiare come catalogo in Azure Databricks.

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
OPTIONS (service_name '<service-name>');

Supporto per pushdown

Nella tabella seguente sono elencate le operazioni di pushdown supportate per Oracle, insieme alle risorse di calcolo necessarie per ognuna.

Automazione a pila	Calcolo supportato
Aggregates	Tutti i calcoli
Operatori aritmetici (ad esempio +, -, *, %, /) - non supportato se ANSI è disabilitato	Tutti i calcoli
Operatori booleani (ad esempio =, <=>, <, <=, >, >=)	Tutti i calcoli
Contiene, Inizia con, Termina con	Tutti i calcoli
Filters	Tutti i calcoli
Limit	Tutti i calcoli
Funzioni matematiche (ABS, FLOOR - supporto parziale, solo espressioni di filtro)	Tutti i calcoli
Funzioni varie (ad esempio Alias, Cast, SortOrder - supporto parziale, solo espressioni di filtro)	Tutti i calcoli
Offset	Tutti i calcoli
Projections	Tutti i calcoli
Ordinamento, quando utilizzato con limitazione	Tutti i calcoli
Funzioni di stringa (UPPER, LOWER, CHAR_LENGTH, TRIM, RTRIM, LTRIM, CONCAT, RPAD, LPAD - supporto parziale, solo espressioni di filtro)	Tutti i calcoli
Joins	Databricks Runtime 17.2 e versioni successive e calcolo di SQL Warehouse. Questo pushdown è in Anteprima pubblica; attiva l'opzione Join Pushdown per le query federate nella pagina Anteprime.
Funzioni finestra	Non supportato

Mapping dei tipi di dati

Quando si legge da Oracle a Spark, i tipi di dati vengono mappati nel modo seguente:

* DATE e TIMESTAMP vengono mappati a Spark TimestampType se spark.sql.timestampType = TIMESTAMP_LTZ (impostazione predefinita). Sono associati a TimestampNTZType se spark.sql.timestampType = TIMESTAMP_NTZ.

** NUMBER senza specificare la precisione verrà eseguito il mapping a DecimalType(38, 10) perché non è disponibile alcun supporto per un decimale a virgola mobile puro in Spark.

Troubleshooting

ORA-01882: zona del fuso orario non trovata

Quando ti connetti alle istanze Oracle 11.2.0.3.0 e successive che non hanno un valore di fuso orario di Etc/UTC, la connessione può fallire con l'errore ORA-01882: timezone region not found. Questo avviene quando il server Oracle non riconosce la regione del fuso orario nominata che la connessione segnala al momento dell'accesso.

Per risolvere questo errore, Databricks raccomanda quanto segue, in ordine:

1. Aggiorna i file dei fusi orari sul server Oracle in modo che riconosca il nome della regione. Questa è la soluzione preferita e permanente. Vedere Supporto Oracle - ORA-01882.
2. Se non puoi aggiornare il server Oracle, imposta l'opzione timezone_as_region di connessione su false. La connessione riporta quindi un offset UTC fisso invece di un nome della regione, evitando così l'errore. Un offset fisso non tiene conto delle variazioni stagionali dell'orario, quindi i valori TIMESTAMP WITH LOCAL TIME ZONE non vengono regolati per l'ora legale.

License

Il driver Oracle e altri file JAR Oracle necessari sono regolati dalla licenza FDHUT senza clic.

Risorse aggiuntive

• Partecipare al pushdown in Lakehouse Federation
• Raccomandazioni di rete per Lakehouse Federation
• Eseguire query su database esterni utilizzando la funzione remote_query