07-python.mdx

---
title: TDengine Python Connector
sidebar_label: Python
description: This document describes taospy, the TDengine Python connector.
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

`taospy` is the official Python connector for TDengine. taospy provides a rich API that makes it easy for Python applications to use TDengine. `taospy` wraps both the [native interface](/reference/connector/cpp) and [REST interface](/reference/rest-api) of TDengine, which correspond to the `taos` and `taosrest` modules of the `taospy` package, respectively.
In addition to wrapping the native and REST interfaces, `taospy` also provides a set of programming interfaces that conforms to the [Python Data Access Specification (PEP 249)](https://peps.python.org/pep-0249/). It is easy to integrate `taospy` with many third-party tools, such as [SQLAlchemy](https://www.sqlalchemy.org/) and [pandas](https://pandas.pydata.org/).

`taos-ws-py` is an optional package to enable using WebSocket to connect TDengine.

The direct connection to the server using the native interface provided by the client driver is referred to hereinafter as a "native connection"; the connection to the server using the REST or WebSocket interface provided by taosAdapter is referred to hereinafter as a "REST connection" or "WebSocket connection".

The source code for the Python connector is hosted on [GitHub](https://github.com/taosdata/taos-connector-python).
## Supported platforms

- The [supported platforms](/reference/connector/#supported-platforms) for the native connection are the same as the ones supported by the TDengine client.
- REST connections are supported on all platforms that can run Python.

### Supported features

- Native connections support all the core features of TDengine, including connection management, SQL execution, bind interface, subscriptions, and schemaless writing.
- REST connections support features such as connection management and SQL execution. (SQL execution allows you to: manage databases, tables, and supertables, write data, query data, create continuous queries, etc.).

## Version selection

We recommend using the latest version of `taospy`, regardless of the version of TDengine.

|Python Connector Version|major changes|
|:-------------------:|:----:|
|2.7.9|support for getting assignment and seek function on subscription|
|2.7.8|add `execute_many` method|

|Python Websocket Connector Version|major changes|
|:----------------------------:|:-----:|
|0.2.5|1. support for getting assignment and seek function on subscription <br/> 2. support schemaless <br/> 3. support STMT|
|0.2.4|support `unsubscribe` on subscription|

## Handling Exceptions

There are 4 types of exception in python connector.

- The exception of Python Connector itself.
- The exception of native library.
- The exception of websocket
- The exception of subscription.
- The exception of other TDengine function modules.

|Error Type|Description|Suggested Actions|
|:--------:|:---------:|:---------------:|
|InterfaceError|the native library is too old that it cannot support the function|please check the TDengine client version|
|ConnectionError|connection error|please check TDengine's status and the connection params|
|DatabaseError|database error|please upgrade Python connector to latest|
|OperationalError|operation error||
|ProgrammingError|||
|StatementError|the exception of stmt||
|ResultError|||
|SchemalessError|the exception of stmt schemaless||
|TmqError|the exception of stmt tmq||

It usually uses try-expect to handle exceptions in python. For exception handling, please refer to [Python Errors and Exceptions Documentation](https://docs.python.org/3/tutorial/errors.html).

All exceptions from the Python Connector are thrown directly. Applications should handle these exceptions. For example:

```python
{{#include docs/examples/python/handle_exception.py}}
```

## TDengine DataType vs. Python DataType

TDengine currently supports timestamp, number, character, Boolean type, and the corresponding type conversion with Python is as follows:

|TDengine DataType|Python DataType|
|:---------------:|:-------------:|
|TIMESTAMP|datetime|
|INT|int|
|BIGINT|int|
|FLOAT|float|
|DOUBLE|int|
|SMALLINT|int|
|TINYINT|int|
|BOOL|bool|
|BINARY|str|
|NCHAR|str|
|JSON|str|

## Installation Steps

### Pre-installation preparation

1. Install Python. The recent taospy package requires Python 3.6.2+. The earlier versions of taospy require Python 3.7+.  The taos-ws-py package requires Python 3.7+. If Python is not available on your system, refer to the [Python BeginnersGuide](https://wiki.python.org/moin/BeginnersGuide/Download) to install it.
2. Install [pip](https://pypi.org/project/pip/). In most cases, the Python installer comes with the pip utility. If not, please refer to [pip documentation](https://pip.pypa.io/en/stable/installation/) to install it.
If you use a native connection, you will also need to [Install Client Driver](/reference/connector#Install-Client-Driver). The client install package includes the TDengine client dynamic link library (`libtaos.so` or `taos.dll`) and the TDengine CLI.

### Install via pip

#### Uninstalling an older version

If you have installed an older version of the Python Connector, please uninstall it beforehand.

```
pip3 uninstall taos taospy
```

:::note
Earlier TDengine client software includes the Python connector. If the Python connector is installed from the client package's installation directory, the corresponding Python package name is `taos`. So the above uninstall command includes `taos`, and it doesn't matter if it doesn't exist.

:::

#### To install `taospy`

<Tabs>
<TabItem label="Install from PyPI" value="pypi">

Install the latest version of:

```
pip3 install taospy
```

You can also specify a specific version to install:

```
pip3 install taospy==2.3.0
```

</TabItem>
<TabItem label="Install from GitHub" value="github">

```
pip3 install git+https://github.com/taosdata/taos-connector-python.git
```

</TabItem>
</Tabs>

#### Install `taos-ws-py` (Optional)

The taos-ws-py package provides the way to access TDengine via WebSocket.

##### Install taos-ws-py with taospy

```bash
pip3 install taospy[ws]
```

##### Install taos-ws-py only

```bash
pip3 install taos-ws-py
```

### Verify

<Tabs defaultValue="rest">
<TabItem value="native" label="native connection">

For native connection, you need to verify that both the client driver and the Python connector itself are installed correctly. The client driver and Python connector have been installed properly if you can successfully import the `taos` module. In the Python Interactive Shell, you can type.

```python
import taos
```

</TabItem>
<TabItem value="rest" label="REST connection">

For REST connections, verifying that the `taosrest` module can be imported successfully can be done in the Python Interactive Shell by typing.

```python
import taosrest
```

</TabItem>
<TabItem  value="ws" label="WebSocket connection">

For WebSocket connection, verifying that the `taosws` module can be imported successfully can be done in the Python Interactive Shell by typing.

```python
import taosws
```

</TabItem>
</Tabs>

:::tip
If you have multiple versions of Python on your system, you may have various `pip` commands. Be sure to use the correct path for the `pip` command. Above, we installed the `pip3` command, which rules out the possibility of using the `pip` corresponding to Python 2.x versions. However, if you have more than one version of Python 3.x on your system, you still need to check that the installation path is correct. The easiest way to verify this is to type `pip3 install taospy` again in the command, and it will print out the exact location of `taospy`, for example, on Windows.

```
C:\> pip3 install taospy
Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple
Requirement already satisfied: taospy in c:\users\username\appdata\local\programs\python\python310\lib\site-packages (2.3.0)
```

:::

## Establishing a connection

### Connectivity testing

Before establishing a connection with the connector, we recommend testing the connectivity of the local TDengine CLI to the TDengine cluster.

<Tabs defaultValue="rest">
<TabItem value="native" label="native connection">

Ensure that the TDengine instance is up and that the FQDN of the machines in the cluster (the FQDN defaults to hostname if you are starting a stand-alone version) can be resolved locally, by testing with the `ping` command.

```
ping <FQDN>
```

Then test if the cluster can be appropriately connected with TDengine CLI:

```
taos -h <FQDN> -p <PORT>
```

The FQDN above can be the FQDN of any dnode in the cluster, and the PORT is the serverPort corresponding to this dnode.

</TabItem>
<TabItem value="rest" label="REST connection" groupId="connect">

For REST connections, make sure the cluster and taosAdapter component, are running. This can be tested using the following `curl ` command.

```
curl -u root:taosdata http://<FQDN>:<PORT>/rest/sql -d "select server_version()"
```

The FQDN above is the FQDN of the machine running taosAdapter, PORT is the port taosAdapter listening, default is `6041`.
If the test is successful, it will output the server version information, e.g.

```json
{
  "code": 0,
  "column_meta": [
    [
      "server_version()",
      "VARCHAR",
      7
    ]
  ],
  "data": [
    [
      "3.0.0.0"
    ]
  ],
  "rows": 1
}
```

</TabItem>
<TabItem value="ws" label="WebSocket connection" groupId="connect">

For WebSocket connection, make sure the cluster and taosAdapter component, are running. This can be testetd using the following `curl` command.

```
curl -i -N -d "show databases" -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Host: <FQDN>:<PORT>" -H "Origin: http://<FQDN>:<PORT>" http://<FQDN>:<PORT>/rest/sql
```

The FQDN above is the FQDN of the machine running taosAdapter, PORT is the port taosAdapter listening, default is `6041`.

If the test is successful, it will output the server version information, e.g.

```json
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 21 Mar 2023 09:29:17 GMT
Transfer-Encoding: chunked

{"status":"succ","head":["server_version()"],"column_meta":[["server_version()",8,8]],"data":[["2.6.0.27"]],"rows":1}
```

</TabItem>
</Tabs>

### Specify the Host and Properties to get the connection

The following example code assumes that TDengine is installed locally and that the default configuration is used for both FQDN and serverPort.

<Tabs defaultValue="rest">
<TabItem value="native" label="native connection" groupId="connect">

```python
{{#include docs/examples/python/connect_native_reference.py}}
```

All arguments of the `connect()` function are optional keyword arguments. The following are the connection parameters specified.

- `host` : The FQDN of the node to connect to. There is no default value. If this parameter is not provided, the firstEP in the client configuration file will be connected.
- `user` : The TDengine user name. The default value is `root`.
- `password` : TDengine user password. The default value is `taosdata`.
- `port` : The starting port of the data node to connect to, i.e., the serverPort configuration. The default value is 6030, which will only take effect if the host parameter is provided.
- `config` : The path to the client configuration file. On Windows systems, the default is `C:\TDengine\cfg`. The default is `/etc/taos/` on Linux/macOS.
- `timezone` : The timezone used to convert the TIMESTAMP data in the query results to python `datetime` objects. The default is the local timezone.

:::warning
`config` and `timezone` are both process-level configurations. We recommend that all connections made by a process use the same parameter values. Otherwise, unpredictable errors may occur.
:::

:::tip
The `connect()` function returns a `taos.TaosConnection` instance. In client-side multi-threaded scenarios, we recommend that each thread request a separate connection instance rather than sharing a connection between multiple threads.

:::

</TabItem>
<TabItem value="rest" label="REST connection">

```python
{{#include docs/examples/python/connect_rest_examples.py:connect}}
```

All arguments to the `connect()` function are optional keyword arguments. The following are the connection parameters specified.

- `url`: The URL of taosAdapter REST service. The default is <http://localhost:6041>.
- `user`: TDengine user name. The default is `root`.
- `password`: TDengine user password. The default is `taosdata`.
- `timeout`: HTTP request timeout. Enter a value in seconds. The default is `socket._GLOBAL_DEFAULT_TIMEOUT`. Usually, no configuration is needed.

</TabItem>

<TabItem value="websocket" label="WebSocket connection">

```python
{{#include docs/examples/python/connect_websocket_examples.py:connect}}
```

The parameter of `connect()` is the url of TDengine, and the protocol is `taosws` or `ws`.

</TabItem>
</Tabs>

### Priority of configuration parameters

If the configuration parameters are duplicated in the parameters or client configuration file, the priority of the parameters, from highest to lowest, are as follows:

1. Parameters in `connect` function.
2. the configuration file taos.cfg of the TDengine client driver when using a native connection.

## Usage examples

### Create database and tables

<Tabs defaultValue="rest">
<TabItem value="native" label="native connection">

```python
conn = taos.connect()
# Execute a sql, ignore the result set, just get affected rows. It's useful for DDL and DML statement.
conn.execute("DROP DATABASE IF EXISTS test")
conn.execute("CREATE DATABASE test")
# change database. same as execute "USE db"
conn.select_db("test")
conn.execute("CREATE STABLE weather(ts TIMESTAMP, temperature FLOAT) TAGS (location INT)")
```

</TabItem>

<TabItem value="rest" label="REST connection">

```python
conn = taosrest.connect(url="http://localhost:6041")
# Execute a sql, ignore the result set, just get affected rows. It's useful for DDL and DML statement.
conn.execute("DROP DATABASE IF EXISTS test")
conn.execute("CREATE DATABASE test")
conn.execute("USE test")
conn.execute("CREATE STABLE weather(ts TIMESTAMP, temperature FLOAT) TAGS (location INT)")
```

</TabItem>

<TabItem value="websocket" label="WebSocket connection">

```python
conn = taosws.connect(url="ws://localhost:6041")
# Execute a sql, ignore the result set, just get affected rows. It's useful for DDL and DML statement.
conn.execute("DROP DATABASE IF EXISTS test")
conn.execute("CREATE DATABASE test")
conn.execute("USE test")
conn.execute("CREATE STABLE weather(ts TIMESTAMP, temperature FLOAT) TAGS (location INT)")
```

</TabItem>
</Tabs>

### Insert data

```python
conn.execute("INSERT INTO t1 USING weather TAGS(1) VALUES (now, 23.5) (now+1m, 23.5) (now+2m, 24.4)")
```

:::
now is an internal function. The default is the current time of the client's computer. now + 1s represents the current time of the client plus 1 second, followed by the number representing the unit of time: a (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks), n (months), y (years).
:::


### Basic Usage

<Tabs defaultValue="rest">
<TabItem value="native" label="native connection">

##### TaosConnection class

The `TaosConnection` class contains both an implementation of the PEP249 Connection interface (e.g., the `cursor()` method and the `close()` method) and many extensions (e.g., the `execute()`, `query()`, `schemaless_insert()`, and `subscribe()` methods).

```python title="execute method"
{{#include docs/examples/python/connection_usage_native_reference.py:insert}}
```

```python title="query method"
{{#include docs/examples/python/connection_usage_native_reference.py:query}}
```

:::tip
The queried results can only be fetched once. For example, only one of `fetch_all()` and `fetch_all_into_dict()` can be used in the example above. Repeated fetches will result in an empty list.
:::

##### Use of TaosResult class

In the above example of using the `TaosConnection` class, we have shown two ways to get the result of a query: `fetch_all()` and `fetch_all_into_dict()`. In addition, `TaosResult` also provides methods to iterate through the result set by rows (`rows_iter`) or by data blocks (`blocks_iter`). Using these two methods will be more efficient in scenarios where the query has a large amount of data.

```python title="blocks_iter method"
{{#include docs/examples/python/result_set_examples.py}}
```
##### Use of the TaosCursor class

The `TaosConnection` class and the `TaosResult` class already implement all the functionality of the native interface. If you are familiar with the interfaces in the PEP249 specification, you can also use the methods provided by the `TaosCursor` class.

```python title="Use of TaosCursor"
{{#include docs/examples/python/cursor_usage_native_reference.py}}
```

:::note
The TaosCursor class uses native connections for write and query operations. In a client-side multi-threaded scenario, this cursor instance must remain thread exclusive and cannot be shared across threads for use, otherwise, it will result in errors in the returned results.

:::

</TabItem>
<TabItem value="rest" label="REST connection">

##### Use of TaosRestCursor class

The `TaosRestCursor` class is an implementation of the PEP249 Cursor interface.

```python title="Use of TaosRestCursor"
{{#include docs/examples/python/connect_rest_examples.py:basic}}
```
- `cursor.execute`: Used to execute arbitrary SQL statements.
- `cursor.rowcount` : For write operations, returns the number of successful rows written. For query operations, returns the number of rows in the result set.
- `cursor.description` : Returns the description of the field. Please refer to [TaosRestCursor](https://docs.taosdata.com/api/taospy/taosrest/cursor.html) for the specific format of the description information.

##### Use of the RestClient class

The `RestClient` class is a direct wrapper for the [REST API](/reference/rest-api). It contains only a `sql()` method for executing arbitrary SQL statements and returning the result.

```python title="Use of RestClient"
{{#include docs/examples/python/rest_client_example.py}}
```

For a more detailed description of the `sql()` method, please refer to [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html).

</TabItem>
<TabItem value="websocket" label="WebSocket connection">

The `Connection` class contains both an implementation of the PEP249 Connection interface (e.g., the `cursor()` method and the `close()` method) and many extensions (e.g., the `execute()`, `query()`, `schemaless_insert()`, and `subscribe()` methods).

```python
{{#include docs/examples/python/connect_websocket_examples.py:basic}}
```

- `conn.execute`: can use to execute arbitrary SQL statements, and return the number of rows affected.
- `conn.query`: can use to execute query SQL statements, and return the query results.

</TabItem>
</Tabs>

### Querying Data

<Tabs defaultValue="rest">
<TabItem value="native" label="native connection">

The `query` method of the `TaosConnection` class can be used to query data and return the result data of type `TaosResult`.

```python
{{#include docs/examples/python/connection_usage_native_reference.py:query}}
```

:::tip
The queried results can only be fetched once. For example, only one of `fetch_all()` and `fetch_all_into_dict()` can be used in the example above. Repeated fetches will result in an empty list.
:::

</TabItem>

<TabItem value="rest" label="REST connection">

The `RestClient` class is a direct wrapper for the [REST API](/reference/rest-api). It contains only a `sql()` method for executing arbitrary SQL statements and returning the result.

```python
{{#include docs/examples/python/rest_client_example.py}}
```

For a more detailed description of the `sql()` method, please refer to [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html).

</TabItem>

<TabItem value="websocket" label="WebSocket connection">

The `query` method of the `TaosConnection` class can be used to query data and return the result data of type `TaosResult`.

```python
{{#include docs/examples/python/connect_websocket_examples.py:basic}}
```

</TabItem>
</Tabs>

### Execute SQL with reqId

By using the optional req_id parameter, you can specify a request ID that can be used for tracing.

<Tabs defaultValue="rest">
<TabItem value="native" label="native connection">

##### TaosConnection class

As the way to connect introduced above but add `req_id` argument.

```python title="execute method"
{{#include docs/examples/python/connection_usage_native_reference_with_req_id.py:insert}}
```

```python title="query method"
{{#include docs/examples/python/connection_usage_native_reference_with_req_id.py:query}}
```

##### Use of TaosResult class

As the way to fetch data introduced above but add `req_id` argument.

```python title="blocks_iter method"
{{#include docs/examples/python/result_set_with_req_id_examples.py}}
```
##### Use of the TaosCursor class

The `TaosConnection` class and the `TaosResult` class already implement all the functionality of the native interface. If you are familiar with the interfaces in the PEP249 specification, you can also use the methods provided by the `TaosCursor` class.

```python title="Use of TaosCursor"
{{#include docs/examples/python/cursor_usage_native_reference_with_req_id.py}}
```

</TabItem>
<TabItem value="rest" label="REST connection">

##### Use of TaosRestCursor class

As the way to connect introduced above but add `req_id` argument.

```python title="Use of TaosRestCursor"
{{#include docs/examples/python/connect_rest_with_req_id_examples.py:basic}}
```
- `cursor.execute`: Used to execute arbitrary SQL statements.
- `cursor.rowcount` : For write operations, returns the number of successful rows written. For query operations, returns the number of rows in the result set.
- `cursor.description` : Returns the description of the field. Please refer to [TaosRestCursor](https://docs.taosdata.com/api/taospy/taosrest/cursor.html) for the specific format of the description information.

##### Use of the RestClient class

The `RestClient` class is a direct wrapper for the [REST API](/reference/rest-api). It contains only a `sql()` method for executing arbitrary SQL statements and returning the result.

```python title="Use of RestClient"
{{#include docs/examples/python/rest_client_with_req_id_example.py}}
```

For a more detailed description of the `sql()` method, please refer to [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html).

</TabItem>

<TabItem value="websocket" label="WebSocket connection">

As the way to connect introduced above but add `req_id` argument.

```python
{{#include docs/examples/python/connect_websocket_with_req_id_examples.py:basic}}
```

- `conn.execute`: can use to execute arbitrary SQL statements, and return the number of rows affected.
- `conn.query`: can use to execute query SQL statements, and return the query results.

</TabItem>
</Tabs>

### Used with pandas

<Tabs defaultValue="rest">
<TabItem value="native" label="native connection">

```python
{{#include docs/examples/python/conn_native_pandas.py}}
```

</TabItem>
<TabItem value="rest" label="REST connection">

```python
{{#include docs/examples/python/conn_rest_pandas.py}}
```

</TabItem>
<TabItem value="websocket" label="WebSocket connection">

```python
{{#include docs/examples/python/conn_websocket_pandas.py}}
```

</TabItem>
</Tabs>

### Writing data via 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.

<Tabs>
<TabItem value="native" label="native connection">

##### 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}}
```
</TabItem>

<TabItem value="websocket" label="WebSocket connection">

##### 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}}
```
</TabItem>
</Tabs>

### Schemaless Writing

Connector support schemaless insert.

<Tabs defaultValue="list">
<TabItem value="list" label="List Insert">

##### Simple insert

```python
{{#include docs/examples/python/schemaless_insert.py}}
```

##### Insert with ttl argument

```python
{{#include docs/examples/python/schemaless_insert_ttl.py}}
```

##### Insert with req_id argument

```python
{{#include docs/examples/python/schemaless_insert_req_id.py}}
```

</TabItem>

<TabItem value="raw" label="Raw Insert">

##### Simple insert

```python
{{#include docs/examples/python/schemaless_insert_raw.py}}
```

##### Insert with ttl argument

```python
{{#include docs/examples/python/schemaless_insert_raw_ttl.py}}
```

##### Insert with req_id argument

```python
{{#include docs/examples/python/schemaless_insert_raw_req_id.py}}
```

</TabItem>
</Tabs>

### Schemaless with reqId

There is a optional parameter called `req_id` in `schemaless_insert` and `schemaless_insert_raw` method. This reqId can be used to request link tracing.

```python
{{#include docs/examples/python/schemaless_insert_req_id.py}}
```

```python
{{#include docs/examples/python/schemaless_insert_raw_req_id.py}}
```

### Data Subscription

Connector support data subscription. For more information about subscroption, please refer to [Data Subscription](../../../develop/tmq/).

#### Create a Topic

To create topic, please refer to [Data Subscription](../../../develop/tmq/#create-a-topic).

#### Create a Consumer

<Tabs defaultValue="native">

<TabItem value="native" label="native connection">

The consumer in the connector contains the subscription api. The syntax for creating a consumer is consumer = Consumer(configs). For more subscription api parameters, please refer to [Data Subscription](../../../develop/tmq/#create-a-consumer).

```python
from taos.tmq import Consumer

consumer = Consumer({"group.id": "local", "td.connect.ip": "127.0.0.1"})
```
</TabItem>

<TabItem value="websocket" label="WebSocket connection">

In addition to native connections, the connector also supports subscriptions via websockets.

The syntax for creating a consumer is "consumer = consumer = Consumer(conf=configs)". You need to specify that the `td.connect.websocket.scheme` parameter is set to "ws" in the configuration. For more subscription api parameters, please refer to [Data Subscription](../../../develop/tmq/#create-a-consumer).

```python
import taosws

consumer = taosws.(conf={"group.id": "local", "td.connect.websocket.scheme": "ws"})
```

</TabItem>
</Tabs>

#### Subscribe to a Topic

<Tabs defaultValue="native">

<TabItem value="native" label="native connection">

The `subscribe` function is used to subscribe to a list of topics.

```python
consumer.subscribe(['topic1', 'topic2'])
```

</TabItem>
<TabItem value="websocket" label="WebSocket connection">

The `subscribe` function is used to subscribe to a list of topics.

```python
consumer.subscribe(['topic1', 'topic2'])
```

</TabItem>
</Tabs>

#### Consume messages

<Tabs defaultValue="native">

<TabItem value="native" label="native connection">

The `poll` function is used to consume data in tmq. The parameter of the `poll` function is a value of type float representing the timeout in seconds. It returns a `Message` before timing out, or `None` on timing out. You have to handle error messages in response data.

```python
while True:
    res = consumer.poll(1)
    if not res:
        continue
    err = res.error()
    if err is not None:
        raise err
    val = res.value()

    for block in val:
        print(block.fetchall())
```

</TabItem>
<TabItem value="websocket" label="WebSocket connection">

The `poll` function is used to consume data in tmq. The parameter of the `poll` function is a value of type float representing the timeout in seconds. It returns a `Message` before timing out, or `None` on timing out. You have to handle error messages in response data.

```python
while True:
    res = consumer.poll(timeout=1.0)
    if not res:
        continue
    err = res.error()
    if err is not None:
        raise err
    for block in message:
        for row in block:
            print(row)
```

</TabItem>
</Tabs>

#### Assignment subscription Offset

<Tabs defaultValue="native">

<TabItem value="native" label="native connection">

The `assignment` function is used to get the assignment of the topic. 

```python
assignments = consumer.assignment()
```

The `seek` function is used to reset the assignment of the topic.

```python
tp = TopicPartition(topic='topic1', partition=0, offset=0)
consumer.seek(tp)
```

</TabItem>
<TabItem value="websocket" label="WebSocket connection">

The `assignment` function is used to get the assignment of the topic. 

```python
assignments = consumer.assignment()
```

The `seek` function is used to reset the assignment of the topic.

```python
consumer.seek(topic='topic1', partition=0, offset=0)
```

</TabItem>
</Tabs>

#### Close subscriptions

<Tabs defaultValue="native">

<TabItem value="native" label="native connection">

You should unsubscribe to the topics and close the consumer after consuming.

```python
consumer.unsubscribe()
consumer.close()
```

</TabItem>
<TabItem value="websocket" label="WebSocket connection">

You should unsubscribe to the topics and close the consumer after consuming.

```python
consumer.unsubscribe()
consumer.close()
```

</TabItem>
</Tabs>

#### Full Sample Code

<Tabs defaultValue="native">

<TabItem value="native" label="native connection">

```python
{{#include docs/examples/python/tmq_example.py}}
```

```python
{{#include docs/examples/python/tmq_assignment_example.py:taos_get_assignment_and_seek_demo}}
```

</TabItem>
<TabItem value="websocket" label="WebSocket connection">

```python
{{#include docs/examples/python/tmq_websocket_example.py}}
```

```python
{{#include docs/examples/python/tmq_websocket_assgnment_example.py:taosws_get_assignment_and_seek_demo}}
```

</TabItem>
</Tabs>

### Other sample programs

| Example program links | Example program content |
| ------------------------------------------------------------------------------------------------------------- | ------------------- ---- |
| [bind_multi.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/bind-multi.py) | parameter binding, 
bind multiple rows at once |
| [bind_row.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/bind-row.py) | bind_row.py
| [insert_lines.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/insert-lines.py) | InfluxDB line protocol writing |
| [json_tag.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/json-tag.py) | Use JSON type tags |
| [tmq.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/tmq.py)                         | TMQ subscription              |

## Other notes 

### About nanoseconds

Due to the current imperfection of Python's nanosecond support (see link below), the current implementation returns integers at nanosecond precision instead of the `datetime` type produced by `ms` and `us`, which application developers will need to handle on their own. And it is recommended to use pandas' to_datetime(). The Python Connector may modify the interface in the future if Python officially supports nanoseconds in full.

1. https://stackoverflow.com/questions/10611328/parsing-datetime-strings-containing-nanoseconds
2. https://www.python.org/dev/peps/pep-0564/

## Important Update

[**Release Notes**] (https://github.com/taosdata/taos-connector-python/releases)

## API Reference

- [taos](https://docs.taosdata.com/api/taospy/taos/)
- [taosrest](https://docs.taosdata.com/api/taospy/taosrest)
  
## Frequently Asked Questions

Welcome to [ask questions or report questions](https://github.com/taosdata/taos-connector-python/issues).