Federazione dei cataloghi della Palantir Foundry

La federazione del catalogo Palantir Foundry permette a Unity Catalog di leggere direttamente le tabelle Iceberg di Palantir Foundry dall'archiviazione cloud.

Con la federazione dei cataloghi, Unity Catalog accede alle tabelle Iceberg di Palantir Foundry nell'archiviazione cloud e la query viene eseguita interamente nelle risorse di calcolo di Azure Databricks. I team dati possono scoprire, governare e interrogare i dati Palantir Foundry da Azure Databricks senza costruire pipeline ETL. L'accesso ai dati è di sola lettura.

Prima di iniziare

Esamina i seguenti requisiti prima di creare la federazione del catalogo Palantir Foundry.

Requisiti dell'area di lavoro:

• L'area di lavoro deve essere abilitata per Unity Catalog. Consulta Introduzione al Catalogo Unity.
• Poiché questa funzione è presente in Anteprima Pubblica, un amministratore dello spazio di lavoro deve abilitarla dalla pagina Anteprime dello Spazio di Lavoro . Vedere Gestire le anteprime a livello di area di lavoro.

Requisiti di calcolo:

• Azure Databricks compute deve utilizzare Databricks Runtime 18 o superiore.
• I warehouse SQL devono essere pro o serverless.
• I cluster dedicati (precedentemente cluster single-user) non sono supportati.

Requisiti di rete:

• Gli intervalli IP in uscita di Azure Databricks, sia per il piano di controllo sia per il piano dati, devono essere inseriti nell'elenco degli elementi consentiti in Palantir Foundry. Vedi Configurazione dell'ingresso in Foundry e Consigli di rete per la federazione Lakehouse.

Autorizzazioni necessarie:

• Per creare una connessione, è necessario essere amministratore del metastore o un utente con il privilegio CREATE CONNECTION nel metastore Unity Catalog collegato all'area di lavoro.
• Per creare un catalogo esterno, devi disporre dell'autorizzazione CREATE CATALOG nel metastore. Devi anche possedere la connessione o avere il CREATE FOREIGN CATALOG privilegio su di essa.

Requisiti della Palantir Foundry:

• I tavoli della Palantir Foundry devono essere tavoli Iceberg.
• Un'applicazione di terze parti di Palantir Foundry per l'autenticazione. Configura l'applicazione secondo il metodo di autenticazione:
  • OAuth da utente a macchina (U2M):
    • L'applicazione deve supportare gli ambiti api:iceberg-read e offline_access.
    • L'applicazione deve avere configurato l'URL https://<databricks-workspace-url>/login/oauth/lakehousefederation.html di reindirizzamento OAuth, dove <databricks-workspace-url> è il nome host del tuo workspace.
    • L'utente che autentica la connessione deve avere accesso alla cartella radice federata.
  • OAuth da macchina a macchina (M2M):
    • La domanda deve supportare la concessione delle credenziali del cliente e l'ambito di api:iceberg-read applicazione.
    • L'utente del servizio dietro l'applicazione deve avere accesso alla cartella radice federata.

Passo 1: Crea una connessione

Permessi richiesti: amministratore del Metastore o utente con il CREATE CONNECTION privilegio.

Una connessione specifica un percorso e le credenziali per accedere a un sistema esterno. Identifica l'host Palantir Foundry e le credenziali con cui autenticarsi, non la cartella da federare. Seleziona la cartella radice quando crei il catalogo estero nel Passo 2: Crea un catalogo estero.

La federazione Palantir Foundry supporta due metodi di autenticazione, descritti nelle seguenti sottosezioni. Entrambi richiedono un'applicazione di terze parti di Palantir Foundry.

OAuth da utente a macchina (U2M)

Con OAuth User to Machine (U2M), il Catalogo Unity accede a Foundry come utente che autentica la connessione. Crea questa connessione usando Catalog Explorer. Questo metodo non può essere configurato usando SQL, perché il flusso di accesso OAuth richiede l'interfaccia utente.

1. Nell'area di lavoro di Azure Databricks fare clic Catalogo.
2. Nella parte superiore del riquadro Catalogo fare clic Aggiungi e selezionare Crea una connessione dal menu.
3. Nella pagina Elementi di base della connessione della Procedura guidata di configurazione della connessione, inserisci un nome di connessione facile da usare.
4. Seleziona un tipo di connessione di Palantir Foundry e un tipo di autenticazione di OAuth da utente a macchina, poi clicca su Next.
5. Nella pagina Autenticazione, inserisci l’host della tua istanza di Palantir Foundry, ad esempio your-company.palantirfoundry.com, e completa la procedura di accesso OAuth per autorizzare la connessione.
6. (Facoltativo) Aggiungere un commento.
7. Fai clic su Crea connessione.

OAuth Machine to Machine (M2M)

Con OAuth Machine to Machine (M2M), il Catalogo Unity accede a Foundry come utente del servizio dietro l'applicazione di terze parti, utilizzando la concessione delle credenziali del cliente. Crea questa connessione usando Catalog Explorer o il comando SQL CREATE CONNECTION in un notebook Azure Databricks o nell'editor di query SQL di Databricks.

Esploratore di cataloghi

1. Nell'area di lavoro di Azure Databricks fare clic Catalogo.
2. Nella parte superiore del riquadro Catalogo fare clic Aggiungi e selezionare Crea una connessione dal menu.
3. Nella pagina Elementi di base della connessione della Procedura guidata di configurazione della connessione, inserisci un nome di connessione facile da usare.
4. Seleziona un tipo di connessione di Palantir Foundry e un tipo di autenticazione di OAuth Machine to Machine, poi clicca su Next.
5. Nella pagina Autenticazione immettere quanto segue:
   • Host: Il nome host della tua istanza di Palantir Foundry, ad esempio your-company.palantirfoundry.com.
   • ID cliente: L'ID client della tua applicazione di terze parti Palantir Foundry.
   • Segreto cliente: Il segreto cliente della tua applicazione terza Palantir Foundry.
6. (Facoltativo) Aggiungere un commento.
7. Fai clic su Crea connessione.

SQL

Eseguire il seguente comando in un notebook o nell'editor di query SQL di Databricks. Sostituisci i valori segnaposto:

• <connection-name>: Nome per la connessione in Azure Databricks.
• <palantir-host>: L'hostname della tua istanza di Palantir Foundry, per esempio your-company.palantirfoundry.com.
• <client-id>: L'ID cliente della tua applicazione di terze parti Palantir Foundry.
• <secret-scope> e <secret-key>: L'ambito e la chiave segrete che memorizzano il client segreto dalla tua applicazione di terze parti Palantir Foundry.

CREATE CONNECTION <connection-name> TYPE PALANTIR
OPTIONS (
  host '<palantir-host>',
  client_id '<client-id>',
  client_secret secret('<secret-scope>','<secret-key>')
);

Databricks raccomanda di usare i segreti invece delle stringhe di testo in chiaro per valori sensibili come il client secret. Per informazioni sulla configurazione dei segreti, vedere Gestione dei segreti.

Passo 2: Crea un catalogo straniero

Permessi richiesti: CREATE CATALOG permesso sul metastore e proprietà della connessione o privilegio CREATE FOREIGN CATALOG sulla connessione.

Un catalogo straniero rispecchia la tua cartella radice Palantir Foundry così puoi interrogare e gestire l'accesso alle sue tabelle usando Azure Databricks e Unity Catalog. Per creare un catalogo straniero, usa la connessione che hai creato nel Passo 1: Crea una connessione.

Crea un catalogo esterno usando Catalog Explorer o il comando SQL CREATE FOREIGN CATALOG in un notebook di Azure Databricks o nell'editor di query di Databricks SQL.

Esploratore di cataloghi

1. Nell'area di lavoro Azure Databricks, fare clic su Catalogo per aprire Esplora Catalogo.
2. Nella parte superiore del riquadro Catalogo fare clic Aggiungi e selezionare Aggiungi un catalogo dal menu.
3. Immettere un nome catalogo e selezionare un tipo di catalogo di esterno.
4. Seleziona la connessione che hai creato nel Passo 1: Crea una connessione dal menu a tendina.
5. Per la cartella Root, inserisci la cartella Palantir Foundry dove il Catalogo Unity cerca schemi e tabelle da federare, ad /space-name/project-name/folder-nameesempio . Vedi mappatura di cartelle radici e namespace.
6. Nel campo Posizione Storage , specifica una posizione di archiviazione cloud scrivibile che memorizzi i metadati per le tabelle Iceberg in questo catalogo. L'account del servizio gestito di Azure Databricks deve avere accesso in lettura e scrittura a esso. Questa posizione può essere qualsiasi secchio di stoccaggio e non deve necessariamente essere collegata ai secchi da tavola.
7. Fare clic su Crea Catalogo.
8. Assegna l'accesso allo spazio di lavoro, un proprietario e i privilegi come richiesto.

SQL

Eseguire il seguente comando in un notebook o nell'editor di query SQL di Databricks. Gli elementi tra parentesi sono facoltativi. Sostituisci i valori segnaposto:

• <catalog-name>: Nome per il catalogo in Azure Databricks.
• <connection-name>: Il nome della connessione che hai creato nel Passo 1: Crea una connessione.
• <root-folder>: La cartella Palantir Foundry dove Unity Catalog cerca schemi e tabelle da federare, ad /space-name/project-name/folder-nameesempio . Vedi mappatura di cartelle radici e namespace.
• <storage-location>: Una posizione di archiviazione cloud scrivibile che memorizza i metadati delle tabelle Iceberg in questo catalogo. L'account del servizio gestito di Azure Databricks deve disporre di accesso in lettura e scrittura ad esso. Questa posizione può essere qualsiasi secchio di stoccaggio e non deve necessariamente essere collegata ai secchi da tavola.

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name>
USING CONNECTION <connection-name>
OPTIONS (
  root_folder '<root-folder>',
  storage_root '<storage-location>'
);

Unity Catalog scopre le cartelle e le tabelle sotto la cartella root:

• Le sottocartelle di Palantir Foundry diventano schemi di Unity Catalog.
• Le tabelle Iceberg di Palantir Foundry diventano tabelle esterne di Unity Catalog.

Passo 3: Concedere permessi e consultare il catalogo

Dopo aver configurato la federazione del catalogo, gli utenti devono avere i permessi appropriati del Catalogo Unity per accedere alle tabelle federate:

• Tutti gli utenti necessitano delle autorizzazioni USE CATALOG per il catalogo e USE SCHEMA per lo schema, rispettivamente.
• Per leggere da una tabella federata, gli utenti hanno bisogno del SELECT permesso.

Per altre informazioni sui privilegi del catalogo Unity e su come concederli, vedere Gestire i privilegi in Unity Catalog.

Dopo aver concesso i permessi, gli utenti possono interrogare le tabelle estere da Azure Databricks:

SELECT * FROM <catalog-name>.<schema>.<table>;

Mappatura delle cartelle radice e dello spazio dei nomi

Quando crei un catalogo straniero, specifichi una cartella Palantir Foundry (ad esempio /space-name/project-name/folder-name) come radice della federazione. Unity Catalog mappa le sue sottocartelle a schemi estranei e le tabelle Iceberg in quelle sottocartelle diventano tabelle estranee nel Unity Catalog. Questo mappa la gerarchia più profonda della Foundry su una struttura coerente a tre livelli.

Ad esempio, se federi la cartella /sales/ordersradice :

Palantir Foundry object                       Unity Catalog object
────────────────────────────────────────────  ──────────────────────────────────────────────────
sales                    (Foundry Space)
└── orders               (Foundry Project)    <foreign-catalog>                        (Catalog)
    └── shipments        (Foundry Folder)     <foreign-catalog>.shipments              (Schema)
        └── line_items   (Iceberg Table)      <foreign-catalog>.shipments.line_items   (Table)

La cartella che federi diventa il catalogo, ogni sottocartella diventa uno schema, e ogni tabella Iceberg diventa una tabella estranea.

Limitations

La Federazione dei cataloghi Palantir Foundry presenta le seguenti limitazioni:

• La federazione Palantir Foundry può accedere solo ai tavoli Iceberg. Le visualizzazioni non sono supportate.
• La connettività privata al catalogo di Palantir Foundry non è supportata.
• I nomi degli schemi e delle tabelle seguono le limitazioni standard di denominazione del Catalogo Unity. Azure Databricks non supporta nomi che contengono un punto (.), spazio ( ) o barra avanzata (/). Vedere Requisiti di denominazione degli oggetti proteggibili.
• Una cartella root che è una cartella a livello singolo in Foundry (una cartella che contiene solo tabelle e nessuna sottocartella da mappare agli schemi) non presenta schemi o tabelle. La federazione richiede almeno un livello di sottocartelle da mappare agli schemi di Unity Catalog.

Vedi Limitazioni per le limitazioni legate agli iceberg.

Troubleshooting

La sezione seguente descrive gli errori comuni e le loro risoluzioni.

Failed to create request URI o cartella radice non valida

• L'opzione root_folder non corrisponde al percorso di cartella nella tua istanza di Palantir Foundry. Verifica il percorso.

L'autenticazione è fallita durante la creazione della connessione

Le credenziali di applicazione di terze parti Palantir Foundry non sono valide, oppure l'identità autenticante non ha accesso alla cartella radice federata. Conferma l'ID client e il secret (per OAuth M2M) o ri-autentica (per OAuth U2M) e verifica che l'identità abbia il permesso sulla cartella root. Vedere Prima di iniziare.