diff --git a/docs/en/14-reference/03-connector/07-python.mdx b/docs/en/14-reference/03-connector/07-python.mdx index 6bd02644d4..aa1186fa52 100644 --- a/docs/en/14-reference/03-connector/07-python.mdx +++ b/docs/en/14-reference/03-connector/07-python.mdx @@ -667,6 +667,137 @@ Insert with req_id argument +### Parameter Binding + +The Python connector provides a parameter binding api for inserting data. Similar to most databases, TDengine currently only supports the question mark `?` to indicate the parameters to be bound. + + + + +#### Create Stmt + +Call the `statement` method in `Connection` to create the `stmt` for parameter binding. + +``` +import taos + +conn = taos.connect() +stmt = conn.statement("insert into log values(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)") +``` + +#### parameter binding + +Call the `new_multi_binds` function to create the parameter list for parameter bindings. + +``` +params = new_multi_binds(16) +params[0].timestamp((1626861392589, 1626861392590, 1626861392591)) +params[1].bool((True, None, False)) +params[2].tinyint([-128, -128, None]) # -128 is tinyint null +params[3].tinyint([0, 127, None]) +params[4].smallint([3, None, 2]) +params[5].int([3, 4, None]) +params[6].bigint([3, 4, None]) +params[7].tinyint_unsigned([3, 4, None]) +params[8].smallint_unsigned([3, 4, None]) +params[9].int_unsigned([3, 4, None]) +params[10].bigint_unsigned([3, 4, None]) +params[11].float([3, None, 1]) +params[12].double([3, None, 1.2]) +params[13].binary(["abc", "dddafadfadfadfadfa", None]) +params[14].nchar(["涛思数据", None, "a long string with 中文字符"]) +params[15].timestamp([None, None, 1626861392591]) +``` + +Call the `bind_param` (for a single row) method or the `bind_param_batch` (for multiple rows) method to set the values. + +``` +stmt.bind_param_batch(params) +``` + +#### execute sql + +Call `execute` method to execute sql. + +``` +stmt.execute() +``` + +#### Close Stmt + +``` +stmt.close() +``` + +#### Example + +```python +{{#include docs/examples/python/stmt_example.py}} +``` + + + + +#### Create Stmt + +Call the `statement` method in `Connection` to create the `stmt` for parameter binding. + +``` +import taosws + +conn = taosws.connect('taosws://localhost:6041/test') +stmt = conn.statement() +``` + +#### Prepare sql + +Call `prepare` method in stmt to prepare sql. + +``` +stmt.prepare("insert into t1 values (?, ?, ?, ?)") +``` + +#### parameter binding + +Call the `bind_param` method to bind parameters. + +``` +stmt.bind_param([ + taosws.millis_timestamps_to_column([1686844800000, 1686844801000, 1686844802000, 1686844803000]), + taosws.ints_to_column([1, 2, 3, 4]), + taosws.floats_to_column([1.1, 2.2, 3.3, 4.4]), + taosws.varchar_to_column(['a', 'b', 'c', 'd']), +]) +``` + +Call the `add_batch` method to add parameters to the batch. + +``` +stmt.add_batch() +``` + +#### execute sql + +Call `execute` method to execute sql. + +``` +stmt.execute() +``` + +#### Close Stmt + +``` +stmt.close() +``` + +#### Example + +```python +{{#include docs/examples/python/stmt_websocket_example.py}} +``` + + + ### Other sample programs | Example program links | Example program content | diff --git a/docs/examples/python/stmt_example.py b/docs/examples/python/stmt_example.py new file mode 100644 index 0000000000..83197a777a --- /dev/null +++ b/docs/examples/python/stmt_example.py @@ -0,0 +1,82 @@ +#! + +import taosws + +import taos + +db_name = 'test_ws_stmt' + + +def before(): + taos_conn = taos.connect() + taos_conn.execute("drop database if exists %s" % db_name) + taos_conn.execute("create database %s" % db_name) + taos_conn.select_db(db_name) + taos_conn.execute("create table t1 (ts timestamp, a int, b float, c varchar(10))") + taos_conn.execute( + "create table stb1 (ts timestamp, a int, b float, c varchar(10)) tags (t1 int, t2 binary(10))") + taos_conn.close() + + +def stmt_insert(): + before() + + conn = taosws.connect('taosws://root:taosdata@localhost:6041/%s' % db_name) + + while True: + try: + stmt = conn.statement() + stmt.prepare("insert into t1 values (?, ?, ?, ?)") + + stmt.bind_param([ + taosws.millis_timestamps_to_column([1686844800000, 1686844801000, 1686844802000, 1686844803000]), + taosws.ints_to_column([1, 2, 3, 4]), + taosws.floats_to_column([1.1, 2.2, 3.3, 4.4]), + taosws.varchar_to_column(['a', 'b', 'c', 'd']), + ]) + + stmt.add_batch() + rows = stmt.execute() + print(rows) + stmt.close() + except Exception as e: + if 'Retry needed' in e.args[0]: # deal with [0x0125] Retry needed + continue + else: + raise e + + break + + +def stmt_insert_into_stable(): + before() + + conn = taosws.connect("taosws://root:taosdata@localhost:6041/%s" % db_name) + + while True: + try: + stmt = conn.statement() + stmt.prepare("insert into ? using stb1 tags (?, ?) values (?, ?, ?, ?)") + stmt.set_tbname('stb1_1') + stmt.set_tags([ + taosws.int_to_tag(1), + taosws.varchar_to_tag('aaa'), + ]) + stmt.bind_param([ + taosws.millis_timestamps_to_column([1686844800000, 1686844801000, 1686844802000, 1686844803000]), + taosws.ints_to_column([1, 2, 3, 4]), + taosws.floats_to_column([1.1, 2.2, 3.3, 4.4]), + taosws.varchar_to_column(['a', 'b', 'c', 'd']), + ]) + + stmt.add_batch() + rows = stmt.execute() + print(rows) + stmt.close() + except Exception as e: + if 'Retry needed' in e.args[0]: # deal with [0x0125] Retry needed + continue + else: + raise e + + break diff --git a/docs/examples/python/stmt_websocket_example.py b/docs/examples/python/stmt_websocket_example.py new file mode 100644 index 0000000000..d0824cfa9f --- /dev/null +++ b/docs/examples/python/stmt_websocket_example.py @@ -0,0 +1,78 @@ +#! +import time + +import taosws + +import taos + + +def before_test(db_name): + taos_conn = taos.connect() + taos_conn.execute("drop database if exists %s" % db_name) + taos_conn.execute("create database %s" % db_name) + taos_conn.select_db(db_name) + taos_conn.execute("create table t1 (ts timestamp, a int, b float, c varchar(10))") + taos_conn.execute( + "create table stb1 (ts timestamp, a int, b float, c varchar(10)) tags (t1 int, t2 binary(10))") + taos_conn.close() + + +def after_test(db_name): + taos_conn = taos.connect() + taos_conn.execute("drop database if exists %s" % db_name) + taos_conn.close() + + +def stmt_insert(): + db_name = 'test_ws_stmt_{}'.format(int(time.time())) + before_test(db_name) + + conn = taosws.connect('taosws://root:taosdata@localhost:6041/%s' % db_name) + + stmt = conn.statement() + stmt.prepare("insert into t1 values (?, ?, ?, ?)") + + stmt.bind_param([ + taosws.millis_timestamps_to_column([1686844800000, 1686844801000, 1686844802000, 1686844803000]), + taosws.ints_to_column([1, 2, 3, 4]), + taosws.floats_to_column([1.1, 2.2, 3.3, 4.4]), + taosws.varchar_to_column(['a', 'b', 'c', 'd']), + ]) + + stmt.add_batch() + rows = stmt.execute() + assert rows == 4 + stmt.close() + after_test(db_name) + + +def stmt_insert_into_stable(): + db_name = 'test_ws_stmt_{}'.format(int(time.time())) + before_test(db_name) + + conn = taosws.connect("taosws://root:taosdata@localhost:6041/%s" % db_name) + + stmt = conn.statement() + stmt.prepare("insert into ? using stb1 tags (?, ?) values (?, ?, ?, ?)") + stmt.set_tbname('stb1_1') + stmt.set_tags([ + taosws.int_to_tag(1), + taosws.varchar_to_tag('aaa'), + ]) + stmt.bind_param([ + taosws.millis_timestamps_to_column([1686844800000, 1686844801000, 1686844802000, 1686844803000]), + taosws.ints_to_column([1, 2, 3, 4]), + taosws.floats_to_column([1.1, 2.2, 3.3, 4.4]), + taosws.varchar_to_column(['a', 'b', 'c', 'd']), + ]) + + stmt.add_batch() + rows = stmt.execute() + assert rows == 4 + stmt.close() + after_test(db_name) + + +if __name__ == '__main__': + stmt_insert() + stmt_insert_into_stable() diff --git a/docs/zh/08-connector/30-python.mdx b/docs/zh/08-connector/30-python.mdx index 10fb2238ee..f4f1aad63b 100644 --- a/docs/zh/08-connector/30-python.mdx +++ b/docs/zh/08-connector/30-python.mdx @@ -672,6 +672,141 @@ consumer.close() +### 通过参数绑定写入数据 + +TDengine 的 Python 连接器支持参数绑定风格的 Prepare API 方式写入数据,和大多数数据库类似,目前仅支持用 `?` 来代表待绑定的参数。 + + + + +#### 创建 stmt + +Python 连接器的 `Connection` 提供了 `statement` 方法用于创建参数绑定对象 stmt,该方法接收 sql 字符串作为参数,sql 字符串目前仅支持用 `?` 来代表绑定的参数。 + +``` +import taos + +conn = taos.connect() +stmt = conn.statement("insert into log values(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)") +``` + +#### 参数绑定 + +调用 `new_multi_binds` 函数创建 params 列表,用于参数绑定。 + +``` +params = new_multi_binds(16) +params[0].timestamp((1626861392589, 1626861392590, 1626861392591)) +params[1].bool((True, None, False)) +params[2].tinyint([-128, -128, None]) # -128 is tinyint null +params[3].tinyint([0, 127, None]) +params[4].smallint([3, None, 2]) +params[5].int([3, 4, None]) +params[6].bigint([3, 4, None]) +params[7].tinyint_unsigned([3, 4, None]) +params[8].smallint_unsigned([3, 4, None]) +params[9].int_unsigned([3, 4, None]) +params[10].bigint_unsigned([3, 4, None]) +params[11].float([3, None, 1]) +params[12].double([3, None, 1.2]) +params[13].binary(["abc", "dddafadfadfadfadfa", None]) +params[14].nchar(["涛思数据", None, "a long string with 中文字符"]) +params[15].timestamp([None, None, 1626861392591]) +``` + +调用 stmt 的 `bind_param` 以单行的方式设置 values 或 `bind_param_batch` 以多行的方式设置 values 方法绑定参数。 + +``` +stmt.bind_param_batch(params) +``` + +#### 执行 sql + +调用 stmt 的 `execute` 方法执行 sql + +``` +stmt.execute() +``` + +#### 关闭 stmt + +最后需要关闭 stmt。 + +``` +stmt.close() +``` + +#### 示例代码 + +```python +{{#include docs/examples/python/stmt_example.py}} +``` + + + + +#### 创建 stmt + +Python WebSocket 连接器的 `Connection` 提供了 `statement` 方法用于创建参数绑定对象 stmt,该方法接收 sql 字符串作为参数,sql 字符串目前仅支持用 `?` 来代表绑定的参数。 + +``` +import taosws + +conn = taosws.connect('taosws://localhost:6041/test') +stmt = conn.statement() +``` + +#### 解析 sql + +调用 stmt 的 `prepare` 方法来解析 insert 语句。 + +``` +stmt.prepare("insert into t1 values (?, ?, ?, ?)") +``` + +#### 参数绑定 + +调用 stmt 的 `bind_param` 方法绑定参数。 + +``` +stmt.bind_param([ + taosws.millis_timestamps_to_column([1686844800000, 1686844801000, 1686844802000, 1686844803000]), + taosws.ints_to_column([1, 2, 3, 4]), + taosws.floats_to_column([1.1, 2.2, 3.3, 4.4]), + taosws.varchar_to_column(['a', 'b', 'c', 'd']), +]) +``` + +调用 stmt 的 `add_batch` 方法,将参数加入批处理。 + +``` +stmt.add_batch() +``` + +#### 执行 sql + +调用 stmt 的 `execute` 方法执行 sql + +``` +stmt.execute() +``` + +#### 关闭 stmt + +最后需要关闭 stmt。 + +``` +stmt.close() +``` + +#### 示例代码 + +```python +{{#include docs/examples/python/stmt_websocket_example.py}} +``` + + + ### 其它示例程序 | 示例程序链接 | 示例程序内容 |