update parameter-binding doc

update parameter-binding doc

documentation20/en/08.connector/01.java/docs.md

@@ -310,46 +310,239 @@ The Java connector may report three types of error codes: JDBC Driver (error cod
 - https://github.com/taosdata/TDengine/blob/develop/src/inc/taoserror.h
 
 ### Write data through parameter binding
+Starting with version 2.1.2.0, TDengine's JDBC-JNI implementation significantly improves support for data write (INSERT) scenarios with Parameter-Binding. When writing data in this way, you can avoid the resource consumption of SQL parsing, which can significantly improve write performance in many cases.
+Note:
+* Jdbc-restful implementations do not provide Parameter-Binding
+* The following sample code is based on taos-jdbcdriver-2.0.36
+* use setString to bind BINARY data, and use setNString to bind NCHAR data
+* Both setString and setNString require the user to declare the column width of the corresponding column in the table definition in the size parameter
 
-Since version 2.1.2.0, TDengine's JDBC-JNI implementation has significantly improved parameter binding support for data write (INSERT) scenarios. Data can be written in the following way, avoiding SQL parsing and significantly improving the write performance.(**Note**: parameter binding is not supported in JDBC-RESTful)
 
+Sample Code:
 ```java
-Statement stmt = conn.createStatement();
-Random r = new Random();
+public class ParameterBindingDemo {
  
-// In the INSERT statement, the VALUES clause allows you to specify a specific column; If automatic table creation is adopted, the TAGS clause needs to set the parameter values of all TAGS columns
-TSDBPreparedStatement s = (TSDBPreparedStatement) conn.prepareStatement("insert into ? using weather_test tags (?, ?) (ts, c1, c2) values(?, ?, ?)");
+    private static final String host = "127.0.0.1";
+    private static final Random random = new Random(System.currentTimeMillis());
+    private static final int BINARY_COLUMN_SIZE = 20;
+    private static final String[] schemaList = {
+            "create table stable1(ts timestamp, f1 tinyint, f2 smallint, f3 int, f4 bigint) tags(t1 tinyint, t2 smallint, t3 int, t4 bigint)",
+            "create table stable2(ts timestamp, f1 float, f2 double) tags(t1 float, t2 double)",
+            "create table stable3(ts timestamp, f1 bool) tags(t1 bool)",
+            "create table stable4(ts timestamp, f1 binary(" + BINARY_COLUMN_SIZE + ")) tags(t1 binary(" + BINARY_COLUMN_SIZE + "))",
+            "create table stable5(ts timestamp, f1 nchar(" + BINARY_COLUMN_SIZE + ")) tags(t1 nchar(" + BINARY_COLUMN_SIZE + "))"
+    };
+    private static final int numOfSubTable = 10, numOfRow = 10;
  
-s.setTableName("w1");
+    public static void main(String[] args) throws SQLException {
  
-// set tags
-s.setTagInt(0, r.nextInt(10));
-s.setTagString(1, "Beijing");
-int numOfRows = 10;
+        String jdbcUrl = "jdbc:TAOS://" + host + ":6030/";
+        Connection conn = DriverManager.getConnection(jdbcUrl, "root", "taosdata");
  
-// set values
-ArrayList<Long> ts = new ArrayList<>();
-for (int i = 0; i < numOfRows; i++){
-    ts.add(System.currentTimeMillis() + i);
-}
-s.setTimestamp(0, ts);
-ArrayList<Integer> s1 = new ArrayList<>();
-for (int i = 0; i < numOfRows; i++){
-    s1.add(r.nextInt(100));
-}
-s.setInt(1, s1);
-ArrayList<String> s2 = new ArrayList<>();
-for (int i = 0; i < numOfRows; i++){
-    s2.add("test" + r.nextInt(100));
+        init(conn);
+ 
+        bindInteger(conn);
+ 
+        bindFloat(conn);
+ 
+        bindBoolean(conn);
+ 
+        bindBytes(conn);
+ 
+        bindString(conn);
+ 
+        conn.close();
+    }
+ 
+    private static void init(Connection conn) throws SQLException {
+        try (Statement stmt = conn.createStatement()) {
+            stmt.execute("drop database if exists test_parabind");
+            stmt.execute("create database if not exists test_parabind");
+            stmt.execute("use test_parabind");
+            for (int i = 0; i < schemaList.length; i++) {
+                stmt.execute(schemaList[i]);
+            }
+        }
+    }
+ 
+    private static void bindInteger(Connection conn) throws SQLException {
+        String sql = "insert into ? using stable1 tags(?,?,?,?) values(?,?,?,?,?)";
+ 
+        try (TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class)) {
+ 
+            for (int i = 1; i <= numOfSubTable; i++) {
+                // set table name
+                pstmt.setTableName("t1_" + i);
+                // set tags
+                pstmt.setTagByte(0, Byte.parseByte(Integer.toString(random.nextInt(Byte.MAX_VALUE))));
+                pstmt.setTagShort(1, Short.parseShort(Integer.toString(random.nextInt(Short.MAX_VALUE))));
+                pstmt.setTagInt(2, random.nextInt(Integer.MAX_VALUE));
+                pstmt.setTagLong(3, random.nextLong());
+                // set columns
+                ArrayList<Long> tsList = new ArrayList<>();
+                long current = System.currentTimeMillis();
+                for (int j = 0; j < numOfRow; j++)
+                    tsList.add(current + j);
+                pstmt.setTimestamp(0, tsList);
+ 
+                ArrayList<Byte> f1List = new ArrayList<>();
+                for (int j = 0; j < numOfRow; j++)
+                    f1List.add(Byte.parseByte(Integer.toString(random.nextInt(Byte.MAX_VALUE))));
+                pstmt.setByte(1, f1List);
+ 
+                ArrayList<Short> f2List = new ArrayList<>();
+                for (int j = 0; j < numOfRow; j++)
+                    f2List.add(Short.parseShort(Integer.toString(random.nextInt(Short.MAX_VALUE))));
+                pstmt.setShort(2, f2List);
+ 
+                ArrayList<Integer> f3List = new ArrayList<>();
+                for (int j = 0; j < numOfRow; j++)
+                    f3List.add(random.nextInt(Integer.MAX_VALUE));
+                pstmt.setInt(3, f3List);
+ 
+                ArrayList<Long> f4List = new ArrayList<>();
+                for (int j = 0; j < numOfRow; j++)
+                    f4List.add(random.nextLong());
+                pstmt.setLong(4, f4List);
+ 
+                // add column
+                pstmt.columnDataAddBatch();
+            }
+            // execute column
+            pstmt.columnDataExecuteBatch();
+        }
+    }
+ 
+    private static void bindFloat(Connection conn) throws SQLException {
+        String sql = "insert into ? using stable2 tags(?,?) values(?,?,?)";
+ 
+        TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class);
+ 
+        for (int i = 1; i <= numOfSubTable; i++) {
+            // set table name
+            pstmt.setTableName("t2_" + i);
+            // set tags
+            pstmt.setTagFloat(0, random.nextFloat());
+            pstmt.setTagDouble(1, random.nextDouble());
+            // set columns
+            ArrayList<Long> tsList = new ArrayList<>();
+            long current = System.currentTimeMillis();
+            for (int j = 0; j < numOfRow; j++)
+                tsList.add(current + j);
+            pstmt.setTimestamp(0, tsList);
+ 
+            ArrayList<Float> f1List = new ArrayList<>();
+            for (int j = 0; j < numOfRow; j++)
+                f1List.add(random.nextFloat());
+            pstmt.setFloat(1, f1List);
+ 
+            ArrayList<Double> f2List = new ArrayList<>();
+            for (int j = 0; j < numOfRow; j++)
+                f2List.add(random.nextDouble());
+            pstmt.setDouble(2, f2List);
+ 
+            // add column
+            pstmt.columnDataAddBatch();
+        }
+        // execute
+        pstmt.columnDataExecuteBatch();
+        // close if no try-with-catch statement is used
+        pstmt.close();
+    }
+ 
+    private static void bindBoolean(Connection conn) throws SQLException {
+        String sql = "insert into ? using stable3 tags(?) values(?,?)";
+ 
+        try (TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class)) {
+            for (int i = 1; i <= numOfSubTable; i++) {
+                // set table name
+                pstmt.setTableName("t3_" + i);
+                // set tags
+                pstmt.setTagBoolean(0, random.nextBoolean());
+                // set columns
+                ArrayList<Long> tsList = new ArrayList<>();
+                long current = System.currentTimeMillis();
+                for (int j = 0; j < numOfRow; j++)
+                    tsList.add(current + j);
+                pstmt.setTimestamp(0, tsList);
+ 
+                ArrayList<Boolean> f1List = new ArrayList<>();
+                for (int j = 0; j < numOfRow; j++)
+                    f1List.add(random.nextBoolean());
+                pstmt.setBoolean(1, f1List);
+ 
+                // add column
+                pstmt.columnDataAddBatch();
+            }
+            // execute
+            pstmt.columnDataExecuteBatch();
+        }
+    }
+ 
+    private static void bindBytes(Connection conn) throws SQLException {
+        String sql = "insert into ? using stable4 tags(?) values(?,?)";
+ 
+        try (TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class)) {
+ 
+            for (int i = 1; i <= numOfSubTable; i++) {
+                // set table name
+                pstmt.setTableName("t4_" + i);
+                // set tags
+                pstmt.setTagString(0, new String("abc"));
+ 
+                // set columns
+                ArrayList<Long> tsList = new ArrayList<>();
+                long current = System.currentTimeMillis();
+                for (int j = 0; j < numOfRow; j++)
+                    tsList.add(current + j);
+                pstmt.setTimestamp(0, tsList);
+ 
+                ArrayList<String> f1List = new ArrayList<>();
+                for (int j = 0; j < numOfRow; j++) {
+                    f1List.add(new String("abc"));
+                }
+                pstmt.setString(1, f1List, BINARY_COLUMN_SIZE);
+ 
+                // add column
+                pstmt.columnDataAddBatch();
+            }
+            // execute
+            pstmt.columnDataExecuteBatch();
+        }
+    }
+ 
+    private static void bindString(Connection conn) throws SQLException {
+        String sql = "insert into ? using stable5 tags(?) values(?,?)";
+ 
+        try (TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class)) {
+ 
+            for (int i = 1; i <= numOfSubTable; i++) {
+                // set table name
+                pstmt.setTableName("t5_" + i);
+                // set tags
+                pstmt.setTagNString(0, "北京-abc");
+ 
+                // set columns
+                ArrayList<Long> tsList = new ArrayList<>();
+                long current = System.currentTimeMillis();
+                for (int j = 0; j < numOfRow; j++)
+                    tsList.add(current + j);
+                pstmt.setTimestamp(0, tsList);
+ 
+                ArrayList<String> f1List = new ArrayList<>();
+                for (int j = 0; j < numOfRow; j++) {
+                    f1List.add("北京-abc");
+                }
+                pstmt.setNString(1, f1List, BINARY_COLUMN_SIZE);
+ 
+                // add column
+                pstmt.columnDataAddBatch();
+            }
+            // execute
+            pstmt.columnDataExecuteBatch();
+        }
+    }
 }
-s.setString(2, s2, 10);
-
-// The cache is not cleared after AddBatch. Do not bind new data again before ExecuteBatch
-s.columnDataAddBatch();
-s.columnDataExecuteBatch();
-// Clear the cache, after which you can bind new data(including table names, tags, values):
-s.columnDataClearBatch();
-s.columnDataCloseBatch();
 ```
 
 The methods used to set tags are:
@@ -383,8 +576,6 @@ public void setString(int columnIndex, ArrayList<String> list, int size) throws
 public void setNString(int columnIndex, ArrayList<String> list, int size) throws SQLException
 ```
 
-**Note**: Both setString and setNString require the user to declare the column width of the corresponding column in the table definition in the size parameter.
-
 ### Data Subscription
 
 #### Subscribe