Ovladač Databricks JDBC (OSS)

Článek
11/16/2024

Důležité

Tento ovladač je ve verzi Public Preview a zatím není k dispozici jako open source.

Databricks poskytuje ovladač JDBC (Open Source Software), který umožňuje připojit nástroje, jako jsou DataGrip, DBeaver a SQL Workbench/J , k Azure Databricks prostřednictvím JDBC (Java Database Connectivity), standardní specifikace pro přístup k systémům pro správu databází.

Tento ovladač implementoval rozhraní JDBC API a poskytuje základní funkce, včetně OAuth, cloudového načítání a funkcí, jako je příjem svazků v Unity. Spouští nativní režim dotazu a podporuje nativní parametrizovaný dotaz a může spouštět pomocí rozhraní API pro spouštění příkazů, která poskytuje výhodnou funkci uchovávání výsledků dotazu nebo thrift.

Tento článek obsahuje informace o instalaci a používání ovladače Databricks JDBC (OSS). Informace o ovladači JDBC jiného systému než OSS Databricks najdete v tématu Ovladač Databricks JDBC.

Požadavky

Pokud chcete použít ovladač Databricks JDBC (OSS), musí být splněny následující požadavky:

Java Runtime Environment (JRE) 11.0 nebo vyšší. Testování CI se podporuje v JRE 11, 17 a 21.

Poznámka:

V důsledku změny sady JDK 16, která způsobila problém s kompatibilitou s knihovnou Apache Arrow používanou ovladačem JDBC, může dojít k chybám za běhu při použití ovladače JDBC s JDK 16 nebo vyšší. Pokud chcete těmto chybám zabránit, restartujte aplikaci nebo ovladač pomocí následující možnosti příkazu JVM:

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

Instalace ovladače

Ovladač Databricks JDBC (OSS) se publikuje v úložišti Maven. Nejnovější verze je 0.9.6-oss.

Chcete-li nainstalovat ovladač, můžete provést některou z následujících věcí:

V případě projektů Maven přidejte do souboru projektu pom.xml následující závislost, která dává Mavenu pokyn, aby ovladač JDBC automaticky stáhl se zadanou verzí:
```
<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-jdbc</artifactId>
  <version>0.9.6-oss</version>
  <scope>runtime</scope>
</dependency>
```
V případě projektů Gradle přidejte do souboru sestavení projektu následující závislost, která dá Gradle pokyn, aby ovladač JDBC automaticky stáhl se zadanou verzí:
```
implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
```

Pokud chcete zobrazit syntaxi závislostí pro jiné typy projektů a získat nejnovější číslo verze ovladače Databricks JDBC (OSS), podívejte se na úložiště Maven.

Konfigurace adresy URL připojení

Pokud se chcete připojit k pracovnímu prostoru Azure Databricks pomocí ovladače JDBC, musíte zadat adresu URL připojení JDBC, která zahrnuje různá nastavení připojení, jako je název hostitele serveru pracovního prostoru Azure Databricks, nastavení výpočetních prostředků a přihlašovací údaje pro ověřování pro připojení k pracovnímu prostoru.

Hodnotu těchto vlastností můžete nastavit na adrese URL připojení JDBC, nastavit a předat je driverManager.getConnection metoda, nebo kombinaci obou. Informace o tom, jak se nejlépe připojit pomocí konkrétní aplikace, klienta, sady SDK, rozhraní API nebo nástroje SQL, najdete v dokumentaci poskytovatele.

Adresa URL připojení JDBC musí být v následujícím formátu. Vlastnosti nerozlišují malá a velká písmena.

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

Případně můžete zadat nastavení pomocí java.util.Properties třídy nebo kombinace:

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

Prvky adresy URL připojení jsou popsány v následující tabulce. Informace o dalších vlastnostech, včetně vlastností ověřování, najdete v následujících částech. Prvky adresy URL a vlastnosti nerozlišují malá a velká písmena.

Element nebo vlastnost ADRESY URL	Popis
`<server-hostname>`	Hodnota názvu hostitele serveru výpočetního prostředku Azure Databricks.
`<port>`	Hodnota portu výpočetního prostředku Azure Databricks Výchozí hodnota je `443`.
`<schema>`	Název schématu. Alternativně můžete vlastnost nastavit `ConnSchema` . Viz Vlastnosti připojení.
`httpPath`	Hodnota cesty HTTP výpočetního prostředku Azure Databricks Konektor vytvoří adresu HTTP pro připojení připojením `httpPath` hodnoty k hostiteli a portu zadanému v adrese URL připojení. Pokud se například chcete připojit k adrese `http://localhost:10002/cliservice`HTTP, použijte následující adresu URL připojení: `jdbc:databricks://localhost:10002;httpPath=cliservice`

Získání adresy URL připojení JDBC pro cluster Azure Databricks:

Přihlaste se k pracovnímu prostoru Azure Databricks.
Na bočním panelu klikněte na Compute a potom klikněte na název cílového clusteru.
Na kartě Konfigurace rozbalte možnosti Upřesnit.
Klikněte na kartu JDBC/ODBC .
Zkopírujte adresu URL JDBC, která se má použít jako adresa URL připojení JDBC, nebo vytvořte adresu URL z hodnot v polích Název hostitele serveru, Port a Cesta HTTP.

Získání adresy URL připojení JDBC pro Databricks SQL Warehouse:

Přihlaste se k pracovnímu prostoru Azure Databricks.
Na bočním panelu klikněte na SQL Warehouses a potom klikněte na název cílového skladu.
Klikněte na kartu Podrobnosti připojení.
Zkopírujte adresu URL JDBC, která se má použít jako adresa URL připojení JDBC, nebo vytvořte adresu URL z hodnot v polích Název hostitele serveru, Port a Cesta HTTP.

Ověření ovladače

Připojení ovladače JDBC můžete ověřit pomocí jednoho z následujících mechanismů ověřování:

Ověřování uživatele OAuth na počítač (U2M) (doporučeno)
Ověřování OAuth mezi počítači (M2M)
Osobní přístupový token Azure Databricks

Ověřování uživatele OAuth na počítač (U2M)

Ovladač JDBC podporuje ověřování uživatelem AAuth (U2M) pro přihlášení člověka v reálném čase a vyjádření souhlasu s ověřením cílového uživatelského účtu Databricks. Označuje se také jako ověřování OAuth založené na prohlížeči.

Azure Databricks vytvořila ID databricks-sql-jdbc klienta OAuth pro zákazníky. Toto je také výchozí ID klienta OAuth použité v ovladači JDBC. Pokud chcete nakonfigurovat ověřování OAuth U2M, stačí do existující adresy URL nebo java.util.Properties objektu připojení JDBC přidat následující vlastnosti:

Vlastnost	Hodnota
`AuthMech`	`11`
`Auth_Flow`	`2`

Ověřování M2M (machine-to-machine) OAuth

Ovladač JDBC podporuje ověřování OAuth typu machine-to-machine (M2M) pomocí instančního objektu Azure Databricks. To se také označuje jako ověřování přihlašovacích údajů klienta OAuth 2.0. Viz Ověření přístupu k Azure Databricks pomocí instančního objektu pomocí OAuth (OAuth M2M).

Konfigurace ověřování přihlašovacích údajů klienta OAuth M2M nebo OAuth 2.0:

Vytvořte spravovaný instanční objekt Microsoft Entra ID a pak ho přiřaďte k účtům a pracovním prostorům Azure Databricks. Podrobnosti najdete v tématu Správa instančních objektů.

Důležité

Ovladač Databricks JDBC (OSS) podporuje tajné kódy Azure Databricks OAuth pro ověřování přihlašovacích údajů klienta OAuth M2M nebo OAuth 2.0. Tajné kódy MICROSOFT Entra ID nejsou podporovány.
Vytvořte tajný klíč Azure Databricks OAuth pro instanční objekt. Postup najdete v tématu Ruční generování a používání přístupových tokenů pro ověřování OAuth M2M.
Udělte instančnímu objektu přístup ke clusteru nebo skladu. Přečtěte si informace o výpočetních oprávněních nebo správě SLUŽBY SQL Warehouse.

Do existující adresy URL nebo java.util.Properties objektu připojení JDBC přidejte následující vlastnosti:

Vlastnost	Hodnota
`AuthMech`	`11`
`Auth_Flow`	`1`
`OAuth2ClientID`	Hodnota ID aplikace (klienta) instančního objektu.
`OAuth2Secret`	Tajný klíč Azure Databricks OAuth instančního objektu. (Ověřování přihlašovacích údajů klienta OAuth M2M nebo OAuth 2.0 nepodporuje tajné kódy MICROSOFT Entra ID.)

Osobní přístupový token Azure Databricks

Pokud chcete ověřit připojení ovladače JDBC pomocí osobního přístupového tokenu Azure Databricks, přidejte do adresy URL nebo java.util.Properties objektu připojení JDBC následující vlastnosti:

Vlastnost	Hodnota
`AuthMech`	`3`
`user`	Hodnota `token`, jako řetězec.
`PWD` nebo `password`	Hodnota osobního přístupového tokenu Azure Databricks jako řetězec

Vlastnosti připojení

Ovladač JDBC podporuje následující další vlastnosti připojení. Vlastnosti nerozlišují malá a velká písmena.

Vlastnost	Výchozí hodnota	Popis
`AuthMech`	Povinní účastníci	Mechanismus ověřování, kde `3` určuje mechanismus, je osobní přístupový token Azure Databricks a `11` určuje mechanismus tokeny OAuth 2.0. Pro každý mechanismus jsou vyžadovány další vlastnosti. Viz Ověření ovladače.
`Auth_Flow`	`0`	Tok ověřování OAuth2 pro připojení ovladače Tato vlastnost je vyžadována, pokud `AuthMech` je `11`.
`SSL`	`1`	Určuje, jestli konektor komunikuje se serverem Spark prostřednictvím soketu s povoleným protokolem SSL.
`ConnCatalog` nebo `catalog`	`SPARK`	Název výchozího katalogu, který se má použít.
`ConnSchema` nebo `schema`	`default`	Název výchozího schématu, které se má použít. Můžete ji zadat tak, že v adrese URL nahradíte `<schema>` názvem schématu, který se má použít, nebo nastavením `ConnSchema` vlastnosti na název schématu, který se má použít.
`ProxyAuth`	`0`	Pokud je nastavena hodnota `1`, ovladač používá uživatele a heslo pro ověřování proxy serveru, které reprezentuje `ProxyUID` a `ProxyPwd`.
`ProxyHost`	`null`	Řetězec, který představuje název hostitele proxy, který se má použít, pokud `UseProxy` je také nastaven na `1`.
`ProxyPort`	`null`	Celé číslo, které představuje počet proxy portu, který se má použít, pokud `UseProxy` je také nastaven na `1`.
`ProxyUID`	`null`	Řetězec, který představuje uživatelské jméno, které se má použít pro ověřování proxy, když `ProxyAuth` a `UseProxy` jsou také nastaveny na `1`.
`ProxyPwd`	`null`	Řetězec, který představuje heslo, které se má použít pro ověřování proxy serveru, když `ProxyAuth` a `UseProxy` jsou také nastaveny na `1`.
`UseProxy`	`0`	Pokud je nastavená hodnota `1`, ovladač použije poskytnuté nastavení proxy serveru (například: `ProxyAuth`, `ProxyHost`, `ProxyPort`, `ProxyPwd`a `ProxyUID`).
`UseSystemProxy`	`0`	Pokud je nastavená hodnota `1`, ovladač použije nastavení proxy serveru, které byly nastaveny na úrovni systému. Pokud jsou v adrese URL připojení nastavené nějaké další vlastnosti proxy serveru, tyto další vlastnosti proxy přepíší ty, které byly nastaveny na úrovni systému.
`UseCFProxy`	`0`	Pokud je nastavená hodnota `1`, ovladač použije nastavení proxy serveru cloudového načítání, pokud jsou k dispozici, jinak použijte běžný proxy server.
`CFProxyAuth`	`0`	Pokud je nastavena hodnota `1`, ovladač používá uživatele a heslo pro ověřování proxy serveru, které reprezentuje `CFProxyUID` a `CFProxyPwd`.
`CFProxyHost`	`null`	Řetězec, který představuje název hostitele proxy, který se má použít, pokud `UseCFProxy` je také nastaven na `1`.
`CFProxyPort`	`null`	Celé číslo, které představuje počet proxy portu, který se má použít, pokud `UseCFProxy` je také nastaven na `1`.
`CFProxyUID`	`null`	Řetězec, který představuje uživatelské jméno, které se má použít pro ověřování proxy, když `CFProxyAuth` a `UseCFProxy` jsou také nastaveny na `1`.
`CFProxyPwd`	`null`	Řetězec, který představuje heslo, které se má použít pro ověřování proxy serveru, když `CFProxyAuth` a `UseCFProxy` jsou také nastaveny na `1`.
`AsyncExecPollInterval`	`200`	Čas v milisekundách mezi každým dotazem pro stav asynchronního spuštění dotazu. Asynchronní odkazuje na skutečnost, že volání RPC použité k provedení dotazu na Spark je asynchronní. Neznamená to, že jsou podporovány asynchronní operace JDBC.
`UserAgentEntry`	`browser`	Položka user-agenta, která se má zahrnout do požadavku HTTP. Tato hodnota je v následujícím formátu: `[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`0`	Určuje, jestli by ovladač JDBC měl používat klienta Thrift k připojení ke clusteru pro všechny účely. Výchozí hodnota funguje pro sklady SQL.

Vlastnosti konfigurace SQL

Ovladač JDBC podporuje následující vlastnosti konfigurace SQL. Tyto parametry jsou také popsány v parametrech konfigurace. Vlastnosti nerozlišují malá a velká písmena.

Vlastnost	Výchozí hodnota	Popis
`ansi_mode`	`TRUE`	Zda povolit přísné chování ANSI SQL pro určité funkce a pravidla přetypování.
`enable_photo`	`TRUE`	Zda povolit vektorizovaný dotazovací stroj Photon.
`legacy_time_parser_policy`	`EXCEPTION`	Metody používané k analýze a formátování kalendářních dat a časových razítek. Platné hodnoty jsou `EXCEPTION`, `LEGACY` a `CORRECTED`.
`max_file_partition_bytes`	`128m`	Maximální počet bajtů, které se mají zabalit do jednoho oddílu při čtení ze zdrojů založených na souborech. Nastavení může být libovolné kladné celé číslo a volitelně může obsahovat míru, například `b` (bajty) `k` nebo `kb` (1024 bajtů).
`read_only_external_metastore`	`false`	Určuje, jestli se externí metastore považuje za jen pro čtení.
`statement_timeout`	`172800`	Nastaví časový limit příkazu SQL mezi 0 a 172800 sekund.
`timezone`	`UTC`	Nastavte místní časové pásmo. ID oblastí ve formuláři `area/city`, například Amerika/Los_Angeles nebo posuny zóny ve formátu (+\|-)HH, (+\|\|-)HH:mm nebo (+\|-)HH:mm:ss, např. -08, +01:00 nebo -13:33:33. `UTC` Podporuje se také jako alias pro +00:00.
`use_cached_result`	`true`	Jestli Databricks SQL ukládá do mezipaměti a opakovaně používá výsledky, kdykoli je to možné.

Vlastnosti protokolování

Ovladač JDBC podporuje následující vlastnosti protokolování. Vlastnosti nerozlišují malá a velká písmena.

Vlastnost	Výchozí hodnota	Popis
`LogLevel`	`OFF`	Úroveň protokolování, což je hodnota 0 až 6: - 0: Zakažte veškeré protokolování. - 1: Povolte protokolování na úrovni ZÁVAŽNÁ CHYBA, která protokoluje velmi závažné chybové události, které vedou konektor k přerušení. - 2: Povolte protokolování na úrovni ERROR, která protokoluje události chyb, které můžou konektoru dál běžet. - 3: Povolte protokolování na úrovni UPOZORNĚNÍ, které protokoluje události, které můžou vést k chybě, pokud akce není provedena. - 4: Povolte protokolování na úrovni INFO, která protokoluje obecné informace popisované průběh konektoru. - 5: Povolte protokolování na úrovni LADĚNÍ, které protokoluje podrobné informace, které jsou užitečné pro ladění konektoru. - 6: Povolte protokolování na úrovni TRACE, která protokoluje všechny aktivity konektoru. Tato vlastnost slouží k povolení nebo zakázání protokolování v konektoru a k určení množství podrobností zahrnutých v souborech protokolu.
`LogPath`	K určení výchozí cesty pro protokoly používá ovladač hodnotu nastavenou pro tyto systémové vlastnosti v tomto pořadí priority: 1. `user.dir` 2. `java.io.tmpdir` 3. aktuální adresář jinými slovy `.`	Úplná cesta ke složce, do které konektor ukládá soubory protokolu, když je protokolování povolené, jako řetězec. Pokud chcete zajistit, aby adresa URL připojení byla kompatibilní se všemi aplikacemi JDBC, ucházejte zpětná lomítka (`\`) do cesty k souboru zadáním jiného zpětného lomítka. `LogPath` Pokud je hodnota neplatná, konektor odešle protokolované informace do standardního výstupního datového proudu (System.out).
`LogFileSize`	Bez maximálního počtu	Maximální povolená velikost souboru protokolu zadaná v MB
`LogFileCount`	Bez maximálního počtu	Maximální počet povolených souborů protokolu

Povolení a konfigurace protokolování

Ovladač JDBC podporuje architektury Java (SLF4J) a java.util.logging (JUL). Ovladač ve výchozím nastavení používá rozhraní protokolování JUL.

Povolení a konfigurace protokolování pro ovladač JDBC:

Povolte rozhraní protokolování, které chcete použít:
- Pro protokolování SLF4J nastavte systémovou vlastnost -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER a zadejte implementaci vazby SLF4J (kompatibilní s SLF4J verze 2.0.13 a vyšší) a odpovídající konfigurační soubor v cestě ke třídě.
- Pro protokolování JUL nastavte vlastnost -Dcom.databricks.jdbc.loggerImpl=JDKLOGGERsystému . Tato možnost je výchozí.
LogLevel Nastavte vlastnost na připojovací řetězec na požadovanou úroveň informací, které chcete zahrnout do souborů protokolu.
LogPath Nastavte vlastnost na připojovací řetězec na úplnou cestu ke složce, do které chcete ukládat soubory protokolu.

Například následující adresa URL připojení umožňuje protokolování úrovně 6 a ukládá soubory protokolu do složky C:temp:
```
jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
```
Restartujte aplikaci JDBC a znovu se připojte k serveru a použijte nastavení.

Příklad: Spuštění dotazu pomocí ovladače JDBC

Následující příklad ukazuje, jak pomocí ovladače JDBC spustit dotaz SQL Databricks pomocí výpočetního prostředku Azure Databricks.

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

Sdílet prostřednictvím