homework-jianmu/docs/en/07-develop/02-sql.md

title	sidebar_label	slug
Running SQL Statements	Running SQL Statements	/developer-guide/running-sql-statements

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

TDengine provides comprehensive support for SQL, allowing users to perform data queries, inserts, and deletions using familiar SQL syntax. TDengine's SQL also supports database and table management operations, such as creating, modifying, and deleting databases and tables. TDengine extends standard SQL by introducing features specific to time-series data processing, such as aggregation queries, downsampling, and interpolation queries, to accommodate the characteristics of time-series data. These extensions enable users to handle time-series data more efficiently and conduct complex data analysis and processing. For specific supported SQL syntax, please refer to TDengine SQL.

Below is an introduction to how to use various language connectors to execute SQL commands for creating databases, creating tables, inserting data, and querying data.

:::note

REST connection: Each programming language's connector encapsulates the connection using HTTP requests, supporting data writing and querying operations. Developers still access TDengine through the interfaces provided by the connector.
REST API: Directly calls the REST API interface provided by taosadapter to perform data writing and querying operations. Code examples demonstrate using the curl command.

:::

Create Database and Table

Using a smart meter as an example, below demonstrates how to execute SQL commands using various language connectors to create a database named power and then set power as the default database. Next, it creates a supertable named meters, with columns including timestamp, current, voltage, phase, and tags for group ID and location.

{{#include docs/examples/java/src/main/java/com/taos/example/JdbcCreatDBDemo.java:create_db_and_table}}

{{#include docs/examples/python/create_db_ws.py}}

{{#include docs/examples/python/create_db_native.py}}

{{#include docs/examples/python/create_db_rest.py}}

{{#include docs/examples/go/sqlquery/main.go:create_db_and_table}}

{{#include docs/examples/rust/nativeexample/examples/createdb.rs:create_db_and_table}}

{{#include docs/examples/node/websocketexample/sql_example.js:create_db_and_table}}

{{#include docs/examples/csharp/wsInsert/Program.cs:create_db_and_table}}

{{#include docs/examples/c-ws/create_db_demo.c:create_db_and_table}}

{{#include docs/examples/c/create_db_demo.c:create_db_and_table}}

Create Database

curl --location -uroot:taosdata 'http://127.0.0.1:6041/rest/sql' \
--data 'CREATE DATABASE IF NOT EXISTS power'

Create Table, specifying the database as power in the URL

curl --location -uroot:taosdata 'http://127.0.0.1:6041/rest/sql/power' \
--data 'CREATE STABLE IF NOT EXISTS meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId INT, location BINARY(24))'

:::note

It is recommended to construct SQL statements using the <dbName>.<tableName> format; using the USE DBName approach in the application is not recommended.

:::

Insert Data

Using a smart meter as an example, below demonstrates how to execute SQL to insert data into the meters supertable in the power database. The example uses TDengine's automatic table creation SQL syntax to write 3 data entries into the d1001 subtable and 1 data entry into the d1002 subtable, and then prints the actual number of inserted data entries.

{{#include docs/examples/java/src/main/java/com/taos/example/JdbcInsertDataDemo.java:insert_data}}

:::note

NOW is an internal function that defaults to the current time of the client's computer. NOW + 1s means the client's current time plus 1 second; the number after represents the time unit: a (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks), n (months), y (years).

:::

{{#include docs/examples/python/insert_ws.py}}

{{#include docs/examples/python/insert_native.py}}

{{#include docs/examples/python/insert_rest.py}}

{{#include docs/examples/go/sqlquery/main.go:insert_data}}

{{#include docs/examples/rust/nativeexample/examples/insert.rs:insert_data}}

{{#include docs/examples/node/websocketexample/sql_example.js:insertData}}

{{#include docs/examples/csharp/wsInsert/Program.cs:insert_data}}

{{#include docs/examples/c-ws/insert_data_demo.c:insert_data}}

{{#include docs/examples/c/insert_data_demo.c:insert_data}}

:::note

NOW is an internal function that defaults to the current time of the client's computer. NOW + 1s means the client's current time plus 1 second; the number after represents the time unit: a (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks), n (months), y (years).

:::

Write Data

curl --location -uroot:taosdata 'http://127.0.0.1:6041/rest/sql' \
--data 'INSERT INTO power.d1001 USING power.meters TAGS(2,'\''California.SanFrancisco'\'') VALUES (NOW + 1a, 10.30000, 219, 0.31000) (NOW + 2a, 12.60000, 218, 0.33000) (NOW + 3a, 12.30000, 221, 0.31000) power.d1002 USING power.meters TAGS(3, '\''California.SanFrancisco'\'') VALUES (NOW + 1a, 10.30000, 218, 0.25000)'

Query Data

Using a smart meter as an example, below demonstrates how to execute SQL using various language connectors to query data, retrieving up to 100 rows from the meters supertable in the power database and printing the results line by line.

{{#include docs/examples/java/src/main/java/com/taos/example/JdbcQueryDemo.java:query_data}}

:::note

Query operations are consistent with relational databases. When accessing return field content using indexes, start from 1; it is recommended to use field names for retrieval.

:::

{{#include docs/examples/python/query_ws.py}}

{{#include docs/examples/python/query_native.py}}

{{#include docs/examples/python/query_rest.py}}

{{#include docs/examples/go/sqlquery/main.go:select_data}}

{{#include docs/examples/rust/nativeexample/examples/query.rs:query_data}}

The Rust connector also supports using serde for deserialization to obtain results as structured data:

{{#include docs/examples/rust/nativeexample/examples/query.rs:query_data_2}}

{{#include docs/examples/node/websocketexample/sql_example.js:queryData}}

{{#include docs/examples/csharp/wsInsert/Program.cs:select_data}}

{{#include docs/examples/c-ws/query_data_demo.c:query_data}}

{{#include docs/examples/c/query_data_demo.c:query_data}}

Query Data

curl --location -uroot:taosdata 'http://127.0.0.1:6041/rest/sql' \
--data 'SELECT ts, current, location FROM power.meters limit 100'

Execute SQL with reqId

reqId can be used for request tracing. It acts similarly to traceId in distributed systems. A request may need to go through multiple services or modules to complete. reqId is used to identify and associate all related operations for this request, making it easier to trace and analyze the complete path of the request.

Benefits of using reqId include:

• Request tracing: By associating the same reqId with all related operations of a request, you can trace the complete path of the request within the system.
• Performance analysis: Analyzing a request's reqId allows you to understand the processing time across various services and modules, helping to identify performance bottlenecks.
• Fault diagnosis: When a request fails, you can find out where the issue occurred by examining the reqId associated with that request.

If users do not set a reqId, the connector will randomly generate one internally, but it is recommended to set it explicitly for better association with user requests.

Below are code samples for setting reqId while executing SQL with various language connectors.

{{#include docs/examples/java/src/main/java/com/taos/example/JdbcReqIdDemo.java:with_reqid}}

{{#include docs/examples/python/reqid_ws.py}}

{{#include docs/examples/python/reqid_native.py}}

{{#include docs/examples/python/reqid_rest.py}}

{{#include docs/examples/go/queryreqid/main.go:query_id}}

{{#include docs/examples/rust/nativeexample/examples/query.rs:query_with_req_id}}

{{#include docs/examples/node/websocketexample/sql_example.js:sqlWithReqid}}

{{#include docs/examples/csharp/wsInsert/Program.cs:query_id}}

{{#include docs/examples/c-ws/with_reqid_demo.c:with_reqid}}

{{#include docs/examples/c/with_reqid_demo.c:with_reqid}}

Query Data, specifying reqId as 3

curl --location -uroot:taosdata 'http://127.0.0.1:6041/rest/sql?req_id=3' \
--data 'SELECT ts, current, location FROM power.meters limit 1'