View a markdown version of this page

JDBC 3.x 驅動器入門 - Amazon Athena
安裝說明執行驅動程式設定驅動程式從 Athena JDBC v2 驅動程式升級

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

JDBC 3.x 驅動器入門

使用本節中的資訊，開始使用 Amazon Athena JDBC 3.x 驅動程式。

安裝說明

您可以在自訂應用程式或第三方 SQL 用戶端中，使用 JDBC 3.x 驅動程式。

在自訂應用程式中

下載包含驅動程式及其相依性.zip的檔案。將驅動程式.jar檔案和 runtime-dependencies目錄中的所有其他.jar檔案新增至自訂應用程式的 Java 類別路徑。只有在您的應用程式已提供該相依性的相容版本時，才省略.jar檔案。AthenaStreamingJavaClient-2.0.jar 檔案提供 software.amazon.awssdk.services.athenastreaming.AthenaStreamingAsyncClient類別。包含此檔案，除非您的應用程式已提供該類別。

在第三方 SQL 用戶端中

下載驅動程式 uber jar 檔案，並依照該用戶端的指示將其新增至第三方 SQL 用戶端。

執行驅動程式

若要執行驅動程式，您可以使用自訂應用程式或第三方 SQL 用戶端。

在自訂應用程式中

使用 JDBC 介面與程式的 JDBC 驅動程式進行互動。下列程式碼顯示了一個自訂 Java 應用程式範例。

public static void main(String args[]) throws SQLException {
    Properties connectionParameters = new Properties();
    connectionParameters.setProperty("Workgroup", "primary");
    connectionParameters.setProperty("Region", "us-east-2");
    connectionParameters.setProperty("Catalog", "AwsDataCatalog");
    connectionParameters.setProperty("Database","sampledatabase");
    connectionParameters.setProperty("OutputLocation","s3://amzn-s3-demo-bucket");
    connectionParameters.setProperty("CredentialsProvider","DefaultChain");
    String url = "jdbc:athena://";
    AthenaDriver driver = new AthenaDriver();
    Connection connection = driver.connect(url, connectionParameters);
    Statement statement = connection.createStatement();
    String query = "SELECT * from sample_table LIMIT 10";
    ResultSet resultSet = statement.executeQuery(query);
    printResults(resultSet); // A custom-defined method for iterating over a
                             // result set and printing its contents
}

在第三方 SQL 用戶端中

遵循您所使用之 SQL 用戶端的文件。一般而言，您可以使用 SQL 用戶端的圖形化使用者介面來輸入及提交查詢，而查詢結果會顯示在相同的介面中。

設定驅動程式

您可以使用連線參數來設定 Amazon Athena JDBC 驅動程式。如需支援的連線參數，請參閱 Amazon Athena JDBC 3.x 連線參數。

在自訂應用程式中

若要在自訂應用程式中設定 JDBC 驅動程式的連線參數，請執行下列其中一個動作：

  • 將參數名稱及其值新增至 Properties 物件。當您呼叫 Connection#connect 時，將該物件與 URL 一起傳遞。如需範例，請參閱 執行驅動程式 中的 Java 範例應用程式。

  • 在連線字串 (URL) 中，使用下列格式將參數名稱及其值直接新增至通訊協定字首之後。

    <parameterName>=<parameterValue>;

    在每個參數名稱/參數值配對的末尾使用分號，分號後不留空格，如下列範例所示。

    String url = "jdbc:athena://WorkGroup=primary;Region=us-east-1;...;";AthenaDriver driver = new AthenaDriver();Connection connection = driver.connect(url, null);
    注意

    如果在連線字串和 Properties 物件中同時指定參數，則連線字串中的值優先。不建議在兩個位置指定相同的參數。

  • 將參數值作為引數新增至 AthenaDataSource 的方法，如下列範例所示。

    AthenaDataSource dataSource = new AthenaDataSource();
    dataSource.setWorkGroup("primary");
    dataSource.setRegion("us-east-2");
    ...
    Connection connection = dataSource.getConnection();
    ...

在第三方 SQL 用戶端中

依照您所使用之 SQL 用戶端的指示進行。通常，用戶端會提供圖形化使用者介面來輸入參數名稱及其值。

從 Athena JDBC v2 驅動程式升級

大多數 JDBC 第 3 版驅動器連線參數都與 JDBC 驅動器第 2 版 (Simba) 回溯相容。這意味著第 2 版連線字串可以與第 3 版驅動程式重複使用。但是，某些連線參數已更改。此處會有這些變更的相關說明。如有必要，當您升級至 JDBC 驅動器第 3 版時，請更新現有的組態。

驅動程式類別

有些 BI 工具會要求您從 JDBC 驅動程式 .jar 檔案提供驅動程式類別。大多數工具都會自動尋找這個類別。第 3 版驅動程式中完全合格的類別名稱為 com.amazon.athena.jdbc.AthenaDriver。在第 2 版驅動程式中，該類別為 com.simba.athena.jdbc.Driver。

連接字串

第 3 版驅動器將 jdbc:athena:// 用於 JDBC 連線字串 URL 開頭的通訊協定。第 3 版驅動器還支援第 2 版通訊協定 jdbc:awsathena://，但第 2 版通訊協定已廢除。為了避免出現未定義的行為，如果第 2 版 (或接受以 jdbc:awsathena:// 為開頭的連線字串的任何其他驅動器) 已向 DriverManager 類別註冊，則第 3 版不接受以 jdbc:awsathena:// 為開頭的連線字串。

字串欄中繼資料

使用 JDBC 3.x 驅動程式時，您無法再使用 JDBC 2.x StringColumnLength連線參數。反之，您可以透過標準JDBC中繼資料方法存取 Athena 提供的精確度，包括 ResultSetMetaData.getPrecision和 ResultSetMetaData.getColumnDisplaySize。由於 Athena string類型不受限制，其報告的精確度可以是 2147483647。

如果您的應用程式從JDBC中繼資料配置固定大小的緩衝區，請將其設定為使用可變大小緩衝區。如果您的應用程式需要週框資料欄中繼資料，請在查詢varchar(n)中將資料欄轉換為 ，或透過檢視公開轉換。選擇保留所有預期資料的 n 值，因為轉換為較小的大小可能會截斷值。

憑證提供者

第 2 版驅動程式會使用完全合格的名稱來辨識不同的憑證提供者 (例如 com.simba.athena.amazonaws.auth.DefaultAWSCredentialsProviderChain)。第 3 版驅動程式則使用較短的名稱 (例如 DefaultChain)。新名稱會在每個憑證提供者的對應章節中說明。

為第 2 版驅動程式編寫的自訂登入資料提供者需要針對第 3 版驅動程式進行修改，才能從新的 實作 AwsCredentialsProvider 介面， 適用於 Java 的 AWS SDK 而不是從先前的 AWSCredentialsProvider 介面實作 AwsCredentialsProvider 介面 適用於 Java 的 AWS SDK。

JDBC 3.x 驅動器不支援 PropertiesFileCredentialsProvider。在 JDBC 2.x 驅動程式中使用提供者，但屬於舊版的適用於 Java 的 AWS SDK，即將終止支援。若要在 JDBC 3.x 驅動器中實現相同的功能，請改用 AWS 組態設定檔登入資料 提供者。

日誌層級

下表顯示 JDBC 第 2 版和第 3 版驅動程式中的 LogLevel 參數差異。

JDBC 驅動程式版本 參數名稱 參數類型 預設值 可能的值 連線字串範例
  v2 LogLevel 選用 0 0-6 LogLevel=6;
v3 LogLevel 選用 TRACE OFF、ERROR、WARN、INFO、DEBUG、TRACE LogLevel=INFO;

查詢 ID 擷取

在第 2 版驅動程式中，您可以將 Statement 執行個體取消包裝至 com.interfaces.core.IStatementQueryInfoProvider，一個具有兩種方法 #getPReparedQueryId 和 #getQueryId 的介面。您可以使用這些方法來取得已執行之查詢的查詢執行 ID。

在第 3 版驅動程式中，您可以將 Statement、PreparedStatement 和 ResultSet 執行個體取消包裝至 com.amazon.athena.jdbc.AthenaResultSet 介面。該介面有一種方法：#getQueryExecutionId。