python query and insert examples (#11093)

* code review

* python insert example

* python stmt example

* python query example

* python async exmaple

* python json example

* java json example

docs-cn/06-insert-data/04-opentsdb-json.mdx

@@ -39,3 +39,24 @@ import CJson from "./_c_opts_json.mdx";
     <CJson />
   </TabItem>
 </Tabs>
+
+以上示例代码会自动创建 2 个超级表， 每个超级表有 2 条数据。
+
+```cmd
+taos> use test;
+Database changed.
+
+taos> show stables;
+              name              |      created_time       | columns |  tags  |   tables    |
+============================================================================================
+ meters.current                 | 2022-03-29 16:05:25.193 |       2 |      2 |           1 |
+ meters.voltage                 | 2022-03-29 16:05:25.200 |       2 |      2 |           1 |
+Query OK, 2 row(s) in set (0.001954s)
+
+taos> select * from `meters.current`;
+           ts            |           value           |          groupid          |            location            |
+===================================================================================================================
+ 2022-03-28 09:56:51.249 |              10.300000000 |               2.000000000 | Beijing.Chaoyang               |
+ 2022-03-28 09:56:51.250 |              12.600000000 |               2.000000000 | Beijing.Chaoyang               |
+Query OK, 2 row(s) in set (0.004076s)
+```

docs-cn/06-insert-data/_py_stmt.mdx

-```py
+```py title=一次绑定一行
 {{#include docs-examples/python/bind_param_example.py}}
-```
\ No newline at end of file
+```
+
+```py title=一次绑定多行
+{{#include docs-examples/python/multi_bind_example.py:bind_batch}}
+```

docs-cn/07-query-data/_py.mdx

+通过迭代逐行获取查询结果。
+
 ```py
-{{#include docs-examples/python/query_example.py}}
+{{#include docs-examples/python/query_example.py:iter}}
+```
+
+一次获取所有查询结果，并把每一行转化为一个字典返回。
+
+```py
+{{#include docs-examples/python/query_example.py:fetch_all}}
 ```

docs-cn/07-query-data/_py_async.mdx

 ```py
 {{#include docs-examples/python/async_query_example.py}}
 ```
+
+:::note
+这个示例程序，目前在 Windows 系统上还无法运行
+
+:::

docs-examples/java/src/main/java/com/taos/example/JSONProtocolExample.java

 package com.taos.example;
 
+import com.taosdata.jdbc.SchemalessWriter;
+import com.taosdata.jdbc.enums.SchemalessProtocolType;
+import com.taosdata.jdbc.enums.SchemalessTimestampType;
+
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.SQLException;
+import java.sql.Statement;
+
 public class JSONProtocolExample {
+    private static Connection getConnection() throws SQLException {
+        String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata";
+        return DriverManager.getConnection(jdbcUrl);
+    }
+
+    private static void createDatabase(Connection conn) throws SQLException {
+        try (Statement stmt = conn.createStatement()) {
+            stmt.execute("create database test");
+            stmt.execute("use test");
+        }
+    }
+
+    private static String getJSONData() {
+        return "[{\"metric\": \"meters.current\", \"timestamp\": 1648432611249, \"value\": 10.3, \"tags\": {\"location\": \"Beijing.Chaoyang\", \"groupid\": 2}}," +
+                " {\"metric\": \"meters.voltage\", \"timestamp\": 1648432611249, \"value\": 219, \"tags\": {\"location\": \"Beijing.Haidian\", \"groupid\": 1}}, " +
+                "{\"metric\": \"meters.current\", \"timestamp\": 1648432611250, \"value\": 12.6, \"tags\": {\"location\": \"Beijing.Chaoyang\", \"groupid\": 2}}," +
+                " {\"metric\": \"meters.voltage\", \"timestamp\": 1648432611250, \"value\": 221, \"tags\": {\"location\": \"Beijing.Haidian\", \"groupid\": 1}}]";
+    }
 
+    public static void main(String[] args) throws SQLException {
+        try (Connection conn = getConnection()) {
+            createDatabase(conn);
+            SchemalessWriter writer = new SchemalessWriter(conn);
+            String jsonData = getJSONData();
+            writer.write(jsonData, SchemalessProtocolType.JSON, SchemalessTimestampType.NOT_CONFIGURED);
+        }
+    }
 }

docs-examples/java/src/main/java/com/taos/example/RestInsertExample.java

@@ -31,32 +31,32 @@ public class RestInsertExample {
     /**
      * The generated SQL is:
      * INSERT INTO power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES('2018-10-03 14:38:05.000',10.30000,219,0.31000)
-     *         power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES('2018-10-03 14:38:15.000',12.60000,218,0.33000)
-     *         power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES('2018-10-03 14:38:16.800',12.30000,221,0.31000)
-     *         power.d1002 USING power.meters TAGS(Beijing.Chaoyang, 3) VALUES('2018-10-03 14:38:16.650',10.30000,218,0.25000)
-     *         power.d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES('2018-10-03 14:38:05.500',11.80000,221,0.28000)
-     *         power.d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES('2018-10-03 14:38:16.600',13.40000,223,0.29000)
-     *         power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES('2018-10-03 14:38:05.000',10.80000,223,0.29000)
-     *         power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES('2018-10-03 14:38:06.500',11.50000,221,0.35000)
+     * power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES('2018-10-03 14:38:15.000',12.60000,218,0.33000)
+     * power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES('2018-10-03 14:38:16.800',12.30000,221,0.31000)
+     * power.d1002 USING power.meters TAGS(Beijing.Chaoyang, 3) VALUES('2018-10-03 14:38:16.650',10.30000,218,0.25000)
+     * power.d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES('2018-10-03 14:38:05.500',11.80000,221,0.28000)
+     * power.d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES('2018-10-03 14:38:16.600',13.40000,223,0.29000)
+     * power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES('2018-10-03 14:38:05.000',10.80000,223,0.29000)
+     * power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES('2018-10-03 14:38:06.500',11.50000,221,0.35000)
      */
     private static String getSQL() {
         StringBuilder sb = new StringBuilder("INSERT INTO ");
         for (String line : getRawData()) {
-            String[] fields = line.split(",");
-            sb.append("power." + fields[0]).append(" USING power.meters TAGS(")
-                    .append(fields[5]).append(", ")
-                    .append(fields[6])
+            String[] ps = line.split(",");
+            sb.append("power." + ps[0]).append(" USING power.meters TAGS(")
+                    .append(ps[5]).append(", ") // tag: location
+                    .append(ps[6]) // tag: groupId
                     .append(") VALUES(")
-                    .append('\'').append(fields[1]).append('\'').append(",")
-                    .append(fields[2]).append(",")
-                    .append(fields[3]).append(",")
-                    .append(fields[4]).append(") ");
+                    .append('\'').append(ps[1]).append('\'').append(",") // ts
+                    .append(ps[2]).append(",") // current
+                    .append(ps[3]).append(",") // voltage
+                    .append(ps[4]).append(") "); // phase
         }
         return sb.toString();
     }
 
     public static void insertData() throws SQLException {
-        try(Connection conn = getConnection()) {
+        try (Connection conn = getConnection()) {
             try (Statement stmt = conn.createStatement()) {
                 stmt.execute("CREATE DATABASE power KEEP 3650");
                 stmt.execute("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) " +

docs-examples/python/async_query_example.py

-import taos
\ No newline at end of file
+import time
+from ctypes import *
+
+from taos import *
+
+
+def fetch_callback(p_param, p_result, num_of_rows):
+    print("fetched ", num_of_rows, "rows")
+    p = cast(p_param, POINTER(Counter))
+    result = TaosResult(p_result)
+
+    if num_of_rows == 0:
+        print("fetching completed")
+        p.contents.done = True
+        result.close()
+        return
+    if num_of_rows < 0:
+        p.contents.done = True
+        result.check_error(num_of_rows)
+        result.close()
+        return None
+
+    for row in result.rows_iter(num_of_rows):
+        print(row)
+    p.contents.count += result.row_count
+    result.fetch_rows_a(fetch_callback, p_param)
+
+
+def query_callback(p_param, p_result, code):
+    if p_result is None:
+        return
+    result = TaosResult(p_result)
+    if code == 0:
+        result.fetch_rows_a(fetch_callback, p_param)
+    result.check_error(code)
+
+
+class Counter(Structure):
+    _fields_ = [("count", c_int), ("done", c_bool)]
+
+    def __str__(self):
+        return "{ count: %d, done: %s }" % (self.count, self.done)
+
+
+def test_query(conn):
+    counter = Counter(count=0)
+    conn.query_a("select ts, current, voltage from power.meters", query_callback, byref(counter))
+
+    while not counter.done:
+        print(counter)
+        time.sleep(1)
+    print(counter)
+    conn.close()
+
+
+if __name__ == "__main__":
+    test_query(connect())
+
+# possible stdout:
+# { count: 0, done: False }
+# fetched  8 rows
+# 1538548685000 10.300000 219
+# 1538548695000 12.600000 218
+# 1538548696800 12.300000 221
+# 1538548696650 10.300000 218
+# 1538548685500 11.800000 221
+# 1538548696600 13.400000 223
+# 1538548685500 10.800000 223
+# 1538548686500 11.500000 221
+# fetched  0 rows
+# fetching completed
+# { count: 8, done: True }

docs-examples/python/bind_param_example.py

-import taos
\ No newline at end of file
+import taos
+from datetime import datetime
+
+# note: lines have already been sorted by table name
+lines = [('d1001', '2018-10-03 14:38:05.000', 10.30000, 219, 0.31000, 'Beijing.Chaoyang', 2),
+         ('d1001', '2018-10-03 14:38:15.000', 12.60000, 218, 0.33000, 'Beijing.Chaoyang', 2),
+         ('d1001', '2018-10-03 14:38:16.800', 12.30000, 221, 0.31000, 'Beijing.Chaoyang', 2),
+         ('d1002', '2018-10-03 14:38:16.650', 10.30000, 218, 0.25000, 'Beijing.Chaoyang', 3),
+         ('d1003', '2018-10-03 14:38:05.500', 11.80000, 221, 0.28000, 'Beijing.Haidian', 2),
+         ('d1003', '2018-10-03 14:38:16.600', 13.40000, 223, 0.29000, 'Beijing.Haidian', 2),
+         ('d1004', '2018-10-03 14:38:05.000', 10.80000, 223, 0.29000, 'Beijing.Haidian', 3),
+         ('d1004', '2018-10-03 14:38:06.500', 11.50000, 221, 0.35000, 'Beijing.Haidian', 3)]
+
+
+def get_ts(ts: str):
+    dt = datetime.strptime(ts, '%Y-%m-%d %H:%M:%S.%f')
+    return int(dt.timestamp() * 1000)
+
+
+def create_stable():
+    conn = taos.connect()
+    try:
+        conn.execute("CREATE DATABASE power")
+        conn.execute("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) "
+                     "TAGS (location BINARY(64), groupId INT)")
+    finally:
+        conn.close()
+
+
+def bind_row_by_row(stmt: taos.TaosStmt):
+    tb_name = None
+    for row in lines:
+        if tb_name != row[0]:
+            tb_name = row[0]
+            tags: taos.TaosBind = taos.new_bind_params(2)  # 2 is count of tags
+            tags[0].binary(row[5])  # location
+            tags[1].int(row[6])  # groupId
+            stmt.set_tbname_tags(tb_name, tags)
+        values: taos.TaosBind = taos.new_bind_params(4)  # 4 is count of columns
+        values[0].timestamp(get_ts(row[1]))
+        values[1].float(row[2])
+        values[2].int(row[3])
+        values[3].float(row[4])
+        stmt.bind_param(values)
+
+
+def insert_data():
+    conn = taos.connect(database="power")
+    try:
+        stmt = conn.statement("INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)")
+        bind_row_by_row(stmt)
+        stmt.execute()
+        stmt.close()
+    finally:
+        conn.close()
+
+
+if __name__ == '__main__':
+    create_stable()
+    insert_data()

docs-examples/python/json_protocol_example.py

@@ -3,15 +3,13 @@ import json
 import taos
 from taos import SmlProtocol, SmlPrecision
 
-lines = [[{"metric": "meters.current", "timestamp": 1648432611249, "value": 10.3, "tags": {"location": "Beijing.Chaoyang", "groupid": 2}},
-          {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219, "tags": {"location": "Beijing.Haidian", "groupid": 1}}],
-         [{"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6, "tags": {"location": "Beijing.Chaoyang", "groupid": 2}},
-          {"metric": "meters.voltage", "timestamp": 1648432611250, "value": 221, "tags": {"location": "Beijing.Haidian", "groupid": 1}}]
-         ]
+lines = [{"metric": "meters.current", "timestamp": 1648432611249, "value": 10.3, "tags": {"location": "Beijing.Chaoyang", "groupid": 2}},
+         {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219, "tags": {"location": "Beijing.Haidian", "groupid": 1}},
+         {"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6, "tags": {"location": "Beijing.Chaoyang", "groupid": 2}},
+         {"metric": "meters.voltage", "timestamp": 1648432611250, "value": 221, "tags": {"location": "Beijing.Haidian", "groupid": 1}}]
 
 
 def get_connection():
-    # create connection use firstEp in taos.cfg.
     return taos.connect()
 
 
@@ -22,14 +20,16 @@ def create_database(conn):
 
 def insert_lines(conn):
     global lines
-    lines = [json.dumps(line) for line in lines]
-    print(lines)
-    affected_rows = conn.schemaless_insert(lines, SmlProtocol.JSON_PROTOCOL, SmlPrecision.NOT_CONFIGURED)
-    print(affected_rows)  # 这里有 bug, 4 条数据只写入 2 条。
+    lines = json.dumps(lines)
+    # note: the first parameter must be a list with only one element.
+    affected_rows = conn.schemaless_insert([lines], SmlProtocol.JSON_PROTOCOL, SmlPrecision.NOT_CONFIGURED)
+    print(affected_rows)  # 4
 
 
 if __name__ == '__main__':
     connection = get_connection()
-    create_database(connection)
-    insert_lines(connection)
-    connection.close()
+    try:
+        create_database(connection)
+        insert_lines(connection)
+    finally:
+        connection.close()

docs-examples/python/line_protocol_example.py

@@ -30,6 +30,8 @@ def insert_lines(conn):
 
 if __name__ == '__main__':
     connection = get_connection()
-    create_database(connection)
-    insert_lines(connection)
-    connection.close()
+    try:
+        create_database(connection)
+        insert_lines(connection)
+    finally:
+        connection.close()

docs-examples/python/multi_bind_example.py

+import taos
+from datetime import datetime
+
+# ANCHOR: bind_batch
+table_tags = {
+    "d1001": ('Beijing.Chaoyang', 2),
+    "d1002": ('Beijing.Chaoyang', 3),
+    "d1003": ('Beijing.Haidian', 2),
+    "d1004": ('Beijing.Haidian', 3)
+}
+
+table_values = {
+    "d1001": [
+        ['2018-10-03 14:38:05.000', '2018-10-03 14:38:15.000', '2018-10-03 14:38:16.800'],
+        [10.3, 12.6, 12.3],
+        [219, 218, 221],
+        [0.31, 0.33, 0.32]
+    ],
+    "d1002": [
+        ['2018-10-03 14:38:16.650'], [10.3], [218], [0.25]
+    ],
+    "d1003": [
+        ['2018-10-03 14:38:05.500', '2018-10-03 14:38:16.600'],
+        [11.8, 13.4],
+        [221, 223],
+        [0.28, 0.29]
+    ],
+    "d1004": [
+        ['2018-10-03 14:38:05.500', '2018-10-03 14:38:06.500'],
+        [10.8, 11.5],
+        [223, 221],
+        [0.29, 0.35]
+    ]
+}
+
+
+def bind_multi_rows(stmt: taos.TaosStmt):
+    """
+    batch bind example
+    """
+    for tb_name in table_values.keys():
+        tags = table_tags[tb_name]
+        tag_params = taos.new_bind_params(2)
+        tag_params[0].binary(tags[0])
+        tag_params[1].int(tags[1])
+        stmt.set_tbname_tags(tb_name, tag_params)
+
+        values = table_values[tb_name]
+        value_params = taos.new_multi_binds(4)
+        value_params[0].timestamp([get_ts(t) for t in values[0]])
+        value_params[1].float(values[1])
+        value_params[2].int(values[2])
+        value_params[3].float(values[3])
+        stmt.bind_param_batch(value_params)
+
+
+def insert_data():
+    conn = taos.connect(database="power")
+    try:
+        stmt = conn.statement("INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)")
+        bind_multi_rows(stmt)
+        stmt.execute()
+        stmt.close()
+    finally:
+        conn.close()
+
+
+# ANCHOR_END: bind_batch
+
+
+def create_stable():
+    conn = taos.connect()
+    try:
+        conn.execute("CREATE DATABASE power")
+        conn.execute("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) "
+                     "TAGS (location BINARY(64), groupId INT)")
+    finally:
+        conn.close()
+
+
+def get_ts(ts: str):
+    dt = datetime.strptime(ts, '%Y-%m-%d %H:%M:%S.%f')
+    return int(dt.timestamp() * 1000)
+
+
+if __name__ == '__main__':
+    create_stable()
+    insert_data()

docs-examples/python/native_insert_example.py

-import taos
\ No newline at end of file
+import taos
+
+lines = ["d1001,2018-10-03 14:38:05.000,10.30000,219,0.31000,Beijing.Chaoyang,2",
+         "d1004,2018-10-03 14:38:05.000,10.80000,223,0.29000,Beijing.Haidian,3",
+         "d1003,2018-10-03 14:38:05.500,11.80000,221,0.28000,Beijing.Haidian,2",
+         "d1004,2018-10-03 14:38:06.500,11.50000,221,0.35000,Beijing.Haidian,3",
+         "d1002,2018-10-03 14:38:16.650,10.30000,218,0.25000,Beijing.Chaoyang,3",
+         "d1001,2018-10-03 14:38:15.000,12.60000,218,0.33000,Beijing.Chaoyang,2",
+         "d1001,2018-10-03 14:38:16.800,12.30000,221,0.31000,Beijing.Chaoyang,2",
+         "d1003,2018-10-03 14:38:16.600,13.40000,223,0.29000,Beijing.Haidian,2"]
+
+
+def get_connection() -> taos.TaosConnection:
+    """
+    create connection use firstEp in taos.cfg and use default user and password.
+    """
+    return taos.connect()
+
+
+def create_stable(conn: taos.TaosConnection):
+    conn.execute("CREATE DATABASE power")
+    conn.execute("USE power")
+    conn.execute("CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) "
+                 "TAGS (location BINARY(64), groupId INT)")
+
+
+# The generated SQL is:
+# INSERT INTO d1001 USING meters TAGS(Beijing.Chaoyang, 2) VALUES ('2018-10-03 14:38:05.000', 10.30000, 219, 0.31000) ('2018-10-03 14:38:15.000', 12.60000, 218, 0.33000) ('2018-10-03 14:38:16.800', 12.30000, 221, 0.31000)
+#             d1002 USING meters TAGS(Beijing.Chaoyang, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)
+#             d1003 USING meters TAGS(Beijing.Haidian, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000)
+#             d1004 USING meters TAGS(Beijing.Haidian, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)
+
+def get_sql():
+    global lines
+    lines = map(lambda line: line.split(','), lines)  # [['d1001', ...]...]
+    lines = sorted(lines, key=lambda ls: ls[0])  # sort by table name
+    sql = "INSERT INTO "
+    tb_name = None
+    for ps in lines:
+        tmp_tb_name = ps[0]
+        if tb_name != tmp_tb_name:
+            tb_name = tmp_tb_name
+            sql += f"{tb_name} USING meters TAGS({ps[5]}, {ps[6]}) VALUES "
+        sql += f"('{ps[1]}', {ps[2]}, {ps[3]}, {ps[4]}) "
+    return sql
+
+
+def insert_data(conn: taos.TaosConnection):
+    sql = get_sql()
+    affected_rows = conn.execute(sql)
+    print("affected_rows", affected_rows)  # 8
+
+
+if __name__ == '__main__':
+    connection = get_connection()
+    try:
+        create_stable(connection)
+        insert_data(connection)
+    finally:
+        connection.close()

docs-examples/python/query_example.py

 import taos
 
-conn = taos.connect()
 
+# ANCHOR: iter
+def query_api_demo(conn: taos.TaosConnection):
+    result: taos.TaosResult = conn.query("SELECT tbname, * FROM meters LIMIT 2")
+    print("field count:", result.field_count)
+    print("meta of fields[1]:", result.fields[1])
+    print("======================Iterate on result=========================")
+    for row in result:
+        print(row)
 
-def print_all():
-    result = conn.query()
+
+# field count: 7
+# meta of files[1]: {name: ts, type: 9, bytes: 8}
+# ======================Iterate on result=========================
+# ('d1001', datetime.datetime(2018, 10, 3, 14, 38, 5), 10.300000190734863, 219, 0.3100000023841858, 'Beijing.Chaoyang', 2)
+# ('d1001', datetime.datetime(2018, 10, 3, 14, 38, 15), 12.600000381469727, 218, 0.33000001311302185, 'Beijing.Chaoyang', 2)
+# ANCHOR_END: iter
+
+# ANCHOR: fetch_all
+def fetch_all_demo(conn: taos.TaosConnection):
+    result: taos.TaosResult = conn.query("SELECT ts, current FROM meters LIMIT 2")
+    rows = result.fetch_all_into_dict()
+    print("row count:", result.row_count)
+    print("===============all data===================")
+    print(rows)
+
+
+# row count: 2
+# ===============all data===================
+# [{'ts': datetime.datetime(2018, 10, 3, 14, 38, 5), 'current': 10.300000190734863},
+# {'ts': datetime.datetime(2018, 10, 3, 14, 38, 15), 'current': 12.600000381469727}]
+# ANCHOR_END: fetch_all
+
+if __name__ == '__main__':
+    connection = taos.connect(database="power")
+    try:
+        query_api_demo(connection)
+        fetch_all_demo(connection)
+    finally:
+        connection.close()

docs-examples/python/telnet_line_protocol_example.py

@@ -30,6 +30,8 @@ def insert_lines(conn):
 
 if __name__ == '__main__':
     connection = get_connection()
-    create_database(connection)
-    insert_lines(connection)
-    connection.close()
+    try:
+        create_database(connection)
+        insert_lines(connection)
+    finally:
+        connection.close()