Databricks JDBC-illesztőprogram (OSS)

Cikk
09/26/2024

Fontos

Ez az illesztőprogram nyilvános előzetes verzióban érhető el, és még nem érhető el nyílt forráskód.

A Databricks egy nyílt forráskód szoftveres (OSS) JDBC-illesztőt biztosít, amely lehetővé teszi az olyan eszközök csatlakoztatását, mint a DataGrip, a DBeaver és az SQL Workbench/J az Azure Databrickshez a Java Database Connectivity (JDBC) használatával, amely iparági szabvány az adatbázis-kezelő rendszerek eléréséhez.

Ez az illesztőprogram implementálta a JDBC API-kat, és olyan alapvető funkciókat biztosít, mint az OAuth, a Cloud Fetch és az olyan funkciók, mint a Unity Catalog kötetbetöltése. Natív lekérdezési módot futtat, és támogatja a natív paraméteres lekérdezést, és az Utasítás-végrehajtási API-k használatával futtatható, amely a lekérdezési eredmények hasznos adatmegőrzési funkcióját vagy a Thriftet biztosítja.

Ez a cikk a Databricks JDBC-illesztőprogram (OSS) telepítésével és használatával kapcsolatos információkat tartalmaz. A nem OSS Databricks JDBC-illesztőprogramról további információt a Databricks JDBC-illesztőprogramban talál.

Követelmények

A Databricks JDBC-illesztőprogram (OSS) használatához a következő követelményeknek kell teljesülniük:

Java Runtime Environment (JRE) 11.0 vagy újabb. A CI-tesztelés a JRE 11, 17 és 21 rendszeren támogatott.

Az illesztőprogram telepítése

A Databricks JDBC-illesztőprogram (OSS) a Maven-adattárban van közzétéve. A legújabb verzió a 0.9.1-oss.

Az illesztőprogram telepítéséhez tegye az alábbiak bármelyikét:

Maven-projektek esetén adja hozzá a következő függőséget a projekt fájljához, hogy utasítsa pom.xml a Mavent, hogy automatikusan töltse le a JDBC-illesztőprogramot a megadott verzióval:
```
<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-jdbc</artifactId>
  <version>0.9.1-oss</version>
  <scope>runtime</scope>
</dependency>
```
Gradle-projektek esetén adja hozzá a következő függőséget a projekt buildfájljához, hogy utasítsa a Gradle-t, hogy automatikusan töltse le a JDBC-illesztőt a megadott verzióval:
```
implementation 'com.databricks:databricks-jdbc:0.9.1-oss'
```

A többi projekttípus függőségi szintaxisának megtekintéséhez és a Databricks JDBC-illesztőprogram (OSS) legújabb verziószámának lekéréséhez tekintse meg a Maven-adattárat.

A kapcsolat URL-címének konfigurálása

Ha az Azure Databricks-munkaterülethez a JDBC-illesztővel szeretne csatlakozni, meg kell adnia egy JDBC kapcsolati URL-címet, amely különböző csatlakozási beállításokat tartalmaz, például az Azure Databricks-munkaterület kiszolgálójának állomásnevét, a számítási erőforrás beállításait és a munkaterülethez való csatlakozáshoz szükséges hitelesítési hitelesítő adatokat.

Ezeknek a tulajdonságoknak az értékét beállíthatja a JDBC kapcsolat URL-címén, beállíthatja és átadhatja őket a DriverManager.getConnection metódusnak, vagy mindkettő kombinációjának. A szolgáltató dokumentációjában megtudhatja, hogyan csatlakozhat a legjobban az adott alkalmazás, ügyfél, SDK, API vagy SQL-eszköz használatával.

A JDBC-kapcsolat URL-címének a következő formátumban kell lennie. A tulajdonságok nem érzékenyek a kis- és nagybetűkre.

jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];...

Másik lehetőségként adja meg a beállításokat az java.util.Properties osztály vagy a kombináció használatával:

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>";
Properties properties = new java.util.Properties();
properties.put("<property1>", "<value1");
properties.put("<property2>", "<value2");
// ...
Connection conn = DriverManager.getConnection(url, properties);

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];";
Connection conn = DriverManager.getConnection(url, "token", "12345678901234667890abcdabcd");

A kapcsolat URL-elemeit az alábbi táblázat ismerteti. További tulajdonságokról, beleértve a hitelesítési tulajdonságokat is, az alábbi szakaszokban talál további információkat. Az URL-elemek és a tulajdonságok nem érzékenyek a kis- és nagybetűkre.

URL-elem vagy tulajdonság	Leírás
`<server-hostname>`	Az Azure Databricks számítási erőforrás kiszolgálói állomásneve.
`<port>`	Az Azure Databricks számítási erőforrás portértéke. Az alapértelmezett érték `443`.
`<schema>`	A séma neve. Másik lehetőségként beállíthatja a tulajdonságot `ConnSchema` . Lásd: Kapcsolat tulajdonságai.
`httpPath`	Az Azure Databricks számítási erőforrás HTTP-elérési útvonalának értéke. Az összekötő a kapcsolat URL-címében megadott gazdagéphez és porthoz fűzve `httpPath` adja meg a HTTP-címet. A HTTP-címhez `http://localhost:10002/cliservice`való csatlakozáshoz például a következő kapcsolati URL-címet kell használnia: `jdbc:databricks://localhost:10002;httpPath=cliservice`

Egy Azure Databricks-fürt JDBC-kapcsolati URL-címének lekérése:

Jelentkezzen be az Azure Databricks munkaterületére.
Az oldalsávon kattintson a Számítás gombra, majd kattintson a célfürt nevére.
A Konfiguráció lapon bontsa ki a Speciális beállítások elemet.
Kattintson a JDBC/ODBC fülre.
Másolja a JDBC URL-címet JDBC kapcsolati URL-címként való használatra, vagy hozza létre az URL-címet a Kiszolgáló állomásneve, a Port és a HTTP Elérési út mezők értékeiből.

A Databricks SQL Warehouse JDBC-kapcsolati URL-címének lekérése:

Jelentkezzen be az Azure Databricks munkaterületére.
Az oldalsávon kattintson az SQL Warehouses elemre, majd a célraktár nevére.
Kattintson a Kapcsolat részletei fülre .
Másolja a JDBC URL-címet JDBC kapcsolati URL-címként való használatra, vagy hozza létre az URL-címet a Kiszolgáló állomásneve, a Port és a HTTP Elérési út mezők értékeiből.

Az illesztőprogram hitelesítése

A JDBC-illesztőprogram-kapcsolatot az alábbi hitelesítési mechanizmusok egyikével hitelesítheti:

OAuth user-to-machine (U2M) hitelesítés (ajánlott)
OAuth gépről gépre (M2M) hitelesítés
Azure Databricks személyes hozzáférési jogkivonat

OAuth user-to-machine (U2M) hitelesítés

A JDBC-illesztő támogatja az OAuth felhasználó–gép (U2M) hitelesítést a valós idejű emberi bejelentkezéshez, és hozzájárul a cél Databricks-felhasználói fiók hitelesítéséhez. Ezt böngészőalapú OAuth-hitelesítésnek is nevezik.

Az Azure Databricks létrehozta az OAuth-ügyfélazonosítót databricks-sql-jdbc az ügyfelek számára. Ez a JDBC-illesztőprogramban használt alapértelmezett OAuth-ügyfélazonosító is. Az OAuth U2M-hitelesítés konfigurálásához egyszerűen adja hozzá a következő tulajdonságokat a meglévő JDBC-kapcsolat URL-címéhez vagy java.util.Properties objektumához:

Tulajdonság	Érték
`AuthMech`	`11`
`Auth_Flow`	`2`

OAuth machine-to-machine (M2M) hitelesítés

A JDBC-illesztő támogatja az OAuth machine-to-machine (M2M) hitelesítést egy Azure Databricks szolgáltatásnév használatával. Ezt OAuth 2.0-ügyfél hitelesítő adatok hitelesítésének is nevezik. Lásd: Azure Databricks-hozzáférés hitelesítése szolgáltatásnévvel az OAuth (OAuth M2M) használatával.

Az OAuth M2M vagy az OAuth 2.0 ügyfél hitelesítő adatainak hitelesítésének konfigurálása:

Hozzon létre egy Microsoft Entra ID által felügyelt szolgáltatásnevet, majd rendelje hozzá az Azure Databricks-fiókokhoz és -munkaterületekhez. További részletekért lásd: Szolgáltatásnevek kezelése.

Fontos

A Databricks JDBC-illesztőprogram (OSS) támogatja az Azure Databricks OAuth-titkos kódokat az OAuth M2M vagy az OAuth 2.0 ügyfél hitelesítő adatainak hitelesítéséhez. A Microsoft Entra-azonosító titkos kulcsai nem támogatottak.
Hozzon létre egy Azure Databricks OAuth-titkos kulcsot a szolgáltatásnévhez. Ehhez tekintse meg az OAuth M2M-hitelesítéshez szükséges hozzáférési jogkivonatok manuális generálása és használata című témakört.
Adjon hozzáférést a szolgáltatásnévnek a fürthöz vagy a raktárhoz. Lásd: Számítási engedélyek vagy SQL-raktár kezelése.

Adja hozzá a következő tulajdonságokat a meglévő JDBC-kapcsolat URL-címéhez vagy java.util.Properties objektumához:

Tulajdonság	Érték
`AuthMech`	`11`
`Auth_Flow`	`1`
`OAuth2ClientID`	A szolgáltatásnév alkalmazás-(ügyfél-) azonosítójának értéke.
`OAuth2Secret`	A szolgáltatásnév Azure Databricks OAuth-titkos kódja. (A Microsoft Entra-azonosító titkos kulcsai nem támogatottak az OAuth M2M vagy az OAuth 2.0 ügyfél hitelesítő adatainak hitelesítéséhez.)

Azure Databricks személyes hozzáférési jogkivonat

A JDBC-illesztőprogram-kapcsolat Azure Databricks személyes hozzáférési jogkivonat használatával történő hitelesítéséhez adja hozzá a következő tulajdonságokat a JDBC-kapcsolat URL-címéhez vagy java.util.Properties objektumához:

Tulajdonság	Érték
`AuthMech`	`3`
`user`	Az érték `token`sztringként.
`PWD` vagy `password`	Az Azure Databricks személyes hozzáférési jogkivonatának értéke sztringként.

Kapcsolat tulajdonságai

A JDBC-illesztő az alábbi további kapcsolati tulajdonságokat támogatja. A tulajdonságok nem érzékenyek a kis- és nagybetűkre.

Tulajdonság	Alapértelmezett érték	Leírás
`AuthMech`	Kötelező	A hitelesítési mechanizmus, amely `3` meghatározza a mechanizmust, egy Azure Databricks személyes hozzáférési jogkivonat, és `11` meghatározza, hogy a mechanizmus OAuth 2.0-jogkivonat. Minden mechanizmushoz további tulajdonságokra van szükség. Lásd : Az illesztőprogram hitelesítése.
`Auth_Flow`	`0`	Az illesztőprogram-kapcsolat OAuth2 hitelesítési folyamata. Ez a tulajdonság akkor szükséges, ha `AuthMech` igen `11`.
`SSL`	`1`	Azt jelzi, hogy az összekötő SSL-kompatibilis szoftvercsatornán keresztül kommunikál-e a Spark-kiszolgálóval.
`ConnCatalog` vagy `catalog`	`SPARK`	A használni kívánt alapértelmezett katalógus neve.
`ConnSchema` vagy `schema`	`default`	A használni kívánt alapértelmezett séma neve. Ez megadható úgy, hogy az URL-címet lecseréli `<schema>` a használni kívánt séma nevére, vagy a `ConnSchema` tulajdonságot a használni kívánt séma nevére állítja.
`ProxyAuth`	`0`	Ha be van `1`állítva, az illesztőprogram a proxyhitelesítő felhasználót és a jelszót használja, amelyet az és `ProxyPwd`a `ProxyUID` .
`ProxyHost`	`null`	Egy sztring, amely a használni kívánt proxy gazdagép nevét jelöli, ha `UseProxy` az is be van állítva `1`.
`ProxyPort`	`null`	Egy egész szám, amely a használni kívánt proxyport számát jelzi, ha `UseProxy` a beállítás értéke is `1`.
`ProxyUID`	`null`	Egy sztring, amely a proxyhitelesítéshez használandó felhasználónevet jelöli, amikor `ProxyAuth` és `UseProxy` az is be van állítva `1`.
`ProxyPwd`	`null`	Olyan sztring, amely a proxyhitelesítéshez használandó jelszót jelöli, amikor `ProxyAuth` és `UseProxy` az is be van állítva `1`.
`UseProxy`	`0`	Ha be van `1`állítva, az illesztőprogram a megadott proxybeállításokat használja (például: `ProxyAuth`, `ProxyHost`, `ProxyPort`, `ProxyPwd`és `ProxyUID`).
`UseSystemProxy`	`0`	Ha be van `1`állítva, az illesztőprogram a rendszerszinten beállított proxybeállításokat használja. Ha a kapcsolati URL-címben további proxytulajdonságok vannak beállítva, ezek a további proxytulajdonságok felülbírálják a rendszerszinten beállítottakat.
`UseCFProxy`	`0`	Ha be van `1`állítva, az illesztőprogram a felhőbeolvasási proxy beállításait használja, ha meg van adva, ellenkező esetben használja a normál proxyt.
`CFProxyAuth`	`0`	Ha be van `1`állítva, az illesztőprogram a proxyhitelesítő felhasználót és a jelszót használja, amelyet az és `CFProxyPwd`a `CFProxyUID` .
`CFProxyHost`	`null`	Egy sztring, amely a használni kívánt proxy gazdagép nevét jelöli, ha `UseCFProxy` az is be van állítva `1`.
`CFProxyPort`	`null`	Egy egész szám, amely a használni kívánt proxyport számát jelzi, ha `UseCFProxy` a beállítás értéke is `1`.
`CFProxyUID`	`null`	Egy sztring, amely a proxyhitelesítéshez használandó felhasználónevet jelöli, amikor `CFProxyAuth` és `UseCFProxy` az is be van állítva `1`.
`CFProxyPwd`	`null`	Olyan sztring, amely a proxyhitelesítéshez használandó jelszót jelöli, amikor `CFProxyAuth` és `UseCFProxy` az is be van állítva `1`.
`AsyncExecPollInterval`	`200`	Az aszinkron lekérdezések végrehajtási állapotának lekérdezései közötti idő ezredmásodpercben. Az aszinkron azt a tényt jelenti, hogy a Lekérdezés Sparkon való végrehajtásához használt RPC-hívás aszinkron. Ez nem jelenti azt, hogy a JDBC aszinkron műveletek támogatottak.
`UserAgentEntry`	`browser`	A HTTP-kérelemben szerepeltetni kívánt user-agent bejegyzés. Ez az érték a következő formátumban van: `[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`0`	Azt jelzi, hogy a JDBC-illesztőnek a Thrift-ügyféllel kell-e csatlakoznia egy teljes célú fürthöz. Az alapértelmezett érték az SQL-raktárak esetében működik.

SQL-konfiguráció tulajdonságai

A JDBC-illesztő az alábbi SQL-konfigurációs tulajdonságokat támogatja. Ezeket a konfigurációs paraméterek is ismertetik. A tulajdonságok nem érzékenyek a kis- és nagybetűkre.

Tulajdonság	Alapértelmezett érték	Leírás
`ansi_mode`	`TRUE`	Az, hogy engedélyez-e szigorú ANSI SQL-viselkedést bizonyos függvényekhez és öntési szabályokhoz.
`enable_photo`	`TRUE`	A Photon vektorizált lekérdezési motor engedélyezése.
`legacy_time_parser_policy`	`EXCEPTION`	A dátumok és időbélyegek elemzéséhez és formázásához használt módszerek. Az érvényes értékek a következők `EXCEPTION`: , `LEGACY`és `CORRECTED`.
`max_file_partition_bytes`	`128m`	Az egyetlen partícióba csomagolható bájtok maximális száma fájlalapú forrásokból való olvasáskor. A beállítás bármilyen pozitív egész szám lehet, és opcionálisan tartalmazhat olyan mértéket, mint `b` a (bájt) `k` vagy `kb` a (1024 bájt).
`read_only_external_metastore`	`false`	Azt szabályozza, hogy egy külső metaadattár írásvédettként legyen-e kezelve.
`statement_timeout`	`172800`	Beállít egy SQL-utasítás időtúllépését 0 és 172800 másodperc között.
`timezone`	`UTC`	Állítsa be a helyi időzónát. Az űrlap `area/city`régióazonosítói, például Amerika/Los_Angeles vagy zónaeltolások formátumban (+\|-)HH, (+\|-)HH:mm vagy (+\|-)HH:mm:ss formátumban, például -08, +01:00 vagy -13:33:33 formátumban. `UTC` Emellett a +00:00 aliasként is támogatott
`use_cached_result`	`true`	Az, hogy a Databricks SQL lehetőség szerint gyorsítótárazza-e és használja-e újra az eredményeket.

Naplózási tulajdonságok

A JDBC-illesztő az alábbi naplózási tulajdonságokat támogatja. A tulajdonságok nem érzékenyek a kis- és nagybetűkre.

Tulajdonság	Alapértelmezett érték	Leírás
`LogLevel`	`4`	A naplózási szint, amely 0 és 6 között van: - 0: Tiltsa le az összes naplózást. - 1: Engedélyezze a FATAL szintű naplózást, amely nagyon súlyos hibaeseményeket naplóz, amelyek az összekötő megszakításához vezetnek. - 2: Engedélyezze a naplózást a HIBA szinten, amely naplózza azokat a hibaeseményeket, amelyek továbbra is lehetővé teszik az összekötő futtatását. - 3: Engedélyezze a naplózást a FIGYELMEZTETÉS szinten, amely naplózza azokat az eseményeket, amelyek hiba esetén hibát okozhatnak, ha nem történik meg a művelet. - 4: Engedélyezze a naplózást az INFO szinten, amely naplózza az összekötő állapotát leíró általános információkat. - 5: Engedélyezze a naplózást a DEBUG szinten, amely naplózza az összekötő hibakereséséhez hasznos részletes információkat. - 6: Engedélyezze a nyomkövetési szintű naplózást, amely minden összekötői tevékenységet naplóz. Ezzel a tulajdonsággel engedélyezheti vagy letilthatja a naplózást az összekötőben, és megadhatja a naplófájlokban található részletesség mértékét.
`LogPath`	`logs/application.log`	Annak a mappának a teljes elérési útja, amelyben az összekötő naplófájlokat ment, amikor engedélyezve van a naplózás, sztringként. Ha az `LogPath` érték érvénytelen, akkor az összekötő elküldi a naplózott adatokat a standard kimeneti streamnek (System.out).

Példa: Lekérdezés futtatása a JDBC-illesztőprogram használatával

Az alábbi példa bemutatja, hogyan futtathat Databricks SQL-lekérdezést a JDBC-illesztővel egy Azure Databricks számítási erőforrás használatával.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.util.Properties;

public class DatabricksJDBCExample {

    public static void main(String[] args) {

        Class.forName("com.databricks.client.jdbc.Driver");

        // Set JDBC URL properties
        String jdbcUrl = "jdbc:databricks://dbc-a1b2345c-d6e7.cloud.databricks.com:443";
        Properties connectionProperties = new Properties();
        connectionProperties.put("httpPath", "sql/protocolv1/o/123456780012345/0123-123450-z000pi22");
        connectionProperties.put("ssl", "1");

        // Set authentication properties (personal access token)
        connectionProperties.put("AuthMech", "3");
        connectionProperties.put("user", "token");
        connectionProperties.put("password", "12345678901234667890abcdabcd");

        // Set logging properties
        connectionProperties.put("logPath", "logs/myapplication.log");

        // Establish connection and execute query
        try (Connection connection = DriverManager.getConnection(jdbcUrl, connectionProperties);
             Statement statement = connection.createStatement();
             ResultSet resultSet = statement.executeQuery("SELECT * FROM samples.nyctaxi.trips")) {

            // Get metadata and column names
            ResultSetMetaData metaData = resultSet.getMetaData();
            String[] columns = new String[metaData.getColumnCount()];
            for (int i = 0; i < columns.length; i++) {
                columns[i] = metaData.getColumnName(i + 1);
            }

            // Process and print the result set
            while (resultSet.next()) {
                System.out.print("Row " + resultSet.getRow() + "=[");
                for (int i = 0; i < columns.length; i++) {
                    if (i != 0) {
                        System.out.print(", ");
                    }
                    System.out.print(columns[i] + "='" + resultSet.getObject(i + 1) + "'");
                }
                System.out.println("]");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Megosztás a következőn keresztül: