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

Merge remote-tracking branch 'origin/3.0' into feat/TS-5992

This commit is contained in:
dapan1121 2025-03-12 14:16:22 +08:00
parent 88fe9fc584 5044c4bd07
commit d997c144a1
590 changed files with 23396 additions and 8588 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.github/workflows/taosd-ci-build.yml vendored
View File

@ -6,6 +6,9 @@ on:
- 'main'
- '3.0'
- '3.1'
- '3.3.6'
- 'enh/cmake-TD-33848'
paths-ignore:
- 'docs/**'
- 'packaging/**'

93
.github/workflows/taosd-ci.yml vendored Normal file
View File

@ -0,0 +1,93 @@
name: TDengine CI Test
on:
pull_request:
branches:
- 'main'
- '3.0'
- '3.1'
paths-ignore:
- 'packaging/**'
- 'docs/**'
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}-TDengine
cancel-in-progress: true
env:
WKC: '/var/lib/jenkins/workspace/TDinternal/community'
jobs:
fetch-parameters:
runs-on:
group: CI
labels: [self-hosted, Linux, X64, testing]
outputs:
run_function_test: ${{ steps.parameters.outputs.run_function_test }}
run_tdgpt_test: ${{ steps.parameters.outputs.run_tdgpt_test }}
steps:
- name: Determine trigger source and fetch parameters
id: parameters
run: |
set -euo pipefail
target_branch=${{ github.event.pull_request.base.ref }}
# Check whether to run tdgpt test cases
cd ${{ env.WKC }}
changed_files_non_doc=$(git --no-pager diff --name-only FETCH_HEAD $(git merge-base FETCH_HEAD $target_branch) | grep -v "^docs/en/" | grep -v "^docs/zh/" | grep -v ".md$" | tr '\n' ' ' || :)
echo "changed files exclude doc: ${changed_files_non_doc}"
if [[ -n "$changed_files_non_doc" && "$changed_files_non_doc" =~ (forecastoperator\.c|anomalywindowoperator\.c|tanalytics\.h|tanalytics\.c|tdgpt_cases\.task|analytics|tdgpt) ]]; then
run_tdgpt_test="true"
else
run_tdgpt_test="false"
fi
echo "run tdgpt test: ${run_tdgpt_test}"
# Check whether to run function test cases
changed_files_non_tdgpt=$(git --no-pager diff --name-only FETCH_HEAD $(git merge-base FETCH_HEAD $target_branch) | \
grep -v "^docs/en/" | \
grep -v "^docs/zh/" | \
grep -v ".md$" | \
grep -Ev "forecastoperator\.c|anomalywindowoperator\.c|tanalytics\.h|tanalytics\.c|tdgpt_cases\.task|analytics|tdgpt" | \
tr '\n' ' ' || :)
echo "changed files exclude tdgpt: ${changed_files_non_tdgpt}"
if [ -n "$changed_files_non_tdgpt" ]; then
run_function_test="true"
else
run_function_test="false"
fi
echo "run function test: ${run_function_test}"
# Output the results for GitHub Actions
echo "run_function_test=$run_function_test" >> $GITHUB_OUTPUT
echo "run_tdgpt_test=$run_tdgpt_test" >> $GITHUB_OUTPUT
echo ${{ github.event.pull_request.head.ref }}
echo ${{ github.event.pull_request.base.ref }}
echo ${{ github.event.pull_request.number }}
run-tests-on-linux:
uses: taosdata/.github/.github/workflows/run-tests-on-linux.yml@main
needs: fetch-parameters
if: ${{ needs.fetch-parameters.outputs.run_tdgpt_test == 'true' || needs.fetch-parameters.outputs.run_function_test == 'true' }}
with:
tdinternal: false
run_function_test: ${{ needs.fetch-parameters.outputs.run_function_test == 'true' }}
run_tdgpt_test: ${{ needs.fetch-parameters.outputs.run_tdgpt_test == 'true' }}
run-tests-on-mac:
uses: taosdata/.github/.github/workflows/run-tests-on-macos.yml@main
needs: fetch-parameters
if: ${{ needs.fetch-parameters.outputs.run_function_test == 'true' }}
with:
tdinternal: false
run-tests-on-windows:
uses: taosdata/.github/.github/workflows/run-tests-on-windows.yml@main
needs: fetch-parameters
if: ${{ needs.fetch-parameters.outputs.run_function_test == 'true' }}
with:
tdinternal: false

48
.github/workflows/taosd-doc-build.yml vendored Normal file
View File

@ -0,0 +1,48 @@
name: TDengine Doc Build
on:
pull_request:
branches:
- 'main'
- '3.0'
paths:
- 'docs/**'
- '*.md'
env:
DOC_WKC: "/root/doc_ci_work"
ZH_DOC_REPO: "docs.taosdata.com"
EN_DOC_REPO: "docs.tdengine.com"
TD_REPO: "TDengine"
TOOLS_REPO: "taos-tools"
jobs:
build-doc:
runs-on:
group: CI
labels: [self-hosted, doc-build]
steps:
- name: Get the latest document contents
run: |
set -e
cd ${{ env.DOC_WKC }}/${{ env.TD_REPO }}
git reset --hard
git clean -f
git remote prune origin
git fetch
git checkout ${{ github.event.pull_request.base.ref }}
git pull >/dev/null
git fetch origin +refs/pull/${{ github.event.pull_request.number }}/merge
git checkout -qf FETCH_HEAD
- name: Build the chinese document
run: |
cd ${{ env.DOC_WKC }}/${{ env.ZH_DOC_REPO }}
yarn ass local
yarn build
- name: Build the english document
run: |
cd ${{ env.DOC_WKC }}/${{ env.EN_DOC_REPO }}
yarn ass local
yarn build

51
.github/workflows/tdgpt-ci.yml vendored Normal file
View File

@ -0,0 +1,51 @@
name: TDgpt CI
on:
pull_request:
branches:
- '3.0'
paths:
- 'tools/tdgpt/**'
jobs:
build:
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

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

@ -0,0 +1,41 @@
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

25
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)
set_property(GLOBAL PROPERTY GLOBAL_DEPENDS_NO_CYCLES OFF)
# api
add_library(api INTERFACE)
target_include_directories(api INTERFACE "include/client")
# src
if(${BUILD_TEST})
include(CTest)
enable_testing()
endif(${BUILD_TEST})
add_subdirectory(contrib)
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)
if(${BUILD_TEST})
include(CTest)
enable_testing()
add_subdirectory(examples/c)
endif(${BUILD_TEST})

170
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-工作流)
@ -43,9 +43,9 @@
TDengine 是一款开源、高性能、云原生的时序数据库 (Time-Series Database, TSDB)。TDengine 能被广泛运用于物联网、工业互联网、车联网、IT 运维、金融等领域。除核心的时序数据库功能外，TDengine 还提供缓存、数据订阅、流式计算等功能，是一极简的时序数据处理平台，最大程度的减小系统设计的复杂度，降低研发和运营成本。与其他时序数据库相比，TDengine 的主要优势如下：
- **高性能**：通过创新的存储引擎设计，无论是数据写入还是查询，TDengine 的性能比通用数据库快 10 倍以上，也远超其他时序数据库，存储空间不及通用数据库的1/10。
- **高性能**：通过创新的存储引擎设计，无论是数据写入还是查询，TDengine 的性能比通用数据库快 10 倍以上，也远超其他时序数据库，存储空间不及通用数据库的 1/10。
- **云原生**：通过原生分布式的设计，充分利用云平台的优势，TDengine 提供了水平扩展能力，具备弹性、韧性和可观测性，支持k8s部署，可运行在公有云、私有云和混合云上。
- **云原生**：通过原生分布式的设计，充分利用云平台的优势，TDengine 提供了水平扩展能力，具备弹性、韧性和可观测性，支持 k8s 部署，可运行在公有云、私有云和混合云上。
- **极简时序数据平台**：TDengine 内建消息队列、缓存、流式计算等功能，应用无需再集成 Kafka/Redis/HBase/Spark 等软件，大幅降低系统的复杂度，降低应用开发和运营成本。
@ -53,29 +53,29 @@ TDengine 是一款开源、高性能、云原生的时序数据库 (Time-Series
- **简单易用**：无任何依赖，安装、集群几秒搞定；提供REST以及各种语言连接器，与众多第三方工具无缝集成；提供命令行程序，便于管理和即席查询；提供各种运维工具。
- **核心开源**：TDengine 的核心代码包括集群功能全部开源，截止到2022年8月1日，全球超过 135.9k 个运行实例，GitHub Star 18.7k，Fork 4.4k，社区活跃。
- **核心开源**：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高级功能的完整列表，请 [点击](https://tdengine.com/tdengine/)。体验 TDengine 最简单的方式是通过 [TDengine云平台](https://cloud.tdengine.com)。
# 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、 Windows、macOS 等平台上安装和运行。任何 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
@ -96,13 +96,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 +110,11 @@ brew install argp-standalone gflags pkgconfig
</details>
## 3.3 Windows系统
## 3.3 Windows 系统
<details>
<summary>安装Windows必备工具</summary>
<summary>安装 Windows 必备工具</summary>
进行中。
@ -122,7 +122,7 @@ brew install argp-standalone gflags pkgconfig
## 3.4 克隆仓库
通过如下命令将TDengine仓库克隆到指定计算机:
通过如下命令将 TDengine 仓库克隆到指定计算机：
```bash
git clone https://github.com/taosdata/TDengine.git
@ -131,23 +131,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
@ -157,15 +157,15 @@ make
如果你想要编译 taosAdapter，需要添加 `-DBUILD_HTTP=false` 选项。
如果你想要编译 taosKeeper，需要添加 `--DBUILD_KEEPER=true` 选项。
如果你想要编译 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 +173,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 +192,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 +208,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 +231,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 +265,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 +281,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 +316,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 +363,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 +389,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>

2
README.md
View File

@ -177,7 +177,7 @@ If you want to compile taosKeeper, you need to add the `--DBUILD_KEEPER=true` op
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.

12
cmake/cmake.define
View File

@ -116,9 +116,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}")
@ -260,12 +257,15 @@ ELSE()
ENDIF()
IF(TD_LINUX)
IF(TD_LINUX_64)
IF(${JEMALLOC_ENABLED})
MESSAGE(STATUS "JEMALLOC_ENABLED 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_ENABLED Disabled")
MESSAGE(STATUS "JEMALLOC Disabled")
SET(LINK_JEMALLOC "")
ENDIF()
ENDIF()

2
cmake/cmake.version
View File

@ -2,7 +2,7 @@
IF (DEFINED VERNUMBER)
SET(TD_VER_NUMBER ${VERNUMBER})
ELSE ()
SET(TD_VER_NUMBER "3.3.5.2.alpha")
SET(TD_VER_NUMBER "3.3.5.8.alpha")
ENDIF ()
IF (DEFINED VERCOMPATIBLE)

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 3.0
GIT_TAG main
SOURCE_DIR "${TD_SOURCE_DIR}/tools/taosws-rs"
BINARY_DIR ""
#BUILD_IN_SOURCE TRUE

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)

15
docs/en/05-basic/03-query.md
View File

@ -145,20 +145,19 @@ Query OK, 10 row(s) in set (2.415961s)
In TDengine, you can use the window clause to perform aggregation queries by time window partitioning, which is particularly suitable for scenarios requiring analysis of large amounts of time-series data, such as smart meters collecting data every 10s but needing to query the average temperature every 1min.
The window clause allows you to partition the queried data set by windows and aggregate the data within each window, including:
- Time window (time window)
- State window (status window)
- Session window (session window)
- Event window (event window)
The logic of window partitioning is shown in the following image:
The window clause allows you to partition the queried data set by windows and aggregate the data within each window. The logic of window partitioning is shown in the following image:
<figure>
<Image img={windowModel} alt="Windowing description"/>
<figcaption>Figure 1. Windowing logic</figcaption>
</figure>
- Time Window: Data is divided based on time intervals, supporting sliding and tumbling time windows, suitable for data aggregation over fixed time periods.
- Status Window: Windows are divided based on changes in device status values, with data of the same status value grouped into one window, which closes when the status value changes.
- Session Window: Sessions are divided based on the differences in record timestamps, with records having a timestamp interval less than the predefined value belonging to the same session.
- Event Window: Windows are dynamically divided based on the start and end conditions of events, opening when the start condition is met and closing when the end condition is met.
- Count Window: Windows are divided based on the number of data rows, with each window consisting of a specified number of rows for aggregation calculations.
The syntax for the window clause is as follows:
```sql

10
docs/en/06-advanced/05-data-in/07-mqtt.md
View File

@ -86,9 +86,15 @@ The keep alive interval is the time interval negotiated between the client and t
In **Clean Session**, choose whether to clear the session. The default value is true.
Fill in the Topic names to be consumed in **Subscription Topics and QoS Configuration**. Use the following format: `topic1::0,topic2::1`.
In the **Topics Qos Config**, fill in the topic name and QoS to subscribe. Use the following format: `{topic_name}::{qos}` (e.g., `my_topic::0`). MQTT protocol 5.0 supports shared subscriptions, allowing multiple clients to subscribe to the same topic for load balancing. Use the following format: `$share/{group_name}/{topic_name}::{qos}`, where `$share` is a fixed prefix indicating the enablement of shared subscription, and `group_name` is the client group name, similar to Kafka's consumer group.
Click the **Check Connectivity** button to check if the data source is available.
In the **Topic Analysis**, fill in the MQTT topic parsing rules. The format is the same as the MQTT Topic, parsing each level of the MQTT Topic into corresponding variable names, with `_` indicating that the current level is ignored during parsing. For example: if the MQTT Topic `a/+/c` corresponds to the parsing rule `v1/v2/_`, it means assigning the first level `a` to variable `v1`, the value of the second level (where the wildcard `+` represents any value) to variable `v2`, and ignoring the value of the third level `c`, which will not be assigned to any variable. In the `payload parsing` below, the variables obtained from Topic parsing can also participate in various transformations and calculations.
In the **Compression**, configure the message body compression algorithm. After receiving the message, taosX uses the corresponding compression algorithm to decompress the message body and obtain the original data. Options include none (no compression), gzip, snappy, lz4, and zstd, with the default being none.
In the **Char Encoding**, configure the message body encoding format. After receiving the message, taosX uses the corresponding encoding format to decode the message body and obtain the original data. Options include UTF_8, GBK, GB18030, and BIG5, with the default being UTF_8.
Click the **Check Connection** button to check if the data source is available.
<figure>
<Image img={imgStep05} alt=""/>

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

@ -495,10 +495,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.

2
docs/en/08-operation/03-deployment/03-kubernetes.md
View File

@ -339,7 +339,7 @@ Helm operates Kubernetes using kubectl and kubeconfig configurations, which can
The TDengine Chart has not yet been released to the Helm repository, it can currently be downloaded directly from GitHub:
```shell
wget https://github.com/taosdata/TDengine-Operator/raw/3.0/helm/tdengine-enterpise-3.5.0.tgz
wget https://github.com/taosdata/TDengine-Operator/raw/refs/heads/3.0/helm/tdengine-enterprise-3.5.0.tgz
```
Note that it's for the enterprise edition, and the community edition is not yet available.

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

@ -16,8 +16,8 @@ TDengine is designed for various writing scenarios, and many of these scenarios
### Syntax
```sql
COMPACT DATABASE db_name [start with 'XXXX'] [end with 'YYYY'];
COMPACT [db_name.]VGROUPS IN (vgroup_id1, vgroup_id2, ...) [start with 'XXXX'] [end with 'YYYY'];
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;
@ -30,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

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

16
docs/en/10-third-party/05-bi/09-seeq.md vendored
View File

@ -22,8 +22,6 @@ Through the `TDengine Java connector`, Seeq can easily support querying time-ser
## Configure Data Source
### Configuration of JDBC Connector
**Step 1**, Check the data storage location
```shell
@ -42,9 +40,13 @@ sudo seeq restart
Use a browser to visit ip:34216 and follow the instructions to enter the license.
## Load TDengine Time-Series Data
## Data Analysis
This chapter demonstrates how to use the Seeq software to load TDengine time-series data.
### Scenario Introduction
The example scenario is a power system where users collect electricity usage data from power station instruments daily and store it in the TDengine cluster. Now, users want to predict how power consumption will develop and purchase more equipment to support it. User power consumption varies with monthly orders, and considering seasonal changes, power consumption will differ. This city is located in the northern hemisphere, so more electricity is used in summer. We simulate data to reflect these assumptions.
### Data preparation
**Step 1**, Create tables in TDengine.
@ -246,12 +248,6 @@ The source code is hosted on [GitHub Repository](https://github.com/sangshuduo/t
}
```
## Data Analysis
### Scenario Introduction
The example scenario is a power system where users collect electricity usage data from power station instruments daily and store it in the TDengine cluster. Now, users want to predict how power consumption will develop and purchase more equipment to support it. User power consumption varies with monthly orders, and considering seasonal changes, power consumption will differ. This city is located in the northern hemisphere, so more electricity is used in summer. We simulate data to reflect these assumptions.
### Using Seeq Workbench
Log in to the Seeq service page and create a new Seeq Workbench. By selecting data sources from search results and choosing different tools as needed, you can display data or make predictions. For detailed usage methods, refer to the [official knowledge base](https://support.seeq.com/space/KB/146440193/Seeq+Workbench).

73
docs/en/10-third-party/05-bi/11-superset.md vendored
View File

@ -7,36 +7,39 @@ Apache Superset is a modern enterprise level business intelligence (BI) web appl
It is supported by the Apache Software Foundation and is an open source project with an active community and rich ecosystem.
Apache Superset provides an intuitive user interface that makes creating, sharing, and visualizing data simple, while supporting multiple data sources and rich visualization options.
Through the Python connector of TDengine, Superset can support TDengine data sources and provide functions such as data presentation and analysis
Through the Python connector of TDengine, Superset can support TDengine data sources and provide functions such as data presentation and analysis.
## Prerequisites
Prepare the following environment:
- TDengine is installed and running normally (both Enterprise and Community versions are available)
- taosAdapter is running normally, refer to [taosAdapter](../../../tdengine-reference/components/taosadapter/)
- Apache Superset version 2.1.0 or above is already installed, refre to [Apache Superset](https://superset.apache.org/)
## Install TDengine Python Connector
- TDengine 3.2.3.0 and above version is installed and running normally (both Enterprise and Community versions are available).
- taosAdapter is running normally, refer to [taosAdapter](../../../tdengine-reference/components/taosadapter/).
- Apache Superset version 2.1.0 or above is already installed, refre to [Apache Superset](https://superset.apache.org/).
- Install Python connector driver, refer to [Python Client Library](../../../tdengine-reference/client-libraries/python).
:::tip
The Python connector of TDengine comes with a connection driver that supports Superset in versions 2.1.18 and later, which will be automatically installed in the Superset directory and provide data source services.
The connection uses the WebSocket protocol, so it is necessary to install the `taos-ws-py` component of TDengine separately. The complete installation script is as follows:
```bash
pip3 install taospy
pip3 install taos-ws-py
```
:::
## Configure TDengine Connection In Superset
## Configure Data Source
**Step 1**, enter the new database connection page, [Superset] -> [Setting] -> [Database Connections] -> [+DATABASE].
**Step 2**, select TDengine database connection, select the `TDengine` option from the drop-down list of [SUPPORTED DATABASES].
**Step 1**, enter the new database connection page, "Superset" → "Setting" → "Database Connections" → "+DATABASE"
**Step 2**, select TDengine database connection, select the "TDengine" option from the drop-down list of "SUPPORTED DATABASES".
:::tip
If there is no TDengine option in the drop-down list, please confirm that the steps of installing, `Superset` is first and `Python Connector` is second.
:::
**Step 3**, write a name of connection in "DISPLAY NAME"
**Step 4**, The "SQLALCHEMY URL" field is a key connection information string, and it must be filled in correctly
**Step 3**, write a name of connection in [DISPLAY NAME].
**Step 4**, The [SQLALCHEMY URL] field is a key connection information string, and it must be filled in correctly.
```bash
taosws://user:password@host:port
```
| Parameter | <center>Parameter Description</center> |
|:---------- |:--------------------------------------------------------- |
|user | Username for logging into TDengine database |
@ -44,32 +47,34 @@ taosws://user:password@host:port
|host | Name of the host where the TDengine database is located |
|port | The port that provides WebSocket services, default is 6041 |
Example:
The TDengine database installed on this machine provides WebSocket service port 6041, using the default username and password, "SQLALCHEMY URL" is:
Example:
The TDengine database installed on this machine provides WebSocket service port 6041, using the default username and password, `SQLALCHEMY URL` is:
```bash
taosws://root:taosdata@localhost:6041
```
**Step 5**, configure the connection string, click "TEST CONNECTION" to test if the connection can be successful. After passing the test, click the "CONNECT" button to complete the connection
**Step 5**, configure the connection string, click "TEST CONNECTION" to test if the connection can be successful. After passing the test, click the "CONNECT" button to complete the connection.
## Data Analysis
## Start
### Data preparation
There is no difference in the use of TDengine data source compared to other data sources. Here is a brief introduction to basic data queries:
1. Click the "+" button in the upper right corner of the Superset interface, select "SQL query", and enter the query interface
2. Select the "TDengine" data source that has been created earlier from the dropdown list of "DATABASES" in the upper left corner
3. Select the name of the database to be operated on from the drop-down list of "SCHEMA" (system libraries are not displayed)
4. "SEE TABLE SCHEMA" select the name of the super table or regular table to be operated on (sub tables are not displayed)
5. Subsequently, the schema information of the selected table will be displayed in the following area
6. In the SQL editor area, any SQL statement that conforms to TDengine syntax can be entered for execution
There is no difference in the use of TDengine data source compared to other data sources. Here is a brief introduction to basic data queries:
## Example
1. Click the [+] button in the upper right corner of the Superset interface, select [SQL query], and enter the query interface.
2. Select the `TDengine` data source that has been created earlier from the dropdown list of [DATABASES] in the upper left corner.
3. Select the name of the database to be operated on from the drop-down list of [SCHEMA] (system libraries are not displayed).
4. [SEE TABLE SCHEMA] select the name of the super table or regular table to be operated on (sub tables are not displayed).
5. Subsequently, the schema information of the selected table will be displayed in the following area.
6. In the `SQL` editor area, any `SQL` statement that conforms to `TDengine` syntax can be entered for execution.
We chose two popular templates from the Superset Chart template to showcase their effects, using smart meter data as an example:
### Smart Meter Example
1. "Aggregate" Type, which displays the maximum voltage value collected per minute during the specified time period in Group 4
We chose two popular templates from the [Superset Chart] template to showcase their effects, using smart meter data as an example:
![superset-demo1](./superset-demo1.jpeg)
2. "RAW RECORDS" Type, which displays the collected values of current and voltage during the specified time period in Group 4
![superset-demo2](./superset-demo2.jpeg)
1. `Aggregate` Type, which displays the maximum voltage value collected per minute during the specified time period in Group 4.
![superset-demo1](./superset-demo1.jpeg)
2. `RAW RECORDS` Type, which displays the collected values of current and voltage during the specified time period in Group 4.
![superset-demo2](./superset-demo2.jpeg)

8
docs/en/10-third-party/05-bi/12-tableau.md vendored
View File

@ -10,8 +10,8 @@ Tableau is a well-known business intelligence tool that supports multiple data s
Prepare the following environment:
- TDengine 3.3.5.4 and above version is installed and running normally (both Enterprise and Community versions are available)
- taosAdapter is running normally, refer to [taosAdapter Reference](../../../tdengine-reference/components/taosadapter/)
- TDengine 3.3.5.8 and above version is installed and running normally (both Enterprise and Community versions are available).
- taosAdapter is running normally, refer to [taosAdapter Reference](../../../tdengine-reference/components/taosadapter/).
- Install and run Tableau Desktop (if not installed, please download and install Windows operating system 64-bit [Download Tableau Desktop](https://www.tableau.com/products/desktop/download)). Install Tableau please refer to [Tableau Desktop](https://www.tableau.com).
- Download the latest Windows operating system X64 client driver from the TDengine official website and install it, refer to [Install ODBC Driver](../../../tdengine-reference/client-libraries/odbc/#Installation).
@ -19,6 +19,10 @@ Prepare the following environment:
**Step 1**, Search and open the "ODBC Data Source (64 bit)" management tool in the Start menu of the Windows operating system and configure it, refer to [Install ODBC Driver](../../../tdengine-reference/client-libraries/odbc/#Installation).
:::tip
It should be noted that when configuring the ODBC data source for Tableau, the [Database] configuration item on the TDengine ODBC data source configuration page is required. You need to select a database that can be successfully connected.
:::
**Step 2**, Start Tableau in the Windows system environment, then search for "ODBC" on its connection page and select "Other Databases (ODBC)".
**Step 3**, Click the `DSN` radio button, then select the configured data source (MyTDengine), and click the `Connect` button. After the connection is successful, delete the content of the string attachment, and finally click the `Sign In` button.

2
docs/en/10-third-party/05-bi/13-excel.md vendored
View File

@ -10,7 +10,7 @@ toc_max_heading_level: 4
Prepare the following environment:
- TDengine 3.3.5.7 and above version is installed and running normally (both Enterprise and Community versions are available).
- TDengine 3.3.5.8 and above version is installed and running normally (both Enterprise and Community versions are available).
- taosAdapter is running normally, refer to [taosAdapter Reference](../../../tdengine-reference/components/taosadapter/).
- Install and run Excel. If not installed, please download and install it. For specific instructions, please refer to Microsoft's official documentation.
- Download the latest Windows operating system X64 client driver from the TDengine official website and install it, refer to [Install ODBC Driver](../../../tdengine-reference/client-libraries/odbc/#Installation).

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

@ -43,7 +43,7 @@ After modifying configuration file parameters, you need to restart the *taosd* s
|resolveFQDNRetryTime | Cancelled after 3.x |Not supported |Number of retries when FQDN resolution fails|
|timeToGetAvailableConn | Cancelled after 3.3.4.x |Maximum waiting time to get an available connection, range 10-50000000, in milliseconds, default value 500000|
|maxShellConns | Cancelled after 3.x |Supported, effective after restart|Maximum number of connections allowed|
|maxRetryWaitTime | |Supported, effective after restart|Maximum timeout for reconnection,calculated from the time of retry,range is 0-86400000,in milliseconds, default value 10000|
|maxRetryWaitTime | |Supported, effective after restart|Maximum timeout for reconnection,calculated from the time of retry,range is 3000-86400000,in milliseconds, default value 10000|
|shareConnLimit |Added in 3.3.4.0 |Supported, effective after restart|Number of requests a connection can share, range 1-512, default value 10|
|readTimeout |Added in 3.3.4.0 |Supported, effective after restart|Minimum timeout for a single request, range 64-604800, in seconds, default value 900|
@ -84,12 +84,12 @@ After modifying configuration file parameters, you need to restart the *taosd* s
|Parameter Name |Supported Version |Dynamic Modification|Description|
|-----------------------|-------------------------|--------------------|------------|
|timezone | |Not supported |Time zone; defaults to dynamically obtaining the current time zone setting from the system|
|locale | |Not supported |System locale information and encoding format, defaults to obtaining from the system|
|charset | |Not supported |Character set encoding, defaults to obtaining from the system|
|timezone | | since 3.1.0.0 |Time zone; defaults to dynamically obtaining the current time zone setting from the system|
|locale | | since 3.1.0.0 |System locale information and encoding format, defaults to obtaining from the system|
|charset | | since 3.1.0.0 |Character set encoding, defaults to obtaining from the system|
:::info
#### Explanation of Regional Related Parameters
1. To address the issue of data writing and querying across multiple time zones, TDengine uses Unix Timestamps to record and store timestamps. The nature of Unix Timestamps ensures that the timestamps generated are consistent at any given moment across any time zone. It is important to note that the conversion to Unix Timestamps is done on the client side. To ensure that other forms of time on the client are correctly converted to Unix Timestamps, it is necessary to set the correct time zone.
On Linux/macOS, the client automatically reads the time zone information set by the system. Users can also set the time zone in the configuration file in various ways. For example:
@ -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
@ -534,29 +535,23 @@ The `taosd_vnodes_role` table records virtual node role information.
| duration | VARCHAR | tag | SQL execution duration, value range: 3-10s, 10-100s, 100-1000s, 1000s- |
| cluster_id | VARCHAR | tag | cluster id |
## Log Related
### taos\_slow\_sql\_detail 表
TDengine records the system's operational status through log files, helping users monitor the system's condition and troubleshoot issues. This section mainly introduces the related explanations of two system logs: taosc and taosd.
`taos_slow_sql_detail` records slow query detail information.The rule of the table name is `{user}_{db}_{ip}_clusterId_{cluster_id}`
TDengine's log files mainly include two types: normal logs and slow logs.
1. Normal Log Behavior Explanation
1. Multiple client processes can be started on the same machine, so the client log naming convention is taoslogX.Y, where X is a number, either empty or from 0 to 9, and Y is a suffix, either 0 or 1.
2. Only one server process can exist on the same machine. Therefore, the server log naming convention is taosdlog.Y, where Y is a suffix, either 0 or 1.
The rules for determining the number and suffix are as follows (assuming the log path is /var/log/taos/):
1. Determining the number: Use 10 numbers as the log naming convention, /var/log/taos/taoslog0.Y - /var/log/taos/taoslog9.Y, check each number sequentially to find the first unused number as the log file number for that process. If all 10 numbers are used by processes, do not use a number, i.e., /var/log/taos/taoslog.Y, and all processes write to the same file (number is empty).
2. Determining the suffix: 0 or 1. For example, if the number is determined to be 3, the alternative log file names would be /var/log/taos/taoslog3.0 /var/log/taos/taoslog3.1. If both files do not exist, use suffix 0; if one exists and the other does not, use the existing suffix. If both exist, use the suffix of the file that was modified most recently.
3. If the log file exceeds the configured number of lines numOfLogLines, it will switch suffixes and continue logging, e.g., /var/log/taos/taoslog3.0 is full, switch to /var/log/taos/taoslog3.1 to continue logging. /var/log/taos/taoslog3.0 will be renamed with a timestamp suffix and compressed for storage (handled by an asynchronous thread).
4. Control how many days log files are kept through the configuration logKeepDays, logs older than a certain number of days will be deleted when new logs are compressed and stored. It is not based on natural days.
In addition to recording normal logs, SQL statements that take longer than the configured time will be recorded in the slow logs. Slow log files are mainly used for analyzing system performance and troubleshooting performance issues.
2. Slow Log Behavior Explanation
1. Slow logs are recorded both locally in slow log files and sent to taosKeeper for structured storage via taosAdapter (monitor switch must be turned on).
2. Slow log file storage rules are:
1. One slow log file per day; if there are no slow logs for the day, there is no file for that day.
2. The file name is taosSlowLog.yyyy-mm-dd (taosSlowLog.2024-08-02), and the log storage path is configured through logDir.
3. Logs from multiple clients are stored in the same taosSlowLog.yyyy.mm.dd file under the respective log path.
4. Slow log files are not automatically deleted or compressed.
5. Uses the same three parameters as normal log files: logDir, minimalLogDirGB, asyncLog. The other two parameters, numOfLogLines and logKeepDays, do not apply to slow logs.
| field | type | is\_tag | comment |
| :------------- | :-------- | :------ | :---------------------------------------------------- |
| start\_ts | TIMESTAMP | | sql start exec time in client, ms,primary key |
| request\_id | UINT64_T | | sql request id, random hash |
| query\_time | INT32_T | | sql exec time, ms |
| code | INT32_T | | sql return code, 0 success |
| error\_info | VARCHAR | | error info if sql exec failed |
| type | INT8_T | | sql type（1-query, 2-insert, 4-others） |
| rows\_num | INT64_T | | sql result rows num |
| sql | VARCHAR | | sql sting |
| process\_name | VARCHAR | | process name |
| process\_id | VARCHAR | | process id |
| db | VARCHAR | TAG | which db the sql belong to |
| user | VARCHAR | TAG | the user that exec this sql |
| ip | VARCHAR | TAG | the client ip that exec this sql |
| cluster\_id | VARCHAR | TAG | cluster id |

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
@ -478,6 +502,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

34
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

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

33
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 | |
@ -37,6 +37,8 @@ The list of keywords is as follows:
| ASOF | |
| AT_ONCE | |
| ATTACH | |
| AUTO | 3.3.5.0+ |
| ASSIGN | 3.3.6.0+ |
### B
@ -78,12 +80,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 | |
@ -114,6 +120,7 @@ The list of keywords is as follows:
| DESC | |
| DESCRIBE | |
| DETACH | |
| DISK_INFO | 3.3.5.0+ |
| DISTINCT | |
| DISTRIBUTED | |
| DIVIDE | |
@ -148,19 +155,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 +216,7 @@ The list of keywords is as follows:
| INTO | |
| IPTOKEN | |
| IROWTS | |
| IROWTS_ORIGIN | 3.3.5.0+ |
| IS | |
| IS_IMPORT | |
| ISFILLED | |
@ -242,6 +250,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 +272,7 @@ The list of keywords is as follows:
| MEDIUMBLOB | |
| MERGE | |
| META | |
| META_ONLY | 3.3.6.0+ |
| MINROWS | |
| MINUS | |
| MNODE | |
@ -281,6 +291,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 +307,7 @@ The list of keywords is as follows:
| OFFSET | |
| ON | |
| ONLY | |
| ON_FAILURE | 3.3.6.0+ |
| OR | |
| ORDER | |
| OUTER | |
@ -345,6 +358,7 @@ The list of keywords is as follows:
| RATIO | |
| READ | |
| RECURSIVE | |
| REGEXP | 3.3.6.0+ |
| REDISTRIBUTE | |
| REM | |
| REPLACE | |
@ -418,7 +432,7 @@ The list of keywords is as follows:
| TABLE_PREFIX | |
| TABLE_SUFFIX | |
| TABLES | |
| tag | |
| TAG | |
| TAGS | |
| TBNAME | |
| THEN | |
@ -435,6 +449,7 @@ The list of keywords is as follows:
| TRANSACTIONS | |
| TRIGGER | |
| TRIM | |
| TRUE_FOR | 3.3.6.0+ |
| TSDB_PAGESIZE | |
| TSERIES | |
| TSMA | |

9
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
@ -320,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

5
docs/en/14-reference/05-connector/30-python.md
View File

@ -71,7 +71,10 @@ WebSocket Connector Historical Versions:
|WebSocket Connector Version | Major Changes | TDengine Version|
| ----------------------- | -------------------------------------------------------------------------------------------------- | ----------------- |
|0.3.5 | Added support for VARBINARY and GEOMETRY types, fixed known issues. | 3.3.0.0 and higher|
|0.3.9 | Fix the problem of incomplete data retrieval when customizing the number of rows with the "fetchmany" method. | - |
|0.3.8 | Supported connecting SuperSet to the TDengine cloud service instance. | - |
|0.3.5 | Fixed the issues in the crypto provider. | - |
|0.3.4 | Supported varbinary and geometry data type. | 3.3.0.0 and higher |
|0.3.2 | Optimize WebSocket SQL query and insertion performance, modify readme and documentation, fix known issues. | 3.2.3.0 and higher|
|0.2.9 | Known issue fixes. | - |
|0.2.5 | 1. Data subscription supports obtaining and resetting consumption progress. <br/>2 Support schemaless. <br/>3 Support STMT. | - |

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

@ -460,7 +460,7 @@ This document details the server error codes that may be encountered when using
| 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 |
| 0x80002680 | Invalid using cols function | Illegal using cols function | 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 cols function with multiple output columns | Illegal using the cols function for multiple column output | Check and correct the SQL statement |
| 0x8000268C | Invalid using alias for cols function | Illegal cols function alias | Check and correct the SQL statement |
@ -485,10 +485,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 |
@ -537,8 +537,10 @@ 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 |
| 0x80004100 | Stream task not exist | The stream computing task does not exist | Check the server-side error logs |

2
docs/en/26-tdinternal/09-stream.md
View File

@ -94,7 +94,7 @@ The sink task is responsible for receiving the output results from the agg task
The above three types of tasks each play their roles in the stream computing architecture, distributed at different levels. Clearly, the number of source tasks directly depends on the number of vnodes, with each source task independently handling the data in its vnode without interference from other source tasks, and there are no sequential constraints. However, it is worth noting that if the final stream computing results converge to one table, then only one sink task will be deployed on the vnode where that table is located. The collaborative relationship between these three types of tasks is shown in the following diagram, together forming the complete execution process of stream computing tasks.
<figure>
<Image img={imgStep02} alt="Relationships between tasks"/>
<Image img={imgStep03} alt="Relationships between tasks"/>
<figcaption>Figure 3. Relationships between tasks</figcaption>
</figure>

293
docs/en/27-train-faq/02-dst.md Normal file
View File

@ -0,0 +1,293 @@
---
title: DST(Daylight Saving Time) Usage
description: Explanation and suggestions for using DST(Daylight Saving Time) in TDengine
---
## Background
In the use of time-series databases, there are times when Daylight Saving Time (DST) is encountered. We analyze and explain the use and issues of DST in TDengine to help you use TDengine more smoothly.
## Definitions
### Time Zone
A time zone is a region on Earth that uses the same standard time. Due to the Earth's rotation, to ensure that the time in each place is coordinated with the local sunrise and sunset, the world is divided into multiple time zones.
### IANA Time Zone
The IANA (Internet Assigned Numbers Authority) time zone database, also known as the tz database, provides a standard reference for global time zone information. It is the basis for modern systems and software to handle time zone-related operations.
IANA uses the "Region/City" format (e.g., Europe/Berlin) to clearly identify time zones.
TDengine supports the use of IANA time zones in different components (except for the time zone settings in Windows taos.cfg).
### Standard Time and Local Time
Standard time is the time determined based on a fixed meridian on Earth. It provides a unified reference point for each time zone.
- Greenwich Mean Time (GMT): Historically used reference time, located at the 0° meridian.
- Coordinated Universal Time (UTC): The modern time standard, similar to GMT but more precise.
The relationship between standard time and time zones is as follows:
- Reference: Standard time (e.g., UTC) is the reference point for setting time zones.
- Offset: Different time zones are defined by their offset from standard time. For example, UTC+1 means 1 hour ahead of UTC.
- Regional Division: The world is divided into multiple time zones, each using one or more standard times.
Relative to standard time, each region sets its local time based on its time zone:
- Time Zone Offset: Local time equals standard time plus the offset of the time zone. For example, UTC+2 means 2 hours ahead of UTC.
- Daylight Saving Time (DST): Some regions adjust their local time during specific periods, such as moving the clock forward by one hour. See the next section for details.
### Daylight Saving Time
Daylight Saving Time (DST) is a system that advances the time by one hour to make better use of daylight and save energy. It usually starts in spring and ends in autumn. The specific start and end times of DST vary by region. The following explanation uses Berlin time as an example to illustrate DST and its effects.
![DST Berlin](./02-dst/dst-berlin.png)
According to this rule, you can see:
- The time between 02:00:00 and 03:00:00 (excluding 03:00:00) on March 31, 2024, in Berlin local time does not exist (jump).
- The time between 02:00:00 and 03:00:00 (excluding 03:00:00) on October 27, 2024, in Berlin local time appears twice.
#### DST and the IANA Time Zone Database
- Recording Rules: The IANA time zone database records detailed DST rules for each region, including the start and end dates and times.
- Automatic Adjustment: Many operating systems and software use the IANA database to automatically handle DST adjustments.
- Historical Changes: The IANA database also tracks historical DST changes to ensure accuracy.
#### DST and Timestamp Conversion
- Converting a timestamp to local time is deterministic. For example, 1729990654 is Berlin time DST 2024-10-27 02:57:34, and 1729994254 is Berlin time standard time 2024-10-27 02:57:34 (these two local times are the same except for the time offset).
- Without specifying the time offset, converting local time to a timestamp is indeterminate. The time skipped during DST does not exist and cannot be converted to a timestamp, such as Berlin time 2024-03-31 02:34:56 does not exist and cannot be converted to a timestamp. The repeated time during the end of DST cannot determine which timestamp it is, such as 2024-10-27 02:57:34 without specifying the time offset cannot determine whether it is 1729990654 or 1729994254. Specifying the time offset can determine the timestamp, such as 2024-10-27 02:57:34 CEST(+02:00), specifying DST 2024-10-27 02:57:34 timestamp 1729990654.
### RFC3339 Time Format
RFC 3339 is an internet time format standard used to represent dates and times. It is based on the ISO 8601 standard but specifies some format details more specifically.
The format is as follows:
- Basic Format: `YYYY-MM-DDTHH:MM:SSZ`
- Time Zone Representation:
- Z represents Coordinated Universal Time (UTC).
- Offset format, such as +02:00, represents the time difference from UTC.
With explicit time zone offsets, the RFC 3339 format can accurately parse and compare times globally.
The advantages of RFC 3339 include:
- Standardization: Provides a unified format for easy cross-system data exchange.
- Clarity: Clearly indicates time zone information, avoiding time misunderstandings.
TDengine uses the RFC3339 format for display in REST API and Explorer UI. In SQL statements, you can use the RFC3339 format to write timestamp data:
```sql
insert into t1 values('2024-10-27T01:59:59.000Z', 0);
select * from t1 where ts >= '2024-10-27T01:59:59.000Z';
```
### Undefined Behavior
Undefined behavior refers to specific code or operations that do not have a clearly defined result and do not guarantee compatibility with that result. TDengine may modify the current behavior in a future version without notifying users. Therefore, users should not rely on the current undefined behavior for judgment or application in TDengine.
## Writing and Querying DST in TDengine
We use the following table to show the impact of DST on writing and querying.
![DST Table](./02-dst/dst-table.png)
### Table Explanation
- **TIMESTAMP**: TDengine uses a 64-bit integer to store raw timestamps.
- **UTC**: The UTC time representation corresponding to the timestamp.
- **Europe/Berlin**: The RFC3339 format time corresponding to the Europe/Berlin time zone.
- **Local**: The local time corresponding to the Europe/Berlin time zone (without time zone).
### Table Analysis
- At the **start of DST** (Berlin time March 31, 02:00), the time jumps directly from 02:00 to 03:00 (one hour forward).
- Light green is the timestamp one hour before the start of DST;
- Dark green is the timestamp one hour after the start of DST;
- Red indicates that the nonexistent local time was inserted into the TDengine database:
- Using SQL `INSERT INTO t1 values('2024-03-31 02:59:59',..)` to insert data from `2024-03-31 02:00:00` to `2024-03-31 02:59:59` will be automatically adjusted to -1000 (in TDengine, this is undefined behavior, currently this value is related to the database precision, millisecond database is -1000, microsecond database is -1000000, nanosecond database is -1000000000), because that moment does not exist in local time;
- At the **end of DST** (Berlin time October 27, 03:00), the time jumps from 03:00 to 02:00 (one hour back).
- Light blue indicates the timestamp one hour before the clock jump;
- Dark blue indicates the timestamp within one hour after the clock jump, its local time without time zone is the same as the previous hour.
- Purple indicates the timestamp one hour after the clock jump;
- **Local Time Changes**: It can be seen that due to the adjustment of DST, local time changes, which may cause some time periods to appear repeated or missing.
- **UTC Time Unchanged**: UTC time remains unchanged, ensuring the consistency and order of time.
- **RFC3339**: The RFC3339 format time shows the change in time offset, changing to +02:00 after the start of DST and to +01:00 after the end of DST.
- **Conditional Query**:
- At the **start of DST**, the skipped time (`[03-31 02:00:00,03-31 03:00:00)`) does not exist, so using that time for queries results in undefined behavior: `SELECT ts FROM t1 WHERE ts BETWEEN '2024-03-31 02:00:00' AND '2024-03-31 02:59:59'` (the nonexistent local timestamp is converted to `-1000`):
```sql
taos> SELECT ts FROM t1 WHERE ts BETWEEN '2024-03-31 02:00:00' AND '2024-03-31 02:59:59';
ts |
=================
-1000 |
Query OK, 1 row(s) in set (0.003635s)
```
When the nonexistent timestamp is used together with the existing timestamp, the result is also not as expected, as shown below where the start local time does not exist:
```sql
taos> SELECT ts, to_iso8601(ts,'Z') FROM t1 WHERE ts BETWEEN '2024-03-31 02:00:00' AND '2024-03-31 03:59:59';
ts | to_iso8601(ts,'Z') |
==================================================
-1000 | 1969-12-31T23:59:59.000Z |
1711843200000 | 2024-03-31T00:00:00.000Z |
1711846799000 | 2024-03-31T00:59:59.000Z |
1711846800000 | 2024-03-31T01:00:00.000Z |
1711846801000 | 2024-03-31T01:00:01.000Z |
Query OK, 5 row(s) in set (0.003339s)
```
In the following statements, the first SQL query end time does not exist, and the second end time exists. The first SQL query result is not as expected:
```sql
taos> SELECT ts, to_iso8601(ts,'Z') FROM t1 WHERE ts BETWEEN '2024-03-31 01:00:00' AND '2024-03-31 02:00:00';
Query OK, 0 row(s) in set (0.000930s)
taos> SELECT ts, to_iso8601(ts,'Z') FROM t1 WHERE ts BETWEEN '2024-03-31 01:00:00' AND '2024-03-31 01:59:59';
ts | to_iso8601(ts,'Z') |
==================================================
1711843200000 | 2024-03-31T00:00:00.000Z |
1711846799000 | 2024-03-31T00:59:59.000Z |
Query OK, 2 row(s) in set (0.001227s)
```
- At the end of DST, the repeated time (`[10-27 02:00:00,10-27 03:00:00)` excluding `10-27 03:00:00`) appears twice, and using that time range for queries in TDengine is also undefined behavior.
- Querying the data between `[2024-10-27 02:00:00, 2024-10-27 03:00:00]` includes the repeated timestamps and the data at `2024-10-27 03:00:00`:
```sql
taos> SELECT ts, to_iso8601(ts,'Z'), TO_CHAR(ts, 'YYYY-MM-DD HH:mi:ss') FROM t1 WHERE ts BETWEEN '2024-10-27 02:00:00' AND '2024-10-27 03:00:00';
ts | to_iso8601(ts,'Z') | to_char(ts, 'YYYY-MM-DD HH:mi:ss') |
=======================================================================================
1729987200000 | 2024-10-27T00:00:00.000Z | 2024-10-27 02:00:00 |
1729990799000 | 2024-10-27T00:59:59.000Z | 2024-10-27 02:59:59 |
1729990800000 | 2024-10-27T01:00:00.000Z | 2024-10-27 02:00:00 |
1729994399000 | 2024-10-27T01:59:59.000Z | 2024-10-27 02:59:59 |
1729994400000 | 2024-10-27T02:00:00.000Z | 2024-10-27 03:00:00 |
Query OK, 5 row(s) in set (0.001370s)
```
- However, the following query for the range [2024-10-27 02:00:00.000,2024-10-27 02:57:34.999] can only find the data at the first 2024-10-27 02:00:00 time point:
```sql
taos> SELECT ts, to_iso8601(ts,'Z'), TO_CHAR(ts, 'YYYY-MM-DD HH:mi:ss') FROM t1 WHERE ts >= '2024-10-27 02:00:00' AND ts <= '2024-10-27 02:57:00.999';
ts | to_iso8601(ts,'Z') | to_char(ts, 'YYYY-MM-DD HH:mi:ss') |
=======================================================================================
1729987200000 | 2024-10-27T00:00:00.000Z | 2024-10-27 02:00:00 |
Query OK, 1 row(s) in set (0.004480s)
```
- The following query for the range [2024-10-27 02:00:01,2024-10-27 02:57:35] can find 3 rows of data (including one row of local time data at 02:59:59):
```sql
taos> SELECT ts, to_iso8601(ts,'Z'), TO_CHAR(ts, 'YYYY-MM-DD HH:mi:ss') FROM t1 WHERE ts >= '2024-10-27 02:00:00' AND ts <= '2024-10-27 02:57:35';;
ts | to_iso8601(ts,'Z') | to_char(ts, 'YYYY-MM-DD HH:mi:ss') |
===============================================================================================
2024-10-27 02:00:00.000 | 2024-10-27T00:00:00.000Z | 2024-10-27 02:00:00 |
2024-10-27 02:59:59.000 | 2024-10-27T00:59:59.000Z | 2024-10-27 02:59:59 |
2024-10-27 02:00:00.000 | 2024-10-27T01:00:00.000Z | 2024-10-27 02:00:00 |
Query OK, 3 row(s) in set (0.004428s)
```
## Summary and Suggestions
### Summary
This explanation only addresses the impact of using local time. Using UNIX timestamps or RFC3339 has no impact.
- Writing:
- It is not possible to write data for nonexistent times during the DST transition.
- Writing data for repeated times during the DST transition is undefined behavior.
- Querying:
- Querying with conditions that specify the skipped time during the start of DST results in undefined behavior.
- Querying with conditions that specify the repeated time during the end of DST results in undefined behavior.
- Display:
- Displaying with time zones is not affected.
- Displaying local time is accurate, but repeated times during the end of DST cannot be distinguished.
- Users should be cautious when using time without time zones for display and application.
### Suggestions
To avoid unnecessary impacts of DST on querying and writing in TDengine, it is recommended to use explicit time offsets for writing and querying.
- Use UNIX Timestamps: Using UNIX timestamps can avoid time zone issues.
| TIMESTAMP | UTC | Europe/Berlin | Local |
| ------------: | :----------------------: | :---------------------------: | :-----------------: |
| 1711846799000 | 2024-03-31T00:59:59.000Z | 2024-03-31T01:59:59.000+01:00 | 2024-03-31 01:59:59 |
| 1711846800000 | 2024-03-31T01:00:00.000Z | 2024-03-31T03:00:00.000+02:00 | 2024-03-31 03:00:00 |
```sql
taos> insert into t1 values(1711846799000, 1)(1711846800000, 2);
Insert OK, 2 row(s) affected (0.001434s)
taos> select * from t1 where ts between 1711846799000 and 1711846800000;
ts | v1 |
===============================
1711846799000 | 1 |
1711846800000 | 2 |
Query OK, 2 row(s) in set (0.003503s)
```
- Use RFC3339 Time Format: The RFC3339 time format with time zone offsets can effectively avoid the uncertainty of DST.
| TIMESTAMP | UTC | Europe/Berlin | Local |
| ------------: | :----------------------: | :---------------------------: | :-----------------: |
| 1729987200000 | 2024-10-27T00:00:00.000Z | 2024-10-27T02:00:00.000+02:00 | 2024-10-27 02:00:00 |
| 1729990799000 | 2024-10-27T00:59:59.000Z | 2024-10-27T02:59:59.000+02:00 | 2024-10-27 02:59:59 |
| 1729990800000 | 2024-10-27T01:00:00.000Z | 2024-10-27T02:00:00.000+01:00 | 2024-10-27 02:00:00 |
| 1729994399000 | 2024-10-27T01:59:59.000Z | 2024-10-27T02:59:59.000+01:00 | 2024-10-27 02:59:59 |
```sql
taos> insert into t1 values ('2024-10-27T02:00:00.000+02:00', 1)
('2024-10-27T02:59:59.000+02:00', 2)
('2024-10-27T02:00:00.000+01:00', 3)
('2024-10-27T02:59:59.000+01:00', 4);
Insert OK, 4 row(s) affected (0.001514s)
taos> SELECT *,
to_iso8601(ts,'Z'),
to_char(ts, 'YYYY-MM-DD HH:mi:ss') FROM t1
WHERE ts >= '2024-10-27T02:00:00.000+02:00'
AND ts <= '2024-10-27T02:59:59.000+01:00';
ts | v1 | to_iso8601(ts,'Z') | to_char(ts, 'YYYY-MM-DD HH:mi:ss') |
=====================================================================================================
1729987200000 | 1 | 2024-10-27T00:00:00.000Z | 2024-10-27 02:00:00 |
1729990799000 | 2 | 2024-10-27T00:59:59.000Z | 2024-10-27 02:59:59 |
1729990800000 | 3 | 2024-10-27T01:00:00.000Z | 2024-10-27 02:00:00 |
1729994399000 | 4 | 2024-10-27T01:59:59.000Z | 2024-10-27 02:59:59 |
Query OK, 4 row(s) in set (0.004275s)
taos> SELECT *,
to_iso8601(ts,'Z'),
to_char(ts, 'YYYY-MM-DD HH:mi:ss') FROM t1
WHERE ts >= '2024-10-27T02:00:00.000+02:00'
AND ts <= '2024-10-27T02:59:59.000+02:00';
ts | v1 | to_iso8601(ts,'Z') | to_char(ts, 'YYYY-MM-DD HH:mi:ss') |
=====================================================================================================
1729987200000 | 1 | 2024-10-27T00:00:00.000Z | 2024-10-27 02:00:00 |
1729990799000 | 2 | 2024-10-27T00:59:59.000Z | 2024-10-27 02:59:59 |
Query OK, 2 row(s) in set (0.004275s)
```
- Pay Attention to Time Zone Settings When Querying: When querying and displaying, if local time is needed, be sure to consider the impact of DST.
- taosAdapter: When using the REST API, it supports setting the IANA time zone, and the result is returned in RFC3339 format.
```shell
$ curl -uroot:taosdata 'localhost:6041/rest/sql?tz=Europe/Berlin'\
-d "select ts from tz1.t1"
{"code":0,"column_meta":[["ts","TIMESTAMP",8]],"data":[["1970-01-01T00:59:59.000+01:00"],["2024-03-31T01:00:00.000+01:00"],["2024-03-31T01:59:59.000+01:00"],["2024-03-31T03:00:00.000+02:00"],["2024-03-31T03:00:01.000+02:00"],["2024-10-27T02:00:00.000+02:00"],["2024-10-27T02:59:59.000+02:00"],["2024-10-27T02:00:00.000+01:00"],["2024-10-27T02:59:59.000+01:00"],["2024-10-27T03:00:00.000+01:00"]],"rows":10}
```
- Explorer: When using the Explorer page for SQL queries, users can configure the client time zone to display in RFC3339 format.
![Explorer DST](./02-dst/explorer-with-tz.png)
## Reference Documents
- IANA Time Zone Database: [https://www.iana.org/time-zones](https://www.iana.org/time-zones)
- RFC3339: [https://datatracker.ietf.org/doc/html/rfc3339](https://datatracker.ietf.org/doc/html/rfc3339)

BIN
docs/en/27-train-faq/02-dst/dst-berlin.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 234 KiB

BIN
docs/en/27-train-faq/02-dst/dst-table.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 80 KiB

BIN
docs/en/27-train-faq/02-dst/explorer-with-tz.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 72 KiB

4
docs/en/28-releases/01-tdengine.md
View File

@ -25,6 +25,10 @@ Download links for TDengine 3.x version installation packages are as follows:
import Release from "/components/ReleaseV3";
## 3.3.5.8
<Release type="tdengine" version="3.3.5.8" />
## 3.3.5.2
<Release type="tdengine" version="3.3.5.2" />

66
docs/en/28-releases/03-notes/3.3.5.8.md Executable file
View File

@ -0,0 +1,66 @@
---
title: TDengine 3.3.5.8 Release Notes
sidebar_label: 3.3.5.8
description: Version 3.3.5.8 Notes
slug: /release-history/release-notes/3.3.5.8
---
## Features
1. feat: suppport tmq subscription with ONLY META in JDBC
2. feat: support multiple-line SQL editor in Grafana
3. feat: add support for VARBINARY/GEOMETRY in ODBC
4. feat: support TDengine with ODBC dirver in Excel
5. feat: taosX agent use specific port range in local connection
## Enhancements
1. enh: websocket handle consumer error when tmq polled nothing
2. enh: JDBC add support for unsigned integers
3. enh: expose global.written_concurrent configuration for kafka/mqtt/csv in Explorer
4. enh: support integration with TDgpt in community version
5. enh: support BinaryRowData type in flink
6. enh: in stmt2 SQL statements, the LIMIT clause supports the use of ? as a parameter placeholder
7. enh: enable compression via websocket in taosX backup
8. enh: ODBC support SQL_ROWSET_SIZE in SQLSetStmtAttr
9. enh: expose num.of.consumers/writters configurations in Explorer
10. enh: Add connector files to the macOS installation package.
11. enh: handle errors when poll result is null in rust connector
12. enh: tsbs support csv output format
13. enh: add Classified Connections Counts table in TDinsight
14. enh: use consist float precision in explorer and tao shell
15. enh: flink table support update/delete
16. enh: taosX agent will resume connection when taosX server disconnected for long time
## Fixes
1. fix: explorer support signup email with dot `.`
2. fix: flock syscall error on aws cloud storage in taosAdapter
3. fix: modify boolean tag values in sub-tables results in erroneous metadata from data subscriptions.
4. fix: allow spaces in columns of csv in explorer datain
5. fix: resolved the issue of high CPU usage by the stmtbind thread when the system is in an idle state
6. fix: health state tick to idle when no data consumed
7. fix: fix security issues in JDBC sample code
8. fix: fix upgrade compaibility issue of taosX
9. fix: ODBC core when set SQL_ATTR_TXN_ISOLATION with SQLSetConnectAttr
10. fix: received/processed_messages should be reset when task rerun
11. fix: when restoring data using taosX, it may crash if the database is not specified
12. fix: when creating a database, the keep_time_offset options supports suffixes h (hours) and d (days) for time values
13. fix: potential deadlocks while drop stream
14. fix: failed to write data in a dual-replica database when a single dnode is disconnected from the network
15. fix: when querying the information_schema.ins_tables table, a "Sync leader is unreachable" error may be triggered if the Leader of the mnode changes.
16. fix: the time-filtering query results involving composite primary keys were incorrect after data compact
17. fix: when the join condition of the primary key column is not a simple equality condition, it may lead to incorrect JOIN results
18. fix: error caused by cursor.fetchmany with custom length in python taosws
19. fix: the issue where the "show grants" command returned an incorrect number of columns
20. fix: unexpected backup points before schedule executing
21. fix: taosX task does not restart after interrupted
22. fix: jdbc select server_version() caused mem high-usage
23. fix: when using the WHERE tbname IN () statement, executing LAST query may cause taosd crash if the subtables filtered out do not belong to the same super table
24. fix: after taosd exits abnormally and is restarted, if the WAL that has not been written to the data file is too large, it may cause an OOM error during startup
25. fix: when using interp interpolation, if the select list contains string constants or string tags, the returned string content may be incomplete.[#29353](https://github.com/taosdata/TDengine/issues/29353)
26. fix: when performing a JOIN query on a super table, using a subquery as the right table may lead to missing results
27. fix: syntax error while use DISTINCT and ORDER BY together.[#29263](https://github.com/taosdata/TDengine/issues/29263)
28. fix: when using the CAST function to convert a floating-point number to a binary and then performing a comparison, the result may be inaccurate due to loss of precision[#29382](https://github.com/taosdata/TDengine/issues/29382)
29. fix: after upgrading from version 3.3.4 to 3.3.5, the taosd service fails to start properly if the configured charset does not exist in the system
30. fix: websocket api timing field should not be negtive
31. fix: duplicates backup points in taosX
32. fix: configuration item s3BucketName was incorrectly set as a global variable, leading to failures while file uploads to S3.

14
docs/en/29-roadmap/index.md Normal file
View File

@ -0,0 +1,14 @@
---
title: Product Roadmap
---
The 2025 roadmap for TDengine OSS is described in the following table.
| Quarter | Feature |
| :----- | :----- |
| 2025Q1 | <ol><li>Virtual tables</li><li>Query engine: conditional expressions in <code>REGEXP</code>, <code>GREATEST</code>, <code>LEAST</code>, and <code>CAST</code> functions; improvements in single-row selection functions; time range interpolation with <code>INTERP</code></li><li>Storage engine: support for writing query results into supertables; <code>KEEP</code> parameter for supertables; performance improvements for the parameter binding interface</li><li>Stream processing: support for virtual tables; decreased compute resource usage; new mechanism for event notification; faster stream creation</li><li>Data types: support for the decimal data type</li><li>High availability: faster recovery from downtime; improved client failover</li><li>Stability: LTS release TDengine 3.3.6.x</li><li>JDBC driver: more efficient data ingestion</li><li>Ecosystem: integration with Microsoft Excel</li></ol> |
| 2025Q2 | <ol><li>Query engine: relaxed restrictions on <code>JOIN</code> queries; support for all mathematical functions in MySQL; integral, integral average, and continuous variance functions; optimization of the <code>CSUM</code> function; support for <code>COUNT(DISTINCT)</code> syntax; enhancements to event windows; faster filtering by tag; faster <code>INTERP</code> queries</li><li>Storage engine: decreased compute resource usage for TSMAs; improved write jitter</li><li>Stream processing: high availability of snodes</li><li>Data types: support for the blob data type</li><li>Data subscription: support for the MQTT protocol</li><li>High availability: faster replica configuration changes; faster recovery from downtime for clusters; improved data recovery after power outage</li><li>Observability: diagnostic tool for data ingestion</li></ol> |
| 2025Q3 | <ol><li>Query engine: more subqueries; support for all operators in MySQL; support for all time functions in MySQL; improved window calculation; reduced jitter in query performance; support for specifying columns in count windows</li><li>Storage engine: faster ingestion in SQL mode</li><li>Observability: diagnostic tool for queries; improved <code>EXPLAIN</code> output; monitoring of long-running tasks</li></ol> |
| 2025Q4 | <ol><li>Query engine: window functions (i.e. the <code>OVER</code> clause); support for all string, aggregation, and conditional functions in MySQL; sorting within groups for partition queries; controls for query resource usage; faster aggregate queries on subtables; time range interpolation in <code>INTERVAL</code> windows</li><li>Data types: support for variable-length strings</li><li>Caching: faster row-oriented caching</li><li>Observability: more insight into operations and maintenance</li></ol> |
For more information, see [TDengine Public Roadmap](https://github.com/orgs/taosdata/projects/4).

BIN
docs/en/assets/architecture-01.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 52 KiB

After

Width:  |  Height:  |  Size: 268 KiB

BIN
docs/en/assets/architecture-02.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 75 KiB

BIN
docs/en/assets/architecture-03.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 64 KiB

After

Width:  |  Height:  |  Size: 216 KiB

BIN
docs/en/assets/architecture-04.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 51 KiB

After

Width:  |  Height:  |  Size: 184 KiB

BIN
docs/en/assets/data-compression-01.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 243 KiB

After

Width:  |  Height:  |  Size: 334 KiB

BIN
docs/en/assets/data-querying-01.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 24 KiB

After

Width:  |  Height:  |  Size: 103 KiB

BIN
docs/en/assets/data-querying-03.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 47 KiB

BIN
docs/en/assets/data-querying-04.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 164 KiB

After

Width:  |  Height:  |  Size: 95 KiB

BIN
docs/en/assets/data-subscription-engine-01.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 162 KiB

BIN
docs/en/assets/data-subscription-engine-02.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 48 KiB

After

Width:  |  Height:  |  Size: 293 KiB

BIN
docs/en/assets/data-subscription-engine-03.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 90 KiB

BIN
docs/en/assets/data-subscription-engine-04.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 103 KiB

After

Width:  |  Height:  |  Size: 263 KiB

BIN
docs/en/assets/data-subscription-engine-05.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 282 KiB

After

Width:  |  Height:  |  Size: 162 KiB

BIN
docs/en/assets/data-subscription-engine-06.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 51 KiB

BIN
docs/en/assets/data-subscription-engine-07.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 52 KiB

After

Width:  |  Height:  |  Size: 90 KiB

BIN
docs/en/assets/mqtt-05.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 64 KiB

After

Width:  |  Height:  |  Size: 57 KiB

BIN
docs/en/assets/query-engine-01.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 338 KiB

After

Width:  |  Height:  |  Size: 264 KiB

BIN
docs/en/assets/query-engine-02.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 501 KiB

After

Width:  |  Height:  |  Size: 342 KiB

BIN
docs/en/assets/storage-engine-01.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 93 KiB

After

Width:  |  Height:  |  Size: 63 KiB

BIN
docs/en/assets/storage-engine-02.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 140 KiB

After

Width:  |  Height:  |  Size: 91 KiB

BIN
docs/en/assets/storage-engine-03.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 96 KiB

After

Width:  |  Height:  |  Size: 68 KiB

BIN
docs/en/assets/storage-engine-04.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 149 KiB

After

Width:  |  Height:  |  Size: 140 KiB

BIN
docs/en/assets/storage-engine-05.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 131 KiB

After

Width:  |  Height:  |  Size: 109 KiB

BIN
docs/en/assets/storage-engine-06.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 117 KiB

After

Width:  |  Height:  |  Size: 137 KiB

BIN
docs/en/assets/storage-engine-07.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 133 KiB

After

Width:  |  Height:  |  Size: 82 KiB

BIN
docs/en/assets/storage-engine-08.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 141 KiB

After

Width:  |  Height:  |  Size: 200 KiB

BIN
docs/en/assets/storage-engine-09.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 70 KiB

After

Width:  |  Height:  |  Size: 107 KiB

BIN
docs/en/assets/storage-engine-10.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 65 KiB

After

Width:  |  Height:  |  Size: 57 KiB

BIN
docs/en/assets/storage-engine-11.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 178 KiB

After

Width:  |  Height:  |  Size: 135 KiB

BIN
docs/en/assets/stream-processing-engine-01.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 190 KiB

After

Width:  |  Height:  |  Size: 283 KiB

BIN
docs/en/assets/stream-processing-engine-02.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 68 KiB

BIN
docs/en/assets/stream-processing-engine-03.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 61 KiB

After

Width:  |  Height:  |  Size: 80 KiB

14
docs/zh/01-index.md
View File

@ -4,19 +4,19 @@ sidebar_label: 文档首页
slug: /
---
TDengine 是一款[开源](https://www.taosdata.com/tdengine/open_source_time-series_database)、[高性能](https://www.taosdata.com/fast)、[云原生](https://www.taosdata.com/tdengine/cloud_native_time-series_database)的<a href="https://www.taosdata.com/" data-internallinksmanager029f6b8e52c="2" title="时序数据库" target="_blank" rel="noopener">时序数据库</a>（<a href="https://www.taosdata.com/time-series-database" data-internallinksmanager029f6b8e52c="9" title="Time Series DataBase" target="_blank" rel="noopener">Time Series Database</a>, <a href="https://www.taosdata.com/tsdb" data-internallinksmanager029f6b8e52c="8" title="TSDB" target="_blank" rel="noopener">TSDB</a>）, 它专为物联网、车联网、工业互联网、金融、IT 运维等场景优化设计。同时它还带有内建的缓存、流式计算、数据订阅等系统功能，能大幅减少系统设计的复杂度，降低研发和运营成本，是一款极简的时序数据处理平台。本文档是 TDengine 的用户手册，主要是介绍 TDengine 的基本概念、安装、使用、功能、开发接口、运营维护、TDengine 内核设计等等，它主要是面向架构师、开发工程师与系统管理员的。如果你对时序数据的基本概念、价值以及其所能带来的业务价值尚不了解，请参考[时序数据基础](./concept)。
TDengine 是一款 [开源](https://www.taosdata.com/tdengine/open_source_time-series_database)、[高性能](https://www.taosdata.com/fast)、[云原生](https://www.taosdata.com/tdengine/cloud_native_time-series_database) 的<a href="https://www.taosdata.com/" data-internallinksmanager029f6b8e52c="2" title="时序数据库" target="_blank" rel="noopener">时序数据库</a>（<a href="https://www.taosdata.com/time-series-database" data-internallinksmanager029f6b8e52c="9" title="Time Series DataBase" target="_blank" rel="noopener">Time Series Database</a>, <a href="https://www.taosdata.com/tsdb" data-internallinksmanager029f6b8e52c="8" title="TSDB" target="_blank" rel="noopener">TSDB</a>）, 它专为物联网、车联网、工业互联网、金融、IT 运维等场景优化设计。同时它还带有内建的缓存、流式计算、数据订阅等系统功能，能大幅减少系统设计的复杂度，降低研发和运营成本，是一款极简的时序数据处理平台。本文档是 TDengine 的用户手册，主要是介绍 TDengine 的基本概念、安装、使用、功能、开发接口、运营维护、TDengine 内核设计等等，它主要是面向架构师、开发工程师与系统管理员的。如果你对时序数据的基本概念、价值以及其所能带来的业务价值尚不了解，请参考 [时序数据基础](./concept)。
TDengine 充分利用了时序数据的特点，提出了“一个数据采集点一张表”与“超级表”的概念，设计了创新的存储引擎，让数据的写入、查询和存储效率都得到极大的提升。为正确理解并使用 TDengine，无论你在工作中是什么角色，请您仔细阅读[数据模型](./basic/model)一章。
TDengine 充分利用了时序数据的特点，提出了“一个数据采集点一张表”与“超级表”的概念，设计了创新的存储引擎，让数据的写入、查询和存储效率都得到极大的提升。为正确理解并使用 TDengine，无论你在工作中是什么角色，请您仔细阅读 [数据模型](./basic/model) 一章。
如果你是开发工程师，请一定仔细阅读[开发指南](./develop)一章，该部分对数据库连接、建模、写入、查询、流式计算、缓存、数据订阅、用户自定义函数等功能都做了详细介绍，并配有各种编程语言的示例代码。大部分情况下，只要复制粘贴示例代码，针对自己的应用稍作改动，就能跑起来。对 REST API、各种编程语言的连接器（Connector）想做更多详细了解，请看[连接器](./reference/connector)一章。
如果你是开发工程师，请一定仔细阅读 [开发指南](./develop) 一章，该部分对数据库连接、建模、写入、查询、流式计算、缓存、数据订阅、用户自定义函数等功能都做了详细介绍，并配有各种编程语言的示例代码。大部分情况下，只要复制粘贴示例代码，针对自己的应用稍作改动，就能跑起来。对 REST API、各种编程语言的连接器（Connector）想做更多详细了解，请看 [连接器](./reference/connector) 一章。
我们已经生活在大数据时代，纵向扩展已经无法满足日益增长的业务需求，任何系统都必须具有水平扩展的能力，集群成为大数据以及 Database 系统的不可缺失功能。TDengine 团队不仅实现了集群功能，而且将这一重要核心功能开源。怎么部署、管理和维护 TDengine 集群，请仔细参考[运维管理](./operation)一章。
我们已经生活在大数据时代，纵向扩展已经无法满足日益增长的业务需求，任何系统都必须具有水平扩展的能力，集群成为大数据以及 Database 系统的不可缺失功能。TDengine 团队不仅实现了集群功能，而且将这一重要核心功能开源。怎么部署、管理和维护 TDengine 集群，请仔细参考 [运维管理](./operation) 一章。
TDengine 采用 SQL 作为查询语言，大大降低学习成本、降低迁移成本，但同时针对时序数据场景，又做了一些扩展，以支持插值、降采样、时间加权平均等操作。[SQL 手册](./reference/taos-sql)一章详细描述了 SQL 语法、详细列出了各种支持的命令和函数。
TDengine 采用 SQL 作为查询语言，大大降低学习成本、降低迁移成本，但同时针对时序数据场景，又做了一些扩展，以支持插值、降采样、时间加权平均等操作。[SQL 手册](./reference/taos-sql) 一章详细描述了 SQL 语法、详细列出了各种支持的命令和函数。
如果你是系统管理员，关心安装、升级、容错灾备、关心数据导入、导出、配置参数，如何监测 TDengine 是否健康运行，如何提升系统运行的性能，请仔细参考[运维指南](./operation)一章。
如果你是系统管理员，关心安装、升级、容错灾备、关心数据导入、导出、配置参数，如何监测 TDengine 是否健康运行，如何提升系统运行的性能，请仔细参考 [运维指南](./operation) 一章。
如果你对数据库内核设计感兴趣，或是开源爱好者，建议仔细阅读[技术内幕](./tdinternal)一章。该章从分布式架构到存储引擎、查询引擎、数据订阅，再到流计算引擎都做了详细阐述。建议对照文档，查看 TDengine 在 GitHub 的源代码，对 TDengine 的设计和编码做深入了解，更欢迎加入开源社区，贡献代码。
如果你对数据库内核设计感兴趣，或是开源爱好者，建议仔细阅读 [技术内幕](./tdinternal) 一章。该章从分布式架构到存储引擎、查询引擎、数据订阅，再到流计算引擎都做了详细阐述。建议对照文档，查看 TDengine 在 GitHub 的源代码，对 TDengine 的设计和编码做深入了解，更欢迎加入开源社区，贡献代码。
最后，作为一个开源软件，欢迎大家的参与。如果发现文档有任何错误、描述不清晰的地方，请在每个页面的最下方，点击“编辑本文档”直接进行修改。

4
docs/zh/03-intro.md
View File

@ -6,7 +6,7 @@ toc_max_heading_level: 4
TDengine 是一个高性能、分布式的时序数据库。通过集成的缓存、数据订阅、流计算和数据清洗与转换等功能，TDengine 已经发展成为一个专为物联网、工业互联网、金融和 IT 运维等关键行业量身定制的时序大数据平台。该平台能够高效地汇聚、存储、分析、计算和分发来自海量数据采集点的大规模数据流，每日处理能力可达 TB 乃至 PB 级别。借助 TDengine，企业可以实现实时的业务监控和预警，进而发掘出有价值的商业洞察。
自 2019 年 7 月 以来， 涛思数据陆续将 TDengine 的不同版本开源，包括单机版（2019 年 7 月）、集群版（2020 年 8 月）以及云原生版（2022 年 8 月）。开源之后，TDengine 迅速获得了全球开发者的关注，多次在 GitHub 网站全球趋势排行榜上位居榜首，最新的关注热度见[涛思数据首页](https://www.taosdata.com/)。
自 2019 年 7 月 以来， 涛思数据陆续将 TDengine 的不同版本开源，包括单机版（2019 年 7 月）、集群版（2020 年 8 月）以及云原生版（2022 年 8 月）。开源之后，TDengine 迅速获得了全球开发者的关注，多次在 GitHub 网站全球趋势排行榜上位居榜首，最新的关注热度见 [涛思数据首页](https://www.taosdata.com/)。
## TDengine 产品
@ -16,7 +16,7 @@ TDengine OSS 是一个开源的高性能时序数据库，与其他时序数据
在 TDengine OSS 的基础上，TDengine Enterprise 提供了增强的辅助功能，包括数据的备份恢复、异地容灾、多级存储、视图、权限控制、安全加密、IP 白名单、支持 MQTT、OPC-UA、OPC-DA、PI、Wonderware、Kafka 等各种数据源。这些功能为企业提供了更为全面、安全、可靠和高效的时序数据管理解决方案。更多的细节请看 [TDengine Enterprise](https://www.taosdata.com/tdengine-pro)。
此外，TDengine Cloud 作为一种全托管的云服务，存储与计算分离，分开计费，为企业提供了企业级的工具和服务，彻底解决了运维难题，尤其适合中小规模的用户使用。更多的细节请看[TDengine 云服务](https://cloud.taosdata.com/?utm_source=menu&utm_medium=webcn)
此外，TDengine Cloud 作为一种全托管的云服务，存储与计算分离，分开计费，为企业提供了企业级的工具和服务，彻底解决了运维难题，尤其适合中小规模的用户使用。更多的细节请看 [TDengine 云服务](https://cloud.taosdata.com/?utm_source=menu&utm_medium=webcn)。
## TDengine 主要功能与特性

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

@ -111,7 +111,7 @@ TDengine 还支持直接向超级表写入数据。需要注意的是，超级
```sql
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)
values("d1001", "2018-10-03 14:38:05", 10.2, 220, 0.23, "California.SanFrancisco", 2)
```
### 零代码写入

24
docs/zh/05-basic/03-query.md
View File

@ -4,6 +4,10 @@ title: TDengine 数据查询
toc_max_heading_level: 4
---
import win from './window.png';
import swin from './session-window.png';
import ewin from './event-window.png';
相较于其他众多时序数据库和实时数据库，TDengine 的一个独特优势在于，自其首个版本发布之初便支持标准的 SQL 查询功能。这一特性极大地降低了用户在使用过程中的学习难度。本章将以智能电表的数据模型为例介绍如何在 TDengine 中运用 SQL 查询来处理时序数据。如果需要进一步了解 SQL 语法的细节和功能，建议参阅 TDengine 的官方文档。通过本章的学习，你将能够熟练掌握 TDengine 的 SQL 查询技巧，进而高效地对时序数据进行操作和分析。
## 基本查询
@ -136,16 +140,15 @@ Query OK, 10 row(s) in set (2.415961s)
在 TDengine 中，你可以使用窗口子句来实现按时间窗口切分方式进行聚合结果查询，这种查询方式特别适用于需要对大量时间序列数据进行分析的场景，例如智能电表每 10s 采集一次数据，但需要查询每隔 1min 的温度平均值。
窗口子句允许你针对查询的数据集合按照窗口进行切分，并对每个窗口内的数据进行聚合，包含：
- 时间窗口（time window）
- 状态窗口（status window）
- 会话窗口（session window）
- 事件窗口（event window）
- 计数窗口（count window）
窗口子句允许你针对查询的数据集合按照窗口进行切分，并对每个窗口内的数据进行聚合。窗口划分逻辑如下图所示。
窗口划分逻辑如下图所示：
<img src={win} width="500" alt="常用窗口划分逻辑" />
![常用窗口划分逻辑](./window.png)
- 时间窗口（time window）：根据时间间隔划分数据，支持滑动时间窗口和翻转时间窗口，适用于按固定时间周期进行数据聚合。
- 状态窗口（status window）：基于设备状态值的变化划分窗口，相同状态值的数据归为一个窗口，状态值改变时窗口关闭。
- 会话窗口（session window）：根据记录的时间戳差异划分会话，时间戳间隔小于预设值的记录属于同一会话。
- 事件窗口（event window）：基于事件的开始条件和结束条件动态划分窗口，满足开始条件时窗口开启，满足结束条件时窗口关闭。
- 计数窗口（count window）：根据数据行数划分窗口，每达到指定行数即为一个窗口，并进行聚合计算。
窗口子句语法如下：
@ -408,7 +411,8 @@ Query OK, 22 row(s) in set (0.153403s)
会话窗口根据记录的时间戳主键的值来确定是否属于同一个会话。如下图所示，如果设置时间戳的连续的间隔小于等于 12 秒，则以下 6 条记录构成 2 个会话窗口，分别是：[2019-04-28 14:22:10，2019-04-28 14:22:30] 和 [2019-04-28 14:23:10，2019-04-28 14:23:30]。因为 2019-04-28 14:22:30 与 2019-04-28 14:23:10 之间的时间间隔是 40 秒，超过了连续时间间隔（12 秒）。
![会话窗口示意图](./session-window.png)
<img src={swin} width="320" alt="会话窗口示意图" />
在 tol_value 时间间隔范围内的结果都认为归属于同一个窗口，如果连续的两条记录的时间超过 tol_val，则自动开启下一个窗口。
@ -461,7 +465,7 @@ Query OK, 10 row(s) in set (0.043489s)
select _wstart, _wend, count(*) from t event_window start with c1 > 0 end with c2 < 10
```
![事件窗口示意图](./event-window.png)
<img src={ewin} width="350" alt="事件窗口示意图" />
示例 SQL:

BIN
docs/zh/05-basic/event-window.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 188 KiB

After

Width:  |  Height:  |  Size: 95 KiB

BIN
docs/zh/05-basic/session-window.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 47 KiB

BIN
docs/zh/05-basic/window.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 188 KiB

After

Width:  |  Height:  |  Size: 97 KiB

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

@ -154,8 +154,8 @@ let v3 = data["voltage"].split(",");
如下图所示
* 对字段`ts`使用 split 规则拆分成日期和时间。split 规则需要设置**分隔符**和**拆分数量**，拆分后的字段命名规则为`{原字段名}_{顺序号}`。
* 对字段`voltage`使用正则表达式 `^(?<voltage>[0-9]+)(?<voltage_unit>[a-zA-Z]+)$` 提取出电压值和电压单位，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)

11
docs/zh/06-advanced/06-TDgpt/07-faq.md
View File

@ -3,7 +3,12 @@ title: "常见问题"
sidebar_label: "常见问题"
---
<b>1. 创建 anode 失败，返回指定服务无法访问</b>
### 1. 安装过程中编译 uWSGI 失败，如何处理
TDgpt 安装过程中需要在本地编译 uWSGI，某些环境的 Python（例如：anaconda）安装 uWSGI 会出现冲突导致编译失败，安装流程因此无法继续下去。这种情况下可以尝试在安装过程中忽略 uWSGI的安装。
由于忽略了 uWSGI 安装，后续启动 taosasnode 服务的时候，需要手动输入命令进行启动 `python3.10 /usr/local/taos/taosanode/lib/taosanalytics/app.py` 。 执行该命令的时候请确保使用了虚拟环境中的 Python 程序才能加载依赖库。
### 2. 创建 anode 失败，返回指定服务无法访问
```bash
taos> create anode '127.0.0.1:6090';
@ -26,7 +31,7 @@ curl: (7) Failed to connect to 127.0.0.1 port 6090: Connection refused
>请勿使用 systemctl status taosanode 检查 taosanode 是否正常
<b>2. 服务正常，查询过程返回服务不可用</b>
### 3. 服务正常，查询过程返回服务不可用
```bash
taos> select _frowts,forecast(current, 'algo=arima, alpha=95, wncheck=0, rows=20') from d1 where ts<='2017-07-14 10:40:09.999';
@ -34,7 +39,7 @@ DB error: Analysis service can't access[0x80000441] (60.195613s)
```
数据分析默认超时时间是 60s，出现这个问题的原因是输入数据分析过程超过默认的最长等待时间，请尝试采用限制数据输入范围的方式将输入数据规模减小或者更换分析算法再次尝试。
<b>3. 返回结果出现非法 JSON 格式错误 (Invalid json format) </b>
### 4. 返回结果出现非法 JSON 格式错误 (Invalid json format)
从 anode 返回到 TDengine 的分析结果有误，请检查 anode 运行日志 `/var/log/taos/taosanode/taosanode.app.log`，以便于获得具体的错误信息。

6
docs/zh/07-develop/02-sql.md
View File

@ -7,7 +7,7 @@ toc_max_heading_level: 4
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
TDengine 对 SQL 语言提供了全面的支持，允许用户以熟悉的 SQL 语法进行数据的查询、插入和删除操作。 TDengine 的 SQL 还支持对数据库和数据表的管理操作，如创建、修改和删除数据库及数据表。TDengine 扩展了标准 SQL，引入了时序数据处理特有的功能，如时间序列数据的聚合查询、降采样、插值查询等，以适应时序数据的特点。这些扩展使得用户可以更高效地处理时间序列数据，进行复杂的数据分析和处理。 具体支持的 SQL 语法请参考 [TDengine SQL](../../reference/taos-sql/)
TDengine 对 SQL 语言提供了全面的支持，允许用户以熟悉的 SQL 语法进行数据的查询、插入和删除操作。TDengine 的 SQL 还支持对数据库和数据表的管理操作，如创建、修改和删除数据库及数据表。TDengine 扩展了标准 SQL，引入了时序数据处理特有的功能，如时间序列数据的聚合查询、降采样、插值查询等，以适应时序数据的特点。这些扩展使得用户可以更高效地处理时间序列数据，进行复杂的数据分析和处理。具体支持的 SQL 语法请参考 [TDengine SQL](../../reference/taos-sql/)
下面介绍使用各语言连接器通过执行 SQL 完成建库、建表、写入数据和查询数据。
@ -108,7 +108,7 @@ curl --location -uroot:taosdata 'http://127.0.0.1:6041/rest/sql/power' \
```
**Note**
NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW + 1s 代表客户端当前时间往后加 1 秒，数字后面代表时间单位：a（毫秒），s（秒），m（分），h（小时），d（天），w（周），n（月），y（年）。
NOW 为系统内部函数，默认为客户端所在计算机当前时间。NOW + 1s 代表客户端当前时间往后加 1 秒，数字后面代表时间单位：a（毫秒），s（秒），m（分），h（小时），d（天），w（周），n（月），y（年）。
</TabItem>
@ -160,7 +160,7 @@ NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW
```
**Note**
NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW + 1s 代表客户端当前时间往后加 1 秒，数字后面代表时间单位：a（毫秒），s（秒），m（分），h（小时），d（天），w（周），n（月），y（年）。
NOW 为系统内部函数，默认为客户端所在计算机当前时间。NOW + 1s 代表客户端当前时间往后加 1 秒，数字后面代表时间单位：a（毫秒），s（秒），m（分），h（小时），d（天），w（周），n（月），y（年）。
</TabItem>
<TabItem label="REST API" value="rest">

43
docs/zh/07-develop/04-schemaless.md
View File

@ -17,7 +17,7 @@ import TabItem from "@theme/TabItem";
## 无模式写入行协议
TDengine 的无模式写入行协议兼容 InfluxDB 的行协议、OpenTSDB 的 telnet 行协议和 OpenTSDB 的 JSON 格式协议。InfluxDB、OpenTSDB 的标准写入协议请参考各自的官方文档。
TDengine 的无模式写入行协议兼容 InfluxDB 的行协议、OpenTSDB 的 TELNET 行协议和 OpenTSDB 的 JSON 格式协议。InfluxDB、OpenTSDB 的标准写入协议请参考各自的官方文档。
下面首先以 InfluxDB 的行协议为基础，介绍 TDengine 扩展的协议内容。该协议允许用户采用更加精细的方式控制（超级表）模式。采用一个字符串来表达一个数据行，可以向写入 API 中一次传入多行字符串来实现多个数据行的批量写入，其格式约定如下。
@ -36,7 +36,7 @@ tag_set 中的所有的数据自动转化为 nchar 数据类型，并不需要
在无模式写入数据行协议中，field_set 中的每个数据项都需要对自身的数据类型进行描述，具体要求如下。
- 如果两边有英文双引号，表示 varchar 类型，例如 "abc"。
- 如果两边有英文双引号而且带有 L 或 l 前缀，表示 nchar 类型，例如 L" 报错信息 "。
- 如果两边有英文双引号而且带有 G 或 g 前缀， 表 示 geometry 类型， 例 如G"Point(4.343 89.342)"。
- 如果两边有英文双引号而且带有 G 或 g 前缀，表示 geometry 类型，例如 G"Point(4.343 89.342)"。
- 如果两边有英文双引号而且带有 B 或 b 前缀，表示 varbinary 类型，双引号内可以为 \x 开头的十六进制或者字符串，例如 B"\x98f46e" 和 B"hello"。
- 对于空格、等号（=）、逗号（,）、双引号（"）、反斜杠（\），前面需要使用反斜杠（\）进行转义（均为英文半角符号）。无模式写入协议的域转义规则如下表所示。
@ -48,7 +48,7 @@ tag_set 中的所有的数据自动转化为 nchar 数据类型，并不需要
| 4 | 列名 | 逗号，等号，空格 |
| 5 | 列值 | 双引号，反斜杠 |
如果使用两个连续的反斜杠，则第1个反斜杠作为转义符，当只有一个反斜杠时则无须转义。无模式写入协议的反斜杠转义规则如下表所示。
如果使用两个连续的反斜杠，则第 1 个反斜杠作为转义符，当只有一个反斜杠时则无须转义。无模式写入协议的反斜杠转义规则如下表所示。
| **序号** | **反斜杠** | **转义为** |
| -------- | ------------ | ---------- |
@ -70,10 +70,9 @@ tag_set 中的所有的数据自动转化为 nchar 数据类型，并不需要
| 5 | i32/u32 | Int/UInt | 4 |
| 6 | i64/i/u64/u | BigInt/BigInt/UBigInt/UBigInt | 8 |
- t, T, true, True, TRUE, f, F, false, False 将直接作为 BOOL 型来处理。
- t、T、true、True、TRUE、f、F、false、False 将直接作为 BOOL 型来处理。
例如如下数据行表示：向名为 st 的超级表下的 t1 标签为 "3"（NCHAR）、t2 标签为 "4"（NCHAR）、t3
标签为 "t3"（NCHAR）的数据子表，写入 c1 列为 3（BIGINT）、c2 列为 false（BOOL）、c3
例如如下数据行表示：向名为 st 的超级表下的 t1 标签为 "3"（NCHAR）、t2 标签为 "4"（NCHAR）、t3 标签为 "t3"（NCHAR）的数据子表，写入 c1 列为 3（BIGINT）、c2 列为 false（BOOL）、c3
列为 "passit"（BINARY）、c4 列为 4（DOUBLE）、主键时间戳为 1626006833639000000 的一行数据。
```json
@ -94,30 +93,28 @@ TDengine 提供数据写入的幂等性保证，即您可以反复调用 API 进
"measurement,tag_key1=tag_value1,tag_key2=tag_value2"
```
- 需要注意的是，这里的 tag_key1, tag_key2 并不是用户输入的标签的原始顺序，而是使用了标签名称按照字符串升序排列后的结果。所以，tag_key1 并不是在行协议中输入的第一个标签。
排列完成以后计算该字符串的 MD5 散列值 "md5_val"。然后将计算的结果与字符串组合生成表名：“t_md5_val”。其中的 “t_” 是固定的前缀，每个通过该映射关系自动生成的表都具有该前缀。
- 需要注意的是，这里的 tag_key1、tag_key2 并不是用户输入的标签的原始顺序，而是使用了标签名称按照字符串升序排列后的结果。所以，tag_key1 并不是在行协议中输入的第一个标签。
排列完成以后计算该字符串的 MD5 散列值 "md5_val"。然后将计算的结果与字符串组合生成表名："t_md5_val"。其中的 "t_" 是固定的前缀，每个通过该映射关系自动生成的表都具有该前缀。
- 如果不想用自动生成的表名，有两种指定子表名的方式(第一种优先级更高)。
1. 通过在taos.cfg里配置 smlAutoChildTableNameDelimiter 参数来指定（`@ # 空格 回车 换行 制表符`除外)。
1. 举例如下：配置 smlAutoChildTableNameDelimiter=- 插入数据为 st,t0=cpu1,t1=4 c1=3 1626006833639000000 则创建的表名为 cpu1-4。
2. 通过在taos.cfg里配置 smlChildTableName 参数来指定。
1. 举例如下：配置 smlChildTableName=tname 插入数据为 st,tname=cpu1,t1=4 c1=3 1626006833639000000 则创建的表名为 cpu1，注意如果多行数据 tname 相同，但是后面的 tag_set 不同，则使用第一行自动建表时指定的 tag_set，其他的行会忽略。
- 如果不想用自动生成的表名，有两种指定子表名的方式(第一种优先级更高)。
- 通过在 taos.cfg 里配置 smlAutoChildTableNameDelimiter 参数来指定（`@ # 空格 回车 换行 制表符` 除外)，例如配置 smlAutoChildTableNameDelimiter=- 插入数据为 st,t0=cpu1,t1=4 c1=3 1626006833639000000 则创建的表名为 cpu1-4。
- 通过在 taos.cfg 里配置 smlChildTableName 参数来指定，例如配置 smlChildTableName=tname 插入数据为 st,tname=cpu1,t1=4 c1=3 1626006833639000000 则创建的表名为 cpu1，注意如果多行数据 tname 相同，但是后面的 tag_set 不同，则使用第一行自动建表时指定的 tag_set，其他的行会忽略。
2. 如果解析行协议获得的超级表不存在，则会创建这个超级表（不建议手动创建超级表，不然插入数据可能异常）。
3. 如果解析行协议获得子表不存在，则 Schemaless 会按照步骤 1 或 2 确定的子表名来创建子表。
3. 如果解析行协议获得子表不存在，则 schemaless 会按照步骤 1 或 2 确定的子表名来创建子表。
4. 如果数据行中指定的标签列或普通列不存在，则在超级表中增加对应的标签列或普通列（只增不减）。
5. 如果超级表中存在一些标签列或普通列未在一个数据行中被指定取值，那么这些列的值在这一行中会被置为 NULL。
6. 对 BINARY 或 NCHAR 列，如果数据行中所提供值的长度超出了列类型的限制，自动增加该列允许存储的字符长度上限（只增不减），以保证数据的完整保存。
7. 整个处理过程中遇到的错误会中断写入过程，并返回错误代码。
8. 为了提高写入的效率，默认假设同一个超级表中 field_set 的顺序是一样的（第一条数据包含所有的 field，后面的数据按照这个顺序），如果顺序不一样，需要配置参数 smlDataFormat 为 false，否则，数据写入按照相同顺序写入，库中数据会异常，从3.0.3.0开始，自动检测顺序是否一致，该配置废弃。
9. 由于sql建表表名不支持点号（.），所以schemaless也对点号（.）做了处理，如果schemaless自动建表的表名如果有点号（.），会自动替换为下划线（\_）。如果手动指定子表名的话，子表名里有点号（.），同样转化为下划线（\_）。
10. taos.cfg 增加 smlTsDefaultName 配置（值为字符串），只在client端起作用，配置后，schemaless自动建表的时间列名字可以通过该配置设置。不配置的话，默认为 _ts。
8. 为了提高写入的效率，默认假设同一个超级表中 field_set 的顺序是一样的（第一条数据包含所有的 field，后面的数据按照这个顺序），如果顺序不一样，需要配置参数 smlDataFormat 为 false，否则，数据写入按照相同顺序写入，库中数据会异常，从 3.0.3.0 开始，自动检测顺序是否一致，该配置废弃。
9. 由于 sql 建表表名不支持点号（.），所以 schemaless 也对点号（.）做了处理，如果 schemaless 自动建表的表名如果有点号（.），会自动替换为下划线（\_）。如果手动指定子表名的话，子表名里有点号（.），同样转化为下划线（\_）。
10. taos.cfg 增加 smlTsDefaultName 配置（字符串类型），只在 client 端起作用，配置后，schemaless 自动建表的时间列名字可以通过该配置设置。不配置的话，默认为 _ts。
11. 无模式写入的数据超级表或子表名区分大小写。
12. 无模式写入仍然遵循 TDengine 对数据结构的底层限制，例如每行数据的总长度不能超过 48KB（从 3.0.5.0 版本开始为 64KB），标签值的总长度不超过16KB。
12. 无模式写入仍然遵循 TDengine 对数据结构的底层限制，例如每行数据的总长度不能超过 48KB（从 3.0.5.0 版本开始为 64KB），标签值的总长度不超过 16KB。
## 时间分辨率识别
无模式写入支持3个指定的模式，如下表所示：
无模式写入支持 3 个指定的模式，如下表所示：
| **序号** | **值** | **说明** |
| -------- | ------------------- | ------------------------------- |
@ -141,13 +138,13 @@ TDengine 提供数据写入的幂等性保证，即您可以反复调用 API 进
## 数据模式映射规则
InfluxDB行协议的数据将被映射成具有模式的数据，其中，measurement映射为超级表名称，tag_set中的标签名称映射为数据模式中的标签名，field_set中的名称映射为列名称。例如下面的数据。
InfluxDB 行协议的数据将被映射成具有模式的数据，其中，measurement 映射为超级表名称，tag_set 中的标签名称映射为数据模式中的标签名，field_set 中的名称映射为列名称。例如下面的数据。
```json
st,t1=3,t2=4,t3=t3 c1=3i64,c3="passit",c2=false,c4=4f64 1626006833639000000
```
该行数据映射生成一个超级表： st， 其包含了 3 个类型为 nchar 的标签，分别是：t1, t2, t3。五个数据列，分别是 ts（timestamp），c1 (bigint），c3(binary)，c2 (bool), c4 (bigint）。映射成为如下 SQL 语句：
该行数据映射生成一个超级表：st， 其包含了 3 个类型为 nchar 的标签，分别是：t1、t2、t3。五个数据列，分别是 ts（timestamp）、c1 (bigint）、c3(binary)、c2 (bool)、c4 (bigint）。映射成为如下 SQL 语句：
```json
create stable st (_ts timestamp, c1 bigint, c2 bool, c3 binary(6), c4 bigint) tags(t1 nchar(1), t2 nchar(1), t3 nchar(2))
@ -164,7 +161,7 @@ st,t1=3,t2=4,t3=t3 c1=3i64,c3="passit",c2=false,c4=4 1626006833639000000
st,t1=3,t2=4,t3=t3 c1=3i64,c3="passit",c2=false,c4=4i 1626006833640000000
```
第一行的数据类型映射将 c4 列定义为 Double， 但是第二行的数据又通过数值后缀方式声明该列为 BigInt， 由此会触发无模式写入的解析错误。
第一行的数据类型映射将 c4 列定义为 Double， 但是第二行的数据又通过数值后缀方式声明该列为 bigInt， 由此会触发无模式写入的解析错误。
如果列前面的行协议将数据列声明为了 binary， 后续的要求长度更长的 binary 长度，此时会触发超级表模式的变更。
@ -299,7 +296,7 @@ writer.write(lineDemo, SchemalessProtocolType.LINE, SchemalessTimestampType.NANO
## 查询写入的数据
运行上节的样例代码，会在 power 数据库l中自动建表，我们可以通过 TDengine CLI 或者应用程序来查询数据。下面给出用 TDengine CLI 查询超级表和 meters 表数据的样例。
运行上节的样例代码，会在 power 数据库中自动建表，我们可以通过 TDengine CLI 或者应用程序来查询数据。下面给出用 TDengine CLI 查询超级表和 meters 表数据的样例。
```shell
taos> show power.stables;

10
docs/zh/07-develop/05-stmt.md
View File

@ -7,7 +7,7 @@ toc_max_heading_level: 4
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
通过参数绑定方式写入数据时，能避免SQL语法解析的资源消耗，从而显著提升写入性能。参数绑定能提高写入效率的原因主要有以下几点：
通过参数绑定方式写入数据时，能避免 SQL 语法解析的资源消耗，从而显著提升写入性能。参数绑定能提高写入效率的原因主要有以下几点：
- 减少解析时间：通过参数绑定，SQL 语句的结构在第一次执行时就已经确定，后续的执行只需要替换参数值，这样可以避免每次执行时都进行语法解析，从而减少解析时间。
- 预编译：当使用参数绑定时，SQL 语句可以被预编译并缓存，后续使用不同的参数值执行时，可以直接使用预编译的版本，提高执行效率。
@ -19,9 +19,9 @@ import TabItem from "@theme/TabItem";
我们只推荐使用下面两种形式的 SQL 进行参数绑定写入：
```sql
一、确定子表存在：
一、确定子表存在
1. INSERT INTO meters (tbname, ts, current, voltage, phase) VALUES(?, ?, ?, ?, ?)
二、自动建表：
二、自动建表
1. INSERT INTO meters (tbname, ts, current, voltage, phase, location, group_id) VALUES(?, ?, ?, ?, ?, ?, ?)
2. INSERT INTO ? USING meters TAGS (?, ?) VALUES (?, ?, ?, ?)
```
@ -50,7 +50,7 @@ import TabItem from "@theme/TabItem";
{{#include docs/examples/java/src/main/java/com/taos/example/WSParameterBindingExtendInterfaceDemo.java:para_bind}}
```
这是一个[更详细的参数绑定示例](https://github.com/taosdata/TDengine/blob/main/docs/examples/java/src/main/java/com/taos/example/WSParameterBindingFullDemo.java)
这是一个 [更详细的参数绑定示例](https://github.com/taosdata/TDengine/blob/main/docs/examples/java/src/main/java/com/taos/example/WSParameterBindingFullDemo.java)
</TabItem>
<TabItem label="Python" value="python">
@ -100,7 +100,7 @@ import TabItem from "@theme/TabItem";
{{#include docs/examples/java/src/main/java/com/taos/example/ParameterBindingBasicDemo.java:para_bind}}
```
这是一个[更详细的参数绑定示例](https://github.com/taosdata/TDengine/blob/main/docs/examples/java/src/main/java/com/taos/example/ParameterBindingFullDemo.java)
这是一个 [更详细的参数绑定示例](https://github.com/taosdata/TDengine/blob/main/docs/examples/java/src/main/java/com/taos/example/ParameterBindingFullDemo.java)
</TabItem>
<TabItem label="Python" value="python">

97
docs/zh/07-develop/07-tmq.md
View File

@ -10,13 +10,13 @@ import TabItem from "@theme/TabItem";
TDengine 提供了类似于消息队列产品的数据订阅和消费接口。在许多场景中，采用 TDengine 的时序大数据平台，无须再集成消息队列产品，从而简化应用程序设计并降低运维成本。本章介绍各语言连接器数据订阅的相关 API 以及使用方法。 数据订阅的基础知识请参考 [数据订阅](../../advanced/subscription/)
## 创建主题
请用 TDengine CLI 或者 参考 [执行 SQL](../sql/) 章节用程序执行创建主题的 SQL：`CREATE TOPIC IF NOT EXISTS topic_meters AS SELECT ts, current, voltage, phase, groupid, location FROM meters`
请用 TDengine CLI 或者参考 [执行 SQL](../sql/) 章节用程序执行创建主题的 SQL：`CREATE TOPIC IF NOT EXISTS topic_meters AS SELECT ts, current, voltage, phase, groupid, location FROM meters`
上述 SQL 将创建一个名为 topic_meters 的订阅。使用该订阅所获取的消息中的每条记录都由此查询语句 `SELECT ts, current, voltage, phase, groupid, location FROM meters` 所选择的列组成。
**注意**
在 TDengine 连接器实现中，对于订阅查询，有以下限制。
- 查询语句限制：订阅查询只能使用 select 语句，并不支持其他类型的SQL，如订阅库，订阅超级表（非 select 方式），insert、update 或 delete 等。
- 查询语句限制：订阅查询只能使用 select 语句，并不支持其他类型的 SQL，如订阅库、订阅超级表（非 select 方式）、insert、update 或 delete 等。
- 原始始数据查询：订阅查询只能查询原始数据，而不能查询聚合或计算结果。
- 时间顺序限制：订阅查询只能按照时间正序查询数据。
@ -28,25 +28,82 @@ TDengine 消费者的概念跟 Kafka 类似，消费者通过订阅主题来接
### 创建参数
创建消费者的参数较多，非常灵活的支持了各种连接类型、 Offset 提交方式、压缩、重连、反序列化等特性。各语言连接器都适用的通用基础配置项如下表所示：
| 参数名称 | 类型 | 参数说明 | 备注 |
| :-----------------------: | :-----: | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `td.connect.ip` | string | 服务端的 FQDN | 可以是ip或者host name |
| `td.connect.user` | string | 用户名 | |
| `td.connect.pass` | string | 密码 | |
| `td.connect.port` | integer | 服务端的端口号 | |
| `group.id` | string | 消费组 ID，同一消费组共享消费进度 | <br />**必填项**。最大长度：192，超长将截断。<br />每个topic最多可建立 100 个 consumer group |
| `client.id` | string | 客户端 ID | 最大长度：255，超长将截断。 |
| `auto.offset.reset` | enum | 消费组订阅的初始位置 | <br />`earliest`: default(version < 3.2.0.0);从头开始订阅; <br/>`latest`: default(version >= 3.2.0.0);仅从最新数据开始订阅; <br/>`none`: 没有提交的 offset 无法订阅 |
| `enable.auto.commit` | boolean | 是否启用消费位点自动提交，true: 自动提交，客户端应用无需commit；false：客户端应用需要自行commit | 默认值为 true |
| `auto.commit.interval.ms` | integer | 消费记录自动提交消费位点时间间隔，单位为毫秒 | 默认值为 5000 |
| `msg.with.table.name` | boolean | 是否允许从消息中解析表名, 不适用于列订阅（列订阅时可将 tbname 作为列写入 subquery 语句）（从 3.2.0.0 版本该参数废弃，恒为 true） | 默认关闭 |
| `enable.replay` | boolean | 是否开启数据回放功能 | 默认关闭 |
| `session.timeout.ms` | integer | consumer 心跳丢失后超时时间，超时后会触发 rebalance 逻辑，成功后该 consumer 会被删除（从 3.3.3.0 版本开始支持） | 默认值为 12000，取值范围 [6000， 1800000] |
| `max.poll.interval.ms` | integer | consumer poll 拉取数据间隔的最长时间，超过该时间，会认为该 consumer 离线，触发 rebalance 逻辑，成功后该 consumer 会被删除（从 3.3.3.0 版本开始支持） | 默认值为 300000，[1000，INT32_MAX] |
| `fetch.max.wait.ms` | integer | 服务端单次返回数据的最大耗时（从 3.3.6.0 版本开始支持） | 默认值为 1000，[1，INT32_MAX] |
| `min.poll.rows` | integer | 服务端单次返回数据的最小条数（从 3.3.6.0 版本开始支持） | 默认值为 4096，[1，INT32_MAX] |
| `msg.consume.rawdata` | integer | 消费数据时拉取数据类型为二进制类型，不可做解析操作，内部参数，只用于 taosX 数据迁移（从 3.3.6.0 版本开始支持） | 默认值为 0 表示不起效， 非 0 为 起效 |
#### td.connect.ip
- 说明：服务端的 FQDN
- 类型：string
- 备注：可以是 ip 或者 host name
#### td.connect.user
- 说明：用户名
- 类型：string
#### td.connect.pass
- 说明：密码
- 类型：string
#### td.connect.port
- 说明：服务端的端口号
- 类型：integer
#### group.id
- 说明：消费组 ID，同一消费组共享消费进度
- 类型：string
- 备注：**必填项**。最大长度：192，超长将截断。<br />每个topic最多可建立 100 个 consumer group
#### client.id
- 说明：客户端 ID
- 类型：string
- 备注：最大长度 255，超长将截断
#### auto.offset.reset
- 说明：消费组订阅的初始位置
- 类型：enum
- 备注：<br />`earliest`：default(version < 3.2.0.0)，从头开始订阅；<br/>`latest`：default(version >= 3.2.0.0)，仅从最新数据开始订阅；<br/>`none`：没有提交的 offset 无法订阅。
#### enable.auto.commit
- 说明：是否启用消费位点自动提交
- 类型：boolean
- 备注：true：自动提交，客户端应用无需 commit；false：客户端应用需要自行 commit；默认值为 true。
#### auto.commit.interval.ms
- 说明：消费记录自动提交消费位点时间间隔
- 类型：integer
- 备注：单位为毫秒，默认值为 5000
#### msg.with.table.name
- 说明：是否允许从消息中解析表名
- 类型：boolean
- 备注：不适用于列订阅（列订阅时可将 tbname 作为列写入 subquery 语句），默认关闭。v3.2.0.0 该参数废弃。
#### enable.replay
- 说明：是否开启数据回放功能
- 类型：boolean
- 备注：默认关闭
#### session.timeout.ms
- 说明：consumer 心跳丢失后超时时间
- 类型：integer
- 备注：超时后会触发 rebalance 逻辑，成功后该 consumer 会被删除。默认值为 12000，取值范围 [6000，1800000]。v3.3.3.0 开始支持）
#### max.poll.interval.ms
- 说明：consumer poll 拉取数据间隔的最长时间
- 类型：integer
- 备注：超过该时间，会认为该 consumer 离线，触发 rebalance 逻辑，成功后该 consumer 会被删除。默认值为 300000，[1000，INT32_MAX]。v3.3.3.0 开始支持。
#### fetch.max.wait.ms
- 说明：服务端单次返回数据的最大耗时
- 类型：integer
- 备注：默认值为 1000，[1，INT32_MAX]。v3.3.6.0 开始支持。
#### min.poll.rows
- 说明：服务端单次返回数据的最小条数
- 类型：integer
- 备注：默认值为 4096，[1，INT32_MAX]。v3.3.6.0 开始支持。
#### msg.consume.rawdata
- 说明：消费数据时拉取数据类型为二进制类型，不可做解析操作 `内部参数，只用于 taosX 数据迁移`
- 类型：integer
- 备注：默认值为 0 表示不起效，非 0 为起效。v3.3.6.0 开始支持。
下面是各语言连接器创建参数：
<Tabs defaultValue="java" groupId="lang">

26
docs/zh/07-develop/09-udf.md
View File

@ -107,7 +107,7 @@ int32_t scalarfn_destroy() {
```
### 聚合函数模板
用C语言开发聚合函数的模板如下。
用 C 语言开发聚合函数的模板如下。
```c
#include "taos.h"
#include "taoserror.h"
@ -292,13 +292,13 @@ select max_vol(vol1, vol2, vol3, deviceid) from battery;
### 准备环境
准备环境的具体步骤如下：
- 第1步，准备好 Python 运行环境。
- 第2步，安装 Python 包 taospyudf。命令如下。
- 第 1 步，准备好 Python 运行环境。
- 第 2 步，安装 Python 包 taospyudf。命令如下。
```shell
pip3 install taospyudf
```
- 第3步，执行命令 ldconfig。
- 第4步，启动 taosd 服务。
- 第 3 步，执行命令 ldconfig。
- 第 4 步，启动 taosd 服务。
安装过程中会编译 C++ 源码，因此系统上要有 cmake 和 gcc。编译生成的 libtaospyudf.so 文件自动会被复制到 /usr/local/lib/ 目录，因此如果是非 root 用户，安装时需加 sudo。安装完可以检查这个目录是否有了这个文件:
@ -323,7 +323,7 @@ def process(input: datablock) -> tuple[output_type]:
```
主要参数说明如下：
- input:datablock 类似二维矩阵，通过成员方法 data(row, col) 读取位于 row 行、col 列的 python 对象
- input:datablock 类似二维矩阵，通过成员方法 data(row, col) 读取位于 row 行、col 列的 Python 对象
- 返回值是一个 Python 对象元组，每个元素类型为输出类型。
#### 聚合函数接口
@ -389,7 +389,7 @@ def finish(buf: bytes) -> output_type:
### 数据类型映射
下表描述了TDengine SQL 数据类型和 Python 数据类型的映射。任何类型的 NULL 值都映射成 Python 的 None 值。
下表描述了 TDengine SQL 数据类型和 Python 数据类型的映射。任何类型的 NULL 值都映射成 Python 的 None 值。
| **TDengine SQL数据类型** | **Python数据类型** |
| :-----------------------: | ------------ |
@ -405,7 +405,7 @@ def finish(buf: bytes) -> output_type:
本文内容由浅入深包括 5 个示例程序，同时也包含大量实用的 debug 技巧。
注意：**UDF 内无法通过 print 函数输出日志，需要自己写文件或用 python 内置的 logging 库写文件**。
注意：**UDF 内无法通过 print 函数输出日志，需要自己写文件或用 Python 内置的 logging 库写文件**。
#### 示例一
@ -472,10 +472,10 @@ taos> select myfun(v1, v2) from t;
DB error: udf function execution failure (0.011088s)
```
不幸的是执行失败了，什么原因呢？查看 udfd 进程的日志。
不幸的是执行失败了，什么原因呢？查看 taosudf 进程的日志。
```shell
tail -10 /var/log/taos/udfd.log
tail -10 /var/log/taos/taosudf.log
```
发现以下错误信息。
@ -652,7 +652,7 @@ tail -20 taospyudf.log
2023-05-25 11:42:34.541 ERROR [1679419] [PyUdf::PyUdf@217] py udf load module failure. error ModuleNotFoundError: No module named 'moment'
```
这是因为 “moment” 所在位置不在 python udf 插件默认的库搜索路径中。怎么确认这一点呢？通过以下命令搜索 taospyudf.log。
这是因为 “moment” 所在位置不在 Python udf 插件默认的库搜索路径中。怎么确认这一点呢？通过以下命令搜索 taospyudf.log。
```shell
grep 'sys path' taospyudf.log | tail -1
@ -664,7 +664,7 @@ grep 'sys path' taospyudf.log | tail -1
2023-05-25 10:58:48.554 INFO [1679419] [doPyOpen@592] python sys path: ['', '/lib/python38.zip', '/lib/python3.8', '/lib/python3.8/lib-dynload', '/lib/python3/dist-packages', '/var/lib/taos//.udf']
```
发现 python udf 插件默认搜索的第三方库安装路径是： /lib/python3/dist-packages，而 moment 默认安装到了 /usr/local/lib/python3.8/dist-packages。下面我们修改 python udf 插件默认的库搜索路径。
发现 Python udf 插件默认搜索的第三方库安装路径是： /lib/python3/dist-packages，而 moment 默认安装到了 /usr/local/lib/python3.8/dist-packages。下面我们修改 Python udf 插件默认的库搜索路径。
先打开 python3 命令行，查看当前的 sys.path。
```python
@ -754,7 +754,7 @@ create or replace aggregate function myspread as '/root/udf/myspread.py' outputt
这个 SQL 语句与创建标量函数的 SQL 语句有两个重要区别。
1. 增加了 aggregate 关键字
2. 增加了 bufsize 关键字，用来指定存储中间结果的内存大小，这个数值可以大于实际使用的数值。本例中间结果是两个浮点数组成的 tuple，序列化后实际占用大小只有 32 个字节，但指定的 bufsize 是128，可以用 python 命令行打印实际占用的字节数
2. 增加了 bufsize 关键字，用来指定存储中间结果的内存大小，这个数值可以大于实际使用的数值。本例中间结果是两个浮点数组成的 tuple，序列化后实际占用大小只有 32 个字节，但指定的 bufsize 是128，可以用 Python 命令行打印实际占用的字节数
```python
>>> len(pickle.dumps((12345.6789, 23456789.9877)))

4
docs/zh/07-develop/15-high.md
View File

@ -352,7 +352,7 @@ main 函数可以接收 5 个启动参数，依次是：
<details>
SQLWriter 类封装了拼 SQL 和写数据的逻辑。所有的表都没有提前创建，而是在发生表不存在错误的时候，再以超级表为模板批量建表，然后重新执行 INSERT 语句。对于其它错误会记录当时执行的 SQL， 以便排查错误和故障恢复。这个类也对 SQL 是否超过最大长度限制做了检查，根据 TDengine 3.0 的限制由输入参数 maxSQLLength 传入了支持的最大 SQL 长度，即 1,048,576 。
SQLWriter 类封装了拼 SQL 和写数据的逻辑。所有的表都没有提前创建，而是在发生表不存在错误的时候，再以超级表为模板批量建表，然后重新执行 INSERT 语句。对于其它错误会记录当时执行的 SQL，以便排查错误和故障恢复。这个类也对 SQL 是否超过最大长度限制做了检查，根据 TDengine 3.0 的限制由输入参数 maxSQLLength 传入了支持的最大 SQL 长度，即 1,048,576 。
<summary>SQLWriter</summary>
@ -374,7 +374,7 @@ SQLWriter 类封装了拼 SQL 和写数据的逻辑。所有的表都没有提
- 已安装 Python3， 推荐版本 >= 3.8
- 已安装 taospy
2. 安装 faster-fifo 代替 python 内置的 multiprocessing.Queue
2. 安装 faster-fifo 代替 Python 内置的 multiprocessing.Queue
```
pip3 install faster-fifo

12
docs/zh/08-operation/01-intro.md
View File

@ -36,7 +36,7 @@ taosAdapter 提供了以下功能：
- RESTful 接口；
- WebSocket 连接；
- 兼容 InfluxDB v1 格式写入；
- 兼容 OpenTSDB JSON 和 Telnet 格式写入；
- 兼容 OpenTSDB JSON 和 TELNET 格式写入；
- 无缝连接到 Telegraf；
- 无缝连接到 collectd；
- 无缝连接到 StatsD；
@ -44,9 +44,9 @@ taosAdapter 提供了以下功能：
## taosKeeper
taosKeeper 是 TDengine 3.0 版本中新增的监控指标导出工具，旨在方便用户对TDengine 的运行状态和性能指标进行实时监控。通过简单的配置，TDengine 能够将其运行状态、指标等信息上报给 taosKeeper。当接收到监控数据后，taosKeeper 会利用 taosAdapter 提供的 RESTful 接口，将这些数据存储到 TDengine 中。
taosKeeper 是 TDengine 3.0 版本中新增的监控指标导出工具，旨在方便用户对 TDengine 的运行状态和性能指标进行实时监控。通过简单的配置，TDengine 能够将其运行状态、指标等信息上报给 taosKeeper。当接收到监控数据后，taosKeeper 会利用 taosAdapter 提供的 RESTful 接口，将这些数据存储到 TDengine 中。
taosKeeper 的一个重要价值在于，它能够将多个甚至一批 TDengine 集群的监控数据集中存储在一个统一的平台上。这使得监控软件能够轻松获取这些数据，从而实现对 TDengine 集群的全面监控和实时分析。通过 taosKeeper，用户可以更加便捷地掌握TDengine 的运行状况，及时发现并解决潜在问题，确保系统的稳定性和高效性。
taosKeeper 的一个重要价值在于，它能够将多个甚至一批 TDengine 集群的监控数据集中存储在一个统一的平台上。这使得监控软件能够轻松获取这些数据，从而实现对 TDengine 集群的全面监控和实时分析。通过 taosKeeper，用户可以更加便捷地掌握 TDengine 的运行状况，及时发现并解决潜在问题，确保系统的稳定性和高效性。
## taosExplorer
@ -60,7 +60,7 @@ taosKeeper 的一个重要价值在于，它能够将多个甚至一批 TDengine
taosX 作为 TDengine Enterprise 的数据管道功能组件，旨在为用户提供一种无须编写代码即可轻松对接第三方数据源的方法，实现数据的便捷导入。目前，taosX 已支持众多主流数据源，包括 AVEVA PI System、AVEVA Historian、OPC-UA/DA、InfluxDB、OpenTSDB、MQTT、Kafka、CSV、TDengine 2.x、TDengine 3.x、MySQL、PostgreSQL和 Oracle 等。
在实际使用中， 用户通常无须直接与 taosX 进行交互。 相反， 他们可以通 过taosExplorer 提供的浏览器用户界面轻松访问和使用 taosX 的强大功能。这种设计简化了操作流程，降低了使用门槛，使得用户能够更加专注于数据处理和分析，从而提高工作效率。
在实际使用中，用户通常无须直接与 taosX 进行交互。 相反， 他们可以通过 taosExplorer 提供的浏览器用户界面轻松访问和使用 taosX 的强大功能。这种设计简化了操作流程，降低了使用门槛，使得用户能够更加专注于数据处理和分析，从而提高工作效率。
## taosX Agent
@ -77,7 +77,7 @@ taosX Agent 是 TDengine Enterprise 数据管道功能的重要组成部分，
这些应用程序负责向业务集群写入、查询业务数据以及订阅数据。应用程序可以通过以下 3 种方式与业务集群进行交互。
- 基于 taosc 的应用程序：采用原生连接的应用程序，直接连接到业务集群，默认端口为 6030。
- 基于 RESTful 连接的应用程序：使用 RESTful 接口访问业务集群的应用程序，需要通过 taosAdapter 进行连接，默认端口为 6041。
- 基于 WebSkcket 连接的应用程序：采用 WebSocket 连接的应用程序，同样需要通过 taosAdapter 进行连接，默认端口为 6041。
- 基于 WebSocket 连接的应用程序：采用 WebSocket 连接的应用程序，同样需要通过 taosAdapter 进行连接，默认端口为 6041。
2. 可视化/BI 工具
@ -85,4 +85,4 @@ TDengine 支持与众多可视化及 BI 工具无缝对接，如 Grafana、Power
3. 数据源
TDengine 具备强大的数据接入能力，可以对接各种数据源，如 MQTT、OPC-UA/DA、Kafka、AVEVA PI System、AVEVA Historian 等。这使得 TDengine 能够轻松整合来自不同数据源的数据，为用户提供全面、统一的数据视图。
TDengine 具备强大的数据接入能力，可以对接各种数据源，如 MQTT、OPC-UA/DA、Kafka、AVEVA PI System、AVEVA Historian 等。这使得 TDengine 能够轻松整合来自不同数据源的数据，为用户提供全面、统一的数据视图。

20
docs/zh/08-operation/02-planning.md
View File

@ -4,11 +4,11 @@ title: 容量规划
toc_max_heading_level: 4
---
若计划使用 TDengine 搭建一个时序数据平台，须提前对计算资源、存储资源和网络资源进行详细规划，以确保满足业务场景的需求。通常 TDengine 会运行多个进程，包括taosd、taosadapter、taoskeeper、taos-explorer 和 taosx。
若计划使用 TDengine 搭建一个时序数据平台，须提前对计算资源、存储资源和网络资源进行详细规划，以确保满足业务场景的需求。通常 TDengine 会运行多个进程，包括 taosd、taosadapter、taoskeeper、taos-explorer 和 taosx。
在这些进程中，taoskeeper、taos-explorer、taosadapter 和 taosx 的资源占用相对较少，通常不需要特别关注。此外，这些进程对存储空间的需求也较低，其占用的 CPU 和内存资源一般为 taosd 进程的十分之一到几分之一（特殊场景除外，如数据同步和历史数据迁移。在这些情况下，涛思数据的技术支持团队将提供一对一的服务）。系统管理员应定期监控这些进程的资源消耗，并及时进行相应处理。
在本节中，我们将重点讨论 TDengine 数据库引擎的核心进程—taosd 的资源规划。合理的资源规划将确保 taosd 进程的高效运行，从而提高整个时序数据平台的性能和稳定性。
在本节中，我们将重点讨论 TDengine 数据库引擎的核心进程 taosd 的资源规划。合理的资源规划将确保 taosd 进程的高效运行，从而提高整个时序数据平台的性能和稳定性。
## 服务器内存需求
@ -17,7 +17,7 @@ toc_max_heading_level: 4
为了帮助用户更好地理解和配置这些参数，TDengine 的官方文档的数据库管理部分提供了详细说明。根据这些参数，可以估算出一个数据库所需的内存大小，具体计算方式如下（具体数值须根据实际情况进行调整）。
vgroups ×replica × (buffer + pages × pagesize + cachesize)
需要明确的是，这些内存资源并非仅由单一服务器承担，而是由整个集群中的所有dnode 共同分摊，也就是说，这些资源的负担实际上是由这些 dnode 所在的服务器集群共同承担的。若集群内存在多个数据库，那么所需的内存总量还须将这些数据库的需求累加起来。更为复杂的情形在于，如果集群中的 dnode 并非一开始就全部部署完毕，而是在使用过程中随着节点负载的上升逐步添加服务器和 dnode，那么新加入的数据库可能会导致新旧 dnode 之间的负载分布不均。在这种情况下，简单地进行理论计算是不够准确的，必须考虑到各个 dnode 的实际负载状况来进行综合评估。
需要明确的是，这些内存资源并非仅由单一服务器承担，而是由整个集群中的所有 dnode 共同分摊，也就是说，这些资源的负担实际上是由这些 dnode 所在的服务器集群共同承担的。若集群内存在多个数据库，那么所需的内存总量还须将这些数据库的需求累加起来。更为复杂的情形在于，如果集群中的 dnode 并非一开始就全部部署完毕，而是在使用过程中随着节点负载的上升逐步添加服务器和 dnode，那么新加入的数据库可能会导致新旧 dnode 之间的负载分布不均。在这种情况下，简单地进行理论计算是不够准确的，必须考虑到各个 dnode 的实际负载状况来进行综合评估。
系统管理员可以通过如下 SQL 查看 information_schema 库中的 ins_vnodes 表来获得所有数据库所有 vnodes 在各个 dnode 上的分布。
@ -33,7 +33,7 @@ dnode_id |vgroup_id | db_name | status | role_time | start_time | restored |
1. 原生连接方式
由于客户端应用程序采用 taosc 与服务器进行通信，因此会产生一定的内存消耗。这些内存消耗主要源于：写入操作中的 SQL、表元数据信息的缓存，以及固有的结构开销。假设该数据库服务能够支持的最大表数量为 N（每个通过超级表创建的表的元数据开销约为 256B），最大并发写入线程数为 T，以及最大 SQL 语句长度为 S（通常情况下为1MB）。基于这些参数，我们可以对客户端的内存消耗进行估算（单位为 MB）。
由于客户端应用程序采用 taosc 与服务器进行通信，因此会产生一定的内存消耗。这些内存消耗主要源于：写入操作中的 SQL、表元数据信息的缓存，以及固有的结构开销。假设该数据库服务能够支持的最大表数量为 N（每个通过超级表创建的表的元数据开销约为 256B），最大并发写入线程数为 T，以及最大 SQL 语句长度为 S（通常情况下为 1MB）。基于这些参数，我们可以对客户端的内存消耗进行估算（单位为 MB）。
M = (T × S × 3 + (N / 4096) + 100)
例如，用户最大并发写入线程数为 100，子表数为 10 000 000，那么客户端的内存最低要求如下：
@ -101,7 +101,7 @@ $ du -hd1 <dataDir>/vnode --exclude=wal
除了存储容量的需求以外，用户可能还希望在特定容量下降低存储成本。为了满足这一需求，TDengine 推出了多级存储功能。该功能允许将近期产生且访问频率较高的数据存储在高成本存储设备上，而将时间较长且访问频率较低的数据存储在低成本存储设备上。通过这种方式，TDengine 实现了以下目标。
- 降低存储成本：通过将海量极冷数据存储在廉价存储设备上，可以显著降低存储成本。
- 提高写入性能：每级存储支持多个挂载点，WAL 文件也支持 0 级的多挂载点并行写入，这些措施极大地提高了写入性能（实际场景中的持续写入速度可达 3 亿测
点 / 秒），在机械硬盘上也能获得极高的硬盘 I/O 吞吐（实测可达 2GB/s）。
点/秒），在机械硬盘上也能获得极高的硬盘 I/O 吞吐（实测可达 2GB/s）。
用户可以根据冷热数据的比例来决定高速和低成本存储设备之间的容量划分。
@ -120,7 +120,7 @@ TDengine 的多级存储功能在使用上还具备以下优点。
- 集群为响应维护指令而额外需要的内部通信带宽，如从单副本切换到三副本导致的数据复制、修复指定 dnode 引发的数据复制等情况。
为了估算入站带宽需求，我们可以采用以下方式：
由 于 taosc 写入在 RPC 通信过程中自带压缩功能，因此写入带宽需求相对于RESTful/WebSocket 连接方式较低。在这里，我们将基于 RESTful/WebSocket 连接方式的
由 于 taosc 写入在 RPC 通信过程中自带压缩功能，因此写入带宽需求相对于 RESTful/WebSocket 连接方式较低。在这里，我们将基于 RESTful/WebSocket 连接方式的
带宽需求来估算写入请求的带宽。
示例：1000 万块智能电表，电表每 15min 采集一次数据，每次采集的数据量为 20B，可计算出平均带宽需求为 0.22MB。
@ -154,9 +154,9 @@ TDengine 的多级存储功能在使用上还具备以下优点。
| taosKeeper | 6043 | TCP |
| statsd 格式写入接口 | 6044 | TCP/UDP |
| collectd 格式写入接口 | 6045 | TCP/UDP |
| openTSDB Telnet 格式写入接口 | 6046 | TCP |
| collectd 使用 openTSDB Telnet 格式写入接口 | 6047 | TCP |
| icinga2 使用 openTSDB Telnet 格式写入接口 | 6048 | TCP |
| tcollector 使用 openTSDB Telnet 格式写入接口 | 6049 | TCP |
| openTSDB TELNET 格式写入接口 | 6046 | TCP |
| collectd 使用 openTSDB TELNET 格式写入接口 | 6047 | TCP |
| icinga2 使用 openTSDB TELNET 格式写入接口 | 6048 | TCP |
| tcollector 使用 openTSDB TELNET 格式写入接口 | 6049 | TCP |
| taosX | 6050, 6055 | TCP |
| taosExplorer | 6060 | TCP |

24
docs/zh/08-operation/03-deployment.md
View File

@ -14,18 +14,18 @@ taosd 是 TDengine 集群中最主要的服务组件，本节介绍手动部署
#### 1. 清除数据
如果搭建集群的物理节点中存在之前的测试数据或者装过其他版本（如 1.x/2.x）的TDengine，请先将其删除，并清空所有数据。
如果搭建集群的物理节点中存在之前的测试数据或者装过其他版本（如 1.x/2.x）的 TDengine，请先将其删除，并清空所有数据。
#### 2. 检查环境
在进行 TDengine 集群部署之前，全面检查所有 dnode 以及应用程序所在物理节点的网络设置至关重要。以下是检查步骤：
- 第 1 步，在每个物理节点上执行 hostname -f 命令，以查看并确认所有节点的hostname 是唯一的。对于应用程序驱动所在的节点，这一步骤可以省略。
- 第 2 步，在每个物理节点上执行 ping host 命令，其中 host 是其他物理节点的 hostname。这一步骤旨在检测当前节点与其他物理节点之间的网络连通性。如果发现无法 ping 通，请立即检查网络和 DNS 设置。对于 Linux 操作系统，请检查 /etc/hosts 文件；对于 Windows 操作系统，请检查C:\Windows\system32\drivers\etc\hosts 文件。网络不通畅将导致无法组建集群，请务必解决此问题。
- 第 3 步，在应用程序运行的物理节点上重复上述网络检测步骤。如果发现网络不通畅，应用程序将无法连接到 taosd 服务。此时，请仔细检查应用程序所在物理节点的DNS 设置或 hosts 文件，确保其配置正确无误。
- 第 2 步，在每个物理节点上执行 ping host 命令，其中 host 是其他物理节点的 hostname。这一步骤旨在检测当前节点与其他物理节点之间的网络连通性。如果发现无法 ping 通，请立即检查网络和 DNS 设置。对于 Linux 操作系统，请检查 /etc/hosts 文件；对于 Windows 操作系统，请检查 `C:\Windows\system32\drivers\etc\hosts` 文件。网络不通畅将导致无法组建集群，请务必解决此问题。
- 第 3 步，在应用程序运行的物理节点上重复上述网络检测步骤。如果发现网络不通畅，应用程序将无法连接到 taosd 服务。此时，请仔细检查应用程序所在物理节点的 DNS 设置或 hosts 文件，确保其配置正确无误。
- 第 4 步，检查端口，确保集群中所有主机在端口 6030 上的 TCP 能够互通。
通过以上步骤，你可以确保所有节点在网络层面顺利通信，从而为成功部署TDengine 集群奠定坚实基础
通过以上步骤，你可以确保所有节点在网络层面顺利通信，从而为成功部署 TDengine 集群奠定坚实基础
#### 3. 安装
@ -77,7 +77,7 @@ taos> show dnodes;
create dnode "h2.taosdata.com:6030"
```
将新 dnode 的 endpoint 添加进集群的 endpoint 列表。需要为 `fqdn:port` 加上双引号，否则运行时出错。请注意将示例的 h2.taosdata.com:6030 替换为这个新 dnode 的 endpoint。然后执行如下 SQL 查看新节点是否成功加入。若要加入的 dnode 当前处于离线状态，请参考本节后面的 “常见问题”部分进行解决。
将新 dnode 的 endpoint 添加进集群的 endpoint 列表。需要为 `fqdn:port` 加上双引号，否则运行时出错。请注意将示例的 h2.taosdata.com:6030 替换为这个新 dnode 的 endpoint。然后执行如下 SQL 查看新节点是否成功加入。若要加入的 dnode 当前处于离线状态，请参考本节后面的“常见问题”部分进行解决。
```shell
show dnodes;
@ -202,7 +202,7 @@ http {
### 部署 taosKeeper
如果要想使用 TDegnine 的监控功能，taosKeeper 是一个必要的组件，关于监控请参考[TDinsight](../../reference/components/tdinsight)，关于部署 taosKeeper 的细节请参考[taosKeeper参考手册](../../reference/components/taoskeeper)。
如果要想使用 TDegnine 的监控功能，taosKeeper 是一个必要的组件，关于监控请参考 [TDinsight](../../reference/components/tdinsight)，关于部署 taosKeeper 的细节请参考 [taosKeeper 参考手册](../../reference/components/taoskeeper)。
### 部署 taosX
@ -210,11 +210,11 @@ http {
### 部署 taosX-Agent
有些数据源如 Pi, OPC 等，因为网络条件和数据源访问的限制，taosX 无法直接访问数据源，这种情况下需要部署一个代理服务 taosX-Agent，关于它的详细说明和部署请参考企业版参考手册。
有些数据源如 PI、OPC 等，因为网络条件和数据源访问的限制，taosX 无法直接访问数据源，这种情况下需要部署一个代理服务 taosX-Agent，关于它的详细说明和部署请参考企业版参考手册。
### 部署 taos-Explorer
TDengine 提供了可视化管理 TDengine 集群的能力，要想使用图形化界面需要部署 taos-Explorer 服务，关于它的详细说明和部署请参考[taos-Explorer 参考手册](../../reference/components/explorer)
TDengine 提供了可视化管理 TDengine 集群的能力，要想使用图形化界面需要部署 taos-Explorer 服务，关于它的详细说明和部署请参考 [taos-Explorer 参考手册](../../reference/components/explorer)
## Docker 部署
@ -299,14 +299,14 @@ echo 127.0.0.1 tdengine |sudo tee -a /etc/hosts
taos -h tdengine -P 6030
```
如果 TAOS_FQDN 被设置为与所在主机名相同，则效果与“在 host 网络模式下启动TDengine”相同。
如果 TAOS_FQDN 被设置为与所在主机名相同，则效果与“在 host 网络模式下启动 TDengine”相同。
## Kubernetes 部署
作为面向云原生架构设计的时序数据库，TDengine 本身就支持 Kubernetes 部署。这里介绍如何使用 YAML 文件从头一步一步创建一个可用于生产使用的高可用 TDengine 集群，并重点介绍 Kubernetes 环境下 TDengine 的常用操作。本小节要求读者对 Kubernetes 有一定的了解，可以熟练运行常见的 kubectl 命令，了解 statefulset、service、pvc 等概念，对这些概念不熟悉的读者，可以先参考 Kubernetes 的官网进行学习。
为了满足高可用的需求，集群需要满足如下要求：
- 3 个及以上 dnode ：TDengine 的同一个 vgroup 中的多个 vnode ，不允许同时分布在一个 dnode ，所以如果创建 3 副本的数据库，则 dnode 数大于等于 3
- 3 个 mnode ：mnode 负责整个集群的管理工作，TDengine 默认是一个 mnode。如果这个 mnode 所在的 dnode 掉线，则整个集群不可用。
- 3 个及以上 dnode：TDengine 的同一个 vgroup 中的多个 vnode，不允许同时分布在一个 dnode ，所以如果创建 3 副本的数据库，则 dnode 数大于等于 3
- 3 个 mnode：mnode 负责整个集群的管理工作，TDengine 默认是一个 mnode。如果这个 mnode 所在的 dnode 掉线，则整个集群不可用。
- 数据库的 3 副本：TDengine 的副本配置是数据库级别，所以数据库 3 副本可满足在 3 个 dnode 的集群中，任意一个 dnode 下线，都不影响集群的正常使用。如果下线 dnode 个数为 2 时，此时集群不可用，因为 RAFT 无法完成选举。（企业版：在灾难恢复场景，任一节点数据文件损坏，都可以通过重新拉起 dnode 进行恢复）
### 前置条件
@ -342,7 +342,7 @@ spec:
### 有状态服务 StatefulSet
根据 Kubernetes 对各类部署的说明，我们将使用 StatefulSet 作为 TDengine 的部署资源类型。 创建文件 tdengine.yaml，其中 replicas 定义集群节点的数量为 3。节点时区为中国（Asia/Shanghai），每个节点分配 5G 标准（standard）存储，你也可以根据实际情况进行相应修改。
根据 Kubernetes 对各类部署的说明，我们将使用 StatefulSet 作为 TDengine 的部署资源类型。 创建文件 tdengine.yaml，其中 replicas 定义集群节点的数量为 3。节点时区为中国（Asia/Shanghai），每个节点分配 5GB 标准（standard）存储，你也可以根据实际情况进行相应修改。
请特别注意 startupProbe 的配置，在 dnode 的 Pod 掉线一段时间后，再重新启动，这个时候新上线的 dnode 会短暂不可用。如果 startupProbe 配置过小，Kubernetes 会认为该 Pod 处于不正常的状态，并尝试重启该 Pod，该 dnode 的 Pod 会频繁重启，始终无法恢复到正常状态。

67
docs/zh/08-operation/04-maintenance.md
View File

@ -8,41 +8,42 @@ sidebar_label: 集群维护
## 节点管理
如何管理集群节点请参考[节点管理](../../reference/taos-sql/node)
如何管理集群节点请参考 [节点管理](../../reference/taos-sql/node)
## 数据重整
TDengine 面向多种写入场景，而很多写入场景下，TDengine 的存储会导致数据存储的放大或数据文件的空洞等。这一方面影响数据的存储效率，另一方面也会影响查询效率。为了解决上述问题，TDengine 企业版提供了对数据的重整功能，即 DATA COMPACT 功能，将存储的数据文件重新整理，删除文件空洞和无效数据，提高数据的组织度，从而提高存储和查询的效率。数据重整功能在 3.0.3.0 版本第一次发布，此后又经过了多次迭代优化，建议使用最新版本。
TDengine 面向多种写入场景，而很多写入场景下，TDengine 的存储会导致数据存储的放大或数据文件的空洞等。这一方面影响数据的存储效率，另一方面也会影响查询效率。为了解决上述问题，TDengine 企业版提供了对数据的重整功能，即 data compact 功能，将存储的数据文件重新整理，删除文件空洞和无效数据，提高数据的组织度，从而提高存储和查询的效率。数据重整功能在 3.0.3.0 版本第一次发布，此后又经过了多次迭代优化，建议使用最新版本。
### 语法
```SQL
COMPACT DATABASE db_name [start with 'XXXX'] [end with 'YYYY'];
COMPACT [db_name.]VGROUPS IN (vgroup_id1, vgroup_id2, ...) [start with 'XXXX'] [end with 'YYYY'];
SHOW COMPACTS;
SHOW COMPACT compact_id;
KILL COMPACT 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;
```
### 效果
- 扫描并压缩指定的 DB 中所有 VGROUP 中 VNODE 的所有数据文件
- 扫描并压缩 DB 中指定的 VGROUP 列表中 VNODE 的所有数据文件, 若 db_name 为空，则默认为当前数据库
- COMPCAT 会删除被删除数据以及被删除的表的数据
- COMPACT 会合并多个 STT 文件
- 可通过 start with 关键字指定 COMPACT 数据的起始时间
- 可通过 end with 关键字指定 COMPACT 数据的终止时间
- COMPACT 命令会返回 COMPACT 任务的 ID
- COMPACT 任务会在后台异步执行，可以通过 SHOW COMPACTS 命令查看 COMPACT 任务的进度
- SHOW 命令会返回 COMPACT 任务的 ID，可以通过 KILL COMPACT 命令终止 COMPACT 任务
- 扫描并压缩指定的 DB 中所有 vgroup 中 vnode 的所有数据文件
- 扫描并压缩 DB 中指定的 vgroup 列表中 vnode 的所有数据文件, 若 db_name 为空，则默认为当前数据库
- compact 会删除被删除数据以及被删除的表的数据
- compact 会合并多个 STT 文件
- 可通过 start with 关键字指定 compact 数据的起始时间
- 可通过 end with 关键字指定 compact 数据的终止时间
- 可通过 `META_ONLY` 关键字指定只 compact 元数据。元数据默认情况下不会 compact。
- compact 命令会返回 compact 任务的 ID
- compact 任务会在后台异步执行，可以通过 show compacts 命令查看 compact 任务的进度
- show 命令会返回 compact 任务的 ID，可以通过 kill compact 命令终止 compact 任务
### 补充说明
- COMPACT 为异步，执行 COMPACT 命令后不会等 COMPACT 结束就会返回。如果上一个 COMPACT 没有完成则再发起一个 COMPACT 任务，则会等上一个任务完成后再返回。
- COMPACT 可能阻塞写入，尤其是在 stt_trigger = 1 的数据库中，但不阻塞查询。
- compact 为异步，执行 compact 命令后不会等 compact 结束就会返回。如果上一个 compact 没有完成则再发起一个 compact 任务，则会等上一个任务完成后再返回。
- compact 可能阻塞写入，尤其是在 stt_trigger = 1 的数据库中，但不阻塞查询。
## Vgroup Leader 再平衡
## vgroup leader 再平衡
当多副本集群中的一个或多个节点因为升级或其它原因而重启后，有可能出现集群中各个 dnode 负载不均衡的现象，极端情况下会出现所有 vgroup 的 leader 都位于同一个 dnode 的情况。为了解决这个问题，可以使用下面的命令，该命令在 3.0.4.0 版本中首次发布，建议尽可能使用最新版本。
@ -54,15 +55,15 @@ balance vgroup leader database <database_name>; # 再平衡一个 database 内
### 功能
尝试让一个或所有 vgroup 的 leader在各自的replica节点上均匀分布。这个命令会让 vgroup 强制重新选举，通过重新选举，在选举的过程中，改变 vgroup 的leader，通过这个方式，最终让leader均匀分布。
尝试让一个或所有 vgroup 的 leader 在各自的 replica 节点上均匀分布。这个命令会让 vgroup 强制重新选举，通过重新选举，在选举的过程中，改变 vgroup 的 leader，通过这个方式，最终让 leader 均匀分布。
### 注意
Vgroup 选举本身带有随机性，所以通过选举的重新分布产生的均匀分布也是带有一定的概率，不会完全的均匀。该命令的副作用是影响查询和写入，在vgroup重新选举时，从开始选举到选举出新的 leader 这段时间，这 个vgroup 无法写入和查询。选举过程一般在秒级完成。所有的vgroup会依次逐个重新选举。
vgroup 选举本身带有随机性，所以通过选举的重新分布产生的均匀分布也是带有一定的概率，不会完全的均匀。该命令的副作用是影响查询和写入，在 vgroup 重新选举时，从开始选举到选举出新的 leader 这段时间，这 个vgroup 无法写入和查询。选举过程一般在秒级完成。所有的 vgroup 会依次逐个重新选举。
## 恢复数据节点
当集群中的某个数据节点（dnode）的数据全部丢失或被破坏，比如磁盘损坏或者目录被误删除，可以通过 restore dnode 命令来恢复该数据节点上的部分或全部逻辑节点，该功能依赖多副本中的其它副本进行数据复制，所以只在集群中 dnode 数量大于等于 3 且副本数为 3 的情况下能够工作。
当集群中的某个数据节点（dnode）的数据全部丢失或被破坏，比如磁盘损坏或者目录被误删除，可以通过 `restore dnode` 命令来恢复该数据节点上的部分或全部逻辑节点，该功能依赖多副本中的其它副本进行数据复制，所以只在集群中 dnode 数量大于等于 3 且副本数为 3 的情况下能够工作。
```sql
restore dnode <dnode_id>；# 恢复dnode上的mnode，所有vnode和qnode
@ -73,12 +74,12 @@ restore qnode on dnode <dnode_id>；# 恢复dnode上的qnode
### 限制
- 该功能是基于已有的复制功能的恢复，不是灾难恢复或者备份恢复，所以对于要恢复的 mnode 和 vnode来说，使用该命令的前提是还存在该 mnode 或 vnode 的其它两个副本仍然能够正常工作。
- 该命令不能修复数据目录中的个别文件的损坏或者丢失。例如，如果某个 mnode 或者 vnode 中的个别文件或数据损坏，无法单独恢复损坏的某个文件或者某块数据。此时，可以选择将该 mnode/vnode 的数据全部清空再进行恢复。
- 该功能是基于已有的复制功能的恢复，不是灾难恢复或者备份恢复，所以对于要恢复的 mnode 和 vnode 来说，使用该命令的前提是还存在该 mnode 或 vnode 的其它两个副本仍然能够正常工作。
- 该命令不能修复数据目录中的个别文件的损坏或者丢失。例如，如果某个 mnode 或者 vnode 中的个别文件或数据损坏，无法单独恢复损坏的某个文件或者某块数据。此时，可以选择将该 mnode/vnode 的数据全部清空再进行恢复。
## 分裂虚拟组
当一个 vgroup 因为子表数过多而导致 CPU 或 Disk 资源使用量负载过高时，增加 dnode 节点后，可通过split vgroup命令把该vgroup分裂为两个虚拟组。分裂完成后，新产生的两个 vgroup 承担原来由一个 vgroup 提供的读写服务。该命令在 3.0.6.0 版本第一次发布，建议尽可能使用最新版本。
当一个 vgroup 因为子表数过多而导致 CPU 或 Disk 资源使用量负载过高时，增加 dnode 节点后，可通过 `split vgroup` 命令把该 vgroup 分裂为两个虚拟组。分裂完成后，新产生的两个 vgroup 承担原来由一个 vgroup 提供的读写服务。该命令在 3.0.6.0 版本第一次发布，建议尽可能使用最新版本。
```sql
split vgroup <vgroup_id>
@ -87,7 +88,7 @@ split vgroup <vgroup_id>
### 注意
- 单副本库虚拟组，在分裂完成后，历史时序数据总磁盘空间使用量，可能会翻倍。所以，在执行该操作之前，通过增加 dnode 节点方式，确保集群中有足够的 CPU 和磁盘资源，避免资源不足现象发生。
- 该命令为 DB 级事务；执行过程，当前DB的其它管理事务将会被拒绝。集群中，其它DB不受影响。
- 该命令为 DB 级事务；执行过程，当前 DB 的其它管理事务将会被拒绝。集群中，其它 DB 不受影响。
- 分裂任务执行过程中，可持续提供读写服务；期间，可能存在可感知的短暂的读写业务中断。
- 在分裂过程中，不支持流和订阅。分裂结束后，历史 WAL 会清空。
- 分裂过程中，可支持节点宕机重启容错；但不支持节点磁盘故障容错。
@ -96,8 +97,6 @@ split vgroup <vgroup_id>
从 3.1.1.0 版本开始，TDengine Enterprise 支持在线热更新 `supportVnodes` 这个很重要的 dnode 配置参数。这个参数的原始配置方式是在 `taos.cfg` 配置文件中，表示该 dnode 能够支持的最大的 vnode 数量。当创建一个数据库时需要分配新的 vnode，当删除一个数据库时其 vnode 都会被销毁。
但在线更新 `supportVnodes` 不会产生持久化，当系统重启后，允许的最大 vnode 数量仍然由 taos.cfg 中配置的 `supportVnodes` 决定。
如果通过在线更新或配置文件方式设置的 `supportVnodes` 小于 dnode 当前已经实际存在的 vnode 数量，已经存在的 vnode 不会受影响。但当尝试创建新的 database 时，是否能够创建成功则仍然受实际生效的 `supportVnodes` 参数决定。
## 双副本
@ -106,7 +105,7 @@ split vgroup <vgroup_id>
### 查看 Vgroups 的状态
通过以下 SQL 命令参看双副本数据库中各 Vgroup 的状态：
通过以下 SQL 命令参看双副本数据库中各 vgroup 的状态：
```sql
show arbgroups;
@ -120,15 +119,15 @@ select * from information_schema.ins_arbgroups;
```
is_sync 有以下两种取值：
- 0: Vgroup 数据未达成同步。在此状态下，如果 Vgroup 中的某一 Vnode 不可访问，另一个 Vnode 无法被指定为 `AssignedLeader` role，该 Vgroup 将无法提供服务。
- 1: Vgroup 数据达成同步。在此状态下，如果 Vgroup 中的某一 Vnode 不可访问，另一个 Vnode 可以被指定为 `AssignedLeader` role，该 Vgroup 可以继续提供服务。
- 0: vgroup 数据未达成同步。在此状态下，如果 vgroup 中的某一 vnode 不可访问，另一个 vnode 无法被指定为 `AssignedLeader` role，该 vgroup 将无法提供服务。
- 1: vgroup 数据达成同步。在此状态下，如果 vgroup 中的某一 vnode 不可访问，另一个 vnode 可以被指定为 `AssignedLeader` role，该 vgroup 可以继续提供服务。
assigned_dnode：
- 标识被指定为 AssignedLeader 的 Vnode 的 DnodeId
- 未指定 AssignedLeader时，该列显示 NULL
- 标识被指定为 AssignedLeader 的 vnode 的 DnodeId
- 未指定 AssignedLeader 时，该列显示 NULL
assigned_token：
- 标识被指定为 AssignedLeader 的 Vnode 的 Token
- 标识被指定为 AssignedLeader 的 vnode 的 Token
- 未指定 AssignedLeader时，该列显示 NULL
### 最佳实践

6
docs/zh/08-operation/05-monitor.md
View File

@ -4,7 +4,7 @@ title: 运行监控
toc_max_heading_level: 4
---
为了确保集群稳定运行，TDengine 集成了多种监控指标收集机制，并通 过taosKeeper 进行汇总。taosKeeper负责接收这些数据，并将其写入一个独立的 TDengine 实例中，该实例可以与被监控的 TDengine 集群保持独立。TDengine 中的两个核心组件 taosd （数据库引擎） 和 taosX （数据接入平台）都通过相同的监控架构来实现对其运行时的监控，但各自的监控指标设计有所不同。
为了确保集群稳定运行，TDengine 集成了多种监控指标收集机制，并通过 taosKeeper 进行汇总。taosKeeper 负责接收这些数据，并将其写入一个独立的 TDengine 实例中，该实例可以与被监控的 TDengine 集群保持独立。TDengine 中的两个核心组件 taosd （数据库引擎）和 taosX （数据接入平台）都通过相同的监控架构来实现对其运行时的监控，但各自的监控指标设计有所不同。
至于如何获取和使用这些监控数据，用户可以使用第三方的监测工具比如 Zabbix 来获取这些保存的系统监测数据，进而将 TDengine 的运行状况无缝集成到现有的 IT 监控系统中。也可以使用 TDengine 提供的 TDinsight 插件，使用该插件用户可以通过 Grafana 平台直观地展示和管理这些监控信息，如下图所示。这为用户提供了灵活的监控选项，以满足不同场景下的运维需求。
@ -24,7 +24,7 @@ taosKeeper 的配置文件默认位于 `/etc/taos/taoskeeper.toml`。 详细配
通过集成 Grafana 和 TDengine 数据源插件，TDinsight 能够读取 taosKeeper 收集的监控数据。这使得用户可以在 Grafana 平台上直观地查看 TDengine 集群的状态、节点信息、读写请求以及资源使用情况等关键指标，实现数据的可视化展示。
以下是TDinsight 的详细使用说明，以帮助你充分利用这一强大工具。
以下是 TDinsight 的详细使用说明，以帮助你充分利用这一强大工具。
#### 前置条件
@ -40,7 +40,7 @@ taosKeeper 的配置文件默认位于 `/etc/taos/taoskeeper.toml`。 详细配
#### 导入仪表盘
TDengine 数据源插件已提交至 Grafana 官网，如何安装 TDengine 数据源插件和配置数据源请参考：[安装 Grafana Plugin 并配置数据源](../../third-party/visual/grafana/#安装-grafana-plugin-并配置数据源)。完成插件的安装和数据源的创建后，可以进行 TDinsight 仪表盘的导入。
TDengine 数据源插件已提交至 Grafana 官网，如何安装 TDengine 数据源插件和配置数据源请参考 [安装 Grafana Plugin 并配置数据源](../../third-party/visual/grafana/#安装-grafana-plugin-并配置数据源)。完成插件的安装和数据源的创建后，可以进行 TDinsight 仪表盘的导入。
在 Grafana 的 “Home” -> “Dashboards” 页面，点击位于右上角的 “New” -> “import” 按钮，即可进入 Dashboard 的导入页面，它支持以下两种导入方式。
- Dashboard ID：18180。

20
docs/zh/08-operation/06-gui.md
View File

@ -4,7 +4,7 @@ title: 可视化管理工具
toc_max_heading_level: 4
---
为方便用户更高效地使用和管理 TDengine，TDengine 3.0 版本推出了一个全新的可视化组件—taosExplorer。这个组件旨在帮助用户在不熟悉 SQL 的情况下，也能轻松管理 TDengine 集群。通过 taosExplorer，用户可以轻松查看 TDengine 的运行状态、浏览数据、配置数据源、实现流计算和数据订阅等功能。此外，用户还可以利用taosExplorer 进行数据的备份、复制和同步操作，以及配置用户的各种访问权限。这些功能极大地简化了数据库的使用过程，提高了用户体验。
为方便用户更高效地使用和管理 TDengine，TDengine 3.0 版本推出了一个全新的可视化组件 taosExplorer。这个组件旨在帮助用户在不熟悉 SQL 的情况下，也能轻松管理 TDengine 集群。通过 taosExplorer，用户可以轻松查看 TDengine 的运行状态、浏览数据、配置数据源、实现流计算和数据订阅等功能。此外，用户还可以利用 taosExplorer 进行数据的备份、复制和同步操作，以及配置用户的各种访问权限。这些功能极大地简化了数据库的使用过程，提高了用户体验。
本节介绍可视化管理的基本功能。
@ -30,7 +30,7 @@ toc_max_heading_level: 4
## 数据浏览器
点击功能列表的“数据浏览器”入口，在“数据浏览器”中可以创建和删除数据库、创建和删除超级表和子表，执行SQL语句，查看SQL语句的执行结果。此外，超级管理员还有对数据库的管理权限，其他用户不提供该功能。如下图所示：
点击功能列表的“数据浏览器”入口，在“数据浏览器”中可以创建和删除数据库、创建和删除超级表和子表，执行 SQL 语句，查看 SQL 语句的执行结果。此外，超级管理员还有对数据库的管理权限，其他用户不提供该功能。如下图所示：
![explorer-01-explorer-entry.jpeg](./pic/explorer-01-explorer-entry.jpeg "进入数据浏览器页面")
@ -38,7 +38,7 @@ toc_max_heading_level: 4
下面通过创建数据库，来熟悉数据浏览器页面的功能和操作，接下来看创建数据库的两种方式：
1. 通过点击图中的 + 号，跳转到创建数据数库页面，点击 创建 按钮，如下图：
1. 通过点击图中的 + 号，跳转到创建数据数库页面，点击“创建”按钮，如下图：
第一步 点击 + 号；
![explorer-02-createDbentry.jpeg](./pic/explorer-02-createDbentry.jpeg "点开 + 号创建数据库")
@ -50,7 +50,7 @@ toc_max_heading_level: 4
弟三步 点击“创建”按钮之后，如下图左边出现数据库名称则创建数据库成功。
![explorer-05-createDbtest01.jpeg](./pic/explorer-05-createDbtest01.jpeg "创建数据库 test01")
2. 通过在 Sql 编辑器中数据 sql 语句，点击 执行 按钮，如下图：
2. 通过在 SQL 编辑器中数据 sql 语句，点击 执行 按钮，如下图：
第一步 输入 sql 语句；
![explorer-06-sqlCreateDb.jpeg](./pic/explorer-06-sqlCreateDb.jpeg "通过 sql 创建数据库")
@ -201,11 +201,11 @@ toc_max_heading_level: 4
## 工具
通过 “工具” 页面，用户可以了解如下 TDengine 周边工具的使用方法。
- TDengine CLI。
- taosBenchmark。
- taosdump。
- TDengine 与 BI 工具的集成，例如 Google Data Studio、Power BI、永洪 BI 等。
- TDengine 与 Grafana、Seeq 的集成。
- TDengine CLI
- taosBenchmark
- taosdump
- TDengine 与 BI 工具的集成，例如 Google Data Studio、Power BI、永洪 BI 等
- TDengine 与 Grafana、Seeq 的集成
## 系统管理
@ -238,7 +238,7 @@ toc_max_heading_level: 4
### 慢 SQL
点击“系统管理”后，点击“慢 SQL”标签页，可以查看慢 SQL 执行语句日志统计与明细。
- 慢 SQL 明细：默认展示的是开始执行时间是一天内和执行耗时大于等于10秒的数据
- 慢 SQL 明细：默认展示的是开始执行时间是一天内和执行耗时大于等于 10 秒的数据
![management-01-slowsql.jpeg](./pic/management-01-slowsql.jpeg)
- 慢 SQL 统计：默认展示所有的数据，可根据开始执行时间进行过滤
![management-02-slowsql.jpeg](./pic/management-02-slowsql.jpeg)

24
docs/zh/08-operation/09-backup.md
View File

@ -8,9 +8,7 @@ toc_max_heading_level: 4
# 1. 基于 taosdump 进行数据备份恢复
taosdump 是一个开源工具，用于支持从运行中的 TDengine 集群备份数据并将备份的数据恢复到相同或另一个正在运行的 TDengine
集群中。taosdump 可以将数据库作为逻辑数据单元进行备份，也可以对数据库中指定时间段内的数据记录进行备份。在使用taosdump
时，可以指定数据备份的目录路径。如果不指定目录路径，taosdump 将默认将数据备份到当前目录。
taosdump 是一个开源工具，用于支持从运行中的 TDengine 集群备份数据并将备份的数据恢复到相同或另一个正在运行的 TDengine 集群中。taosdump 可以将数据库作为逻辑数据单元进行备份，也可以对数据库中指定时间段内的数据记录进行备份。在使用 taosdump 时，可以指定数据备份的目录路径。如果不指定目录路径，taosdump 将默认将数据备份到当前目录。
以下为 taosdump 执行数据备份的使用示例。
@ -18,14 +16,11 @@ taosdump 是一个开源工具，用于支持从运行中的 TDengine 集群备
taosdump -h localhost -P 6030 -D dbname -o /file/path
```
执行上述命令后，taosdump 会连接 localhost:6030 所在的 TDengine 集群，查询数据库 dbname 中的所有数据，并将数据备份到 /f
ile/path 下。
执行上述命令后，taosdump 会连接 localhost:6030 所在的 TDengine 集群，查询数据库 dbname 中的所有数据，并将数据备份到 /file/path 下。
在使用 taosdump 时，如果指定的存储路径已经包含数据文件，taosdump
会提示用户并立即退出，以避免数据被覆盖。这意味着同一存储路径只能用于一次备份。如果你看到相关提示，请谨慎操作，以免误操作导致数据丢失。
在使用 taosdump 时，如果指定的存储路径已经包含数据文件，taosdump 会提示用户并立即退出，以避免数据被覆盖。这意味着同一存储路径只能用于一次备份。如果你看到相关提示，请谨慎操作，以免误操作导致数据丢失。
要将本地指定文件路径中的数据文件恢复到正在运行的 TDengine 集群中，可以通过指定命令行参数和数据文件所在路径来执行 taosdump
命令。以下为 taosdump 执行数据恢复的示例代码。
要将本地指定文件路径中的数据文件恢复到正在运行的 TDengine 集群中，可以通过指定命令行参数和数据文件所在路径来执行 taosdump 命令。以下为 taosdump 执行数据恢复的示例代码。
```shell
taosdump -i /file/path -h localhost -P 6030
@ -76,6 +71,17 @@ taosExplorer 服务页面中，进入“系统管理 - 备份”页面，在“
8. 备份文件大小：备份文件的大小限制。当备份文件大小达到此限制时，会自动创建新的备份文件。
9. 文件压缩等级：备份文件的压缩等级。支持：最快速度、最佳压缩比、兼具速度和压缩比。
用户可以通过开启 S3 转储，将备份文件上传至 S3 存储服务上。开启 S3 转储，需要填写以下信息：
1. S3 节点：S3 节点的地址。
2. 访问密钥 ID：访问密钥 ID。
3. 访问密钥：访问密钥。
4. 存储桶：存储桶名称。
5. 区域：存储桶所在的区域。
6. 对象前缀：备份文件的对象前缀，类似于 S3 上的目录。
7. 本地备份文件的保留时长：本地备份的保留时间，所有早于`当前时间 - backup_retention_period`的文件都需要上传到 S3。
8. 本地备份文件的保留个数：本地备份文件的保留个数，本地只保留最新的`backup_retention_size`个备份文件。
创建成功后，备份计划会开始按照配置的参数运行。在“备份计划”下的列表中，可以查看已创建的备份计划。
备份计划支持以下操作：

8
docs/zh/08-operation/10-disaster.md
View File

@ -10,7 +10,7 @@ toc_max_heading_level: 4
TDengine 支持 WAL 机制，实现数据的容错能力，保证数据的高可靠。TDengine 接收到应用程序的请求数据包时，会先将请求的原始数据包写入数据库日志文件，等数据成功写入数据库数据文件后，再删除相应的 WAL。这样保证了 TDengine 能够在断电等因素导致的服务重启时，从数据库日志文件中恢复数据，避免数据丢失。涉及的配置参数有如下两个：
- wal_level ：WAL 级别，1 表示写 WAL，但不执行 fsync ； 2 表示写 WAL，而且执行 fsync。默认值为 1。
- wal_level：WAL 级别，1 表示写 WAL，但不执行 fsync；2 表示写 WAL，而且执行 fsync。默认值为 1。
- wal_fsync_period：当 wal_level 设置为 2 时，执行 fsync 的周期；当 wal_fsync_period 设置为 0 时，表示每次写入，立即执行 fsync。
如果要 100% 保证数据不丢失，则需要将 wal_level 设置为 2，wal_fsync_period 设置为 0。这时写入速度将会下降。但如果应用程序侧启动的写数据的线程数达到一定的数量（超过 50），那么写入数据的性能也会很不错，只会比 wal_fsync_period 设置为 3000ms 下降 30% 左右。
@ -27,10 +27,8 @@ TDengine 支持 WAL 机制，实现数据的容错能力，保证数据的高可
- 第 3 步，访问 TDengine 集群 B，创建一个与集群 A 中数据库 db1 参数配置相同的数据库 db2。
- 第 4 步，通过 Web 浏览器访问集群 B 的 taosExplorer 服务，在 “数据浏览器” 页面找到 db2，在 “查看数据库配置” 选项中可以获取该数据库的 DSN，例如 taos+ws://root:taosdata@clusterB:6041/db2
- 第 4 步，通过 Web 浏览器访问集群 B 的 taosExplorer 服务，在 “数据浏览器” 页面找到 db2，在 “查看数据库配置” 选项中可以获取该数据库的 DSN，例如 `taos+ws://root:taosdata@clusterB:6041/db2`
- 第 5 步，在 taosExplorer 服务的“系统管理 - 数据同步”页面新增一个数据同步任务，在任务配置信息中填写需要同步的数据库 db1 和目标数据库 db2 的 DSN，完成创建任务后即可启动数据同步。
- 第 6 步，访问集群 B，可以看到集群 B 中的数据库 db2 源源不断写入来自集群 A 数据库 db1 的数据，直至两个集群的数据库数据量基本保持一致。至此，一个简单的基于
TDengine Enterprise 的数据灾备体系搭建完成。
- 第 6 步，访问集群 B，可以看到集群 B 中的数据库 db2 源源不断写入来自集群 A 数据库 db1 的数据，直至两个集群的数据库数据量基本保持一致。至此，一个简单的基于 TDengine Enterprise 的数据灾备体系搭建完成。

27
docs/zh/08-operation/12-multi.md
View File

@ -5,10 +5,10 @@ toc_max_heading_level: 4
---
本节介绍 TDengine Enterprise 特有的多级存储功能，其作用是将较近的热度较高的数据存储在高速介质上，而时间久远热度很低的数据存储在低成本介质上，达成了以下目标：
- 降低存储成本 -- 将数据分级存储后，海量极冷数据存入廉价存储介质带来显著经济性
- 提升写入性能 -- 得益于每级存储可支持多个挂载点，WAL 预写日志也支持 0 级的多挂载点并行写入，极大提升写入性能（实际场景测得支持持续写入每秒 3 亿测点以上），在机械硬盘上可获得极高磁盘 IO 吞吐（实测可达 2GB/s）
- 方便维护 -- 配置好各级存储挂载点后，系统数据迁移等工作，无需人工干预；存储扩容更灵活、方便
- 对 SQL 透明 -- 无论查询的数据是否跨级，一条 SQL 可返回所有数据，简单高效
- **降低存储成本**：将数据分级存储后，海量极冷数据存入廉价存储介质带来显著经济性
- **提升写入性能**：得益于每级存储可支持多个挂载点，WAL 预写日志也支持 0 级的多挂载点并行写入，极大提升写入性能（实际场景测得支持持续写入每秒 3 亿测点以上），在机械硬盘上可获得极高磁盘 IO 吞吐（实测可达 2GB/s）
- **方便维护**：配置好各级存储挂载点后，系统数据迁移等工作，无需人工干预；存储扩容更灵活、方便
- **对 SQL 透明**：无论查询的数据是否跨级，一条 SQL 可返回所有数据，简单高效
多级存储所涉及的各层存储介质都是本地存储设备。除了本地存储设备之外，TDengine Enterprise 还支持使用对象存储(S3)，将最冷的一批数据保存在最廉价的介质上，以进一步降低存储成本，并在必要时仍然可以进行查询，且数据存储在哪里也对 SQL 透明。支持对象存储在 3.3.0.0 版本中首次发布，建议使用最新版本。
@ -26,9 +26,11 @@ dataDir [path] <level> <primary>
```
- path: 挂载点的文件夹路径。
- level: 介质存储等级，取值为 0，1，2。 0 级存储最新的数据，1 级存储次新的数据，2 级存储最老的数据，省略默认为 0。 各级存储之间的数据流向：0 级存储 -> 1 级存储 -> 2 级存储。 同一存储等级可挂载多个硬盘，同一存储等级上的数据文件分布在该存储等级的所有硬盘上。 需要说明的是，数据在不同级别的存储介质上的移动，是由系统自动完成的，用户无需干预。
- primary: 是否为主挂载点，0（否）或 1（是），省略默认为 1。
- level：介质存储等级，取值为 0、1、2。 0 级存储最新的数据，1 级存储次新的数据，2 级存储最老的数据，省略默认为 0。各级存储之间的数据流向：0 级存储 -> 1 级存储 -> 2 级存储。 同一存储等级可挂载多个硬盘，同一存储等级上的数据文件分布在该存储等级的所有硬盘上。需要说明的是，数据在不同级别的存储介质上的移动，是由系统自动完成的，用户无需干预。
- primary：是否为主挂载点，0（否）或 1（是），省略默认为 1。
在配置中，只允许一个主挂载点的存在（level=0，primary=1），例如采用如下的配置方式：
```shell
dataDir /mnt/data1 0 1
dataDir /mnt/data2 0 0
@ -38,7 +40,8 @@ dataDir /mnt/data5 2 0
dataDir /mnt/data6 2 0
```
**注意** 1. 多级存储不允许跨级配置，合法的配置方案有：仅 0 级，仅 0 级+ 1 级，以及 0 级+ 1 级+ 2 级。而不允许只配置 level=0 和 level=2，而不配置 level=1。
**注意**
1. 多级存储不允许跨级配置，合法的配置方案有：仅 0 级、仅 0 级 + 1 级、以及 0 级 + 1 级 + 2 级。而不允许只配置 level=0 和 level=2，而不配置 level=1。
2. 禁止手动移除使用中的挂载盘，挂载盘目前不支持非本地的网络盘。
### 负载均衡
@ -74,13 +77,13 @@ dataDir /mnt/data6 2 0
| 参数名称 | 参数含义 |
|:---------------------|:-----------------------------------------------|
| s3EndPoint | 用户所在地域的 COS 服务域名，支持 http 和 https，bucket 的区域需要与 endpoint 的保持一致，否则无法访问。 |
| s3EndPoint | 用户所在地域的 COS 服务域名，支持 http 和 https，bucket 的区域需要与 endpoint 的保持一致，否则无法访问 |
| s3AccessKey | 冒号分隔的用户 SecretId:SecretKey。例如：AKIDsQmwsfKxTo2A6nGVXZN0UlofKn6JRRSJ:lIdoy99ygEacU7iHfogaN2Xq0yumSm1E |
| s3BucketName | 存储桶名称，减号后面是用户注册 COS 服务的 AppId。其中 AppId 是 COS 特有，AWS 和阿里云都没有，配置时需要作为 bucket name 的一部分，使用减号分隔。参数值均为字符串类型，但不需要引号。例如：test0711-1309024725 |
| s3UploadDelaySec | data 文件持续多长时间不再变动后上传至 s3，单位：秒。最小值：1；最大值：2592000（30天），默认值 60 秒 |
| s3PageCacheSize | S3 page cache 缓存页数目，单位：页。最小值：4；最大值：1024*1024*1024。 ，默认值 4096|
| s3MigrateIntervalSec | 本地数据文件自动上传 S3 的触发周期，单位为秒。最小值：600；最大值：100000。默认值 3600 |
| s3MigrateEnabled | 是否自动进行 S3 迁移，默认值为 0，表示关闭自动 S3 迁移，可配置为 1。 |
| s3MigrateEnabled | 是否自动进行 S3 迁移，默认值为 0，表示关闭自动 S3 迁移，可配置为 1 |
#### 检查配置参数可用性
@ -124,8 +127,8 @@ s3migrate database <db_name>;
当 TSDB 时序数据超过 `s3_keeplocal` 参数指定的时间，相关的数据文件会被切分成多个文件块，每个文件块的默认大小是 512M 字节 (`s3_chunkpages * tsdb_pagesize`)。除了最后一个文件块保留在本地文件系统外，其余的文件块会被上传到对象存储服务。
```math
上传次数 = 数据文件大小 / (s3_chunkpages * tsdb_pagesize) - 1
```text
上传次数 = 数据文件大小 / (s3_chunkpages * tsdb_pagesize) - 1
```
在创建数据库时，可以通过 `s3_chunkpages` 参数调整每个文件块的大小，从而控制每个数据文件的上传次数。
@ -138,7 +141,7 @@ s3migrate database <db_name>;
相邻的多个数据页会作为一个数据块从对象存储下载一次，以减少从对象存储下载的次数。每个数据页的大小，在创建数据库时，通过 `tsdb_pagesize` 参数指定，默认 4K 字节。
```math
```text
下载次数 = 查询需要的数据块数量 - 已缓存的数据块数量
```

24
docs/zh/08-operation/14-user.md
View File

@ -17,11 +17,14 @@ create user user_name pass'password' [sysinfo {1|0}] [createdb {1|0}]
相关参数说明如下。
- user_name：用户名最长不超过 23 个字节。
- password：密码长度必须为 8 到 16 位，并且至少包含大写字母、小写字母、数字、特殊字符中的三类。特殊字符包括 `! @ # $ % ^ & * ( ) - _ + = [ ] { } : ; > < ? | ~ , .`。（始自 3.3.5.0 版本）
- sysinfo ：用户是否可以查看系统信息。1 表示可以查看，0 表示不可以查看。系统信息包括服务端配置信息、服务端各种节点信息，如 dnode、查询节点（qnode）等，以及与存储相关的信息等。默认为可以查看系统信息。
- createdb：用户是否可以创建数据库。1 表示可以创建，0 表示不可以创建。缺省值为 0。// 从 TDengine 企业版 3.3.2.0 开始支持
- password：密码长度必须为 8 到 255 个字节。密码至少包含大写字母、小写字母、数字、特殊字符中的三类。特殊字符包括 `! @ # $ % ^ & * ( ) - _ + = [ ] { } : ; > < ? | ~ , .`（始自 v3.3.5.0），可以通过在 taos.cfg 中添加参数 `enableStrongPassword 0` 关闭此强制要求，或者通过如下 SQL 关闭（始自 v3.3.6.0）。
```sql
alter all dnode 'EnableStrongPassword' '0'
```
- sysinfo：用户是否可以查看系统信息。1 表示可以查看，0 表示不可以查看。系统信息包括服务端配置信息、服务端各种节点信息，如 dnode、查询节点（qnode）等，以及与存储相关的信息等。默认为可以查看系统信息。
- createdb：用户是否可以创建数据库。1 表示可以创建，0 表示不可以创建。缺省值为 0。从企业版 v3.3.2.0 开始支持。
如下 SQL 可以创建密码为 abc123!@# 且可以查看系统信息的用户 test。
如下 SQL 可以创建密码为 `abc123!@#` 且可以查看系统信息的用户 test。
```sql
create user test pass 'abc123!@#' sysinfo 1
@ -55,8 +58,8 @@ alter_user_clause: {
相关参数说明如下。
- pass：修改用户密码。
- enable：是否启用用户。1 表示启用此用户，0 表示禁用此用户。
- sysinfo ：用户是否可查看系统信息。1 表示可以查看系统信息，0 表示不可以查看系统信息
- createdb：用户是否可创建数据库。1 表示可以创建数据库，0 表示不可以创建数据库。// 从 TDengine 企业版 3.3.2.0 开始支持
- sysinfo：用户是否可查看系统信息。1 表示可以查看系统信息，0 表示不可以查看系统信息
- createdb：用户是否可创建数据库。1 表示可以创建数据库，0 表示不可以创建数据库。从企业版 v3.3.2.0 开始支持。
如下 SQL 禁用 test 用户。
```sql
@ -76,7 +79,7 @@ drop user user_name
### 库和表的授权
在 TDengine 中，库和表的权限分为 read （读）和 write （写）两种。这些权限可以单独授予，也可以同时授予用户。
在 TDengine 中，库和表的权限分为 read 和 write 两种。这些权限可以单独授予，也可以同时授予用户。
- read 权限：拥有 read 权限的用户仅能查询库或表中的数据，而无法对数据进行修改或删除。这种权限适用于需要访问数据但不需要对数据进行写入操作的场景，如数据分析师、报表生成器等。
- write 权限：拥有 write 权限的用户可以向库或表中写入数据。这种权限适用于需要对数据进行写入操作的场景，如数据采集器、数据处理器等。如果只拥有 write 权限而没有 read 权限，则只能写入数据但不能查询数据。
@ -101,10 +104,11 @@ resources ：{
```
相关参数说明如下。
- resources ：可以访问的库或表。. 之前为数据库名称，. 之后为表名称。dbname.tbname 的意思是名为 dbname 的数据库中的 tbname 表必须为普通表或超级表。dbname.* 的意思是名为 dbname 的数据库中的所有表。*.* 的意思是所有数据库中的所有表。
- tag_f ilter：超级表的过滤条件。
- resources：可以访问的库或表。`.` 之前为数据库名称，`.` 之后为表名称。`dbname.tbname` 的意思是名为 dbname 的数据库中的 tbname 表必须为普通表或超级表。`dbname.*` 的意思是名为 dbname 的数据库中的所有表。`*.*` 的意思是所有数据库中的所有表。
- tag_filter：超级表的过滤条件。
上述 SQL 既可以授权一个库、所有库，也可以授权一个库下的普通表或超级表，还可以通过 `dbname.tbname` 和 `with` 子句的组合授权符合过滤条件的一张超级表下的所有子表。
上述 SQL 既可以授权一个库、所有库，也可以授权一个库下的普通表或超级表，还可以通过 dbname.tbname 和 with 子句的组合授权符合过滤条件的一张超级表下的所有子表。
如下 SQL 将数据库 power 的 read 权限授权给用户 test。
```sql
grant read on power to test

54
docs/zh/08-operation/16-security.md
View File

@ -28,24 +28,24 @@ ALTER USER TEST DROP HOST HOST_NAME1
```
说明
- 开源版和企业版本都能添加成功，且可以查询到，但是开源版本不会对 IP 做任何限制。
- create user u_write pass 'taosdata1' host 'iprange1','iprange2', 可以一次添加多个 iprange, 服务端会做去重，去重的逻辑是需要 iprange 完全一样
- 默认会把 127.0.0.1 添加到白名单列表，且在白名单列表可以查询
- `create user u_write pass 'taosdata1' host 'iprange1','iprange2'`，可以一次添加多个 ip range，服务端会做去重，去重的逻辑是需要 ip range 完全一样
- 默认会把 `127.0.0.1` 添加到白名单列表，且在白名单列表可以查询
- 集群的节点 IP 集合会自动添加到白名单列表，但是查询不到。
- taosadaper 和 taosd 不在一个机器的时候，需要把 taosadaper IP 手动添加到 taosd 白名单列表中
- 集群情况下，各个节点 enableWhiteList 成一样，或者全为 false,或者全为 true, 要不然集群无法启动
- 白名单变更生效时间 1s，不超过 2s, 每次变更对收发性能有些微影响（多一次判断，可以忽略），变更完之后、影响忽略不计, 变更过程中对集群没有影响，对正在访问客户端也没有影响（假设这些客户端的 IP 包含在 white list 内）
- 如果添加两个 ip range, 192.168.1.1/16(假设为 A), 192.168.1.1/24(假设为 B), 严格来说，A 包含了 B，但是考虑情况太复杂，并不会对 A 和 B 做合并
- 要删除的时候，必须严格匹配。 也就是如果添加的是 192.168.1.1/24, 要删除也是 192.168.1.1/24
- 集群情况下，各个节点 enableWhiteList 成一样，或者全为 false，或者全为 true，要不然集群无法启动
- 白名单变更生效时间 1s，不超过 2s，每次变更对收发性能有些微影响（多一次判断，可以忽略），变更完之后、影响忽略不计，变更过程中对集群没有影响，对正在访问客户端也没有影响（假设这些客户端的 IP 包含在 white list 内）
- 如果添加两个 ip range，192.168.1.1/16(假设为 A)，192.168.1.1/24(假设为 B)，严格来说，A 包含了 B，但是考虑情况太复杂，并不会对 A 和 B 做合并
- 要删除的时候，必须严格匹配。 也就是如果添加的是 192.168.1.1/24，要删除也是 192.168.1.1/24
- 只有 root 才有权限对其他用户增删 ip white list
- 兼容之前的版本，但是不支持从当前版本回退到之前版本
- x.x.x.x/32 和 x.x.x.x 属于同一个 iprange, 显示为 x.x.x.x
- 如果客户端拿到的 0.0.0.0/0, 说明没有开启白名单
- x.x.x.x/32 和 x.x.x.x 属于同一个 iprange，显示为 x.x.x.x
- 如果客户端拿到的 0.0.0.0/0，说明没有开启白名单
- 如果白名单发生了改变， 客户端会在 heartbeat 里检测到。
- 针对一个 user, 添加的 IP 个数上限是 2048
- 针对一个 user，添加的 IP 个数上限是 2048
## 审计日志
TDengine 先对用户操作进行记录和管理，然后将这些作为审计日志发送给taosKeeper，再由 taosKeeper 保存至任意 TDengine 集群。管理员可通过审计日志进行安全监控、历史追溯。TDengine 的审计日志功能开启和关闭操作非常简单，只须修改TDengine 的配置文件后重启服务。审计日志的配置说明如下。
TDengine 先对用户操作进行记录和管理，然后将这些作为审计日志发送给 taosKeeper，再由 taosKeeper 保存至任意 TDengine 集群。管理员可通过审计日志进行安全监控、历史追溯。TDengine 的审计日志功能开启和关闭操作非常简单，只须修改 TDengine 的配置文件后重启服务。审计日志的配置说明如下。
### taosd 配置
@ -53,7 +53,7 @@ TDengine 先对用户操作进行记录和管理，然后将这些作为审计
| 参数名称 | 参数含义 |
|:-------------:|:--------------------------------------------------------:|
|audit | 是否打开审计日志，默认值为 0。1 为开启，0 为关闭 |
|audit | 是否打开审计日志，1 为开启，0 为关闭，默认值为 0。 |
|monitorFqdn | 接收审计日志的 taosKeeper 所在服务器的 FQDN |
|monitorPort | 接收审计日志的 taosKeeper 服务所用端口 |
|monitorCompaction | 上报数据时是否进行压缩 |
@ -64,7 +64,7 @@ TDengine 先对用户操作进行记录和管理，然后将这些作为审计
| 参数名称 | 参数含义 |
|:-------------:|:--------------------------------------------------------:|
|auditDB | 用于存放审计日志的数据库的名字，默认值为 "audit" ，taosKeeper 在收到上报的审计日志后会判断该数据库是否存在，如果不存在会自动创建它 |
|auditDB | 用于存放审计日志的数据库的名字，默认值为 "audit"，taosKeeper 在收到上报的审计日志后会判断该数据库是否存在，如果不存在会自动创建 |
### 数据格式
@ -88,19 +88,19 @@ TDengine 先对用户操作进行记录和管理，然后将这些作为审计
taosKeeper 会依据上报的审计数据在相应的数据库中自动建立超级表用于存储数据。该超级表的定义如下
```sql
CREATE STABLE operations(ts timestamp, details VARCHAR(64000)， User VARCHAR(25), Operation VARCHAR(20), db VARCHAR(65), resource VARCHAR(193), client_add(25)) TAGS (clusterID VARCHAR(64) );
create stable operations(ts timestamp, details varchar(64000)， user varchar(25), operation varchar(20), db varchar(65), resource varchar(193), client_add(25)) tags (clusterID varchar(64) );
```
其中：
1. db为操作涉及的database，resource为操作涉及的资源。
2. User 和 Operation 为数据列，表示哪个用户在该对象上进行了什么操作
其中
1. db 为操作涉及的 database，resource 为操作涉及的资源。
2. user 和 operation 为数据列，表示哪个用户在该对象上进行了什么操作
3. timestamp 为时间戳列，表示操作发生时的时间
4. details 为该操作的一些补充细节，在大多数操作下是所执行的操作的SQL语句。
5. client_add为客户端地址，包括ip和端口
4. details 为该操作的一些补充细节，在大多数操作下是所执行的操作的 SQL 语句。
5. client_add 为客户端地址，包括 ip 和端口
### 操作列表
目前审计日志中所记录的操作列表以及每个操作中各字段的含义如下表（注：因为每个操作的实加者即 user 字段、时间戳字段和client_add在所有操作中的含义相同，下表不包含）
目前审计日志中所记录的操作列表以及每个操作中各字段的含义（因为每个操作的施加者，即 user、client_add、时间戳字段在所有操作中的含义相同，下表不再描述）
| 操作 | Operation | DB | Resource | Details |
| ----------------| ----------| ---------| ---------| --------|
@ -110,8 +110,8 @@ CREATE STABLE operations(ts timestamp, details VARCHAR(64000)， User VARCHAR(25
| create stable | createStb | db name | stable name | SQL |
| alter stable | alterStb | db name | stable name | SQL |
| drop stable | dropStb | db name | stable name | SQL |
| create user | createUser | NULL | 被创建的用户名 | 用户属性参数, (password除外) |
| alter user | alterUser | NULL | 被修改的用户名 | 修改密码操作记录的是被修改的参数和新值 (password除外) ；其他操作记录SQL |
| create user | createUser | NULL | 被创建的用户名 | 用户属性参数， (password 除外) |
| alter user | alterUser | NULL | 被修改的用户名 | 修改密码记录被修改的参数和新值 (password 除外)，其他操作记录 SQL |
| drop user | dropUser | NULL | 被删除的用户名 | SQL |
| create topic | createTopic | topic 所在 DB | 创建的 topic 名字 | SQL |
| drop topic | cropTopic | topic 所在 DB | 删除的 topic 名字 | SQL |
@ -123,7 +123,7 @@ CREATE STABLE operations(ts timestamp, details VARCHAR(64000)， User VARCHAR(25
| create qnode | createQnode | NULL | dnodeId | SQL |
| drop qnode | dropQnode | NULL | dnodeId | SQL |
| login | login | NULL | NULL | appName |
| create stream | createStream | NULL | 所创建的 strem 名 | SQL |
| create stream | createStream | NULL | 所创建的 stream 名 | SQL |
| drop stream | dropStream | NULL | 所删除的 stream 名 | SQL |
| grant privileges| grantPrivileges | NULL | 所授予的用户 | SQL |
| remove privileges | revokePrivileges | NULL | 被收回权限的用户 | SQL |
@ -171,7 +171,7 @@ database_option: {
```
主要参数说明如下。
encrypt_algorithm：指定数据采用的加密算法。默认是 none，即不采用加密。sm4 表示采用 SM4 加密算法
- encrypt_algorithm：指定数据采用的加密算法。默认是 none，即不采用加密。sm4 表示采用 SM4 加密算法
### 查看加密配置
@ -186,7 +186,7 @@ select name, `encrypt_algorithm` from ins_databases;
### 查看节点密钥状态
通过以下的SQL命令参看节点密钥状态：
通过以下的 SQL 命令参看节点密钥状态。
```sql
show encryptions;
@ -200,12 +200,12 @@ select * from information_schema.ins_encryptions;
```
key_status 有三种取值：
- 当节点未设置密钥时，状态列显示 unset。
- 当密钥被检验成功并且加载后，状态列显示 loaded.
- 当节点未启动，key的状态无法被探知时，状态列显示 unknown
- 当密钥被检验成功并且加载后，状态列显示 loaded。
- 当节点未启动，key 的状态无法被探知时，状态列显示 unknown。
### 更新密钥配置
当节点的硬件配置发生变更时，需要通过以下命令更新密钥，与离线配置密钥的命令相同：
当节点的硬件配置发生变更时，需要通过以下命令更新密钥，与离线配置密钥的命令相同。
```shell
taosd -y {encryptKey}

6
docs/zh/08-operation/18-ha/02-replica2.md
View File

@ -67,11 +67,15 @@ alter database <dbname> replica 2|1
| 异常场景 | 集群状态 |
| ------- | ------ |
| 没有 Vnode 发生故障： Arbitrator 故障（Mnode 宕机节点超过一个，导致 Mnode 无法选主）| **持续提供服务** |
| 没有 Vnode 发生故障：Arbitrator 故障（Mnode 宕机节点超过一个，导致 Mnode 无法选主）| **持续提供服务** |
| 仅一个 Vnode 故障：VGroup 已经达成同步后，某一个 Vnode 才发生故障的 | **持续提供服务** |
| 仅一个 Vnode 故障：2 个 Vnode 同时故障，故障前 VGroup 达成同步，但是只有一个 Vnode 从故障中恢复服务，另一个 Vnode 服务故障 | **通过下面的命令，强制指定 leader, 继续提供服务** |
| 仅一个 Vnode 故障：离线 Vnode 启动后，VGroup 未达成同步前，另一个 Vnode 服务故障的 | **无法提供服务** |
| 两个 Vnode 都发生故障 | **无法提供服务** |
```sql
ASSIGN LEADER FORCE;
```
## 常见问题

22
docs/zh/08-operation/18-ha/03-dual.md
View File

@ -81,7 +81,12 @@ taosx replica start -f source_endpoint -t sink_endpoint [database...]
taosx replica start -f td1:6030 -t td2:6030
```
该示例命令会自动创建除 information_schema、performance_schema、log、audit 库之外的同步任务。可以使用 `http://td2:6041` 指定该 endpoint 使用 websocket 接口（默认是原生接口）。也可以指定数据库同步：taosx replica start -f td1:6030 -t td2:6030 db1 仅创建指定的数据库同步任务。
该示例命令会自动创建除 information_schema、performance_schema、log、audit 库之外的同步任务，并持续监听新增的数据库，当 td1 和 td2 中新增同名数据库时可自动启动新增数据库的数据复制任务。需要说明的是：
- 可以使用 `http://td2:6041` 指定该 endpoint 使用 websocket 接口（默认是原生接口）。
- 可以使用 `--new-database-checking-interval <SECONDS>` 指定新增数据库的检查间隔，默认为 30 分钟。
- 可以使用 `--no-new-databases` 禁用监听行为。
- 也可以指定数据库同步：taosx replica start -f td1:6030 -t td2:6030 db1 仅创建指定的数据库同步任务。此时相当于配置了 `--no-new-databases`，不会开启新增数据库自动同步。
2. 方法二
@ -121,6 +126,7 @@ taosx replica stop id [db...]
该命令作用如下：
1. 停止指定 Replica ID 下所有或指定数据库的双副本同步任务。
2. 使用 `taosx replica stop id1 db1` 表示停止 id1 replica 下 db1的同步任务。
3. `--no-new-databases` 选项启用时，不停止新增数据库监听任务，仅停止当前同步中的数据库。
### 重启双活任务
@ -145,8 +151,8 @@ taosx replica diff id [db....]
| replica | database | source | sink | vgroup_id | current | latest | diff |
+---------+----------+----------+----------+-----------+---------+---------+------+
| a | opc | td1:6030 | td2:6030 | 2 | 17600 | 17600 | 0 |
| ad | opc | td2:6030 | td2:6030 | 3 | 17600 | 17600 | 0 |
```
| a | opc | td2:6030 | td2:6030 | 3 | 17600 | 17600 | 0 |
```
### 删除双活任务
@ -156,6 +162,16 @@ taosx replica remove id [--force]
删除当前所有双活同步任务。正常情况下要想删除同步任务，需要先 stop 该任务；但当 --force 启用时，会强制停止并清除任务。
`--no-new-databases` 选项启用时，不会删除新增数据库同步任务，仅删除当前数据库的同步任务。当 taosx 重启后，如果删除的数据库任务对应的数据库仍然存在，则会继续创建同步任务；不重启 taosx 或者不更新双活监听任务时，也不会再新建这些数据库的同步任务。
### 更新双活新增数据库检查间隔
```shell
taosx replica update id --new-database-checking-interval <SECONDS>
```
更新双活新增数据库的检查间隔，单位为秒。
### 推荐使用步骤
1. 假定在机器 A 上运行，需要首先使用 taosx replica start 来配置 taosX，其输入参数是待同步的源端和目标端服务器地址 ，在完成配置后会自动启动同步服务和任务。此处假定 taosx 服务使用标准端口，同步任务使用原生连接。

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