xxq250
/
homework-jianmu
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Merge pull request #30427 from taosdata/merge/3.3.6tomain 

merge: from main to 3.0 branch
This commit is contained in:
Simon Guan 2025-03-25 10:31:44 +08:00 committed by GitHub
parent db3471f053 00d3a04a05
commit ce14972d8e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1187 changed files with 414335 additions and 19607 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.github/workflows/tdengine-build.yml vendored
View File

@ -74,6 +74,11 @@ jobs:
snappy \
zlib
- name: prepare install path
run: |
sudo mkdir -p /usr/local/lib
sudo mkdir -p /usr/local/include
- name: Build and install TDengine
run: |
mkdir debug && cd debug

2
.github/workflows/tdengine-test.yml vendored
View File

@ -6,12 +6,14 @@ on:
- 'main'
- '3.0'
- '3.1'
- '3.3.6'
paths-ignore:
- 'packaging/**'
- 'docs/**'
- 'tools/tdgpt/**'
- 'source/libs/executor/src/forecastoperator.c'
- 'source/libs/executor/src/anomalywindowoperator.c'
- 'source/dnode/mnode/impl/src/mndAnode.c'
- 'include/common/tanalytics.h'
- 'source/common/src/tanalytics.c'
- 'tests/parallel/tdgpt_cases.task'

203
.github/workflows/tdgpt-test.yml vendored Normal file
View File

@ -0,0 +1,203 @@
# Run unit-test and system-test cases for TDgpt when TDgpt code is changed.
name: TDgpt Test
on:
pull_request:
branches:
- 'main'
- '3.0'
- '3.3.6'
paths:
- 'tools/tdgpt/**'
- 'source/libs/executor/src/forecastoperator.c'
- 'source/libs/executor/src/anomalywindowoperator.c'
- 'source/dnode/mnode/impl/src/mndAnode.c'
- 'include/common/tanalytics.h'
- 'source/common/src/tanalytics.c'
- 'tests/parallel/tdgpt_cases.task'
- 'tests/script/tsim/analytics'
jobs:
unit-test:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
python-version: ["3.10"]
defaults:
run:
working-directory: ${{ github.workspace }}/tools/tdgpt
steps:
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v3
with:
python-version: ${{ matrix.python-version }}
cache: 'pip'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
python -m pip install flake8 pytest pylint
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
- name: Checking the code with pylint
run: |
pylint $(git ls-files '*.py') --exit-zero
- name: Checking the code with flake8
run: |
# stop the build if there are Python syntax errors or undefined names
flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
# exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
- name: Run test cases with pytest
run: |
pytest
function-test:
runs-on:
group: CI
labels: [self-hosted, Linux, X64, testing]
env:
CONTAINER_NAME: 'taosd-test'
WKDIR: '/var/lib/jenkins/workspace'
WK: '/var/lib/jenkins/workspace/TDinternal'
WKC: '/var/lib/jenkins/workspace/TDinternal/community'
SOURCE_BRANCH: ${{ github.event.pull_request.head.ref }}
TARGET_BRANCH: ${{ github.event.pull_request.base.ref }}
PR_NUMBER: ${{ github.event.pull_request.number }}
steps:
- name: Output the environment information
run: |
echo "::group::Environment Info"
date
hostname
env
echo "Runner: ${{ runner.name }}"
echo "Workspace: ${{ env.WKDIR }}"
git --version
echo "${{ env.WKDIR }}/restore.sh -p PR-${{ env.PR_NUMBER }} -n ${{ github.run_number }} -c ${{ env.CONTAINER_NAME }}"
echo "::endgroup::"
- name: Prepare repositories
run: |
set -euo pipefail
prepare_environment() {
cd "$1"
git reset --hard
git clean -f
git remote prune origin
git fetch
git checkout "$2"
}
prepare_environment "${{ env.WK }}" "${{ env.TARGET_BRANCH }}"
prepare_environment "${{ env.WKC }}" "${{ env.TARGET_BRANCH }}"
- name: Get latest codes and logs
run: |
cd ${{ env.WKC }}
git remote prune origin
git pull >/dev/null
git log -5
echo "`date "+%Y%m%d-%H%M%S"` TDengineTest/${{ env.PR_NUMBER }}:${{ github.run_number }}:${{ env.TARGET_BRANCH }}" >>${{ env.WKDIR }}/jenkins.log
echo "CHANGE_BRANCH:${{ env.SOURCE_BRANCH }}" >>${{ env.WKDIR }}/jenkins.log
echo "community log: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
git fetch origin +refs/pull/${{ env.PR_NUMBER }}/merge
git checkout -qf FETCH_HEAD
git log -5
echo "community log merged: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
cd ${{ env.WK }}
git pull >/dev/null
git log -5
echo "TDinternal log: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
- name: Update submodule
run: |
cd ${{ env.WKC }}
git submodule update --init --recursive
- name: Detect non-doc files changed
run: |
mkdir -p ${{ env.WKDIR }}/tmp/${{ env.PR_NUMBER }}_${{ github.run_number }}
cd ${{ env.WKC }}
changed_files_non_doc=$(git --no-pager diff --name-only \
FETCH_HEAD \
$(git merge-base FETCH_HEAD ${{ env.TARGET_BRANCH }}) | \
grep -v "^docs/en/" | \
grep -v "^docs/zh/" | \
grep -v ".md$" | \
tr '\n' ' ' || : \
)
echo $changed_files_non_doc > \
${{ env.WKDIR }}/tmp/${{ env.PR_NUMBER }}_${{ github.run_number }}/docs_changed.txt
- name: Check assert testing
run: |
cd ${{ env.WKC }}/tests/parallel_test
./run_check_assert_container.sh -d ${{ env.WKDIR }}
- name: Check void function testing
run: |
cd ${{ env.WKC }}/tests/parallel_test
./run_check_void_container.sh -d ${{ env.WKDIR }}
- name: Build docker container
run: |
date
rm -rf ${{ env.WKC }}/debug
cd ${{ env.WKC }}/tests/parallel_test
time ./container_build.sh -w ${{ env.WKDIR }} -e
- name: Get parameters for testing
id: get_param
run: |
log_server_file="/home/log_server.json"
timeout_cmd=""
extra_param=""
if [ -f "$log_server_file" ]; then
log_server_enabled=$(jq '.enabled' "$log_server_file")
timeout_param=$(jq '.timeout' "$log_server_file")
if [ "$timeout_param" != "null" ] && [ "$timeout_param" != "0" ]; then
timeout_cmd="timeout $timeout_param"
fi
if [ "$log_server_enabled" == "1" ]; then
log_server=$(jq '.server' "$log_server_file" | sed 's/\\\"//g')
if [ "$log_server" != "null" ] && [ "$log_server" != "" ]; then
extra_param="-w $log_server"
fi
fi
fi
echo "timeout_cmd=$timeout_cmd" >> $GITHUB_OUTPUT
echo "extra_param=$extra_param" >> $GITHUB_OUTPUT
- name: Run function returns with a null pointer scan testing
run: |
cd ${{ env.WKC }}/tests/parallel_test
./run_scan_container.sh \
-d ${{ env.WKDIR }} \
-b ${{ env.PR_NUMBER }}_${{ github.run_number }} \
-f ${{ env.WKDIR }}/tmp/${{ env.PR_NUMBER }}_${{ github.run_number }}/docs_changed.txt \
${{ steps.get_param.outputs.extra_param }}
- name: Run tdgpt test cases
run: |
cd ${{ env.WKC }}/tests/parallel_test
export DEFAULT_RETRY_TIME=2
date
timeout 600 time ./run.sh -e \
-m /home/m.json \
-t tdgpt_cases.task \
-b "${{ env.PR_NUMBER }}_${{ github.run_number }}" \
-l ${{ env.WKDIR }}/log \
-o 300 ${{ steps.get_param.outputs.extra_param }}

43
.github/workflows/tdgpt-update-service.yml vendored Normal file
View File

@ -0,0 +1,43 @@
# Scheduled updates for the TDgpt service.
name: TDgpt Update Service
on:
schedule:
- cron: '30 00 * * *'
env:
WKC: "/root/TDengine"
jobs:
update-service:
runs-on:
group: CI
labels: [self-hosted, Linux, X64, tdgpt-anode-service]
steps:
- name: Update TDengine codes
run: |
set -euo pipefail
cd ${{ env.WKC }}
git checkout 3.0
- name: Package the TDGpt Anode Service
run: |
set -euo pipefail
cd ${{ env.WKC }}/tools/tdgpt/script && ./release.sh
- name: Reinstall and restart the TDGpt Anode Service
run: |
set -euo pipefail
cd ${{ env.WKC }}/tools/tdgpt/release
if [[ -f "TDengine-enterprise-anode-1.0.1.tar.gz" ]]; then
tar -xzf TDengine-enterprise-anode-1.0.1.tar.gz
cd TDengine-enterprise-anode-1.0.1
./install.sh
fi
systemctl restart taosanoded
- name: Clean up
if: always()
run: |
if [[ -f ${{ env.WKC }}/tools/tdgpt/release/TDengine-enterprise-anode-1.0.1 ]] then rm -rf ${{ env.WKC }}/tools/tdgpt/release/TDengine-enterprise-anode-1.0.1; fi

7
.gitignore vendored
View File

@ -51,7 +51,6 @@ pysim/
tests/script/api/batchprepare
taosadapter
taosadapter-debug
tools/taos-tools/*
tools/taosws-rs/*
tools/taosadapter/*
tools/upx*
@ -60,7 +59,6 @@ tools/upx*
html/
/.vs
/CMakeFiles/3.10.2
/CMakeCache.txt
/Makefile
/*.cmake
/src/cq/test/CMakeFiles/cqtest.dir/*.cmake
@ -133,14 +131,12 @@ tools/THANKS
tools/NEWS
tools/COPYING
tools/BUGS
tools/taos-tools
tools/taosws-rs
tags
.clangd
*CMakeCache*
*CMakeFiles*
.history/
*.txt
*.tcl
*.pc
contrib/geos
@ -156,6 +152,9 @@ pcre2_grep_test.sh
pcre2_chartables.c
geos-config
config.h
!contrib/xml2-cmake
!contrib/xml2-cmake/linux_x86_64/include/config.h
!contrib/xml2-cmake/CMakeLists.txt
pcre2.h
zconf.h
version.h

21
CMakeLists.txt
View File

@ -11,36 +11,29 @@ if(NOT DEFINED TD_SOURCE_DIR)
endif()
SET(TD_COMMUNITY_DIR ${PROJECT_SOURCE_DIR})
set(TD_SUPPORT_DIR "${TD_SOURCE_DIR}/cmake")
set(TD_CONTRIB_DIR "${TD_SOURCE_DIR}/contrib")
include(${TD_SUPPORT_DIR}/cmake.platform)
include(${TD_SUPPORT_DIR}/cmake.define)
include(${TD_SUPPORT_DIR}/cmake.options)
include(${TD_SUPPORT_DIR}/cmake.define)
include(${TD_SUPPORT_DIR}/cmake.version)
# contrib
add_subdirectory(contrib)
include(${TD_SUPPORT_DIR}/cmake.install)
enable_testing()
set_property(GLOBAL PROPERTY GLOBAL_DEPENDS_NO_CYCLES OFF)
add_subdirectory(contrib)
# api
add_library(api INTERFACE)
target_include_directories(api INTERFACE "include/client")
# src
if(${BUILD_TEST})
include(CTest)
enable_testing()
add_subdirectory(examples/c)
endif(${BUILD_TEST})
add_library(api INTERFACE)
target_include_directories(api INTERFACE "include/client")
add_subdirectory(source)
add_subdirectory(tools)
add_subdirectory(utils)
add_subdirectory(examples/c)
add_subdirectory(tests)
include(${TD_SUPPORT_DIR}/cmake.install)
# docs
add_subdirectory(docs/doxgen)

3
Jenkinsfile2
View File

@ -361,6 +361,7 @@ def pre_test_build_win() {
pip3 install taospy==2.7.21
pip3 install taos-ws-py==0.3.8
xcopy /e/y/i/f %WIN_INTERNAL_ROOT%\\debug\\build\\lib\\taos.dll C:\\Windows\\System32
xcopy /e/y/i/f %WIN_INTERNAL_ROOT%\\debug\\build\\lib\\taosnative.dll C:\\Windows\\System32
'''
return 1
}
@ -379,7 +380,9 @@ def run_win_test() {
bat '''
echo "windows test ..."
xcopy /e/y/i/f %WIN_INTERNAL_ROOT%\\debug\\build\\lib\\taos.dll C:\\Windows\\System32
xcopy /e/y/i/f %WIN_INTERNAL_ROOT%\\debug\\build\\lib\\taosnative.dll C:\\Windows\\System32
ls -l C:\\Windows\\System32\\taos.dll
ls -l C:\\Windows\\System32\\taosnative.dll
time /t
cd %WIN_SYSTEM_TEST_ROOT%
echo "testing ..."

180
README-CN.md
View File

@ -8,30 +8,30 @@
</a>
</p>
简体中文 | [English](README.md) | [TDengine 云服务](https://cloud.taosdata.com/?utm_medium=cn&utm_source=github) | 很多职位正在热招中，请看[这里](https://www.taosdata.com/careers/)
简体中文 | [English](README.md) | [TDengine 云服务](https://cloud.taosdata.com/?utm_medium=cn&utm_source=github) | 很多职位正在热招中，请看 [这里](https://www.taosdata.com/careers/)
# 目录
1. [TDengine 简介](#1-tdengine-简介)
1. [文档](#2-文档)
1. [必备工具](#3-必备工具)
- [3.1 Linux预备](#31-linux系统)
- [3.2 macOS预备](#32-macos系统)
- [3.3 Windows预备](#33-windows系统)
- [3.1 Linux 预备](#31-Linux系统)
- [3.2 macOS 预备](#32-macOS系统)
- [3.3 Windows 预备](#3.3-Windows系统)
- [3.4 克隆仓库](#34-克隆仓库)
1. [构建](#4-构建)
- [4.1 Linux系统上构建](#41-linux系统上构建)
- [4.2 macOS系统上构建](#42-macos系统上构建)
- [4.3 Windows系统上构建](#43-windows系统上构建)
- [4.1 Linux 系统上构建](#41-Linux系统上构建)
- [4.2 macOS 系统上构建](#42-macOS系统上构建)
- [4.3 Windows 系统上构建](#43-Windows系统上构建)
1. [打包](#5-打包)
1. [安装](#6-安装)
- [6.1 Linux系统上安装](#61-linux系统上安装)
- [6.2 macOS系统上安装](#62-macos系统上安装)
- [6.3 Windows系统上安装](#63-windows系统上安装)
- [6.1 Linux 系统上安装](#61-Linux系统上安装)
- [6.2 macOS 系统上安装](#62-macOS系统上安装)
- [6.3 Windows 系统上安装](#63-Windows系统上安装)
1. [快速运行](#7-快速运行)
- [7.1 Linux系统上运行](#71-linux系统上运行)
- [7.2 macOS系统上运行](#72-macos系统上运行)
- [7.3 Windows系统上运行](#73-windows系统上运行)
- [7.1 Linux 系统上运行](#71-Linux系统上运行)
- [7.2 macOS 系统上运行](#72-macOS系统上运行)
- [7.3 Windows 系统上运行](#73-Windows系统上运行)
1. [测试](#8-测试)
1. [版本发布](#9-版本发布)
1. [工作流](#10-工作流)
@ -41,46 +41,48 @@
# 1. 简介
TDengine 是一款开源、高性能、云原生的时序数据库 (Time-Series Database, TSDB)。TDengine 能被广泛运用于物联网、工业互联网、车联网、IT 运维、金融等领域。除核心的时序数据库功能外，TDengine 还提供缓存、数据订阅、流式计算等功能，是一极简的时序数据处理平台，最大程度的减小系统设计的复杂度，降低研发和运营成本。与其他时序数据库相比，TDengine 的主要优势如下：
TDengine 是一款开源、高性能、云原生、AI 驱动的时序数据库 (Time-Series Database, TSDB)。TDengine 能被广泛运用于物联网、工业互联网、车联网、IT 运维、金融等领域。除核心的时序数据库功能外，TDengine 还提供缓存、数据订阅、流式计算、AI 智能体等功能，是一极简的时序数据处理平台，最大程度的减小系统设计的复杂度，降低研发和运营成本。与其他时序数据库相比，TDengine 的主要优势如下：
- **高性能**：通过创新的存储引擎设计，无论是数据写入还是查询，TDengine 的性能比通用数据库快 10 倍以上，也远超其他时序数据库，存储空间不及通用数据库的1/10。
- **高性能**：通过创新的存储引擎设计，无论是数据写入还是查询，TDengine 的性能比通用数据库快 10 倍以上，也远超其他时序数据库，存储空间不及通用数据库的 1/10。
- **云原生**：通过原生分布式的设计，充分利用云平台的优势，TDengine 提供了水平扩展能力，具备弹性、韧性和可观测性，支持k8s部署，可运行在公有云、私有云和混合云上。
- **云原生**：通过原生分布式的设计，充分利用云平台的优势，TDengine 提供了水平扩展能力，具备弹性、韧性和可观测性，支持 k8s 部署，可运行在公有云、私有云和混合云上。
- **极简时序数据平台**：TDengine 内建消息队列、缓存、流式计算等功能，应用无需再集成 Kafka/Redis/HBase/Spark 等软件，大幅降低系统的复杂度，降低应用开发和运营成本。
- **极简时序数据平台**：TDengine 内建消息队列、缓存、流式计算、AI 智能体等功能，应用无需再集成 Kafka/Redis/HBase/Spark 等软件，大幅降低系统的复杂度，降低应用开发和运营成本。
- **分析能力**：支持 SQL，同时为时序数据特有的分析提供SQL扩展。通过超级表、存储计算分离、分区分片、预计算、自定义函数等技术，TDengine 具备强大的分析能力。
- **分析能力**：支持 SQL，同时为时序数据特有的分析提供 SQL 扩展。通过超级表、存储计算分离、分区分片、预计算、自定义函数以及 AI Agent 等技术，TDengine 具备强大的分析能力。
- **简单易用**：无任何依赖，安装、集群几秒搞定；提供REST以及各种语言连接器，与众多第三方工具无缝集成；提供命令行程序，便于管理和即席查询；提供各种运维工具。
- **AI智能体**：内置时序数据智能体 TDgpt, 无缝连接时序数据基础模型、大语言模型、机器学习、传统统计算法等，提供时序数据预测、异常检测、数据补全和数据分类的功能。
- **核心开源**：TDengine 的核心代码包括集群功能全部开源，截止到2022年8月1日，全球超过 135.9k 个运行实例，GitHub Star 18.7k，Fork 4.4k，社区活跃。
- **简单易用**：无任何依赖，安装、集群几秒搞定；提供 REST 以及各种语言连接器，与众多第三方工具无缝集成；提供命令行程序，便于管理和即席查询；提供各种运维工具。
了解TDengine高级功能的完整列表，请 [点击](https://tdengine.com/tdengine/)。体验TDengine最简单的方式是通过[TDengine云平台](https://cloud.tdengine.com)。
- **核心开源**：TDengine 的核心代码包括集群功能全部开源，截止到 2022 年 8 月 1 日，全球超过 135.9k 个运行实例，GitHub Star 18.7k，Fork 4.4k，社区活跃。
了解TDengine高级功能的完整列表，请 [点击](https://tdengine.com/tdengine/)。体验 TDengine 最简单的方式是通过 [TDengine云平台](https://cloud.tdengine.com)。对最新发布的 TDengine 组件 TDgpt，请访问 [TDgpt README](./tools/tdgpt/README.md) 了解细节。
# 2. 文档
关于完整的使用手册，系统架构和更多细节，请参考 [TDengine](https://www.taosdata.com/) 或者 [TDengine 官方文档](https://docs.taosdata.com)。
用户可根据需求选择通过[容器](https://docs.taosdata.com/get-started/docker/)、[安装包](https://docs.taosdata.com/get-started/package/)、[Kubernetes](https://docs.taosdata.com/deployment/k8s/)来安装或直接使用无需安装部署的[云服务](https://cloud.taosdata.com/)。本快速指南是面向想自己编译、打包、测试的开发者的。
用户可根据需求选择通过 [容器](https://docs.taosdata.com/get-started/docker/)、[安装包](https://docs.taosdata.com/get-started/package/)、[Kubernetes](https://docs.taosdata.com/deployment/k8s/) 来安装或直接使用无需安装部署的 [云服务](https://cloud.taosdata.com/)。本快速指南是面向想自己编译、打包、测试的开发者的。
如果想编译或测试TDengine连接器，请访问以下仓库: [JDBC连接器](https://github.com/taosdata/taos-connector-jdbc), [Go连接器](https://github.com/taosdata/driver-go), [Python连接器](https://github.com/taosdata/taos-connector-python), [Node.js连接器](https://github.com/taosdata/taos-connector-node), [C#连接器](https://github.com/taosdata/taos-connector-dotnet), [Rust连接器](https://github.com/taosdata/taos-connector-rust).
如果想编译或测试 TDengine 连接器，请访问以下仓库：[JDBC连接器](https://github.com/taosdata/taos-connector-jdbc)、[Go连接器](https://github.com/taosdata/driver-go)、[Python连接器](https://github.com/taosdata/taos-connector-python)、[Node.js连接器](https://github.com/taosdata/taos-connector-node)、[C#连接器](https://github.com/taosdata/taos-connector-dotnet)、[Rust连接器](https://github.com/taosdata/taos-connector-rust)。
# 3. 前置条件
TDengine 目前可以在 Linux、 Windows、macOS 等平台上安装和运行。任何 OS 的应用也可以选择 taosAdapter 的 RESTful 接口连接服务端 taosd。CPU 支持 X64/ARM64，后续会支持 MIPS64、Alpha64、ARM32、RISC-V 等 CPU 架构。目前不支持使用交叉编译器构建。
TDengine 目前可以在 Linux 和 macOS 平台上安装和运行 (企业版支持 Windows)。任何 OS 的应用也可以选择 taosAdapter 的 RESTful 接口连接服务端 taosd。CPU 支持 X64、ARM64，后续会支持 MIPS64、Alpha64、ARM32、RISC-V 等 CPU 架构。目前不支持使用交叉编译器构建。
如果你想要编译 taosAdapter 或者 taosKeeper，需要安装 Go 1.18 及以上版本。
## 3.1 Linux系统
## 3.1 Linux 系统
<details>
<summary>安装Linux必备工具</summary>
<summary>安装 Linux 必备工具</summary>
### Ubuntu 18.04、20.04、22.04
```bash
sudo apt-get udpate
sudo apt-get update
sudo apt-get install -y gcc cmake build-essential git libjansson-dev \
libsnappy-dev liblzma-dev zlib1g-dev pkg-config
```
@ -96,13 +98,13 @@ yum install -y zlib-static xz-devel snappy-devel jansson-devel pkgconfig libatom
</details>
## 3.2 macOS系统
## 3.2 macOS 系统
<details>
<summary>安装macOS必备工具</summary>
<summary>安装 macOS 必备工具</summary>
根据提示安装依赖工具 [brew](https://brew.sh/).
根据提示安装依赖工具 [brew](https://brew.sh/)
```bash
brew install argp-standalone gflags pkgconfig
@ -110,11 +112,11 @@ brew install argp-standalone gflags pkgconfig
</details>
## 3.3 Windows系统
## 3.3 Windows 系统
<details>
<summary>安装Windows必备工具</summary>
<summary>安装 Windows 必备工具</summary>
进行中。
@ -122,7 +124,7 @@ brew install argp-standalone gflags pkgconfig
## 3.4 克隆仓库
通过如下命令将TDengine仓库克隆到指定计算机:
通过如下命令将 TDengine 仓库克隆到指定计算机：
```bash
git clone https://github.com/taosdata/TDengine.git
@ -131,23 +133,23 @@ cd TDengine
# 4. 构建
TDengine 还提供一组辅助工具软件 taosTools，目前它包含 taosBenchmark（曾命名为 taosdemo）和 taosdump 两个软件。默认 TDengine 编译不包含 taosTools, 您可以在编译 TDengine 时使用`cmake .. -DBUILD_TOOLS=true` 来同时编译 taosTools。
TDengine 还提供一组辅助工具软件 taosTools，目前它包含 taosBenchmark（曾命名为 taosdemo）和 taosdump 两个软件。默认 TDengine 编译不包含 taosTools，您可以在编译 TDengine 时使用 `cmake .. -DBUILD_TOOLS=true` 来同时编译 taosTools。
为了构建TDengine, 请使用 [CMake](https://cmake.org/) 3.13.0 或者更高版本。
为了构建 TDengine，请使用 [CMake](https://cmake.org/) 3.13.0 或者更高版本。
## 4.1 Linux系统上构建
## 4.1 Linux 系统上构建
<details>
<summary>Linux系统上构建步骤</summary>
<summary>Linux 系统上构建步骤</summary>
可以通过以下命令使用脚本 `build.sh` 编译TDengine和taosTools，包括taosBenchmark和taosdump:
可以通过以下命令使用脚本 `build.sh` 编译 TDengine 和 taosTools，包括 taosBenchmark 和 taosdump。
```bash
./build.sh
```
也可以通过以下命令进行构建:
也可以通过以下命令进行构建：
```bash
mkdir debug && cd debug
@ -159,13 +161,13 @@ make
如果你想要编译 taosKeeper，需要添加 `-DBUILD_KEEPER=true` 选项。
可以使用Jemalloc作为内存分配器，而不是使用glibc:
可以使用 Jemalloc 作为内存分配器，而不是使用 glibc：
```bash
cmake .. -DJEMALLOC_ENABLED=true
cmake .. -DJEMALLOC_ENABLED=ON
```
TDengine构建脚本可以自动检测x86、x86-64、arm64平台上主机的体系结构。
您也可以通过CPUTYPE选项手动指定架构:
TDengine 构建脚本可以自动检测 x86、x86-64、arm64 平台上主机的体系结构。
您也可以通过 CPUTYPE 选项手动指定架构：
```bash
cmake .. -DCPUTYPE=aarch64 && cmake --build .
@ -173,13 +175,13 @@ cmake .. -DCPUTYPE=aarch64 && cmake --build .
</details>
## 4.2 macOS系统上构建
## 4.2 macOS 系统上构建
<details>
<summary>macOS系统上构建步骤</summary>
<summary>macOS 系统上构建步骤</summary>
请安装XCode命令行工具和cmake。使用XCode 11.4+在Catalina和Big Sur上完成验证。
请安装 XCode 命令行工具和 cmake。使用 XCode 11.4+ 在 Catalina 和 Big Sur 上完成验证。
```shell
mkdir debug && cd debug
@ -192,14 +194,14 @@ cmake .. && cmake --build .
</details>
## 4.3 Windows系统上构建
## 4.3 Windows 系统上构建
<details>
<summary>Windows系统上构建步骤</summary>
<summary>Windows 系统上构建步骤</summary>
如果您使用的是Visual Studio 2013，请执行“cmd.exe”打开命令窗口执行如下命令。
执行vcvarsall.bat时，64位的Windows请指定“amd64”，32位的Windows请指定“x86”。
如果您使用的是 Visual Studio 2013，请执行 “cmd.exe” 打开命令窗口执行如下命令。
执行 vcvarsall.bat 时，64 位的 Windows 请指定 “amd64”，32 位的 Windows 请指定 “x86”。
```cmd
mkdir debug && cd debug
@ -208,19 +210,19 @@ cmake .. -G "NMake Makefiles"
nmake
```
如果您使用Visual Studio 2019或2017:
如果您使用 Visual Studio 2019 或 2017：
请执行“cmd.exe”打开命令窗口执行如下命令。
执行vcvarsall.bat时，64位的Windows请指定“x64”，32位的Windows请指定“x86”。
请执行 “cmd.exe” 打开命令窗口执行如下命令。
执行 vcvarsall.bat 时，64 位的 Windows 请指定 “x64”，32 位的 Windows 请指定 “x86”。
```cmd
mkdir debug && cd debug
"c:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" < x64 | x86 >
"C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" < x64 | x86 >
cmake .. -G "NMake Makefiles"
nmake
```
或者，您可以通过点击Windows开始菜单打开命令窗口->“Visual Studio < 2019 | 2017 >”文件夹->“x64原生工具命令提示符VS < 2019 | 2017 >”或“x86原生工具命令提示符VS < 2019 | 2017 >”取决于你的Windows是什么架构，然后执行命令如下：
或者，您可以通过点击 Windows 开始菜单打开命令窗口 -> `Visual Studio < 2019 | 2017 >` 文件夹 -> `x64 原生工具命令提示符 VS < 2019 | 2017 >` 或 `x86 原生工具命令提示符 < 2019 | 2017 >` 取决于你的 Windows 是什么架构，然后执行命令如下：
```cmd
mkdir debug && cd debug
@ -231,33 +233,33 @@ nmake
# 5. 打包
由于一些组件依赖关系，TDengine社区安装程序不能仅由该存储库创建。我们仍在努力改进。
由于一些组件依赖关系，TDengine 社区安装程序不能仅由该存储库创建。我们仍在努力改进。
# 6. 安装
## 6.1 Linux系统上安装
## 6.1 Linux 系统上安装
<details>
<summary>Linux系统上安装详细步骤</summary>
<summary>Linux 系统上安装详细步骤</summary>
构建成功后，TDengine可以通过以下命令进行安装:
构建成功后，TDengine 可以通过以下命令进行安装：
```bash
sudo make install
```
从源代码安装还将为TDengine配置服务管理。用户也可以使用[TDengine安装包](https://docs.taosdata.com/get-started/package/)进行安装。
从源代码安装还将为 TDengine 配置服务管理。用户也可以使用 [TDengine安装包](https://docs.taosdata.com/get-started/package/)进行安装。
</details>
## 6.2 macOS系统上安装
## 6.2 macOS 系统上安装
<details>
<summary>macOS系统上安装详细步骤</summary>
<summary>macOS 系统上安装详细步骤</summary>
构建成功后，TDengine可以通过以下命令进行安装:
构建成功后，TDengine可以通过以下命令进行安装：
```bash
sudo make install
@ -265,13 +267,13 @@ sudo make install
</details>
## 6.3 Windows系统上安装
## 6.3 Windows 系统上安装
<details>
<summary>Windows系统上安装详细步骤</summary>
<summary>Windows 系统上安装详细步骤</summary>
构建成功后，TDengine可以通过以下命令进行安装:
构建成功后，TDengine 可以通过以下命令进行安装：
```cmd
nmake install
@ -281,32 +283,32 @@ nmake install
# 7. 快速运行
## 7.1 Linux系统上运行
## 7.1 Linux 系统上运行
<details>
<summary>Linux系统上运行详细步骤</summary>
<summary>Linux 系统上运行详细步骤</summary>
在Linux系统上安装TDengine完成后，在终端运行如下命令启动服务:
在Linux 系统上安装 TDengine 完成后，在终端运行如下命令启动服务：
```bash
sudo systemctl start taosd
```
然后用户可以通过如下命令使用TDengine命令行连接TDengine服务:
然后用户可以通过如下命令使用 TDengine 命令行连接 TDengine 服务：
```bash
taos
```
如果TDengine 命令行连接服务器成功，系统将打印欢迎信息和版本信息。否则，将显示连接错误信息。
如果 TDengine 命令行连接服务器成功，系统将打印欢迎信息和版本信息。否则，将显示连接错误信息。
如果您不想将TDengine作为服务运行，您可以在当前终端中运行它。例如，要在构建完成后快速启动TDengine服务器，在终端中运行以下命令：（我们以Linux为例，Windows上的命令为 `taosd.exe`）
如果您不想将 TDengine 作为服务运行，您可以在当前终端中运行它。例如，要在构建完成后快速启动 TDengine 服务器，在终端中运行以下命令：（以 Linux 为例，Windows 上的命令为 `taosd.exe`）
```bash
./build/bin/taosd -c test/cfg
```
在另一个终端上，使用TDengine命令行连接服务器:
在另一个终端上，使用 TDengine 命令行连接服务器：
```bash
./build/bin/taos -c test/cfg
@ -316,42 +318,42 @@ taos
</details>
## 7.2 macOS系统上运行
## 7.2 macOS 系统上运行
<details>
<summary>macOS系统上运行详细步骤</summary>
<summary>macOS 系统上运行详细步骤</summary>
在macOS上安装完成后启动服务，双击/applications/TDengine启动程序，或者在终端中执行如下命令：
在 macOS 上安装完成后启动服务，双击 `/applications/TDengine` 启动程序，或者在终端中执行如下命令：
```bash
sudo launchctl start com.tdengine.taosd
```
然后在终端中使用如下命令通过TDengine命令行连接TDengine服务器:
然后在终端中使用如下命令通过 TDengine 命令行连接 TDengine 服务器：
```bash
taos
```
如果TDengine命令行连接服务器成功，系统将打印欢迎信息和版本信息。否则，将显示错误信息。
如果 TDengine 命令行连接服务器成功，系统将打印欢迎信息和版本信息。否则，将显示错误信息。
</details>
## 7.3 Windows系统上运行
## 7.3 Windows 系统上运行
<details>
<summary>Windows系统上运行详细步骤</summary>
<summary>Windows 系统上运行详细步骤</summary>
您可以使用以下命令在Windows平台上启动TDengine服务器:
您可以使用以下命令在 Windows 平台上启动 TDengine 服务器：
```cmd
.\build\bin\taosd.exe -c test\cfg
```
在另一个终端上，使用TDengine命令行连接服务器:
在另一个终端上，使用 TDengine 命令行连接服务器：
```cmd
.\build\bin\taos.exe -c test\cfg
@ -363,25 +365,25 @@ taos
# 8. 测试
有关如何在TDengine上运行不同类型的测试，请参考 [TDengine测试](./tests/README-CN.md)
有关如何在 TDengine 上运行不同类型的测试，请参考 [TDengine测试](./tests/README-CN.md)
# 9. 版本发布
TDengine发布版本的完整列表，请参考 [版本列表](https://github.com/taosdata/TDengine/releases)
TDengine 发布版本的完整列表，请参考 [版本列表](https://github.com/taosdata/TDengine/releases)
# 10. 工作流
TDengine构建检查工作流可以在参考 [Github Action](https://github.com/taosdata/TDengine/actions/workflows/taosd-ci-build.yml), 更多的工作流正在创建中，将很快可用。
TDengine 构建检查工作流可以在参考 [Github Action](https://github.com/taosdata/TDengine/actions/workflows/taosd-ci-build.yml)，更多的工作流正在创建中，将很快可用。
# 11. 覆盖率
最新的TDengine测试覆盖率报告可参考 [coveralls.io](https://coveralls.io/github/taosdata/TDengine)
最新的 TDengine 测试覆盖率报告可参考 [coveralls.io](https://coveralls.io/github/taosdata/TDengine)
<details>
<summary>如何在本地运行测试覆盖率报告？</summary>
在本地创建测试覆盖率报告（HTML格式），请运行以下命令:
在本地创建测试覆盖率报告（HTML 格式），请运行以下命令：
```bash
cd tests
@ -389,8 +391,8 @@ bash setup-lcov.sh -v 1.16 && ./run_local_coverage.sh -b main -c task
# on main branch and run cases in longtimeruning_cases.task
# for more infomation about options please refer to ./run_local_coverage.sh -h
```
> **注意:**
> 请注意，-b和-i选项将使用-DCOVER=true选项重新编译TDengine，这可能需要花费一些时间。
> **注意**：
> 请注意，-b 和 -i 选项将使用 -DCOVER=true 选项重新编译 TDengine，这可能需要花费一些时间。
</details>

14
README.md
View File

@ -54,21 +54,23 @@ English | [简体中文](README-CN.md) | [TDengine Cloud](https://cloud.tdengine
# 1. Introduction
TDengine is an open source, high-performance, cloud native [time-series database](https://tdengine.com/tsdb/) optimized for Internet of Things (IoT), Connected Cars, and Industrial IoT. It enables efficient, real-time data ingestion, processing, and monitoring of TB and even PB scale data per day, generated by billions of sensors and data collectors. TDengine differentiates itself from other time-series databases with the following advantages:
TDengine is an open source, high-performance, cloud native and AI powered [time-series database](https://tdengine.com/tsdb/) designed for Internet of Things (IoT), Connected Cars, and Industrial IoT. It enables efficient, real-time data ingestion, processing, and analysis of TB and even PB scale data per day, generated by billions of sensors and data collectors. TDengine differentiates itself from other time-series databases with the following advantages:
- **[High Performance](https://tdengine.com/tdengine/high-performance-time-series-database/)**: TDengine is the only time-series database to solve the high cardinality issue to support billions of data collection points while out performing other time-series databases for data ingestion, querying and data compression.
- **[Simplified Solution](https://tdengine.com/tdengine/simplified-time-series-data-solution/)**: Through built-in caching, stream processing and data subscription features, TDengine provides a simplified solution for time-series data processing. It reduces system design complexity and operation costs significantly.
- **[Simplified Solution](https://tdengine.com/tdengine/simplified-time-series-data-solution/)**: Through built-in caching, stream processing, data subscription and AI agent features, TDengine provides a simplified solution for time-series data processing. It reduces system design complexity and operation costs significantly.
- **[Cloud Native](https://tdengine.com/tdengine/cloud-native-time-series-database/)**: Through native distributed design, sharding and partitioning, separation of compute and storage, RAFT, support for kubernetes deployment and full observability, TDengine is a cloud native Time-Series Database and can be deployed on public, private or hybrid clouds.
- **[AI Powered](https://tdengine.com/tdengine/tdgpt/)**: Through the built in AI agent TDgpt, TDengine can connect to a variety of time series foundation model, large language model, machine learning and traditional algorithms to provide time series data forecasting, anomly detection, imputation and classification.
- **[Ease of Use](https://tdengine.com/tdengine/easy-time-series-data-platform/)**: For administrators, TDengine significantly reduces the effort to deploy and maintain. For developers, it provides a simple interface, simplified solution and seamless integrations for third party tools. For data users, it gives easy data access.
- **[Easy Data Analytics](https://tdengine.com/tdengine/time-series-data-analytics-made-easy/)**: Through super tables, storage and compute separation, data partitioning by time interval, pre-computation and other means, TDengine makes it easy to explore, format, and get access to data in a highly efficient way.
- **[Easy Data Analytics](https://tdengine.com/tdengine/time-series-data-analytics-made-easy/)**: Through super tables, storage and compute separation, data partitioning by time interval, pre-computation and AI agent, TDengine makes it easy to explore, format, and get access to data in a highly efficient way.
- **[Open Source](https://tdengine.com/tdengine/open-source-time-series-database/)**: TDengine’s core modules, including cluster feature, are all available under open source licenses. It has gathered 19.9k stars on GitHub. There is an active developer community, and over 139k running instances worldwide.
- **[Open Source](https://tdengine.com/tdengine/open-source-time-series-database/)**: TDengine’s core modules, including cluster feature and AI agent, are all available under open source licenses. It has gathered 23.7k stars on GitHub. There is an active developer community, and over 730k running instances worldwide.
For a full list of TDengine competitive advantages, please [check here](https://tdengine.com/tdengine/). The easiest way to experience TDengine is through [TDengine Cloud](https://cloud.tdengine.com).
For a full list of TDengine competitive advantages, please [check here](https://tdengine.com/tdengine/). The easiest way to experience TDengine is through [TDengine Cloud](https://cloud.tdengine.com). For the latest TDengine component TDgpt, please refer to [TDgpt README](./tools/tdgpt/README.md) for details.
# 2. Documentation
@ -173,7 +175,7 @@ If you want to compile taosKeeper, you need to add the `-DBUILD_KEEPER=true` opt
You can use Jemalloc as memory allocator instead of glibc:
```bash
cmake .. -DJEMALLOC_ENABLED=true
cmake .. -DJEMALLOC_ENABLED=ON
```
TDengine build script can auto-detect the host machine's architecture on x86, x86-64, arm64 platform.

1
cmake/azure_CMakeLists.txt.in
View File

@ -2,6 +2,7 @@
ExternalProject_Add(azure
URL https://github.com/Azure/azure-sdk-for-cpp/archive/refs/tags/azure-storage-blobs_12.13.0-beta.1.tar.gz
URL_HASH SHA256=3eca486fd60e3522d0a633025ecd652a71515b1e944799b2e8ee31fd590305a9
DEPENDS xml2
DOWNLOAD_NO_PROGRESS 1
DOWNLOAD_DIR "${TD_CONTRIB_DIR}/deps-download"
SOURCE_DIR "${TD_CONTRIB_DIR}/azure-sdk-for-cpp-azure-storage-blobs_12.13.0-beta.1"

31
cmake/cmake.define
View File

@ -97,14 +97,10 @@ ELSE()
SET(TD_TAOS_TOOLS TRUE)
ENDIF()
SET(TAOS_LIB taos)
SET(TAOS_LIB taos)
SET(TAOS_LIB_STATIC taos_static)
IF(${TD_WINDOWS})
SET(TAOS_LIB_PLATFORM_SPEC taos_static)
ELSE()
SET(TAOS_LIB_PLATFORM_SPEC taos)
ENDIF()
SET(TAOS_NATIVE_LIB taosnative)
SET(TAOS_NATIVE_LIB_STATIC taosnative_static)
# build TSZ by default
IF("${TSZ_ENABLED}" MATCHES "false")
@ -116,9 +112,6 @@ ELSE()
set(VAR_TSZ "TSZ" CACHE INTERNAL "global variant tsz")
ENDIF()
# force set all platform to JEMALLOC_ENABLED = false
# SET(JEMALLOC_ENABLED OFF)
IF(TD_WINDOWS)
MESSAGE("${Yellow} set compiler flag for Windows! ${ColourReset}")
@ -259,10 +252,16 @@ ELSE()
ENDIF()
ENDIF()
IF(${JEMALLOC_ENABLED})
MESSAGE(STATUS "JEMALLOC_ENABLED Enabled")
SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-error=attributes")
SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-error=attributes")
ELSE()
MESSAGE(STATUS "JEMALLOC_ENABLED Disabled")
IF(TD_LINUX_64)
IF(${JEMALLOC_ENABLED})
MESSAGE(STATUS "JEMALLOC Enabled")
SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-error=attributes")
SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-error=attributes")
SET(LINK_JEMALLOC "-L${CMAKE_BINARY_DIR}/build/lib -ljemalloc")
ADD_DEFINITIONS(-DTD_JEMALLOC_ENABLED -I${CMAKE_BINARY_DIR}/build/include -L${CMAKE_BINARY_DIR}/build/lib -Wl,-rpath,${CMAKE_BINARY_DIR}/build/lib)
ELSE()
MESSAGE(STATUS "JEMALLOC Disabled")
SET(LINK_JEMALLOC "")
ENDIF()
ENDIF()

243
cmake/cmake.options
View File

@ -9,61 +9,61 @@ option(
)
IF(${TD_WINDOWS})
IF(NOT TD_ASTRA)
MESSAGE("build pthread Win32")
option(
BUILD_PTHREAD
"If build pthread on Windows"
ON
)
MESSAGE("build pthread Win32")
option(
BUILD_PTHREAD
"If build pthread on Windows"
ON
)
MESSAGE("build gnu regex for Windows")
option(
BUILD_GNUREGEX
"If build gnu regex on Windows"
ON
)
MESSAGE("build gnu regex for Windows")
option(
BUILD_GNUREGEX
"If build gnu regex on Windows"
ON
)
MESSAGE("build iconv Win32")
option(
BUILD_WITH_ICONV
"If build iconv on Windows"
ON
)
MESSAGE("build iconv Win32")
option(
BUILD_WITH_ICONV
"If build iconv on Windows"
ON
)
MESSAGE("build msvcregex Win32")
option(
BUILD_MSVCREGEX
"If build msvcregex on Windows"
ON
)
MESSAGE("build msvcregex Win32")
option(
BUILD_MSVCREGEX
"If build msvcregex on Windows"
ON
)
MESSAGE("build wcwidth Win32")
option(
BUILD_WCWIDTH
"If build wcwidth on Windows"
ON
)
MESSAGE("build wcwidth Win32")
option(
BUILD_WCWIDTH
"If build wcwidth on Windows"
ON
)
MESSAGE("build wingetopt Win32")
option(
BUILD_WINGETOPT
"If build wingetopt on Windows"
ON
)
MESSAGE("build wingetopt Win32")
option(
BUILD_WINGETOPT
"If build wingetopt on Windows"
ON
)
option(
TDENGINE_3
"TDengine 3.x for taos-tools"
ON
)
option(
BUILD_CRASHDUMP
"If build crashdump on Windows"
ON
)
option(
TDENGINE_3
"TDengine 3.x for taos-tools"
ON
)
option(
BUILD_CRASHDUMP
"If build crashdump on Windows"
ON
)
ENDIF ()
ELSEIF (TD_DARWIN_64)
IF(${BUILD_TEST})
add_definitions(-DCOMPILER_SUPPORTS_CXX13)
@ -71,58 +71,102 @@ ELSEIF (TD_DARWIN_64)
ENDIF ()
option(
BUILD_GEOS
"If build with geos"
BUILD_WITH_LEMON
"If build with lemon"
ON
)
option(
BUILD_WITH_UDF
"If build with UDF"
ON
)
IF(NOT TD_ASTRA)
option(
BUILD_GEOS
"If build with geos"
ON
)
option(
BUILD_SHARED_LIBS
""
OFF
)
option(
RUST_BINDINGS
"If build with rust-bindings"
ON
)
option(
BUILD_PCRE2
"If build with pcre2"
ON
)
option(
BUILD_SHARED_LIBS
""
OFF
option(
JEMALLOC_ENABLED
"If build with jemalloc"
OFF
)
option(
BUILD_SANITIZER
"If build sanitizer"
OFF
)
option(
BUILD_ADDR2LINE
"If build addr2line"
OFF
)
option(
BUILD_WITH_LEVELDB
"If build with leveldb"
OFF
)
option(
RUST_BINDINGS
"If build with rust-bindings"
ON
option(
BUILD_WITH_ROCKSDB
"If build with rocksdb"
ON
)
option(
BUILD_PCRE2
"If build with pcre2"
ON
)
option(
BUILD_WITH_LZ4
"If build with lz4"
ON
)
ELSE ()
option(
JEMALLOC_ENABLED
"If build with jemalloc"
OFF
option(
BUILD_WITH_LZMA2
"If build with lzma2"
ON
)
option(
BUILD_SANITIZER
"If build sanitizer"
OFF
)
ENDIF ()
option(
BUILD_ADDR2LINE
"If build addr2line"
OFF
)
ADD_DEFINITIONS(-DUSE_AUDIT)
ADD_DEFINITIONS(-DUSE_GEOS)
ADD_DEFINITIONS(-DUSE_UDF)
ADD_DEFINITIONS(-DUSE_STREAM)
ADD_DEFINITIONS(-DUSE_PRCE2)
ADD_DEFINITIONS(-DUSE_RSMA)
ADD_DEFINITIONS(-DUSE_TSMA)
ADD_DEFINITIONS(-DUSE_TQ)
ADD_DEFINITIONS(-DUSE_TOPIC)
ADD_DEFINITIONS(-DUSE_MONITOR)
ADD_DEFINITIONS(-DUSE_REPORT)
option(
BUILD_WITH_LEVELDB
"If build with leveldb"
OFF
)
option(
BUILD_WITH_ROCKSDB
"If build with rocksdb"
ON
)
IF(${TD_ASTRA_RPC})
ADD_DEFINITIONS(-DTD_ASTRA_RPC)
ENDIF()
IF(${TD_LINUX})
@ -150,6 +194,12 @@ option(
ON
)
option(
BUILD_WITH_LZMA2
"If build with lzma2"
ON
)
ENDIF ()
IF(NOT TD_ENTERPRISE)
@ -191,6 +241,14 @@ option(BUILD_WITH_COS "If build with cos" OFF)
ENDIF ()
IF(${TAOSD_INTEGRATED})
add_definitions(-DTAOSD_INTEGRATED)
ENDIF()
IF(${TD_AS_LIB})
add_definitions(-DTD_AS_LIB)
ENDIF()
option(
BUILD_WITH_SQLITE
"If build with sqlite"
@ -209,6 +267,14 @@ option(
off
)
option(
BUILD_WITH_NURAFT
"If build with NuRaft"
OFF
)
IF(NOT TD_ASTRA)
option(
BUILD_WITH_UV
"If build with libuv"
@ -242,6 +308,7 @@ option(
"If use invertedIndex"
ON
)
ENDIF ()
option(
BUILD_RELEASE

2
cmake/curl_CMakeLists.txt.in
View File

@ -12,7 +12,7 @@ ExternalProject_Add(curl2
BUILD_IN_SOURCE TRUE
BUILD_ALWAYS 1
UPDATE_COMMAND ""
CONFIGURE_COMMAND ${CONTRIB_CONFIG_ENV} ./configure --prefix=$ENV{HOME}/.cos-local.2 --with-ssl=$ENV{HOME}/.cos-local.2 --enable-websockets --enable-shared=no --disable-ldap --disable-ldaps --without-brotli --without-zstd --without-libidn2 --without-nghttp2 --without-libpsl #--enable-debug
CONFIGURE_COMMAND ${CONTRIB_CONFIG_ENV} ./configure --prefix=$ENV{HOME}/.cos-local.2 --with-ssl=$ENV{HOME}/.cos-local.2 --enable-websockets --enable-shared=no --disable-ldap --disable-ldaps --without-brotli --without-zstd --without-libidn2 --without-nghttp2 --without-libpsl --without-librtmp #--enable-debug
BUILD_COMMAND make -j
INSTALL_COMMAND make install
TEST_COMMAND ""

3
cmake/lzma_CMakeLists.txt.in
View File

@ -1,7 +1,6 @@
# xz
if (${TD_LINUX})
if (${BUILD_WITH_LZMA2})
ExternalProject_Add(lzma2
GIT_REPOSITORY https://github.com/conor42/fast-lzma2.git
SOURCE_DIR "${TD_CONTRIB_DIR}/lzma2"

2
cmake/taosws_CMakeLists.txt.in
View File

@ -2,7 +2,7 @@
# taosws-rs
ExternalProject_Add(taosws-rs
GIT_REPOSITORY https://github.com/taosdata/taos-connector-rust.git
GIT_TAG main
GIT_TAG main
SOURCE_DIR "${TD_SOURCE_DIR}/tools/taosws-rs"
BINARY_DIR ""
#BUILD_IN_SOURCE TRUE

15
cmake/xml2_CMakeLists.txt.in
View File

@ -1,19 +1,16 @@
# xml2
ExternalProject_Add(xml2
URL https://download.gnome.org/sources/libxml2/2.11/libxml2-2.11.5.tar.xz
URL_HASH SHA256=3727b078c360ec69fa869de14bd6f75d7ee8d36987b071e6928d4720a28df3a6
#https://github.com/GNOME/libxml2/archive/refs/tags/v2.11.5.tar.gz
#GIT_REPOSITORY https://github.com/GNOME/libxml2
#GIT_TAG v2.11.5
URL https://github.com/GNOME/libxml2/archive/refs/tags/v2.10.4.tar.gz
URL_HASH SHA256=6f6fb27f91bb65f9d7196e3c616901b3e18a7dea31ccc2ae857940b125faa780
DOWNLOAD_NO_PROGRESS 1
DOWNLOAD_DIR "${TD_CONTRIB_DIR}/deps-download"
SOURCE_DIR "${TD_CONTRIB_DIR}/xml2"
SOURCE_DIR "${TD_CONTRIB_DIR}/libxml2"
#BINARY_DIR ""
BUILD_IN_SOURCE TRUE
CONFIGURE_COMMAND ./configure --prefix=$ENV{HOME}/.cos-local.2 --enable-shared=no --enable-static=yes --without-python --without-lzma
BUILD_COMMAND make -j
INSTALL_COMMAND make install && ln -sf $ENV{HOME}/.cos-local.2/include/libxml2/libxml $ENV{HOME}/.cos-local.2/include/libxml
CONFIGURE_COMMAND ""
BUILD_COMMAND ""
INSTALL_COMMAND ""
TEST_COMMAND ""
GIT_SHALLOW true
)

48
contrib/CMakeLists.txt
View File

@ -92,7 +92,9 @@ if(${BUILD_TEST})
endif(${BUILD_TEST})
# lz4
cat("${TD_SUPPORT_DIR}/lz4_CMakeLists.txt.in" ${CONTRIB_TMP_FILE})
if(${BUILD_WITH_LZ4})
cat("${TD_SUPPORT_DIR}/lz4_CMakeLists.txt.in" ${CONTRIB_TMP_FILE})
endif(${BUILD_WITH_LZ4})
# zlib
cat("${TD_SUPPORT_DIR}/zlib_CMakeLists.txt.in" ${CONTRIB_TMP_FILE})
@ -159,7 +161,6 @@ elseif(${BUILD_WITH_COS})
# cat("${TD_SUPPORT_DIR}/mxml_CMakeLists.txt.in" ${CONTRIB_TMP_FILE})
# cat("${TD_SUPPORT_DIR}/apr_CMakeLists.txt.in" ${CONTRIB_TMP_FILE})
# cat("${TD_SUPPORT_DIR}/apr-util_CMakeLists.txt.in" ${CONTRIB_TMP_FILE})
# cat("${TD_SUPPORT_DIR}/curl_CMakeLists.txt.in" ${CONTRIB_TMP_FILE})
cat("${TD_SUPPORT_DIR}/cos_CMakeLists.txt.in" ${CONTRIB_TMP_FILE})
add_definitions(-DUSE_COS)
endif()
@ -187,16 +188,22 @@ if(${BUILD_PCRE2})
cat("${TD_SUPPORT_DIR}/pcre2_CMakeLists.txt.in" ${CONTRIB_TMP_FILE})
endif()
find_program(C_COMPILER_LEMON NAMES gcc)
if(C_COMPILER_LEMON)
message(STATUS "LEMON C compiler: ${C_COMPILER_LEMON}")
else()
set(C_COMPILER_LEMON ${CMAKE_C_COMPILER})
message(STATUS "LEMON C compiler: ${C_COMPILER_LEMON}")
endif()
# lemon
cat("${TD_SUPPORT_DIR}/lemon_CMakeLists.txt.in" ${CONTRIB_TMP_FILE})
if(${BUILD_WITH_LEMON})
if(${TD_ACORE})
set(C_COMPILER_LEMON ${CMAKE_C_COMPILER})
else()
find_program(C_COMPILER_LEMON NAMES gcc)
endif()
if(C_COMPILER_LEMON)
message(STATUS "LEMON C compiler: ${C_COMPILER_LEMON}")
else()
set(C_COMPILER_LEMON ${CMAKE_C_COMPILER})
message(STATUS "LEMON C compiler: ${C_COMPILER_LEMON}")
endif()
cat("${TD_SUPPORT_DIR}/lemon_CMakeLists.txt.in" ${CONTRIB_TMP_FILE})
endif()
# Force specify CC=cc on MacOS. Because the default CC setting in the generated Makefile has issues finding standard library headers
IF(${TD_DARWIN})
@ -274,11 +281,13 @@ unset(CMAKE_PROJECT_INCLUDE_BEFORE)
# endif()
# lz4
add_subdirectory(lz4/build/cmake EXCLUDE_FROM_ALL)
target_include_directories(
lz4_static
PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/lz4/lib
)
if(${BUILD_WITH_LZ4})
add_subdirectory(lz4/build/cmake EXCLUDE_FROM_ALL)
target_include_directories(
lz4_static
PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/lz4/lib
)
endif(${BUILD_WITH_LZ4})
# zlib
set(CMAKE_PROJECT_INCLUDE_BEFORE "${TD_SUPPORT_DIR}/EnableCMP0048.txt.in")
@ -665,7 +674,12 @@ if(${BUILD_PCRE2})
endif(${BUILD_PCRE2})
if(${TD_LINUX} AND ${BUILD_WITH_S3})
add_subdirectory(azure-cmake EXCLUDE_FROM_ALL)
set(ORIG_CMAKE_C_FLAGS ${CMAKE_C_FLAGS})
string(REPLACE " -Werror " " " CMAKE_C_FLAGS "${CMAKE_C_FLAGS}")
add_subdirectory(xml2-cmake)
set(CMAKE_C_FLAGS ${ORIG_CMAKE_C_FLAGS})
add_subdirectory(azure-cmake)
endif()
IF(TD_LINUX)

7
contrib/azure-cmake/CMakeLists.txt
View File

@ -36,10 +36,6 @@ target_include_directories(
)
find_library(CURL_LIBRARY curl $ENV{HOME}/.cos-local.2/lib NO_DEFAULT_PATH)
find_library(XML2_LIBRARY xml2 $ENV{HOME}/.cos-local.2/lib NO_DEFAULT_PATH)
# find_library(CURL_LIBRARY curl)
# find_library(XML2_LIBRARY xml2)
find_library(SSL_LIBRARY ssl $ENV{HOME}/.cos-local.2/lib64 $ENV{HOME}/.cos-local.2/lib NO_DEFAULT_PATH)
find_library(CRYPTO_LIBRARY crypto $ENV{HOME}/.cos-local.2/lib64 $ENV{HOME}/.cos-local.2/lib NO_DEFAULT_PATH)
@ -50,9 +46,8 @@ target_link_libraries(
PRIVATE ${CURL_LIBRARY}
PRIVATE ${SSL_LIBRARY}
PRIVATE ${CRYPTO_LIBRARY}
PRIVATE ${XML2_LIBRARY}
# PRIVATE xml2
PRIVATE _libxml2
PRIVATE zlib
# PRIVATE ${CoreFoundation_Library}

6
contrib/test/CMakeLists.txt
View File

@ -20,9 +20,9 @@ if(${BUILD_WITH_SQLITE})
add_subdirectory(sqlite)
endif(${BUILD_WITH_SQLITE})
if(${BUILD_S3})
add_subdirectory(azure)
endif()
# if(${BUILD_S3})
# add_subdirectory(azure)
# endif()
add_subdirectory(tdev)
add_subdirectory(lz4)

58
contrib/xml2-cmake/CMakeLists.txt Normal file
View File

@ -0,0 +1,58 @@
set(LIBXML2_SOURCE_DIR "${TD_CONTRIB_DIR}/libxml2")
set(SRCS
"${LIBXML2_SOURCE_DIR}/SAX.c"
"${LIBXML2_SOURCE_DIR}/entities.c"
"${LIBXML2_SOURCE_DIR}/encoding.c"
"${LIBXML2_SOURCE_DIR}/error.c"
"${LIBXML2_SOURCE_DIR}/parserInternals.c"
"${LIBXML2_SOURCE_DIR}/parser.c"
"${LIBXML2_SOURCE_DIR}/tree.c"
"${LIBXML2_SOURCE_DIR}/hash.c"
"${LIBXML2_SOURCE_DIR}/list.c"
"${LIBXML2_SOURCE_DIR}/xmlIO.c"
"${LIBXML2_SOURCE_DIR}/xmlmemory.c"
"${LIBXML2_SOURCE_DIR}/uri.c"
"${LIBXML2_SOURCE_DIR}/valid.c"
"${LIBXML2_SOURCE_DIR}/xlink.c"
"${LIBXML2_SOURCE_DIR}/HTMLparser.c"
"${LIBXML2_SOURCE_DIR}/HTMLtree.c"
"${LIBXML2_SOURCE_DIR}/debugXML.c"
"${LIBXML2_SOURCE_DIR}/xpath.c"
"${LIBXML2_SOURCE_DIR}/xpointer.c"
"${LIBXML2_SOURCE_DIR}/xinclude.c"
"${LIBXML2_SOURCE_DIR}/nanohttp.c"
"${LIBXML2_SOURCE_DIR}/nanoftp.c"
"${LIBXML2_SOURCE_DIR}/catalog.c"
"${LIBXML2_SOURCE_DIR}/globals.c"
"${LIBXML2_SOURCE_DIR}/threads.c"
"${LIBXML2_SOURCE_DIR}/c14n.c"
"${LIBXML2_SOURCE_DIR}/xmlstring.c"
"${LIBXML2_SOURCE_DIR}/buf.c"
"${LIBXML2_SOURCE_DIR}/xmlregexp.c"
"${LIBXML2_SOURCE_DIR}/xmlschemas.c"
"${LIBXML2_SOURCE_DIR}/xmlschemastypes.c"
"${LIBXML2_SOURCE_DIR}/xmlunicode.c"
"${LIBXML2_SOURCE_DIR}/triostr.c"
"${LIBXML2_SOURCE_DIR}/xmlreader.c"
"${LIBXML2_SOURCE_DIR}/relaxng.c"
"${LIBXML2_SOURCE_DIR}/dict.c"
"${LIBXML2_SOURCE_DIR}/SAX2.c"
"${LIBXML2_SOURCE_DIR}/xmlwriter.c"
"${LIBXML2_SOURCE_DIR}/legacy.c"
"${LIBXML2_SOURCE_DIR}/chvalid.c"
"${LIBXML2_SOURCE_DIR}/pattern.c"
"${LIBXML2_SOURCE_DIR}/xmlsave.c"
"${LIBXML2_SOURCE_DIR}/xmlmodule.c"
"${LIBXML2_SOURCE_DIR}/schematron.c"
"${LIBXML2_SOURCE_DIR}/xzlib.c"
)
add_library(_libxml2 ${SRCS})
#target_link_libraries(_libxml2 PRIVATE td_contrib::zlib)
target_link_libraries(_libxml2 PRIVATE zlib)
target_include_directories(_libxml2 BEFORE PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/linux_x86_64/include")
target_include_directories(_libxml2 BEFORE PUBLIC "${LIBXML2_SOURCE_DIR}/include")
add_library(td_contrib::libxml2 ALIAS _libxml2)

285
contrib/xml2-cmake/linux_x86_64/include/config.h Normal file
View File

@ -0,0 +1,285 @@
/* config.h. Generated from config.h.in by configure. */
/* config.h.in. Generated from configure.ac by autoheader. */
/* Type cast for the gethostbyname() argument */
#define GETHOSTBYNAME_ARG_CAST /**/
/* Define to 1 if you have the <arpa/inet.h> header file. */
#define HAVE_ARPA_INET_H 1
/* Define to 1 if you have the <arpa/nameser.h> header file. */
#define HAVE_ARPA_NAMESER_H 1
/* Whether struct sockaddr::__ss_family exists */
/* #undef HAVE_BROKEN_SS_FAMILY */
/* Define to 1 if you have the <ctype.h> header file. */
#define HAVE_CTYPE_H 1
/* Define to 1 if you have the <dirent.h> header file. */
#define HAVE_DIRENT_H 1
/* Define to 1 if you have the <dlfcn.h> header file. */
#define HAVE_DLFCN_H 1
/* Have dlopen based dso */
#define HAVE_DLOPEN /**/
/* Define to 1 if you have the <dl.h> header file. */
/* #undef HAVE_DL_H */
/* Define to 1 if you have the <errno.h> header file. */
#define HAVE_ERRNO_H 1
/* Define to 1 if you have the <fcntl.h> header file. */
#define HAVE_FCNTL_H 1
/* Define to 1 if you have the <float.h> header file. */
#define HAVE_FLOAT_H 1
/* Define to 1 if you have the `fprintf' function. */
#define HAVE_FPRINTF 1
/* Define to 1 if you have the `ftime' function. */
#define HAVE_FTIME 1
/* Define if getaddrinfo is there */
#define HAVE_GETADDRINFO /**/
/* Define to 1 if you have the `gettimeofday' function. */
#define HAVE_GETTIMEOFDAY 1
/* Define to 1 if you have the <inttypes.h> header file. */
#define HAVE_INTTYPES_H 1
/* Define to 1 if you have the `isascii' function. */
#define HAVE_ISASCII 1
/* Define if isinf is there */
#define HAVE_ISINF /**/
/* Define if isnan is there */
#define HAVE_ISNAN /**/
/* Define if history library is there (-lhistory) */
/* #undef HAVE_LIBHISTORY */
/* Define if pthread library is there (-lpthread) */
#define HAVE_LIBPTHREAD /**/
/* Define if readline library is there (-lreadline) */
/* #undef HAVE_LIBREADLINE */
/* Define to 1 if you have the <limits.h> header file. */
#define HAVE_LIMITS_H 1
/* Define to 1 if you have the `localtime' function. */
#define HAVE_LOCALTIME 1
/* Define to 1 if you have the <lzma.h> header file. */
/* #undef HAVE_LZMA_H */
/* Define to 1 if you have the <malloc.h> header file. */
#define HAVE_MALLOC_H 1
/* Define to 1 if you have the <math.h> header file. */
#define HAVE_MATH_H 1
/* Define to 1 if you have the <memory.h> header file. */
#define HAVE_MEMORY_H 1
/* Define to 1 if you have the `mmap' function. */
#define HAVE_MMAP 1
/* Define to 1 if you have the `munmap' function. */
#define HAVE_MUNMAP 1
/* mmap() is no good without munmap() */
#if defined(HAVE_MMAP) && !defined(HAVE_MUNMAP)
# undef /**/ HAVE_MMAP
#endif
/* Define to 1 if you have the <ndir.h> header file, and it defines `DIR'. */
/* #undef HAVE_NDIR_H */
/* Define to 1 if you have the <netdb.h> header file. */
#define HAVE_NETDB_H 1
/* Define to 1 if you have the <netinet/in.h> header file. */
#define HAVE_NETINET_IN_H 1
/* Define to 1 if you have the <poll.h> header file. */
#define HAVE_POLL_H 1
/* Define to 1 if you have the `printf' function. */
#define HAVE_PRINTF 1
/* Define if <pthread.h> is there */
#define HAVE_PTHREAD_H /**/
/* Define to 1 if you have the `putenv' function. */
#define HAVE_PUTENV 1
/* Define to 1 if you have the `rand' function. */
#define HAVE_RAND 1
/* Define to 1 if you have the `rand_r' function. */
#define HAVE_RAND_R 1
/* Define to 1 if you have the <resolv.h> header file. */
#define HAVE_RESOLV_H 1
/* Have shl_load based dso */
/* #undef HAVE_SHLLOAD */
/* Define to 1 if you have the `signal' function. */
#define HAVE_SIGNAL 1
/* Define to 1 if you have the <signal.h> header file. */
#define HAVE_SIGNAL_H 1
/* Define to 1 if you have the `snprintf' function. */
#define HAVE_SNPRINTF 1
/* Define to 1 if you have the `sprintf' function. */
#define HAVE_SPRINTF 1
/* Define to 1 if you have the `srand' function. */
#define HAVE_SRAND 1
/* Define to 1 if you have the `sscanf' function. */
#define HAVE_SSCANF 1
/* Define to 1 if you have the `stat' function. */
#define HAVE_STAT 1
/* Define to 1 if you have the <stdarg.h> header file. */
#define HAVE_STDARG_H 1
/* Define to 1 if you have the <stdint.h> header file. */
#define HAVE_STDINT_H 1
/* Define to 1 if you have the <stdlib.h> header file. */
#define HAVE_STDLIB_H 1
/* Define to 1 if you have the `strftime' function. */
#define HAVE_STRFTIME 1
/* Define to 1 if you have the <strings.h> header file. */
#define HAVE_STRINGS_H 1
/* Define to 1 if you have the <string.h> header file. */
#define HAVE_STRING_H 1
/* Define to 1 if you have the <sys/dir.h> header file, and it defines `DIR'.
*/
/* #undef HAVE_SYS_DIR_H */
/* Define to 1 if you have the <sys/mman.h> header file. */
#define HAVE_SYS_MMAN_H 1
/* Define to 1 if you have the <sys/ndir.h> header file, and it defines `DIR'.
*/
/* #undef HAVE_SYS_NDIR_H */
/* Define to 1 if you have the <sys/select.h> header file. */
#define HAVE_SYS_SELECT_H 1
/* Define to 1 if you have the <sys/socket.h> header file. */
#define HAVE_SYS_SOCKET_H 1
/* Define to 1 if you have the <sys/stat.h> header file. */
#define HAVE_SYS_STAT_H 1
/* Define to 1 if you have the <sys/timeb.h> header file. */
#define HAVE_SYS_TIMEB_H 1
/* Define to 1 if you have the <sys/time.h> header file. */
#define HAVE_SYS_TIME_H 1
/* Define to 1 if you have the <sys/types.h> header file. */
#define HAVE_SYS_TYPES_H 1
/* Define to 1 if you have the `time' function. */
#define HAVE_TIME 1
/* Define to 1 if you have the <time.h> header file. */
#define HAVE_TIME_H 1
/* Define to 1 if you have the <unistd.h> header file. */
#define HAVE_UNISTD_H 1
/* Whether va_copy() is available */
#define HAVE_VA_COPY 1
/* Define to 1 if you have the `vfprintf' function. */
#define HAVE_VFPRINTF 1
/* Define to 1 if you have the `vsnprintf' function. */
#define HAVE_VSNPRINTF 1
/* Define to 1 if you have the `vsprintf' function. */
#define HAVE_VSPRINTF 1
/* Define to 1 if you have the <zlib.h> header file. */
/* #undef HAVE_ZLIB_H */
/* Whether __va_copy() is available */
/* #undef HAVE___VA_COPY */
/* Define as const if the declaration of iconv() needs const. */
#define ICONV_CONST
/* Define to the sub-directory where libtool stores uninstalled libraries. */
#define LT_OBJDIR ".libs/"
/* Name of package */
#define PACKAGE "libxml2"
/* Define to the address where bug reports for this package should be sent. */
#define PACKAGE_BUGREPORT ""
/* Define to the full name of this package. */
#define PACKAGE_NAME ""
/* Define to the full name and version of this package. */
#define PACKAGE_STRING ""
/* Define to the one symbol short name of this package. */
#define PACKAGE_TARNAME ""
/* Define to the home page for this package. */
#define PACKAGE_URL ""
/* Define to the version of this package. */
#define PACKAGE_VERSION ""
/* Type cast for the send() function 2nd arg */
#define SEND_ARG2_CAST /**/
/* Define to 1 if you have the ANSI C header files. */
#define STDC_HEADERS 1
/* Support for IPv6 */
#define SUPPORT_IP6 /**/
/* Define if va_list is an array type */
#define VA_LIST_IS_ARRAY 1
/* Version number of package */
#define VERSION "2.9.8"
/* Determine what socket length (socklen_t) data type is */
#define XML_SOCKLEN_T socklen_t
/* Define for Solaris 2.5.1 so the uint32_t typedef from <sys/synch.h>,
<pthread.h>, or <semaphore.h> is not used. If the typedef were allowed, the
#define below would cause a syntax error. */
/* #undef _UINT32_T */
/* ss_family is not defined here, use __ss_family instead */
/* #undef ss_family */
/* Define to the type of an unsigned integer type of width exactly 32 bits if
such a type exists and the standard includes do not define it. */
/* #undef uint32_t */

501
contrib/xml2-cmake/linux_x86_64/include/libxml/xmlversion.h Normal file
View File

@ -0,0 +1,501 @@
/*
* Summary: compile-time version information
* Description: compile-time version information for the XML library
*
* Copy: See Copyright for the status of this software.
*
* Author: Daniel Veillard
*/
#ifndef __XML_VERSION_H__
#define __XML_VERSION_H__
#include <libxml/xmlexports.h>
#ifdef __cplusplus
extern "C" {
#endif
/*
* use those to be sure nothing nasty will happen if
* your library and includes mismatch
*/
#ifndef LIBXML2_COMPILING_MSCCDEF
XMLPUBFUN void XMLCALL xmlCheckVersion(int version);
#endif /* LIBXML2_COMPILING_MSCCDEF */
/**
* LIBXML_DOTTED_VERSION:
*
* the version string like "1.2.3"
*/
#define LIBXML_DOTTED_VERSION "2.10.3"
/**
* LIBXML_VERSION:
*
* the version number: 1.2.3 value is 10203
*/
#define LIBXML_VERSION 21003
/**
* LIBXML_VERSION_STRING:
*
* the version number string, 1.2.3 value is "10203"
*/
#define LIBXML_VERSION_STRING "21003"
/**
* LIBXML_VERSION_EXTRA:
*
* extra version information, used to show a git commit description
*/
#define LIBXML_VERSION_EXTRA ""
/**
* LIBXML_TEST_VERSION:
*
* Macro to check that the libxml version in use is compatible with
* the version the software has been compiled against
*/
#define LIBXML_TEST_VERSION xmlCheckVersion(21003);
#ifndef VMS
#if 0
/**
* WITH_TRIO:
*
* defined if the trio support need to be configured in
*/
#define WITH_TRIO
#else
/**
* WITHOUT_TRIO:
*
* defined if the trio support should not be configured in
*/
#define WITHOUT_TRIO
#endif
#else /* VMS */
/**
* WITH_TRIO:
*
* defined if the trio support need to be configured in
*/
#define WITH_TRIO 1
#endif /* VMS */
/**
* LIBXML_THREAD_ENABLED:
*
* Whether the thread support is configured in
*/
#if 1
#define LIBXML_THREAD_ENABLED
#endif
/**
* LIBXML_THREAD_ALLOC_ENABLED:
*
* Whether the allocation hooks are per-thread
*/
#if 0
#define LIBXML_THREAD_ALLOC_ENABLED
#endif
/**
* LIBXML_TREE_ENABLED:
*
* Whether the DOM like tree manipulation API support is configured in
*/
#if 1
#define LIBXML_TREE_ENABLED
#endif
/**
* LIBXML_OUTPUT_ENABLED:
*
* Whether the serialization/saving support is configured in
*/
#if 1
#define LIBXML_OUTPUT_ENABLED
#endif
/**
* LIBXML_PUSH_ENABLED:
*
* Whether the push parsing interfaces are configured in
*/
#if 1
#define LIBXML_PUSH_ENABLED
#endif
/**
* LIBXML_READER_ENABLED:
*
* Whether the xmlReader parsing interface is configured in
*/
#if 1
#define LIBXML_READER_ENABLED
#endif
/**
* LIBXML_PATTERN_ENABLED:
*
* Whether the xmlPattern node selection interface is configured in
*/
#if 1
#define LIBXML_PATTERN_ENABLED
#endif
/**
* LIBXML_WRITER_ENABLED:
*
* Whether the xmlWriter saving interface is configured in
*/
#if 1
#define LIBXML_WRITER_ENABLED
#endif
/**
* LIBXML_SAX1_ENABLED:
*
* Whether the older SAX1 interface is configured in
*/
#if 1
#define LIBXML_SAX1_ENABLED
#endif
/**
* LIBXML_FTP_ENABLED:
*
* Whether the FTP support is configured in
*/
#if 0
#define LIBXML_FTP_ENABLED
#endif
/**
* LIBXML_HTTP_ENABLED:
*
* Whether the HTTP support is configured in
*/
#if 1
#define LIBXML_HTTP_ENABLED
#endif
/**
* LIBXML_VALID_ENABLED:
*
* Whether the DTD validation support is configured in
*/
#if 1
#define LIBXML_VALID_ENABLED
#endif
/**
* LIBXML_HTML_ENABLED:
*
* Whether the HTML support is configured in
*/
#if 1
#define LIBXML_HTML_ENABLED
#endif
/**
* LIBXML_LEGACY_ENABLED:
*
* Whether the deprecated APIs are compiled in for compatibility
*/
#if 0
#define LIBXML_LEGACY_ENABLED
#endif
/**
* LIBXML_C14N_ENABLED:
*
* Whether the Canonicalization support is configured in
*/
#if 1
#define LIBXML_C14N_ENABLED
#endif
/**
* LIBXML_CATALOG_ENABLED:
*
* Whether the Catalog support is configured in
*/
#if 1
#define LIBXML_CATALOG_ENABLED
#endif
/**
* LIBXML_XPATH_ENABLED:
*
* Whether XPath is configured in
*/
#if 1
#define LIBXML_XPATH_ENABLED
#endif
/**
* LIBXML_XPTR_ENABLED:
*
* Whether XPointer is configured in
*/
#if 1
#define LIBXML_XPTR_ENABLED
#endif
/**
* LIBXML_XPTR_LOCS_ENABLED:
*
* Whether support for XPointer locations is configured in
*/
#if 0
#define LIBXML_XPTR_LOCS_ENABLED
#endif
/**
* LIBXML_XINCLUDE_ENABLED:
*
* Whether XInclude is configured in
*/
#if 1
#define LIBXML_XINCLUDE_ENABLED
#endif
/**
* LIBXML_ICONV_ENABLED:
*
* Whether iconv support is available
*/
#if 0
#define LIBXML_ICONV_ENABLED
#endif
/**
* LIBXML_ICU_ENABLED:
*
* Whether icu support is available
*/
#if 0
#define LIBXML_ICU_ENABLED
#endif
/**
* LIBXML_ISO8859X_ENABLED:
*
* Whether ISO-8859-* support is made available in case iconv is not
*/
#if 1
#define LIBXML_ISO8859X_ENABLED
#endif
/**
* LIBXML_DEBUG_ENABLED:
*
* Whether Debugging module is configured in
*/
#if 1
#define LIBXML_DEBUG_ENABLED
#endif
/**
* DEBUG_MEMORY_LOCATION:
*
* Whether the memory debugging is configured in
*/
#if 0
#define DEBUG_MEMORY_LOCATION
#endif
/**
* LIBXML_DEBUG_RUNTIME:
*
* Whether the runtime debugging is configured in
*/
#if 0
#define LIBXML_DEBUG_RUNTIME
#endif
/**
* LIBXML_UNICODE_ENABLED:
*
* Whether the Unicode related interfaces are compiled in
*/
#if 1
#define LIBXML_UNICODE_ENABLED
#endif
/**
* LIBXML_REGEXP_ENABLED:
*
* Whether the regular expressions interfaces are compiled in
*/
#if 1
#define LIBXML_REGEXP_ENABLED
#endif
/**
* LIBXML_AUTOMATA_ENABLED:
*
* Whether the automata interfaces are compiled in
*/
#if 1
#define LIBXML_AUTOMATA_ENABLED
#endif
/**
* LIBXML_EXPR_ENABLED:
*
* Whether the formal expressions interfaces are compiled in
*
* This code is unused and disabled unconditionally for now.
*/
#if 0
#define LIBXML_EXPR_ENABLED
#endif
/**
* LIBXML_SCHEMAS_ENABLED:
*
* Whether the Schemas validation interfaces are compiled in
*/
#if 1
#define LIBXML_SCHEMAS_ENABLED
#endif
/**
* LIBXML_SCHEMATRON_ENABLED:
*
* Whether the Schematron validation interfaces are compiled in
*/
#if 1
#define LIBXML_SCHEMATRON_ENABLED
#endif
/**
* LIBXML_MODULES_ENABLED:
*
* Whether the module interfaces are compiled in
*/
#if 1
#define LIBXML_MODULES_ENABLED
/**
* LIBXML_MODULE_EXTENSION:
*
* the string suffix used by dynamic modules (usually shared libraries)
*/
#define LIBXML_MODULE_EXTENSION ".so"
#endif
/**
* LIBXML_ZLIB_ENABLED:
*
* Whether the Zlib support is compiled in
*/
#if 1
#define LIBXML_ZLIB_ENABLED
#endif
/**
* LIBXML_LZMA_ENABLED:
*
* Whether the Lzma support is compiled in
*/
#if 0
#define LIBXML_LZMA_ENABLED
#endif
#ifdef __GNUC__
/**
* ATTRIBUTE_UNUSED:
*
* Macro used to signal to GCC unused function parameters
*/
#ifndef ATTRIBUTE_UNUSED
# if ((__GNUC__ > 2) || ((__GNUC__ == 2) && (__GNUC_MINOR__ >= 7)))
# define ATTRIBUTE_UNUSED __attribute__((unused))
# else
# define ATTRIBUTE_UNUSED
# endif
#endif
/**
* LIBXML_ATTR_ALLOC_SIZE:
*
* Macro used to indicate to GCC this is an allocator function
*/
#ifndef LIBXML_ATTR_ALLOC_SIZE
# if (!defined(__clang__) && ((__GNUC__ > 4) || ((__GNUC__ == 4) && (__GNUC_MINOR__ >= 3))))
# define LIBXML_ATTR_ALLOC_SIZE(x) __attribute__((alloc_size(x)))
# else
# define LIBXML_ATTR_ALLOC_SIZE(x)
# endif
#else
# define LIBXML_ATTR_ALLOC_SIZE(x)
#endif
/**
* LIBXML_ATTR_FORMAT:
*
* Macro used to indicate to GCC the parameter are printf like
*/
#ifndef LIBXML_ATTR_FORMAT
# if ((__GNUC__ > 3) || ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 3)))
# define LIBXML_ATTR_FORMAT(fmt,args) __attribute__((__format__(__printf__,fmt,args)))
# else
# define LIBXML_ATTR_FORMAT(fmt,args)
# endif
#else
# define LIBXML_ATTR_FORMAT(fmt,args)
#endif
#ifndef XML_DEPRECATED
# ifdef IN_LIBXML
# define XML_DEPRECATED
# else
/* Available since at least GCC 3.1 */
# define XML_DEPRECATED __attribute__((deprecated))
# endif
#endif
#else /* ! __GNUC__ */
/**
* ATTRIBUTE_UNUSED:
*
* Macro used to signal to GCC unused function parameters
*/
#define ATTRIBUTE_UNUSED
/**
* LIBXML_ATTR_ALLOC_SIZE:
*
* Macro used to indicate to GCC this is an allocator function
*/
#define LIBXML_ATTR_ALLOC_SIZE(x)
/**
* LIBXML_ATTR_FORMAT:
*
* Macro used to indicate to GCC the parameter are printf like
*/
#define LIBXML_ATTR_FORMAT(fmt,args)
/**
* XML_DEPRECATED:
*
* Macro used to indicate that a function, variable, type or struct member
* is deprecated.
*/
#ifndef XML_DEPRECATED
#define XML_DEPRECATED
#endif
#endif /* __GNUC__ */
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif

186
docs/en/05-basic/01-model.md
View File

@ -6,6 +6,8 @@ slug: /basic-features/data-model
import Image from '@theme/IdealImage';
import dataModel from '../assets/data-model-01.png';
import origintable from '../assets/data-model-origin-table.png';
import origintable2 from '../assets/data-model-origin-table-2.png';
To clearly explain the concepts of time-series data and facilitate the writing of example programs, the TDengine documentation uses smart meters as an example. These example smart meters can collect three metrics: current, voltage, and phase. In addition, each smart meter also has two static attributes: location and group ID. The data collected by these smart meters is shown in the table below.
@ -79,6 +81,19 @@ To better understand the relationship between metrics, tags, supertables, and su
<figcaption>Figure 1. The TDengine data model</figcaption>
</figure>
### Virtual Tables
The design of "one table per data collection point" and "supertables" addresses most challenges in time-series data management and analysis for industrial and IoT scenarios. However, in real-world scenarios, a single device often has multiple sensors with varying collection frequencies. For example, a wind turbine may have electrical parameters, environmental parameters, and mechanical parameters, each collected by different sensors at different intervals. This makes it difficult to describe a device with a single table, often requiring multiple tables. When analyzing data across multiple sensors, multi-level join queries become necessary, which can lead to usability and performance issues. From a user perspective, "one table per device" is more intuitive. However, directly implementing this model would result in excessive NULL values at each timestamp due to varying collection frequencies, reducing storage and query efficiency.
To resolve this, TDengine introduces **Virtual Tables** (VTables). A virtual table is a logical entity that does not store physical data but enables analytical computations by dynamically combining columns from multiple source tables (subtables or regular tables). Like physical tables, virtual tables can be categorized into **virtual supertables**, **virtual subtables**, and **virtual regular tables**. A virtual supertable can represent a complete dataset for a device or group of devices, while each virtual subtable can flexibly reference columns from different sources. This allows users to define custom data views tailored to specific analytical needs, achieving a "personalized schema per user" effect. Virtual tables cannot be written to or deleted from but are queried like physical tables. The key distinction is that virtual table data is dynamically generated during queries—only columns referenced in a query are merged into the virtual table. Thus, the same virtual table may present entirely different datasets across different queries.
**Key Features of Virtual Supertables:**
1. **Column Selection & Merging**: Users can select specific columns from multiple source tables and combine them into a unified view.
2. **Timestamp-Based Alignment**: Data is aligned by timestamp. If multiple tables have data at the same timestamp, their column values are merged into a single row. Missing values are filled with NULL.
3. **Dynamic Updates**: Virtual tables automatically reflect changes in source tables, ensuring real-time data without physical storage.
By introducing virtual tables, TDengine simplifies the management of complex device data. Regardless of how individual collection points are modeled (single-column or multi-column) or distributed across databases/tables, users can freely define data sources through virtual supertables. This enables cross-collection-point aggregation and analysis, making "one table per device" a practical reality.
### Database
A database in TDengine is used to manage a collection of tables. TDengine allows a running instance to contain multiple databases, and each database can be configured with different storage strategies. Since different types of data collection points usually have different data characteristics, such as data collection frequency, data retention period, number of replicas, data block size, etc., it is recommended to create supertables with different data characteristics in different databases.
@ -226,3 +241,174 @@ TDengine supports flexible data model designs, including multi-column and single
Although TDengine recommends using the multi-column model because it generally offers better writing and storage efficiency, the single-column model might be more suitable in certain specific scenarios. For example, if the types of quantities collected at a data collection point frequently change, using a multi-column model would require frequent modifications to the supertable's structural definition, increasing the complexity of the application. In such cases, using a single-column model can simplify the design and management of the application, as it allows independent management and expansion of each physical quantity's supertable.
Overall, TDengine offers flexible data model options, allowing users to choose the most suitable model based on actual needs and scenarios to optimize performance and manage complexity.
### Creating Virtual Tables
Whether using single-column or multi-column models, TDengine enables cross-table operations through virtual tables. Using smart meters as an example, here we introduce two typical use cases for virtual tables:
1. Single-Source Multi-Dimensional Time-Series Aggregation
2. Cross-Source Metric Comparative Analysis
---
#### 1. Single-Source Multi-Dimensional Time-Series Aggregation
In this scenario, "single-source" refers to multiple **single-column time-series tables** from the **same data collection point**. While these tables are physically split due to business requirements or constraints, they maintain logical consistency through device tags and timestamps. Virtual tables restore "vertically" split data into a complete "horizontal" view of the collection point.
For example, Suppose three supertables are created for current, voltage, and phase measurements using a single-column model. Virtual tables can aggregate these three measurements into one unified view.
The SQL statement for creating a supertable in the single-column model is as follows:
```sql
CREATE STABLE current_stb (
ts timestamp,
current float
) TAGS (
device_id varchar(64),
location varchar(64),
group_id int
);
CREATE STABLE voltage_stb (
ts timestamp,
voltage int
) TAGS (
device_id varchar(64),
location varchar(64),
group_id int
);
CREATE STABLE phase_stb (
ts timestamp,
phase float
) TAGS (
device_id varchar(64),
location varchar(64),
group_id int
);
```
Assume there are four devices: d1001, d1002, d1003, and d1004. To create subtables for their current, voltage, and phase measurements, use the following SQL statements:
```sql
create table current_d1001 using current_stb(deviceid, location, group_id) tags("d1001", "California.SanFrancisco", 2);
create table current_d1002 using current_stb(deviceid, location, group_id) tags("d1002", "California.SanFrancisco", 3);
create table current_d1003 using current_stb(deviceid, location, group_id) tags("d1003", "California.LosAngeles", 3);
create table current_d1004 using current_stb(deviceid, location, group_id) tags("d1004", "California.LosAngeles", 2);
create table voltage_d1001 using voltage_stb(deviceid, location, group_id) tags("d1001", "California.SanFrancisco", 2);
create table voltage_d1002 using voltage_stb(deviceid, location, group_id) tags("d1002", "California.SanFrancisco", 3);
create table voltage_d1003 using voltage_stb(deviceid, location, group_id) tags("d1003", "California.LosAngeles", 3);
create table voltage_d1004 using voltage_stb(deviceid, location, group_id) tags("d1004", "California.LosAngeles", 2);
create table phase_d1001 using phase_stb(deviceid, location, group_id) tags("d1001", "California.SanFrancisco", 2);
create table phase_d1002 using phase_stb(deviceid, location, group_id) tags("d1002", "California.SanFrancisco", 3);
create table phase_d1003 using phase_stb(deviceid, location, group_id) tags("d1003", "California.LosAngeles", 3);
create table phase_d1004 using phase_stb(deviceid, location, group_id) tags("d1004", "California.LosAngeles", 2);
```
A virtual supertable can be used to aggregate these three types of measurements into a single table. The SQL statement to create the virtual supertable is as follows:
```sql
CREATE STABLE meters_v (
ts timestamp,
current float,
voltage int,
phase float
) TAGS (
location varchar(64),
group_id int
) VIRTUAL 1;
```
For the four devices d1001, d1002, d1003, and d1004, create virtual subtables with the following SQL statements:
```sql
CREATE VTABLE d1001_v (
current from current_d1001.current,
voltage from voltage_d1001.voltage,
phase from phase_d1001.phase
)
USING meters_v
TAGS (
"California.SanFrancisco",
2
);
CREATE VTABLE d1002_v (
current from current_d1002.current,
voltage from voltage_d1002.voltage,
phase from phase_d1002.phase
)
USING meters_v
TAGS (
"California.SanFrancisco",
3
);
CREATE VTABLE d1003_v (
current from current_d1003.current,
voltage from voltage_d1003.voltage,
phase from phase_d1003.phase
)
USING meters_v
TAGS (
"California.LosAngeles",
3
);
CREATE VTABLE d1004_v (
current from current_d1004.current,
voltage from voltage_d1004.voltage,
phase from phase_d1004.phase
)
USING meters_v
TAGS (
"California.LosAngeles",
2
);
```
Taking device d1001 as an example, assume that the current, voltage, and phase data of device d1001 are as follows:
<img src={origintable} width="500" alt="data-model-origin-table" />
| Timestamp | Current | Voltage | Phase |
|-------------------|---------|---------|-------|
| 1538548685000 | 10.3 | 219 | 0.31 |
| 1538548695000 | 12.6 | 218 | 0.33 |
| 1538548696800 | 12.3 | 221 | 0.31 |
| 1538548697100 | 12.1 | 220 | NULL |
| 1538548697200 | NULL | NULL | 0.32 |
| 1538548697700 | 11.8 | NULL | NULL |
| 1538548697800 | NULL | 222 | 0.33 |
---
#### 2. Cross-Source Metric Comparative Analysis
In this scenario, "cross-source" refers to data from **different data collection points**. Virtual tables align and merge semantically comparable measurements from multiple devices for comparative analysis.
For example, Compare current measurements across devices `d1001`, `d1002`, `d1003`, and `d1004`. The SQL statement to create the virtual table is as follows:
```sql
CREATE VTABLE current_v (
ts TIMESTAMP,
d1001_current FLOAT FROM current_d1001.current,
d1002_current FLOAT FROM current_d1002.current,
d1003_current FLOAT FROM current_d1003.current,
d1004_current FLOAT FROM current_d1004.current
);
```
Assume that the current data of devices d1001, d1002, d1003, and d1004 are as follows:
<img src={origintable2} width="500" alt="data-model-origin-table-2" />
The virtual table `current_v` aligns current data by timestamp:
| Timestamp | d1001_current | d1002_current | d1003_current | d1004_current |
|-------------------|---------------|---------------|---------------|---------------|
| 1538548685000 | 10.3 | 11.7 | 11.2 | 12.4 |
| 1538548695000 | 12.6 | 11.9 | 10.8 | 11.3 |
| 1538548696800 | 12.3 | 12.4 | 12.3 | 10.1 |
| 1538548697100 | 12.1 | NULL | 11.1 | NULL |
| 1538548697200 | NULL | 12.2 | NULL | 11.7 |
| 1538548697700 | 11.8 | 11.4 | NULL | NULL |
| 1538548697800 | NULL | NULL | 12.1 | 12.6 |

9
docs/en/06-advanced/01-subscription.md
View File

@ -69,10 +69,10 @@ This statement creates a subscription that includes all table data in the databa
## Delete Topic
If you no longer need to subscribe to the data, you can delete the topic. Note that only topics that are not currently subscribed can be deleted.
If you no longer need to subscribe to the data, you can delete the topic. If the current topic is subscribed to by a consumer, it can be forcibly deleted using the FORCE syntax. After the forced deletion, the subscribed consumer will consume data with errors (FORCE syntax supported from version 3.3.6.0).
```sql
DROP TOPIC [IF EXISTS] topic_name;
DROP TOPIC [IF EXISTS] [FORCE] topic_name;
```
## View Topics
@ -99,10 +99,10 @@ Displays information about all consumers in the current database, including the
### Delete Consumer Group
When creating a consumer, a consumer group is assigned to the consumer. Consumers cannot be explicitly deleted, but the consumer group can be deleted with the following statement when there are no consumers in the group:
When creating a consumer, a consumer group is assigned to the consumer. Consumers cannot be explicitly deleted, but the consumer group can be deleted. If there are consumers in the current consumer group who are consuming, the FORCE syntax can be used to force deletion. After forced deletion, subscribed consumers will consume data with errors (FORCE syntax supported from version 3.3.6.0).
```sql
DROP CONSUMER GROUP [IF EXISTS] cgroup_name ON topic_name;
DROP CONSUMER GROUP [IF EXISTS] [FORCE] cgroup_name ON topic_name;
```
## Data Subscription
@ -137,6 +137,7 @@ If the following 3 data entries were written, then during replay, the first entr
When using the data subscription's replay feature, note the following:
- Enable replay function by configuring the consumption parameter enable.replay to true
- The replay function of data subscription only supports data playback for query subscriptions; supertable and database subscriptions do not support playback.
- Replay does not support progress saving.
- Because data playback itself requires processing time, there is a precision error of several tens of milliseconds in playback.

19
docs/en/06-advanced/03-stream.md
View File

@ -26,11 +26,11 @@ CREATE STREAM [IF NOT EXISTS] stream_name [stream_options] INTO stb_name
SUBTABLE(expression) AS subquery
stream_options: {
TRIGGER [AT_ONCE | WINDOW_CLOSE | MAX_DELAY time | FORCE_WINDOW_CLOSE]
TRIGGER [AT_ONCE | WINDOW_CLOSE | MAX_DELAY time | FORCE_WINDOW_CLOSE | CONTINUOUS_WINDOW_CLOSE [recalculate rec_time_val] ]
WATERMARK time
IGNORE EXPIRED [0|1]
DELETE_MARK time
FILL_HISTORY [0|1]
FILL_HISTORY [0|1] [ASYNC]
IGNORE UPDATE [0|1]
}
@ -108,6 +108,13 @@ Under normal circumstances, stream computation tasks will not process data that
By enabling the fill_history option, the created stream computation task will be capable of processing data written before, during, and after the creation of the stream. This means that data written either before or after the creation of the stream will be included in the scope of stream computation, thus ensuring data integrity and consistency. This setting provides users with greater flexibility, allowing them to flexibly handle historical and new data according to actual needs.
Tips:
- When enabling fill_history, creating a stream requires finding the boundary point of historical data. If there is a lot of historical data, it may cause the task of creating a stream to take a long time. In this case, you can use fill_history 1 async (supported since version 3.3.6.0) , then the task of creating a stream can be processed in the background. The statement of creating a stream can be returned immediately without blocking subsequent operations. async only takes effect when fill_history 1 is used, and creating a stream with fill_history 0 is very fast and does not require asynchronous processing.
- Show streams can be used to view the progress of background stream creation (ready status indicates success, init status indicates stream creation in progress, failed status indicates that the stream creation has failed, and the message column can be used to view the reason for the failure. In the case of failed stream creation, the stream can be deleted and rebuilt).
- Besides, do not create multiple streams asynchronously at the same time, as transaction conflicts may cause subsequent streams to fail.
For example, create a stream to count the number of data entries generated by all smart meters every 10s, and also calculate historical data. SQL as follows:
```sql
@ -135,8 +142,12 @@ When creating a stream, you can specify the trigger mode of stream computing thr
1. AT_ONCE: Triggered immediately upon writing.
2. WINDOW_CLOSE: Triggered when the window closes (the closing of the window is determined by the event time, can be used in conjunction with watermark).
3. MAX_DELAY time: If the window closes, computation is triggered. If the window has not closed, and the duration since it has not closed exceeds the time specified by max delay, computation is triggered.
4. FORCE_WINDOW_CLOSE: Based on the current time of the operating system, only the results of the currently closed window are calculated and pushed out. The window is only calculated once at the moment of closure, and will not be recalculated subsequently. This mode currently only supports INTERVAL windows (does not support sliding); FILL_HISTORY must be 0, IGNORE EXPIRED must be 1, IGNORE UPDATE must be 1; FILL only supports PREV, NULL, NONE, VALUE.
4. FORCE_WINDOW_CLOSE: Based on the current time of the operating system, only the results of the currently closed window are calculated and pushed out. The window is only calculated once at the moment of closure, and will not be recalculated subsequently. This mode currently only supports INTERVAL windows (does support sliding); In this mode, FILL_HISTORY is automatically set to 0, IGNORE EXPIRED is automatically set to 1 and IGNORE UPDATE is automatically set to 1; FILL only supports PREV, NULL, NONE, VALUE.
- This mode can be used to implement continuous queries, such as creating a stream that queries the number of data entries in the past 10 seconds window every 1 second。SQL as follows:
```sql
create stream if not exists continuous_query_s trigger force_window_close into continuous_query as select count(*) from power.meters interval(10s) sliding(1s)
```
5. CONTINUOUS_WINDOW_CLOSE: Results are output when the window is closed. Modifying or deleting data does not immediately trigger a recalculation. Instead, periodic recalculations are performed every rec_time_val duration. If rec_time_val is not specified, the recalculation period is 60 minutes. If the recalculation time exceeds rec_time_val, the next recalculation will be automatically initiated after the current one is completed. Currently, this mode only supports INTERVAL windows. If the FILL clause is used, relevant information of the adapter needs to be configured, including adapterFqdn, adapterPort, and adapterToken. The adapterToken is a string obtained by Base64-encoding `{username}:{password}`. For example, after encoding `root:taosdata`, the result is `cm9vdDp0YW9zZGF0YQ==`.
The closing of the window is determined by the event time, such as when the event stream is interrupted or continuously delayed, at which point the event time cannot be updated, possibly leading to outdated computation results.
Therefore, stream computing provides the MAX_DELAY trigger mode that combines event time with processing time: MAX_DELAY mode triggers computation immediately when the window closes, and its unit can be specified, specific units: a (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks). Additionally, when data is written, if the time that triggers computation exceeds the time specified by MAX_DELAY, computation is triggered immediately.

3
docs/en/07-develop/07-tmq.md
View File

@ -44,6 +44,9 @@ There are many parameters for creating consumers, which flexibly support various
| `enable.replay` | boolean | Whether to enable data replay function | Default is off |
| `session.timeout.ms` | integer | Timeout after consumer heartbeat is lost, after which rebalance logic is triggered, and upon success, that consumer will be removed (supported from version 3.3.3.0) | Default is 12000, range [6000, 1800000] |
| `max.poll.interval.ms` | integer | The longest time interval for consumer poll data fetching, exceeding this time will be considered as the consumer being offline, triggering rebalance logic, and upon success, that consumer will be removed (supported from version 3.3.3.0) | Default is 300000, range [1000, INT32_MAX] |
| `fetch.max.wait.ms` | integer | The maximum time it takes for the server to return data once (supported from version 3.3.6.0) | Default is 1000, range [1, INT32_MAX] |
| `min.poll.rows` | integer | The minimum number of data returned by the server once (supported from version 3.3.6.0) | Default is 4096, range [1, INT32_MAX]
| `msg.consume.rawdata` | integer | When consuming data, the data type pulled is binary and cannot be parsed. It is an internal parameter and is only used for taosx data migration（supported from version 3.3.6.0） | The default value of 0 indicates that it is not effective, and non-zero indicates that it is effective |
Below are the connection parameters for connectors in various languages:
<Tabs defaultValue="java" groupId="lang">

46
docs/en/07-develop/09-udf.md
View File

@ -298,13 +298,53 @@ select max_vol(vol1, vol2, vol3, deviceid) from battery;
</details>
#### Aggregate Function Example 3 Split string and calculate average value [extract_avg](https://github.com/taosdata/TDengine/blob/3.0/tests/script/sh/extract_avg.c)
The `extract_avg` function converts a comma-separated string sequence into a set of numerical values, counts the results of all rows, and calculates the final average. Note when implementing:
- `interBuf->numOfResult` needs to return 1 or 0 and cannot be used for count.
- Count can use additional caches, such as the `SumCount` structure.
- Use `varDataVal` to obtain the string.
Create table:
```shell
create table scores(ts timestamp, varStr varchar(128));
```
Create custom function:
```shell
create aggregate function extract_avg as '/root/udf/libextract_avg.so' outputtype double bufsize 16 language 'C';
```
Use custom function:
```shell
select extract_avg(valStr) from scores;
```
Generate `.so` file
```bash
gcc -g -O0 -fPIC -shared extract_vag.c -o libextract_avg.so
```
<details>
<summary>max_vol.c</summary>
```c
{{#include tests/script/sh/max_vol.c}}
```
</details>
## Developing UDFs in Python Language
### Environment Setup
The specific steps to prepare the environment are as follows:
- Step 1, prepare the Python runtime environment.
- Step 1, prepare the Python runtime environment. If you compile and install Python locally, be sure to enable the `--enable-shared` option, otherwise the subsequent installation of taospyudf will fail due to failure to generate a shared library.
- Step 2, install the Python package taospyudf. The command is as follows.
```shell
@ -495,10 +535,10 @@ taos> select myfun(v1, v2) from t;
DB error: udf function execution failure (0.011088s)
```
Unfortunately, the execution failed. What could be the reason? Check the udfd process logs.
Unfortunately, the execution failed. What could be the reason? Check the taosudf process logs.
```shell
tail -10 /var/log/taos/udfd.log
tail -10 /var/log/taos/taosudf.log
```
Found the following error messages.

7
docs/en/08-operation/04-maintenance.md
View File

@ -16,8 +16,10 @@ TDengine is designed for various writing scenarios, and many of these scenarios
### Syntax
```sql
COMPACT DATABASE db_name [start with 'XXXX'] [end with 'YYYY'];
SHOW COMPACTS [compact_id];
COMPACT DATABASE db_name [start with 'XXXX'] [end with 'YYYY'] [META_ONLY];
COMPACT [db_name.]VGROUPS IN (vgroup_id1, vgroup_id2, ...) [start with 'XXXX'] [end with 'YYYY'] [META_ONLY];
SHOW COMPACTS;
SHOW COMPACT compact_id;
KILL COMPACT compact_id;
```
@ -28,6 +30,7 @@ KILL COMPACT compact_id;
- COMPACT will merge multiple STT files
- You can specify the start time of the COMPACT data with the start with keyword
- You can specify the end time of the COMPACT data with the end with keyword
- You can specify the META_ONLY keyword to only compact the meta data which are not compacted by default
- The COMPACT command will return the ID of the COMPACT task
- COMPACT tasks are executed asynchronously in the background, and you can view the progress of COMPACT tasks using the SHOW COMPACTS command
- The SHOW command will return the ID of the COMPACT task, and you can terminate the COMPACT task using the KILL COMPACT command

5
docs/en/08-operation/14-user.md
View File

@ -18,7 +18,10 @@ create user user_name pass'password' [sysinfo {1|0}] [createdb {1|0}]
The parameters are explained as follows.
- user_name: Up to 23 B long.
- password: The password must be between 8 and 16 characters long and include at least three types of characters from the following: uppercase letters, lowercase letters, numbers, and special characters. Special characters include `! @ # $ % ^ & * ( ) - _ + = [ ] { } : ; > < ? | ~ , .`.
- password: The password must be between 8 and 255 characters long. The password include at least three types of characters from the following: uppercase letters, lowercase letters, numbers, and special characters, special characters include `! @ # $ % ^ & * ( ) - _ + = [ ] { } : ; > < ? | ~ , .`, and this reqirement is able to be closed by adding enableStrongPassword 0 in taos.cfg, or by the following SQL:
```sql
alter all dnode 'EnableStrongPassword' '0'
```
- sysinfo: Whether the user can view system information. 1 means they can view it, 0 means they cannot. System information includes server configuration information, various node information such as dnode, query node (qnode), etc., as well as storage-related information, etc. The default is to view system information.
- createdb: Whether the user can create databases. 1 means they can create databases, 0 means they cannot. The default value is 0. // Supported starting from TDengine Enterprise version 3.3.2.0

278
docs/en/08-operation/17-security-suggestions.md Normal file
View File

@ -0,0 +1,278 @@
---
sidebar_label: Security Suggestions
title: Security Suggestions
toc_max_heading_level: 4
---
import Image from '@theme/IdealImage';
import imgEcosys from '../assets/tdengine-components-01.png';
## Background
The distributed and multi-component nature of TDengine makes its security configuration a concern in production systems. This document aims to explain the security issues of various TDengine components and different deployment methods, and provide deployment and configuration suggestions to support the security of user data.
## Components Involved in Security Configuration
TDengine includes multiple components:
- `taosd`: Core component.
- `taosc`: Client library.
- `taosAdapter`: REST API and WebSocket service.
- `taosKeeper`: Monitoring service component.
- `taosX`: Data pipeline and backup recovery component.
- `taosxAgent`: Auxiliary component for external data source access.
- `taosExplorer`: Web visualization management interface.
In addition to TDengine deployment and applications, there are also the following components:
- Applications that access and use the TDengine database through various connectors.
- External data sources: Other data sources that access TDengine, such as MQTT, OPC, Kafka, etc.
The relationship between the components is as follows:
<figure>
<Image img={imgEcosys} alt="TDengine ecosystem"/>
<figcaption>TDengine ecosystem</figcaption>
</figure>
## TDengine Security Settings
### `taosd`
The `taosd` cluster uses TCP connections based on its own protocol for data exchange, which has low risk, but the transmission process is not encrypted, so there is still some security risk.
Enabling compression may help with TCP data obfuscation.
- **compressMsgSize**: Whether to compress RPC messages. Integer, optional: -1: Do not compress any messages; 0: Compress all messages; N (N>0): Only compress messages larger than N bytes.
To ensure the traceability of database operations, it is recommended to enable the audit function.
- **audit**: Audit function switch, 0 is off, 1 is on. Default is on.
- **auditInterval**: Reporting interval, in milliseconds. Default is 5000.
- **auditCreateTable**: Whether to enable the audit function for creating sub-tables. 0 is off, 1 is on. Default is on.
To ensure the security of data files, database encryption can be enabled.
- **encryptAlgorithm**: Data encryption algorithm.
- **encryptScope**: Data encryption scope.
Enabling the whitelist can restrict access addresses and further enhance privacy.
- **enableWhiteList**: Whitelist function switch, 0 is off, 1 is on; default is off.
### `taosc`
Users and other components use the native client library (`taosc`) and its own protocol to connect to `taosd`, which has low data security risk, but the transmission process is still not encrypted, so there is some security risk.
### `taosAdapter`
`taosAdapter` uses the native client library (`taosc`) and its own protocol to connect to `taosd`, and also supports RPC message compression, so there is no data security issue.
Applications and other components connect to `taosAdapter` through various language connectors. By default, the connection is based on HTTP 1.1 and is not encrypted. To ensure the security of data transmission between `taosAdapter` and other components, SSL encrypted connections need to be configured. Modify the following configuration in the `/etc/taos/taosadapter.toml` configuration file:
```toml
[ssl]
enable = true
certFile = "/path/to/certificate-file"
keyFile = "/path/to/private-key"
```
Configure HTTPS/SSL access in the connector to complete encrypted access.
To further enhance security, the whitelist function can be enabled, and configured in `taosd`, which also applies to the `taosAdapter` component.
### `taosX`
`taosX` includes REST API and gRPC interfaces, where the gRPC interface is used for `taos-agent` connections.
- The REST API interface is based on HTTP 1.1 and is not encrypted, posing a security risk.
- The gRPC interface is based on HTTP 2 and is not encrypted, posing a security risk.
To ensure data security, it is recommended that the `taosX` API interface is limited to internal access only. Modify the following configuration in the `/etc/taos/taosx.toml` configuration file:
```toml
[serve]
listen = "127.0.0.1:6050"
grpc = "127.0.0.1:6055"
```
Starting from TDengine 3.3.6.0, `taosX` supports HTTPS connections. Add the following configuration in the `/etc/taos/taosx.toml` file:
```toml
[serve]
ssl_cert = "/path/to/server.pem"
ssl_key = "/path/to/server.key"
ssl_ca = "/path/to/ca.pem"
```
And modify the API address to HTTPS connection in Explorer:
```toml
# Local connection to taosX API
x_api = "https://127.0.01:6050"
# Public IP or domain address
grpc = "https://public.domain.name:6055"
```
### `taosExplorer`
Similar to the `taosAdapter` component, the `taosExplorer` component provides HTTP services for external access. Modify the following configuration in the `/etc/taos/explorer.toml` configuration file:
```toml
[ssl]
# SSL certificate file
certificate = "/path/to/ca.file"
# SSL certificate private key
certificate_key = "/path/to/key.file"
```
Then, use HTTPS to access Explorer, such as [https://192.168.12.34](https://192.168.12.34:6060).
### `taosxAgent`
After `taosX` enables HTTPS, the `Agent` component and `taosX` use HTTP 2 encrypted connections, using Arrow-Flight RPC for data exchange. The transmission content is in binary format, and only registered `Agent` connections are valid, ensuring data security.
It is recommended to always enable HTTPS connections for `Agent` services in insecure or public network environments.
### `taosKeeper`
`taosKeeper` uses WebSocket connections to communicate with `taosAdapter`, writing monitoring information reported by other components into TDengine.
The current version of `taosKeeper` has security risks:
- The monitoring address cannot be restricted to the local machine. By default, it monitors all addresses on port 6043, posing a risk of network attacks. This risk can be ignored when deploying with Docker or Kubernetes without exposing the `taosKeeper` port.
- The configuration file contains plaintext passwords, so the visibility of the configuration file needs to be reduced. In `/etc/taos/taoskeeper.toml`:
```toml
[tdengine]
host = "localhost"
port = 6041
username = "root"
password = "taosdata"
usessl = false
```
## Security Enhancements
We recommend using TDengine within a local area network.
If you must provide access outside the local area network, consider adding the following configurations:
### Load Balancing
Use load balancing to provide `taosAdapter` services externally.
Take Nginx as an example to configure multi-node load balancing:
```nginx
http {
server {
listen 6041;
location / {
proxy_pass http://websocket;
# Headers for websocket compatible
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# Forwarded headers
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-Server $hostname;
proxy_set_header X-Real-IP $remote_addr;
}
}
upstream websocket {
server 192.168.11.61:6041;
server 192.168.11.62:6041;
server 192.168.11.63:6041;
}
}
```
If the `taosAdapter` component is not configured with SSL secure connections, SSL needs to be configured to ensure secure access. SSL can be configured at a higher-level API Gateway or in Nginx; if you have stronger security requirements for the connections between components, you can configure SSL in all components. The Nginx configuration is as follows:
```nginx
http {
server {
listen 443 ssl;
ssl_certificate /path/to/your/certificate.crt;
ssl_certificate_key /path/to/your/private.key;
}
}
```
### Security Gateway
In modern internet production systems, the use of security gateways is also very common. [traefik](https://traefik.io/) is a good open-source choice. We take traefik as an example to explain the security configuration in the API gateway.
Traefik provides various security configurations through middleware, including:
1. Authentication: Traefik provides multiple authentication methods such as BasicAuth, DigestAuth, custom authentication middleware, and OAuth 2.0.
2. IP Whitelist: Restrict the allowed client IPs.
3. Rate Limit: Control the number of requests sent to the service.
4. Custom Headers: Add configurations such as `allowedHosts` through custom headers to improve security.
A common middleware example is as follows:
```yaml
labels:
- "traefik.enable=true"
- "traefik.http.routers.tdengine.rule=Host(`api.tdengine.example.com`)"
- "traefik.http.routers.tdengine.entrypoints=https"
- "traefik.http.routers.tdengine.tls.certresolver=default"
- "traefik.http.routers.tdengine.service=tdengine"
- "traefik.http.services.tdengine.loadbalancer.server.port=6041"
- "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https"
- "traefik.http.middlewares.check-header.headers.customrequestheaders.X-Secret-Header=SecretValue"
- "traefik.http.middlewares.check-header.headers.customresponseheaders.X-Header-Check=true"
- "traefik.http.middlewares.tdengine-ipwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
- "traefik.http.routers.tdengine.middlewares=redirect-to-https,check-header,tdengine-ipwhitelist"
```
The above example completes the following configurations:
- TLS authentication uses the `default` configuration, which can be configured in the configuration file or traefik startup parameters, as follows:
```yaml
traefik:
image: "traefik:v2.3.2"
hostname: "traefik"
networks:
- traefik
command:
- "--log.level=INFO"
- "--api.insecure=true"
- "--providers.docker=true"
- "--providers.docker.exposedbydefault=false"
- "--providers.docker.swarmmode=true"
- "--providers.docker.network=traefik"
- "--providers.docker.watch=true"
- "--entrypoints.http.address=:80"
- "--entrypoints.https.address=:443"
- "--certificatesresolvers.default.acme.dnschallenge=true"
- "--certificatesresolvers.default.acme.dnschallenge.provider=alidns"
- "--certificatesresolvers.default.acme.dnschallenge.resolvers=ns1.alidns.com"
- "--certificatesresolvers.default.acme.email=linhehuo@gmail.com"
- "--certificatesresolvers.default.acme.storage=/letsencrypt/acme.json"
```
The above startup parameters configure the `default` TSL certificate resolver and automatic acme authentication (automatic certificate application and renewal).
- Middleware `redirect-to-https`: Configure redirection from HTTP to HTTPS, forcing the use of secure connections.
```yaml
- "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https"
```
- Middleware `check-header`: Configure custom header checks. External access must add custom headers and match header values to prevent unauthorized access. This is a very simple and effective security mechanism when providing API access.
- Middleware `tdengine-ipwhitelist`: Configure IP whitelist. Only allow specified IPs to access, using CIDR routing rules for matching, and can set internal and external IP addresses.
## Summary
Data security is a key indicator of the TDengine product. These measures are designed to protect TDengine deployments from unauthorized access and data breaches while maintaining performance and functionality. However, the security configuration of TDengine itself is not the only guarantee in production. It is more important to develop solutions that better match customer needs in combination with the user's business system.

13
docs/en/08-operation/18-dual.md
View File

@ -53,6 +53,8 @@ It is not necessary to configure your cluster specifically for active-active mod
- The sink endpoint is the FQDN of TDengine on the secondary node.
- You can use the native connection (port 6030) or WebSocket connection (port 6041).
- You can specify one or more databases to replicate only the data contained in those databases. If you do not specify a database, all databases on the node are replicated except for `information_schema`, `performance_schema`, `log`, and `audit`.
- New databases in both sides will be detected periodically to start replication, with optional `--new-database-checking-interval <SECONDS>` argument.
- New databases checking will be disabled with `--no-new-databases`.
When the command is successful, the replica ID is displayed. You can use this ID to add other databases to the replication task if necessary.
@ -97,7 +99,6 @@ You can manage your active-active deployment with the following commands:
:::note
- This command cannot create duplicate tasks. It only adds the specified databases to the specified task.
- The replica ID is globally unique within a taosX instance and is independent of the source/sink combination.
:::
2. Check the status of a task:
@ -124,6 +125,8 @@ You can manage your active-active deployment with the following commands:
If you specify a database, replication for that database is stopped. If you do not specify a database, all replication tasks on the ID are stopped. If you do not specify an ID, all replication tasks on the instance are stopped.
Use `--no-new-databases` to not stop new-databases checking.
4. Restart a replication task:
```shell
@ -132,6 +135,14 @@ You can manage your active-active deployment with the following commands:
If you specify a database, replication for that database is restarted. If you do not specify a database, all replication tasks in the instance are restarted. If you do not specify an ID, all replication tasks on the instance are restarted.
5. Update new databases checking interval:
```shell
taosx replica update id --new-database-checking-interval <SECONDS>
```
This command will only update the checking interval for new databases.
5. Check the progress of a replication task:
```shell

6
docs/en/14-reference/01-components/01-taosd.md
View File

@ -231,6 +231,7 @@ The effective value of charset is UTF-8.
|udf | |Supported, effective after restart|Whether to start UDF service; 0: do not start, 1: start; default value 0 |
|udfdResFuncs | |Supported, effective after restart|Internal parameter, for setting UDF result sets|
|udfdLdLibPath | |Supported, effective after restart|Internal parameter, indicates the library path for loading UDF|
|enableStrongPassword | After 3.3.5.0 |Supported, effective after restart|The password include at least three types of characters from the following: uppercase letters, lowercase letters, numbers, and special characters, special characters include `! @ # $ % ^ & * ( ) - _ + = [ ] { } : ; > < ? \| ~ , .`; 0: disable, 1: enable; default value 1 |
### Stream Computing Parameters
@ -243,6 +244,11 @@ The effective value of charset is UTF-8.
| concurrentCheckpoint | |Supported, effective immediately | Internal parameter, whether to check checkpoints concurrently |
| maxStreamBackendCache | |Supported, effective immediately | Internal parameter, maximum cache used by stream computing |
| streamSinkDataRate | |Supported, effective after restart| Internal parameter, used to control the write speed of stream computing results |
| streamNotifyMessageSize | After 3.3.6.0 | Not supported | Internal parameter, controls the message size for event notifications, default value is 8192 |
| streamNotifyFrameSize | After 3.3.6.0 | Not supported | Internal parameter, controls the underlying frame size when sending event notification messages, default value is 256 |
| adapterFqdn | After 3.3.6.0 | Not supported | Internal parameter, The address of the taosadapter services, default value is localhost |
| adapterPort | After 3.3.6.0 | Not supported | Internal parameter, The port of the taosadapter services, default value is 6041 |
| adapterToken | After 3.3.6.0 | Not supported | Internal parameter, The string obtained by Base64-encoding `{username}:{password}`, default value is `cm9vdDp0YW9zZGF0YQ==` |
### Log Related

1
docs/en/14-reference/01-components/02-taosc.md
View File

@ -44,6 +44,7 @@ The TDengine client driver provides all the APIs needed for application programm
|enableQueryHb | |Supported, effective immediately |Internal parameter, whether to send query heartbeat messages|
|minSlidingTime | |Supported, effective immediately |Internal parameter, minimum allowable value for sliding|
|minIntervalTime | |Supported, effective immediately |Internal parameter, minimum allowable value for interval|
|compareAsStrInGreatest | v3.3.6.0 |Supported, effective immediately |When the greatest and least functions have both numeric and string types as parameters, the comparison type conversion rules are as follows: Integer; 1: uniformly converted to string comparison, 0: uniformly converted to numeric type comparison.|
### Writing Related

37
docs/en/14-reference/02-tools/10-taosbenchmark.md
View File

@ -188,9 +188,12 @@ taosBenchmark -A INT,DOUBLE,NCHAR,BINARY\(16\)
The parameters listed in this section apply to all functional modes.
- **filetype**: The function to test, possible values are `insert`, `query`, and `subscribe`. Corresponding to insert, query, and subscribe functions. Only one can be specified in each configuration file.
- **filetype**: The function to test, possible values are `insert`, `query`, `subscribe` and `csvfile`. Corresponding to insert, query, subscribe and generate csv file functions. Only one can be specified in each configuration file.
- **cfgdir**: Directory where the TDengine client configuration file is located, default path is /etc/taos.
- **output_dir**: The directory specified for output files. When the feature category is csvfile, it refers to the directory where the generated csv files will be saved. The default value is ./output/.
- **host**: Specifies the FQDN of the TDengine server to connect to, default value is localhost.
- **port**: The port number of the TDengine server to connect to, default value is 6030.
@ -283,6 +286,27 @@ Parameters related to supertable creation are configured in the `super_tables` s
- **repeat_ts_max** : Numeric type, when composite primary key is enabled, specifies the maximum number of records with the same timestamp to be generated
- **sqls** : Array of strings type, specifies the array of sql to be executed after the supertable is successfully created, the table name specified in sql must be prefixed with the database name, otherwise an unspecified database error will occur
- **csv_file_prefix**: String type, sets the prefix for the names of the generated csv files. Default value is "data".
- **csv_ts_format**: String type, sets the format of the time string in the names of the generated csv files, following the `strftime` format standard. If not set, files will not be split by time intervals. Supported patterns include:
- %Y: Year as a four-digit number (e.g., 2025)
- %m: Month as a two-digit number (01 to 12)
- %d: Day of the month as a two-digit number (01 to 31)
- %H: Hour in 24-hour format as a two-digit number (00 to 23)
- %M: Minute as a two-digit number (00 to 59)
- %S: Second as a two-digit number (00 to 59)
- **csv_ts_interval**: String type, sets the time interval for splitting generated csv file names. Supports daily, hourly, minute, and second intervals such as 1d/2h/30m/40s. The default value is "1d".
- **csv_output_header**: String type, sets whether the generated csv files should contain column header descriptions. The default value is "yes".
- **csv_tbname_alias**: String type, sets the alias for the tbname field in the column header descriptions of csv files. The default value is "device_id".
- **csv_compress_level**: String type, sets the compression level for generating csv-encoded data and automatically compressing it into gzip file. This process directly encodes and compresses the data, rather than first generating a csv file and then compressing it. Possible values are:
- none: No compression
- fast: gzip level 1 compression
- balance: gzip level 6 compression
- best: gzip level 9 compression
#### Tag and Data Columns
@ -505,6 +529,17 @@ Note: Data types in the taosBenchmark configuration file must be in lowercase to
</details>
### Export CSV File Example
<details>
<summary>csv-export.json</summary>
```json
{{#include /TDengine/tools/taos-tools/example/csv-export.json}}
```
</details>
Other json examples see [here](https://github.com/taosdata/TDengine/tree/main/tools/taos-tools/example)
## Output Performance Indicators

13
docs/en/14-reference/03-taos-sql/01-data-type.md
View File

@ -43,6 +43,7 @@ In TDengine, the following data types can be used in the data model of basic tab
| 16 | VARCHAR | Custom | Alias for BINARY type |
| 17 | GEOMETRY | Custom | Geometry type, supported starting from version 3.1.0.0 |
| 18 | VARBINARY | Custom | Variable-length binary data, supported starting from version 3.1.1.0 |
| 19 | DECIMAL | 8 or 16 | High-precision numeric type. The range of values depends on the precision and scale specified in the type. Supported starting from version 3.3.6. See the description below. |
:::note
@ -61,6 +62,18 @@ In TDengine, the following data types can be used in the data model of basic tab
- VARBINARY is a data type for storing binary data, with a maximum length of 65,517 bytes for data columns and 16,382 bytes for label columns. Binary data can be written via SQL or schemaless methods (needs to be converted to a string starting with \x), or through stmt methods (can use binary directly). Displayed as hexadecimal starting with \x.
:::
### DECIMAL Data Type
The `DECIMAL` data type is used for high-precision numeric storage and is supported starting from version 3.3.6. The definition syntax is: `DECIMAL(18, 2)`, `DECIMAL(38, 10)`, where two parameters must be specified: `precision` and `scale`. `Precision` refers to the maximum number of significant digits supported, and `scale` refers to the maximum number of decimal places. For example, `DECIMAL(8, 4)` represents a range of `[-9999.9999, 9999.9999]`. When defining the `DECIMAL` data type, the range of `precision` is `[1, 38]`, and the range of `scale` is `[0, precision]`. If `scale` is 0, it represents integers only. You can also omit `scale`, in which case it defaults to 0. For example, `DECIMAL(18)` is equivalent to `DECIMAL(18, 0)`.
When the `precision` value is less than or equal to 18, 8 bytes of storage (DECIMAL64) are used internally. When the `precision` is in the range `(18, 38]`, 16 bytes of storage (DECIMAL) are used. When writing `DECIMAL` type data in SQL, numeric values can be written directly. If the value exceeds the maximum representable value for the type, a `DECIMAL_OVERFLOW` error will be reported. If the value does not exceed the maximum representable value but the number of decimal places exceeds the `scale`, it will be automatically rounded. For example, if the type is defined as `DECIMAL(10, 2)` and the value `10.987` is written, the actual stored value will be `10.99`.
The `DECIMAL` type only supports regular columns and does not currently support tag columns. The `DECIMAL` type supports SQL-based writes only and does not currently support `stmt` or schemaless writes.
When performing operations between integer types and the `DECIMAL` type, the integer type is converted to the `DECIMAL` type before the calculation. When the `DECIMAL` type is involved in calculations with `DOUBLE`, `FLOAT`, `VARCHAR`, or `NCHAR` types, it is converted to `DOUBLE` type for computation.
When querying `DECIMAL` type expressions, if the intermediate result of the calculation exceeds the maximum value that the current type can represent, a `DECIMAL_OVERFLOW` error is reported.
## Constants

3
docs/en/14-reference/03-taos-sql/04-stable.md
View File

@ -20,6 +20,7 @@ table_options:
table_option: {
COMMENT 'string_value'
| SMA(col_name [, col_name] ...)
| KEEP value
}
```
@ -34,6 +35,7 @@ table_option: {
- TAGS can have up to 128 columns, at least 1, with a total length not exceeding 16 KB.
4. For the use of `ENCODE` and `COMPRESS`, please refer to [Column Compression](../manage-data-compression/)
5. For explanations of parameters in table_option, please refer to [Table SQL Description](../manage-tables/)
6. Regarding the keep parameter in table_option, it only takes effect for super tables. For detailed explanation of the keep parameter, please refer to [Database Description](02-database.md). The only difference is that the super table's keep parameter does not immediately affect query results, but only takes effect after compaction.
## View Supertables
@ -144,6 +146,7 @@ alter_table_options:
alter_table_option: {
COMMENT 'string_value'
| KEEP value
}
```

272
docs/en/14-reference/03-taos-sql/05-virtualtable.md Normal file
View File

@ -0,0 +1,272 @@
---
sidebar_label: Virtual Tables
title: Virtual Tables
description: Various management operations for virtual tables
---
import origintable from './assets/virtual-table-origin-table.png';
import queryres from './assets/virtual-table-query-res.png';
import partres from './assets/virtual-table-query-res-part.png';
## Create Virtual Table
The `CREATE VTABLE` statement is used to create virtual basic tables and virtual subtables using virtual supertables as templates.
### Create Virtual Supertables
Refer to the `VIRTUAL` parameter in [Create Supertable](./04-stable.md#create-supertable).
### Create Virtual Basic Table
```sql
CREATE VTABLE [IF NOT EXISTS] [db_name].vtb_name
ts_col_name timestamp,
(create_definition[ ,create_definition] ...)
create_definition:
vtb_col_name column_definition
column_definition:
type_name [FROM [db_name.]table_name.col_name]
```
### Create Virtual Subtable
```sql
CREATE VTABLE [IF NOT EXISTS] [db_name].vtb_name
(create_definition[ ,create_definition] ...)
USING [db_name.]stb_name
[(tag_name [, tag_name] ...)]
TAGS (tag_value [, tag_value] ...)
create_definition:
[stb_col_name FROM] [db_name.]table_name.col_name
tag_value:
const_value
```
**Usage Notes**
1. Naming rules for virtual tables/columns follow [Name Rules](./19-limit.md#naming-rules).
2. Maximum table name length: 192 characters.
3. The first column must be TIMESTAMP and is automatically set as primary key.
4. Row length cannot exceed 64KB (Note: VARCHAR/NCHAR/GEOMETRY columns consume 2 extra bytes each).
5. Specify maximum length for VARCHAR/NCHAR/GEOMETRY types (e.g., VARCHAR(20)).
6. Use `FROM` to specify column data sources. Cross-database sources are supported via `db_name`.
7. The timestamp column (ts) values of virtual table are merged results from all involved tables' timestamp primary keys during queries.
8. Virtual supertables only support creating virtual subtables, virtual subtables can only use virtual supertables as template.
9. Ensure virtual tables' column/tag data types match their source columns/tags.
10. Virtual table names must be unique within a database and cannot conflict with table names, and it is recommended that view names do not duplicate virtual table names (not enforced). When a view and a virtual table have the same name, operations such as writing, querying, granting, and revoking permissions prioritize the virtual table with the same name. .
11. When creating virtual subtables/basic tables, `FROM` columns must originate from basic tables/subtables (not supertables, views, or other virtual tables).
## Query Virtual Tables
Virtual tables use the same query syntax as regular tables, but their dataset may vary between queries based on data alignment rules.
### Data Alignment Rules
1. Align data from multiple source tables by timestamp.
2. Combine columns with same timestamp into one row; missing values fill with NULL.
3. Virtual table timestamps are the union of all involved columns' origin tables' timestamps. Therefore, the number of rows in the result set may vary when different queries select different columns.
4. Users can combine any columns from multiple tables; unselected columns are excluded.
**Example**
Given tables t1, t2, t3 with data:
<img src={origintable} width="500" alt="Original Table Structure and Data" />
Create a virtual table v1:
```sql
CREATE VTABLE v1 (
ts timestamp,
c1 int FROM t1.value,
c2 int FROM t2.value,
c3 int FROM t3.value1,
c4 int FROM t3.value2);
```
Querying all columns:
```sql
SELECT * FROM v1;
```
Result:
<img src={queryres} width="200" alt="Full Query Result" />
Partial column query:
```sql
SELECT c1, c2 FROM v1;
```
Result:
<img src={partres} width="200" alt="Partial Query Result" />
Since the original tables t1 and t2 (corresponding to columns c1 and c2) lack the timestamp 0:00:03, this timestamp will not appear in the final result.
**Limitations**
1. Querying virtual supertables does not support subtables from different databases.
## Modify Virtual Basic Tables
```sql
ALTER VTABLE [db_name.]vtb_name alter_table_clause
alter_table_clause: {
ADD COLUMN vtb_col_name vtb_column_type [FROM table_name.col_name]
| DROP COLUMN vtb_col_name
| ALTER COLUMN vtb_col_name SET {table_name.col_name | NULL }
| MODIFY COLUMN col_name column_type
| RENAME COLUMN old_col_name new_col_name
}
```
### Add Column
```sql
ALTER VTABLE vtb_name ADD COLUMN vtb_col_name vtb_col_type [FROM [db_name].table_name.col_name]
```
### Drop Column
```sql
ALTER VTABLE vtb_name DROP COLUMN vtb_col_name
```
### Modify Column Width
```sql
ALTER VTABLE vtb_name MODIFY COLUMN vtb_col_name data_type(length);
```
### Rename Column
```sql
ALTER VTABLE vtb_name RENAME COLUMN old_col_name new_col_name
```
### Change Column Source
```sql
ALTER VTABLE vtb_name ALTER COLUMN vtb_col_name SET {[db_name.]table_name.col_name | NULL}
```
## Modify Virtual Subtables
```sql
ALTER VTABLE [db_name.]vtb_name alter_table_clause
alter_table_clause: {
ALTER COLUMN vtb_col_name SET table_name.col_name
| SET TAG tag_name = new_tag_value
}
```
### Modify Subtable Tag Value
```sql
ALTER VTABLE tb_name SET TAG tag_name1=new_tag_value1, tag_name2=new_tag_value2 ...;
```
### Change Column Source
```sql
ALTER VTABLE vtb_name ALTER COLUMN vtb_col_name SET {[db_name.]table_name.col_name | NULL}
```
## Drop Virtual Tables
```sql
DROP VTABLE [IF EXISTS] [dbname].vtb_name;
```
## View Virtual Table Information
### List Virtual Tables
```sql
SHOW [NORMAL | CHILD] [db_name.]VTABLES [LIKE 'pattern'];
```
### Show Creation Statement
```sql
SHOW CREATE VTABLE [db_name.]vtable_name;
```
### Describe Structure
```sql
DESCRIBE [db_name.]vtb_name;
```
### Query All Virtual Tables' Information
```sql
SELECT ... FROM information_schema.ins_tables WHERE type = 'VIRTUAL_NORMAL_TABLE' OR type = 'VIRTUAL_CHILD_TABLE';
```
## Write to Virtual Tables
Writing or deleting data in virtual tables is **not supported**. Virtual tables are logical views computed from source tables.
## Virtual Tables vs. Views
| Property | Virtual Table | View |
|-----------------------|-----------------------------------|-------------------------------|
| **Definition** | Dynamic structure combining multiple tables by timestamp. | Saved SQL query definition. |
| **Data Source** | Multiple tables with timestamp alignment. | Single/multiple table query results. |
| **Storage** | No physical storage; dynamic generation. | No storage; query logic only. |
| **Timestamp Handling**| Aligns timestamps across tables. | Follows query logic. |
| **Update Mechanism** | Real-time reflection of source changes. | Depends on query execution. |
| **Special Features** | Supports NULL filling and interpolation (prev/next/linear). | No built-in interpolation. |
| **Use Case** | Time series alignment, cross-table analysis. | Simplify complex queries, access control. |
| **Performance** | Potentially higher complexity. | Similar to underlying queries. |
Mutual conversion between virtual tables and views is not supported. For example, you cannot create a view based on a virtual table or create a virtual table from a view.
## Permissions
Virtual table permissions are categorized into READ and WRITE. Query operations require READ permission, while operations to delete or modify the virtual table itself require WRITE permission.
### Syntax
#### Grant
```sql
GRANT privileges ON [db_name.]vtable_name TO user_name
privileges: { ALL | READ | WRITE }
```
#### Revoke
```sql
REVOKE privileges ON [db_name.]vtable_name FROM user_name
privileges: { ALL | READ | WRITE }
```
### Permission Rules
1. The creator of a virtual table and the root user have all permissions by default.
2. Users can grant or revoke read/write permissions for specific virtual tables (including virtual supertables and virtual regular tables) via `dbname.vtbname`. Direct permission operations on virtual subtables are not supported.
3. Virtual subtables and virtual supertables do not support tag-based authorization (table-level authorization). Virtual subtables inherit permissions from their virtual supertables.
4. Granting and revoking permissions for other users must be performed through `GRANT` and `REVOKE` statements, and only the root user can execute these operations.
5. The detailed permission control rules are summarized below:
| No. | Operation | Permission Requirements |
|-----|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | CREATE VTABLE | The user has **WRITE** permission on the database to which the virtual table belongs, and <br />the user has **READ** permission on the source tables corresponding to the virtual table's data sources. |
| 2 | DROP/ALTER VTABLE | The user has **WRITE** permission on the virtual table. If specifying a column's data source, the user must also have **READ** permission on the source table corresponding to that column. |
| 3 | SHOW VTABLES | None |
| 4 | SHOW CREATE VTABLE | None |
| 5 | DESCRIBE VTABLE | None |
| 6 | Query System Tables | None |
| 7 | SELECT FROM VTABLE | The user has **READ** permission on the virtual table. |
| 8 | GRANT/REVOKE | Only the **root user** has permission. |
## Use Cases
| SQL Query | SQL Write | STMT Query | STMT Write | Subscribe | Stream Compute |
|----------|-----------|------------|------------|-----------|----------------|
| Supported | Not Supported | Not Supported | Not Supported | Not Supported | Supported |

0
docs/en/14-reference/03-taos-sql/05-insert.md → docs/en/14-reference/03-taos-sql/06-insert.md
View File

7
docs/en/14-reference/03-taos-sql/06-select.md → docs/en/14-reference/03-taos-sql/07-select.md
View File

@ -55,14 +55,13 @@ join_clause:
window_clause: {
SESSION(ts_col, tol_val)
| STATE_WINDOW(col)
| STATE_WINDOW(col) [TRUE_FOR(true_for_duration)]
| INTERVAL(interval_val [, interval_offset]) [SLIDING (sliding_val)] [WATERMARK(watermark_val)] [FILL(fill_mod_and_val)]
| EVENT_WINDOW START WITH start_trigger_condition END WITH end_trigger_condition
| EVENT_WINDOW START WITH start_trigger_condition END WITH end_trigger_condition [TRUE_FOR(true_for_duration)]
| COUNT_WINDOW(count_val[, sliding_val])
interp_clause:
RANGE(ts_val [, ts_val]) EVERY(every_val) FILL(fill_mod_and_val)
| RANGE(ts_val, surrounding_time_val) FILL(fill_mod_and_val)
RANGE(ts_val [, ts_val] [, surrounding_time_val]) EVERY(every_val) FILL(fill_mod_and_val)
partition_by_clause:
PARTITION BY partition_by_expr [, partition_by_expr] ...

0
docs/en/14-reference/03-taos-sql/07-tag-index.md → docs/en/14-reference/03-taos-sql/08-tag-index.md
View File

0
docs/en/14-reference/03-taos-sql/08-delete-data.md → docs/en/14-reference/03-taos-sql/09-delete-data.md
View File

67
docs/en/14-reference/03-taos-sql/10-function.md
View File

@ -124,7 +124,39 @@ FLOOR(expr)
```
**Function Description**: Gets the floor of the specified field.
Other usage notes see CEIL function description.
Other usage notes see [CEIL](#ceil) function description.
#### GREATEST
```sql
GREATEST(expr1, expr2[, expr]...)
```
**Function Description**: Get the maximum value of all input parameters. The minimum number of parameters for this function is 2.
**Version**：ver-3.3.6.0
**Return Type**：Refer to the comparison rules. The comparison type is the final return type.
**Applicable Data Types**:
- Numeric types: timestamp, bool, integer and floating point types
- Strings types: nchar and varchar types.
**Comparison rules**: The following rules describe the conversion method of the comparison operation:
- If any parameter is NULL, the comparison result is NULL.
- If all parameters in the comparison operation are string types, compare them as string types
- If all parameters are numeric types, compare them as numeric types.
- If there are both string types and numeric types in the parameters, according to the `compareAsStrInGreatest` configuration item, they are uniformly compared as strings or numeric values. By default, they are compared as strings.
- In all cases, when different types are compared, the comparison type will choose the type with a larger range for comparison. For example, when comparing integer types, if there is a BIGINT type, BIGINT will definitely be selected as the comparison type.
**Related configuration items**: Client configuration, compareAsStrInGreatest is 1, which means that both string types and numeric types are converted to string comparisons, and 0 means that they are converted to numeric types. The default is 1.
#### LEAST
```sql
LEAST(expr1, expr2[, expr]...)
```
**Function Description**：Get the minimum value of all input parameters. The rest of the description is the same as the [GREATEST](#greatest) function.
#### LOG
@ -1154,6 +1186,7 @@ CAST(expr AS type_name)
1) Invalid character situations when converting string types to numeric types, e.g., "a" might convert to 0, but will not throw an error.
2) When converting to numeric types, if the value exceeds the range that `type_name` can represent, it will overflow, but will not throw an error.
3) When converting to string types, if the converted length exceeds the length specified in `type_name`, it will be truncated, but will not throw an error.
- The DECIMAL type does not support conversion to or from JSON, VARBINARY, or GEOMETRY types.
#### TO_ISO8601
@ -1659,12 +1692,14 @@ AVG(expr)
**Function Description**: Calculates the average value of the specified field.
**Return Data Type**: DOUBLE.
**Return Data Type**: DOUBLE, DECIMAL.
**Applicable Data Types**: Numeric types.
**Applicable to**: Tables and supertables.
**Description**: When the input type is DECIMAL, the output type is also DECIMAL. The precision and scale of the output conform to the rules described in the data type section. The result type is obtained by dividing the SUM type by UINT64. If the SUM result causes a DECIMAL type overflow, a DECIMAL OVERFLOW error is reported.
### COUNT
```sql
@ -1815,12 +1850,14 @@ SUM(expr)
**Function Description**: Calculates the sum of a column in a table/supertable.
**Return Data Type**: DOUBLE, BIGINT.
**Return Data Type**: DOUBLE, BIGINT,DECIMAL.
**Applicable Data Types**: Numeric types.
**Applicable to**: Tables and supertables.
**Description**: When the input type is DECIMAL, the output type is DECIMAL(38, scale), where precision is the maximum value currently supported, and scale is the scale of the input type. If the SUM result overflows, a DECIMAL OVERFLOW error is reported.
### HYPERLOGLOG
```sql
@ -1932,6 +1969,7 @@ FIRST(expr)
- If all values in a column in the result set are NULL, the return for that column is also NULL;
- If all columns in the result set are NULL, no results are returned.
- For tables with composite primary keys, if there are multiple entries with the smallest timestamp, only the data with the smallest composite primary key is returned.
### LAST
```sql
@ -2088,6 +2126,28 @@ UNIQUE(expr)
**Applicable to**: Tables and supertables.
### COLS​
```sql​
COLS​(func(expr), output_expr1, [, output_expr2] ... )​
```
**Function Description**: On the data row where the execution result of function func(expr) is located, execute the expression output_expr1, [, output_expr2], return its result, and the result of func (expr) is not output.​
**Return Data Type**: Returns multiple columns of data, and the data type of each column is the type of the result returned by the corresponding expression.​
**Applicable Data Types**: All type fields.​
**Applicable to**: Tables and Super Tables.​
**Usage Instructions**:
- Func function type: must be a single-line selection function (output result is a single-line selection function, for example, last is a single-line selection function, but top is a multi-line selection function).​
- Mainly used to obtain the associated columns of multiple selection function results in a single SQL query. For example: select cols(max(c0), ts), cols(max(c1), ts) from ... can be used to get the different ts values of the maximum values of columns c0 and c1.
- The result of the parameter func is not returned. If you need to output the result of func, you can add additional output columns, such as: select first(ts), cols(first(ts), c1) from ..
- When there is only one column in the output, you can set an alias for the function. For example, you can do it like this: "select cols(first (ts), c1) as c11 from ...".
- Output one or more columns, and you can set an alias for each output column of the function. For example, you can do it like this: "select (first (ts), c1 as c11, c2 as c22) from ...".
## Time-Series Specific Functions
Time-Series specific functions are tailor-made by TDengine to meet the query scenarios of time-series data. In general databases, implementing similar functionalities usually requires complex query syntax and is inefficient. TDengine has built these functionalities into functions, greatly reducing the user's cost of use.
@ -2199,6 +2259,7 @@ ignore_null_values: {
- INTERP is used to obtain the record value of a specified column at the specified time slice. It has a dedicated syntax (interp_clause) when used. For syntax introduction, see [reference link](../query-data/#interp).
- When there is no row data that meets the conditions at the specified time slice, the INTERP function will interpolate according to the settings of the [FILL](../time-series-extensions/#fill-clause) parameter.
- When INTERP is applied to a supertable, it will sort all the subtable data under that supertable by primary key column and perform interpolation calculations, and can also be used with PARTITION BY tbname to force the results to a single timeline.
- When using INTERP with FILL PREV/NEXT/NEAR modes, its behavior differs from window queries. If data exists at the slice, no FILL operation will be performed, even if the current value is NULL.
- INTERP can be used with the pseudocolumn _irowts to return the timestamp corresponding to the interpolation point (supported from version 3.0.2.0).
- INTERP can be used with the pseudocolumn _isfilled to display whether the return result is from the original record or generated by the interpolation algorithm (supported from version 3.0.3.0).
- INTERP can only use the pseudocolumn `_irowts_origin` when using FILL PREV/NEXT/NEAR modes. `_irowts_origin` is supported from version 3.3.4.9.

20
docs/en/14-reference/03-taos-sql/12-distinguished.md
View File

@ -53,9 +53,9 @@ The syntax for the window clause is as follows:
```sql
window_clause: {
SESSION(ts_col, tol_val)
| STATE_WINDOW(col)
| STATE_WINDOW(col) [TRUE_FOR(true_for_duration)]
| INTERVAL(interval_val [, interval_offset]) [SLIDING (sliding_val)] [FILL(fill_mod_and_val)]
| EVENT_WINDOW START WITH start_trigger_condition END WITH end_trigger_condition
| EVENT_WINDOW START WITH start_trigger_condition END WITH end_trigger_condition [TRUE_FOR(true_for_duration)]
| COUNT_WINDOW(count_val[, sliding_val])
}
```
@ -84,10 +84,10 @@ The FILL statement specifies the filling mode when data is missing in a window i
1. No filling: NONE (default filling mode).
2. VALUE filling: Fixed value filling, where the fill value must be specified. For example: FILL(VALUE, 1.23). Note that the final fill value is determined by the type of the corresponding column, such as FILL(VALUE, 1.23), if the corresponding column is of INT type, then the fill value is 1. If multiple columns in the query list need FILL, then each FILL column must specify a VALUE, such as `SELECT _wstart, min(c1), max(c1) FROM ... FILL(VALUE, 0, 0)`. Note, only ordinary columns in the SELECT expression need to specify FILL VALUE, such as `_wstart`, `_wstart+1a`, `now`, `1+1` and the partition key (like tbname) used with partition by do not need to specify VALUE, like `timediff(last(ts), _wstart)` needs to specify VALUE.
3. PREV filling: Fill data using the previous non-NULL value. For example: FILL(PREV).
3. PREV filling: Fill data using the previous value. For example: FILL(PREV).
4. NULL filling: Fill data with NULL. For example: FILL(NULL).
5. LINEAR filling: Perform linear interpolation filling based on the nearest non-NULL values before and after. For example: FILL(LINEAR).
6. NEXT filling: Fill data using the next non-NULL value. For example: FILL(NEXT).
6. NEXT filling: Fill data using the next value. For example: FILL(NEXT).
Among these filling modes, except for the NONE mode which does not fill by default, other modes will be ignored if there is no data in the entire query time range, resulting in no fill data and an empty query result. This behavior is reasonable under some modes (PREV, NEXT, LINEAR) because no data means no fill value can be generated. For other modes (NULL, VALUE), theoretically, fill values can be generated, and whether to output fill values depends on the application's needs. To meet the needs of applications that require forced filling of data or NULL, without breaking the compatibility of existing filling modes, two new filling modes have been added starting from version 3.0.3.0:
@ -177,6 +177,12 @@ TDengine also supports using CASE expressions in state quantities, which can exp
SELECT tbname, _wstart, CASE WHEN voltage >= 205 and voltage <= 235 THEN 1 ELSE 0 END status FROM meters PARTITION BY tbname STATE_WINDOW(CASE WHEN voltage >= 205 and voltage <= 235 THEN 1 ELSE 0 END);
```
The state window supports using the TRUE_FOR parameter to set its minimum duration. If the window's duration is less than the specified value, it will be discarded automatically and no result will be returned. For example, setting the minimum duration to 3 seconds:
```
SELECT COUNT(*), FIRST(ts), status FROM temp_tb_1 STATE_WINDOW(status) TRUE_FOR (3s);
```
### Session Window
The session window is determined based on the timestamp primary key values of the records. As shown in the diagram below, if the continuous interval of the timestamps is set to be less than or equal to 12 seconds, the following 6 records form 2 session windows, which are: [2019-04-28 14:22:10, 2019-04-28 14:22:30] and [2019-04-28 14:23:10, 2019-04-28 14:23:30]. This is because the interval between 2019-04-28 14:22:30 and 2019-04-28 14:23:10 is 40 seconds, exceeding the continuous interval (12 seconds).
@ -212,6 +218,12 @@ select _wstart, _wend, count(*) from t event_window start with c1 > 0 end with c
<Image img={imgStep04} alt=""/>
</figure>
The event window supports using the TRUE_FOR parameter to set its minimum duration. If the window's duration is less than the specified value, it will be discarded automatically and no result will be returned. For example, setting the minimum duration to 3 seconds:
```
select _wstart, _wend, count(*) from t event_window start with c1 > 0 end with c2 < 10 true_for (3s);
```
### Count Window
Count windows divide data into windows based on a fixed number of data rows. By default, data is sorted by timestamp, then divided into multiple windows based on the value of count_val, and aggregate calculations are performed. count_val represents the maximum number of data rows in each count window; if the total number of data rows is not divisible by count_val, the last window will have fewer rows than count_val. sliding_val is a constant that represents the number of rows the window slides, similar to the SLIDING in interval.

8
docs/en/14-reference/03-taos-sql/13-tmq.md
View File

@ -58,11 +58,11 @@ Note: Subscriptions to supertables and databases are advanced subscription modes
## Delete topic
If you no longer need to subscribe to data, you can delete the topic, but note: only TOPICS that are not currently being subscribed to can be deleted.
If you no longer need to subscribe to the data, you can delete the topic. If the current topic is subscribed to by a consumer, it can be forcibly deleted using the FORCE syntax. After the forced deletion, the subscribed consumer will consume data with errors (FORCE syntax supported from version 3.3.6.0)
```sql
/* Delete topic */
DROP TOPIC [IF EXISTS] topic_name;
DROP TOPIC [IF EXISTS] [FORCE] topic_name;
```
At this point, if there are consumers on this subscription topic, they will receive an error.
@ -81,8 +81,10 @@ Consumer groups can only be created through the TDengine client driver or APIs p
## Delete consumer group
When creating a consumer, a consumer group is assigned to the consumer. Consumers cannot be explicitly deleted, but the consumer group can be deleted. If there are consumers in the current consumer group who are consuming, the FORCE syntax can be used to force deletion. After forced deletion, subscribed consumers will consume data with errors (FORCE syntax supported from version 3.3.6.0).
```sql
DROP CONSUMER GROUP [IF EXISTS] cgroup_name ON topic_name;
DROP CONSUMER GROUP [IF EXISTS] [FORCE] cgroup_name ON topic_name;
```
Deletes the consumer group `cgroup_name` on the topic `topic_name`.

254
docs/en/14-reference/03-taos-sql/14-stream.md
View File

@ -9,13 +9,13 @@ import imgStream from './assets/stream-processing-01.png';
## Creating Stream Computing
```sql
CREATE STREAM [IF NOT EXISTS] stream_name [stream_options] INTO stb_name[(field1_name, field2_name [PRIMARY KEY], ...)] [TAGS (create_definition [, create_definition] ...)] SUBTABLE(expression) AS subquery
CREATE STREAM [IF NOT EXISTS] stream_name [stream_options] INTO stb_name[(field1_name, field2_name [PRIMARY KEY], ...)] [TAGS (create_definition [, create_definition] ...)] SUBTABLE(expression) AS subquery [notification_definition]
stream_options: {
TRIGGER [AT_ONCE | WINDOW_CLOSE | MAX_DELAY time | FORCE_WINDOW_CLOSE]
TRIGGER [AT_ONCE | WINDOW_CLOSE | MAX_DELAY time | FORCE_WINDOW_CLOSE | CONTINUOUS_WINDOW_CLOSE [recalculate rec_time_val] ]
WATERMARK time
IGNORE EXPIRED [0|1]
DELETE_MARK time
FILL_HISTORY [0|1]
FILL_HISTORY [0|1] [ASYNC]
IGNORE UPDATE [0|1]
}
@ -85,6 +85,8 @@ CREATE STREAM streams1 IGNORE EXPIRED 1 WATERMARK 100s INTO streamt1 AS
SELECT _wstart, count(*), avg(voltage) from meters PARTITION BY tbname COUNT_WINDOW(10);
```
notification_definition clause specifies the addresses to which notifications should be sent when designated events occur during window computations, such as window opening or closing. For more details, see [Stream Computing Event Notifications](#stream-computing-event-notifications).
## Stream Computation Partitioning
You can use `PARTITION BY TBNAME`, tags, regular columns, or expressions to partition a stream for multi-partition computation. Each partition's timeline and window are independent, aggregating separately, and writing into different subtables of the target table.
@ -125,6 +127,13 @@ create stream if not exists s1 fill_history 1 into st1 as select count(*) from
If the stream task is completely outdated and you no longer want it to monitor or process data, you can manually delete it. The computed data will still be retained.
Tips:
- When enabling fill_history, creating a stream requires finding the boundary point of historical data. If there is a lot of historical data, it may cause the task of creating a stream to take a long time. In this case, you can use fill_history 1 async (supported since version 3.3.6.0) , then the task of creating a stream can be processed in the background. The statement of creating a stream can be returned immediately without blocking subsequent operations. async only takes effect when fill_history 1 is used, and creating a stream with fill_history 0 is very fast and does not require asynchronous processing.
- Show streams can be used to view the progress of background stream creation (ready status indicates success, init status indicates stream creation in progress, failed status indicates that the stream creation has failed, and the message column can be used to view the reason for the failure. In the case of failed stream creation, the stream can be deleted and rebuilt).
- Besides, do not create multiple streams asynchronously at the same time, as transaction conflicts may cause subsequent streams to fail.
## Deleting Stream Computing
```sql
@ -155,6 +164,7 @@ For non-window computations, the trigger of stream computing is real-time; for w
2. WINDOW_CLOSE: Triggered when the window closes (window closure is determined by event time, can be used in conjunction with watermark)
3. MAX_DELAY time: Trigger computation if the window closes. If the window does not close, and the time since it has not closed exceeds the time specified by max delay, then trigger computation.
4. FORCE_WINDOW_CLOSE: Based on the current time of the operating system, only compute and push the results of the currently closed window. The window is only computed once at the moment of closure and will not be recalculated subsequently. This mode currently only supports INTERVAL windows (does not support sliding); FILL_HISTORY must be 0, IGNORE EXPIRED must be 1, IGNORE UPDATE must be 1; FILL only supports PREV, NULL, NONE, VALUE.
5. CONTINUOUS_WINDOW_CLOSE: Results are output when the window is closed. Modifying or deleting data does not immediately trigger a recalculation. Instead, periodic recalculations are performed every rec_time_val duration. If rec_time_val is not specified, the recalculation period is 60 minutes. If the recalculation time exceeds rec_time_val, the next recalculation will be automatically initiated after the current one is completed. Currently, this mode only supports INTERVAL windows. If the FILL clause is used, relevant information of the adapter needs to be configured, including adapterFqdn, adapterPort, and adapterToken. The adapterToken is a string obtained by Base64-encoding `{username}:{password}`. For example, after encoding `root:taosdata`, the result is `cm9vdDp0YW9zZGF0YQ==`.
Since the closure of the window is determined by event time, if the event stream is interrupted or continuously delayed, the event time cannot be updated, which may result in not obtaining the latest computation results.
@ -305,3 +315,241 @@ CREATE SNODE ON DNODE [id]
The id is the serial number of the dnode in the cluster. Please be mindful of the selected dnode, as the intermediate state of stream computing will automatically be backed up on it.
Starting from version 3.3.4.0, in a multi-replica environment, creating a stream will perform an **existence check** of snode, requiring the snode to be created first. If the snode does not exist, the stream cannot be created.
## Stream Computing Event Notifications
### User Guide
Stream computing supports sending event notifications to external systems when windows open or close. Users can specify the events to be notified and the target addresses for receiving notification messages using the notification_definition clause.
```sql
notification_definition:
NOTIFY (url [, url] ...) ON (event_type [, event_type] ...) [notification_options]
event_type:
'WINDOW_OPEN'
| 'WINDOW_CLOSE'
notification_options: {
NOTIFY_HISTORY [0|1]
ON_FAILURE [DROP|PAUSE]
}
```
The rules for the syntax above are as follows:
1. `url`: Specifies the target address for the notification. It must include the protocol, IP or domain name, port, and may include a path and parameters. Currently, only the websocket protocol is supported. For example: 'ws://localhost:8080', 'ws://localhost:8080/notify', 'wss://localhost:8080/notify?key=foo'.
2. `event_type`: Defines the events that trigger notifications. Supported event types include:
1. 'WINDOW_OPEN': Window open event; triggered when any type of window opens.
2. 'WINDOW_CLOSE': Window close event; triggered when any type of window closes.
3. `NOTIFY_HISTORY`: Controls whether to trigger notifications during the computation of historical data. The default value is 0, which means no notifications are sent.
4. `ON_FAILURE`: Determines whether to allow dropping some events if sending notifications fails (e.g., in poor network conditions). The default value is `PAUSE`:
1. PAUSE means that the stream computing task is paused if sending a notification fails. taosd will retry until the notification is successfully delivered and the task resumes.
2. DROP means that if sending a notification fails, the event information is discarded, and the stream computing task continues running unaffected.
For example, the following creates a stream that computes the per-minute average current from electric meters and sends notifications to two target addresses when the window opens and closes. It does not send notifications for historical data and does not allow dropping notifications on failure:
```sql
CREATE STREAM avg_current_stream FILL_HISTORY 1
AS SELECT _wstart, _wend, AVG(current) FROM meters
INTERVAL (1m)
NOTIFY ('ws://localhost:8080/notify', 'wss://192.168.1.1:8080/notify?key=foo')
ON ('WINDOW_OPEN', 'WINDOW_CLOSE');
NOTIFY_HISTORY 0
ON_FAILURE PAUSE;
```
When the specified events are triggered, taosd will send a POST request to the given URL(s) with a JSON message body. A single request may contain events from several streams, and the event types may differ.
The details of the event information depend on the type of window:
1. Time Window: At the opening, the start time is sent; at the closing, the start time, end time, and computation result are sent.
2. State Window: At the opening, the start time, previous window's state, and current window's state are sent; at closing, the start time, end time, computation result, current window state, and next window state are sent.
3. Session Window: At the opening, the start time is sent; at the closing, the start time, end time, and computation result are sent.
4. Event Window: At the opening, the start time along with the data values and corresponding condition index that triggered the window opening are sent; at the closing, the start time, end time, computation result, and the triggering data value and condition index for window closure are sent.
5. Count Window: At the opening, the start time is sent; at the closing, the start time, end time, and computation result are sent.
An example structure for the notification message is shown below:
```json
{
"messageId": "unique-message-id-12345",
"timestamp": 1733284887203,
"streams": [
{
"streamName": "avg_current_stream",
"events": [
{
"tableName": "t_a667a16127d3b5a18988e32f3e76cd30",
"eventType": "WINDOW_OPEN",
"eventTime": 1733284887097,
"windowId": "window-id-67890",
"windowType": "Time",
"windowStart": 1733284800000
},
{
"tableName": "t_a667a16127d3b5a18988e32f3e76cd30",
"eventType": "WINDOW_CLOSE",
"eventTime": 1733284887197,
"windowId": "window-id-67890",
"windowType": "Time",
"windowStart": 1733284800000,
"windowEnd": 1733284860000,
"result": {
"_wstart": 1733284800000,
"avg(current)": 1.3
}
}
]
},
{
"streamName": "max_voltage_stream",
"events": [
{
"tableName": "t_96f62b752f36e9b16dc969fe45363748",
"eventType": "WINDOW_OPEN",
"eventTime": 1733284887231,
"windowId": "window-id-13579",
"windowType": "Event",
"windowStart": 1733284800000,
"triggerCondition": {
"conditionIndex": 0,
"fieldValue": {
"c1": 10,
"c2": 15
}
},
},
{
"tableName": "t_96f62b752f36e9b16dc969fe45363748",
"eventType": "WINDOW_CLOSE",
"eventTime": 1733284887231,
"windowId": "window-id-13579",
"windowType": "Event",
"windowStart": 1733284800000,
"windowEnd": 1733284810000,
"triggerCondition": {
"conditionIndex": 1,
"fieldValue": {
"c1": 20
"c2": 3
}
},
"result": {
"_wstart": 1733284800000,
"max(voltage)": 220
}
}
]
}
]
}
```
The following sections explain the fields in the notification message.
### Root-Level Field Descriptions
1. "messageId": A string that uniquely identifies the notification message. It ensures that the entire message can be tracked and de-duplicated.
2. "timestamp": A long integer timestamp representing the time when the notification message was generated, accurate to the millisecond (i.e., the number of milliseconds since '00:00, Jan 1 1970 UTC').
3. "streams": An array containing the event information for multiple stream tasks. (See the following sections for details.)
### "stream" Object Field Descriptions
1. "streamName": A string representing the name of the stream task, used to identify which stream the events belong to.
2. "events": An array containing the list of event objects for the stream task. Each event object includes detailed information. (See the next sections for details.)
### "event" Object Field Descriptions
#### Common Fields
These fields are common to all event objects.
1. "tableName": A string indicating the name of the target subtable.
2. "eventType": A string representing the event type ("WINDOW_OPEN", "WINDOW_CLOSE", or "WINDOW_INVALIDATION").
3. "eventTime": A long integer timestamp that indicates when the event was generated, accurate to the millisecond (i.e., the number of milliseconds since '00:00, Jan 1 1970 UTC').
4. "windowId": A string representing the unique identifier for the window. This ID ensures that the open and close events for the same window can be correlated. In the case that taosd restarts due to a fault, some events may be sent repeatedly, but the windowId remains constant for the same window.
5. "windowType": A string that indicates the window type ("Time", "State", "Session", "Event", or "Count").
#### Fields for Time Windows
These fields are present only when "windowType" is "Time".
1. When "eventType" is "WINDOW_OPEN", the following field is included:
1. "windowStart": A long integer timestamp representing the start time of the window, matching the time precision of the result table.
2. When "eventType" is "WINDOW_CLOSE", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "windowEnd": A long integer timestamp representing the end time of the window.
1. "result": An object containing key-value pairs of the computed result columns and their corresponding values.
#### Fields for State Windows
These fields are present only when "windowType" is "State".
1. When "eventType" is "WINDOW_OPEN", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "prevState": A value of the same type as the state column, representing the state of the previous window. If there is no previous window (i.e., this is the first window), it will be NULL.
1. "curState": A value of the same type as the state column, representing the current window's state.
2. When "eventType" is "WINDOW_CLOSE", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "windowEnd": A long integer timestamp representing the end time of the window.
1. "curState": The current window's state.
1. "nextState": The state for the next window.
1. "result": An object containing key-value pairs of the computed result columns and their corresponding values.
#### Fields for Session Windows
These fields are present only when "windowType" is "Session".
1. When "eventType" is "WINDOW_OPEN", the following field is included:
1. "windowStart": A long integer timestamp representing the start time of the window.
2. When "eventType" is "WINDOW_CLOSE", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "windowEnd": A long integer timestamp representing the end time of the window.
1. "result": An object containing key-value pairs of the computed result columns and their corresponding values.
#### Fields for Event Windows
These fields are present only when "windowType" is "Event".
1. When "eventType" is "WINDOW_OPEN", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "triggerCondition": An object that provides information about the condition that triggered the window to open. It includes:
1. "conditionIndex": An integer representing the index of the condition that triggered the window, starting from 0.
1. "fieldValue": An object containing key-value pairs of the column names related to the condition and their respective values.
2. When "eventType" is "WINDOW_CLOSE", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "windowEnd": A long integer timestamp representing the end time of the window.
1. "triggerCondition": An object that provides information about the condition that triggered the window to close. It includes:
1. "conditionIndex": An integer representing the index of the condition that triggered the closure, starting from 0.
1. "fieldValue": An object containing key-value pairs of the related column names and their respective values.
1. "result": An object containing key-value pairs of the computed result columns and their corresponding values.
#### Fields for Count Windows
These fields are present only when "windowType" is "Count".
1. When "eventType" is "WINDOW_OPEN", the following field is included:
1. "windowStart": A long integer timestamp representing the start time of the window.
2. When "eventType" is "WINDOW_CLOSE", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "windowEnd": A long integer timestamp representing the end time of the window.
1. "result": An object containing key-value pairs of the computed result columns and their corresponding values.
#### Fields for Window Invalidation
Due to scenarios such as data disorder, updates, or deletions during stream computing, windows that have already been generated might be removed or their results need to be recalculated. In such cases, a notification with the eventType "WINDOW_INVALIDATION" is sent to inform which windows have been invalidated.
For events with "eventType" as "WINDOW_INVALIDATION", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "windowEnd": A long integer timestamp representing the end time of the window.
## Support for Virtual Tables in Stream Computing
Starting with v3.3.6.0, stream computing can use virtual tables—including virtual regular tables, virtual sub-tables, and virtual super tables—as data sources for computation. The syntax is identical to that for non‑virtual tables.
However, because the behavior of virtual tables differs from that of non‑virtual tables, the following restrictions apply when using stream computing:
1. The schema of virtual regular tables/virtual sub-tables involved in stream computing cannot be modified.
1. During stream computing, if the data source corresponding to a column in a virtual table is changed, the stream computation will not pick up the change; it will still read from the old data source.
1. During stream computing, if the original table corresponding to a column in a virtual table is deleted and later a new table with the same name and a column with the same name is created, the stream computation will not read data from the new table.
1. The watermark for stream computing must be 0; otherwise, an error will occur during creation.
1. If the data source for stream computing is a virtual super table, sub-tables that are added after the stream computing task starts will not participate in the computation.
1. The timestamps of different underlying tables in a virtual table may not be completely consistent; merging the data might produce null values, and interpolation is currently not supported.
1. Out-of-order data, updates, or deletions are not handled. In other words, when creating a stream, you cannot specify `ignore update 0` or `ignore expired 0`; otherwise, an error will be reported.
1. Historical data computation is not supported. That is, when creating a stream, you cannot specify `fill_history 1`; otherwise, an error will be reported.
1. The trigger modes MAX_DELAY, CONTINUOUS_WINDOW_CLOSE and FORCE_WINDOW_CLOSE are not supported.
1. The COUNT_WINDOW type is not supported.

5
docs/en/14-reference/03-taos-sql/16-operators.md
View File

@ -43,7 +43,8 @@ TDengine supports `UNION ALL` and `UNION` operators. UNION ALL combines the resu
| 9 | LIKE | BINARY, NCHAR, and VARCHAR | Matches the specified pattern string with wildcard |
| 10 | NOT LIKE | BINARY, NCHAR, and VARCHAR | Does not match the specified pattern string with wildcard |
| 11 | MATCH, NMATCH | BINARY, NCHAR, and VARCHAR | Regular expression match |
| 12 | CONTAINS | JSON | Whether a key exists in JSON |
| 12 | REGEXP, NOT REGEXP | BINARY, NCHAR, and VARCHAR | Regular expression match |
| 13 | CONTAINS | JSON | Whether a key exists in JSON |
LIKE conditions use wildcard strings for matching checks, with the following rules:
@ -51,7 +52,7 @@ LIKE conditions use wildcard strings for matching checks, with the following rul
- If you want to match an underscore character that is originally in the string, you can write it as \_ in the wildcard string, i.e., add a backslash to escape it.
- The wildcard string cannot exceed 100 bytes in length. It is not recommended to use too long wildcard strings, as it may severely affect the performance of the LIKE operation.
MATCH and NMATCH conditions use regular expressions for matching, with the following rules:
MATCH/REGEXP and NMATCH/NOT REGEXP conditions use regular expressions for matching, with the following rules:
- Supports regular expressions that comply with the POSIX standard, see Regular Expressions for specific standards.
- When MATCH matches a regular expression, it returns TRUE. When NMATCH does not match a regular expression, it returns TRUE.

2
docs/en/14-reference/03-taos-sql/19-limit.md
View File

@ -37,6 +37,6 @@ Removed `` ‘“`\ `` (single and double quotes, apostrophe, backslash, space)
- Number of databases, supertables, and tables are not limited by the system, only by system resources
- Number of replicas for a database can only be set to 1 or 3
- Maximum length of username is 23 bytes
- Maximum length of user password is 31 bytes
- Maximum length of user password is 255 bytes
- Total number of data rows depends on available resources
- Maximum number of virtual nodes for a single database is 1024

37
docs/en/14-reference/03-taos-sql/20-keywords.md
View File

@ -23,11 +23,11 @@ The list of keywords is as follows:
| ALIVE | |
| ALL | |
| ALTER | |
| ANALYZE | Version 3.3.4.3 and later |
| ANALYZE | 3.3.4.3+ |
| AND | |
| ANODE | Version 3.3.4.3 and later |
| ANODES | Version 3.3.4.3 and later |
| ANOMALY_WINDOW | Version 3.3.4.3 and later |
| ANODE | 3.3.4.3+ |
| ANODES | 3.3.4.3+ |
| ANOMALY_WINDOW | 3.3.4.3+ |
| ANTI | |
| APPS | |
| ARBGROUPS | |
@ -35,8 +35,11 @@ The list of keywords is as follows:
| AS | |
| ASC | |
| ASOF | |
| ASYNC | 3.3.6.0+ |
| AT_ONCE | |
| ATTACH | |
| AUTO | 3.3.5.0+ |
| ASSIGN | 3.3.6.0+ |
### B
@ -78,12 +81,16 @@ The list of keywords is as follows:
| CLIENT_VERSION | |
| CLUSTER | |
| COLON | |
| COLS | 3.3.6.0+ |
| COLUMN | |
| COMMA | |
| COMMENT | |
| COMP | |
| COMPACT | |
| COMPACTS | |
| COMPACT_INTERVAL | 3.3.5.0+ |
| COMPACT_TIME_OFFSET | 3.3.5.0+ |
| COMPACT_TIME_RANGE | 3.3.5.0+ |
| CONCAT | |
| CONFLICT | |
| CONNECTION | |
@ -92,6 +99,7 @@ The list of keywords is as follows:
| CONSUMER | |
| CONSUMERS | |
| CONTAINS | |
| CONTINUOUS_WINDOW_CLOSE | 3.3.6.0+ |
| COPY | |
| COUNT | |
| COUNT_WINDOW | |
@ -106,7 +114,7 @@ The list of keywords is as follows:
| DATABASE | |
| DATABASES | |
| DBS | |
| DECIMAL | |
| DECIMAL | 3.3.6.0+ |
| DEFERRED | |
| DELETE | |
| DELETE_MARK | |
@ -114,6 +122,7 @@ The list of keywords is as follows:
| DESC | |
| DESCRIBE | |
| DETACH | |
| DISK_INFO | 3.3.5.0+ |
| DISTINCT | |
| DISTRIBUTED | |
| DIVIDE | |
@ -148,19 +157,19 @@ The list of keywords is as follows:
|Keyword|Description|
|----------------------|-|
| FAIL | |
| FHIGH | Version 3.3.4.3 and later |
| FHIGH | 3.3.4.3+ |
| FILE | |
| FILL | |
| FILL_HISTORY | |
| FIRST | |
| FLOAT | |
| FLOW | Version 3.3.4.3 and later |
| FLOW | 3.3.4.3+ |
| FLUSH | |
| FOR | |
| FORCE | |
| FORCE_WINDOW_CLOSE | Version 3.3.4.3 and later |
| FORCE_WINDOW_CLOSE | 3.3.4.3+ |
| FROM | |
| FROWTS | Version 3.3.4.3 and later |
| FROWTS | 3.3.4.3+ |
| FULL | |
| FUNCTION | |
| FUNCTIONS | |
@ -209,6 +218,7 @@ The list of keywords is as follows:
| INTO | |
| IPTOKEN | |
| IROWTS | |
| IROWTS_ORIGIN | 3.3.5.0+ |
| IS | |
| IS_IMPORT | |
| ISFILLED | |
@ -242,6 +252,7 @@ The list of keywords is as follows:
| LEADER | |
| LEADING | |
| LEFT | |
| LEVEL | 3.3.0.0 - 3.3.2.11 |
| LICENCES | |
| LIKE | |
| LIMIT | |
@ -263,6 +274,7 @@ The list of keywords is as follows:
| MEDIUMBLOB | |
| MERGE | |
| META | |
| META_ONLY | 3.3.6.0+ |
| MINROWS | |
| MINUS | |
| MNODE | |
@ -281,6 +293,8 @@ The list of keywords is as follows:
| NONE | |
| NORMAL | |
| NOT | |
| NOTIFY | 3.3.6.0+ |
| NOTIFY_HISTORY | 3.3.6.0+ |
| NOTNULL | |
| NOW | |
| NULL | |
@ -295,6 +309,7 @@ The list of keywords is as follows:
| OFFSET | |
| ON | |
| ONLY | |
| ON_FAILURE | 3.3.6.0+ |
| OR | |
| ORDER | |
| OUTER | |
@ -345,6 +360,7 @@ The list of keywords is as follows:
| RATIO | |
| READ | |
| RECURSIVE | |
| REGEXP | 3.3.6.0+ |
| REDISTRIBUTE | |
| REM | |
| REPLACE | |
@ -418,7 +434,7 @@ The list of keywords is as follows:
| TABLE_PREFIX | |
| TABLE_SUFFIX | |
| TABLES | |
| tag | |
| TAG | |
| TAGS | |
| TBNAME | |
| THEN | |
@ -435,6 +451,7 @@ The list of keywords is as follows:
| TRANSACTIONS | |
| TRIGGER | |
| TRIM | |
| TRUE_FOR | 3.3.6.0+ |
| TSDB_PAGESIZE | |
| TSERIES | |
| TSMA | |

12
docs/en/14-reference/03-taos-sql/24-show.md
View File

@ -127,10 +127,11 @@ Displays created indexes.
## SHOW LOCAL VARIABLES
```sql
SHOW LOCAL VARIABLES;
SHOW LOCAL VARIABLES [like pattern];
```
Displays the runtime values of configuration parameters for the current client.
You can use the like pattern to filter by name.
## SHOW MNODES
@ -304,9 +305,10 @@ Displays information about all topics in the current database.
```sql
SHOW TRANSACTIONS;
SHOW TRANSACTION [tranaction_id];
```
Displays information about transactions currently being executed in the system (these transactions are only for metadata level, not for regular tables).
Displays information about one of or all transaction(s) currently being executed in the system (these transactions are only for metadata level, not for regular tables).
## SHOW USERS
@ -319,11 +321,11 @@ Displays information about all users in the current system, including user-defin
## SHOW CLUSTER VARIABLES (before version 3.0.1.6 it was SHOW VARIABLES)
```sql
SHOW CLUSTER VARIABLES;
SHOW DNODE dnode_id VARIABLES;
SHOW CLUSTER VARIABLES [like pattern];
SHOW DNODE dnode_id VARIABLES [like pattern];
```
Displays the runtime values of configuration parameters that need to be the same across nodes in the current system, or you can specify a DNODE to view its configuration parameters.
Displays the runtime values of configuration parameters that need to be the same across nodes in the current system, or you can specify a DNODE to view its configuration parameters. And you can use the like pattern to filter by name.
## SHOW VGROUPS

13
docs/en/14-reference/03-taos-sql/31-join.md
View File

@ -29,6 +29,17 @@ SELECT a.* FROM meters a LEFT ASOF JOIN meters b ON timetruncate(a.ts, 1s) < tim
### Main Join Condition
As a time-series database, all join queries in TDengine revolve around the primary key timestamp column. Therefore, all join queries (except ASOF/Window Join) must include an equality condition on the primary key column, and the first primary key column equality condition that appears in the join conditions will be considered the main join condition. ASOF Join's main join condition can include non-equality conditions, while Window Join's main join condition is specified through `WINDOW_OFFSET`.
Starting from version 3.3.6.0, TDengine supports constant timestamps in subqueries (including constant functions with return timestamps such as today (), now (), etc., constant timestamps and their addition and subtraction operations) as equivalent primary key columns that can appear in the main join condition. For example:
```sql
SELECT * from d1001 a JOIN (SELECT today() as ts1, * from d1002 WHERE ts = '2025-03-19 10:00:00.000') b ON timetruncate(a.ts, 1d) = b.ts1;
```
The above example SQL will perform join operation between all records in table d1001 today and a certain time record in table d1002. It should be noticed that the constant time string appears in SQL will not be treated as a timestamp by default. For example, "2025-03-19 10:00:00.000" will only be treated as a string instead of a timestamp. Therefore, when it needs to be treated as a constant timestamp, you can specify the constant string as a timestamp type by using the type prefix timestamp. For example:
```sql
SELECT * from d1001 a JOIN (SELECT timestamp '2025-03-19 10:00:00.000' as ts1, * from d1002 WHERE ts = '2025-03-19 10:00:00.000') b ON timetruncate(a.ts, 1d) = b.ts1;
```
Apart from Window Join, TDengine supports the `timetruncate` function operation in the main join condition, such as `ON timetruncate(a.ts, 1s) = timetruncate(b.ts, 1s)`, but does not support other functions and scalar operations.
@ -38,7 +49,7 @@ The characteristic ASOF/Window Join of time-series databases supports grouping t
### Primary Key Timeline
As a time-series database, TDengine requires each table (subtable) to have a primary key timestamp column, which will serve as the primary key timeline for many time-related operations. The result of a subquery or the result of a Join operation also needs to clearly identify which column will be considered the primary key timeline for subsequent time-related operations. In subqueries, the first appearing ordered primary key column (or its operation) or a pseudocolumn equivalent to the primary key column (`_wstart`/`_wend`) will be considered the primary key timeline of the output table. The selection of the primary key timeline in Join output results follows these rules:
As a time-series database, TDengine requires each table (subtable) to have a primary key timestamp column, which will serve as the primary key timeline for many time-related operations. The result of a subquery or the result of a Join operation also needs to clearly identify which column will be considered the primary key timeline for subsequent time-related operations. In subqueries, the first appearing ordered primary key column (or its operation) or a pseudocolumn equivalent to the primary key column (`_wstart`/`_wend`) will be considered the primary key timeline of the output table. In addition, starting with version 3.3.6.0, TDengine also supports constant timestamp columns in subquery results as the primary key timeline for the output table. The selection of the primary key timeline in Join output results follows these rules:
- In the Left/Right Join series, the primary key column of the driving table (subquery) will be used as the primary key timeline for subsequent queries; additionally, within the Window Join window, since both tables are ordered, any table's primary key column can be used as the primary key timeline, with a preference for the primary key column of the same table.
- Inner Join can use the primary key column of any table as the primary key timeline, but when there are grouping conditions similar to tag column equality conditions related by `AND` with the main join condition, it will not produce a primary key timeline.

1
docs/en/14-reference/03-taos-sql/32-compress.md
View File

@ -36,6 +36,7 @@ In this document, it specifically refers to the internal levels of the second-le
| float/double | disabled/delta-d | delta-d | lz4/zlib/zstd/xz/tsz | lz4 | medium |
| binary/nchar | disabled | disabled | lz4/zlib/zstd/xz | zstd | medium |
| bool | disabled/bit-packing | bit-packing | lz4/zlib/zstd/xz | zstd | medium |
| decimal | disabled | disabled | lz4/zlib/zstd/xz | zstd | medium |
## SQL Syntax

BIN
docs/en/14-reference/03-taos-sql/assets/virtual-table-origin-table.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.8 KiB

BIN
docs/en/14-reference/03-taos-sql/assets/virtual-table-query-res-part.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.1 KiB

BIN
docs/en/14-reference/03-taos-sql/assets/virtual-table-query-res.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.9 KiB

23
docs/en/14-reference/05-connector/10-cpp.md
View File

@ -510,7 +510,6 @@ For the OpenTSDB text protocol, the parsing of timestamps follows its official p
- tmq: [Input] Points to a valid ws_tmq_t structure pointer, which represents a TMQ consumer object.
- timeout: [Input] Polling timeout in milliseconds, a negative number indicates a default timeout of 1 second.
- **Return Value**: Non-`NULL`: Success, returns a pointer to a WS_RES structure, which contains the received message. `NULL`: indicates no data, the error code can be obtained through ws_errno (NULL), please refer to the reference manual for specific error message. WS_RES results are consistent with taos_query results, and information in WS_RES can be obtained through various query interfaces, such as schema, etc.
- `int32_t ws_tmq_consumer_close(ws_tmq_t *tmq)`
- **Interface Description**: Used to close the ws_tmq_t structure. Must be used in conjunction with ws_tmq_consumer_new.
- tmq: [Input] Points to a valid ws_tmq_t structure pointer, which represents a TMQ consumer object.
@ -683,7 +682,7 @@ The basic API is used to establish database connections and provide a runtime en
- **Interface Description**: Cleans up the runtime environment, should be called before the application exits.
- `int taos_options(TSDB_OPTION option, const void * arg, ...)`
- **Interface Description**: Sets client options, currently supports locale (`TSDB_OPTION_LOCALE`), character set (`TSDB_OPTION_CHARSET`), timezone (`TSDB_OPTION_TIMEZONE`), and configuration file path (`TSDB_OPTION_CONFIGDIR`). Locale, character set, and timezone default to the current settings of the operating system.
- **Interface Description**: Sets client options, currently supports locale (`TSDB_OPTION_LOCALE`), character set (`TSDB_OPTION_CHARSET`), timezone (`TSDB_OPTION_TIMEZONE`), configuration file path (`TSDB_OPTION_CONFIGDIR`), and driver type (`TSDB_OPTION_DRIVER`). Locale, character set, and timezone default to the current settings of the operating system. The driver type can be either the native interface(`native`) or the WebSocket interface(`websocket`), with the default being `websocket`.
- **Parameter Description**:
- `option`: [Input] Setting item type.
- `arg`: [Input] Setting item value.
@ -831,6 +830,12 @@ This section introduces APIs that are all synchronous interfaces. After being ca
- res: [Input] Result set.
- **Return Value**: Non-`NULL`: successful, returns a pointer to a TAOS_FIELD structure, each element representing the metadata of a column. `NULL`: failure.
- `TAOS_FIELD_E *taos_fetch_fields_e(TAOS_RES *res)`
- **Interface Description**: Retrieves the attributes of each column in the query result set (column name, data type, column length). Used in conjunction with `taos_num_fields()`, it can be used to parse the data of a tuple (a row) returned by `taos_fetch_row()`. In addition to the basic information provided by TAOS_FIELD, TAOS_FIELD_E also includes `precision` and `scale` information for the data type.
- **Parameter Description**:
- res: [Input] Result set.
- **Return Value**: Non-`NULL`: Success, returns a pointer to a TAOS_FIELD_E structure, where each element represents the metadata of a column. `NULL`: Failure.
- `void taos_stop_query(TAOS_RES *res)`
- **Interface Description**: Stops the execution of the current query.
- **Parameter Description**:
@ -1122,10 +1127,14 @@ In addition to using SQL or parameter binding APIs to insert data, you can also
- conf: [Input] Pointer to a valid tmq_conf_t structure, representing a TMQ configuration object.
- key: [Input] Configuration item key name.
- value: [Input] Configuration item value.
- **Return Value**: Returns a tmq_conf_res_t enum value, indicating the result of the configuration setting.
- TMQ_CONF_OK: Successfully set the configuration item.
- TMQ_CONF_INVALID_KEY: Invalid key value.
- TMQ_CONF_UNKNOWN: Invalid key name.
- **Return Value**: Returns a tmq_conf_res_t enum value, indicating the result of the configuration setting. tmq_conf_res_t defined as follows:
```
typedef enum tmq_conf_res_t {
TMQ_CONF_UNKNOWN = -2, // invalid key
TMQ_CONF_INVALID = -1, // invalid value
TMQ_CONF_OK = 0, // success
} tmq_conf_res_t;
```
- `void tmq_conf_set_auto_commit_cb(tmq_conf_t *conf, tmq_commit_cb *cb, void *param)`
- **Interface Description**: Sets the auto-commit callback function in the TMQ configuration object.
@ -1196,7 +1205,7 @@ In addition to using SQL or parameter binding APIs to insert data, you can also
- tmq: [Input] Points to a valid tmq_t structure pointer, representing a TMQ consumer object.
- timeout: [Input] Polling timeout in milliseconds, a negative number indicates a default timeout of 1 second.
- **Return Value**: Non-`NULL`: Success, returns a pointer to a TAOS_RES structure containing the received messages. `NULL`: indicates no data, the error code can be obtained through taos_errno (NULL), please refer to the reference manual for specific error message. TAOS_RES results are consistent with taos_query results, and information in TAOS_RES can be obtained through various query interfaces, such as schema, etc.
- `int32_t tmq_consumer_close(tmq_t *tmq)`
- **Interface Description**: Used to close a tmq_t structure. Must be used in conjunction with tmq_consumer_new.
- tmq: [Input] Points to a valid tmq_t structure pointer, which represents a TMQ consumer object.

12
docs/en/14-reference/05-connector/14-java.md
View File

@ -121,6 +121,7 @@ Please refer to the specific error codes:
| 0x2378 | consumer create error | Data subscription creation failed, check the error information and taos log for troubleshooting. |
| 0x2379 | seek offset must not be a negative number | The seek interface parameter must not be negative, use the correct parameters. |
| 0x237a | vGroup not found in result set | VGroup not assigned to the current consumer, due to the Rebalance mechanism causing the Consumer and VGroup to be unbound. |
| 0x2390 | background thread write error in Efficient Writing | In the event of an efficient background thread write error, you can stop writing and rebuild the connection. |
- [TDengine Java Connector Error Code](https://github.com/taosdata/taos-connector-jdbc/blob/main/src/main/java/com/taosdata/jdbc/TSDBErrorNumbers.java)
<!-- - [TDengine_ERROR_CODE](../error-code) -->
@ -148,6 +149,7 @@ TDengine currently supports timestamp, numeric, character, boolean types, and th
| JSON | java.lang.String | only supported in tags |
| VARBINARY | byte[] | |
| GEOMETRY | byte[] | |
| DECIMAL | java.math.BigDecimal | |
**Note**: Due to historical reasons, the BINARY type in TDengine is not truly binary data and is no longer recommended. Please use VARBINARY type instead.
GEOMETRY type is binary data in little endian byte order, complying with the WKB standard. For more details, please refer to [Data Types](../../sql-manual/data-types/)
@ -319,7 +321,15 @@ The configuration parameters in properties are as follows:
- TSDBDriver.PROPERTY_KEY_DISABLE_SSL_CERT_VALIDATION: Disable SSL certificate validation. Effective only when using WebSocket connections. true: enabled, false: not enabled. Default is false.
- TSDBDriver.PROPERTY_KEY_APP_NAME: App name, can be used for display in the `show connections` query result. Effective only when using WebSocket connections. Default value is java.
- TSDBDriver.PROPERTY_KEY_APP_IP: App IP, can be used for display in the `show connections` query result. Effective only when using WebSocket connections. Default value is empty.
- TSDBDriver.PROPERTY_KEY_ASYNC_WRITE: Efficient Writing mode. Currently, only the `stmt` method is supported. Effective only when using WebSocket connections. DeDefault value is empty, meaning Efficient Writing mode is not enabled.
- TSDBDriver.PROPERTY_KEY_BACKEND_WRITE_THREAD_NUM: In Efficient Writing mode, this refers to the number of background write threads. Effective only when using WebSocket connections. Default value is 10.
- TSDBDriver.PROPERTY_KEY_BATCH_SIZE_BY_ROW: In Efficient Writing mode, this is the batch size for writing data, measured in rows. Effective only when using WebSocket connections. Default value is 1000.
- TSDBDriver.PROPERTY_KEY_CACHE_SIZE_BY_ROW: In Efficient Writing mode, this is the cache size, measured in rows. Effective only when using WebSocket connections. Default value is 10000.
- TSDBDriver.PROPERTY_KEY_COPY_DATA: In Efficient Writing mode, this determines Whether to copy the binary data passed by the application through the `addBatch` method. Effective only when using WebSocket connections. Default value is false.
- TSDBDriver.PROPERTY_KEY_STRICT_CHECK: In Efficient Writing mode, this determines whether to validate the length of table names and variable-length data types. Effective only when using WebSocket connections. Default value is false.
- TSDBDriver.PROPERTY_KEY_RETRY_TIMES: In Efficient Writing mode, this is the number of retry attempts for failed write operations. Effective only when using WebSocket connections. Default value is 3.
Additionally, for native JDBC connections, other parameters such as log level and SQL length can be specified by specifying the URL and Properties.
**Priority of Configuration Parameters**

229
docs/en/14-reference/09-error-code.md
View File

@ -41,6 +41,8 @@ This document details the server error codes that may be encountered when using
| 0x80000107 | Ref ID is removed | The referenced ref resource has been released | Preserve the scene and logs, report issue on github |
| 0x80000108 | Invalid Ref ID | Invalid ref ID | Preserve the scene and logs, report issue on github |
| 0x8000010A | Ref is not there | ref information does not exist | Preserve the scene and logs, report issue on github |
| 0x8000010B | Driver was not loaded | libtaosnative.so or libtaosws.so was not found in the system path | Reinstall the client driver |
| 0x8000010C | Function was not loaded from the driver | some function defined in libtaos.so are not implemented in libtaosnative.so or libtaosws.so | Reinstall the client driver |
| 0x80000110 | Unexpected generic error | System internal error | Preserve the scene and logs, report issue on github |
| 0x80000111 | Action in progress | Operation in progress | 1. Wait for the operation to complete 2. Cancel the operation if necessary 3. If it exceeds a reasonable time and still not completed, preserve the scene and logs, or contact customer support |
| 0x80000112 | Out of range | Configuration parameter exceeds allowed value range | Change the parameter |
@ -73,6 +75,8 @@ This document details the server error codes that may be encountered when using
| 0x80000134 | Invalid value | Invalid value | Preserve the scene and logs, report issue on github |
| 0x80000135 | Invalid fqdn | Invalid FQDN | Check if the configured or input FQDN value is correct |
| 0x8000013C | Invalid disk id | Invalid disk id | Check users whether the mounted disk is invalid or use the parameter diskIDCheckEnabled to skip the disk check. |
| 0x8000013D | Decimal value overflow | Decimal value overflow | Check query expression and decimal values |
| 0x8000013E | Division by zero error | Division by zero | Check division expression |
## tsc
@ -109,6 +113,7 @@ This document details the server error codes that may be encountered when using
| 0x8000030C | Invalid query id | Internal error | Report issue |
| 0x8000030E | Invalid connection id | Internal error | Report issue |
| 0x80000315 | User is disabled | User is unavailable | Grant permissions |
| 0x80000318 | Mnode internal error | Internal error | Report issue |
| 0x80000320 | Object already there | Internal error | Report issue |
| 0x80000322 | Invalid table type | Internal error | Report issue |
| 0x80000323 | Object not there | Internal error | Report issue |
@ -165,6 +170,7 @@ This document details the server error codes that may be encountered when using
| 0x8000038B | Index not exist | Does not exist | Confirm if the operation is correct |
| 0x80000396 | Database in creating status | Database is being created | Retry |
| 0x8000039A | Invalid system table name | Internal error | Report issue |
| 0x8000039F | No VGroup's leader need to be balanced | Perform balance leader operation on VGroup | There is no VGroup's leader needs to be balanced |
| 0x800003A0 | Mnode already exists | Already exists | Confirm if the operation is correct |
| 0x800003A1 | Mnode not there | Already exists | Confirm if the operation is correct |
| 0x800003A2 | Qnode already exists | Already exists | Confirm if the operation is correct |
@ -370,98 +376,111 @@ This document details the server error codes that may be encountered when using
## parser
| Error Code | Description | Possible Error Scenarios or Reasons | Suggested Actions for Users |
| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 0x80002600 | syntax error near | SQL syntax error | Check and correct the SQL statement |
| 0x80002601 | Incomplete SQL statement | Incomplete SQL statement | Check and correct the SQL statement |
| 0x80002602 | Invalid column name | Illegal or non-existent column name | Check and correct the SQL statement |
| 0x80002603 | Table does not exist | Table does not exist | Check and confirm the existence of the table in the SQL statement |
| 0x80002604 | Column ambiguously defined | Column (alias) redefined | Check and correct the SQL statement |
| 0x80002605 | Invalid value type | Illegal constant value | Check and correct the SQL statement |
| 0x80002608 | There mustn't be aggregation | Aggregation function used in illegal clause | Check and correct the SQL statement |
| 0x80002609 | ORDER BY item must be the number of a SELECT-list expression | Illegal position specified in Order by | Check and correct the SQL statement |
| 0x8000260A | Not a GROUP BY expression | Illegal group by statement | Check and correct the SQL statement |
| 0x8000260B | Not SELECTed expression | Illegal expression | Check and correct the SQL statement |
| 0x8000260C | Not a single-group group function | Illegal use of column and function | Check and correct the SQL statement |
| 0x8000260D | Tags number not matched | Mismatched number of tag columns | Check and correct the SQL statement |
| 0x8000260E | Invalid tag name | Invalid or non-existent tag name | Check and correct the SQL statement |
| 0x80002610 | Value is too long | Value length exceeds limit | Check and correct the SQL statement or API parameters |
| 0x80002611 | Password too short or empty | Password is empty or less than 8 chars | Use a valid password |
| 0x80002612 | Port should be an integer that is less than 65535 and greater than 0 | Illegal port number | Check and correct the port number |
| 0x80002613 | Endpoint should be in the format of 'fqdn:port' | Incorrect address format | Check and correct the address information |
| 0x80002614 | This statement is no longer supported | Feature has been deprecated | Refer to the feature documentation |
| 0x80002615 | Interval too small | Interval value exceeds the allowed minimum | Change the INTERVAL value |
| 0x80002616 | Database not specified | Database not specified | Specify the database for the current operation |
| 0x80002617 | Invalid identifier name | Illegal or invalid length ID | Check the names of related libraries, tables, columns, TAGs, etc. in the statement |
| 0x80002618 | Corresponding supertable not in this db | Supertable does not exist | Check if the corresponding supertable exists in the database |
| 0x80002619 | Invalid database option | Illegal database option value | Check and correct the database option values |
| 0x8000261A | Invalid table option | Illegal table option value | Check and correct the table option values |
| 0x80002624 | GROUP BY and WINDOW-clause can't be used together | Group by and window cannot be used together | Check and correct the SQL statement |
| 0x80002627 | Aggregate functions do not support nesting | Functions do not support nested use | Check and correct the SQL statement |
| 0x80002628 | Only support STATE_WINDOW on integer/bool/varchar column | Unsupported STATE_WINDOW data type | Check and correct the SQL statement |
| 0x80002629 | Not support STATE_WINDOW on tag column | STATE_WINDOW not supported on tag column | Check and correct the SQL statement |
| 0x8000262A | STATE_WINDOW not support for supertable query | STATE_WINDOW not supported for supertable | Check and correct the SQL statement |
| 0x8000262B | SESSION gap should be fixed time window, and greater than 0 | Illegal SESSION window value | Check and correct the SQL statement |
| 0x8000262C | Only support SESSION on primary timestamp column | Illegal SESSION window column | Check and correct the SQL statement |
| 0x8000262D | Interval offset cannot be negative | Illegal INTERVAL offset value | Check and correct the SQL statement |
| 0x8000262E | Cannot use 'year' as offset when interval is 'month' | Illegal INTERVAL offset unit | Check and correct the SQL statement |
| 0x8000262F | Interval offset should be shorter than interval | Illegal INTERVAL offset value | Check and correct the SQL statement |
| 0x80002630 | Does not support sliding when interval is natural month/year | Illegal sliding unit | Check and correct the SQL statement |
| 0x80002631 | sliding value no larger than the interval value | Illegal sliding value | Check and correct the SQL statement |
| 0x80002632 | sliding value can not less than 1%% of interval value | Illegal sliding value | Check and correct the SQL statement |
| 0x80002633 | Only one tag if there is a json tag | Only single JSON tag column supported | Check and correct the SQL statement |
| 0x80002634 | Query block has incorrect number of result columns | Mismatched number of columns | Check and correct the SQL statement |
| 0x80002635 | Incorrect TIMESTAMP value | Illegal primary timestamp column value | Check and correct the SQL statement |
| 0x80002637 | soffset/offset can not be less than 0 | Illegal soffset/offset value | Check and correct the SQL statement |
| 0x80002638 | slimit/soffset only available for PARTITION/GROUP BY query | slimit/soffset only supported for PARTITION BY/GROUP BY statements | Check and correct the SQL statement |
| 0x80002639 | Invalid topic query | Unsupported TOPIC query | |
| 0x8000263A | Cannot drop supertable in batch | Batch deletion of supertables not supported | Check and correct the SQL statement |
| 0x8000263B | Start(end) time of query range required or time range too large | Window count exceeds limit | Check and correct the SQL statement |
| 0x8000263C | Duplicated column names | Duplicate column names | Check and correct the SQL statement |
| 0x8000263D | Tags length exceeds max length | tag value length exceeds maximum supported range | Check and correct the SQL statement |
| 0x8000263E | Row length exceeds max length | Row length check and correct SQL statement | Check and correct the SQL statement |
| 0x8000263F | Illegal number of columns | Incorrect number of columns | Check and correct the SQL statement |
| 0x80002640 | Too many columns | Number of columns exceeds limit | Check and correct the SQL statement |
| 0x80002641 | First column must be timestamp | The first column must be the primary timestamp column | Check and correct the SQL statement |
| 0x80002642 | Invalid binary/nchar column/tag length | Incorrect length for binary/nchar | Check and correct the SQL statement |
| 0x80002643 | Invalid number of tag columns | Incorrect number of tag columns | Check and correct the SQL statement |
| 0x80002644 | Permission denied | Permission error | Check and confirm user permissions |
| 0x80002645 | Invalid stream query | Illegal stream statement | Check and correct the SQL statement |
| 0x80002646 | Invalid _c0 or_rowts expression | Illegal use of _c0 or_rowts | Check and correct the SQL statement |
| 0x80002647 | Invalid timeline function | Function depends on non-existent primary timestamp | Check and correct the SQL statement |
| 0x80002648 | Invalid password | Password does not meet standards | Check and change the password |
| 0x80002649 | Invalid alter table statement | Illegal modify table statement | Check and correct the SQL statement |
| 0x8000264A | Primary timestamp column cannot be dropped | Primary timestamp column cannot be deleted | Check and correct the SQL statement |
| 0x8000264B | Only binary/nchar column length could be modified, and the length can only be increased, not decreased | Illegal column modification | Check and correct the SQL statement |
| 0x8000264C | Invalid tbname pseudocolumn | Illegal use of tbname column | Check and correct the SQL statement |
| 0x8000264D | Invalid function name | Illegal function name | Check and correct the function name |
| 0x8000264E | Comment too long | Comment length exceeds limit | Check and correct the SQL statement |
| 0x8000264F | Function(s) only allowed in SELECT list, cannot mixed with non scalar functions or columns | Illegal mixing of functions | Check and correct the SQL statement |
| 0x80002650 | Window query not supported, since no valid timestamp column included in the result of subquery | Window query depends on non-existent primary timestamp column | Check and correct the SQL statement |
| 0x80002651 | No columns can be dropped | Essential columns cannot be deleted | Check and correct the SQL statement |
| 0x80002652 | Only tag can be json type | Normal columns do not support JSON type | Check and correct the SQL statement |
| 0x80002655 | The DELETE statement must have a definite time window range | Illegal WHERE condition in DELETE statement | Check and correct the SQL statement |
| 0x80002656 | The REDISTRIBUTE VGROUP statement only support 1 to 3 dnodes | Illegal number of DNODEs specified in REDISTRIBUTE VGROUP | Check and correct the SQL statement |
| 0x80002657 | Fill now allowed | Function does not allow FILL feature | Check and correct the SQL statement |
| 0x80002658 | Invalid windows pc | Illegal use of window pseudocolumn | Check and correct the SQL statement |
| 0x80002659 | Window not allowed | Function cannot be used in window | Check and correct the SQL statement |
| 0x8000265A | Stream not allowed | Function cannot be used in stream computation | Check and correct the SQL statement |
| 0x8000265B | Group by not allowd | Function cannot be used in grouping | Check and correct the SQL statement |
| 0x8000265D | Invalid interp clause | Illegal INTERP or related statement | Check and correct the SQL statement |
| 0x8000265E | Not valid function ion window | Illegal window statement | Check and correct the SQL statement |
| 0x8000265F | Only support single table | Function only supported in single table queries | Check and correct the SQL statement |
| 0x80002660 | Invalid sma index | Illegal creation of SMA statement | Check and correct the SQL statement |
| 0x80002661 | Invalid SELECTed expression | Invalid query statement | Check and correct the SQL statement |
| 0x80002662 | Fail to get table info | Failed to retrieve table metadata information | Preserve the scene and logs, report issue on GitHub |
| 0x80002663 | Not unique table/alias | Table name (alias) conflict | Check and correct the SQL statement |
| Error Code | Description | Possible Error Scenarios or Reasons | Suggested Actions for Users |
|------------| ------------------------------------------------------------ |----------------------------------------------------------------------------| ------------------------------------------------------------ |
| 0x80002600 | syntax error near | SQL syntax error | Check and correct the SQL statement |
| 0x80002601 | Incomplete SQL statement | Incomplete SQL statement | Check and correct the SQL statement |
| 0x80002602 | Invalid column name | Illegal or non-existent column name | Check and correct the SQL statement |
| 0x80002603 | Table does not exist | Table does not exist | Check and confirm the existence of the table in the SQL statement |
| 0x80002604 | Column ambiguously defined | Column (alias) redefined | Check and correct the SQL statement |
| 0x80002605 | Invalid value type | Illegal constant value | Check and correct the SQL statement |
| 0x80002608 | There mustn't be aggregation | Aggregation function used in illegal clause | Check and correct the SQL statement |
| 0x80002609 | ORDER BY item must be the number of a SELECT-list expression | Illegal position specified in Order by | Check and correct the SQL statement |
| 0x8000260A | Not a GROUP BY expression | Illegal group by statement | Check and correct the SQL statement |
| 0x8000260B | Not SELECTed expression | Illegal expression | Check and correct the SQL statement |
| 0x8000260C | Not a single-group group function | Illegal use of column and function | Check and correct the SQL statement |
| 0x8000260D | Tags number not matched | Mismatched number of tag columns | Check and correct the SQL statement |
| 0x8000260E | Invalid tag name | Invalid or non-existent tag name | Check and correct the SQL statement |
| 0x80002610 | Value is too long | Value length exceeds limit | Check and correct the SQL statement or API parameters |
| 0x80002611 | Password too short or empty | Password is empty or less than 8 chars | Use a valid password |
| 0x80002612 | Port should be an integer that is less than 65535 and greater than 0 | Illegal port number | Check and correct the port number |
| 0x80002613 | Endpoint should be in the format of 'fqdn:port' | Incorrect address format | Check and correct the address information |
| 0x80002614 | This statement is no longer supported | Feature has been deprecated | Refer to the feature documentation |
| 0x80002615 | Interval too small | Interval value exceeds the allowed minimum | Change the INTERVAL value |
| 0x80002616 | Database not specified | Database not specified | Specify the database for the current operation |
| 0x80002617 | Invalid identifier name | Illegal or invalid length ID | Check the names of related libraries, tables, columns, TAGs, etc. in the statement |
| 0x80002618 | Corresponding supertable not in this db | Supertable does not exist | Check if the corresponding supertable exists in the database |
| 0x80002619 | Invalid database option | Illegal database option value | Check and correct the database option values |
| 0x8000261A | Invalid table option | Illegal table option value | Check and correct the table option values |
| 0x80002624 | GROUP BY and WINDOW-clause can't be used together | Group by and window cannot be used together | Check and correct the SQL statement |
| 0x80002627 | Aggregate functions do not support nesting | Functions do not support nested use | Check and correct the SQL statement |
| 0x80002628 | Only support STATE_WINDOW on integer/bool/varchar column | Unsupported STATE_WINDOW data type | Check and correct the SQL statement |
| 0x80002629 | Not support STATE_WINDOW on tag column | STATE_WINDOW not supported on tag column | Check and correct the SQL statement |
| 0x8000262A | STATE_WINDOW not support for supertable query | STATE_WINDOW not supported for supertable | Check and correct the SQL statement |
| 0x8000262B | SESSION gap should be fixed time window, and greater than 0 | Illegal SESSION window value | Check and correct the SQL statement |
| 0x8000262C | Only support SESSION on primary timestamp column | Illegal SESSION window column | Check and correct the SQL statement |
| 0x8000262D | Interval offset cannot be negative | Illegal INTERVAL offset value | Check and correct the SQL statement |
| 0x8000262E | Cannot use 'year' as offset when interval is 'month' | Illegal INTERVAL offset unit | Check and correct the SQL statement |
| 0x8000262F | Interval offset should be shorter than interval | Illegal INTERVAL offset value | Check and correct the SQL statement |
| 0x80002630 | Does not support sliding when interval is natural month/year | Illegal sliding unit | Check and correct the SQL statement |
| 0x80002631 | sliding value no larger than the interval value | Illegal sliding value | Check and correct the SQL statement |
| 0x80002632 | sliding value can not less than 1%% of interval value | Illegal sliding value | Check and correct the SQL statement |
| 0x80002633 | Only one tag if there is a json tag | Only single JSON tag column supported | Check and correct the SQL statement |
| 0x80002634 | Query block has incorrect number of result columns | Mismatched number of columns | Check and correct the SQL statement |
| 0x80002635 | Incorrect TIMESTAMP value | Illegal primary timestamp column value | Check and correct the SQL statement |
| 0x80002637 | soffset/offset can not be less than 0 | Illegal soffset/offset value | Check and correct the SQL statement |
| 0x80002638 | slimit/soffset only available for PARTITION/GROUP BY query | slimit/soffset only supported for PARTITION BY/GROUP BY statements | Check and correct the SQL statement |
| 0x80002639 | Invalid topic query | Unsupported TOPIC query | |
| 0x8000263A | Cannot drop supertable in batch | Batch deletion of supertables not supported | Check and correct the SQL statement |
| 0x8000263B | Start(end) time of query range required or time range too large | Window count exceeds limit | Check and correct the SQL statement |
| 0x8000263C | Duplicated column names | Duplicate column names | Check and correct the SQL statement |
| 0x8000263D | Tags length exceeds max length | tag value length exceeds maximum supported range | Check and correct the SQL statement |
| 0x8000263E | Row length exceeds max length | Row length check and correct SQL statement | Check and correct the SQL statement |
| 0x8000263F | Illegal number of columns | Incorrect number of columns | Check and correct the SQL statement |
| 0x80002640 | Too many columns | Number of columns exceeds limit | Check and correct the SQL statement |
| 0x80002641 | First column must be timestamp | The first column must be the primary timestamp column | Check and correct the SQL statement |
| 0x80002642 | Invalid binary/nchar column/tag length | Incorrect length for binary/nchar | Check and correct the SQL statement |
| 0x80002643 | Invalid number of tag columns | Incorrect number of tag columns | Check and correct the SQL statement |
| 0x80002644 | Permission denied | Permission error | Check and confirm user permissions |
| 0x80002645 | Invalid stream query | Illegal stream statement | Check and correct the SQL statement |
| 0x80002646 | Invalid _c0 or_rowts expression | Illegal use of _c0 or_rowts | Check and correct the SQL statement |
| 0x80002647 | Invalid timeline function | Function depends on non-existent primary timestamp | Check and correct the SQL statement |
| 0x80002648 | Invalid password | Password does not meet standards | Check and change the password |
| 0x80002649 | Invalid alter table statement | Illegal modify table statement | Check and correct the SQL statement |
| 0x8000264A | Primary timestamp column cannot be dropped | Primary timestamp column cannot be deleted | Check and correct the SQL statement |
| 0x8000264B | Only binary/nchar column length could be modified, and the length can only be increased, not decreased | Illegal column modification | Check and correct the SQL statement |
| 0x8000264C | Invalid tbname pseudocolumn | Illegal use of tbname column | Check and correct the SQL statement |
| 0x8000264D | Invalid function name | Illegal function name | Check and correct the function name |
| 0x8000264E | Comment too long | Comment length exceeds limit | Check and correct the SQL statement |
| 0x8000264F | Function(s) only allowed in SELECT list, cannot mixed with non scalar functions or columns | Illegal mixing of functions | Check and correct the SQL statement |
| 0x80002650 | Window query not supported, since no valid timestamp column included in the result of subquery | Window query depends on non-existent primary timestamp column | Check and correct the SQL statement |
| 0x80002651 | No columns can be dropped | Essential columns cannot be deleted | Check and correct the SQL statement |
| 0x80002652 | Only tag can be json type | Normal columns do not support JSON type | Check and correct the SQL statement |
| 0x80002655 | The DELETE statement must have a definite time window range | Illegal WHERE condition in DELETE statement | Check and correct the SQL statement |
| 0x80002656 | The REDISTRIBUTE VGROUP statement only support 1 to 3 dnodes | Illegal number of DNODEs specified in REDISTRIBUTE VGROUP | Check and correct the SQL statement |
| 0x80002657 | Fill now allowed | Function does not allow FILL feature | Check and correct the SQL statement |
| 0x80002658 | Invalid windows pc | Illegal use of window pseudocolumn | Check and correct the SQL statement |
| 0x80002659 | Window not allowed | Function cannot be used in window | Check and correct the SQL statement |
| 0x8000265A | Stream not allowed | Function cannot be used in stream computation | Check and correct the SQL statement |
| 0x8000265B | Group by not allowd | Function cannot be used in grouping | Check and correct the SQL statement |
| 0x8000265D | Invalid interp clause | Illegal INTERP or related statement | Check and correct the SQL statement |
| 0x8000265E | Not valid function ion window | Illegal window statement | Check and correct the SQL statement |
| 0x8000265F | Only support single table | Function only supported in single table queries | Check and correct the SQL statement |
| 0x80002660 | Invalid sma index | Illegal creation of SMA statement | Check and correct the SQL statement |
| 0x80002661 | Invalid SELECTed expression | Invalid query statement | Check and correct the SQL statement |
| 0x80002662 | Fail to get table info | Failed to retrieve table metadata information | Preserve the scene and logs, report issue on GitHub |
| 0x80002663 | Not unique table/alias | Table name (alias) conflict | Check and correct the SQL statement |
| 0x80002664 | Join requires valid time-series input | Unsupported JOIN query without primary timestamp column output in subquery | Check and correct the SQL statement |
| 0x80002665 | The _TAGS pseudocolumn can only be used for subtable and supertable queries | Illegal tag column query | Check and correct the SQL statement |
| 0x80002666 | Subquery does not output primary timestamp column | Check and correct the SQL statement | |
| 0x80002667 | Invalid usage of expr: %s | Illegal expression | Check and correct the SQL statement |
| 0x80002687 | True_for duration cannot be negative | Use negative value as true_for duration | Check and correct the SQL statement |
| 0x80002688 | Cannot use 'year' or 'month' as true_for duration | Use year or month as true_for_duration | Check and correct the SQL statement |
| 0x80002689 | Invalid using cols function | Illegal using cols function | Check and correct the SQL statement |
| 0x8000268A | Cols function's first param must be a select function that output a single row | The first parameter of the cols function should be a selection function | Check and correct the SQL statement |
| 0x8000268B | Invalid using alias for cols function | Illegal cols function alias | Check and correct the SQL statement |
| 0x8000268C | Join primary key col must be timestmap type | Join primary key data type error | Check and correct the SQL statement |
| 0x8000268D | Invalid virtual table's ref column | Create/Update Virtual table using incorrect data source column | Check and correct the SQL statement |
| 0x8000268E | Invalid table type | Incorrect Table type | Check and correct the SQL statement |
| 0x8000268F | Invalid ref column type | Virtual table's column type and data source column's type are different | Check and correct the SQL statement |
| 0x80002690 | Create child table using virtual super table | Create non-virtual child table using virtual super table | Check and correct the SQL statement |
| 0x800026FF | Parser internal error | Internal error in parser | Preserve the scene and logs, report issue on GitHub |
| 0x80002700 | Planner internal error | Internal error in planner | Preserve the scene and logs, report issue on GitHub |
| 0x80002701 | Expect ts equal | JOIN condition validation failed | Preserve the scene and logs, report issue on GitHub |
| 0x80002702 | Cross join not support | CROSS JOIN not supported | Check and correct the SQL statement |
| 0x80002704 | Planner slot key not found | Planner cannot find slotId during making physic plan | Preserve the scene and logs, report issue on GitHub |
| 0x80002705 | Planner invalid table type | Planner get invalid table type | Preserve the scene and logs, report issue on GitHub |
| 0x80002706 | Planner invalid query control plan type | Planner get invalid query control plan type during making physic plan | Preserve the scene and logs, report issue on GitHub |
## function
@ -479,10 +498,10 @@ This document details the server error codes that may be encountered when using
| Error Code | Description | Possible Scenarios or Reasons | Recommended Actions |
| ---------- | ---------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 0x80002901 | udf is stopping | udf call received when dnode exits | Stop executing udf queries |
| 0x80002902 | udf pipe read error | Error occurred when taosd reads from udfd pipe | udfd unexpectedly exits, 1) C udf crash 2) udfd crash |
| 0x80002903 | udf pipe connect error | Error establishing pipe connection to udfd in taosd | 1) Corresponding udfd not started in taosd. Restart taosd |
| 0x80002904 | udf pipe not exist | Connection error occurs between two phases of udf setup, call, and teardown, causing the connection to disappear, subsequent phases continue | udfd unexpectedly exits, 1) C udf crash 2) udfd crash |
| 0x80002905 | udf load failure | Error loading udf in udfd | 1) udf does not exist in mnode 2) Error in udf loading. Check logs |
| 0x80002902 | udf pipe read error | Error occurred when taosd reads from taosudf pipe | taosudf unexpectedly exits, 1) C udf crash 2) taosudf crash |
| 0x80002903 | udf pipe connect error | Error establishing pipe connection to taosudf in taosd | 1) Corresponding taosudf not started in taosd. Restart taosd |
| 0x80002904 | udf pipe not exist | Connection error occurs between two phases of udf setup, call, and teardown, causing the connection to disappear, subsequent phases continue | taosudf unexpectedly exits, 1) C udf crash 2) taosudf crash |
| 0x80002905 | udf load failure | Error loading udf in taosudf | 1) udf does not exist in mnode 2) Error in udf loading. Check logs |
| 0x80002906 | udf invalid function input | udf input check | udf function does not accept input, such as wrong column type |
| 0x80002907 | udf invalid bufsize | Intermediate result in udf aggregation function exceeds specified bufsize | Increase bufsize, or reduce intermediate result size |
| 0x80002908 | udf invalid output type | udf output type differs from the type specified when creating udf | Modify udf, or the type when creating udf, to match the result |
@ -531,8 +550,38 @@ This document details the server error codes that may be encountered when using
| Error Code | Description | Possible Error Scenarios or Reasons | Recommended Actions for Users |
| ---------- | --------------------- | ------------------------------------------------------------ | -------------------------------------------- |
| 0x800003E6 | Consumer not exist | Consumer timeout offline | rebuild consumer to subscribe data again |
| 0x800003EA | Consumer not ready | Consumer rebalancing | retry after 2s |
| 0x80004000 | Invalid message | The subscribed data is illegal, generally does not occur | Check the client-side error logs for details |
| 0x80004001 | Consumer mismatch | The vnode requested for subscription and the reassigned vnode are inconsistent, usually occurs when new consumers join the same consumer group | Internal error, not exposed to users |
| 0x80004001 | Consumer mismatch | The vnode requested for subscription and the reassigned vnode are inconsistent, usually occurs when new consumers join the same consumer group | Internal error |
| 0x80004002 | Consumer closed | The consumer no longer exists | Check if it has already been closed |
| 0x80004017 | Invalid status, please subscribe topic first | tmq status invalidate | Without calling subscribe, directly poll data |
| 0x80004017 | Invalid status, please subscribe topic first | tmq status invalidate | Without calling subscribe, directly poll data |
| 0x80004100 | Stream task not exist | The stream computing task does not exist | Check the server-side error logs |
## TDgpt
| Error Code | Description | Possible Error Scenarios or Reasons | Recommanded Actions for Users |
| ---------- | --------------------- | -------------------------------------------------------------------------------- | ------------------------------ |
| 0x80000440 | Analysis service response is NULL | The response content is empty | Check the taosanode.app.log for detailed response information |
| 0x80000441 | Analysis service can't access | Service is not work currectly, or network is broken | Check the status of taosanode and network status |
| 0x80000442 | Analysis algorithm is missing | Algorithm used in analysis is not specified | Add the "algo" parameter in forecast function or anomaly_window clause |
| 0x80000443 | Analysis algorithm not loaded | The specified algorithm is not available | Check for the specified algorithm |
| 0x80000444 | Analysis invalid buffer type | The bufferred data type is invalid | Check the taosanode.app.log for more details |
| 0x80000445 | Analysis failed since anode return error | The responses from anode with error message | Check the taosanode.app.log for more details |
| 0x80000446 | Analysis failed since too many input rows for anode | Input data is too many | Reduce the rows of input data to below than the threshold |
| 0x80000447 | white-noise data not processed | white noise data is not processed | Ignore the white noise check or use another input data |
| 0x80000448 | Analysis internal error, not processed | Internal error occurs | Check the taosanode.app.log for more details |
## virtual table
| Error Code | Description | Possible Error Scenarios or Reasons | Recommended Actions for Users |
|------------|---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| 0x80006200 | Virtual table scan internal error | virtual table scan operator internal error, generally does not occur | Check error logs, contact development for handling |
| 0x80006201 | Virtual table scan invalid downstream operator type | The incorrect execution plan generated causes the downstream operator type of the virtual table scan operator to be incorrect. | Check error logs, contact development for handling |
| 0x80006202 | Virtual table prim timestamp column should not has ref | The timestamp primary key column of a virtual table should not have a data source. If it does, this error will occur during subsequent queries on the virtual table. | Check error logs, contact development for handling |
| 0x80006203 | Create virtual child table must use virtual super table | Create virtual child table using non-virtual super table | create virtual child table using virtual super table |
| 0x80006204 | Virtual table not support decimal type | Create virtual table using decimal type | create virtual table without using decimal type |
| 0x80006205 | Virtual table not support in STMT query and STMT insert | Use virtual table in stmt query and stmt insert | do not use virtual table in stmt query and insert |
| 0x80006206 | Virtual table not support in Topic | Use virtual table in topic | do not use virtual table in topic |
| 0x80006207 | Virtual super table query not support origin table from different databases | Virtual super table ‘s child table's origin table from different databases | make sure virtual super table's child table's origin table from same database |

297
docs/en/27-train-faq/03-password.md Normal file
View File

@ -0,0 +1,297 @@
---
title: Usage of Special Characters in Passwords
description: Usage of special characters in user passwords in TDengine
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
TDengine user passwords must meet the following rules:
1. The username must not exceed 23 bytes.
2. The password length must be between 8 and 255 characters.
3. The range of password characters:
1. Uppercase letters: `A-Z`
2. Lowercase letters: `a-z`
3. Numbers: `0-9`
4. Special characters: `! @ # $ % ^ & * ( ) - _ + = [ ] { } : ; > < ? | ~ , .`
4. When strong password is enabled (EnableStrongPassword 1, enabled by default), the password must contain at least three of the following categories: uppercase letters, lowercase letters, numbers, and special characters. When not enabled, there are no restrictions on character types.
## Usage Guide for Special Characters in Different Components
Take the username `user1` and password `Ab1!@#$%^&*()-_+=[]{}` as an example.
```sql
CREATE USER user1 PASS 'Ab1!@#$%^&*()-_+=[]{}';
```
<Tabs defaultValue="shell" groupId="component">
<TabItem label="CLI" value="shell">
In the [TDengine Command Line Interface (CLI)](../../tdengine-reference/tools/tdengine-cli/), note the following:
- If the `-p` parameter is used without a password, you will be prompted to enter a password, and any acceptable characters can be entered.
- If the `-p` parameter is used with a password, and the password contains special characters, single quotes must be used.
Login with user `user1`:
```shell
taos -u user1 -p'Ab1!@#$%^&*()-_+=[]{}'
taos -u user1 -pAb1\!\@\#\$\%\^\&\*\(\)\-\_\+\=\[\]\{\}
```
</TabItem>
<TabItem label="taosdump" value="taosdump">
In [taosdump](../../tdengine-reference/tools/taosdump/), note the following:
- If the `-p` parameter is used without a password, you will be prompted to enter a password, and any acceptable characters can be entered.
- If the `-p` parameter is used with a password, and the password contains special characters, single quotes or escaping must be used.
Backup database `test` with user `user1`:
```shell
taosdump -u user1 -p'Ab1!@#$%^&*()-_+=[]{}' -D test
taosdump -u user1 -pAb1\!\@\#\$\%\^\&\*\(\)\-\_\+\=\[\]\{\} -D test
```
</TabItem>
<TabItem label="Benchmark" value="benchmark">
In [taosBenchmark](../../tdengine-reference/tools/taosbenchmark/), note the following:
- If the `-p` parameter is used without a password, you will be prompted to enter a password, and any acceptable characters can be entered.
- If the `-p` parameter is used with a password, and the password contains special characters, single quotes or escaping must be used.
Example of data write test with user `user1`:
```shell
taosBenchmark -u user1 -p'Ab1!@#$%^&*()-_+=[]{}' -d test -y
```
When using `taosBenchmark -f <JSON>`, there are no restrictions on the password in the JSON file.
</TabItem>
<TabItem label="taosX" value="taosx">
[taosX](../../tdengine-reference/components/taosx/) uses DSN to represent TDengine connections, in the format: `(taos|tmq)[+ws]://<user>:<pass>@<ip>:<port>`, where `<pass>` can contain special characters, such as: `taos+ws://user1:Ab1!@#$%^&*()-_+=[]{}@192.168.10.10:6041`.
Example of exporting data with user `user1`:
```shell
taosx -f 'taos://user1:Ab1!@#$%^&*()-_+=[]{}@localhost:6030?query=select * from test.t1' \
-t 'csv:./test.csv'
```
Note that if the password can be URL decoded, the URL decoded result will be used as the password. For example: `taos+ws://user1:Ab1%21%40%23%24%25%5E%26%2A%28%29-_%2B%3D%5B%5D%7B%7D@localhost:6041` is equivalent to `taos+ws://user1:Ab1!@#$%^&*()-_+=[]{}@localhost:6041`.
No special handling is required in [Explorer](../../tdengine-reference/components/taosexplorer/), just use it directly.
</TabItem>
<TabItem label="Java" value="java">
When using special character passwords in JDBC, the password needs to be URL encoded, as shown below:
```java
package com.taosdata.example;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.util.Properties;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import com.taosdata.jdbc.TSDBDriver;
public class JdbcPassDemo {
public static void main(String[] args) throws Exception {
String password = "Ab1!@#$%^&*()-_+=[]{}";
String encodedPassword = URLEncoder.encode(password, StandardCharsets.UTF_8.toString());
String jdbcUrl = "jdbc:TAOS-WS://localhost:6041";
Properties connProps = new Properties();
connProps.setProperty(TSDBDriver.PROPERTY_KEY_USER, "user1");
connProps.setProperty(TSDBDriver.PROPERTY_KEY_PASSWORD, encodedPassword);
connProps.setProperty(TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT, "true");
connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8");
connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8");
try (Connection conn = DriverManager.getConnection(jdbcUrl, connProps)) {
System.out.println("Connected to " + jdbcUrl + " successfully.");
// you can use the connection for execute SQL here
} catch (Exception ex) {
// please refer to the JDBC specifications for detailed exceptions info
System.out.printf("Failed to connect to %s, %sErrMessage: %s%n",
jdbcUrl,
ex instanceof SQLException ? "ErrCode: " + ((SQLException) ex).getErrorCode() + ", " : "",
ex.getMessage());
// Print stack trace for context in examples. Use logging in production.
ex.printStackTrace();
throw ex;
}
}
}
```
</TabItem>
<TabItem label="Python" value="python">
No special handling is required for special character passwords in Python, as shown below:
```python
import taos
import taosws
def create_connection():
host = "localhost"
port = 6030
return taos.connect(
user="user1",
password="Ab1!@#$%^&*()-_+=[]{}",
host=host,
port=port,
)
def create_ws_connection():
host = "localhost"
port = 6041
return taosws.connect(
user="user1",
password="Ab1!@#$%^&*()-_+=[]{}",
host=host,
port=port,
)
def show_databases(conn):
cursor = conn.cursor()
cursor.execute("show databases")
print(cursor.fetchall())
cursor.close()
if __name__ == "__main__":
print("Connect with native protocol")
conn = create_connection()
show_databases(conn)
print("Connect with websocket protocol")
conn = create_ws_connection()
show_databases(conn)
```
</TabItem>
<TabItem label="Go" value="go">
Starting from version 3.6.0, Go supports passwords containing special characters, which need to be encoded using encodeURIComponent.
```go
package main
import (
"database/sql"
"fmt"
"log"
"net/url"
_ "github.com/taosdata/driver-go/v3/taosWS"
)
func main() {
var user = "user1"
var password = "Ab1!@#$%^&*()-_+=[]{}"
var encodedPassword = url.QueryEscape(password)
var taosDSN = user + ":" + encodedPassword + "@ws(localhost:6041)/"
taos, err := sql.Open("taosWS", taosDSN)
if err != nil {
log.Fatalln("Failed to connect to " + taosDSN + "; ErrMessage: " + err.Error())
}
fmt.Println("Connected to " + taosDSN + " successfully.")
defer taos.Close()
}
```
</TabItem>
<TabItem label="Rust" value="rust">
In Rust, DSN is used to represent TDengine connections, in the format: `(taos|tmq)[+ws]://<user>:<pass>@<ip>:<port>`, where `<pass>` can contain special characters, such as: `taos+ws://user1:Ab1!@#$%^&*()-_+=[]{}@192.168.10.10:6041`.
```rust
let dsn = "taos+ws://user1:Ab1!@#$%^&*()-_+=[]{}@localhost:6041";
let connection = TaosBuilder::from_dsn(&dsn)?.build().await?;
```
</TabItem>
<TabItem label="Node.js" value="node">
Starting from version 3.1.5, the Node.js connector supports passwords containing all valid characters.
```js
const taos = require("@tdengine/websocket");
let dsn = 'ws://localhost:6041';
async function createConnect() {
try {
let conf = new taos.WSConfig(dsn);
conf.setUser('user1');
conf.setPwd('Ab1!@#$%^&*()-_+=[]{}');
conf.setDb('test');
conn = await taos.sqlConnect(conf);
console.log("Connected to " + dsn + " successfully.");
return conn;
} catch (err) {
console.log("Connection failed with code: " + err.code + ", message: " + err.message);
throw err;
}
}
createConnect()
```
</TabItem>
<TabItem label="C#" value="csharp">
When using passwords in C#, note that connection strings do not support semicolons (as semicolons are delimiters). In this case, you can construct the `ConnectionStringBuilder` without a password, and then set the username and password.
As shown below:
```csharp
var builder = new ConnectionStringBuilder("host=localhost;port=6030");
builder.Username = "user1";
builder.Password = "Ab1!@#$%^&*()-_+=[]{}";
using (var client = DbDriver.Open(builder)){}
```
</TabItem>
<TabItem label="C" value="c">
There are no restrictions on passwords in C.
```c
TAOS *taos = taos_connect("localhost", "user1", "Ab1!@#$%^&*()-_+=[]{}", NULL, 6030);
```
</TabItem>
<TabItem label="REST" value="rest">
When using passwords in REST API, note the following:
- Passwords use Basic Auth, in the format `Authorization: Basic base64(<user>:<pass>)`.
- Passwords containing colons `:` are not supported.
The following two methods are equivalent:
```shell
curl -u'user1:Ab1!@#$%^&*()-_+=[]{}' \
-d 'show databases' http://localhost:6041/rest/sql
curl -H 'Authorization: Basic dXNlcjE6QWIxIUAjJCVeJiooKS1fKz1bXXt9' \
-d 'show databases' http://localhost:6041/rest/sql
```
</TabItem>
</Tabs>

BIN
docs/en/assets/data-model-origin-table-2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 55 KiB

BIN
docs/en/assets/data-model-origin-table.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 53 KiB

3
docs/examples/c/insert_data_demo.c
View File

@ -58,12 +58,13 @@ static int DemoInsertData() {
taos_cleanup();
return -1;
}
taos_free_result(result);
// you can check affectedRows here
int rows = taos_affected_rows(result);
fprintf(stdout, "Successfully inserted %d rows into power.meters.\n", rows);
taos_free_result(result);
// close & clean
taos_close(taos);
taos_cleanup();

8
docs/examples/python/kafka_example_consumer.py
View File

@ -182,7 +182,7 @@ def test_json_to_taos(consumer: Consumer):
'voltage': 105,
'phase': 0.02027, }),
partition=1, topic='test', serialized_key_size=None, serialized_header_size=None,
serialized_value_size=None, timestamp=time.time(), timestamp_type=None),
serialized_value_size=None, timestamp=time.time(), timestamp_type=None, leader_epoch=0),
ConsumerRecord(checksum=None, headers=None, offset=1, key=None,
value=json.dumps({'table_name': 'd1',
'ts': '2022-12-06 15:13:39.643',
@ -190,7 +190,7 @@ def test_json_to_taos(consumer: Consumer):
'voltage': 102,
'phase': 0.02027, }),
partition=1, topic='test', serialized_key_size=None, serialized_header_size=None,
serialized_value_size=None, timestamp=time.time(), timestamp_type=None),
serialized_value_size=None, timestamp=time.time(), timestamp_type=None,leader_epoch=0 ),
]
]
@ -203,11 +203,11 @@ def test_line_to_taos(consumer: Consumer):
ConsumerRecord(checksum=None, headers=None, offset=1, key=None,
value="d0 values('2023-01-01 00:00:00.001', 3.49, 109, 0.02737)".encode('utf-8'),
partition=1, topic='test', serialized_key_size=None, serialized_header_size=None,
serialized_value_size=None, timestamp=time.time(), timestamp_type=None),
serialized_value_size=None, timestamp=time.time(), timestamp_type=None,leader_epoch=0 ),
ConsumerRecord(checksum=None, headers=None, offset=1, key=None,
value="d1 values('2023-01-01 00:00:00.002', 6.19, 112, 0.09171)".encode('utf-8'),
partition=1, topic='test', serialized_key_size=None, serialized_header_size=None,
serialized_value_size=None, timestamp=time.time(), timestamp_type=None),
serialized_value_size=None, timestamp=time.time(), timestamp_type=None,leader_epoch=0 ),
]
]
consumer._line_to_taos(messages=records)

199
docs/zh/05-basic/01-model.md
View File

@ -3,6 +3,8 @@ sidebar_label: 数据模型
title: TDengine 数据模型
toc_max_heading_level: 4
---
import origintable from './data-model-origin-table.png';
import origintable2 from './data-model-origin-table-2.png';
为了清晰地阐述时序数据的基本概念，并为示例程序的编写提供便利，整个文档都将以智能电表为例，探讨时序数据的典型应用场景。设想有一种型号的智能电表，它能够采集
电流、电压和相位这 3 个模拟量。此外，每块智能电表还具有位置和分组等静态属性。这些智能电表采集的数据示例如下表所示。
@ -57,11 +59,11 @@ toc_max_heading_level: 4
### 超级表
采用“一个数据采集点一张表”的设计虽然有助于针对性地管理每个采集点，但随着设备数量不断增加表的数量也会急剧增加，这给数据库管理和数据分析带来了挑战。在进行跨数据采集点的聚合操作时，用户需要面对大量的表，工作变得异常繁重。
TDengine 采用“一个数据采集点一张表”的设计虽然有利于高效地管理每个数据采集点，但随着设备数量不断增加，表的数量也会急剧增加，这给表的管理以及表之间的聚合带来了巨大的挑战。
为了解决这个问题，TDengine 引入超级表（Super Table，简称为 STable）的概念。超级表是一种数据结构，它能够将某一特定类型的数据采集点聚集在一起，形成一张逻辑上的统一表。这些数据采集点具有相同的表结构，但各自的静态属性（如标签）可能不同。创建超级表时，除了定义采集量以外，还需定义超级表的标签。一张超级表至少包含一个时间戳列、一个或多个采集量列以及一个或多个标签列。此外，超级表的标签可以灵活地进行增加、修改或删除操作。
为了解决这个问题，TDengine 引入超级表（Super Table，简称为 STable）的概念。超级表是一种数据结构，它能将某一特定类型的数据采集点聚集在一起，形成一张逻辑上的统一表。这些数据采集点具有相同的表结构，但各自的静态属性（如标签）可能不同。创建超级表时，除了定义采集量的结构之外，还需定义超级表的标签。一张超级表至少包含一个时间戳列、一个或多个采集量列以及一个或多个标签列。此外，超级表的标签可以灵活地进行增加、修改或删除操作。
在 TDengine 中，表代表具体的数据采集点，而超级表则代表一组具有相同属性的数据采集点集合。以智能电表为例，我们可以为该类型的电表创建一张超级表，其中包含了所有智能电表的共有属性和采集量。这种设计不仅简化了表的管理，还便于进行跨数据采集点的聚合操作，从而提高数据处理的效率。
在 TDengine 中，表代表具体的数据采集点，而超级表则代表一组具有相同属性的数据采集点集合。以智能电表为例，我们可以为该类型的电表创建一张超级表，其中包含了所有智能电表的共有属性，包括动态的时序数据以及静态的标签数据。这种设计不仅简化了表的管理，还便于进行跨数据采集点的聚合操作，从而提高数据处理的效率。
### 子表
@ -77,6 +79,19 @@ toc_max_heading_level: 4
![数据模型示意图](./data-model.png)
### 虚拟表
“一个数据采集点一张表”以及“超级表”的设计解决了工业和物联网等场景下的大多数时序数据管理和分析难题。但是在真实的场景中，一个设备往往有多种传感器，而且他们的数据采集频次还相差很大。比如对于一台风机，有电的参数、环境参数、机械参数，各自的传感器和采集频次完全不一样。因此我们很难用一张表来描述一台设备，往往需要多张表。当需要综合多个传感器的数据进行分析计算时，只能通过多级关联查询的方式来进行，而这往往会导致易用性和性能方面的问题。而从用户的角度来看，“一个设备一张表”更为直观，容易操作。但如果我们建模之初，直接采用"一个设备一张表的“的设计，由于采集频次的不同，会导致每一个具体时间戳，大量的列是空值，从而降低存储和查询的效率。
为了解决这个问题，TDengine 引入虚拟表（Virtual Table，简称为 VTable）的概念。虚拟表是一种不存储实际数据而可以用于分析计算的表，它的数据来源为其它真实存储数据的子表、普通表，通过将各个原始表的不同列的数据按照时间戳排序、对齐、合并的方式来生成虚拟表。同真实表类似，虚拟表也可以分为虚拟超级表、虚拟子表、虚拟普通表。虚拟超级表可以是一个设备或一组分析计算所需数据的完整集合，每个虚拟子表可以根据需要引用相同或不同的列，因此可以灵活地根据业务需要进行定义，最终达到“千人千面”的效果。虚拟表不能写入、删除数据，在查询使用上同真实表相同。TDengine 支持虚拟超级表、虚拟子表、虚拟普通表上的任何查询。唯一的区别在于虚拟表的数据是每次查询计算时动态生成的，只有一个查询中引用的列才会被合并进虚拟表中，因此同一个虚拟表在不同的查询中所呈现以及扫描的数据可能是完全不同的。
虚拟超级表的主要功能特点包括：
1. 列选择与拼接：用户可以从多个原始表中选择指定的列，按需组合到一张虚拟表中，形成统一的数据视图。
2. 基于时间戳对齐：以时间戳为依据对数据进行对齐，如果多个表在相同时间戳下存在数据，则对应列的值组合成同一行；若部分表在该时间戳下无数据，则对应列填充为 NULL。
3. 动态更新：虚拟表根据原始表的数据变化自动更新，确保数据的实时性。虚拟表不需实际存储，计算在生成时动态完成。
通过引入虚拟表的概念，TDengine 可以非常方便的管理更大更复杂的设备数据。无论每个采集点如何建模（单列 or 多列），无论这些采集点的数据是分布在一个或多个库中，都可以通过定义虚拟表的方式跨库跨表任意指定数据源，通过虚拟超级表的方式进行跨数据采集点、跨分析的聚合运算，从此“一个设备一张表”彻底成为现实。
### 库
库是 TDengine 中用于管理一组表的集合。TDengine 允许一个运行实例包含多个库，并且每个库都可以配置不同的存储策略。由于不同类型的数据采集点通常具有不同的数据特征，如数据采集频率、数据保留期限、副本数量、数据块大小等。为了在各种场景下确保 TDengine 能够发挥最大效率，建议将具有不同数据特征的超级表创建在不同的库中。
@ -85,7 +100,7 @@ toc_max_heading_level: 4
### 时间戳
时间戳在时序数据处理中扮演着至关重要的角色，特别是在应用程序需要从多个不同时区访问数据库时，这一问题变得更加复杂。在深入了解 TDengine 如何处理时间戳与时区之前，我们先介绍以下几个基本概念。
时间戳在时序数据处理中扮演着至关重要的角色，特别是在应用程序需要从多个不同时区访问数据库时，这一问题变得更加复杂。在深入了解 TDengine 如何处理时间戳与时区之前，先介绍以下几个基本概念。
- 本地日期时间：指特定地区的当地时间，通常表示为 yyyy-MM-dd hh:mm:ss.SSS 格式的字符串。这种时间表示不包含任何时区信息，如 “2021-07-21 12:00:00.000”。
- 时区：地球上不同地理位置的标准时间。协调世界时（Universal Time Coordinated，UTC）或格林尼治时间是国际时间标准，其他时区通常表示为相对于 UTC 的偏移量，如 “UTC+8” 代表东八区时间。 UTC 时间戳：表示自 UNIX 纪元（即 UTC 时间 1970 年 1 月 1 日 0 点）起经过的毫秒数。例如，“1700000000000” 对应的日期时间是 “2023-11-14 22:13:20（UTC+0）”。 在 TDengine 中保存时序数据时，实际上保存的是 UTC 时间戳。TDengine 在写入数据时，时间戳的处理分为如下两种情况。
- RFC-3339 格式：当使用这种格式时，TDengine 能够正确解析带有时区信息的时间字符串为 UTC 时间戳。例如，“2018-10-03T14:38:05.000+08:00” 会被转换为 UTC 时间戳。
@ -95,7 +110,7 @@ toc_max_heading_level: 4
## 数据建模
本节用智能电表做例子，简要的介绍如何在 TDengine 里使用 SQL 创建数据库、超级表、表的基本操作。
本节以智能电表为例，介绍如何在 TDengine 里使用 SQL 创建数据库、超级表、表的基本操作。
### 创建数据库
@ -215,3 +230,177 @@ TDengine 支持灵活的数据模型设计，包括多列模型和单列模型
尽管 TDengine 推荐使用多列模型，因为这种模型在写入效率和存储效率方面通常更优，但在某些特定场景下，单列模型可能更为适用。例如，当一个数据采集点的采集量种类经常发生变化时，如果采用多列模型，就需要频繁修改超级表的结构定义，这会增加应用程序的复杂性。在这种情况下，采用单列模型可以简化应用程序的设计和管理，因为它允许独立地管理和扩展每个物理量的超级表。
总之，TDengine 提供了灵活的数据模型选项，用户可以根据实际需求和场景选择最适合的模型，以优化性能和管理复杂性。
### 创建虚拟表
无论是选择单列模型还是多列模型，TDengine 都可以通过使用虚拟表进行跨表的运算。为智能电表为例，这里介绍虚拟表的两种使用场景：
1. 单源多维度时序聚合
2. 跨源采集量对比分析
#### 单源多维度时序聚合
在单源多维度时序聚合场景中，“单源”并非指单一物理表，而是指来自**同一数据采集点**下的多个单列时序数据表。这些数据因业务需求或其他限制被拆分为多个单列存储的表，但通过设备标签和时间基准保持逻辑一致性。虚拟表在此场景中的作用是将一个采集点中“纵向“拆分的数据，还原为完整的“横向”状态。
例如，在建模时采用了单列模型，对于电流、电压和相位这 3 种物理量，分别建立 3 张超级表。在这种场景下，用户可以通过虚拟表将这 3 种不同的采集量聚合到一张表中，以便进行统一的查询和分析。
创建单列模型的超级表的 SQL 如下：
```sql
CREATE STABLE current_stb (
ts timestamp,
current float
) TAGS (
device_id varchar(64),
location varchar(64),
group_id int
);
CREATE STABLE voltage_stb (
ts timestamp,
voltage int
) TAGS (
device_id varchar(64),
location varchar(64),
group_id int
);
CREATE STABLE phase_stb (
ts timestamp,
phase float
) TAGS (
device_id varchar(64),
location varchar(64),
group_id int
);
```
假设有 d1001、d1002、d1003、d1004 四个设备，为四个设备的电流、电压、相位采集量分别创建子表，SQL 如下：
```sql
create table current_d1001 using current_stb(deviceid, location, group_id) tags("d1001", "California.SanFrancisco", 2);
create table current_d1002 using current_stb(deviceid, location, group_id) tags("d1002", "California.SanFrancisco", 3);
create table current_d1003 using current_stb(deviceid, location, group_id) tags("d1003", "California.LosAngeles", 3);
create table current_d1004 using current_stb(deviceid, location, group_id) tags("d1004", "California.LosAngeles", 2);
create table voltage_d1001 using voltage_stb(deviceid, location, group_id) tags("d1001", "California.SanFrancisco", 2);
create table voltage_d1002 using voltage_stb(deviceid, location, group_id) tags("d1002", "California.SanFrancisco", 3);
create table voltage_d1003 using voltage_stb(deviceid, location, group_id) tags("d1003", "California.LosAngeles", 3);
create table voltage_d1004 using voltage_stb(deviceid, location, group_id) tags("d1004", "California.LosAngeles", 2);
create table phase_d1001 using phase_stb(deviceid, location, group_id) tags("d1001", "California.SanFrancisco", 2);
create table phase_d1002 using phase_stb(deviceid, location, group_id) tags("d1002", "California.SanFrancisco", 3);
create table phase_d1003 using phase_stb(deviceid, location, group_id) tags("d1003", "California.LosAngeles", 3);
create table phase_d1004 using phase_stb(deviceid, location, group_id) tags("d1004", "California.LosAngeles", 2);
```
可通过一张虚拟超级表来将这三种采集量聚合到一张表中，创建虚拟超级表 SQL 如下：
```sql
CREATE STABLE meters_v (
ts timestamp,
current float,
voltage int,
phase float
) TAGS (
location varchar(64),
group_id int
) VIRTUAL 1;
```
并且对四个设备 d1001、d1002、d1003、d1004 分别创建虚拟子表，SQL 如下：
```sql
CREATE VTABLE d1001_v (
current from current_d1001.current,
voltage from voltage_d1001.voltage,
phase from phase_d1001.phase
)
USING meters_v
TAGS (
"California.SanFrancisco",
2
);
CREATE VTABLE d1002_v (
current from current_d1002.current,
voltage from voltage_d1002.voltage,
phase from phase_d1002.phase
)
USING meters_v
TAGS (
"California.SanFrancisco",
3
);
CREATE VTABLE d1003_v (
current from current_d1003.current,
voltage from voltage_d1003.voltage,
phase from phase_d1003.phase
)
USING meters_v
TAGS (
"California.LosAngeles",
3
);
CREATE VTABLE d1004_v (
current from current_d1004.current,
voltage from voltage_d1004.voltage,
phase from phase_d1004.phase
)
USING meters_v
TAGS (
"California.LosAngeles",
2
);
```
以设备 d1001 为例，假设 d1001 设备的电流、电压、相位数据如下：
<img src={origintable} width="500" alt="data-model-origin-table" />
虚拟表 d1001_v 中的数据如下:
| Timestamp | Current | Voltage | Phase |
|:--------------:|:-------:|:---------:|:-------:|
| 1538548685000 | 10.3 | 219 | 0.31 |
| 1538548695000 | 12.6 | 218 | 0.33 |
| 1538548696800 | 12.3 | 221 | 0.31 |
| 1538548697100 | 12.1 | 220 | NULL |
| 1538548697200 | NULL | NULL | 0.32 |
| 1538548697700 | 11.8 | NULL | NULL |
| 1538548697800 | NULL | 222 | 0.33 |
#### 跨源采集量对比分析
在跨源采集量对比分析中，“跨源”指数据来自**不同数据采集点**。在不同数据采集点中提取具有可比语义的采集量，通过虚拟表将这些采集量按照时间戳进行对齐和合并，并进行对比分析。
例如，用户可以将来自不同设备的电流数据聚合到一张虚拟表中，以便进行电流数据的对比分析。
以分析 d1001、d1002、d1003、d1004 四个设备的电流数据为例，创建虚拟表的 SQL 如下：
```sql
CREATE VTABLE current_v (
ts timestamp,
d1001_current float from current_d1001.current,
d1002_current float from current_d1002.current,
d1003_current float from current_d1003.current,
d1004_current float from current_d1004.current
);
```
假设 d1001, d1002, d1003, d1004 四个设备的电流数据如下：
<img src={origintable2} width="500" alt="data-model-origin-table-2" />
虚拟表 current_v 中的数据如下：
| Timestamp | d1001_current | d1002_current | d1003_current | d1004_current |
|:--------------:|:-------------:|:-------------:|:-------------:|:-------------:|
| 1538548685000 | 10.3 | 11.7 | 11.2 | 12.4 |
| 1538548695000 | 12.6 | 11.9 | 10.8 | 11.3 |
| 1538548696800 | 12.3 | 12.4 | 12.3 | 10.1 |
| 1538548697100 | 12.1 | NULL | 11.1 | NULL |
| 1538548697200 | NULL | 12.2 | NULL | 11.7 |
| 1538548697700 | 11.8 | 11.4 | NULL | NULL |
| 1538548697800 | NULL | NULL | 12.1 | 12.6 |

3
docs/zh/05-basic/02-insert.md
View File

@ -113,6 +113,9 @@ TDengine 还支持直接向超级表写入数据。需要注意的是，超级
insert into meters (tbname, ts, current, voltage, phase, location, group_id)
values("d1001", "2018-10-03 14:38:05", 10.2, 220, 0.23, "California.SanFrancisco", 2)
```
### 通过虚拟表写入
TDengine 不支持向虚拟表或虚拟超级表写入，因为虚拟表或虚拟超级表是动态生成的，本身不存储数据。
### 零代码写入

BIN
docs/zh/05-basic/data-model-origin-table-2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 55 KiB

BIN
docs/zh/05-basic/data-model-origin-table.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 53 KiB

9
docs/zh/06-advanced/01-subscription.md
View File

@ -64,10 +64,10 @@ CREATE TOPIC [IF NOT EXISTS] topic_name [with meta] AS DATABASE db_name;
## 删除主题
如果不再需要订阅数据，可以删除 topic，需要注意只有当前未在订阅中的 topic 才能被删除。
如果不再需要订阅数据，可以删除 topic，如果当前 topic 被消费者订阅，通过 FORCE 语法可强制删除，强制删除后订阅的消费者会消费数据会出错（FORCE 语法从 v3.3.6.0 开始支持）。
```sql
DROP TOPIC [IF EXISTS] topic_name;
DROP TOPIC [IF EXISTS] [FORCE] topic_name;
```
## 查看主题
@ -94,9 +94,9 @@ SHOW CONSUMERS;
### 删除消费组
消费者创建的时候，会给消费者指定一个消费者组，消费者不能显式的删除，但是消费者组在组内没有消费者时可以通过下面语句删除：
消费者创建的时候，会给消费者指定一个消费者组，消费者不能显式的删除，但是可以删除消费者组。如果当前消费者组里有消费者在消费，通过 FORCE 语法可强制删除，强制删除后订阅的消费者会消费数据会出错（FORCE 语法从 v3.3.6.0 开始支持）。
```sql
DROP CONSUMER GROUP [IF EXISTS] cgroup_name ON topic_name;
DROP CONSUMER GROUP [IF EXISTS] [FORCE] cgroup_name ON topic_name;
```
## 数据订阅
@ -129,6 +129,7 @@ TDengine 的数据订阅功能支持回放（replay）功能，允许用户按
```
使用数据订阅的回放功能时需要注意如下几项：
- 通过配置消费参数 enable.replay 为 true 开启回放功能。
- 数据订阅的回放功能仅查询订阅支持数据回放，超级表和库订阅不支持回放。
- 回放不支持进度保存。
- 因为数据回放本身需要处理时间，所以回放的精度存在几十毫秒的误差。

18
docs/zh/06-advanced/03-stream.md
View File

@ -23,11 +23,11 @@ CREATE STREAM [IF NOT EXISTS] stream_name [stream_options] INTO stb_name
SUBTABLE(expression) AS subquery
stream_options: {
TRIGGER [AT_ONCE | WINDOW_CLOSE | MAX_DELAY time | FORCE_WINDOW_CLOSE]
TRIGGER [AT_ONCE | WINDOW_CLOSE | MAX_DELAY time | FORCE_WINDOW_CLOSE | CONTINUOUS_WINDOW_CLOSE [recalculate rec_time_val] ]
WATERMARK time
IGNORE EXPIRED [0|1]
DELETE_MARK time
FILL_HISTORY [0|1]
FILL_HISTORY [0|1] [ASYNC]
IGNORE UPDATE [0|1]
}
@ -101,6 +101,13 @@ PARTITION 子句中，为 tbname 定义了一个别名 tname， 在 PARTITION
通过启用 fill_history 选项，创建的流计算任务将具备处理创建前、创建过程中以及创建后写入的数据的能力。这意味着，无论数据是在流创建之前还是之后写入的，都将纳入流计算的范围，从而确保数据的完整性和一致性。这一设置为用户提供了更大的灵活性，使其能够根据实际需求灵活处理历史数据和新数据。
注意：
- 开启 fill_history 时，创建流需要找到历史数据的分界点，如果历史数据很多，可能会导致创建流任务耗时较长，此时可以通过 fill_history 1 async（v3.3.6.0 开始支持） 语法将创建流的任务放在后台处理，创建流的语句可立即返回，不阻塞后面的操作。async 只对 fill_history 1 起效，fill_history 0 时建流很快，不需要异步处理。
- 通过 show streams 可查看后台建流的进度（ready 状态表示成功，init 状态表示正在建流，failed 状态表示建流失败，失败时 message 列可以查看原因。对于建流失败的情况可以删除流重新建立）。
- 另外，不要同时异步创建多个流，可能由于事务冲突导致后面创建的流失败。
比如，创建一个流，统计所有智能电表每 10s 产生的数据条数，并且计算历史数据。SQL 如下：
```sql
create stream if not exists count_history_s fill_history 1 into count_history as select count(*) from power.meters interval(10s)
@ -124,7 +131,12 @@ create stream if not exists count_history_s fill_history 1 into count_history as
1. AT_ONCE：写入立即触发。
2. WINDOW_CLOSE：窗口关闭时触发（窗口关闭由事件时间决定，可配合 watermark 使用）。
3. MAX_DELAY time：若窗口关闭，则触发计算。若窗口未关闭，且未关闭时长超过 max delay 指定的时间，则触发计算。
4. FORCE_WINDOW_CLOSE：以操作系统当前时间为准，只计算当前关闭窗口的结果，并推送出去。窗口只会在被关闭的时刻计算一次，后续不会再重复计算。该模式当前只支持 INTERVAL 窗口（不支持滑动）；FILL_HISTORY必须为 0，IGNORE EXPIRED 必须为 1，IGNORE UPDATE 必须为 1；FILL 只支持 PREV 、NULL、 NONE、VALUE。
4. FORCE_WINDOW_CLOSE：以操作系统当前时间为准，只计算当前关闭窗口的结果，并推送出去。窗口只会在被关闭的时刻计算一次，后续不会再重复计算。该模式当前只支持 INTERVAL 窗口（支持滑动）；该模式时，FILL_HISTORY 自动设置为 0，IGNORE EXPIRED 自动设置为 1，IGNORE UPDATE 自动设置为 1；FILL 只支持 PREV 、NULL、 NONE、VALUE。
- 该模式可用于实现连续查询，比如，创建一个流，每隔 1s 查询一次过去 10s 窗口内的数据条数。SQL 如下：
```sql
create stream if not exists continuous_query_s trigger force_window_close into continuous_query as select count(*) from power.meters interval(10s) sliding(1s)
```
5. CONTINUOUS_WINDOW_CLOSE：窗口关闭时输出结果。修改、删除数据，并不会立即触发重算，每等待 rec_time_val 时长，会进行周期性重算。如果不指定 rec_time_val，那么重算周期是 60 分钟。如果重算的时间长度超过 rec_time_val，在本次重算后，自动开启下一次重算。该模式当前只支持 INTERVAL 窗口。如果使用 FILL，需要配置 adapter的相关信息：adapterFqdn、adapterPort、adapterToken。adapterToken 为 `{username}:{password}` 经过 Base64 编码之后的字符串，例如 `root:taosdata` 编码后为 `cm9vdDp0YW9zZGF0YQ==`。
窗口关闭是由事件时间决定的，如事件流中断、或持续延迟，此时事件时间无法更新，可能导致无法得到最新的计算结果。

50
docs/zh/06-advanced/05-data-in/07-mqtt.mdx
View File

@ -37,6 +37,14 @@ TDengine 可以通过 MQTT 连接器从 MQTT 代理订阅数据并将其写入 T
在 **MQTT 端口** 中填写 MQTT 代理的端口，例如：`1883`
在 **TLS 校验** 中选择 TLS 证书的校验方式
1. 不开启：表示不进行 TLS 证书认证。在连接 MQTT 时，会先进行 TCP 连接，如果连接失败，会进行无证书认证模式的 TLS 连接。
2. 单向认证：开启 TLS 连接，并验证服务端证书，此时需要上传 CA 证书。
3. 双向认证：开启 TLS 连接，并与服务端进行双向认证，此时需要上传 CA 证书，客户端证书以及客户端密钥。
在 **用户** 中填写 MQTT 代理的用户名。
在 **密码** 中填写 MQTT 代理的密码。
@ -44,13 +52,7 @@ TDengine 可以通过 MQTT 连接器从 MQTT 代理订阅数据并将其写入 T
![mqtt-03.png](./mqtt-03.png)
### 4. 配置 SSL 证书
如果 MQTT 代理使用了 SSL 证书，需要在 **SSL证书** 中上传证书文件。
![mqtt-04.png](./mqtt-04.png)
### 5. 配置采集信息
### 4. 配置采集信息
在 **采集配置** 区域填写采集任务相关的配置参数。
@ -65,6 +67,8 @@ TDengine 可以通过 MQTT 连接器从 MQTT 代理订阅数据并将其写入 T
在 **订阅主题及 QoS 配置** 中填写要消费的 Topic 名称和 QoS。使用如下格式设置： `{topic_name}::{qos}`（如：`my_topic::0`）。MQTT 协议 5.0 支持共享订阅，可以通过多个客户端订阅同一个 Topic 实现负载均衡，使用如下格式： `$share/{group_name}/{topic_name}::{qos}`，其中，`$share` 是固定前缀，表示启用共享订阅，`group_name` 是分组名称，类似 kafka 的消费者组。
在 **主题解析** 中填写 MQTT 主题解析规则，格式与 MQTT Topic 相同，将 MQTT Topic 各层级内容解析为对应变量名，`_` 表示解析时忽略当前层级。例如：MQTT Topic `a/+/c` 对应解析规则如果设置为 `v1/v2/_`，代表将第一层级的 `a` 赋值给变量 `v1`，第二层级的值（这里通配符 `+` 代表任意值）复制给变量 `v2`，第三层级的值 `c` 忽略，不会赋值给任何变量。在下方的 `payload 解析` 中，Topic 解析得到的变量同样可以参与各种转换和计算。
在 **数据压缩** 中，配置消息体压缩算法，taosX 在接收到消息后，使用对应的压缩算法对消息体进行解压缩获取原始数据。可选项 none(不压缩), gzip, snappy, lz4 和 zstd，默认为 none。
在 **字符编码** 中，配置消息体编码格式，taosX 在接收到消息后，使用对应的编码格式对消息体进行解码获取原始数据。可选项 UTF_8, GBK, GB18030, BIG5，默认为 UTF_8
@ -73,13 +77,13 @@ TDengine 可以通过 MQTT 连接器从 MQTT 代理订阅数据并将其写入 T
![mqtt-05.png](./mqtt-05.png)
### 6. 配置 MQTT Payload 解析
### 5. 配置 MQTT Payload 解析
在 **MQTT Payload 解析** 区域填写 Payload 解析相关的配置参数。
taosX 可以使用 JSON 提取器解析数据，并允许用户在数据库中指定数据模型，包括，指定表名称和超级表名，设置普通列和标签列等。
#### 6.1 解析
#### 5.1 解析
有三种获取示例数据的方法：
@ -110,7 +114,7 @@ json 数据支持 JSONObject 或者 JSONArray，使用 json 解析器可以解
![mqtt-07.png](./mqtt-07.png)
#### 6.2 字段拆分
#### 5.2 字段拆分
在 **从列中提取或拆分** 中填写从消息体中提取或拆分的字段，例如：将 message 字段拆分成 `message_0` 和 `message_1` 这2 个字段，选择 split 提取器，seperator 填写 -, number 填写 2。
@ -124,7 +128,7 @@ json 数据支持 JSONObject 或者 JSONArray，使用 json 解析器可以解
![mqtt-09.png](./mqtt-09.png)
#### 6.3 数据过滤
#### 5.3 数据过滤
在 **过滤** 中，填写过滤条件，例如：填写`id != 1`，则只有 id 不为 1 的数据才会被写入 TDengine。
@ -136,9 +140,13 @@ json 数据支持 JSONObject 或者 JSONArray，使用 json 解析器可以解
![mqtt-11.png](./mqtt-11.png)
#### 6.4 表映射
#### 5.4 表映射
在 **目标超级表** 的下拉列表中选择一个目标超级表，也可以先点击右侧的 **创建超级表** 按钮
在 **目标超级表** 的下拉列表中选择一个目标超级表，也可以先点击右侧的 **创建超级表** 按钮创建新的超级表。
当超级表需要根据消息动态生成时，可以选择 **创建模板**。其中，超级表名称，列名，列类型等均可以使用模板变量，当接收到数据后，程序会自动计算模板变量并生成对应的超级表模板，当数据库中超级表不存在时，会使用此模板创建超级表；对于已创建的超级表，如果缺少通过模板变量计算得到的列，也会自动创建对应列。
![mqtt-17.png](./mqtt-17.png)
在 **映射** 中，填写目标超级表中的子表名称，例如：`t_{id}`。根据需求填写映射规则，其中 mapping 支持设置缺省值。
@ -148,7 +156,17 @@ json 数据支持 JSONObject 或者 JSONArray，使用 json 解析器可以解
![mqtt-13.png](./mqtt-13.png)
### 7. 高级选项
如果超级表列为模板变量，在子表映射时会进行 pivot 操作，其中模板变量的值展开为列名，列的值为对应的映射列
例如：
![mqtt-18.png](./mqtt-18.png)
预览结果为：
![mqtt-19.png](./mqtt-19.png)
### 6. 高级选项
在 **消息等待队列大小** 中填写接收 MQTT 消息的缓存队列大小，当队列满时，新到达的数据会直接丢弃。可设置为 0，即不缓存。
@ -166,12 +184,12 @@ json 数据支持 JSONObject 或者 JSONArray，使用 json 解析器可以解
![mqtt-14](./mqtt-14.png)
### 8. 异常处理策略
### 7. 异常处理策略
import Contributing from './_03-exception-handling-strategy.mdx'
<Contributing />
### 9. 创建完成
### 8. 创建完成
点击 **提交** 按钮，完成创建 MQTT 到 TDengine 的数据同步任务，回到**数据源列表**页面可查看任务执行情况。

24
docs/zh/06-advanced/05-data-in/_03-exception-handling-strategy.mdx
View File

@ -9,9 +9,15 @@
> 丢弃：将异常数据忽略，不写入目标库
> 报错：任务报错
- **目标库连接超时** 目标库连接失败，可选处理策略：归档、丢弃、报错、缓存
> 缓存：当目标库状态异常（连接错误或资源不足等情况）时写入缓存文件（默认路径为 `${data_dir}/tasks/_id/.datetime`），目标库恢复正常后重新入库
- **目标库不存在** 写入报错目标库不存在，可选处理策略：归档、丢弃、报错
- **表不存在** 写入报错表不存在，可选处理策略：归档、丢弃、报错、自动建表
> 自动建表：自动建表，建表成功后重试
- **主键时间戳溢出** 检查数据中第一列时间戳是否在正确的时间范围内（now - keep1, now + 100y），可选处理策略：归档、丢弃、报错
- **主键时间戳空** 检查数据中第一列时间戳是否为空，可选处理策略：归档、丢弃、报错、使用当前时间
> 使用当前时间：使用当前时间填充到空的时间戳字段中
- **复合主键空** 写入报错复合主键空，可选处理策略：归档、丢弃、报错
- **表名长度溢出** 检查子表表名的长度是否超出限制（最大 192 字符），可选处理策略：归档、丢弃、报错、截断、截断且归档
> 截断：截取原始表名的前 192 个字符作为新的表名
> 截断且归档：截取原始表名的前 192 个字符作为新的表名，并且将此行记录写入归档文件
@ -20,4 +26,20 @@
- **表名模板变量空值** 检查子表表名模板中的变量是否为空，可选处理策略：丢弃、留空、变量替换为指定字符串
> 留空：变量位置不做任何特殊处理，例如 `a_{x}` 转换为 `a_`
> 变量替换为指定字符串：变量位置使用后方输入框中的指定字符串，例如 `a_{x}` 转换为 `a_b`
- **列名长度溢出** 检查列名的长度是否超出限制（最大 64 字符），可选处理策略：归档、丢弃、报错
- **列名不存在** 写入报错列名不存在，可选处理策略：归档、丢弃、报错、自动增加缺失列
> 自动增加缺失列：根据数据信息，自动修改表结构增加列，修改成功后重试
- **列名长度溢出** 检查列名的长度是否超出限制（最大 64 字符），可选处理策略：归档、丢弃、报错
- **列自动扩容** 开关选项，打开时，列数据长度超长时将自动修改表结构并重试
- **列长度溢出** 写入报错列长度溢出，可选处理策略：归档、丢弃、报错、截断、截断且归档
> 截断：截取数据中符合长度限制的前 n 个字符
> 截断且归档：截取数据中符合长度限制的前 n 个字符，并且将此行记录写入归档文件
- **数据异常** 其他数据异常（未在上方列出的其他异常）的处理策略，可选处理策略：归档、丢弃、报错
- **连接超时** 配置目标库连接超时时间，单位“秒”取值范围 1~600
- **临时存储文件位置** 配置缓存文件的位置，实际生效位置 `$DATA_DIR/tasks/:id/{location}`
- **归档数据保留天数** 非负整数，0 表示无限制
- **归档数据可用空间** 0~65535，其中 0 表示无限制
- **归档数据文件位置** 配置归档文件的位置，实际生效位置 `$DATA_DIR/tasks/:id/{location}`
- **归档数据失败处理策略** 当写入归档文件报错时的处理策略，可选处理策略：删除旧文件、丢弃、报错并停止任务
> 删除旧文件：删除旧文件，如果删除旧文件后仍然无法写入，则报错并停止任务
> 丢弃：丢弃即将归档的数据
> 报错并停止任务：报错并停止当前任务

6
docs/zh/06-advanced/05-data-in/index.md
View File

@ -152,7 +152,11 @@ let v3 = data["voltage"].split(",");
使用 json 规则解析出的电压是字符串表达的带单位形式，最终入库希望能使用 int 类型记录电压值和电流值，便于统计分析，此时就需要对电压进一步拆分；另外日期期望拆分为日期和时间入库。
如下图所示可以对源字段`ts`使用 split 规则拆分成日期和时间，对字段`voltage`使用 regex 提取出电压值和电压单位。split 规则需要设置**分隔符**和**拆分数量**，拆分后的字段命名规则为`{原字段名}_{顺序号}`，Regex 规则同解析过程中的一样，使用**命名捕获组**命名提取字段。
如下图所示
* 对字段 `ts` 使用 split 规则拆分成日期和时间。split 规则需要设置 **分隔符** 和 **拆分数量**，拆分后的字段命名规则为 `{原字段名}_{顺序号}`。
* 对字段 `voltage` 使用正则表达式 `^(?<voltage>[0-9]+)(?<voltage_unit>[a-zA-Z]+)$` 提取出电压值和电压单位，Regex 规则同解析过程中的一样，使用 **命名捕获组** 命名提取字段。
* 对字段 `location` 使用 convert 转换，填写一个 JSON map 对象，其中 key 为字段 `current` 的值，`value` 为转换后的值。如图，`location` 字段的值 `"beijing.chaoyang.datun"` 被转换为 `"beijing.chaoyang.datunludong"`。
![拆分和提取](./pic/transform-04.png)

BIN
docs/zh/06-advanced/05-data-in/mqtt-03.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 30 KiB

After

Width:  |  Height:  |  Size: 37 KiB

BIN
docs/zh/06-advanced/05-data-in/mqtt-04.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 24 KiB

BIN
docs/zh/06-advanced/05-data-in/mqtt-05.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 53 KiB

After

Width:  |  Height:  |  Size: 60 KiB

BIN
docs/zh/06-advanced/05-data-in/mqtt-17.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

BIN
docs/zh/06-advanced/05-data-in/mqtt-18.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

BIN
docs/zh/06-advanced/05-data-in/mqtt-19.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
docs/zh/06-advanced/05-data-in/pic/exception-handling-strategy.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 43 KiB

After

Width:  |  Height:  |  Size: 98 KiB

BIN
docs/zh/06-advanced/05-data-in/pic/transform-04.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 56 KiB

After

Width:  |  Height:  |  Size: 170 KiB

98
docs/zh/06-advanced/06-TDgpt/01-introduction.md Normal file
View File

@ -0,0 +1,98 @@
---
sidebar_label: TDgpt 技术内幕
title: TDgpt 技术内幕
---
import TDgpt from './pic/data-analysis.png';
# 背景介绍
针对时间序列数据预测分析、异常检测、数据补全和数据分类的应用领域，相关领域的研究人员提出并开发出了众多不同技术特点、适用于不同场景的时序数据分析算法，广泛应用在时间序列数据预测、异常检测等领域。
分析算法通常以高级编程语言（Python 语言或 R 语言）工具包的形式存在，并通过开源的方式广泛分发和使用，这种应用模式极大地便利了软件开发人员在应用系统中调用复杂的分析算法，极大地降低了使用高级算法的门槛。
另一方面，数据库系统研发人员也尝试将数据分析算法模型整合到数据库系统中，通过建立 Machine Learning 库（例如 Spark 的机器学习库）充分利用成熟分析技术增强数据库或分析计算引擎的高级数据分析能力。
飞速发展的人工智能（AI）为时序数据分析应用带来的新机遇，快速有效地将 AI 能力应用在时间序列数据分析领域也为数据库。为此，涛思数据创新性地提出了时序数据分析智能体 TDgpt，使用 TDgpt，将您能够通过 SQL 语句，直接调用适配和整合驱动统计分析算法、机器学习算法模型、深度学习模型，时序数据基础模型以及大语言模型，并将这些分析能力转化为 SQL 语句的调用，通过异常检测窗口和预测函数的方式应用在时序数据上。
# 技术特点
TDgpt 是与 TDengine 主进程 taosd 适配的外置式时序数据分析智能体，能够将时序数据分析服务无缝集成在 TDengine 的查询执行流程中。
TDgpt 是一个无状态的平台，其内置了经典的统计分析模型库 Statsmodel，内嵌了 torch/Keras 等机器/深度学习框架库，此外还通过请求转发和适配的方式直接调用涛思数据自研的时序数据基础大模型 TDtsfm (TDengine time series foundation model)。
作为一个分析智能体，TDgpt 后续还将整合第三方时序数据 MaaS 大模型服务，仅修改一个参数（algo）就能够调用最先进的时间序列模型服务。
TDgpt 是一个开放的系统，用户能够根据自己的需要，添加预测分析、异常检测、数据补全、数据分类算法，添加完成后，仅通过修改 SQL 语句中调用的算法参数就能够无缝使用新加入的算法。
无需应用修改一行代码。
# 系统架构
TDgpt 由若干个无状态的分析节点 anode 构成，可以按需在系统集群中部署 Anode 节点，也可以根据分析模型算法的特点，将 Anode 部署在合适的硬件环境中，例如带有 GPU 的计算节点。
TDgpt 针对不同的分析算法，提供统一的调用接口和调用方式，根据用户请求的参数，调用高级分析算法包及其他的分析工具，并将分析获得的结果按照约定的方式返回给 TDengine 的主进程 taosd。
TDgpt 的主要包含四个部分的内容。
- 第一部分是内置分析库，包括 statsmodels, pyculiarity, pmdarima 等，提供可以直接调用的预测分析和异常检测算法模型。
- 第二部分是内置的机器学习库（包括：torch,keras,scikit-learn等），用于驱动预训练完成的机器（深度）学习模型在 TDgpt 的进程空间内运行。预训练的流程可以使用 Merlion/Kats 等 开源的端到端机器学习框架进行管理，并将完成训练的模型上传到 TDgpt 指定目录即可;
- 第三部分是通用大语言模型的请求适配模块。将时序数据预测请求转换后，基于 Prompt 向 DeepSeek、LlaMa 等通用大语言模型 MaaS 请求服务（这部分功能暂未开源）；
- 第四部分是通过 Adapter 直接向本地部署的 Time-MoE、TDtsfm 等时序数据模型请求服务。时序数据专用模型相对于通用语言大模型，无需 Prompt，更加便捷轻量，本地应用部署对硬件资源要求也较低；除此之外，Adapter 还可以直接请求 TimeGPT 这种类型的时序数据分析 MaaS 服务，调用云端的时序模型服务提供本地化时序数据分析能力。
<img src={TDgpt} alt="TDgpt架构图" />
查询过程中，TDengine 中的Vnode 会将涉及时序数据高级分析的部分直接转发到 Anode，并等待分析完成后将结果组装完成，嵌入查询执行流程。
# 时序数据分析服务
使用TDgpt 提供的时序数据分析服务，包括：
- 时序数据异常检测：TDengine 中定义了新的时间窗口——异常（状态）窗口——来提供异常检测服务。异常窗口可以视为一种特殊的事件窗口（Event Window），即异常检测算法确定的连续异常时间序列数据所在的时间窗口。与普通事件窗口区别在于——时间窗口的起始时间和结束时间均是分析算法确定，不是用户指定的表达式判定。异常窗口使用方式与其他类型的时间窗口（例如状态窗口、会话窗口等）类似。因此时间窗口内可使用的查询操作均可应用在异常窗口上。
- 时序数据分析预测：TDengine 中提供了一个新的函数FORECAST提供时序数据预测服务，基于输入的（历史）时间序列数据调用指定（或默认）预测算法给出输入时序数据后续时间序列的预测数据。
- 时序数据补全：研发测试中，2025 年 7 月发布
- 时序数据分类：研发测试中，2025 年 7 月发布
# 自定义分析算法
TDgpt 是一个可扩展的时序数据高级分析智能体，用户遵循 [算法开发者指南](./dev)中的简易步骤就能将自己开发的分析算法添加到系统中。之后应用可以通过 SQL 语句直接调用, 让高级分析算法的使用门槛降到几乎为零。对于新引入的算法或模型，应用不用做任何调整。
TDpgt 只支持使用 Python 语言开发的分析算法。Anode 采用 Python 类动态加载模式，在启动的时候扫描特定目录内满足约定条件的所有代码文件，并将其加载到系统中。因此，开发者只需要遵循以下几步就能完成新算法的添加工作：
1. 开发完成符合要求的分析算法类
2. 将代码文件放入对应目录，然后重启 Anode
3. 使用SQL命令更新算法缓存列表即可。
添加完成的算法在刷新算法列表后，立即使用 SQL 语句进行调用。
# 算法评估工具
在 TDgpt 企业版中，还提供针对多种算法模型有效性的综合评估工具。该工具可以针对 TDgpt 可调用所有时序数据分析（预测分析与异常检测）服务，包括内置数据分析算法模型，已部署的预训练机器学习模型、第三方时序数据（大）模型服务，基于 TDengine 中的时序数据进行预测分析对比和异常检测对比评估，并给出量化指标评估不同分析模型在给定数据集上准确度及性能。
# 模型管理
对于 Torch/Tensorflow/Keras 等机器学习库框架驱动的预训练模型，需要首先将训练完成的数据模型添加到 Anode 的指定目录中，Anode 可以自动调用该目录内的模型，驱动其运行并提供服务。
企业版本的 TDgpt 具备模型的管理能力，能够与开源的端到端时序数据机器学习框架（例如：Merlion、Kats 等）无缝集成。
处理能力
通常意义上，时间序列数据分析主要是计算密集型任务。这种计算密集型任务，可以使用更高性能的 CPU 或 GPU 来提升处理性能。
如果是机器/深度学习模型，依赖于 torch 库驱动其运行，可以采用标准的提升分析处理能力的方案来提升 TDgpt 的服务能力，例如将 Anode 部署在内存更大，并具有 GPU 的服务器之上，使用可调用 GPU 的 torch 库驱动模型运行，以提升分析响应能力。
不同的模型、算法可以部署在不同的 Anode 上，增加并行的处理能力。
# 运营维护
开源版本不提供用户权限和资源控制机制。
TDgpt 默认使用 uWSGI 驱动的 flask 服务，可以通过打开 uwsgi 的端口监控服务的运行状态。
# 参考文献
[1] Merlion：https://opensource.salesforce.com/Merlion/latest/index.html
[2] Kats:https://facebookresearch.github.io/Kats/
[3] StatsModels: https://www.statsmodels.org/stable/index.html
[4] Keras:https://keras.io/guides/
[5] Torch:https://pytorch.org/
[6] Scikit-learn:https://scikit-learn.org/stable/index.html
[7] Time-MoE:https://github.com/Time-MoE/Time-MoE
[8] TimeGPT:https://docs.nixtla.io/docs/getting-started-about_timegpt
[9] DeepSeek:https://www.deepseek.com/
[10] LlaMa:https://www.llama.com/docs/overview/
[11] Spark MLlib:https://spark.apache.org/docs/latest/ml-guide.html

37
docs/zh/06-advanced/06-TDgpt/02-management.md
View File

@ -5,14 +5,41 @@ sidebar_label: "安装部署"
### 环境准备
使用 TDgpt 的高级时序数据分析功能需要在 TDengine 集群中安装部署 AI node（Anode）。Anode 运行在 Linux 平台上，并需要 3.10 或以上版本的 Python 环境支持。
> 部署 Anode 需要 TDengine Enterprise 3.3.4.3 及以后版本，请首先确认搭配 Anode 使用的 TDengine 能够支持 Anode。
> 部署 Anode 需要 TDengine 3.3.6.0 及以后版本，请首先确认搭配 Anode 使用的 TDengine 能够支持 Anode。
可以使用以下的命令在 Ubuntu Linux 上安装 Python 3.10 环境
#### 安装 Python
```shell
sudo apt-get install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.10
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 2
sudo update-alternatives --config python3
sudo apt install python3.10-venv
sudo apt install python3.10-dev
```
#### 安装 Pip
```shell
curl -sS https://bootstrap.pypa.io/get-pip.py | python3.10
```
####
将 `~/.local/bin` 路径添加到环境变量中 `~/.bashrc or ~/.bash_profile`
```shell
export PATH=$PATH:~/.local/bin
```
至此 Python 环境准备完成，可以进行 taosanode 的安装和部署。
### 安装及卸载
使用 Linux 环境下的安装包 TDengine-enterprise-anode-1.x.x.tar.gz 可进行 Anode 的安装部署工作，命令如下：
使用 Linux 环境下的安装包 TDengine-anode-3.3.x.x-Linux-x64.tar.gz 可进行 Anode 的安装部署工作，命令如下：
```bash
tar -xzvf TDengine-enterprise-anode-1.0.0.tar.gz
cd TDengine-enterprise-anode-1.0.0
tar -xzvf TDengine-anode-3.3.6.0-Linux-x64.tar.gz
cd TDengine-anode-3.3.6.0
sudo ./install.sh
```
@ -80,7 +107,7 @@ app-log = /var/log/taos/taosanode/taosanode.app.log
model-dir = /usr/local/taos/taosanode/model/
# default log level
log-level = DEBUG
log-level = INFO
```

4
docs/zh/06-advanced/06-TDgpt/03-preprocess.md
View File

@ -9,14 +9,14 @@ import wndata from './pic/white-noise-data.png'
### 分析流程
时序数据分析之前需要有预处理的过程，为减轻分析算法的负担，TDgpt 在将时序数据发给具体分析算法进行分析时，已经对数据做了预处理，整体的流程如下图所示。
<img src={activity} width="560" alt="预处理流程" />
<img src={activity} alt="预处理流程"/>
TDgpt 首先对输入数据进行白噪声检查（White Noise Data check）, 检查通过以后针对预测分析，还要进行输入（历史）数据的重采样和时间戳对齐处理（异常检测跳过数据重采样和时间戳对齐步骤）。
预处理完成以后，再进行预测或异常检测操作。预处理过程不属于预测或异常检测处理逻辑的一部分。
### 白噪声检查
<img src={wndata} width="430" alt="white-noise-data"/>
<img src={wndata} alt="white-noise-data"/>
白噪声时序数据可以简单地认为是随机数构成的时间数据序列（如上图所示的正态分布随机数序列），随机数构成的时间序列没有分析的价值，因此会直接返回。白噪声检查采用经典的 `Ljung-Box` 统计量检验，计算 `Ljung-Box` 统计量需遍历整个输入时间序列。如果用户能够明确输入序列一定不是白噪声序列，那么可以在参数列表中增加参数 `wncheck=0` 强制要求分析平台忽略白噪声检查，从而节省计算资源。
TDgpt 暂不提供独立的时间序列白噪声检测功能。

31
docs/zh/06-advanced/06-TDgpt/04-forecast/04-lstm.md Normal file
View File

@ -0,0 +1,31 @@
---
title: "LSTM"
sidebar_label: "LSTM"
---
本节说明 LSTM 模型的使用方法。
## 功能概述
LSTM 模型即长短期记忆网络(Long Short Term Memory)，是一种特殊的循环神经网络，适用于处理时间序列数据、自然语言处理等任务，通过其独特的门控机制，能够有效捕捉长期依赖关系，
解决传统 RNN 的梯度消失问题，从而对序列数据进行准确预测，不过它不直接提供计算的置信区间范围结果。
完整的调用 SQL 语句如下：
```SQL
SELECT _frowts, FORECAST(i32, "algo=lstm,alpha=95,period=10,start_p=1,max_p=5,start_q=1,max_q=5") from foo
```
```json5
{
"rows": fc_rows, // 返回结果的行数
"period": period, // 返回结果的周期性，同输入
"alpha": alpha, // 返回结果的置信区间，同输入
"algo": "lstm", // 返回结果使用的算法
"mse": mse, // 拟合输入时间序列时候生成模型的最小均方误差(MSE)
"res": res // 列模式的结果
}
```
### 参考文献
- [1] Hochreiter S. Long Short-term Memory[J]. Neural Computation MIT-Press, 1997.

35
docs/zh/06-advanced/06-TDgpt/04-forecast/05-mlp.md Normal file
View File

@ -0,0 +1,35 @@
---
title: "MLP"
sidebar_label: "MLP"
---
本节说明 MLP 模型的使用方法。
## 功能概述
MLP（MutiLayers Perceptron，多层感知机）是一种典的神经网络模型，能够通过学习历史数据的非线性关系，
捕捉时间序列中的模式并进行未来值预测。它通过多层全连接网络进行特征提取和映射，
对输入的历史数据生成预测结果。由于不直接考虑趋势或季节性变化，通常需要结合数据预处理来提升效果，
适合解决非线性和复杂的时间序列问题。
完整的调用SQL语句如下：
```SQL
SELECT _frowts, FORECAST(i32, "algo=mlp") from foo
```
```json5
{
"rows": fc_rows, // 返回结果的行数
"period": period, // 返回结果的周期性，同输入
"alpha": alpha, // 返回结果的置信区间，同输入
"algo": "mlp", // 返回结果使用的算法
"mse": mse, // 拟合输入时间序列时候生成模型的最小均方误差(MSE)
"res": res // 列模式的结果
}
```
### 参考文献
- [1]Rumelhart D E, Hinton G E, Williams R J. Learning representations by back-propagating errors[J]. nature, 1986, 323(6088): 533-536.
- [2]Rosenblatt F. The perceptron: a probabilistic model for information storage and organization in the brain[J]. Psychological review, 1958, 65(6): 386.
- [3]LeCun Y, Bottou L, Bengio Y, et al. Gradient-based learning applied to document recognition[J]. Proceedings of the IEEE, 1998, 86(11): 2278-2324.

98
docs/zh/06-advanced/06-TDgpt/04-forecast/index.md
View File

@ -3,19 +3,18 @@ title: 预测算法
description: 预测算法
---
import fc_result from '../pic/fc.png';
import fc_result_figure from '../pic/fc-result.png';
import fc_result from '../pic/fc-result.png';
时序数据预测处理以持续一个时间段的时序数据作为输入，预测接下来一个连续时间区间内时间序列数据趋势。用户可以指定输出的（预测）时间序列数据点的数量，因此其输出的结果行数不确定。为此，TDengine 使用新 SQL 函数 `FORECAST` 提供时序数据预测服务。基础数据（用于预测的历史时间序列数据）是该函数的输入，预测结果是该函数的输出。用户可以通过 `FORECAST` 函数调用 Anode 提供的预测算法提供的服务。
时序数据预测处理以持续一个时间段的时序数据作为输入，预测接下来一个连续时间区间内时间序列数据趋势。用户可以指定输出的（预测）时间序列数据点的数量，因此其输出的结果行数不确定。为此，TDengine 引入新 SQL 函数 `FORECAST` 提供预测分析功能。基础数据（用于预测的历史时间序列数据）是该函数的输入，预测结果是该函数的输出。用户可以通过 `FORECAST` 函数调用 Anode 提供的预测算法提供的服务。预测分析通常只能针对超级表的子表或者不同表中同一个时间序列。
在后续章节中，使用时序数据表`foo`作为示例，介绍预测和异常检测算法的使用方式，`foo` 表的模式如下：
在后续章节中，使用时序数据表 `foo` 作为示例，介绍预测和异常检测算法的使用方式，`foo` 表的模式如下：
|列名称|类型|说明|
|---|---|---|
|ts| timestamp| 主时间戳列|
|i32| int32| 4字节整数，设备测量值 metric|
| 列名称 | 类型 | 说明 |
| ------ | --------- | ---------------------------- |
| ts | timestamp | 主时间戳列 |
| i32 | int32 | 4字节整数，设备测量值 metric |
```bash
```sql
taos> select * from foo;
ts | i32 |
========================================
@ -30,6 +29,7 @@ taos> select * from foo;
```
### 语法
```SQL
FORECAST(column_expr, option_expr)
@ -42,26 +42,29 @@ algo=expr1
[,start=start_ts_val]
[,expr2]
"}
```
1. `column_expr`：预测的时序数据列，只支持数值类型列输入。
2. `options`：预测函数的参数。字符串类型，其中使用 K=V 方式调用算法及相关参数。采用逗号分隔的 K=V 字符串表示，其中的字符串不需要使用单引号、双引号、或转义号等符号，不能使用中文及其他宽字符。预测支持 `conf`, `every`, `rows`, `start`, `rows` 几个控制参数，其含义如下：
### 参数说明
|参数|含义|默认值|
|---|---|---|
|algo|预测分析使用的算法|holtwinters|
|wncheck|白噪声（white noise data）检查|默认值为 1，0 表示不进行检查|
|conf|预测数据的置信区间范围 ，取值范围 [0, 100]|95|
|every|预测数据的采样间隔|输入数据的采样间隔|
|start|预测结果的开始时间戳|输入数据最后一个时间戳加上一个采样间隔时间区间|
|rows|预测结果的记录数|10|
| 参数 | 含义 | 默认值 |
| ------- | ------------------------------------------ | ---------------------------------------------- |
| algo | 预测分析使用的算法 | holtwinters |
| wncheck | 白噪声（white noise data）检查 | 默认值为 1，0 表示不进行检查 |
| conf | 预测数据的置信区间范围 ，取值范围 [0, 100] | 95 |
| every | 预测数据的采样间隔 | 输入数据的采样间隔 |
| start | 预测结果的开始时间戳 | 输入数据最后一个时间戳加上一个采样间隔时间区间 |
| rows | 预测结果的记录数 | 10 |
1. 预测查询结果新增三个伪列，具体如下：`_FROWTS`：预测结果的时间戳、`_FLOW`：置信区间下界、`_FHIGH`：置信区间上界, 对于没有置信区间的预测算法，其置信区间同预测结果
2. 更改参数 `START`：返回预测结果的起始时间，改变起始时间不会影响返回的预测数值，只影响起始时间。
3. `EVERY`：可以与输入数据的采样频率不同。采样频率只能低于或等于输入数据采样频率，不能**高于**输入数据的采样频率。
4. 对于某些不需要计算置信区间的算法，即使指定了置信区间，返回的结果中其上下界退化成为一个点。
5. rows 的最大输出值是 1024，即只能预测 1024 个值。超过输出范围的参数会被自动设置为 1024。
6. 预测分析的输入数据行数最大值是 40000 行，即用于预测分析的历史数据不能超过 40000 行。针对部分分析模型，输入限制更严格。
### 示例
@ -74,7 +77,8 @@ FROM foo;
SELECT _flow, _fhigh, _frowts, FORECAST(i32, "algo=arima,alpha=95,period=10,wncheck=0")
FROM foo;
```
```
```sql
taos> select _flow, _fhigh, _frowts, forecast(i32) from foo;
_flow | _fhigh | _frowts | forecast(i32) |
========================================================================================
@ -90,8 +94,8 @@ taos> select _flow, _fhigh, _frowts, forecast(i32) from foo;
-1076.1566162 | 1214.4498291 | 2020-01-01 00:01:44.000 | 69 |
```
## 内置预测算法
- [arima](./02-arima.md)
- [holtwinters](./03-holtwinters.md)
- CES (Complex Exponential Smoothing)
@ -111,7 +115,10 @@ taos> select _flow, _fhigh, _frowts, forecast(i32) from foo;
- TimesNet
## 算法有效性评估工具
TDgpt 提供预测分析算法有效性评估工具 `analytics_compare`，调用该工具并设置合适的参数，能够使用 TDengine 中的数据作为回测依据，评估不同预测算法或相同的预测算法在不同的参数或训练模型的下的预测有效性。预测有效性的评估使用 `MSE` 和 `MAE` 指标作为依据，后续还将增加 `MAPE`指标。
TDgpt 在企业版中提供预测分析算法有效性评估工具 `analytics_compare`，调用该工具并设置合适的参数，能够使用 TDengine 中已经保存的数据作为回测依据，评估不同预测算法或训练模型的预测有效性。预测有效性的评估使用 `MSE` 指标作为依据，后续还将增加 `MAPE` 和 `MAE` 指标。
使用评估工具，需要在配置文件`` 中设置正确的参数，包括选取评估的数据范围，结果输出时间，参与评估的算法、算法相应的参数、是否生成预测结果图等配置信息。
```ini
[forecast]
@ -134,12 +141,55 @@ res_start_time = 1730000000000
gen_figure = true
```
算法对比分析运行完成以后，生成 fc-results.xlsx 文件，其中包含了调用算法的预测分析误差、执行时间、调用参数等信息。如下图所示：
在具备完备的 Python 库的运行环境中，通过 `shell` 调用 TDgpt 安装路径下的 misc 中 `analytics_compare` 的命令即可。可以按照如下方式体验算法有效性评估工具：
1. 在配置文件 `analytics.ini` 配置文件中设置 `taosd` 服务的连接信息，包括 主机地址、配置文件路径、用户名、登录密码等信息。
```ini
[taosd]
# taosd 服务主机名
host = 127.0.0.1
<img src={fc_result} width="760" alt="预测对比结果" />
# 登录用户名
user = root
# 登录密码
password = taosdata
# 配置文件路径
conf = /etc/taos/taos.cfg
[input_data]
# 用于预测评估的数据库名称
db_name = test
# 读取数据的表名称
table_name = passengers
# 读取列名称
column_name = val, _c0
```
2. 准备数据。
我们在 TDgpt 安装目录下的 `resource` 文件夹中准备了一个样例数据 `sample-fc.sql`, 执行以下命令即可见示例数据写入到数据库：
```shell
taos -f sample-fc.sql
```
即可将示例数据写入到数据库中，以便进行后续的评估
3. 执行算法评估工具，首先需要确保激活虚拟环境并调用 taosanode 运行的虚拟环境的 Python，否则启动的时候 Python 会提示找不到所需要的依赖库。
```shell
python3.10 ./analytics_compare.py forecast
```
4. 运行完成后，在当前目录下生成 `fc_result.xlsx` 文件，此文件即为算法评估的结果文件。该文件中第一个卡片是算法运行结果（如下表所示），分别包含了算法名称、执行调用参数、均方误差、执行时间 4 个指标。
| algorithm | params | MSE | elapsed_time(ms.) |
| ----------- | ------------------------------------------------------------------------- | ------- | ----------------- |
| holtwinters | `{"trend":"add", "seasonal":"add"}` | 351.622 | 125.1721 |
| arima | `{"time_step":3600000, "start_p":0, "max_p":10, "start_q":0, "max_q":10}` | 433.709 | 45577.9187 |
如果设置了 `gen_figure` 为 true，分析结果中还会有绘制的分析预测结果图（如下图所示）。
<img src={fc_result_figure} width="760" alt="预测对比结果" />
<img src={fc_result} alt="预测对比结果"/>

4
docs/zh/06-advanced/06-TDgpt/05-anomaly-detection/04-machine-learning.md
View File

@ -3,7 +3,9 @@ title: "机器学习算法"
sidebar_label: "机器学习算法"
---
Autoencoder<sup>[1]</sup>: TDgpt 内置使用自编码器（Autoencoder）的异常检测算法，对周期性的时间序列数据具有较好的检测结果。使用该模型需要针对输入时序数据进行预训练，同时将训练完成的模型保存在到服务目录 `ad_autoencoder` 中，然后在 SQL 语句中指定调用该算法模型即可使用。
Autoencoder<sup>[1]</sup>: TDgpt 内置使用自编码器（Autoencoder）的异常检测算法，
对周期性的时间序列数据具有较好的检测结果。使用该模型需要针对输入时序数据进行预训练，
同时将训练完成的模型保存在到服务目录 `ad_autoencoder` 中，然后在 SQL 语句中指定调用该算法模型即可使用。
```SQL
--- 在 options 中增加 model 的名称，ad_autoencoder_foo， 针对 foo 数据集（表）训练的采用自编码器的异常检测模型进行异常检测

31
docs/zh/06-advanced/06-TDgpt/05-anomaly-detection/index.md
View File

@ -5,7 +5,6 @@ description: 异常检测算法
import ad from '../pic/anomaly-detection.png';
import ad_result from '../pic/ad-result.png';
import ad_result_figure from '../pic/ad-result-figure.png';
TDengine 中定义了异常（状态）窗口来提供异常检测服务。异常窗口可以视为一种特殊的**事件窗口（Event Window）**，即异常检测算法确定的连续异常时间序列数据所在的时间窗口。与普通事件窗口区别在于——时间窗口的起始时间和结束时间均是分析算法识别确定，不是用户给定的表达式进行判定。因此，在 `WHERE` 子句中使用 `ANOMALY_WINDOW` 关键词即可调用时序数据异常检测服务，同时窗口伪列（`_WSTART`, `_WEND`, `_WDURATION`）也能够像其他时间窗口一样用于描述异常窗口的起始时间(`_WSTART`)、结束时间(`_WEND`)、持续时间(`_WDURATION`)。例如：
@ -18,7 +17,7 @@ ANOMALY_WINDOW(col_val, "algo=iqr");
如下图所示，Anode 将返回时序数据异常窗口 $[10:51:30, 10:53:40]$
<img src={ad} width="760" alt="异常检测" />
<img src={ad} alt="异常检测"/>
在此基础上，用户可以针对异常窗口内的时序数据进行查询聚合、变换处理等操作。
@ -40,13 +39,15 @@ algo=expr1
4. 输入数据默认进行白噪声检查，如果输入数据是白噪声，将不会有任何（异常）窗口信息返回。
### 参数说明
|参数|含义|默认值|
|---|---|---|
|algo|异常检测调用的算法|iqr|
|wncheck|对输入数据列是否进行白噪声检查，取值为0或1|1|
| 参数 | 含义 | 默认值 |
| ------- | ------------------------------------------ | ------ |
| algo | 异常检测调用的算法 | iqr |
| wncheck | 对输入数据列是否进行白噪声检查，取值为0或1 | 1 |
### 示例
```SQL
--- 使用 iqr 算法进行异常检测，检测列 i32 列。
SELECT _wstart, _wend, SUM(i32)
@ -65,11 +66,12 @@ taos> SELECT _wstart, _wend, count(*) FROM foo ANOMAYL_WINDOW(i32);
Query OK, 1 row(s) in set (0.028946s)
```
### 内置异常检测算法
分析平台内置了6个异常检查模型，分为3个类别，分别是[基于统计学的算法](./02-statistics-approach.md)、[基于数据密度的算法](./03-data-density.md)、以及[基于机器学习的算法](./04-machine-learning.md)。在不指定异常检测使用的方法的情况下，默认调用 IQR 进行异常检测。
### 异常检测算法有效性比较工具
TDgpt 提供自动化的工具对比不同数据集的不同算法监测有效性，针对异常检测算法提供查全率（recall）和查准率（precision）两个指标衡量不同算法的有效性。
通过在配置文件中(analysis.ini)设置以下的选项可以调用需要使用的异常检测算法，异常检测算法测试用数据的时间范围、是否生成标注结果的图片、调用的异常检测算法以及相应的参数。
调用异常检测算法比较之前，需要人工手动标注异常监测数据集的结果，即设置[anno_res]选项的数值，第几个数值是异常点，需要标注在数组中，如下测试集中，第 9 个点是异常点，我们就标注异常结果为 [9].
@ -93,14 +95,21 @@ anno_res = [9]
ksigma={"k": 2}
iqr={}
grubbs={}
lof={"algo":"auto", "n_neighbor": 3}
lof={"algorithm":"auto", "n_neighbor": 3}
```
对比程序执行完成以后，会自动生成名称为`ad_result.xlsx` 的文件，第一个卡片是算法运行结果（如下图所示），分别包含了算法名称、执行调用参数、查全率、查准率、执行时间 5 个指标。
对比程序执行完成以后，会自动生成名称为 `ad_result.xlsx` 的文件，第一个卡片是算法运行结果（如下表所示），分别包含了算法名称、执行调用参数、查全率、查准率、执行时间 5 个指标。
| algorithm | params | precision(%) | recall(%) | elapsed_time(ms.) |
| --------- | -------------------------------------- | ------------ | --------- | ----------------- |
| ksigma | `{"k":2}` | 100 | 100 | 0.453 |
| iqr | `{}` | 100 | 100 | 2.727 |
| grubbs | `{}` | 100 | 100 | 2.811 |
| lof | `{"algorithm":"auto", "n_neighbor":3}` | 0 | 0 | 4.660 |
<img src={ad_result} width="760" alt="异常检测对比结果" />
如果设置了 `gen_figure` 为 `true`，比较程序会自动将每个参与比较的算法分析结果采用图片方式呈现出来（如下图所示为 ksigma 的异常检测结果标注）。
<img src={ad_result_figure} width="760" alt="异常检测标注图" />
<img src={ad_result} alt="异常检测标注图"/>

1
docs/zh/06-advanced/06-TDgpt/06-dev/02-forecast.md
View File

@ -8,6 +8,7 @@ sidebar_label: "预测算法"
### 输出约定及父类属性说明
`execute` 方法执行完成后的返回一个如下字典对象， 预测返回结果如下：
```python
return {
"mse": mse, # 预测算法的拟合数据最小均方误差(minimum squared error)

6
docs/zh/06-advanced/06-TDgpt/07-imputation.md Normal file
View File

@ -0,0 +1,6 @@
---
title: "缺失数据补值"
sidebar_label: "缺失数据补值"
---
近期发布

6
docs/zh/06-advanced/06-TDgpt/08-classification.md Normal file
View File

@ -0,0 +1,6 @@
---
title: "时间序列分类"
sidebar_label: "时间序列分类"
---
近期发布

73
docs/zh/06-advanced/06-TDgpt/09-tutorial.md Normal file
View File

@ -0,0 +1,73 @@
---
title: "快速体验"
sidebar_label: "快速体验"
---
# 通过 Docker 快速体验
本节首先介绍如何通过 Docker 快速体验 TDgpt。
## 启动 TDgpt
如果已经安装了 Docker，首先拉取最新的 TDengine 容器镜像：
```shell
docker pull tdengine/tdengine:latest
```
或者指定版本的容器镜像：
```shell
docker pull tdengine/tdengine:3.3.3.0
```
然后只需执行下面的命令：
```shell
docker run -d -p 6030:6030 -p 6041:6041 -p 6043:6043 -p 6044-6049:6044-6049 -p 6044-6045:6044-6045/udp -p 6060:6060 tdengine/tdengine
```
注意：TDgpt 服务端使用 6090 TCP 端口。TDgpt 是一个无状态时序数据分析智能体，并不会在本地持久化保存数据，仅根据配置可能在本地生成运行日志。
确定该容器已经启动并且在正常运行。
```shell
docker ps
```
进入该容器并执行 `bash`
```shell
docker exec -it <container name> bash
```
然后就可以执行相关的 Linux 命令操作和访问 TDengine。
# 通过安装包快速体验
## 获取安装包
1. 从列表中下载获得 tar.gz 安装包：
2. 进入到安装包所在目录，使用 `tar` 解压安装包；
3. 进入到安装包所在目录，先解压文件后，进入子目录，执行其中的 install.sh 安装脚本。
> 请将 `<version>` 替换为下载的安装包版本
```bash
tar -zxvf TDengine-anode-<version>-Linux-x64.tar.gz
```
解压文件后，进入相应子目录，执行其中的 `install.sh` 安装脚本：
```bash
sudo ./install.sh
```
## 安装部署使用
请参考[安装部署指南](./management) 准备环境，并安装部署 TDgpt。
# 通过云服务快速体验
TDgpt 可以在 TDengine Cloud 上进行快速体验。如果您已经有云服务账号，请在数据库集市里面找到“时序数据预测分析数据集”数据库，点击启用就可以进入这个数据库，然后按照 TDgpt 的 SQL 操作手册来执行语句，比如 `select forecast(val, 'algo=tdtsfm_1') from forecast.electricity_demand;`。

0
docs/zh/06-advanced/06-TDgpt/07-faq.md → docs/zh/06-advanced/06-TDgpt/10-faq.md
View File

23
docs/zh/06-advanced/06-TDgpt/index.md
View File

@ -3,23 +3,12 @@ sidebar_label: TDgpt
title: TDgpt
---
import TDgpt from './pic/data-analysis.png';
TDgpt 是 TDengine Enterprise 中针对时序数据提供高级分析功能的企业级组件，通过内置接口向 TDengine 提供运行时动态扩展的时序数据分析服务。TDgpt 能够独立于 TDengine 主进程部署和运行，因此可避免消耗占用 TDengine 集群的主进程资源。
TDgpt 具有服务无状态、功能易扩展、快速弹性部署、应用轻量化、高安全性等优势。
TDgpt 运行在集群中的 AI Node (Anode)中，集群中可以部署若干个 Anode 节点，不同的 Anode 节点之间无同步依赖或协同的要求。Anode 注册到 TDengine 集群以后，立即就可以提供服务。TDgpt 提供的高级时序数据分析服务可分为时序数据异常检测和时序数据预测分析两大类。
下图是部署 TDgpt 的 TDengine 集群示意图。
<img src={TDgpt} width="560" alt="TDgpt架构图" />
在查询处理过程中，Vnode中运行的查询引擎会根据查询处理物理执行计划，按需向 Anode 请求高级时序数据分析服务。因此用户可通过 SQL 语句与 Anode 节点交互并使用其提供的全部分析服务。需要注意的是 Anode 不直接接受用户的数据分析请求。同时 Anode 具备分析算法动态注册机制，其算法扩展过程完全不影响 TDengine 集群的服务，仅在非常小的（秒级）时间窗口内影响涉及高级分析的查询服务。
目前 TDgpt 提供如下的高级分析服务：
- 时序数据异常检测。TDengine 中定义了新的时间窗口——异常（状态）窗口——来提供异常检测服务。异常窗口可以视为一种特殊的**事件窗口（Event Window）**，即异常检测算法确定的连续异常时间序列数据所在的时间窗口。与普通事件窗口区别在于——时间窗口的起始时间和结束时间均是分析算法确定，不是用户指定的表达式判定。异常窗口使用方式与其他类型的时间窗口（例如状态窗口、会话窗口等）类似。因此时间窗口内可使用的查询操作均可应用在异常窗口上。
- 时序数据预测。定义了一个新函数`FORECAST`，基于输入的（历史）时间序列数据调用指定（或默认）预测算法给出输入时序数据后续时间序列的**预测**数据。
TDgpt 还为算法开发者提供了一 SDK。任何开发者只需要按照[算法开发者指南](./dev)的步骤，就可以将自己独有的时序数据预测或时序数据异常检测算法无缝集成到 TDgpt, 这样 TDengine 用户就可以通过一条 SQL 获得时序数据预测结果或是异常窗口了, 大幅降低了用户使用新的时序数据分析算法的门槛，而且让 TDengine 成为一开放的系统。
本章主要介绍如何安装部署、使用时序数据分析智能体 TDgpt 以及向 TDgpt 添加算法模型，协同 taosd 提供分析服务。
```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
<DocCardList items={useCurrentSidebarCategory().items}/>
```

BIN
docs/zh/06-advanced/06-TDgpt/pic/activity.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 29 KiB

BIN
docs/zh/06-advanced/06-TDgpt/pic/ad-result-figure.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 41 KiB

BIN
docs/zh/06-advanced/06-TDgpt/pic/ad-result.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 24 KiB

BIN
docs/zh/06-advanced/06-TDgpt/pic/anomaly-detection.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 324 KiB

After

Width:  |  Height:  |  Size: 40 KiB

BIN
docs/zh/06-advanced/06-TDgpt/pic/data-analysis.png Executable file → Normal file
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 57 KiB

After

Width:  |  Height:  |  Size: 149 KiB

BIN
docs/zh/06-advanced/06-TDgpt/pic/fc-result.png Normal file → Executable file
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 61 KiB

After

Width:  |  Height:  |  Size: 40 KiB

BIN
docs/zh/06-advanced/06-TDgpt/pic/fc.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 13 KiB

Some files were not shown because too many files have changed in this diff Show More