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


Databricks JDBC-illesztőprogram (OSS)

Fontos

Ez az illesztőprogram nyilvános előzetes verziójú érhető el, és nyílt forráskódúként lesz elérhető, amikor általánosan elérhetővé válik.

Az illesztőprogram legújabb verziója, a Databricks JDBC (OSS) lehetővé teszi olyan eszközök csatlakoztatását, mint DataGrip, DBeaver, és 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.

Feljegyzés

A JDK 16-ban bekövetkezett olyan változás következtében, amely kompatibilitási problémát okozott a JDBC-illesztőprogram által használt Apache Arrow-kódtárral, futásidejű hibák léphetnek fel a JDBC-illesztő JDK 16-os vagy újabb JDK-val való használatakor. A hibák elkerülése érdekében indítsa újra az alkalmazást vagy az illesztőprogramot a következő JVM parancsbeállítással:

--add-opens=java.base/java.nio=org.apache.arrow.memory.core ALL-UNNAMED

Az illesztőprogram telepítése

A Databricks JDBC-illesztőprogram (OSS) a Maven-adattárban van közzétéve.

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.6-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.6-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ár.

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 ConnSchema tulajdonságot. 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/cliservicevaló 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:

  1. Jelentkezzen be az Azure Databricks munkaterületére.
  2. Az oldalsávon kattintson a Számítás gombra, majd kattintson a célfürt nevére.
  3. A Konfiguráció lapon bontsa ki a Speciális beállítások elemet.
  4. Kattintson a JDBC/ODBC fülre.
  5. 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ó gazdagépnevének, portés HTTP-elérési út mezőinek értékeiből.

A Databricks SQL raktárJDBC-kapcsolati URL-címének lekérése:

  1. Jelentkezzen be az Azure Databricks munkaterületére.
  2. Az oldalsávon kattintson az SQL Warehouses elemre, majd a célraktár nevére.
  3. Kattintson a Kapcsolat részletei fülre .
  4. 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ó gazdagépnevének, portés HTTP-elérési út mezőinek é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

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. Ez más néven OAuth 2.0 ügyfél hitelesítő. Lásd: Felügyelet nélküli hozzáférés engedélyezése az Azure Databricks-erőforrásokhoz egy szolgáltatásfelelős segítségével, az OAuthhasználatával.

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

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

  2. Hozzon létre egy Azure Databricks OAuth-titkos kulcsot a szolgáltatásnévhez. Ehhez lásd: Hozzáférési jogkivonatok manuális létrehozása és használata az OAuth szolgáltatásnév-hitelesítéshez.

  3. 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 tokensztringké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, amelynél a 3 jelöli, hogy a mechanizmus egy Azure Databricks személyes hozzáférési jogkivonat, és a 11 jelzi, hogy a mechanizmus az OAuth 2.0 jogkivonatokat használja. 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 úgy adható meg, hogy az URL-címben szereplő <schema> lecseréli a használni kívánt séma nevére, vagy ha a ConnSchema tulajdonságot a használni kívánt séma nevére állítja.
ProxyAuth 0 Ha 1értékre van állítva, az illesztőprogram a proxyhitelesítő felhasználót és a jelszót használja, amelyet ProxyUID és ProxyPwdjelöl.
ProxyHost null Egy karakterlánc, amely azt a proxy gazdagép nevét képviseli, amelyet akkor kell használni, ha UseProxy-t is 1-re állítják.
ProxyPort null Egy egész szám, amely a UseProxy esetén használandó proxyport számát 1értékre állítja.
ProxyUID null Az a karakterlánc, amely a proxyhitelesítéshez használandó felhasználónevet jelöli, amikor a ProxyAuth és UseProxy is 1-re van állítva.
ProxyPwd null Egy karakterlánc, amely a proxyhitelesítéshez használandó jelszót képviseli, amikor ProxyAuth és UseProxy is 1-re van állítva.
UseProxy 0 Ha 1van beá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 1van beá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 1van beállítva, az illesztőprogram a felhőbeolvasási proxy beállításait használja, ha vannak megadva, ellenkező esetben használja a normál proxyt.
CFProxyAuth 0 Ha 1értékre van állítva, az illesztőprogram a proxyhitelesítő felhasználót és a jelszót használja, amelyet CFProxyUID és CFProxyPwdjelöl.
CFProxyHost null Egy karakterlánc, amely azt a proxy gazdagép nevét képviseli, amelyet akkor kell használni, ha UseCFProxy-t is 1-re állítják.
CFProxyPort null Egy egész szám, amely a UseCFProxy esetén használandó proxyport számát 1értékre állítja.
CFProxyUID null Az a karakterlánc, amely a proxyhitelesítéshez használandó felhasználónevet jelöli, amikor a CFProxyAuth és UseCFProxy is 1-re van állítva.
CFProxyPwd null Egy karakterlánc, amely a proxyhitelesítéshez használandó jelszót képviseli, amikor CFProxyAuth és UseCFProxy is 1-re van állítva.
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 konfigurációs paraméterekis 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_photon 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/cityré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 OFF 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 A naplók alapértelmezett elérési útjának meghatározásához az illesztőprogram a rendszertulajdonságokhoz beállított értéket használja ebben a prioritási sorrendben:

1. user.dir
2. java.io.tmpdir
3. az aktuális könyvtár, más szóval .
Annak a mappának a teljes elérési útja, amelyben a csatlakozó menti a naplófájlokat, amikor a naplózás engedélyezve van, sztringként. Ha meg szeretné győződni arról, hogy a kapcsolati URL-cím kompatibilis az összes JDBC-alkalmazással, egy másik fordított perjel beírásával lépjen ki a fájl elérési útjában lévő fordított perjelek (\) elől.

Ha az LogPath érték érvénytelen, az összekötő elküldi a naplózott adatokat a standard kimeneti streamnek (System.out).
LogFileSize Nincs maximális érték Az MB-ban megadott maximális engedélyezett naplófájlméret
LogFileCount Nincs maximális érték Az engedélyezett naplófájlok maximális száma

Naplózás engedélyezése és konfigurálása

A JDBC-illesztő támogatja a Java (SLF4J) és a java.util.logging (JUL) keretrendszereket. Az illesztőprogram alapértelmezés szerint a JUL naplózási keretrendszert használja.

A JDBC-illesztőprogram naplózásának engedélyezése és konfigurálása:

  1. Engedélyezze a használni kívánt naplózási keretrendszert:

    • Az SLF4J-naplózáshoz állítsa be a rendszertulajdonságot -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER, és adja meg az SLF4J kötés implementálását (kompatibilis az SLF4J 2.0.13-s és újabb verziójával) és a megfelelő konfigurációs fájlt az osztályúton.
    • JUL-naplózás beállításához állítsa be a rendszertulajdonságot -Dcom.databricks.jdbc.loggerImpl=JDKLOGGER. Ez az alapértelmezett beállítás.
  2. Állítsa be a kapcsolati sztring LogLevel tulajdonságát a naplófájlokban felvenni kívánt információszintre.

  3. Állítsa a kapcsolati sztring LogPath tulajdonságát a mappa teljes elérési útjára, ahová a naplófájlokat menteni szeretné.

    A következő kapcsolati URL-cím például engedélyezi a 6. naplózási szintet, és menti a naplófájlokat a C:temp mappába:

    jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
    
  4. Indítsa újra a JDBC-alkalmazást, és csatlakozzon újra a kiszolgálóhoz a beállítások alkalmazásához.

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();
        }
    }
}

További erőforrások