全部产品
Search
文档中心

Tablestore:Gunakan JDBC untuk mengakses Tablestore dengan mengeksekusi pernyataan SQL

更新时间:Jul 06, 2025

Tablestore menyediakan driver Java Database Connectivity (JDBC) yang dapat digunakan untuk mengeksekusi pernyataan SQL guna mengakses Tablestore. Topik ini menjelaskan cara menggunakan JDBC untuk mengakses Tablestore.

Catatan Penggunaan

Fitur kueri SQL tersedia di wilayah berikut: Tiongkok (Hangzhou), Tiongkok (Shanghai), Tiongkok (Beijing), Tiongkok (Zhangjiakou), Tiongkok (Ulanqab), Tiongkok (Shenzhen), Tiongkok (Chengdu), Tiongkok (Hong Kong), Jepang (Tokyo), Singapura, Malaysia (Kuala Lumpur), Inggris (London), AS (Silicon Valley), Indonesia (Jakarta), Jerman (Frankfurt), SAU (Riyadh - Partner Region), dan AS (Virginia).

Prasyarat

  • Jika Anda ingin mengkueri data sebagai pengguna RAM, pastikan pengguna RAM telah dibuat dan semua izin operasi SQL diberikan kepada pengguna tersebut. Anda dapat mengonfigurasi "Action": "ots:SQL*" dalam kebijakan kustom yang dilampirkan pada pengguna RAM untuk memberikan semua izin operasi SQL. Untuk informasi lebih lanjut, lihat Gunakan kebijakan RAM untuk memberikan izin kepada pengguna RAM.

  • Pasangan AccessKey yang terdiri dari ID AccessKey dan Rahasia AccessKey telah diperoleh. Untuk informasi lebih lanjut, lihat Buat pasangan AccessKey.

  • Tabel data telah dibuat, serta tabel pemetaan untuk tabel data. Untuk informasi lebih lanjut, lihat Prosedur dan Buat tabel pemetaan untuk tabel.

Prosedur

Langkah 1: Instal driver JDBC

Anda dapat menginstal driver JDBC menggunakan salah satu metode berikut:

  • Unduh driver JDBC untuk Tablestore dan impor driver tersebut ke proyek. Untuk informasi lebih lanjut tentang jalur unduhan, lihat Driver JDBC untuk Tablestore.

  • Tambahkan dependensi ke proyek Maven.

    Untuk menggunakan driver JDBC untuk Tablestore di Maven, tambahkan dependensi yang sesuai ke file pom.xml. Dalam contoh ini, driver JDBC versi 5.17.0 digunakan. Tambahkan konten berikut ke <dependencies>:

    <dependency>
      <groupId>com.aliyun.openservices</groupId>
      <artifactId>tablestore-jdbc</artifactId>
      <version>5.17.0</version>
    </dependency>

Langkah 2: Akses Tablestore menggunakan JDBC

  1. Muat driver JDBC untuk Tablestore menggunakan Class.forName().

    Nama driver JDBC untuk Tablestore adalah com.alicloud.openservices.tablestore.jdbc.OTSDriver.

    Class.forName("com.alicloud.openservices.tablestore.jdbc.OTSDriver");
  2. Akses instance Tablestore menggunakan JDBC.

    String url = "jdbc:ots:https://myinstance.cn-hangzhou.ots.aliyuncs.com/myinstance";
    String user = "************************";
    String password = "********************************";
    Connection conn = DriverManager.getConnection(url, user, password);

    Tabel berikut menjelaskan parameter yang harus dikonfigurasi untuk mengakses instance Tablestore menggunakan JDBC.

    Parameter

    Contoh

    Deskripsi

    url

    jdbc:ots:https://myinstance.cn-hangzhou.ots.aliyuncs.com/myinstance

    URL driver JDBC untuk Tablestore dalam format jdbc:ots:schema://[accessKeyId:accessKeySecret@]endpoint/instanceName[?param1=value1&...&paramN=valueN]. URL tersebut mencakup bidang-bidang berikut:

    • schema: Bidang ini wajib dan menentukan protokol yang digunakan oleh driver JDBC untuk Tablestore. Pada umumnya, bidang ini disetel ke https.

    • accessKeyId:accessKeySecret: Bidang ini opsional dan menentukan ID AccessKey dan Rahasia AccessKey akun Alibaba Cloud atau pengguna RAM Anda.

    • endpoint: Bidang ini wajib dan menentukan titik akhir instance. Untuk informasi lebih lanjut, lihat Titik Akhir.

    • instanceName: Bidang ini wajib dan menentukan nama instance.

    Untuk informasi lebih lanjut tentang item konfigurasi lainnya, lihat Item Konfigurasi.

    user

    ************************

    ID AccessKey akun Alibaba Cloud Anda atau pengguna RAM.

    password

    ********************************

    Rahasia AccessKey akun Alibaba Cloud Anda atau pengguna RAM.

    Anda dapat meneruskan pasangan AccessKey dan item konfigurasi menggunakan URL atau parameter Properties. Contoh berikut menunjukkan cara mengakses instance myinstance di wilayah China (Hangzhou) melalui Internet.

    • Teruskan pasangan AccessKey dan item konfigurasi menggunakan URL

      DriverManager.getConnection("jdbc:ots:https://************************:********************************@myinstance.cn-hangzhou.ots.aliyuncs.com/myinstance?enableRequestCompression=true");
    • Teruskan pasangan AccessKey dan item konfigurasi menggunakan parameter Properties

      Properties info = new Properties();
      info.setProperty("user", "************************");
      info.setProperty("password", "********************************");
      info.setProperty("enableRequestCompression", "true");
      DriverManager.getConnection("jdbc:ots:https://myinstance.cn-hangzhou.ots.aliyuncs.com/myinstance", info);
  3. Eksekusi pernyataan SQL.

    Anda dapat menggunakan metode createStatement atau prepareStatement untuk membuat pernyataan SQL.

    Catatan

    Untuk informasi tentang pernyataan SQL yang didukung, lihat Fitur SQL.

    Gunakan metode createStatement untuk membuat pernyataan SQL

    // Buat pernyataan SQL berdasarkan kebutuhan bisnis Anda. Kode sampel berikut menunjukkan cara mengkueri data di kolom id dan name dalam tabel test_table: 
    String sql = "SELECT id,name FROM test_table";
    
    Statement stmt = conn.createStatement();
    ResultSet resultSet = stmt.executeQuery(sql);
    while (resultSet.next()) {
        String id = resultSet.getString("id");       
        String name = resultSet.getString("name");                 
        System.out.println(id);
        System.out.println(name);
    }
    
    resultSet.close();
    stmt.close();

    Gunakan metode prepareStatement untuk membuat pernyataan SQL

    // Buat pernyataan SQL berdasarkan kebutuhan bisnis Anda. Kode sampel berikut menunjukkan cara mengkueri data dengan kunci utama tertentu dalam tabel test_table: 
    String sql = "SELECT * FROM test_table WHERE pk = ?";
    
    PreparedStatement stmt = connection.prepareStatement(sql);
    stmt.setLong(1, 1);
    ResultSet resultSet = stmt.executeQuery();
    ResultSetMetaData metaData = resultSet.getMetaData();
    while (resultSet.next()) {
        int columnCount = metaData.getColumnCount();
        for (int i=0; i< columnCount;i++) {
            String columnName = metaData.getColumnName(i+1);
            String columnValue = resultSet.getString(columnName);
            System.out.println(columnName);
            System.out.println(columnValue);
        }
    }
    
    resultSet.close();
    stmt.close();

Kode sampel lengkap

Kode sampel berikut menunjukkan cara mengkueri semua data dalam tabel test_table instance myinstance di wilayah China (Hangzhou):

public class Demo {
    public static void main(String[] args) throws SQLException, ClassNotFoundException {

        Class.forName("com.alicloud.openservices.tablestore.jdbc.OTSDriver");

        String url = "jdbc:ots:https://myinstance.cn-hangzhou.ots.aliyuncs.com/myinstance";
        String user = "************************";
        String password = "********************************";
        Connection conn = DriverManager.getConnection(url, user, password);

        String sql = "SELECT * FROM test_table";
        Statement stmt = conn.createStatement();
        ResultSet resultSet = stmt.executeQuery(sql);
        ResultSetMetaData metaData = resultSet.getMetaData();
        while (resultSet.next()) {
            int columnCount = metaData.getColumnCount();
            for (int i=0; i< columnCount;i++) {
                String columnName = metaData.getColumnName(i+1);
                String columnValue = resultSet.getString(columnName);
                System.out.println(columnName);
                System.out.println(columnValue);
            }
        }
        resultSet.close();
        stmt.close();
        conn.close();    // Tutup koneksi. Jika tidak, program tidak dapat keluar. 
    }
}           

Item konfigurasi

Driver JDBC untuk Tablestore diimplementasikan berdasarkan Tablestore SDK for Java. Anda dapat menggunakan JDBC untuk memodifikasi item konfigurasi Tablestore SDK for Java. Tabel berikut menjelaskan item konfigurasi umum.

Penting

Jika durasi permintaan SQL melebihi 30 detik, server akan mengembalikan kesalahan timeout. Jika Anda ingin menentukan periode timeout yang lebih kecil, atur item syncClientWaitFutureTimeoutInMillis ke nilai yang lebih kecil dari 30.000 milidetik. Anda dapat menggunakan metode setQueryTimeout untuk menentukan periode timeout terpisah untuk setiap pernyataan.

Item konfigurasi

Contoh

Deskripsi

enableRequestCompression

false

Menentukan apakah akan menekan data permintaan. Nilai default: false. Nilai valid:

  • true: menekan data permintaan.

  • false: tidak menekan data permintaan.

enableResponseCompression

false

Menentukan apakah akan menekan data respons. Nilai default: false. Nilai valid:

  • true: menekan data respons.

  • false: tidak menekan data respons.

ioThreadCount

2

Jumlah thread IOReactor dari HttpAsyncClient. Nilai default sama dengan jumlah vCPU.

maxConnections

300

Jumlah maksimum koneksi HTTP yang diizinkan.

socketTimeoutInMillisecond

30000

Periode timeout untuk transmisi data di lapisan Socket. Unit: milidetik. Nilai 0 menunjukkan penantian tak terbatas.

connectionTimeoutInMillisecond

30000

Periode timeout untuk pembuatan koneksi. Unit: milidetik. Nilai 0 menunjukkan penantian tak terbatas.

retryThreadCount

1

Jumlah thread yang digunakan untuk mengeksekusi ulang percobaan dalam pool thread.

syncClientWaitFutureTimeoutInMillis

-1

Periode timeout untuk penantian asinkron. Unit: milidetik.

connectionRequestTimeoutInMillisecond

60000

Periode timeout untuk pengiriman permintaan. Unit: milidetik.

retryStrategy

default

Kebijakan percobaan ulang. Nilai valid:

  • disable: tidak melakukan percobaan ulang permintaan.

  • default: melakukan percobaan ulang permintaan hingga timeout untuk kesalahan OTSNotEnoughCapacityUnit, OTSTableNotReady, OTSPartitionUnavailable, OTSServerBusy, OTSQuotaExhausted, OTSTimeout, OTSInternalServerError, dan OTSServerUnavailable.

retryTimeout

10

Periode timeout untuk percobaan ulang dan unit untuk periode timeout. Unit untuk periode timeout:

  • detik

  • milidetik

  • mikrodetik

  • nanodetik

  • menit

  • jam

retryTimeoutUnit

detik

Konversi tipe data

Tablestore mendukung lima tipe data: Integer, Double, String, Binary, dan Boolean. Saat menggunakan Tablestore SDK for Java dan JDBC untuk mengakses Tablestore, driver JDBC dapat secara otomatis mengonversi tipe data antara Java dan Tablestore.

Konversi tipe data Java ke tipe data Tablestore

Jika Anda menggunakan metode PreparedStatement untuk menentukan nilai parameter dalam pernyataan SQL, tipe data Byte, Short, Int, Long, BigDecimal, Float, Double, String, CharacterStream, Bytes, dan Boolean dalam Java dapat diteruskan ke mesin SQL Tablestore.

PreparedStatement stmt = connection.prepareStatement("SELECT * FROM t WHERE pk = ?");
stmt.setLong(1, 1);                                // Tipe data dapat dikonversi. 
stmt.setURL(1, new URL("https://aliyun.com/"));    // Tipe data tidak dapat dikonversi, dan sistem melempar pengecualian.

Konversi tipe data Tablestore ke tipe data Java

Jika Anda menggunakan metode ResultSet untuk mendapatkan hasil kueri SQL, perhatikan aturan konversi dalam tabel berikut. Tabel berikut menjelaskan aturan untuk konversi otomatis tipe data Tablestore ke tipe data Java.

Tipe data di Tablestore

Aturan konversi

Integer

  • Saat sistem mengonversi tipe data ke tipe integer, sistem melempar pengecualian jika nilai asli berada di luar rentang nilai tipe integer.

  • Saat sistem mengonversi tipe data ke tipe floating-point, presisi nilai yang dikonversi lebih rendah daripada presisi nilai asli.

  • Saat sistem mengonversi tipe data ke tipe string atau biner, nilai yang dikonversi sama dengan hasil pemrosesan nilai asli menggunakan toString().

  • Saat sistem mengonversi tipe data ke tipe Boolean dan nilai asli bukan nol, nilai yang dikonversi adalah true.

Double

String

  • Saat sistem mengonversi tipe data ke tipe integer atau floating-point, sistem melempar pengecualian jika penguraian gagal.

  • Saat sistem mengonversi tipe data ke tipe Boolean dan string asli adalah true, nilai yang dikonversi adalah true.

Binary

Boolean

  • Saat sistem mengonversi tipe data ke tipe integer atau floating-point dan nilai asli adalah true, nilai yang dikonversi adalah 1. Jika nilai asli adalah false, nilai yang dikonversi adalah 0.

  • Saat sistem mengonversi tipe data ke tipe string atau biner, nilai yang dikonversi sama dengan hasil pemrosesan nilai asli menggunakan toString().

Statement stmt = conn.createStatement();
ResultSet resultSet = stmt.executeQuery("SELECT count(*) FROM t");
while (resultSet.next()) {
    resultSet.getLong(1);               // Tipe data dapat dikonversi. 
    resultSet.getCharacterStream(1);    // Tipe data tidak dapat dikonversi, dan sistem melempar pengecualian. 
}

Untuk informasi lebih lanjut tentang konversi tipe data antara Tablestore dan Java, lihat tabel berikut.

Catatan

Dalam tabel berikut, centang (✓) menunjukkan konversi normal, tilde (~) menunjukkan bahwa pengecualian mungkin dilempar selama konversi, dan silang (×) menunjukkan bahwa konversi tidak dapat dilakukan.

Tipe data

Integer

Double

String

Binary

Boolean

Byte

~

~

~

~

Short

~

~

~

~

Int

~

~

~

~

Long

~

~

~

BigDecimal

~

~

Float

~

~

Double

~

~

String

CharacterStream

×

×

×

Bytes

Boolean

Referensi

  • Jika Anda ingin mempercepat kueri data dan komputasi dengan mengeksekusi pernyataan SQL, Anda dapat membuat indeks sekunder atau indeks pencarian. Untuk informasi lebih lanjut, lihat Kebijakan pemilihan indeks dan Komputasi pushdown.

  • Anda juga dapat menggunakan mesin komputasi seperti MaxCompute, Spark, Hive, HadoopMR, Function Compute, Flink, dan PrestoDB untuk menghitung dan menganalisis data dalam tabel. Untuk informasi lebih lanjut, lihat Ikhtisar.

  • Untuk memvisualisasikan data, Anda dapat menggunakan Grafana. Misalnya, Anda dapat menggunakan Grafana untuk menampilkan data Tablestore dalam bentuk grafik. Untuk informasi lebih lanjut, lihat Hubungkan Tablestore ke Grafana.