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

Merge branch '3.0' into feat/TS-5927-long-password

This commit is contained in:
dongming chen 2025-03-05 12:15:12 +08:00 committed by GitHub
parent 71e38429d6 0bbfef749b
commit e5fb75797a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2051 changed files with 34555 additions and 273810 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -6,12 +6,14 @@ on:
- 'main'
- '3.0'
- '3.1'
- 'enh/cmake-TD-33848'
paths-ignore:
- 'docs/**'
- 'packaging/**'
- 'tests/**'
- '*.md'
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
@ -43,15 +45,33 @@ jobs:
if: runner.os == 'Linux'
run: |
sudo apt update -y
sudo apt install -y build-essential cmake \
libgeos-dev libjansson-dev libsnappy-dev liblzma-dev libz-dev \
zlib1g-dev pkg-config libssl-dev gawk
sudo apt install -y \
build-essential \
cmake \
gawk \
libgeos-dev \
libjansson-dev \
liblzma-dev \
libsnappy-dev \
libssl-dev \
libz-dev \
pkg-config \
zlib1g
- name: Install dependencies on macOS
if: runner.os == 'macOS'
run: |
brew update
brew install argp-standalone gflags pkg-config snappy zlib geos jansson gawk openssl
brew install \
argp-standalone \
gawk \
gflags \
geos \
jansson \
openssl \
pkg-config \
snappy \
zlib
- name: Build and install TDengine
run: |
@ -80,7 +100,7 @@ jobs:
run: |
taosBenchmark -t 10 -n 10 -y
taos -s "select count(*) from test.meters"
- name: Clean up
if: always()
run: |

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

@ -0,0 +1,315 @@
name: TDengine CI Test
on:
pull_request:
branches:
- 'main'
- '3.0'
- '3.1'
paths-ignore:
- 'packaging/**'
- 'docs/**'
repository_dispatch:
types: [run-tests]
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
env:
CONTAINER_NAME: 'taosd-test'
WKDIR: '/var/lib/jenkins/workspace'
WK: '/var/lib/jenkins/workspace/TDinternal'
WKC: '/var/lib/jenkins/workspace/TDinternal/community'
jobs:
fetch-parameters:
runs-on:
group: CI
labels: [self-hosted, Linux, X64, testing]
outputs:
tdinternal: ${{ steps.parameters.outputs.tdinternal }}
run_function_test: ${{ steps.parameters.outputs.run_function_test }}
run_tdgpt_test: ${{ steps.parameters.outputs.run_tdgpt_test }}
source_branch: ${{ steps.parameters.outputs.source_branch }}
target_branch: ${{ steps.parameters.outputs.target_branch }}
pr_number: ${{ steps.parameters.outputs.pr_number }}
steps:
- name: Determine trigger source and fetch parameters
id: parameters
run: |
set -euo pipefail
# check the trigger source and get branch information
if [ "${{ github.event_name }}" == "repository_dispatch" ]; then
tdinternal="true"
source_branch=${{ github.event.client_payload.tdinternal_source_branch }}
target_branch=${{ github.event.client_payload.tdinternal_target_branch }}
pr_number=${{ github.event.client_payload.tdinternal_pr_number }}
run_tdgpt_test="true"
run_function_test="true"
else
tdinternal="false"
source_branch=${{ github.event.pull_request.head.ref }}
target_branch=${{ github.event.pull_request.base.ref }}
pr_number=${{ github.event.pull_request.number }}
# 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' ' ' || :)
if [[ "$changed_files_non_doc" != '' && "$changed_files_non_doc" =~ /forecastoperator.c|anomalywindowoperator.c|tanalytics.h|tanalytics.c|tdgpt_cases.task|analytics/ ]]; then
run_tdgpt_test="true"
else
run_tdgpt_test="false"
fi
# 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" | tr '\n' ' ' ||:)
if [ $changed_files_non_tdgpt != '' ]; then
run_function_test="true"
else
run_function_test="false"
fi
fi
echo "tdinternal=$tdinternal" >> $GITHUB_OUTPUT
echo "run_function_test=$run_function_test" >> $GITHUB_OUTPUT
echo "run_tdgpt_test=$run_tdgpt_test" >> $GITHUB_OUTPUT
echo "source_branch=$source_branch" >> $GITHUB_OUTPUT
echo "target_branch=$target_branch" >> $GITHUB_OUTPUT
echo "pr_number=$pr_number" >> $GITHUB_OUTPUT
run-tests-on-linux:
needs: fetch-parameters
runs-on:
group: CI
labels: [self-hosted, Linux, X64, testing]
timeout-minutes: 200
env:
IS_TDINTERNAL: ${{ needs.fetch-parameters.outputs.tdinternal }}
RUN_RUNCTION_TEST: ${{ needs.fetch-parameters.outputs.run_function_test }}
RUN_TDGPT_TEST: ${{ needs.fetch-parameters.outputs.run_tdgpt_tests }}
SOURCE_BRANCH: ${{ needs.fetch-parameters.outputs.source_branch }}
TARGET_BRANCH: ${{ needs.fetch-parameters.outputs.target_branch }}
PR_NUMBER: ${{ needs.fetch-parameters.outputs.pr_number }}
steps:
- name: Output the environment information
run: |
echo "::group::Environment Info"
date
hostname
env
echo "Runner: ${{ runner.name }}"
echo "Trigger Source from TDinternal: ${{ env.IS_TDINTERNAL }}"
echo "Workspace: ${{ env.WKDIR }}"
git --version
echo "${{ env.WKDIR }}/restore.sh -p ${{ env.PR_NUMBER }} -n ${{ github.run_number }} -c ${{ env.CONTAINER_NAME }}"
echo "::endgroup::"
- name: Prepare repositories
run: |
set -euo pipefail
prepare_environment() {
cd "$1"
git reset --hard
git clean -f
git remote prune origin
git fetch
git checkout "$2"
}
prepare_environment "${{ env.WK }}" "${{ env.TARGET_BRANCH }}"
prepare_environment "${{ env.WKC }}" "${{ env.TARGET_BRANCH }}"
- name: Get latest codes and logs for TDinternal PR
if: ${{ env.IS_TDINTERNAL == 'true' }}
run: |
cd ${{ env.WK }}
git pull >/dev/null
git log -5
echo "`date "+%Y%m%d-%H%M%S"` TDinternalTest/${{ env.PR_NUMBER }}:${{ github.run_number }}:${{ env.TARGET_BRANCH }}" >>${{ env.WKDIR }}/jenkins.log
echo "CHANGE_BRANCH:${{ env.SOURCE_BRANCH }}" >>${{ env.WKDIR }}/jenkins.log
echo "TDinternal log: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
git fetch origin +refs/pull/${{ env.PR_NUMBER }}/merge
git checkout -qf FETCH_HEAD
git log -5
echo "TDinternal log merged: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
cd ${{ env.WKC }}
git remote prune origin
git pull >/dev/null
git log -5
echo "community log: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
- name: Get latest codes and logs for TDengine PR
if: ${{ env.IS_TDINTERNAL == 'false' }}
run: |
cd ${{ env.WKC }}
git remote prune origin
git pull >/dev/null
git log -5
echo "`date "+%Y%m%d-%H%M%S"` TDengineTest/${{ env.PR_NUMBER }}:${{ github.run_number }}:${{ env.TARGET_BRANCH }}" >>${{ env.WKDIR }}/jenkins.log
echo "CHANGE_BRANCH:${{ env.SOURCE_BRANCH }}" >>${{ env.WKDIR }}/jenkins.log
echo "community log: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
git fetch origin +refs/pull/${{ env.PR_NUMBER }}/merge
git checkout -qf FETCH_HEAD
git log -5
echo "community log merged: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
cd ${{ env.WK }}
git pull >/dev/null
git log -5
echo "TDinternal log: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
- name: Update submodule
run: |
cd ${{ env.WKC }}
git submodule update --init --recursive
- name: Output the 'file_no_doc_changed' information to the file
if: ${{ env.IS_TDINTERNAL == 'false' }}
run: |
mkdir -p ${{ env.WKDIR }}/tmp/${{ env.PR_NUMBER }}_${{ github.run_number }}
changed_files_non_doc=$(git --no-pager diff --name-only FETCH_HEAD `git merge-base FETCH_HEAD ${{ env.TARGET_BRANCH }}`|grep -v "^docs/en/"|grep -v "^docs/zh/"|grep -v ".md$" | tr '\n' ' ' || :)
echo $changed_files_non_doc > ${{ env.WKDIR }}/tmp/${{ env.PR_NUMBER }}_${{ github.run_number }}/docs_changed.txt
- name: Check assert testing
run: |
cd ${{ env.WKC }}/tests/parallel_test
./run_check_assert_container.sh -d ${{ env.WKDIR }}
- name: Check void function testing
run: |
cd ${{ env.WKC }}/tests/parallel_test
./run_check_void_container.sh -d ${{ env.WKDIR }}
- name: Build docker container
run: |
date
rm -rf ${{ env.WKC }}/debug
cd ${{ env.WKC }}/tests/parallel_test
time ./container_build.sh -w ${{ env.WKDIR }} -e
- name: Get parameters for testing
id: get_param
run: |
log_server_file="/home/log_server.json"
timeout_cmd=""
extra_param=""
if [ -f "$log_server_file" ]; then
log_server_enabled=$(jq '.enabled' "$log_server_file")
timeout_param=$(jq '.timeout' "$log_server_file")
if [ "$timeout_param" != "null" ] && [ "$timeout_param" != "0" ]; then
timeout_cmd="timeout $timeout_param"
fi
if [ "$log_server_enabled" == "1" ]; then
log_server=$(jq '.server' "$log_server_file" | sed 's/\\\"//g')
if [ "$log_server" != "null" ] && [ "$log_server" != "" ]; then
extra_param="-w $log_server"
fi
fi
fi
echo "timeout_cmd=$timeout_cmd" >> $GITHUB_OUTPUT
echo "extra_param=$extra_param" >> $GITHUB_OUTPUT
- name: Run function returns with a null pointer scan testing
run: |
cd ${{ env.WKC }}/tests/parallel_test
./run_scan_container.sh -d ${{ env.WKDIR }} -b ${{ env.PR_NUMBER }}_${{ github.run_number }} -f ${{ env.WKDIR }}/tmp/${{ env.PR_NUMBER }}_${{ github.run_number }}/docs_changed.txt ${{ steps.get_param.outputs.extra_param }}
- name: Run tdgpt test cases
if: ${{ env.IS_TDINTERNAL }} == 'false' && ${{ env.RUN_TDGPT_TEST }} == 'true'
run: |
cd ${{ env.WKC }}/tests/parallel_test
export DEFAULT_RETRY_TIME=2
date
timeout 600 time ./run.sh -e -m /home/m.json -t tdgpt_cases.task -b ${{ env.PR_NUMBER }}_${{ github.run_number }} -l ${{ env.WKDIR }}/log -o 300 ${{ steps.get_param.outputs.extra_param }}
- name: Run function test cases
if: ${{ env.RUN_RUNCTION_TEST }} == 'true'
run: |
cd ${{ env.WKC }}/tests/parallel_test
export DEFAULT_RETRY_TIME=2
date
${{ steps.get_param.outputs.timeout_cmd }} time ./run.sh -e -m /home/m.json -t cases.task -b ${{ env.PR_NUMBER }}_${{ github.run_number }} -l ${{ env.WKDIR }}/log -o 1200 ${{ steps.get_param.outputs.extra_param }}
run-tests-on-mac:
needs: fetch-parameters
if: ${{ needs.fetch-parameters.outputs.run_function_test == 'false' }}
runs-on:
group: CI
labels: [self-hosted, macOS, ARM64, testing]
timeout-minutes: 60
env:
IS_TDINTERNAL: ${{ needs.fetch-parameters.outputs.tdinternal }}
SOURCE_BRANCH: ${{ needs.fetch-parameters.outputs.source_branch }}
TARGET_BRANCH: ${{ needs.fetch-parameters.outputs.target_branch }}
PR_NUMBER: ${{ needs.fetch-parameters.outputs.pr_number }}
steps:
- name: Output the environment information
run: |
echo "::group::Environment Info"
date
hostname
env
echo "Runner: ${{ runner.name }}"
echo "Trigger Source from TDinternal: ${{ env.IS_TDINTERNAL }}"
echo "Workspace: ${{ env.WKDIR }}"
git --version
echo "${{ env.WKDIR }}/restore.sh -p ${{ env.PR_NUMBER }} -n ${{ github.run_number }} -c ${{ env.CONTAINER_NAME }}"
echo "::endgroup::"
- name: Prepare repositories
run: |
set -euo pipefail
prepare_environment() {
cd "$1"
git reset --hard
git clean -f
git remote prune origin
git fetch
git checkout "$2"
}
prepare_environment "${{ env.WK }}" "${{ env.TARGET_BRANCH }}"
prepare_environment "${{ env.WKC }}" "${{ env.TARGET_BRANCH }}"
- name: Get latest codes and logs for TDinternal PR
if: ${{ env.IS_TDINTERNAL == 'true' }}
run: |
cd ${{ env.WK }}
git pull >/dev/null
git log -5
echo "`date "+%Y%m%d-%H%M%S"` TDinternalTest/${{ env.PR_NUMBER }}:${{ github.run_number }}:${{ env.TARGET_BRANCH }}" >>${{ env.WKDIR }}/jenkins.log
echo "CHANGE_BRANCH:${{ env.SOURCE_BRANCH }}" >>${{ env.WKDIR }}/jenkins.log
echo "TDinternal log: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
git fetch origin +refs/pull/${{ env.PR_NUMBER }}/merge
git checkout -qf FETCH_HEAD
git log -5
echo "TDinternal log merged: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
cd ${{ env.WKC }}
git remote prune origin
git pull >/dev/null
git log -5
echo "community log: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
- name: Get latest codes and logs for TDengine PR
if: ${{ env.IS_TDINTERNAL == 'false' }}
run: |
cd ${{ env.WKC }}
git remote prune origin
git pull >/dev/null
git log -5
echo "`date "+%Y%m%d-%H%M%S"` TDengineTest/${{ env.PR_NUMBER }}:${{ github.run_number }}:${{ env.TARGET_BRANCH }}" >>${{ env.WKDIR }}/jenkins.log
echo "CHANGE_BRANCH:${{ env.SOURCE_BRANCH }}" >>${{ env.WKDIR }}/jenkins.log
echo "community log: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
git fetch origin +refs/pull/${{ env.PR_NUMBER }}/merge
git checkout -qf FETCH_HEAD
git log -5
echo "community log merged: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
cd ${{ env.WK }}
git pull >/dev/null
git log -5
echo "TDinternal log: `git log -5`" >>${{ env.WKDIR }}/jenkins.log
- name: Update submodule
run: |
cd ${{ env.WKC }}
git submodule update --init --recursive
- name: Run tests
run: |
date
cd ${{ env.WK }}
rm -rf debug
mkdir debug
cd ${{ env.WK }}/debug
echo $PATH
echo "PATH=/opt/homebrew/bin:$PATH" >> $GITHUB_ENV
cmake .. -DBUILD_TEST=true -DBUILD_HTTPS=false -DCMAKE_BUILD_TYPE=Release
make -j10
ctest -j10 || exit 7
date

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

@ -0,0 +1,49 @@
name: TDengine Doc Build
on:
pull_request:
branches:
- 'main'
- '3.0'
- '3.1'
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

4
.github/workflows/taoskeeper-ci.yml → .github/workflows/taoskeeper-ci-build.yml vendored
View File

@ -1,4 +1,4 @@
name: taosKeeper CI
name: taosKeeper Build
on:
push:
@ -8,7 +8,7 @@ on:
jobs:
build:
runs-on: ubuntu-latest
name: Run unit tests
name: Build and test on ubuntu-latest
steps:
- name: Checkout the repository

2
Jenkinsfile2
View File

@ -70,7 +70,7 @@ def check_docs(){
returnStdout: true
)
def file_no_doc_changed = sh (
file_no_doc_changed = sh (
script: '''
cd ${WKC}
git --no-pager diff --name-only FETCH_HEAD `git merge-base FETCH_HEAD ${CHANGE_TARGET}`|grep -v "^docs/en/"|grep -v "^docs/zh/"|grep -v ".md$" || :

10
README-CN.md
View File

@ -69,6 +69,8 @@ TDengine 是一款开源、高性能、云原生的时序数据库 (Time-Series
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系统
<details>
@ -153,6 +155,10 @@ cmake .. -DBUILD_TOOLS=true -DBUILD_CONTRIB=true
make
```
如果你想要编译 taosAdapter，需要添加 `-DBUILD_HTTP=false` 选项。
如果你想要编译 taosKeeper，需要添加 `--DBUILD_KEEPER=true` 选项。
可以使用Jemalloc作为内存分配器，而不是使用glibc:
```bash
@ -180,6 +186,10 @@ mkdir debug && cd debug
cmake .. && cmake --build .
```
如果你想要编译 taosAdapter，需要添加 `-DBUILD_HTTP=false` 选项。
如果你想要编译 taosKeeper，需要添加 `--DBUILD_KEEPER=true` 选项。
</details>
## 4.3 Windows系统上构建

12
README.md
View File

@ -22,7 +22,7 @@
[![LinkedIn](https://img.shields.io/badge/Follow_LinkedIn--white?logo=linkedin&style=social)](https://www.linkedin.com/company/tdengine)
[![StackOverflow](https://img.shields.io/badge/Ask_StackOverflow--white?logo=stackoverflow&style=social&logoColor=orange)](https://stackoverflow.com/questions/tagged/tdengine)
English | [简体中文](README-CN.md) | [TDengine Cloud](https://cloud.tdengine.com) | [Learn more about TSDB](https://tdengine.com/tsdb/)
English | [简体中文](README-CN.md) | [TDengine Cloud](https://cloud.tdengine.com) | [Learn more about TSDB](https://tdengine.com/time-series-database/)
# Table of Contents
@ -82,6 +82,8 @@ For contributing/building/testing TDengine Connectors, please check the followin
At the moment, TDengine server supports running on Linux/Windows/MacOS systems. Any application can also choose the RESTful interface provided by taosAdapter to connect the taosd service. TDengine supports X64/ARM64 CPU, and it will support MIPS64, Alpha64, ARM32, RISC-V and other CPU architectures in the future. Right now we don't support build with cross-compiling environment.
If you want to compile taosAdapter or taosKeeper, you need to install Go 1.18 or above.
## 3.1 On Linux
<details>
@ -168,6 +170,10 @@ cmake .. -DBUILD_TOOLS=true -DBUILD_CONTRIB=true
make
```
If you want to compile taosAdapter, you need to add the `-DBUILD_HTTP=false` option.
If you want to compile taosKeeper, you need to add the `--DBUILD_KEEPER=true` option.
You can use Jemalloc as memory allocator instead of glibc:
```bash
@ -196,6 +202,10 @@ mkdir debug && cd debug
cmake .. && cmake --build .
```
If you want to compile taosAdapter, you need to add the `-DBUILD_HTTP=false` option.
If you want to compile taosKeeper, you need to add the `--DBUILD_KEEPER=true` option.
</details>
## 4.3 Build on Windows

13
cmake/cmake.define
View File

@ -117,7 +117,7 @@ ELSE()
ENDIF()
# force set all platform to JEMALLOC_ENABLED = false
SET(JEMALLOC_ENABLED OFF)
# SET(JEMALLOC_ENABLED OFF)
IF(TD_WINDOWS)
MESSAGE("${Yellow} set compiler flag for Windows! ${ColourReset}")
@ -258,3 +258,14 @@ ELSE()
SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-reserved-user-defined-literal -g3 -Wno-literal-suffix -Werror=return-type -fPIC -gdwarf-2 -Wformat=2 -Wno-format-nonliteral -Wno-format-truncation -Wno-format-y2k")
ENDIF()
ENDIF()
IF(TD_LINUX)
IF(${JEMALLOC_ENABLED})
MESSAGE(STATUS "JEMALLOC_ENABLED Enabled")
SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-error=attributes")
SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-error=attributes")
ELSE()
MESSAGE(STATUS "JEMALLOC_ENABLED Disabled")
ENDIF()
ENDIF()

14
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)
@ -15,6 +15,18 @@ IF (TD_PRODUCT_NAME)
ADD_DEFINITIONS(-DTD_PRODUCT_NAME="${TD_PRODUCT_NAME}")
ENDIF ()
IF (CUS_NAME)
ADD_DEFINITIONS(-DCUS_NAME="${CUS_NAME}")
ENDIF ()
IF (CUS_PROMPT)
ADD_DEFINITIONS(-DCUS_PROMPT="${CUS_PROMPT}")
ENDIF ()
IF (CUS_EMAIL)
ADD_DEFINITIONS(-DCUS_EMAIL="${CUS_EMAIL}")
ENDIF ()
find_program(HAVE_GIT NAMES git)
IF (DEFINED GITINFO)

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)

2
docs/en/07-develop/04-schemaless.md
View File

@ -304,7 +304,7 @@ Not supported
## Querying the Written Data
By running the example code from the previous section, tables will be automatically created in the power database. We can query the data using taos shell or an application. Below is an example of querying the data from the supertable and meters table using taos shell.
By running the example code from the previous section, tables will be automatically created in the power database. We can query the data using TDengine CLI or an application. Below is an example of querying the data from the supertable and meters table using TDengine CLI.
```shell
taos> show power.stables;

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

@ -10,7 +10,7 @@ TDengine provides data subscription and consumption interfaces similar to those
## Creating Topics
Please use taos shell or refer to the [Execute SQL](../running-sql-statements/) section to execute the SQL for creating topics: `CREATE TOPIC IF NOT EXISTS topic_meters AS SELECT ts, current, voltage, phase, groupid, location FROM meters`
Please use TDengine CLI or refer to the [Execute SQL](../running-sql-statements/) section to execute the SQL for creating topics: `CREATE TOPIC IF NOT EXISTS topic_meters AS SELECT ts, current, voltage, phase, groupid, location FROM meters`
The above SQL will create a subscription named topic_meters. Each record in the messages obtained using this subscription is composed of the columns selected by this query statement `SELECT ts, current, voltage, phase, groupid, location FROM meters`.
@ -44,6 +44,9 @@ There are many parameters for creating consumers, which flexibly support various
| `enable.replay` | boolean | Whether to enable data replay function | Default is off |
| `session.timeout.ms` | integer | Timeout after consumer heartbeat is lost, after which rebalance logic is triggered, and upon success, that consumer will be removed (supported from version 3.3.3.0) | Default is 12000, range [6000, 1800000] |
| `max.poll.interval.ms` | integer | The longest time interval for consumer poll data fetching, exceeding this time will be considered as the consumer being offline, triggering rebalance logic, and upon success, that consumer will be removed (supported from version 3.3.3.0) | Default is 300000, range [1000, INT32_MAX] |
| `fetch.max.wait.ms` | integer | The maximum time it takes for the server to return data once (supported from version 3.3.6.0) | Default is 1000, range [1, INT32_MAX] |
| `min.poll.rows` | integer | The minimum number of data returned by the server once (supported from version 3.3.6.0) | Default is 4096, range [1, INT32_MAX]
| `msg.consume.rawdata` | integer | When consuming data, the data type pulled is binary and cannot be parsed. It is an internal parameter and is only used for taosx data migration（supported from version 3.3.6.0） | The default value of 0 indicates that it is not effective, and non-zero indicates that it is effective |
Below are the connection parameters for connectors in various languages:
<Tabs defaultValue="java" groupId="lang">

2
docs/en/08-operation/02-planning.md
View File

@ -87,7 +87,7 @@ Additionally, to accelerate the data processing process, TDengine specifically s
```text
Users can use the performance testing tool taosBenchmark to assess the data compression effect of TDengine. By using the -f option to specify the write configuration file, taosBenchmark can write a specified number of CSV sample data into the specified database parameters and table structure.
After completing the data writing, users can execute the flush database command in the taos shell to force all data to be written to the disk. Then, use the du command of the Linux operating system to get the size of the data folder of the specified vnode. Finally, divide the original data size by the actual storage data size to calculate the real compression ratio.
After completing the data writing, users can execute the flush database command in the TDengine CLI to force all data to be written to the disk. Then, use the du command of the Linux operating system to get the size of the data folder of the specified vnode. Finally, divide the original data size by the actual storage data size to calculate the real compression ratio.
```
The following command can be used to obtain the storage space occupied by TDengine.

8
docs/en/08-operation/03-deployment/01-manual.md
View File

@ -55,7 +55,7 @@ For dnodes wishing to join the cluster, it is essential to ensure that the param
### 5. Start
Start the first dnode, such as `h1.tdengine.com`, following the steps mentioned above. Then execute taos in the terminal to start TDengine's CLI program taos, and execute the `show dnodes` command within it to view all dnode information in the current cluster.
Start the first dnode, such as `h1.tdengine.com`, following the steps mentioned above. Then execute taos in the terminal to start TDengine CLI program taos, and execute the `show dnodes` command within it to view all dnode information in the current cluster.
```shell
taos> show dnodes;
@ -68,7 +68,7 @@ You can see that the endpoint of the dnode node that has just started is `h1.tde
### 6. Adding dnode
Follow the steps mentioned earlier, start taosd on each physical node. Each dnode needs to configure the firstEp parameter in the taos.cfg file to the endpoint of the first node of the new cluster, which in this case is `h1.tdengine.com:6030`. On the machine where the first dnode is located, run taos in the terminal, open TDengine's CLI program taos, then log into the TDengine cluster, and execute the following SQL.
Follow the steps mentioned earlier, start taosd on each physical node. Each dnode needs to configure the firstEp parameter in the taos.cfg file to the endpoint of the first node of the new cluster, which in this case is `h1.tdengine.com:6030`. On the machine where the first dnode is located, run taos in the terminal, open TDengine CLI program taos, then log into the TDengine cluster, and execute the following SQL.
```shell
create dnode "h2.tdengine.com:6030"
@ -84,13 +84,13 @@ In the logs, please confirm that the fqdn and port of the output dnode are consi
**Tips**
- Any dnode that has joined the cluster can serve as the firstEp for subsequent nodes to be added. The firstEp parameter only functions when that dnode first joins the cluster. After joining, the dnode will save the latest mnode's endpoint list, and subsequently, it no longer depends on this parameter. The firstEp parameter in the configuration file is mainly used for client connections, and if no parameters are set for TDengine's CLI, it will default to connecting to the node specified by firstEp.
- Any dnode that has joined the cluster can serve as the firstEp for subsequent nodes to be added. The firstEp parameter only functions when that dnode first joins the cluster. After joining, the dnode will save the latest mnode's endpoint list, and subsequently, it no longer depends on this parameter. The firstEp parameter in the configuration file is mainly used for client connections, and if no parameters are set for TDengine CLI, it will default to connecting to the node specified by firstEp.
- Two dnodes that have not configured the firstEp parameter will run independently after starting. At this time, it is not possible to join one dnode to another to form a cluster.
- TDengine does not allow merging two independent clusters into a new cluster.
### 7. Adding mnode
When creating a TDengine cluster, the first dnode automatically becomes the mnode of the cluster, responsible for managing and coordinating the cluster. To achieve high availability of mnode, subsequent dnodes need to manually create mnode. Please note that a cluster can create up to 3 mnodes, and only one mnode can be created on each dnode. When the number of dnodes in the cluster reaches or exceeds 3, you can create mnode for the existing cluster. In the first dnode, first log into TDengine through the CLI program taos, then execute the following SQL.
When creating a TDengine cluster, the first dnode automatically becomes the mnode of the cluster, responsible for managing and coordinating the cluster. To achieve high availability of mnode, subsequent dnodes need to manually create mnode. Please note that a cluster can create up to 3 mnodes, and only one mnode can be created on each dnode. When the number of dnodes in the cluster reaches or exceeds 3, you can create mnode for the existing cluster. In the first dnode, first log into TDengine through TDengine CLI program taos, then execute the following SQL.
```shell
create mnode on dnode <dnodeId>

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

@ -456,7 +456,7 @@ export POD_NAME=$(kubectl get pods --namespace default \
kubectl --namespace default exec $POD_NAME -- taos -s "show dnodes; show mnodes"
3. Run into taos shell:
3. Run into TDengine CLI:
kubectl --namespace default exec -it $POD_NAME -- taos
```

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

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

7
docs/en/10-third-party/01-collection/flink.md vendored
View File

@ -26,6 +26,8 @@ Flink Connector supports all platforms that can run Flink 1.19 and above version
| Flink Connector Version | Major Changes | TDengine Version|
|-------------------------| ------------------------------------ | ---------------- |
| 2.1.0 | Fix the issue of writing varchar types from different data sources.| - |
| 2.0.2 | The Table Sink supports types such as RowKind.UPDATE_BEFORE, RowKind.UPDATE_AFTER, and RowKind.DELETE.| - |
| 2.0.1 | Sink supports writing types from Rowdata implementations.| - |
| 2.0.0 | 1.Support SQL queries on data in TDengine database. <br/> 2. Support CDC subscription to data in TDengine database.<br/> 3. Supports reading and writing to TDengine database using Table SQL. | 3.3.5.1 and higher|
| 1.0.0 | Support Sink function to write data from other sources to TDengine in the future.| 3.3.2.0 and higher|
@ -85,7 +87,8 @@ TDengine currently supports timestamp, number, character, and boolean types, and
| SMALLINT | Short |
| TINYINT | Byte |
| BOOL | Boolean |
| BINARY | byte[] |
| VARCHAR | StringData |
| BINARY | StringData |
| NCHAR | StringData |
| JSON | StringData |
| VARBINARY | byte[] |
@ -115,7 +118,7 @@ If using Maven to manage a project, simply add the following dependencies in pom
<dependency>
<groupId>com.taosdata.flink</groupId>
<artifactId>flink-connector-tdengine</artifactId>
<version>2.0.1</version>
<version>2.1.0</version>
</dependency>
```

87
docs/en/10-third-party/05-bi/03-powerbi.md vendored
View File

@ -7,36 +7,24 @@ Power BI is a business analytics tool provided by Microsoft. By configuring the
## Prerequisites
Install and run Power BI Desktop software (if not installed, please download the latest version for Windows OS 32/64 bit from its official address).
- TDengine 3.3.4.0 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 Power BI Desktop software (if not installed, please download the latest version for Windows OS 32/64 bit from its official address).
- Download the latest Windows OS X64 client driver from the TDengine official website and install it on the machine running Power BI. After successful installation, the TDengine driver can be seen in the "ODBC Data Sources (32-bit)" or "ODBC Data Sources (64-bit)" management tool.
## Install ODBC Driver
## Configure Data Source
Download the latest Windows OS X64 client driver from the TDengine official website and install it on the machine running Power BI. After successful installation, the TDengine driver can be seen in the "ODBC Data Sources (32-bit)" or "ODBC Data Sources (64-bit)" management tool.
**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).
**Step 2**, Open Power BI and log in, click [Home] -> [Get Data] -> [Other] -> [ODBC] -> [Connect], add data source.
## Configure ODBC Data Source
**Step 3**, Select the data source name just created, such as [MyTDengine], if you need to enter SQL, you can click the [Advanced options] tab, in the expanded dialog box enter the SQL statement. Click the [OK] button to connect to the configured data source.
The steps to configure the ODBC data source are as follows.
**Step 4**, Enter the [Navigator], you can browse the corresponding database's tables/views and load data.
Step 1, search and open "ODBC Data Sources (32-bit)" or "ODBC Data Sources (64-bit)" management tool from the Windows start menu.
Step 2, click the "User DSN" tab → "Add" button, enter the "Create New Data Source" dialog box.
Step 3, in the list of "Select the driver you want to install for this data source" choose "TDengine", click the "Finish" button, enter the TDengine ODBC data source configuration page. Fill in the necessary information as follows.
## Data Analysis
- DSN: Data source name, required, such as "MyTDengine".
- Connection Type: Check the "WebSocket" checkbox.
- URL: ODBC data source URL, required, such as `http://127.0.0.1:6041`.
- Database: Indicates the database to connect to, optional, such as "test".
- Username: Enter username, if not filled, default is "root".
- Password: Enter user password, if not filled, default is "taosdata".
Step 4, click the "Test Connection" button, test the connection situation, if successfully connected, it will prompt "Successfully connected to `http://127.0.0.1:6041`".
Step 5, click the "OK" button, to save the configuration and exit.
## Import TDengine Data into Power BI
The steps to import TDengine data into Power BI are as follows:
Step 1, open Power BI and log in, click "Home" → "Get Data" → "Other" → "ODBC" → "Connect", add data source.
Step 2, select the data source name just created, such as "MyTDengine", if you need to enter SQL, you can click the "Advanced options" tab, in the expanded dialog box enter the SQL statement. Click the "OK" button to connect to the configured data source.
Step 3, enter the "Navigator", you can browse the corresponding database's tables/views and load data.
### Instructions for use
To fully leverage Power BI's advantages in analyzing data from TDengine, users need to first understand core concepts such as dimensions, metrics, window split queries, data split queries, time-series, and correlation, then import data through custom SQL.
@ -47,7 +35,7 @@ To fully leverage Power BI's advantages in analyzing data from TDengine, users n
- Time-Series: When drawing curves or aggregating data by time, it is usually necessary to introduce a date table. Date tables can be imported from Excel spreadsheets, or obtained in TDengine by executing SQL like `select _wstart date, count(*) cnt from test.meters where ts between A and B interval(1d) fill(0)`, where the fill clause represents the filling mode in case of data missing, and the pseudocolumn `_wstart` is the date column to be obtained.
- Correlation: Tells how data is related, such as metrics and dimensions can be associated together through the tbname column, date tables and metrics can be associated through the date column, combined to form visual reports.
## Smart Meter Example
### Smart Meter Example
TDengine employs a unique data model to optimize the storage and query performance of time-series data. This model uses supertables as templates to create an independent table for each device. Each table is designed with high scalability in mind, supporting up to 4096 data columns and 128 tag columns. This design enables TDengine to efficiently handle large volumes of time-series data while maintaining flexibility and ease of use.
@ -56,24 +44,35 @@ Taking smart meters as an example, suppose each meter generates one record per s
In Power BI, users can map the tag columns in TDengine tables to dimension columns for grouping and filtering data. Meanwhile, the aggregated results of the data columns can be imported as measure columns for calculating key indicators and generating reports. In this way, Power BI helps decision-makers quickly obtain the information they need, gain a deeper understanding of business operations, and make more informed decisions.
Follow the steps below to experience the functionality of generating time-series data reports through Power BI.
Step 1, Use TDengine's taosBenchMark to quickly generate data for 1,000 smart meters over 3 days, with a collection frequency of 1s.
```shell
taosBenchmark -t 1000 -n 259200 -S 1000 -y
```
Step 2, Import dimension data. In Power BI, import the tag columns of the table, named as tags, using the following SQL to get the tag data of all smart meters under the supertable.
```sql
select distinct tbname device, groupId, location from test.meters
```
Step 3, Import measure data. In Power BI, import the average current, voltage, and phase of each smart meter in 1-hour time windows, named as data, with the following SQL.
```sql
select tbname, _wstart ws, avg(current), avg(voltage), avg(phase) from test.meters PARTITION by tbname interval(1h)
```
Step 4, Import date data. Using a 1-day time window, obtain the time range and data count of the time-series data, with the following SQL. In the Power Query editor, convert the format of the date column from "text" to "date".
```sql
select _wstart date, count(*) from test.meters interval(1d) having count(*)>0
```
Step 5, Establish the relationship between dimensions and measures. Open the model view and establish the relationship between the tags and data tables, setting tbname as the relationship data column.
Step 6, Establish the relationship between date and measures. Open the model view and establish the relationship between the date dataset and data, with the relationship data columns being date and datatime.
Step 7, Create reports. Use these data in bar charts, pie charts, and other controls.
**Step 1**, Use TDengine's taosBenchMark to quickly generate data for 1,000 smart meters over 3 days, with a collection frequency of 1s.
```shell
taosBenchmark -t 1000 -n 259200 -S 1000 -y
```
**Step 2**, Import dimension data. In Power BI, import the tag columns of the table, named as tags, using the following SQL to get the tag data of all smart meters under the supertable.
```sql
select distinct tbname device, groupId, location from test.meters
```
**Step 3**, Import measure data. In Power BI, import the average current, voltage, and phase of each smart meter in 1-hour time windows, named as data, with the following SQL.
```sql
select tbname, _wstart ws, avg(current), avg(voltage), avg(phase) from test.meters PARTITION by tbname interval(1h)
```
**Step 4**, Import date data. Using a 1-day time window, obtain the time range and data count of the time-series data, with the following SQL. In the Power Query editor, convert the format of the date column from "text" to "date".
```sql
select _wstart date, count(*) from test.meters interval(1d) having count(*)>0
```
**Step 5**, Establish the relationship between dimensions and measures. Open the model view and establish the relationship between the tags and data tables, setting tbname as the relationship data column.
**Step 6**, Establish the relationship between date and measures. Open the model view and establish the relationship between the date dataset and data, with the relationship data columns being date and datatime.
**Step 7**, Create reports. Use these data in bar charts, pie charts, and other controls.
Due to TDengine's superior performance in handling time-series data, users can enjoy a very good experience during data import and daily regular data refreshes. For more information on building Power BI visual effects, please refer to the official Power BI documentation.

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

@ -11,43 +11,44 @@ import imgStep04 from '../../assets/seeq-04.png';
Seeq is advanced analytics software for the manufacturing and Industrial Internet of Things (IIOT). Seeq supports innovative new features using machine learning in process manufacturing organizations. These features enable organizations to deploy their own or third-party machine learning algorithms to advanced analytics applications used by frontline process engineers and subject matter experts, thus extending the efforts of a single data scientist to many frontline staff.
Through the TDengine Java connector, Seeq can easily support querying time-series data provided by TDengine and offer data presentation, analysis, prediction, and other functions.
Through the `TDengine Java connector`, Seeq can easily support querying time-series data provided by TDengine and offer data presentation, analysis, prediction, and other functions.
## Prerequisites
- Seeq has been installed. Download the relevant software from [Seeq's official website](https://www.seeq.com/customer-download), such as Seeq Server and Seeq Data Lab, etc. Seeq Data Lab needs to be installed on a different server from Seeq Server and interconnected through configuration. For detailed installation and configuration instructions, refer to the [Seeq Knowledge Base](https://support.seeq.com/kb/latest/cloud/).
- TDengine 3.1.0.3 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/).
- Seeq has been installed. Download the relevant software from [Seeq's official website](https://www.seeq.com/customer-download), such as `Seeq Server` and `Seeq Data Lab`, etc. `Seeq Data Lab` needs to be installed on a different server from `Seeq Server` and interconnected through configuration. For detailed installation and configuration instructions, refer to the [Seeq Knowledge Base](https://support.seeq.com/kb/latest/cloud/).
- Install the JDBC driver. Download the `TDengine JDBC connector` file `taos-jdbcdriver-3.2.5-dist.jar` or a higher version from `maven.org`.
- TDengine local instance has been installed. Please refer to the [official documentation](../../../get-started). If using TDengine Cloud, please go to https://cloud.taosdata.com apply for an account and log in to see how to access TDengine Cloud.
## Configure Data Source
## Configuring Seeq to Access TDengine
1. Check the data storage location
**Step 1**, Check the data storage location
```shell
sudo seeq config get Folders/Data
```
2. Download the TDengine Java connector package from maven.org, the latest version is [3.2.5](https://repo1.maven.org/maven2/com/taosdata/jdbc/taos-jdbcdriver/3.2.5/taos-jdbcdriver-3.2.5-dist.jar), and copy it to the plugins\lib in the data storage location.
**Step 2**, Download the TDengine Java connector package from `maven.org` and copy it to the `plugins\lib` directory in the data storage location.
3. Restart seeq server
**Step 3**, Restart seeq server
```shell
sudo seeq restart
```
4. Enter License
**Step 4**, Enter License
Use a browser to visit ip:34216 and follow the instructions to enter the license.
## Using Seeq to Analyze TDengine Time-Series Data
This section demonstrates how to use Seeq software in conjunction with TDengine for time-series data analysis.
## 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.
### Data Schema
### Data preparation
**Step 1**, Create tables in TDengine.
```sql
CREATE STABLE meters (ts TIMESTAMP, num INT, temperature FLOAT, goods INT) TAGS (device NCHAR(20));
@ -58,7 +59,7 @@ CREATE TABLE goods (ts1 TIMESTAMP, ts2 TIMESTAMP, goods FLOAT);
<Image img={imgStep01} alt=""/>
</figure>
### Data Construction Method
**Step 2**, Construct data in TDengine.
```shell
python mockdata.py
@ -67,11 +68,7 @@ taos -s "insert into power.goods select _wstart, _wstart + 10d, avg(goods) from
The source code is hosted on [GitHub Repository](https://github.com/sangshuduo/td-forecasting).
## Using Seeq for Data Analysis
### Configuring Data Source
Log in using a Seeq administrator role account and create a new data source.
**第 3 步**，Log in using a Seeq administrator role account and create a new data source.
- Power
@ -330,77 +327,7 @@ Program output results:
<Image img={imgStep03} alt=""/>
</figure>
## Configuring Seeq Data Source Connection to TDengine Cloud
Configuring a Seeq data source connection to TDengine Cloud is essentially no different from connecting to a local TDengine installation. Simply log in to TDengine Cloud, select "Programming - Java" and copy the JDBC string with a token to fill in as the DatabaseJdbcUrl value for the Seeq Data Source.
Note that when using TDengine Cloud, the database name needs to be specified in SQL commands.
### Configuration example using TDengine Cloud as a data source
```json
{
"QueryDefinitions": [
{
"Name": "CloudVoltage",
"Type": "SIGNAL",
"Sql": "SELECT ts, voltage FROM test.meters",
"Enabled": true,
"TestMode": false,
"TestQueriesDuringSync": true,
"InProgressCapsulesEnabled": false,
"Variables": null,
"Properties": [
{
"Name": "Name",
"Value": "Voltage",
"Sql": null,
"Uom": "string"
},
{
"Name": "Interpolation Method",
"Value": "linear",
"Sql": null,
"Uom": "string"
},
{
"Name": "Maximum Interpolation",
"Value": "2day",
"Sql": null,
"Uom": "string"
}
],
"CapsuleProperties": null
}
],
"Type": "GENERIC",
"Hostname": null,
"Port": 0,
"DatabaseName": null,
"Username": "root",
"Password": "taosdata",
"InitialSql": null,
"TimeZone": null,
"PrintRows": false,
"UseWindowsAuth": false,
"SqlFetchBatchSize": 100000,
"UseSSL": false,
"JdbcProperties": null,
"GenericDatabaseConfig": {
"DatabaseJdbcUrl": "jdbc:TAOS-RS://gw.cloud.tdengine.com?useSSL=true&token=41ac9d61d641b6b334e8b76f45f5a8XXXXXXXXXX",
"SqlDriverClassName": "com.taosdata.jdbc.rs.RestfulDriver",
"ResolutionInNanoseconds": 1000,
"ZonedColumnTypes": []
}
}
```
### Example of Seeq Workbench Interface with TDengine Cloud as Data Source
<figure>
<Image img={imgStep04} alt=""/>
</figure>
## Solution Summary
### Solution Summary
By integrating Seeq and TDengine, users can fully leverage the efficient storage and querying capabilities of TDengine, while also benefiting from the powerful data visualization and analysis features provided by Seeq.

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)

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

@ -0,0 +1,45 @@
---
sidebar_label: Tableau
title: Integration With Tableau
toc_max_heading_level: 4
---
Tableau is a well-known business intelligence tool that supports multiple data sources, making it easy to connect, import, and integrate data. And through an intuitive user interface, users can create rich and diverse visual charts, with powerful analysis and filtering functions, providing strong support for data decision-making. Users can import tag data, raw time-series data, or time-series data aggregated over time from TDengine into Tableau via the TDengine ODBC Connector to create reports or dashboards, and no code writing is required throughout the entire process.
## Prerequisites
Prepare the following environment:
- 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).
## Configure Data Source
**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.
![tableau-odbc](./tableau/tableau-odbc.jpg)
## Data Analysis
**Step 1**, In the workbook page, the connected data sources will be displayed. Clicking on the dropdown list of databases will display the databases that require data analysis. On this basis, click the search button in the table options to display all tables in the database. Then, drag the table to be analyzed to the right area to display the table structure.
![tableau-workbook](./tableau/tableau-table.jpg)
**Step 2**, Click the `Update Now` button below to display the data in the table.
![tableau-workbook](./tableau/tableau-data.jpg)
**Step 3**, Click on the "Worksheet" at the bottom of the window to pop up the data analysis window, which displays all the fields of the analysis table. Drag the fields to the rows and columns to display the chart.
![tableau-workbook](./tableau/tableau-analysis.jpg)

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

@ -0,0 +1,42 @@
---
sidebar_label: Excel
title: Integration With Excel
toc_max_heading_level: 4
---
By configuring the use of the ODBC connector, Excel can quickly access data from TDengine. Users can import tag data, raw time-series data, or time-aggregated time series data from TDengine into Excel to create reports or dashboards, all without the need for any coding.
## Prerequisites
Prepare the following environment:
- 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).
## Configure Data Source
**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).
**Step 2**, Start Excel in the Windows system environment, then select [Data] -> [Get Data] -> [From Other Sources] -> [From ODBC].
![excel-odbc](./excel/odbc-menu.jpg)
**Step 3**, In the pop-up window, select the data source you need to connect to from the drop-down list of [Data source name (DSN)], and then click the [OK] button.
![excel-odbc](./excel/odbc-select.jpg)
**Step 4**, Enter the username and password for TDengine.
![excel-odbc](./excel/odbc-config.jpg)
**Step 5**, In the pop-up [Navigator] dialog box, select the database tables you want to load, and then click [Load] to complete the data loading.
![excel-odbc](./excel/odbc-load.jpg)
## Data Analysis
Select the imported data. On the [Insert] tab, choose the column chart, and then configure the data fields in the [PivotChart Fields] pane on the right.
![excel-odbc](./excel/odbc-data.jpg)

BIN
docs/en/10-third-party/05-bi/excel/odbc-config.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 300 KiB

BIN
docs/en/10-third-party/05-bi/excel/odbc-data.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 761 KiB

BIN
docs/en/10-third-party/05-bi/excel/odbc-load.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.3 MiB

BIN
docs/en/10-third-party/05-bi/excel/odbc-menu.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 659 KiB

BIN
docs/en/10-third-party/05-bi/excel/odbc-select.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 505 KiB

BIN
docs/en/10-third-party/05-bi/tableau/tableau-analysis.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 243 KiB

BIN
docs/en/10-third-party/05-bi/tableau/tableau-data.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 255 KiB

BIN
docs/en/10-third-party/05-bi/tableau/tableau-odbc.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 226 KiB

BIN
docs/en/10-third-party/05-bi/tableau/tableau-table.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 107 KiB

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

@ -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:
@ -243,6 +243,8 @@ The effective value of charset is UTF-8.
| concurrentCheckpoint | |Supported, effective immediately | Internal parameter, whether to check checkpoints concurrently |
| maxStreamBackendCache | |Supported, effective immediately | Internal parameter, maximum cache used by stream computing |
| streamSinkDataRate | |Supported, effective after restart| Internal parameter, used to control the write speed of stream computing results |
| streamNotifyMessageSize | After 3.3.6.0 | Not supported | Internal parameter, controls the message size for event notifications, default value is 8192 |
| streamNotifyFrameSize | After 3.3.6.0 | Not supported | Internal parameter, controls the underlying frame size when sending event notification messages, default value is 256 |
### Log Related
@ -532,29 +534,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 |

144
docs/en/14-reference/02-tools/08-taos-cli.md
View File

@ -6,6 +6,9 @@ slug: /tdengine-reference/tools/tdengine-cli
The TDengine command line program (hereinafter referred to as TDengine CLI) is the simplest and most commonly used tool for users to operate and interact with TDengine instances. It requires the installation of either the TDengine Server package or the TDengine Client package before use.
## Get
TDengine CLI is the default installation component in the TDengine server and client installation package. It can be used after installation, refer to [TDengine Installation](../../../get-started/)
## Startup
To enter the TDengine CLI, simply execute `taos` in the terminal.
@ -29,15 +32,83 @@ To exit the TDengine CLI, execute `q`, `quit`, or `exit` and press enter.
taos> quit
```
## Command Line Parameters
### Basic Parameters
You can change the behavior of the TDengine CLI by configuring command line parameters. Below are some commonly used command line parameters:
- -h HOST: The FQDN of the server where the TDengine service is located, default is to connect to the local service.
- -P PORT: Specifies the port number used by the server.
- -u USER: Username to use when connecting.
- -p PASSWORD: Password to use when connecting to the server.
- -?, --help: Prints out all command line parameters.
- -s COMMAND: SQL command executed in non-interactive mode.
Use the `-s` parameter to execute SQL non interactively, and exit after execution. This mode is suitable for use in automated scripts.
For example, connect to the server h1.taos.com with the following command, and execute the SQL specified by `-s`:
```bash
taos -h my-server -s "use db; show tables;"
```
- -c CONFIGDIR: Specify the configuration file directory.
In Linux, the default is `/etc/tao`. The default name of the configuration file in this directory is `taos.cfg`.
Use the `-c` parameter to change the location where the `taosc` client loads the configuration file. For client configuration parameters, refer to [Client Configuration](../../components/taosc).
The following command specifies the `taos.cfg` configuration file under `/root/cfg/` loaded by the `taosc` client.
```bash
taos -c /root/cfg/
```
### Advanced Parameters
- -a AUTHSTR: Authorization information for connecting to the server.
- -A: Calculate authorization information using username and password.
- -B: Set BI tool display mode, after setting, all outputs follow the format of BI tools.
- -C: Print the configuration parameters of `taos.cfg` in the directory specified by -c.
- -d DATABASE: Specifies the database to use when connecting to the server.
- -E dsn: Connect to cloud services or servers providing WebSocket connections using WebSocket DSN.
- -f FILE: Execute SQL script file in non-interactive mode. Each SQL statement in the file must occupy one line.
- -k: Test the running status of the server, 0: unavailable, 1: network ok, 2: service ok, 3: service degraded, 4: exiting.
- -l PKTLEN: Test packet size used during network testing.
- -n NETROLE: Test range during network connection testing, default is `client`, options are `client`, `server`.
- -N PKTNUM: Number of test packets used during network testing.
- -r: Convert time columns to unsigned 64-bit integer type output (i.e., uint64_t in C language).
- -R: Connect to the server using RESTful mode.
- -t: Test the startup status of the server, status same as -k.
- -w DISPLAYWIDTH: Client column display width.
- -z TIMEZONE: Specifies the timezone, default is the local timezone.
- -V: Print the current version number.
## Data Export/Import
### Data Export To a File
- You can use the symbol “>>” to export query results to a file, the syntax is: sql query statement >> 'output file name'; If no path is written for the output file, it will be output to the current directory. For example, `select * from d0 >> '/root/d0.csv';` will output the query results to /root/d0.csv.
### Data Import From a File
- You can use insert into table_name file 'input file name', to import the data file exported in the previous step back into the specified table. For example, `insert into d0 file '/root/d0.csv';` means to import all the data exported above back into the d0 table.
## Execute SQL Scripts
In the TDengine CLI, you can run multiple SQL commands from a script file using the `source` command.
In the TDengine CLI, you can run multiple SQL commands from a script file using the `source` command, multiple SQL statements in the script file can be written in line.
```sql
taos> source <filename>;
```
## Online Modification of Display Character Width
## TDengine CLI Tips
### TAB Key Completion
- Pressing the TAB key when no command is present will list all commands supported by TDengine CLI.
- Pressing the TAB key when preceded by a space will display the first of all possible command words at this position, pressing TAB again will switch to the next one.
- If a string precedes the TAB key, it will search for all command words that match the prefix of this string and display the first one, pressing TAB again will switch to the next one.
- Entering a backslash `\` + TAB key, will automatically complete to the column display mode command word `\G;`.
### Modification of Display Character Width
You can adjust the display character width in the TDengine CLI using the following command:
@ -47,71 +118,16 @@ taos> SET MAX_BINARY_DISPLAY_WIDTH <nn>;
If the displayed content ends with ..., it indicates that the content has been truncated. You can modify the display character width with this command to display the full content.
## Command Line Parameters
### Other
You can change the behavior of the TDengine CLI by configuring command line parameters. Below are some commonly used command line parameters:
- You can use the up and down arrow keys to view previously entered commands.
- In TDengine CLI, use the `alter user` command to change user passwords, the default password is `taosdata`.
- Ctrl+C to stop a query that is in progress.
- Execute `RESET QUERY CACHE` to clear the cache of the local table Schema.
- Batch execute SQL statements.
You can store a series of TDengine CLI commands (ending with a semicolon `;`, each SQL statement on a new line) in a file, and execute the command `source <file-name>` in TDengine CLI to automatically execute all SQL statements in that file.
- -h HOST: The FQDN of the server where the TDengine service is located, default is to connect to the local service
- -P PORT: Specifies the port number used by the server
- -u USER: Username to use when connecting
- -p PASSWORD: Password to use when connecting to the server
- -?, --help: Prints out all command line parameters
There are many other parameters:
- -a AUTHSTR: Authorization information for connecting to the server
- -A: Calculate authorization information using username and password
- -B: Set BI tool display mode, after setting, all outputs follow the format of BI tools
- -c CONFIGDIR: Specify the configuration file directory, default in Linux environment is `/etc/taos`, the default name of the configuration file in this directory is `taos.cfg`
- -C: Print the configuration parameters of `taos.cfg` in the directory specified by -c
- -d DATABASE: Specifies the database to use when connecting to the server
- -E dsn: Connect to cloud services or servers providing WebSocket connections using WebSocket DSN
- -f FILE: Execute SQL script file in non-interactive mode. Each SQL statement in the file must occupy one line
- -k: Test the running status of the server, 0: unavailable, 1: network ok, 2: service ok, 3: service degraded, 4: exiting
- -l PKTLEN: Test packet size used during network testing
- -n NETROLE: Test range during network connection testing, default is `client`, options are `client`, `server`
- -N PKTNUM: Number of test packets used during network testing
- -r: Convert time columns to unsigned 64-bit integer type output (i.e., uint64_t in C language)
- -R: Connect to the server using RESTful mode
- -s COMMAND: SQL command executed in non-interactive mode
- -t: Test the startup status of the server, status same as -k
- -w DISPLAYWIDTH: Client column display width
- -z TIMEZONE: Specifies the timezone, default is the local timezone
- -V: Print the current version number
Example:
```shell
taos -h h1.taos.com -s "use db; show tables;"
```
## Configuration File
You can also control the behavior of the TDengine CLI through parameters set in the configuration file. For available configuration parameters, please refer to [Client Configuration](../../components/taosc)
## Error Code Table
Starting from TDengine version 3.3.4.8, TDengine CLI returns specific error codes in error messages. Users can visit the TDengine official website's error code page to find specific reasons and solutions, see: [Error Code Reference](../../error-codes/)
## TDengine CLI TAB Key Completion
- Pressing the TAB key when no command is present will list all commands supported by TDengine CLI
- Pressing the TAB key when preceded by a space will display the first of all possible command words at this position, pressing TAB again will switch to the next one
- If a string precedes the TAB key, it will search for all command words that match the prefix of this string and display the first one, pressing TAB again will switch to the next one
- Entering a backslash `\` + TAB key, will automatically complete to the column display mode command word `\G;`
## TDengine CLI Tips
- You can use the up and down arrow keys to view previously entered commands
- In TDengine CLI, use the `alter user` command to change user passwords, the default password is `taosdata`
- Ctrl+C to stop a query that is in progress
- Execute `RESET QUERY CACHE` to clear the cache of the local table Schema
- Batch execute SQL statements. You can store a series of TDengine CLI commands (ending with a semicolon `;`, each SQL statement on a new line) in a file, and execute the command `source <file-name>` in TDengine CLI to automatically execute all SQL statements in that file
## TDengine CLI Export Query Results to a File
- You can use the symbol “>>” to export query results to a file, the syntax is: sql query statement >> 'output file name'; If no path is written for the output file, it will be output to the current directory. For example, select * from d0 >> '/root/d0.csv'; will output the query results to /root/d0.csv.
## TDengine CLI Import Data from a File into a Table
- You can use insert into table_name file 'input file name', to import the data file exported in the previous step back into the specified table. For example, insert into d0 file '/root/d0.csv'; means to import all the data exported above back into the d0 table.

104
docs/en/14-reference/02-tools/09-taosdump.md
View File

@ -6,45 +6,26 @@ slug: /tdengine-reference/tools/taosdump
`taosdump` is a TDengine data backup/recovery tool provided for open source users, and the backed up data files adopt the standard [Apache AVRO](https://avro.apache.org/)
Format, convenient for exchanging data with the external ecosystem.
Taosdump provides multiple data backup and recovery options to meet different data needs, and all supported options can be viewed through --help.
taosdump provides multiple data backup and recovery options to meet different data needs, and all supported options can be viewed through --help.
## Installation
## Get
taosdump is the default installation component in the TDengine installation package, which can be used after installing TDengine. For how to install TDengine, please refer to [TDengine Installation](../../../get-started/)
taosdump is the default installation component in the TDengine server and client installation package. It can be used after installation, refer to [TDengine Installation](../../../get-started/)
## Common Use Cases
## Startup
### taosdump Backup Data
taosdump needs to be run in the command line terminal. It must be run with parameters to indicate backup or restore operations, such as:
``` bash
taosdump -h my-server -D test -o /root/test/
```
The above command means to backup the `test` database on the `my server` machine to the `/root/test/` directory.
1. Backup all databases: specify the `-A` or `--all-databases` parameter;
2. Backup multiple specified databases: use the `-D db1,db2,...` parameter;
3. Backup certain supertables or basic tables in a specified database: use the `dbname stbname1 stbname2 tbname1 tbname2 ...` parameter, note that this input sequence starts with the database name, supports only one database, and the second and subsequent parameters are the names of the supertables or basic tables in that database, separated by spaces;
4. Backup the system log database: TDengine clusters usually include a system database named `log`, which contains data for TDengine's own operation, taosdump does not back up the log database by default. If there is a specific need to back up the log database, you can use the `-a` or `--allow-sys` command line parameter.
5. "Tolerant" mode backup: Versions after taosdump 1.4.1 provide the `-n` and `-L` parameters, used for backing up data without using escape characters and in "tolerant" mode, which can reduce backup data time and space occupied when table names, column names, and label names do not use escape characters. If unsure whether to use `-n` and `-L`, use the default parameters for "strict" mode backup. For an explanation of escape characters, please refer to the [official documentation](../../sql-manual/escape-characters/).
6. If a backup file already exists in the directory specified by the `-o` parameter, to prevent data from being overwritten, taosdump will report an error and exit. Please replace it with another empty directory or clear the original data before backing up.
7. Currently, taosdump does not support data breakpoint backup function. Once the data backup is interrupted, it needs to be started from scratch.
If the backup takes a long time, it is recommended to use the (-S -E options) method to specify the start/end time for segmented backup.
``` bash
taosdump -h my-server -i /root/test/
```
The above command means to restore the previously backed up data files in the `/root/test/` directory to the host named `my server`.
:::tip
- Versions after taosdump 1.4.1 provide the `-I` parameter, used for parsing avro file schema and data, specifying the `-s` parameter will only parse the schema.
- Backups after taosdump 1.4.2 use the `-B` parameter to specify the number of batches, the default value is 16384. If "Error actual dump .. batch .." occurs due to insufficient network speed or disk performance in some environments, you can try adjusting the `-B` parameter to a smaller value.
- taosdump's export does not support interruption recovery, so the correct way to handle an unexpected termination of the process is to delete all related files that have been exported or generated.
- taosdump's import supports interruption recovery, but when the process restarts, you may receive some "table already exists" prompts, which can be ignored.
:::
### taosdump Restore Data
- Restore data files from a specified path: use the `-i` parameter along with the data file path. As mentioned earlier, the same directory should not be used to back up different data sets, nor should the same path be used to back up the same data set multiple times, otherwise, the backup data will cause overwriting or multiple backups.
- taosdump supports data recovery to a new database name with the parameter `-W`, please refer to the command line parameter description for details.
:::tip
taosdump internally uses the TDengine stmt binding API to write restored data, currently using 16384 as a batch for writing. If there are many columns in the backup data, it may cause a "WAL size exceeds limit" error, in which case you can try adjusting the `-B` parameter to a smaller value.
:::
## Detailed Command Line Parameters List
## Command Line Parameters
Below is the detailed command line parameters list for taosdump:
@ -65,8 +46,8 @@ Usage: taosdump [OPTION...] dbname [tbname ...]
-c, --config-dir=CONFIG_DIR Configure directory. Default is /etc/taos
-i, --inpath=INPATH Input file path.
-o, --outpath=OUTPATH Output file path.
-r, --resultFile=RESULTFILE DumpOut/In Result file path and name.
-a, --allow-sys Allow to dump system database
-r, --resultFile=RESULTFILE DumpOut/In Result file path and name.
-a, --allow-sys Allow to dump system database.
-A, --all-databases Dump all databases.
-D, --databases=DATABASES Dump inputted databases. Use comma to separate
databases' name.
@ -98,23 +79,54 @@ Usage: taosdump [OPTION...] dbname [tbname ...]
-n, --no-escape No escape char '`'. Default is using it.
-Q, --dot-replace Replace dot character with underline character in
the table name.(Version 2.5.3)
-T, --thread-num=THREAD_NUM Number of thread for dump in file. Default is
8.
-W, --rename=RENAME-LIST Rename database name with new name during
-T, --thread-num=THREAD_NUM Number of thread for dump in file. Default is 8.
-W, --rename=RENAME-LIST Rename database name with new name during.
importing data. RENAME-LIST:
"db1=newDB1|db2=newDB2" means rename db1 to newDB1
and rename db2 to newDB2 (Version 2.5.4)
and rename db2 to newDB2 (Version 2.5.4).
-k, --retry-count=VALUE Set the number of retry attempts for connection or
query failures
-z, --retry-sleep-ms=VALUE retry interval sleep time, unit ms
-C, --cloud=CLOUD_DSN specify a DSN to access TDengine cloud service
-R, --restful Use RESTful interface to connect TDengine
query failures.
-z, --retry-sleep-ms=VALUE retry interval sleep time, unit ms.
-C, --cloud=CLOUD_DSN specify a DSN to access TDengine cloud service.
-R, --restful Use RESTful interface to connect TDengine.
-t, --timeout=SECONDS The timeout seconds for websocket to interact.
-g, --debug Print debug info.
-?, --help Give this help list
--usage Give a short usage message
-V, --version Print program version
-?, --help Give this help list.
--usage Give a short usage message.
-V, --version Print program version.
Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.
```
## Common Use Cases
### Backup Data
1. Backup all databases: specify the `-A` or `--all-databases` parameter.
2. Backup multiple specified databases: use the `-D db1,db2,...` parameter.
3. Backup certain supertables or basic tables in a specified database: use the `dbname stbname1 stbname2 tbname1 tbname2 ...` parameter, note that this input sequence starts with the database name, supports only one database, and the second and subsequent parameters are the names of the supertables or basic tables in that database, separated by spaces.
4. Backup the system log database: TDengine clusters usually include a system database named `log`, which contains data for TDengine's own operation, taosdump does not back up the log database by default. If there is a specific need to back up the log database, you can use the `-a` or `--allow-sys` command line parameter.
5. "Tolerant" mode backup: Versions after taosdump 1.4.1 provide the `-n` and `-L` parameters, used for backing up data without using escape characters and in "tolerant" mode, which can reduce backup data time and space occupied when table names, column names, and label names do not use escape characters. If unsure whether to use `-n` and `-L`, use the default parameters for "strict" mode backup. For an explanation of escape characters, please refer to the [official documentation](../../sql-manual/escape-characters/)
6. If a backup file already exists in the directory specified by the `-o` parameter, to prevent data from being overwritten, taosdump will report an error and exit. Please replace it with another empty directory or clear the original data before backing up.
7. Currently, taosdump does not support data breakpoint backup function. Once the data backup is interrupted, it needs to be started from scratch.
If the backup takes a long time, it is recommended to use the (-S -E options) method to specify the start/end time for segmented backup.
:::tip
- Versions after taosdump 1.4.1 provide the `-I` parameter, used for parsing avro file schema and data, specifying the `-s` parameter will only parse the schema.
- Backups after taosdump 1.4.2 use the `-B` parameter to specify the number of batches, the default value is 16384. If "Error actual dump .. batch .." occurs due to insufficient network speed or disk performance in some environments, you can try adjusting the `-B` parameter to a smaller value.
- taosdump's export does not support interruption recovery, so the correct way to handle an unexpected termination of the process is to delete all related files that have been exported or generated.
- taosdump's import supports interruption recovery, but when the process restarts, you may receive some "table already exists" prompts, which can be ignored.
:::
### Restore Data
- Restore data files from a specified path: use the `-i` parameter along with the data file path. As mentioned earlier, the same directory should not be used to back up different data sets, nor should the same path be used to back up the same data set multiple times, otherwise, the backup data will cause overwriting or multiple backups.
- taosdump supports data recovery to a new database name with the parameter `-W`, please refer to the command line parameter description for details.
:::tip
taosdump internally uses the TDengine stmt binding API to write restored data, currently using 16384 as a batch for writing. If there are many columns in the backup data, it may cause a "WAL size exceeds limit" error, in which case you can try adjusting the `-B` parameter to a smaller value.
:::

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

@ -2,30 +2,33 @@
title: taosBenchmark Reference
sidebar_label: taosBenchmark
slug: /tdengine-reference/tools/taosbenchmark
toc_max_heading_level: 4
---
TaosBenchmark is a performance benchmarking tool for TDengine products, providing insertion, query, and subscription performance testing for TDengine products, and outputting performance indicators.
## Installation
## Get
taosBenchmark is the default installation component in the TDengine installation package, which can be used after installing TDengine. For how to install TDengine, please refer to [TDengine Installation](../../../get started/)
taosBenchmark is the default installation component in the TDengine server and client installation package. It can be used after installation, refer to [TDengine Installation](../../../get-started/)
## Operation
## Startup
### Configuration and Operation Methods
taosbenchmark supports three operating modes:
- No Parameter Mode
- Command Line Mode
- JSON Configuration File Mode
taosBbenchmark supports three operating modes:
- No parameter mode
- Command line mode
- JSON configuration file mode
The command-line approach is a subset of the functionality of JSON configuration files, which immediately uses the command line and then the configuration file, with the parameters specified by the command line taking precedence.
The `Command Line Mode` is a subset of the `JSON Configuration File Mode` function. When both are used at the same time, the `Command Line Mode` takes precedence.
**Ensure that the TDengine cluster is running correctly before running taosBenchmark.**
:::tip
Ensure that the TDengine cluster is running correctly before running taosBenchmark.
:::
### Running Without Command Line Arguments
### No Parameter Mode
Execute the following command to quickly experience taosBenchmark performing a write performance test on TDengine based on the default configuration.
```shell
taosBenchmark
```
@ -33,17 +36,18 @@ taosBenchmark
When running without parameters, taosBenchmark defaults to connecting to the TDengine cluster specified in `/etc/taos/taos.cfg `.
After successful connection, a smart meter example database test, super meters, and 10000 sub meters will be created, with 10000 records per sub meter. If the test database already exists, it will be deleted before creating a new one.
### Running Using Command Line Configuration Parameters
### Command Line Mode
When running taosBenchmark using command line parameters and controlling its behavior, the `-f <json file>` parameter cannot be used. All configuration parameters must be specified through the command line. Below is an example of using command line mode to test the write performance of taosBenchmark.
The parameters supported by the command line are those frequently used in the write function. The query and subscription function does not support the command line mode.
For example:
```shell
taosBenchmark -I stmt -n 200 -t 100
```bash
taosBenchmark -d db -t 100 -n 1000 -T 4 -I stmt -y
```
The above command `taosBenchmark` will create a database named `test`, establish a supertable `meters` within it, create 100 subtables in the supertable, and insert 200 records into each subtable using parameter binding.
This command means that using `taosBenchmark` will create a database named `db`, create the default super table `meters`, sub table 100, and use parameter binding (stmt) to write 1000 records for each sub table.
### Running Using a Configuration File
### JSON Configuration File Mode
Running in configuration file mode provides all functions, so parameters can be configured to run in the configuration file.
@ -51,42 +55,8 @@ Running in configuration file mode provides all functions, so parameters can be
taosBenchmark -f <json file>
```
**Below are a few examples of configuration files:**
#### JSON Configuration File Example for Insertion Scenario
<details>
<summary>insert.json</summary>
```json
{{#include /TDengine/tools/taos-tools/example/insert.json}}
```
</details>
#### Example JSON Configuration File for Query Scenario
<details>
<summary>query.json</summary>
```json
{{#include /TDengine/tools/taos-tools/example/query.json}}
```
</details>
#### Example JSON Configuration File for Subscription Scenario
<details>
<summary>tmq.json</summary>
```json
{{#include /TDengine/tools/taos-tools/example/tmq.json}}
```
</details>
## Detailed Explanation of Command Line Parameters
## Command Line Parameters
- **-f/--file \<json file>** :
The JSON configuration file to use, specifying all parameters. This parameter cannot be used simultaneously with other command line parameters. There is no default value.
@ -212,62 +182,7 @@ taosBenchmark -A INT,DOUBLE,NCHAR,BINARY\(16\)
Displays help information and exits. Cannot be used with other parameters.
## Output performance indicators
#### Write indicators
After writing is completed, a summary performance metric will be output in the last two lines in the following format:
``` bash
SUCC: Spent 8.527298 (real 8.117379) seconds to insert rows: 10000000 with 8 thread(s) into test 1172704.41 (real 1231924.74) records/second
SUCC: insert delay, min: 19.6780ms, avg: 64.9390ms, p90: 94.6900ms, p95: 105.1870ms, p99: 130.6660ms, max: 157.0830ms
```
First line write speed statistics:
- Spent: Total write time, in seconds, counting from the start of writing the first data to the end of the last data. This indicates that a total of 8.527298 seconds were spent
- Real: Total write time (calling the engine), excluding the time spent preparing data for the testing framework. Purely counting the time spent on engine calls, The time spent is 8.117379 seconds. If 8.527298-8.117379=0.409919 seconds, it is the time spent preparing data for the testing framework
- Rows: Write the total number of rows, which is 10 million pieces of data
- Threads: The number of threads being written, which is 8 threads writing simultaneously
- Records/second write speed = `total write time` / `total number of rows written`, real in parentheses is the same as before, indicating pure engine write speed
Second line single write delay statistics:
- min: Write minimum delay
- avg: Write normal delay
- p90: Write delay p90 percentile delay number
- p95: Write delay p95 percentile delay number
- p99: Write delay p99 percentile delay number
- max: maximum write delay
Through this series of indicators, the distribution of write request latency can be observed
#### Query indicators
The query performance test mainly outputs the QPS indicator of query request speed, and the output format is as follows:
``` bash
complete query with 3 threads and 10000 query delay avg: 0.002686s min: 0.001182s max: 0.012189s p90: 0.002977s p95: 0.003493s p99: 0.004645s SQL command: select ...
INFO: Spend 26.9530 second completed total queries: 30000, the QPS of all threads: 1113.049
```
- The first line represents the percentile distribution of query execution and query request delay for each of the three threads executing 10000 queries. The SQL command is the test query statement
- The second line indicates that the total query time is 26.9653 seconds, the total queries is 10000 * 3 = 30000, and the query rate per second (QPS) is 1113.049 times/second
- If the `continue_if_fail` option is set to `yes` in the query, the last line will output the number of failed requests and error rate, the format like "error + number of failed requests (error rate)"
- QPS = number of successful requests / time spent (in seconds)
- Error rate = number of failed requests / (number of successful requests + number of failed requests)
#### Subscription metrics
The subscription performance test mainly outputs consumer consumption speed indicators, with the following output format:
``` bash
INFO: consumer id 0 has poll total msgs: 376, period rate: 37.592 msgs/s, total rows: 3760000, period rate: 375924.815 rows/s
INFO: consumer id 1 has poll total msgs: 362, period rate: 36.131 msgs/s, total rows: 3620000, period rate: 361313.504 rows/s
INFO: consumer id 2 has poll total msgs: 364, period rate: 36.378 msgs/s, total rows: 3640000, period rate: 363781.731 rows/s
INFO: consumerId: 0, consume msgs: 1000, consume rows: 10000000
INFO: consumerId: 1, consume msgs: 1000, consume rows: 10000000
INFO: consumerId: 2, consume msgs: 1000, consume rows: 10000000
INFO: Consumed total msgs: 3000, total rows: 30000000
```
- Lines 1 to 3 real-time output of the current consumption speed of each consumer, msgs/s represents the number of consumption messages, each message contains multiple rows of data, and rows/s represents the consumption speed calculated by rows
- Lines 4 to 6 show the overall statistics of each consumer after the test is completed, including the total number of messages consumed and the total number of lines
- The overall statistics of all consumers in line 7, `msgs` represents how many messages were consumed in total, `rows` represents how many rows of data were consumed in total
## Configuration File Parameters Detailed Explanation
## Configuration File Parameters
### General Configuration Parameters
@ -284,7 +199,7 @@ The parameters listed in this section apply to all functional modes.
- **password** : Password for connecting to the TDengine server, default value is taosdata.
### Configuration Parameters for Insertion Scenarios
### Insertion Configuration Parameters
In insertion scenarios, `filetype` must be set to `insert`. For this parameter and other common parameters, see Common Configuration Parameters.
@ -299,7 +214,7 @@ In insertion scenarios, `filetype` must be set to `insert`. For this parameter a
“continue_if_fail”: “yes”, taosBenchmark warns the user and continues writing
“continue_if_fail”: “smart”, if the child table does not exist upon failure, taosBenchmark will create the child table and continue writing
#### Database Related Configuration Parameters
#### Database Parameters
Parameters related to database creation are configured in the `dbinfo` section of the json configuration file, specific parameters are as follows. Other parameters correspond to those specified in TDengine's `create database`, see [../../taos-sql/database]
@ -307,23 +222,7 @@ Parameters related to database creation are configured in the `dbinfo` section o
- **drop**: Whether to delete the database before insertion, options are "yes" or "no", "no" means do not create. Default is to delete.
#### Stream Computing Related Configuration Parameters
Parameters related to stream computing are configured in the `stream` section of the json configuration file, specific parameters are as follows.
- **stream_name**: Name of the stream computing, mandatory.
- **stream_stb**: Name of the supertable corresponding to the stream computing, mandatory.
- **stream_sql**: SQL statement for the stream computing, mandatory.
- **trigger_mode**: Trigger mode for the stream computing, optional.
- **watermark**: Watermark for the stream computing, optional.
- **drop**: Whether to create stream computing, options are "yes" or "no", "no" means do not create.
#### Supertable Related Configuration Parameters
#### Supertable Parameters
Parameters related to supertable creation are configured in the `super_tables` section of the json configuration file, specific parameters are as follows.
@ -357,7 +256,7 @@ Parameters related to supertable creation are configured in the `super_tables` s
- **childtable_limit** : Effective only when child_table_exists is yes, specifies the limit when getting the subtable list from the supertable.
- **interlace_rows** : Enables interlaced insertion mode and specifies the number of rows to insert into each subtable at a time. Interlaced insertion mode means inserting the number of rows specified by this parameter into each subtable in turn and repeating this process until all subtable data is inserted. The default value is 0, i.e., data is inserted into one subtable before moving to the next subtable.
- **interlace_rows** : Enables interlaced insertion mode and specifies the number of rows to insert into each subtable at a time. Interlaced insertion mode means inserting the number of rows specified by this parameter into each subtable in turn and repeating this process until all subtable data is inserted. The default is 0, i.e., data is inserted into one subtable before moving to the next subtable.
- **insert_interval** : Specifies the insertion interval for interlaced insertion mode, in ms, default value is 0. Only effective when `-B/--interlace-rows` is greater than 0. It means that the data insertion thread will wait for the time interval specified by this value after inserting interlaced records for each subtable before proceeding to the next round of writing.
@ -385,7 +284,7 @@ Parameters related to supertable creation are configured in the `super_tables` s
- **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
#### Tag and Data Column Configuration Parameters
#### Tag and Data Columns
Specify the configuration parameters for tag and data columns in `super_tables` under `columns` and `tag`.
@ -420,7 +319,7 @@ Specify the configuration parameters for tag and data columns in `super_tables`
- **fillNull**: String type, specifies whether this column randomly inserts NULL values, can be specified as "true" or "false", only effective when generate_row_rule is 2.
#### Insertion Behavior Configuration Parameters
#### Insertion Behavior Parameters
- **thread_count**: The number of threads for inserting data, default is 8.
@ -432,7 +331,7 @@ Specify the configuration parameters for tag and data columns in `super_tables`
- **confirm_parameter_prompt** : A toggle parameter that requires user confirmation after a prompt to continue. The value can be "yes" or "no", by default "no".
- **interlace_rows** : Enables interleaved insertion mode and specifies the number of rows to insert into each subtable at a time. Interleaved insertion mode refers to inserting the specified number of rows into each subtable in sequence and repeating this process until all subtable data has been inserted. The default value is 0, meaning data is inserted into one subtable completely before moving to the next.
- **interlace_rows** : Enables interleaved insertion mode and specifies the number of rows to insert into each subtable at a time. Interleaved insertion mode refers to inserting the specified number of rows into each subtable in sequence and repeating this process until all subtable data has been inserted. The default is 0, meaning data is inserted into one subtable completely before moving to the next.
This parameter can also be configured in `super_tables`; if configured, the settings in `super_tables` take higher priority and override the global settings.
- **insert_interval** :
@ -442,68 +341,84 @@ Specify the configuration parameters for tag and data columns in `super_tables`
- **num_of_records_per_req** :
The number of data rows requested per write to TDengine, default is 30000. If set too high, the TDengine client driver will return corresponding error messages, and this parameter needs to be reduced to meet the writing requirements.
- **prepare_rand** : The number of unique values in the generated random data. If it is 1, it means all data are the same. The default value is 10000.
- **prepare_rand** : The number of unique values in the generated random data. If it is 1, it means all data are the same. The default is 10000.
- **pre_load_tb_meta** : Whether to pre-load the meta data of subtables, values are “yes” or "no". When there are a large number of subtables, turning on this option can improve the writing speed.
### Configuration Parameters for Query Scenarios
### Query Parameters
In query scenarios, `filetype` must be set to `query`.
`query_times` specifies the number of times to run the query, numeric type.
Query scenarios can control the execution of slow query statements by setting `kill_slow_query_threshold` and `kill_slow_query_interval` parameters, where threshold controls that queries exceeding the specified exec_usec time will be killed by taosBenchmark, in seconds; interval controls the sleep time to avoid continuous slow query CPU consumption, in seconds.
For other common parameters, see Common Configuration Parameters.
For other common parameters, see [General Configuration Parameters](#general-configuration-parameters)
#### Configuration Parameters for Executing Specified Query Statements
Configuration parameters for querying specified tables (can specify supertables, subtables, or regular tables) are set in `specified_table_query`.
- `General Query`: Each SQL in `sqls` starts `threads` threads to query this SQL, Each thread exits after executing the `query_times` queries, and only after all threads executing this SQL have completed can the next SQL be executed.
The total number of queries(`General Query`) = the number of `sqls` * `query_times` * `threads`
- `Mixed Query` : All SQL statements in `sqls` are divided into `threads` groups, with each thread executing one group. Each SQL statement needs to execute `query_times` queries.
The total number of queries(`Mixed Query`) = the number of `sqls` * `query_times`
#### Specified Query
Configuration parameters for querying specified tables (can specify supertables, subtables, or regular tables) are set in `specified_table_query`.
- **mixed_query** : Query Mode . "yes" is `Mixed Query`, "no" is `General Query`, default is "no".
`General Query`:
Each SQL in `sqls` starts `threads` threads to query this SQL, Each thread exits after executing the `query_times` queries, and only after all threads executing this SQL have completed can the next SQL be executed.
The total number of queries(`General Query`) = the number of `sqls` * `query_times` * `threads`
`Mixed Query`:
All SQL statements in `sqls` are divided into `threads` groups, with each thread executing one group. Each SQL statement needs to execute `query_times` queries.
The total number of queries(`Mixed Query`) = the number of `sqls` * `query_times`
- **query_interval** : Query interval, in millisecond, default is 0.
- **threads** : Number of threads executing the SQL query, default is 1.
- **sqls**:
- **sql**: The SQL command to execute, required.
- **result**: File to save the query results, if not specified, results are not saved.
#### Configuration Parameters for Querying Supertables
#### Supertables
Configuration parameters for querying supertables are set in `super_table_query`.
The thread mode of the super table query is the same as the `Normal Query` mode of the specified query statement described above, except that `sqls` is filled all sub tables.
- **stblname** : The name of the supertable to query, required.
- **query_interval** : Query interval, in seconds, default is 0.
- **threads** : Number of threads executing the SQL query, default is 1.
- **sqls** :
- **sql** : The SQL command to execute, required; for supertable queries, keep "xxxx" in the SQL command, the program will automatically replace it with all subtable names of the supertable.
- **result** : File to save the query results, if not specified, results are not saved.
- **Note**: The maximum number of SQL arrays configured under SQL is 100.
### Configuration Parameters for Subscription Scenarios
### Subscription Parameters
In subscription scenarios, `filetype` must be set to `subscribe`, this parameter and other common parameters see Common Configuration Parameters.
In the subscription scenario, `filetype` must be set to `subscribe`. For details of this parameter and other general parameters, see [General Configuration Parameters](#general-configuration-parameters)
The subscription configuration parameters are set under `tmq_info`. The parameters are as follows:
#### Configuration Parameters for Executing Specified Subscription Statements
- **concurrent**: the number of consumers who consume subscriptions, or the number of concurrent consumers. The default value is 1.
- **create_mode**: create a consumer mode.
Which can be sequential: create in sequence. parallel: It is created at the same time. It is required and has no default value.
- **group_mode**: generate the consumer groupId mode.
Which can take the value share: all consumers can only generate one groupId independent: Each consumer generates an independent groupId. If `group.id` is not set, this item is mandatory and has no default value.
-**poll_delay**: The polling timeout time passed in by calling tmq_consumer_poll.
The unit is milliseconds. A negative number means the default timeout is 1 second.
-**enable.manual.commit**: whether manual submission is allowed.
The value can be true: manual submission is allowed, after consuming messages, manually call tmq_commit_sync to complete the submission. false：Do not submit, default value: false.
-**rows_file**: a file that stores consumption data.
It can be a full path or a relative path with a file name.The actual saved file will be followed by the consumer serial number. For example, rows_file is result, and the actual file name is result_1 (consumer 1) result_2 (consumer 2).
-**expect_rows**: the number of rows and data types expected to be consumed by each consumer.
When the consumption reaches this number, the consumption will exit, and the consumption will continue without setting.
-**topic_list**: specifies the topic list and array type of consumption.
Example of topic list format: `{"name": "topic1", "sql": "select * from test.meters;"}`.
name: Specify the topic name.
sql: Specify the sql statement for creating topic, Ensure that the sql is correct, and the framework will automatically create topic.
Configuration parameters for subscribing to specified tables (can specify supertables, subtables, or regular tables) are set in `specified_table_query`.
For the following parameters, see the description of [Subscription](../../../advanced-features/data-subscription/):
- **client.id**
- **auto.offset.reset**
- **enable.auto.commit**
- **enable.auto.commit**
- **msg.with.table.name**
- **auto.commit.interval.ms**
- **group.id**: If this value is not specified, the groupId will be generated by the rule specified by `group_mode`. If this value is specified, the `group_mode` parameter is ignore.
- **threads/concurrent** : Number of threads executing the SQL, default is 1.
- **sqls** :
- **sql** : The SQL command to execute, required.
### Data Type Comparison Table
#### Data Type Writing Comparison Table in Configuration File
| # | **Engine** | **taosBenchmark**
| # | **TDengine** | **taosBenchmark**
| --- | :----------------: | :---------------:
| 1 | TIMESTAMP | timestamp
| 2 | INT | int
@ -525,3 +440,97 @@ Configuration parameters for subscribing to specified tables (can specify supert
| 18 | JSON | json
Note: Data types in the taosBenchmark configuration file must be in lowercase to be recognized.
## Example Of Configuration Files
**Below are a few examples of configuration files:**
#### Insertion Example
<details>
<summary>insert.json</summary>
```json
{{#include /TDengine/tools/taos-tools/example/insert.json}}
```
</details>
#### Query Example
<details>
<summary>query.json</summary>
```json
{{#include /TDengine/tools/taos-tools/example/query.json}}
```
</details>
#### Subscription Example
<details>
<summary>tmq.json</summary>
```json
{{#include /TDengine/tools/taos-tools/example/tmq.json}}
```
</details>
Other json examples see [here](https://github.com/taosdata/TDengine/tree/main/tools/taos-tools/example)
## Output Performance Indicators
#### Write Indicators
After writing is completed, a summary performance metric will be output in the last two lines in the following format:
``` bash
SUCC: Spent 8.527298 (real 8.117379) seconds to insert rows: 10000000 with 8 thread(s) into test 1172704.41 (real 1231924.74) records/second
SUCC: insert delay, min: 19.6780ms, avg: 64.9390ms, p90: 94.6900ms, p95: 105.1870ms, p99: 130.6660ms, max: 157.0830ms
```
First line write speed statistics:
- Spent: Total write time, in seconds, counting from the start of writing the first data to the end of the last data. This indicates that a total of 8.527298 seconds were spent.
- Real: Total write time (calling the engine), excluding the time spent preparing data for the testing framework. Purely counting the time spent on engine calls, The time spent is 8.117379 seconds. If 8.527298-8.117379=0.409919 seconds, it is the time spent preparing data for the testing framework.
- Rows: Write the total number of rows, which is 10 million pieces of data.
- Threads: The number of threads being written, which is 8 threads writing simultaneously.
- Records/second write speed = `total write time` / `total number of rows written`, real in parentheses is the same as before, indicating pure engine write speed.
Second line single write delay statistics:
- min: Write minimum delay.
- avg: Write normal delay.
- p90: Write delay p90 percentile delay number.
- p95: Write delay p95 percentile delay number.
- p99: Write delay p99 percentile delay number.
- max: maximum write delay.
Through this series of indicators, the distribution of write request latency can be observed.
#### Query indicators
The query performance test mainly outputs the QPS indicator of query request speed, and the output format is as follows:
``` bash
complete query with 3 threads and 10000 query delay avg: 0.002686s min: 0.001182s max: 0.012189s p90: 0.002977s p95: 0.003493s p99: 0.004645s SQL command: select ...
INFO: Spend 26.9530 second completed total queries: 30000, the QPS of all threads: 1113.049
```
- The first line represents the percentile distribution of query execution and query request delay for each of the three threads executing 10000 queries. The SQL command is the test query statement.
- The second line indicates that the total query time is 26.9653 seconds, and the query rate per second (QPS) is 1113.049 times/second.
- If the `continue_if_fail` option is set to `yes` in the query, the last line will output the number of failed requests and error rate, the format like "error + number of failed requests (error rate)".
- QPS = number of successful requests / time spent (in seconds)
- Error rate = number of failed requests / (number of successful requests + number of failed requests)
#### Subscription indicators
The subscription performance test mainly outputs consumer consumption speed indicators, with the following output format:
``` bash
INFO: consumer id 0 has poll total msgs: 376, period rate: 37.592 msgs/s, total rows: 3760000, period rate: 375924.815 rows/s
INFO: consumer id 1 has poll total msgs: 362, period rate: 36.131 msgs/s, total rows: 3620000, period rate: 361313.504 rows/s
INFO: consumer id 2 has poll total msgs: 364, period rate: 36.378 msgs/s, total rows: 3640000, period rate: 363781.731 rows/s
INFO: consumerId: 0, consume msgs: 1000, consume rows: 10000000
INFO: consumerId: 1, consume msgs: 1000, consume rows: 10000000
INFO: consumerId: 2, consume msgs: 1000, consume rows: 10000000
INFO: Consumed total msgs: 3000, total rows: 30000000
```
- Lines 1 to 3 real-time output of the current consumption speed of each consumer, msgs/s represents the number of consumption messages, each message contains multiple rows of data, and rows/s represents the consumption speed calculated by rows.
- Lines 4 to 6 show the overall statistics of each consumer after the test is completed, including the total number of messages consumed and the total number of lines.
- The overall statistics of all consumers in line 7, `msgs` represents how many messages were consumed in total, `rows` represents how many rows of data were consumed in total.

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

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

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

@ -1967,7 +1967,7 @@ ignore_null_values: {
- For queries on tables with composite primary keys, if there are data with the same timestamp, only the data with the smallest composite primary key participates in the calculation.
- INTERP query supports NEAR FILL mode, i.e., when FILL is needed, it uses the data closest to the current time point for interpolation. When the timestamps before and after are equally close to the current time slice, FILL the previous row's value. This mode is not supported in stream computing and window queries. For example: SELECT INTERP(col) FROM tb RANGE('2023-01-01 00:00:00', '2023-01-01 00:10:00') FILL(NEAR).(Supported from version 3.3.4.9).
- INTERP can only use the pseudocolumn `_irowts_origin` when using FILL PREV/NEXT/NEAR modes. `_irowts_origin` is supported from version 3.3.4.9.
- INTERP `RANGE` clause supports the expansion of the time range (supported from version 3.3.4.9), such as `RANGE('2023-01-01 00:00:00', 10s)` means to find data 10s before and after the time point '2023-01-01 00:00:00' for interpolation, FILL PREV/NEXT/NEAR respectively means to look for data forward/backward/around the time point, if there is no data around the time point, then use the value specified by FILL for interpolation, therefore the FILL clause must specify a value at this time. For example: SELECT INTERP(col) FROM tb RANGE('2023-01-01 00:00:00', 10s) FILL(PREV, 1). Currently, only the combination of time point and time range is supported, not the combination of time interval and time range, i.e., RANGE('2023-01-01 00:00:00', '2023-02-01 00:00:00', 1h) is not supported. The specified time range rules are similar to EVERY, the unit cannot be year or month, the value cannot be 0, and cannot have quotes. When using this extension, other FILL modes except FILL PREV/NEXT/NEAR are not supported, and the EVERY clause cannot be specified.
- INTERP `RANGE` clause supports the expansion of the time range (supported from version 3.3.4.9), For example, `RANGE('2023-01-01 00:00:00', 10s)` means that only data within 10s around the time point '2023-01-01 00:00:00' can be used for interpolation. `FILL PREV/NEXT/NEAR` respectively means to look for data forward/backward/around the time point. If there is no data around the time point, the default value specified by `FILL` is used for interpolation. Therefore the `FILL` clause must specify the default value at the same time. For example: SELECT INTERP(col) FROM tb RANGE('2023-01-01 00:00:00', 10s) FILL(PREV, 1). Starting from the 3.3.6.0 version, the combination of time period and time range is supported. When interpolating for each point within the time period, the time range requirement must be met. Prior versions only supported single time point and its time range. The available values for time range are similar to `EVERY`, the unit cannot be year or month, the value must be greater than 0, and cannot be in quotes. When using this extension, `FILL` modes other than `PREV/NEXT/NEAR` are not supported.
### LAST
@ -2125,6 +2125,28 @@ UNIQUE(expr)
**Applicable to**: Tables and supertables.
### COLS​
```sql​
COLS​(func(expr), output_expr1, [, output_expr2] ... )​
```
**Function Description**: On the data row where the execution result of function func(expr) is located, execute the expression output_expr1, [, output_expr2], return its result, and the result of func (expr) is not output.​
**Return Data Type**: Returns multiple columns of data, and the data type of each column is the type of the result returned by the corresponding expression.​
**Applicable Data Types**: All type fields.​
**Applicable to**: Tables and Super Tables.​
**Usage Instructions**:
- Func function type: must be a single-line selection function (output result is a single-line selection function, for example, last is a single-line selection function, but top is a multi-line selection function).​
- Mainly used to obtain the associated columns of multiple selection function results in a single SQL query. For example: select cols(max(c0), ts), cols(max(c1), ts) from ... can be used to get the different ts values of the maximum values of columns c0 and c1.
- The result of the parameter func is not returned. If you need to output the result of func, you can add additional output columns, such as: select first(ts), cols(first(ts), c1) from ..
- When there is only one column in the output, you can set an alias for the function. For example, you can do it like this: "select cols(first (ts), c1) as c11 from ...".
- Output one or more columns, and you can set an alias for each output column of the function. For example, you can do it like this: "select (first (ts), c1 as c11, c2 as c22) from ...".
## Time-Series Specific Functions
Time-Series specific functions are tailor-made by TDengine to meet the query scenarios of time-series data. In general databases, implementing similar functionalities usually requires complex query syntax and is inefficient. TDengine has built these functionalities into functions, greatly reducing the user's cost of use.

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

@ -53,9 +53,9 @@ The syntax for the window clause is as follows:
```sql
window_clause: {
SESSION(ts_col, tol_val)
| STATE_WINDOW(col)
| STATE_WINDOW(col) [TRUE_FOR(true_for_duration)]
| INTERVAL(interval_val [, interval_offset]) [SLIDING (sliding_val)] [FILL(fill_mod_and_val)]
| EVENT_WINDOW START WITH start_trigger_condition END WITH end_trigger_condition
| EVENT_WINDOW START WITH start_trigger_condition END WITH end_trigger_condition [TRUE_FOR(true_for_duration)]
| COUNT_WINDOW(count_val[, sliding_val])
}
```
@ -177,6 +177,12 @@ TDengine also supports using CASE expressions in state quantities, which can exp
SELECT tbname, _wstart, CASE WHEN voltage >= 205 and voltage <= 235 THEN 1 ELSE 0 END status FROM meters PARTITION BY tbname STATE_WINDOW(CASE WHEN voltage >= 205 and voltage <= 235 THEN 1 ELSE 0 END);
```
The state window supports using the TRUE_FOR parameter to set its minimum duration. If the window's duration is less than the specified value, it will be discarded automatically and no result will be returned. For example, setting the minimum duration to 3 seconds:
```
SELECT COUNT(*), FIRST(ts), status FROM temp_tb_1 STATE_WINDOW(status) TRUE_FOR (3s);
```
### Session Window
The session window is determined based on the timestamp primary key values of the records. As shown in the diagram below, if the continuous interval of the timestamps is set to be less than or equal to 12 seconds, the following 6 records form 2 session windows, which are: [2019-04-28 14:22:10, 2019-04-28 14:22:30] and [2019-04-28 14:23:10, 2019-04-28 14:23:30]. This is because the interval between 2019-04-28 14:22:30 and 2019-04-28 14:23:10 is 40 seconds, exceeding the continuous interval (12 seconds).
@ -212,6 +218,12 @@ select _wstart, _wend, count(*) from t event_window start with c1 > 0 end with c
<Image img={imgStep04} alt=""/>
</figure>
The event window supports using the TRUE_FOR parameter to set its minimum duration. If the window's duration is less than the specified value, it will be discarded automatically and no result will be returned. For example, setting the minimum duration to 3 seconds:
```
select _wstart, _wend, count(*) from t event_window start with c1 > 0 end with c2 < 10 true_for (3s);
```
### Count Window
Count windows divide data into windows based on a fixed number of data rows. By default, data is sorted by timestamp, then divided into multiple windows based on the value of count_val, and aggregate calculations are performed. count_val represents the maximum number of data rows in each count window; if the total number of data rows is not divisible by count_val, the last window will have fewer rows than count_val. sliding_val is a constant that represents the number of rows the window slides, similar to the SLIDING in interval.

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

@ -9,7 +9,7 @@ import imgStream from './assets/stream-processing-01.png';
## Creating Stream Computing
```sql
CREATE STREAM [IF NOT EXISTS] stream_name [stream_options] INTO stb_name[(field1_name, field2_name [PRIMARY KEY], ...)] [TAGS (create_definition [, create_definition] ...)] SUBTABLE(expression) AS subquery
CREATE STREAM [IF NOT EXISTS] stream_name [stream_options] INTO stb_name[(field1_name, field2_name [PRIMARY KEY], ...)] [TAGS (create_definition [, create_definition] ...)] SUBTABLE(expression) AS subquery [notification_definition]
stream_options: {
TRIGGER [AT_ONCE | WINDOW_CLOSE | MAX_DELAY time | FORCE_WINDOW_CLOSE]
WATERMARK time
@ -85,6 +85,8 @@ CREATE STREAM streams1 IGNORE EXPIRED 1 WATERMARK 100s INTO streamt1 AS
SELECT _wstart, count(*), avg(voltage) from meters PARTITION BY tbname COUNT_WINDOW(10);
```
notification_definition clause specifies the addresses to which notifications should be sent when designated events occur during window computations, such as window opening or closing. For more details, see [Stream Computing Event Notifications](#stream-computing-event-notifications).
## Stream Computation Partitioning
You can use `PARTITION BY TBNAME`, tags, regular columns, or expressions to partition a stream for multi-partition computation. Each partition's timeline and window are independent, aggregating separately, and writing into different subtables of the target table.
@ -305,3 +307,223 @@ CREATE SNODE ON DNODE [id]
The id is the serial number of the dnode in the cluster. Please be mindful of the selected dnode, as the intermediate state of stream computing will automatically be backed up on it.
Starting from version 3.3.4.0, in a multi-replica environment, creating a stream will perform an **existence check** of snode, requiring the snode to be created first. If the snode does not exist, the stream cannot be created.
## Stream Computing Event Notifications
### User Guide
Stream computing supports sending event notifications to external systems when windows open or close. Users can specify the events to be notified and the target addresses for receiving notification messages using the notification_definition clause.
```sql
notification_definition:
NOTIFY (url [, url] ...) ON (event_type [, event_type] ...) [notification_options]
event_type:
'WINDOW_OPEN'
| 'WINDOW_CLOSE'
notification_options: {
NOTIFY_HISTORY [0|1]
ON_FAILURE [DROP|PAUSE]
}
```
The rules for the syntax above are as follows:
1. `url`: Specifies the target address for the notification. It must include the protocol, IP or domain name, port, and may include a path and parameters. Currently, only the websocket protocol is supported. For example: 'ws://localhost:8080', 'ws://localhost:8080/notify', 'wss://localhost:8080/notify?key=foo'.
2. `event_type`: Defines the events that trigger notifications. Supported event types include:
1. 'WINDOW_OPEN': Window open event; triggered when any type of window opens.
2. 'WINDOW_CLOSE': Window close event; triggered when any type of window closes.
3. `NOTIFY_HISTORY`: Controls whether to trigger notifications during the computation of historical data. The default value is 0, which means no notifications are sent.
4. `ON_FAILURE`: Determines whether to allow dropping some events if sending notifications fails (e.g., in poor network conditions). The default value is `PAUSE`:
1. PAUSE means that the stream computing task is paused if sending a notification fails. taosd will retry until the notification is successfully delivered and the task resumes.
2. DROP means that if sending a notification fails, the event information is discarded, and the stream computing task continues running unaffected.
For example, the following creates a stream that computes the per-minute average current from electric meters and sends notifications to two target addresses when the window opens and closes. It does not send notifications for historical data and does not allow dropping notifications on failure:
```sql
CREATE STREAM avg_current_stream FILL_HISTORY 1
AS SELECT _wstart, _wend, AVG(current) FROM meters
INTERVAL (1m)
NOTIFY ('ws://localhost:8080/notify', 'wss://192.168.1.1:8080/notify?key=foo')
ON ('WINDOW_OPEN', 'WINDOW_CLOSE');
NOTIFY_HISTORY 0
ON_FAILURE PAUSE;
```
When the specified events are triggered, taosd will send a POST request to the given URL(s) with a JSON message body. A single request may contain events from several streams, and the event types may differ.
The details of the event information depend on the type of window:
1. Time Window: At the opening, the start time is sent; at the closing, the start time, end time, and computation result are sent.
2. State Window: At the opening, the start time, previous window's state, and current window's state are sent; at closing, the start time, end time, computation result, current window state, and next window state are sent.
3. Session Window: At the opening, the start time is sent; at the closing, the start time, end time, and computation result are sent.
4. Event Window: At the opening, the start time along with the data values and corresponding condition index that triggered the window opening are sent; at the closing, the start time, end time, computation result, and the triggering data value and condition index for window closure are sent.
5. Count Window: At the opening, the start time is sent; at the closing, the start time, end time, and computation result are sent.
An example structure for the notification message is shown below:
```json
{
"messageId": "unique-message-id-12345",
"timestamp": 1733284887203,
"streams": [
{
"streamName": "avg_current_stream",
"events": [
{
"tableName": "t_a667a16127d3b5a18988e32f3e76cd30",
"eventType": "WINDOW_OPEN",
"eventTime": 1733284887097,
"windowId": "window-id-67890",
"windowType": "Time",
"windowStart": 1733284800000
},
{
"tableName": "t_a667a16127d3b5a18988e32f3e76cd30",
"eventType": "WINDOW_CLOSE",
"eventTime": 1733284887197,
"windowId": "window-id-67890",
"windowType": "Time",
"windowStart": 1733284800000,
"windowEnd": 1733284860000,
"result": {
"_wstart": 1733284800000,
"avg(current)": 1.3
}
}
]
},
{
"streamName": "max_voltage_stream",
"events": [
{
"tableName": "t_96f62b752f36e9b16dc969fe45363748",
"eventType": "WINDOW_OPEN",
"eventTime": 1733284887231,
"windowId": "window-id-13579",
"windowType": "Event",
"windowStart": 1733284800000,
"triggerCondition": {
"conditionIndex": 0,
"fieldValue": {
"c1": 10,
"c2": 15
}
},
},
{
"tableName": "t_96f62b752f36e9b16dc969fe45363748",
"eventType": "WINDOW_CLOSE",
"eventTime": 1733284887231,
"windowId": "window-id-13579",
"windowType": "Event",
"windowStart": 1733284800000,
"windowEnd": 1733284810000,
"triggerCondition": {
"conditionIndex": 1,
"fieldValue": {
"c1": 20
"c2": 3
}
},
"result": {
"_wstart": 1733284800000,
"max(voltage)": 220
}
}
]
}
]
}
```
The following sections explain the fields in the notification message.
### Root-Level Field Descriptions
1. "messageId": A string that uniquely identifies the notification message. It ensures that the entire message can be tracked and de-duplicated.
2. "timestamp": A long integer timestamp representing the time when the notification message was generated, accurate to the millisecond (i.e., the number of milliseconds since '00:00, Jan 1 1970 UTC').
3. "streams": An array containing the event information for multiple stream tasks. (See the following sections for details.)
### "stream" Object Field Descriptions
1. "streamName": A string representing the name of the stream task, used to identify which stream the events belong to.
2. "events": An array containing the list of event objects for the stream task. Each event object includes detailed information. (See the next sections for details.)
### "event" Object Field Descriptions
#### Common Fields
These fields are common to all event objects.
1. "tableName": A string indicating the name of the target subtable.
2. "eventType": A string representing the event type ("WINDOW_OPEN", "WINDOW_CLOSE", or "WINDOW_INVALIDATION").
3. "eventTime": A long integer timestamp that indicates when the event was generated, accurate to the millisecond (i.e., the number of milliseconds since '00:00, Jan 1 1970 UTC').
4. "windowId": A string representing the unique identifier for the window. This ID ensures that the open and close events for the same window can be correlated. In the case that taosd restarts due to a fault, some events may be sent repeatedly, but the windowId remains constant for the same window.
5. "windowType": A string that indicates the window type ("Time", "State", "Session", "Event", or "Count").
#### Fields for Time Windows
These fields are present only when "windowType" is "Time".
1. When "eventType" is "WINDOW_OPEN", the following field is included:
1. "windowStart": A long integer timestamp representing the start time of the window, matching the time precision of the result table.
2. When "eventType" is "WINDOW_CLOSE", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "windowEnd": A long integer timestamp representing the end time of the window.
1. "result": An object containing key-value pairs of the computed result columns and their corresponding values.
#### Fields for State Windows
These fields are present only when "windowType" is "State".
1. When "eventType" is "WINDOW_OPEN", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "prevState": A value of the same type as the state column, representing the state of the previous window. If there is no previous window (i.e., this is the first window), it will be NULL.
1. "curState": A value of the same type as the state column, representing the current window's state.
2. When "eventType" is "WINDOW_CLOSE", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "windowEnd": A long integer timestamp representing the end time of the window.
1. "curState": The current window's state.
1. "nextState": The state for the next window.
1. "result": An object containing key-value pairs of the computed result columns and their corresponding values.
#### Fields for Session Windows
These fields are present only when "windowType" is "Session".
1. When "eventType" is "WINDOW_OPEN", the following field is included:
1. "windowStart": A long integer timestamp representing the start time of the window.
2. When "eventType" is "WINDOW_CLOSE", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "windowEnd": A long integer timestamp representing the end time of the window.
1. "result": An object containing key-value pairs of the computed result columns and their corresponding values.
#### Fields for Event Windows
These fields are present only when "windowType" is "Event".
1. When "eventType" is "WINDOW_OPEN", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "triggerCondition": An object that provides information about the condition that triggered the window to open. It includes:
1. "conditionIndex": An integer representing the index of the condition that triggered the window, starting from 0.
1. "fieldValue": An object containing key-value pairs of the column names related to the condition and their respective values.
2. When "eventType" is "WINDOW_CLOSE", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "windowEnd": A long integer timestamp representing the end time of the window.
1. "triggerCondition": An object that provides information about the condition that triggered the window to close. It includes:
1. "conditionIndex": An integer representing the index of the condition that triggered the closure, starting from 0.
1. "fieldValue": An object containing key-value pairs of the related column names and their respective values.
1. "result": An object containing key-value pairs of the computed result columns and their corresponding values.
#### Fields for Count Windows
These fields are present only when "windowType" is "Count".
1. When "eventType" is "WINDOW_OPEN", the following field is included:
1. "windowStart": A long integer timestamp representing the start time of the window.
2. When "eventType" is "WINDOW_CLOSE", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "windowEnd": A long integer timestamp representing the end time of the window.
1. "result": An object containing key-value pairs of the computed result columns and their corresponding values.
#### Fields for Window Invalidation
Due to scenarios such as data disorder, updates, or deletions during stream computing, windows that have already been generated might be removed or their results need to be recalculated. In such cases, a notification with the eventType "WINDOW_INVALIDATION" is sent to inform which windows have been invalidated.
For events with "eventType" as "WINDOW_INVALIDATION", the following fields are included:
1. "windowStart": A long integer timestamp representing the start time of the window.
1. "windowEnd": A long integer timestamp representing the end time of the window.

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 | |

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. | - |

26
docs/en/14-reference/05-connector/35-node.md
View File

@ -25,6 +25,8 @@ Support all platforms that can run Node.js.
| Node.js Connector Version | Major Changes | TDengine Version |
| ------------------------- | ------------------------------------------------------------------------ | --------------------------- |
| 3.1.4 | Modified the readme.| - |
| 3.1.3 | Upgraded the es5-ext version to address vulnerabilities in the lower version. | - |
| 3.1.2 | Optimized data protocol and parsing, significantly improved performance. | - |
| 3.1.1 | Optimized data transmission performance. | 3.3.2.0 and higher versions |
| 3.1.0 | New release, supports WebSocket connection. | 3.2.0.0 and higher versions |
@ -132,16 +134,20 @@ Node.js connector (`@tdengine/websocket`), which connects to a TDengine instance
In addition to obtaining a connection through a specified URL, you can also use WSConfig to specify parameters when establishing a connection.
```js
try {
let url = 'ws://127.0.0.1:6041'
let conf = WsSql.NewConfig(url)
conf.setUser('root')
conf.setPwd('taosdata')
conf.setDb('db')
conf.setTimeOut(500)
let wsSql = await WsSql.open(conf);
} catch (e) {
console.error(e);
const taos = require("@tdengine/websocket");
async function createConnect() {
try {
let url = 'ws://127.0.0.1:6041'
let conf = new taos.WSConfig(url)
conf.setUser('root')
conf.setPwd('taosdata')
conf.setDb('db')
conf.setTimeOut(500)
let wsSql = await taos.sqlConnect(conf)
} catch (e) {
console.error(e);
}
}
```

39
docs/en/14-reference/05-connector/40-csharp.md
View File

@ -25,6 +25,7 @@ import RequestId from "../../assets/resources/_request_id.mdx";
| Connector Version | Major Changes | TDengine Version |
|-------------------|------------------------------------------------------------|--------------------|
| 3.1.6 | Optimize WebSocket connection message handling. | - |
| 3.1.5 | Fix WebSocket encoding error for Chinese character length. | - |
| 3.1.4 | Improved WebSocket query and insert performance. | 3.3.2.0 and higher |
| 3.1.3 | Supported WebSocket auto-reconnect. | - |
@ -39,25 +40,25 @@ For error reporting in other TDengine modules, please refer to [Error Codes](../
## Data Type Mapping
| TDengine DataType | C# Type |
|-------------------|------------------|
| TIMESTAMP | DateTime |
| TINYINT | sbyte |
| SMALLINT | short |
| INT | int |
| BIGINT | long |
| TINYINT UNSIGNED | byte |
| SMALLINT UNSIGNED | ushort |
| INT UNSIGNED | uint |
| BIGINT UNSIGNED | ulong |
| FLOAT | float |
| DOUBLE | double |
| BOOL | bool |
| BINARY | byte[] |
| NCHAR | string (utf-8 encoded) |
| JSON | byte[] |
| VARBINARY | byte[] |
| GEOMETRY | byte[] |
| TDengine DataType | C# Type |
|-------------------|----------|
| TIMESTAMP | DateTime |
| TINYINT | sbyte |
| SMALLINT | short |
| INT | int |
| BIGINT | long |
| TINYINT UNSIGNED | byte |
| SMALLINT UNSIGNED | ushort |
| INT UNSIGNED | uint |
| BIGINT UNSIGNED | ulong |
| FLOAT | float |
| DOUBLE | double |
| BOOL | bool |
| BINARY | byte[] |
| NCHAR | string |
| JSON | byte[] |
| VARBINARY | byte[] |
| GEOMETRY | byte[] |
**Note**: JSON type is only supported in tags.
The GEOMETRY type is binary data in little endian byte order, conforming to the WKB standard. For more details, please refer to [Data Types](../../sql-manual/data-types/)

151
docs/en/14-reference/05-connector/50-odbc.md
View File

@ -138,7 +138,7 @@ The table below explains how the ODBC connector maps server data types to defaul
| BIGINT | SQL_BIGINT | SQL_C_SBIGINT |
| BIGINT UNSIGNED | SQL_BIGINT | SQL_C_UBIGINT |
| FLOAT | SQL_REAL | SQL_C_FLOAT |
| DOUBLE | SQL_REAL | SQL_C_DOUBLE |
| DOUBLE | SQL_DOUBLE | SQL_C_DOUBLE |
| BINARY | SQL_BINARY | SQL_C_BINARY |
| SMALLINT | SQL_SMALLINT | SQL_C_SSHORT |
| SMALLINT UNSIGNED | SQL_SMALLINT | SQL_C_USHORT |
@ -146,33 +146,145 @@ The table below explains how the ODBC connector maps server data types to defaul
| TINYINT UNSIGNED | SQL_TINYINT | SQL_C_UTINYINT |
| BOOL | SQL_BIT | SQL_C_BIT |
| NCHAR | SQL_VARCHAR | SQL_C_CHAR |
| JSON | SQL_VARCHAR | SQL_C_CHAR |
| VARCHAR | SQL_VARCHAR | SQL_C_CHAR |
| JSON | SQL_WVARCHAR | SQL_C_WCHAR |
| GEOMETRY | SQL_VARBINARY | SQL_C_BINARY |
| VARBINARY | SQL_VARBINARY | SQL_C_BINARY |
## API Reference
This section summarizes the ODBC API by functionality. For a complete ODBC API reference, please visit the [ODBC Programmer's Reference page](http://msdn.microsoft.com/en-us/library/ms714177.aspx).
### API List
### Data Source and Driver Management
- **Currently exported ODBC functions are**:
| ODBC/Setup API | Linux | macOS | Windows | Note |
| :----- | :---- | :---- | :---- | :---- |
| ConfigDSN | ❌ | ❌ | ✅ | |
| ConfigDriver | ❌ | ❌ | ✅ | |
| ConfigTranslator | ❌ | ❌ | ❌ | |
| SQLAllocHandle | ✅ | ✅ | ✅ | |
| SQLBindCol | ✅ | ✅ | ✅ | Column-Wise Binding only |
| SQLBindParameter | ✅ | ✅ | ✅ | Column-Wise Binding only |
| SQLBrowseConnect | ❌ | ❌ | ❌ | |
| SQLBulkOperations | ❌ | ❌ | ❌ | TDengine has no counterpart |
| SQLCloseCursor | ✅ | ✅ | ✅ | |
| SQLColAttribute | ✅ | ✅ | ✅ | |
| SQLColumnPrivileges | ❌ | ❌ | ❌ | TDengine has no strict counterpart |
| SQLColumns | ✅ | ✅ | ✅ | |
| SQLCompleteAsync | ❌ | ❌ | ❌ | |
| SQLConnect | ✅ | ✅ | ✅ | |
| SQLCopyDesc | ❌ | ❌ | ❌ | |
| SQLDescribeCol | ✅ | ✅ | ✅ | |
| SQLDescribeParam | ✅ | ✅ | ✅ | |
| SQLDisconnect | ✅ | ✅ | ✅ | |
| SQLDriverConnect | ✅ | ✅ | ✅ | |
| SQLEndTran | ✅ | ✅ | ✅ | TDengine is non-transactional, thus this is at most simulating |
| SQLExecDirect | ✅ | ✅ | ✅ | |
| SQLExecute | ✅ | ✅ | ✅ | |
| SQLExtendedFetch | ❌ | ❌ | ❌ | |
| SQLFetch | ✅ | ✅ | ✅ | |
| SQLFetchScroll | ✅ | ✅ | ✅ | TDengine has no counterpart, just implement SQL_FETCH_NEXT |
| SQLForeignKeys | ❌ | ❌ | ❌ | TDengine has no counterpart |
| SQLFreeHandle | ✅ | ✅ | ✅ | |
| SQLFreeStmt | ✅ | ✅ | ✅ | |
| SQLGetConnectAttr | ✅ | ✅ | ✅ | Supports partial attributes; unsupported attributes are listed below. |
| SQLGetCursorName | ❌ | ❌ | ❌ | TDengine has no counterpart |
| SQLGetData | ✅ | ✅ | ✅ | |
| SQLGetDescField | ❌ | ❌ | ❌ | |
| SQLGetDescRec | ❌ | ❌ | ❌ | |
| SQLGetDiagField | ✅ | ✅ | ✅ | |
| SQLGetDiagRec | ✅ | ✅ | ✅ | |
| SQLGetEnvAttr | ✅ | ✅ | ✅ | |
| SQLGetInfo | ✅ | ✅ | ✅ | |
| SQLGetStmtAttr | ✅ | ✅ | ✅ | Supports partial attributes; unsupported attributes are listed below. |
| SQLGetTypeInfo | ✅ | ✅ | ✅ | |
| SQLMoreResults | ✅ | ✅ | ✅ | |
| SQLNativeSql | ❌ | ❌ | ❌ | TDengine has no counterpart |
| SQLNumParams | ✅ | ✅ | ✅ | |
| SQLNumResultCols | ✅ | ✅ | ✅ | |
| SQLParamData | ❌ | ❌ | ❌ | TDengine has no counterpart |
| SQLPrepare | ✅ | ✅ | ✅ | |
| SQLPrimaryKeys | ✅ | ✅ | ✅ | |
| SQLProcedureColumns | ❌ | ❌ | ❌ | TDengine has no counterpart |
| SQLProcedures | ❌ | ❌ | ❌ | TDengine has no counterpart |
| SQLPutData | ❌ | ❌ | ❌ | TDengine has no counterpart |
| SQLRowCount | ✅ | ✅ | ✅ | |
| SQLSetConnectAttr | ✅ | ✅ | ✅ | Supports partial attributes; unsupported attributes are listed below. |
| SQLSetCursorName | ❌ | ❌ | ❌ | TDengine has no counterpart |
| SQLSetDescField | ❌ | ❌ | ❌ | |
| SQLSetDescRec | ❌ | ❌ | ❌ | |
| SQLSetEnvAttr | ✅ | ✅ | ✅ | |
| SQLSetPos | ❌ | ❌ | ❌ | TDengine has no counterpart |
| SQLSetStmtAttr | ✅ | ✅ | ✅ | Supports partial attributes; unsupported attributes are listed below. |
| SQLSpecialColumns | ❌ | ❌ | ❌ | TDengine has no counterpart |
| SQLStatistics | ❌ | ❌ | ❌ | TDengine has no counterpart |
| SQLTablePrivileges | ❌ | ❌ | ❌ | TDengine has no strict counterpart |
| SQLTables | ✅ | ✅ | ✅ | |
- **Non-supported-statement-attributes (SQLSetStmtAttr)**
| Attribute | Note |
| :----- | :---- |
| SQL_ATTR_CONCURRENCY | TDengine has no updatable-CURSOR machanism |
| SQL_ATTR_FETCH_BOOKMARK_PTR | TDengine has no BOOKMARK machanism |
| SQL_ATTR_IMP_PARAM_DESC | |
| SQL_ATTR_IMP_ROW_DESC | |
| SQL_ATTR_KEYSET_SIZE | |
| SQL_ATTR_PARAM_BIND_OFFSET_PTR | |
| SQL_ATTR_PARAM_OPERATION_PTR | |
| SQL_ATTR_ROW_NUMBER | Readonly attribute |
| SQL_ATTR_ROW_OPERATION_PTR | |
| SQL_ATTR_SIMULATE_CURSOR | |
- **Non-supported-connection-attributes (SQLSetConnectAttr)**
| Attribute | Note |
| :----- | :---- |
| SQL_ATTR_AUTO_IPD | Readonly attribute |
| SQL_ATTR_CONNECTION_DEAD | Readonly attribute |
| SQL_ATTR_ENLIST_IN_DTC | |
| SQL_ATTR_PACKET_SIZE | |
| SQL_ATTR_TRACE | |
| SQL_ATTR_TRACEFILE | |
| SQL_ATTR_TRANSLATE_LIB | |
| SQL_ATTR_TRANSLATE_OPTION | |
- **Enable any programming language with ODBC-bindings/ODBC-plugings to communicate with TDengine:**
| programming language | ODBC-API or bindings/plugins |
| :----- | :---- |
| C/C++ | ODBC-API |
| CSharp | System.Data.Odbc |
| Erlang | odbc module |
| Go | [odbc](https://github.com/alexbrainman/odbc), database/sql |
| Haskell | HDBC, HDBC-odbc |
| Common Lisp | plain-odbc |
| Nodejs | odbc |
| Python3 | pyodbc |
| Rust | odbc |
### API Functional Categories
This section summarizes the ODBC API by functionality. For a complete ODBC API reference, please visit the [Microsoft Open Database Connectivity (ODBC)](https://learn.microsoft.com/en-us/sql/odbc/microsoft-open-database-connectivity-odbc).
#### Data Source and Driver Management
- API: ConfigDSN
- **Supported**: Yes
- **Supported**: Yes (Windows only)
- **Standard**: ODBC
- **Function**: Configures data sources
- API: ConfigDriver
- **Supported**: Yes
- **Supported**: Yes (Windows only)
- **Standard**: ODBC
- **Function**: Used to perform installation and configuration tasks related to a specific driver
- API: ConfigTranslator
- **Supported**: Yes
- **Supported**: No
- **Standard**: ODBC
- **Function**: Used to parse the DSN configuration, translating or converting between DSN configuration and actual database driver configuration
### Connecting to Data Sources
#### Connecting to Data Sources
- API: SQLAllocHandle
- **Supported**: Yes
@ -204,7 +316,7 @@ This section summarizes the ODBC API by functionality. For a complete ODBC API r
- **Standard**: Deprecated
- **Function**: In ODBC 3.x, the ODBC 2.x function SQLAllocConnect has been replaced by SQLAllocHandle
### Retrieving Information about Drivers and Data Sources
#### Retrieving Information about Drivers and Data Sources
- API: SQLDataSources
- **Supported**: No
@ -231,7 +343,7 @@ This section summarizes the ODBC API by functionality. For a complete ODBC API r
- **Standard**: ISO 92
- **Function**: Returns information about supported data types
### Setting and Retrieving Driver Properties
#### Setting and Retrieving Driver Properties
- API: SQLSetConnectAttr
- **Supported**: Yes
@ -283,7 +395,7 @@ This section summarizes the ODBC API by functionality. For a complete ODBC API r
- **Standard**: Deprecated
- **Purpose**: In ODBC 3.x, the ODBC 2.0 function SQLSetStmtOption has been replaced by SQLGetStmtAttr
### Preparing SQL Requests
#### Preparing SQL Requests
- API: SQLAllocStmt
- **Supported**: Not supported
@ -320,7 +432,7 @@ This section summarizes the ODBC API by functionality. For a complete ODBC API r
- **Standard**: ODBC
- **Purpose**: Sets options that control cursor behavior
### Submitting Requests
#### Submitting Requests
- API: SQLExecute
- **Supported**: Supported
@ -357,7 +469,7 @@ This section summarizes the ODBC API by functionality. For a complete ODBC API r
- **Standard**: ISO 92
- **Function**: When using stream input mode, it can be used to send data blocks to output parameters
### Retrieving Results and Information About Results
#### Retrieving Results and Information About Results
- API: SQLRowCount
- **Support**: Supported
@ -419,7 +531,7 @@ This section summarizes the ODBC API by functionality. For a complete ODBC API r
- **Standard**: ODBC
- **Function**: Performs bulk insert and bulk bookmark operations, including updates, deletions, and fetching by bookmark
### Retrieving Error or Diagnostic Information
#### Retrieving Error or Diagnostic Information
- API: SQLError
- **Support**: Not supported
@ -436,7 +548,7 @@ This section summarizes the ODBC API by functionality. For a complete ODBC API r
- **Standard**: ISO 92
- **Function**: Returns additional diagnostic information (multiple diagnostic results)
### Retrieving Information About System Table Entries Related to the Data Source
#### Retrieving Information About System Table Entries Related to the Data Source
- API: SQLColumnPrivileges
- **Support**: Not supported
@ -488,7 +600,7 @@ This section summarizes the ODBC API by functionality. For a complete ODBC API r
- **Standard**: ODBC
- **Function**: Returns column information for stored procedures, including details of input and output parameters
### Transaction Execution
#### Transaction Execution
- API: SQLTransact
- **Support**: Not supported
@ -498,9 +610,9 @@ This section summarizes the ODBC API by functionality. For a complete ODBC API r
- API: SQLEndTran
- **Support**: Supported
- **Standard**: ISO 92
- **Function**: Used to commit or rollback transactions, TDengine does not support transactions, therefore rollback operation is not supported
- **Function**: Used to commit or rollback transactions. TDengine is non-transactional, so this function can at most simulate commit or rollback operations. If there are any outstanding connections or statements, neither commit nor rollback will succeed
### Connection Termination
#### Connection Termination
- API: SQLDisconnect
- **Support**: Supported
@ -532,6 +644,3 @@ This section summarizes the ODBC API by functionality. For a complete ODBC API r
- **Standard**: ODBC
- **Function**: Closes the cursor associated with the current statement handle and releases all resources used by the cursor
## Integration with Third Parties
As an example of using the TDengine ODBC driver, you can use Power BI to analyze time-series data with TDengine. For more details, please refer to [Power BI](../../../third-party-tools/analytics/power-bi/)

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

@ -458,6 +458,12 @@ This document details the server error codes that may be encountered when using
| 0x80002665 | The _TAGS pseudocolumn can only be used for subtable and supertable queries | Illegal tag column query | Check and correct the SQL statement |
| 0x80002666 | Subquery does not output primary timestamp column | Check and correct the SQL statement | |
| 0x80002667 | Invalid usage of expr: %s | Illegal expression | Check and correct the SQL statement |
| 0x80002687 | True_for duration cannot be negative | Use negative value as true_for duration | Check and correct the SQL statement |
| 0x80002688 | Cannot use 'year' or 'month' as true_for duration | Use year or month as true_for_duration | Check and correct the SQL statement |
| 0x80002689 | Invalid using cols function | Illegal using cols function | Check and correct the SQL statement |
| 0x8000268A | Cols function's first param must be a select function that output a single row | The first parameter of the cols function should be a selection function | Check and correct the SQL statement |
| 0x8000268B | Invalid using 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 |
| 0x800026FF | Parser internal error | Internal error in parser | Preserve the scene and logs, report issue on GitHub |
| 0x80002700 | Planner internal error | Internal error in planner | Preserve the scene and logs, report issue on GitHub |
| 0x80002701 | Expect ts equal | JOIN condition validation failed | Preserve the scene and logs, report issue on GitHub |

10
docs/en/27-train-faq/index.md
View File

@ -73,7 +73,7 @@ If the client encounters a connection failure, please follow the steps below to
### 5. What to do if you encounter the error "Unable to resolve FQDN"?
This error occurs because the client or data node cannot resolve the FQDN (Fully Qualified Domain Name). For the TAOS Shell or client applications, please check the following:
This error occurs because the client or data node cannot resolve the FQDN (Fully Qualified Domain Name). For the TDengine CLI or client applications, please check the following:
1. Check if the FQDN of the server you are connecting to is correct.
2. If there is a DNS server in the network configuration, check if it is working properly
@ -244,15 +244,15 @@ launchctl limit maxfiles
This prompt indicates that the number of vnodes required for creating the db is not enough, exceeding the upper limit of vnodes in the dnode. By default, a dnode contains twice the number of CPU cores worth of vnodes, which can also be controlled by the supportVnodes parameter in the configuration file.
Normally, increase the supportVnodes parameter in taos.cfg.
### 21 Why can data from a specified time period be queried using taos-CLI on the server, but not on the client machine?
### 21 Why can data from a specified time period be queried using TDengine CLI on the server, but not on the client machine?
This issue is due to the client and server having different time zone settings. Adjusting the client's time zone to match the server's will resolve the issue.
### 22 The table name is confirmed to exist, but returns "table name does not exist" when writing or querying, why?
In TDengine, all names, including database names and table names, are case-sensitive. If these names are not enclosed in backticks (\`) in the program or taos-CLI, even if you input them in uppercase, the engine will convert them to lowercase for use. If the names are enclosed in backticks, the engine will not convert them to lowercase and will use them as is.
In TDengine, all names, including database names and table names, are case-sensitive. If these names are not enclosed in backticks (\`) in the program or TDengine CLI, even if you input them in uppercase, the engine will convert them to lowercase for use. If the names are enclosed in backticks, the engine will not convert them to lowercase and will use them as is.
### 23 How to fully display field content in taos-CLI queries?
### 23 How to fully display field content in TDengine CLI queries?
You can use the \G parameter for vertical display, such as `show databases\G\;` (for ease of input, press TAB after "\" to automatically complete the content).
@ -315,4 +315,4 @@ Problem solving: You should configure the automatic mount of the dataDir directo
Directly querying from child table is fast. The query from super table with TAG filter is designed to meet the convenience of querying. It can filter data from multiple child tables at the same time. If the goal is to pursue performance and the child table has been clearly queried, directly querying from the sub table can achieve higher performance
### 35 How to view data compression ratio indicators?
Currently, TDengine only provides compression ratios based on tables, not databases or the entire system. To view the compression ratios, execute the `SHOW TABLE DISTRIBUTED table_name;` command in the client taos-CLI. The table_name can be a super table, regular table, or subtable. For details [Click Here](https://docs.tdengine.com/tdengine-reference/sql-manual/show-commands/#show-table-distributed)
Currently, TDengine only provides compression ratios based on tables, not databases or the entire system. To view the compression ratios, execute the `SHOW TABLE DISTRIBUTED table_name;` command in the client TDengine CLI. The table_name can be a super table, regular table, or subtable. For details [Click Here](https://docs.tdengine.com/tdengine-reference/sql-manual/show-commands/#show-table-distributed)

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" />

2
docs/en/28-releases/03-notes/3.3.2.0.md
View File

@ -56,4 +56,4 @@ slug: /release-history/release-notes/3-3-2-0
13. Upgrading to 3.3.0.0 and enabling `cachemodel` causes incorrect row count returns for `last + group by`
14. `taos-explorer` navigation bar does not display all supertable names (Enterprise Edition only)
15. Querying causes `taosd` to crash when compound primary key VARCHAR length exceeds 125
16. High CPU usage by `taos CLI` and `taosAdapter`
16. High CPU usage by `TDengine CLI` and `taosAdapter`

4
docs/en/28-releases/03-notes/3.3.3.0.md
View File

@ -53,7 +53,7 @@ slug: /release-history/release-notes/3-3-3-0
22. Cursor error in data filling during cache update causes taosd to exit abnormally
23. Random incorrect results of STDDEV function calculation
24. Unable to add offline nodes in multi-tier storage and encryption scenarios
25. taos CLI cannot input passwords longer than 20 bytes
25. TDengine CLI cannot input passwords longer than 20 bytes
26. SQL write error: int data overflow
27. Metadata consistency in scenarios of high query concurrency
28. Attempt to solve the issue where manually clicking the stop button does not stop the task
@ -90,4 +90,4 @@ slug: /release-history/release-notes/3-3-3-0
59. Client memory leak
60. Open-source users unable to modify other database options after upgrading stt_trigger value
61. Incorrect results for NOT IN (NULL) queries
62. taos shell and taosBenchmark unable to successfully connect to cloud service instances
62. TDengine CLI and taosBenchmark unable to successfully connect to cloud service instances

20
docs/en/28-releases/03-notes/3.3.4.3.md
View File

@ -52,13 +52,13 @@ slug: /release-history/release-notes/3-3-4-3
1. fix: memory leak caused by repeated addition and deletion of tables on the Windows platform.
1. fix(stream): check the right return code for concurrent checkpoint trans.
1. fix: the "too many session" problem while perform large concurrent queries.
1. fix: the problem of taos shell crashing in slow query scenarios on the Windows platform.
1. fix: the encrypted database cannot be recovered when opening the dnode log.
1. fix: the problem that taosd cannot be started due to mnode synchronization timeout.
1. fix: the slow sorting of file group data during snapshot synchronization leads to the inability of Vnode to recover.
1. fix: when writing data with escape characters to a varchar field throug line protocol, taosd will crash.
1. fix: metadata file damage caused by incorrect logic processing of error code
1. fix: when a query statement contains multiple nested "not" conditional statements, not setting the scalar mode will lead to query errors.
1. fix: the problem of dnode going offline due to timeout of vnode stat report.
1. fix: taosd failed to start on servers that not support AVX instructions.
1. fix(taosX): handle 0x09xx error codes in migration
2. fix: the problem of TDengine CLI crashing in slow query scenarios on the Windows platform.
3. fix: the encrypted database cannot be recovered when opening the dnode log.
4. fix: the problem that taosd cannot be started due to mnode synchronization timeout.
5. fix: the slow sorting of file group data during snapshot synchronization leads to the inability of Vnode to recover.
6. fix: when writing data with escape characters to a varchar field throug line protocol, taosd will crash.
7. fix: metadata file damage caused by incorrect logic processing of error code
8. fix: when a query statement contains multiple nested "not" conditional statements, not setting the scalar mode will lead to query errors.
9. fix: the problem of dnode going offline due to timeout of vnode stat report.
10. fix: taosd failed to start on servers that not support AVX instructions.
11. fix(taosX): handle 0x09xx error codes in migration

2
docs/en/28-releases/03-notes/3.3.5.0.md
View File

@ -10,7 +10,7 @@ slug: /release-history/release-notes/3-3-5-0
2. feat: refactor taosX incremental backup-restore
3. feat: add stmt2 apis in JDBC via websocket connection
4. feat: add stmt2 api in Rust connector
5. feat: add error codes in error prompts in taos-CLI
5. feat: add error codes in error prompts in TDengine CLI
6. feat: superSet can connect TDengine with python connector
7. feat: configurable grafana dashboards in explorer management
8. feat: add taosX-agent in-memory cache queu capacity option

2
docs/en/28-releases/03-notes/3.3.5.2.md
View File

@ -38,6 +38,6 @@ slug: /release-history/release-notes/3.3.5.2
20. fix: column names were not correctly copied when using SELECT * FROM subqueries
21. fix: when performing max/min function on string type data, the results are inaccurate and taosd will crash
22. fix: stream computing does not support the use of the HAVING clause, but no error is reported during creation
23. fix: the version information displayed by taos shell for the server is inaccurate, such as being unable to correctly distinguish between the community edition and the enterprise edition
23. fix: the version information displayed by TDengine CLI for the server is inaccurate, such as being unable to correctly distinguish between the community edition and the enterprise edition
24. fix: in certain specific query scenarios, when JOIN and CAST are used together, taosd may crash

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).

7
docs/examples/JDBC/taosdemo/pom.xml
View File

@ -77,13 +77,6 @@
<artifactId>fastjson</artifactId>
<version>1.2.83</version>
</dependency>
<!-- mysql: just for test -->
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>8.0.28</version>
<scope>test</scope>
</dependency>
<!-- log4j -->
<dependency>
<groupId>org.apache.logging.log4j</groupId>

26
docs/examples/flink/Main.java
View File

@ -198,7 +198,7 @@ splitSql.setSelect("ts, current, voltage, phase, groupid, location")
", current: " + rowData.getFloat(1) +
", voltage: " + rowData.getInt(2) +
", phase: " + rowData.getFloat(3) +
", location: " + new String(rowData.getBinary(4)));
", location: " + rowData.getString(4).toString());
sb.append("\n");
return sb.toString();
});
@ -273,7 +273,7 @@ splitSql.setSelect("ts, current, voltage, phase, groupid, location")
", current: " + row.getFloat(1) +
", voltage: " + row.getInt(2) +
", phase: " + row.getFloat(3) +
", location: " + new String(row.getBinary(4)));
", location: " + rowData.getString(4).toString());
sb.append("\n");
totalVoltage.addAndGet(row.getInt(2));
}
@ -311,7 +311,7 @@ splitSql.setSelect("ts, current, voltage, phase, groupid, location")
", current: " + rowData.getFloat(1) +
", voltage: " + rowData.getInt(2) +
", phase: " + rowData.getFloat(3) +
", location: " + new String(rowData.getBinary(4)));
", location: " + rowData.getString(4).toString());
sb.append("\n");
totalVoltage.addAndGet(rowData.getInt(2));
return sb.toString();
@ -353,7 +353,7 @@ splitSql.setSelect("ts, current, voltage, phase, groupid, location")
", current: " + row.getFloat(1) +
", voltage: " + row.getInt(2) +
", phase: " + row.getFloat(3) +
", location: " + new String(row.getBinary(4)));
", location: " + rowData.getString(4).toString());
sb.append("\n");
totalVoltage.addAndGet(row.getInt(2));
}
@ -489,9 +489,9 @@ splitSql.setSelect("ts, current, voltage, phase, groupid, location")
" `current` FLOAT," +
" voltage INT," +
" phase FLOAT," +
" location VARBINARY," +
" location VARCHAR(255)," +
" groupid INT," +
" tbname VARBINARY" +
" tbname VARCHAR(255)" +
") WITH (" +
" 'connector' = 'tdengine-connector'," +
" 'td.jdbc.url' = 'jdbc:TAOS-WS://localhost:6041/power?user=root&password=taosdata'," +
@ -506,9 +506,9 @@ splitSql.setSelect("ts, current, voltage, phase, groupid, location")
" `current` FLOAT," +
" voltage INT," +
" phase FLOAT," +
" location VARBINARY," +
" location VARCHAR(255)," +
" groupid INT," +
" tbname VARBINARY" +
" tbname VARCHAR(255)" +
") WITH (" +
" 'connector' = 'tdengine-connector'," +
" 'td.jdbc.mode' = 'sink'," +
@ -535,9 +535,9 @@ splitSql.setSelect("ts, current, voltage, phase, groupid, location")
" `current` FLOAT," +
" voltage INT," +
" phase FLOAT," +
" location VARBINARY," +
" location VARCHAR(255)," +
" groupid INT," +
" tbname VARBINARY" +
" tbname VARCHAR(255)" +
") WITH (" +
" 'connector' = 'tdengine-connector'," +
" 'bootstrap.servers' = 'localhost:6041'," +
@ -554,12 +554,12 @@ splitSql.setSelect("ts, current, voltage, phase, groupid, location")
" `current` FLOAT," +
" voltage INT," +
" phase FLOAT," +
" location VARBINARY," +
" location VARCHAR(255)," +
" groupid INT," +
" tbname VARBINARY" +
" tbname VARCHAR(255)" +
") WITH (" +
" 'connector' = 'tdengine-connector'," +
" 'td.jdbc.mode' = 'cdc'," +
" 'td.jdbc.mode' = 'sink'," +
" 'td.jdbc.url' = 'jdbc:TAOS-WS://localhost:6041/power_sink?user=root&password=taosdata'," +
" 'sink.db.name' = 'power_sink'," +
" 'sink.supertable.name' = 'sink_meters'" +

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

@ -8,7 +8,7 @@ TDengine 是一款[开源](https://www.taosdata.com/tdengine/open_source_time-se
TDengine 充分利用了时序数据的特点，提出了“一个数据采集点一张表”与“超级表”的概念，设计了创新的存储引擎，让数据的写入、查询和存储效率都得到极大的提升。为正确理解并使用 TDengine，无论你在工作中是什么角色，请您仔细阅读[数据模型](./basic/model)一章。
如果你是开发工程师，请一定仔细阅读[开发指南](./develop)一章，该部分对数据库连接、建模、插入数据、查询、流式计算、缓存、数据订阅、用户自定义函数等功能都做了详细介绍，并配有各种编程语言的示例代码。大部分情况下，你只要复制粘贴示例代码，针对自己的应用稍作改动，就能跑起来。对 REST API、各种编程语言的连接器（Connector）想做更多详细了解的话，请看[连接器](./reference/connector)一章。
如果你是开发工程师，请一定仔细阅读[开发指南](./develop)一章，该部分对数据库连接、建模、写入、查询、流式计算、缓存、数据订阅、用户自定义函数等功能都做了详细介绍，并配有各种编程语言的示例代码。大部分情况下，只要复制粘贴示例代码，针对自己的应用稍作改动，就能跑起来。对 REST API、各种编程语言的连接器（Connector）想做更多详细了解，请看[连接器](./reference/connector)一章。
我们已经生活在大数据时代，纵向扩展已经无法满足日益增长的业务需求，任何系统都必须具有水平扩展的能力，集群成为大数据以及 Database 系统的不可缺失功能。TDengine 团队不仅实现了集群功能，而且将这一重要核心功能开源。怎么部署、管理和维护 TDengine 集群，请仔细参考[运维管理](./operation)一章。
@ -16,7 +16,7 @@ TDengine 采用 SQL 作为查询语言，大大降低学习成本、降低迁移
如果你是系统管理员，关心安装、升级、容错灾备、关心数据导入、导出、配置参数，如何监测 TDengine 是否健康运行，如何提升系统运行的性能，请仔细参考[运维指南](./operation)一章。
如果你对数据库内核设计感兴趣，或是开源爱好者，建议仔细阅读[技术内幕](./tdinternal)一章。该章从分布式架构到存储引擎、查询引擎、数据订阅，再到流计算引擎都做了详细阐述。建议对照文档，查看TDengine在GitHub的源代码，对TDengine的设计和编码做深入了解，更欢迎加入开源社区，贡献代码。
如果你对数据库内核设计感兴趣，或是开源爱好者，建议仔细阅读[技术内幕](./tdinternal)一章。该章从分布式架构到存储引擎、查询引擎、数据订阅，再到流计算引擎都做了详细阐述。建议对照文档，查看 TDengine 在 GitHub 的源代码，对 TDengine 的设计和编码做深入了解，更欢迎加入开源社区，贡献代码。
最后，作为一个开源软件，欢迎大家的参与。如果发现文档有任何错误、描述不清晰的地方，请在每个页面的最下方，点击“编辑本文档”直接进行修改。

12
docs/zh/02-concept.md
View File

@ -9,7 +9,7 @@ toc_max_heading_level: 4
时序数据，即时间序列数据（Time-Series Data），它们是一组按照时间发生先后顺序进行排列的序列数据。日常生活中，设备、传感器采集的数据就是时序数据，证券交易的记录也是时序数据。因此时序数据的处理并不陌生，特别在是工业自动化以及证券金融行业，专业的时序数据处理软件早已存在，比如工业领域的 PI System 以及金融行业的 KDB。
这些时序数据是周期、准周期产生的，或事件触发产生的，有的采集频率高，有的采集频率低。一般被发送至服务器中进行汇总并进行实时分析和处理，对系统的运行做出实时监测或预警，对股市行情进行预测。这些数据也可以被长期保存下来，用以进行离线数据分析。比如统计时间区间内设备的运行节奏与产出，分析如何进一步优化配置来提升生产效率；统计一段时间内生产过程中的成本分布，分析如何降低生产成本；统计一段时间内的设备异常值，结合业务分析潜在的安全隐患，以降低故障时长等等。
这些时序数据是周期、准周期产生的，或事件触发产生的，有的采集频率高，有的采集频率低。一般被发送至服务器进行汇总并进行实时分析和处理，对系统的运行做出实时监测或预警，对股市行情进行预测。这些数据也可以被长期保存下来，用以进行离线数据分析。比如统计时间区间内设备的运行节奏与产出，分析如何进一步优化配置来提升生产效率；统计一段时间内生产过程中的成本分布，分析如何降低生产成本；统计一段时间内的设备异常值，结合业务分析潜在的安全隐患，以降低故障时长等等。
过去的二十年，随着数据通讯成本的急剧下降，以及各种传感技术和智能设备的出现，特别是物联网与工业 4.0 的推动，工业、物联网企业为了监测设备、环境、生产线及整个系统的运行状态，在各个关键点都配有传感器，采集各种数据。从手环、共享出行、智能电表、环境监测设备到电梯、数控机床、挖掘机、工业生产线等都在源源不断的产生海量的实时数据，时序数据的体量正指数级的增长。以智能电表为例，智能电表每隔 15 分钟采集一次数据，每天会自动生成 96 条记录。现在全中国已经有超过 10 亿台智能电表，一天就产生 960 亿条时序数据。一台联网的汽车往往每隔 10 到 15 秒采集一次数据发到云端，那么一天下来就很容易产生 1000 条记录。假设中国有 2 亿车辆联网，它们每天将产生总计 2000 亿条甚至更多的时序数据。
@ -33,7 +33,7 @@ toc_max_heading_level: 4
7. 用户关注的是一段时间的趋势：对于一条银行交易记录，或者一条微博、微信，对于它的用户而言，每一条都很重要。但对于物联网、工业时序数据，每个数据点与数据点的变化并不大，大家关心的更多是一段时间，比如过去五分钟、一小时数据变化的趋势，不会只针对一个时间点进行。
8. 数据是有保留期限的：采集的数据一般都有基于时长的保留策略，比如仅仅保留一天、一周、一个月、一年甚至更长时间，该类数据的价值往往是由时间段决定的，因此对于不在重要时间段内的数据，都是可以被视为过期数据整块删除的。
8. 数据是有保留期限的：采集的数据一般都有基于时长的保留策略，比如仅仅保留一天、一周、一个月、一年甚至更长时间，该类数据的价值往往是由时间段决定的，因此对于不在重要时间段内的数据，都是可以被视为过期数据整块删除的。
9. 需要实时分析计算操作：对于大部分互联网大数据应用，更多的是离线分析，即使有实时分析，但要求并不高。比如用户画像、可以积累一定的用户行为数据后进行，早一天晚一天画不会特别影响结果。但是对于工业、物联网的平台应用以及交易系统，对数据的实时计算要求就往往很高，因为需要根据计算结果进行实时报警、监控，从而避免事故的发生、决策时机的错过。
@ -47,7 +47,7 @@ toc_max_heading_level: 4
1. 电力能源领域：电力能源领域范围较大，不论是在发电、输电、配电、用电还是其他环节中，各种电力设备都会产生大量时序数据，以风力发电为例，风电机作为大型设备，拥有可能高达数百的数据采集点，因此每日所产生的时序数据量极其之大，对这些数据的监控分析是确保发电环节准确无误的必要工作。在用电环节，对智能电表实时采集回来的电流、电压等数据进行快速计算，实时了解最新的用电总量、尖、峰、平、谷用电量，判断设备是否正常工作。有些时候，电力系统可能需要拉取历史上某一年的全量数据，通过机器学习等技术分析用户的用电习惯、进行负荷预测、节能方案设计、帮助电力公司合理规划电力的供应。或者拉取上个月的尖峰平谷用电量，根据不同价位进行周期性的电费结算，以上都是时序数据在电力能源领域的典型应用。
2. 车联网/轨道交通领域：车辆的 GPS 、速度、油耗、故障信息等，都是典型的时序数据，通过对它们科学合理地数据分析，可以为车辆管理和优化提供强有力的支持。但是，不同车型采集的点位信息从数百点到数千点之间不一而同，随着联网的交通设备数量越来越多，这些海量的时序数据如何安全上传、数据存储、查询和分析，成为了一个亟待解决的行业问题。对于交通工具的本身，科学合理地处理时序数据可以实现车辆轨迹追踪、无人驾驶、故障预警等功能。对于交通工具的整体配套服务，也可以提供良好的支持。比如，在新一代的智能地铁管理系统中，通过地铁站中各种传感器的时序数据采集分析，可以在站中实时展示各个车厢的拥挤度、温度、舒适度等数据，让用户可以自行选择体验度最佳的出行方案，对于地铁运营商，也可以更好地实现乘客流量的调度管理。
2. 车联网/轨道交通领域：车辆的 GPS 、速度、油耗、故障信息等，都是典型的时序数据，通过科学合理地数据分析，可以为车辆管理和优化提供强有力的支持。但是，不同车型采集的点位信息从数百点到数千点之间不一而同，随着联网的交通设备数量越来越多，这些海量的时序数据如何安全上传、数据存储、查询和分析，成为了一个亟待解决的行业问题。对于交通工具的本身，科学合理地处理时序数据可以实现车辆轨迹追踪、无人驾驶、故障预警等功能。对于交通工具的整体配套服务，也可以提供良好的支持。比如，在新一代的智能地铁管理系统中，通过地铁站中各种传感器的时序数据采集分析，可以在站中实时展示各个车厢的拥挤度、温度、舒适度等数据，让用户可以自行选择体验度最佳的出行方案，对于地铁运营商，也可以更好地实现乘客流量的调度管理。
3. 智能制造领域：过去的十几年间，许多传统工业企业的数字化得到了长足的发展，单个工厂从传统的几千个数据采集点，到如今数十万点、上百万点，部分远程运维场景面临上万设备、千万点的数据采集存储的需求，这些数据都属于典型的时序数据。就整个工业大数据系统而言，时序数据的处理是相当复杂的。以烟草行业的数据采集为例，设备的工业数据协议各式各样、数据采集单位随着设备类型的不同而不同。数据的实时处理能力随着数据采集点的持续增加而难以跟上，与此同时还要兼顾数据的高性能、高可用、可拓展性等等诸多特性。但从另一个角度来看，如果大数据平台能够解决以上困难，满足企业对于时序数据存储分析的需求，就可以帮助企业实现更加智能化、自动化的生产模式，从而完成质的飞升。
@ -55,7 +55,7 @@ toc_max_heading_level: 4
5. IT 运维领域：IT 领域中，基础设施（如服务器、网络设备、存储设备）、应用程序运行的过程中会产生大量的时序数据。通过对这些时序数据的监控，可以很快地发现基础设施/应用的运行状态和服务可用性，包括系统是否在线、服务是否正常响应等；也能看到具体到某一个具体的点位的性能指标：如 CPU 利用率、内存利用率、磁盘空间利用率、网络带宽利用率等； 还可以监控系统产生的错误日志和异常事件，包括入侵检测、安全事件日志、权限控制等，最终通过设置报警规则，及时通知管理员或运维人员具体的情况，从而及时发现问题、预防故障，并优化系统性能，确保系统稳定可靠地运行。
6. 金融领域：金融领域目前正经历着数据管理的一场革命，它们的行情数据属于典型的时序数据，由于保留行情数据的储存期限往往需长达 5 至 10 年，甚至超过 30 年，而且可能全世界各个国家/地区的主流金融市场的交易数据都需要全量保存，因此行情数据的总量数据体量庞大，会轻松达到 TB 级别，造成存储、查询等等各方面的瓶颈。在金融领域中，量化交易平台是最能凸显时序数据处理重要性的革命性应用之一：通过对大量时序行情数据的读取分析来及时响应市场变化，帮助交易者把握投资机会，同时规避不必要的风险，实现资产的稳健增长。可以实现包括但不限于：资产管理、情绪监控、股票回测、交易信号模拟、报表自动生成等等诸多功能。
6. 金融领域：金融领域目前正经历着数据管理的一场革命，行情数据属于典型的时序数据，由于保留行情数据的储存期限往往需长达 5 至 10 年，甚至超过 30 年，而且可能全世界各个国家/地区的主流金融市场的交易数据都需要全量保存，因此行情数据的总量数据体量庞大，会轻松达到 TB 级别，造成存储、查询等等各方面的瓶颈。在金融领域中，量化交易平台是最能凸显时序数据处理重要性的革命性应用之一：通过对大量时序行情数据的读取分析来及时响应市场变化，帮助交易者把握投资机会，同时规避不必要的风险，实现资产的稳健增长。可以实现包括但不限于：资产管理、情绪监控、股票回测、交易信号模拟、报表自动生成等等诸多功能。
## 处理时序数据所需要的工具
@ -71,11 +71,11 @@ toc_max_heading_level: 4
5. 缓存（Cache）：物联网、工业、金融应用需要实时展示一些设备或股票的最新状态，因此平台需要缓存技术提供快速的数据访问。原因是：由于时序数据体量极大，如果不使用缓存技术，而是进行常规的读取、筛选，那么对于监控设备最新状态之类的计算是十分困难的，将会导致很大的延迟，从而失去“实时”的意义。因此，缓存技术是时序数据处理平台不可缺少的一环， Redis 就是这样一种常用的缓存工具。
处理时序数据需要一系列模块的协同作业，从数据采集到存储、计算、分析与可视化，再到专用的时序数据算法库，每个环节都有相应的工具支持。这些工具的选择取决于具体的业务需求和数据特点，合理地选用和搭配它们才能做到高效地处理各种类型的时序数据，挖掘数据背后的价值。
处理时序数据需要一系列模块的协同作业，从数据采集到存储、计算、分析与可视化，再到专用的时序数据算法库，每个环节都有相应的工具支持。这些工具的选择取决于具体的业务需求和数据特点，合理地选用和搭配才能做到高效地处理各种类型的时序数据，挖掘数据背后的价值。
## 专用时序数据处理工具的必要性
在时序数据的十大特征一节中提到，对于一个优秀的时序大数据处理平台来说，它必然需要具备处理时序数据十大特征的能力。在处理时序数据所需要的工具一节中介绍了时序大数据平台处理时序数据所需要的主要模块/组件。 结合这两节的内容与实际情况，可以发现：处理海量时序数据，其实是一个很庞大复杂的系统。
在时序数据的十大特征一节中提到，对于一个优秀的时序大数据处理平台来说，必然需要具备处理时序数据十大特征的能力。在处理时序数据所需要的工具一节中介绍了时序大数据平台处理时序数据所需要的主要模块/组件。结合这两节的内容与实际情况，可以发现：处理海量时序数据，其实是一个很庞大复杂的系统。
早些年，为处理日益增长的互联网数据，众多的工具开始出现，最流行的便是 Hadoop 体系。除使用大家所熟悉的 Hadoop 组件如 HDFS、MapReduce、HBase 和 Hive 外，通用的大数据处理平台往往还使用 Kafka 或其他消息队列工具，Redis 或其他缓存软件，Flink 或其他实时流式数据处理软件。存储上也有人选用 MongoDB、Cassandra 或其他 NoSQL 数据库。这样一个典型的大数据处理平台基本上能很好的处理互联网行业的引用，比如典型的用户画像、舆情分析等。

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

@ -14,7 +14,7 @@ TDengine 是一个高性能、分布式的时序数据库。通过集成的缓
TDengine OSS 是一个开源的高性能时序数据库，与其他时序数据库相比，它的核心优势在于其集群开源、高性能和云原生架构。而且除了基础的写入、查询和存储功能外，TDengine OSS 还集成了缓存、流式计算和数据订阅等高级功能，这些功能显著简化了系统设计，降低了企业的研发和运营成本。
在 TDengine OSS 的基础上，企业版 TDengine Enterprise 提供了增强的辅助功能，包括数据的备份恢复、异地容灾、多级存储、视图、权限控制、安全加密、IP 白名单、支持 MQTT、OPC-UA、OPC-DA、PI、Wonderware、Kafka 等各种数据源。这些功能为企业提供了更为全面、安全、可靠和高效的时序数据管理解决方案。更多的细节请看 [TDengine Enterprise](https://www.taosdata.com/tdengine-pro)
在 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)
@ -30,19 +30,19 @@ TDengine 经过特别优化，以适应时间序列数据的独特需求，引
4. 流式计算：TDengine 流式计算引擎提供了实时处理写入的数据流的能力，不仅支持连续查询，还支持事件驱动的流式计算。它提供了替代复杂流处理系统的轻量级解决方案，并能够在高吞吐的数据写入的情况下，提供毫秒级的计算结果延迟。
5. 数据订阅：TDengine 提供了类似 Kafka 的数据订阅功能。但用户可以通过 SQL 来灵活控制订阅的数据内容，并使用 Kafka 相同的 API 来订阅一张表、一组表、全部列或部分列、甚至整个数据库的数据。TDengine 可以替代需要集成消息队列产品的场景， 从而简化系统设计的复杂度，降低运营维护成本。
5. 数据订阅：TDengine 提供了类似 Kafka 的数据订阅功能。但用户可以通过 SQL 来灵活控制订阅的数据内容，并使用和 Kafka 相同的 API 来订阅一张表、一组表、全部列或部分列、甚至整个数据库的数据。TDengine 可以替代需要集成消息队列产品的场景， 从而简化系统设计的复杂度，降低运营维护成本。
6. 可视化/BI：TDengine 本身不提供可视化或 BI 的功能。但通过其 RESTful API， 标准的 JDBC、ODBC 接口，TDengine 能够 Grafana、Google Data Studio、Power BI、Tableau 以及国产 BI 工具无缝集成。
6. 可视化/BI：TDengine 本身不提供可视化或 BI 的功能。但通过其 RESTful API， 标准的 JDBC、ODBC 接口，TDengine 能够和 Grafana、Google Data Studio、Power BI、Tableau 以及国产 BI 工具无缝集成。
7. 集群功能：TDengine 支持集群部署，能够随着业务数据量的增长，通过增加节点线性提升系统处理能力，实现水平扩展。同时，通过多副本技术提供高可用性，并支持 Kubernetes 部署。同时还提供了多种运维工具，方便系统管理员更好地管理和维护集群的健壮运行。
7. 集群功能：TDengine 支持集群部署，能够随着业务数据量的增长，通过增加节点线性提升系统处理能力，实现水平扩展。同时，通过多副本技术提供高可用性，支持 Kubernetes 部署，提供了多种运维工具，方便系统管理员更好地管理和维护集群的健壮运行。
8. 数据迁移：TDengine 提供了多种便捷的数据导入导出功能，包括脚本文件导入导出、数据文件导入导出、taosdump 工具导入导出等。
9. 编程连接器：TDengine 提供不同语言的连接器，包括 C/C++、Java、Go、Node.js、Rust、Python、C#、R、PHP 等。这些连接器大多都支持原生连接和 WebSocket 两种连接方式。TDengine 也提供 RESTful 接口，任何语言的应用程序可以直接通过 HTTP 请求访问数据库。
9. 编程连接器：TDengine 提供多种语言的连接器，包括 C/C++、Java、Go、Node.js、Rust、Python、C#、R、PHP 等。这些连接器大多都支持原生连接和 WebSocket 两种连接方式。TDengine 也提供 RESTful 接口，任何语言的应用程序可以直接通过 HTTP 请求访问数据库。
10. 数据安全：TDengine 提供了丰富的用户管理和权限管理功能以控制不同用户对数据库和表的访问权限，提供了 IP 白名单功能以控制不同帐号只能从特定的服务器接入集群。TDengine 支持系统管理员对不同数据库按需加密，数据加密后对读写完全透明且对性能的影响很小。还提供了审计日志功能以记录系统中的敏感操作。
11. 常用工具：TDengine 还提供了交互式命令行程序（CLI），便于管理集群、检查系统状态、做即时查询。压力测试工具 taosBenchmark，用于测试 TDengine 的性能。TDengine 还提供了图形化管理界面，简化了操作和管理过程。
11. 常用工具：TDengine 提供了交互式命令行程序（CLI），便于管理集群、检查系统状态、做即时查询。压力测试工具 taosBenchmark，用于测试 TDengine 的性能。TDengine 还提供了图形化管理界面，简化了操作和管理过程。
12. 零代码数据接入：TDengine 企业版提供了丰富的数据接入功能，依托强大的数据接入平台，无需一行代码，只需要做简单的配置即可实现多种数据源的数据接入，目前已经支持的数据源包括：OPC-UA、OPC-DA、PI、MQTT、Kafka、InfluxDB、OpenTSDB、MySQL、SQL Server、Oracle、Wonderware Historian、MongoDB。
@ -63,8 +63,11 @@ TDengine 经过特别优化，以适应时间序列数据的独特需求，引
6. 核心开源：TDengine 的核心代码，包括集群功能，均在开源协议下公开发布。它在 GitHub 网站全球趋势排行榜上多次位居榜首，显示出其受欢迎程度。同时，TDengine 拥有一个活跃的开发者社区，为技术的持续发展和创新提供了有力支持。
采用 TDengine，企业可以在物联网、车联网、工业互联网等典型场景中显著降低大数据平台的总拥有成本，主要体现在以下几个方面：
1. 高性能带来的成本节约：TDengine 卓越的写入、查询和存储性能意味着系统所需的计算资源和存储资源可以大幅度减少。这不仅降低了硬件成本，还减少了能源消耗和维护费用。
2. 标准化与兼容性带来的成本效益：由于 TDengine 支持标准 SQL，并与众多第三方软件实现了无缝集成，用户可以轻松地将现有系统迁移到 TDengine 上，无须重写大量代码。这种标准化和兼容性大大降低了学习和迁移成本，缩短了项目周期。
3. 简化系统架构带来的成本降低：作为一个极简的时序数据平台，TDengine 集成了消息队列、缓存、流计算等必要功能，避免了额外集成众多其他组件的需要。这种简化的系统架构显著降低了系统的复杂度，从而减少了研发和运营成本，提高了整体运营效率。
## 技术生态
@ -78,7 +81,7 @@ TDengine 经过特别优化，以适应时间序列数据的独特需求，引
<center><figcaption>图 1. TDengine 技术生态图</figcaption></center>
</figure>
上图中，左侧是各种数据采集或消息队列，包括 OPC-UA、MQTT、Telegraf、也包括 Kafka，他们的数据将被源源不断的写入到 TDengine。右侧则是可视化、BI 工具、组态软件、应用程序。下侧则是 TDengine 自身提供的命令行程序（CLI）以及可视化管理工具。
上图中，左侧是各种数据采集或消息队列，包括 OPC-UA、MQTT、Telegraf、也包括 Kafka，它们的数据将被源源不断的写入到 TDengine。右侧是可视化、BI 工具、组态软件、应用程序。下侧是 TDengine 自身提供的命令行程序（CLI）以及可视化管理工具。
## 典型适用场景

4
docs/zh/04-get-started/01-docker.md
View File

@ -1,5 +1,5 @@
---
sidebar_label: 用Docker快速体验
sidebar_label: 用 Docker 快速体验
title: 用 Docker 快速体验 TDengine
description: 使用 Docker 快速体验 TDengine 的高效写入和查询
---
@ -91,7 +91,7 @@ taosBenchmark 提供了丰富的选项，允许用户自定义测试参数，如
taosBenchmark --help
```
有关taosBenchmark 的详细使用方法，请参考[taosBenchmark 参考手册](../../reference/tools/taosbenchmark)
有关 taosBenchmark 的详细使用方法，请参考 [taosBenchmark 参考手册](../../reference/tools/taosbenchmark)
### 体验查询

38
docs/zh/04-get-started/03-package.md
View File

@ -8,7 +8,7 @@ import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import PkgListV3 from "/components/PkgListV3";
TDengine 完整的软件包包括服务端（taosd）、应用驱动（taosc）、用于与第三方系统对接并提供 RESTful 接口的 taosAdapter、命令行程序（CLI，taos）和一些工具软件。目前 TDinsight 仅在 Linux 系统上安装和运行，后续将支持 Windows、macOS 等系统。TDengine 除了提供多种语言的连接器之外，还通过 [taosAdapter](../../reference/components/taosadapter/) 提供 [RESTful 接口](../../reference/connector/rest-api/)。
TDengine 完整的软件包包括服务端（taosd）、应用驱动（taosc）、用于与第三方系统对接并提供 RESTful 接口的 taosAdapter、命令行程序（TDengine CLI）和一些工具软件。目前 TDinsight 仅在 Linux 系统上安装和运行，后续将支持 Windows、macOS 等系统。TDengine 除了提供多种语言的连接器之外，还通过 [taosAdapter](../../reference/components/taosadapter/) 提供 [RESTful 接口](../../reference/connector/rest-api/)。
为方便使用，标准的服务端安装包包含了 taosd、taosAdapter、taosc、taos、taosdump、taosBenchmark、TDinsight 安装脚本和示例代码；如果您只需要用到服务端程序和客户端连接的 C/C++ 语言支持，也可以仅下载 Lite 版本的安装包。
@ -17,30 +17,27 @@ TDengine 完整的软件包包括服务端（taosd）、应用驱动（taosc）
此外，TDengine 也提供 macOS x64/m1 平台的 pkg 安装包。
## 运行环境要求
在linux系统中，运行环境最低要求如下:
1. linux 内核版本：3.10.0-1160.83.1.el7.x86_64 或以上
2. glibc 版本：2.17 或以上
linux 内核版本 - 3.10.0-1160.83.1.el7.x86_64;
glibc 版本 - 2.17;
如果通过clone源码进行编译安装，还需要满足:
cmake版本 - 3.26.4或以上;
gcc 版本 - 9.3.1或以上;
如果通过 Clone 源码进行编译安装，还需要满足:
1. cmake 版本：3.26.4 或以上
2. gcc 版本：9.3.1 或以上
## 安装
**注意**
从TDengine 3.0.6.0 开始，不再提供单独的 taosTools 安装包，原 taosTools 安装包中包含的工具都在 TDengine-server 安装包中，如果需要请直接下载 TDengine -server 安装包。
从 TDengine 3.0.6.0 开始，不再提供单独的 taosTools 安装包，原 taosTools 安装包中包含的工具都在 TDengine-server 安装包中，如果需要请直接下载 TDengine-server 安装包。
<Tabs>
<TabItem label="Deb 安装" value="debinst">
1. 从列表中下载获得 Deb 安装包；
1. 从列表中下载获得 Deb 安装包：
<PkgListV3 type={6}/>
2. 进入到安装包所在目录，执行如下的安装命令：
> 请将 `<version>` 替换为下载的安装包版本
@ -53,8 +50,9 @@ sudo dpkg -i TDengine-server-<version>-Linux-x64.deb
<TabItem label="RPM 安装" value="rpminst">
1. 从列表中下载获得 RPM 安装包；
1. 从列表中下载获得 RPM 安装包：
<PkgListV3 type={5}/>
2. 进入到安装包所在目录，执行如下的安装命令：
> 请将 `<version>` 替换为下载的安装包版本
@ -67,7 +65,7 @@ sudo rpm -ivh TDengine-server-<version>-Linux-x64.rpm
<TabItem label="tar.gz 安装" value="tarinst">
1. 从列表中下载获得 tar.gz 安装包；
1. 从列表中下载获得 tar.gz 安装包：
<PkgListV3 type={0}/>
2. 进入到安装包所在目录，使用 `tar` 解压安装包；
3. 进入到安装包所在目录，先解压文件后，进入子目录，执行其中的 install.sh 安装脚本。
@ -126,14 +124,14 @@ apt-get 方式只适用于 Debian 或 Ubuntu 系统。
**注意**
- 目前 TDengine 在 Windows 平台上只支持 Windows Server 2016/2019 和 Windows 10/11。
- 从 TDengine 3.1.0.0 开始，只提供 Windows 客户端安装包。如果需要 Windows 服务端安装包，请联系 TDengine 销售团队升级为企业版。
- Windows 上需要安装 VC 运行时库，可在此下载安装 [VC运行时库](https://learn.microsoft.com/zh-cn/cpp/windows/latest-supported-vc-redist?view=msvc-170), 如果已经安装此运行库可忽略。
- Windows 上需要安装 VC 运行时库，可在此下载安装 [VC 运行时库](https://learn.microsoft.com/zh-cn/cpp/windows/latest-supported-vc-redist?view=msvc-170)，如果已经安装此运行库可忽略。
按照以下步骤安装：
1. 从列表中下载获得 exe 安装程序；
1. 从列表中下载获得 exe 安装程序：
<PkgListV3 type={3}/>
2. 运行可执行程序来安装 TDengine。
Note: 从 3.0.1.7 开始，只提供 TDengine 客户端的 Windows 客户端的下载。想要使用TDengine 服务端的 Windows 版本，请联系销售升级为企业版本。
Note: 从 3.0.1.7 版本开始，只提供 TDengine 客户端的 Windows 客户端的下载。想要使用 TDengine 服务端的 Windows 版本，请联系 TDengine 销售团队升级为企业版。
</TabItem>
<TabItem label="macOS 安装" value="macos">
@ -210,12 +208,12 @@ sudo launchctl start com.tdengine.taoskeeper
sudo launchctl start com.tdengine.taos-explorer
```
你也可以直接运行 start-all.sh 脚本来启动上面的所有服务
你也可以直接运行 `start-all.sh` 脚本来启动上面的所有服务
```bash
start-all.sh
```
可以使用 `launchctl` 命令管理上面提到的每个 TDengine 服务，以下示例使用 `taosd` ：
可以使用 `launchctl` 命令管理上面提到的每个 TDengine 服务，以下示例使用 `taosd` ：
```bash
sudo launchctl start com.tdengine.taosd

9
docs/zh/04-get-started/05-cloud.md
View File

@ -4,7 +4,7 @@ title: 通过云服务 快速体验 TDengine
toc_max_heading_level: 4
---
TDengine Cloud 作为一个全托管的时序大数据云服务平台，致力于让用户迅速领略TDengine 的强大功能。该平台不仅继承了 TDengine Enterprise 的核心功能特性，还充分发挥了 TDengine 的云原生优势。TDengine Cloud 以其极致的资源弹性伸缩、高可用性、容器化部署以及按需付费等特点，灵活满足各类用户需求，为用户打造高效、可靠且经济的时序大数据处理解决方案。
TDengine Cloud 作为一个全托管的时序大数据云服务平台，致力于让用户迅速领略 TDengine 的强大功能。该平台不仅继承了 TDengine Enterprise 的核心功能特性，还充分发挥了 TDengine 的云原生优势。TDengine Cloud 以其极致的资源弹性伸缩、高可用性、容器化部署以及按需付费等特点，灵活满足各类用户需求，为用户打造高效、可靠且经济的时序大数据处理解决方案。
TDengine Cloud 大幅减轻了用户在部署、运维等方面的人力负担，同时提供了全方位的企业级服务。这些服务涵盖多角色、多层次的用户管理、数据共享功能，以适应各种异构网络环境。此外，TDengine Cloud 还提供私有链接服务和极简的数据备份与恢复功能，确保数据安全无忧。
@ -25,11 +25,10 @@ TDengine Cloud 大幅减轻了用户在部署、运维等方面的人力负担
要在 TDengine Cloud 中创建 TDengine 实例，只须遵循以下 3 个简单步骤。
1. 第 1 步，选择公共数据库。在此步骤中，TDengine Cloud 提供了可供公共访问的智能电表等数据库。通过浏览和查询这些数据库，你可以立即体验 TDengine 的各种功能和高性能。你可以根据需求在此步骤启动数据库访问，或在后续使用过程中再进行启动。若不需要此步骤，可直接点击“下一步”按钮跳过。
1. 选择公共数据库。在此步骤中，TDengine Cloud 提供了可供公共访问的智能电表等数据库。通过浏览和查询这些数据库，你可以立即体验 TDengine 的各种功能和高性能。你可以根据需求在此步骤启动数据库访问，或在后续使用过程中再进行启动。若不需要此步骤，可直接点击“下一步”按钮跳过。
2. 第 2 步，创建组织。在此步骤中，请输入一个具有意义的名称，代表你的公司或组织，这将有助于你和平台更好地管理云上资源。
3. 第 3 步，创建实例。在此步骤中，你需要填写实例的区域、名称、是否选择高可用选项以及计费方案等必填信息。确认无误后，点击“创建”按钮。大约等待 1min，新的TDengine 实例便会创建完成。随后，你可以在控制台中对该实例进行各种操作，如查询数据、创建订阅、创建流等。
2. 创建组织。在此步骤中，请输入一个具有意义的名称，代表你的公司或组织，这将有助于你和平台更好地管理云上资源。
3. 创建实例。在此步骤中，你需要填写实例的区域、名称、是否选择高可用选项以及计费方案等必填信息。确认无误后，点击“创建”按钮。大约等待 1min，新的 TDengine 实例便会创建完成。随后，你可以在控制台中对该实例进行各种操作，如查询数据、创建订阅、创建流等。
TDengine Cloud 提供多种级别的计费方案，包括入门版、基础版、标准版、专业版和旗舰版，以满足不同客户的需求。如果你觉得现有计费方案无法满足自己的特定需求，请联系 TDengine Cloud 的客户支持团队，他们将为你量身定制计费方案。注册后，你将获得一定的免费额度，以便体验服务

2
docs/zh/04-get-started/index.md
View File

@ -8,7 +8,7 @@ import xiaot_new from './xiaot-20231007.png'
import channel from './channel.webp'
import official_account from './official-account.webp'
TDengine 完整的软件包包括服务端（taosd）、用于与第三方系统对接并提供 RESTful 接口的 taosAdapter、应用驱动（taosc）、命令行程序 (CLI，taos) 和一些工具软件。TDengine 除了提供多种语言的连接器之外，还通过 [taosAdapter](../reference/components/taosadapter) 提供 [RESTful 接口](../reference/connector/rest-api)。
TDengine 完整的软件包包括服务端（taosd）、用于与第三方系统对接并提供 RESTful 接口的 taosAdapter、应用驱动（taosc）、命令行程序 (TDengine CLI) 和一些工具软件。TDengine 除了提供多种语言的连接器之外，还通过 [taosAdapter](../reference/components/taosadapter) 提供 [RESTful 接口](../reference/connector/rest-api)。
本章主要介绍如何快速设置 TDengine 环境并体验其高效写入和查询。

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

@ -25,11 +25,11 @@ toc_max_heading_level: 4
### 采集量
采集量是指通过各种传感器、设备或其他类型的采集点所获取的物理量，如电流、电压、温度、压力、GPS 等。由于这些物理量随时间不断变化，因此采集的数据类型多
样，包括整型、浮点型、布尔型以及字符串等。随着时间的积累，存储的数据将持续增长。以智能电表为例，其中的 current（电流）、voltage（电压）和 phase（相位）便是典型的采集量。
样，包括整型、浮点型、布尔型以及字符串等。随着时间的积累，存储的数据将持续增长。以智能电表为例，其中的 current、voltage 和 phase 便是典型的采集量。
### 标签
标签是指附着在传感器、设备或其他类型采集点上的静态属性，这些属性不会随时间发生变化，例如设备型号、颜色、设备所在地等。标签的数据类型可以是任意类型。尽管标签本身是静态的，但在实际应用中，用户可能需要对标签进行修改、删除或添加。与采集量不同，随着时间的推移，存储的标签数据量保持相对稳定，不会呈现明显的增长趋势。在智能电表的示例中，location（位置）和 Group ID（分组 ID）就是典型的标签。
标签是指附着在传感器、设备或其他类型采集点上的静态属性，这些属性不会随时间发生变化，例如设备型号、颜色、设备所在地等。标签的数据类型可以是任意类型。尽管标签本身是静态的，但在实际应用中，用户可能需要对标签进行修改、删除或添加。与采集量不同，随着时间的推移，存储的标签数据量保持相对稳定，不会呈现明显的增长趋势。在智能电表的示例中，location 和 Group ID 就是典型的标签。
### 数据采集点
@ -49,9 +49,9 @@ toc_max_heading_level: 4
4. 一个数据块内部，采用列式存储，对于不同的数据类型，可以采用不同压缩算法来提高压缩率。并且，由于采集量的变化通常是缓慢的，压缩率会更高。
如果采用传统的方式，将多个数据采集点的数据写入一张表，由于网络延时不可控，不同数据采集点的数据到达服务器的时序是无法保证的，写入操作是要有锁保护的，而且一个数据采集点的数据是难以保证连续存储在一起的。采用一个数据采集点一张表的方式，能最大程度的保证单个数据采集点的插入和查询的性能是最优的，，而且数据压缩率最高。
如果采用传统的方式，将多个数据采集点的数据写入一张表，由于网络延时不可控，不同数据采集点的数据到达服务器的时序是无法保证的，写入操作是要有锁保护的，而且一个数据采集点的数据是难以保证连续存储在一起的。采用一个数据采集点一张表的方式，能最大程度的保证单个数据采集点的插入和查询的性能是最优的，而且数据压缩率最高。
在 TDengine 中，通常使用数据采集点的名称（如：d1001）来做表名，每个数据采集点可以有多个采集量（如：current、voltage、phase 等），每个采集量对应一张表的一列。采集量的数据类型可以是整型、浮点型、字符串等。
在 TDengine 中，通常使用数据采集点的名称（如 d1001）来做表名，每个数据采集点可以有多个采集量（如 current、voltage、phase 等），每个采集量对应一张表的一列。采集量的数据类型可以是整型、浮点型、字符串等。
此外，表的第一列必须是时间戳，即数据类型为 Timestamp。对于每个采集量，TDengine 将使用第一列时间戳建立索引，采用列式存储。对于复杂的设备，比如汽车，它有多个数据采集点，则需要为一辆汽车建立多张表。
@ -86,12 +86,12 @@ toc_max_heading_level: 4
### 时间戳
时间戳在时序数据处理中扮演着至关重要的角色，特别是在应用程序需要从多个不同时区访问数据库时，这一问题变得更加复杂。在深入了解 TDengine 如何处理时间戳与时区之前，我们先介绍以下几个基本概念。
- 本地日期时间：指特定地区的当地时间，通常表示为 yyyy-MM-dd hh:mm:ss.SSS 格 式 的 字 符 串。 这 种 时 间 表 示 不 包 含 任 何 时 区 信 息， 如“2021-07-21 12:00:00.000”。
- 时区：地球上不同地理位置的标准时间。协调世界时（Universal Time Coordinated，UTC）或格林尼治时间是国际时间标准，其他时区通常表示为相对于 UTC 的偏移量，如“UTC+8”代表东八区时间。 UTC 时间戳：表示自 UNIX 纪 元（即 UTC 时 间 1970 年 1 月 1 日 0 点） 起 经 过的毫秒数。例如，“1700000000000”对应的日期时间是“2023-11-14 22:13:20（UTC+0）”。 在 TDengine 中保存时序数据时，实际上保存的是 UTC 时间戳。TDengine 在写入数据时，时间戳的处理分为如下两种情况。
- RFC-3339 格式：当使用这种格式时，TDengine 能够正确解析带有时区信息的时间字符串为 UTC 时间戳。例如，“2018-10-03T14:38:05.000+08:00”会被转换为UTC 时间戳。
- 本地日期时间：指特定地区的当地时间，通常表示为 yyyy-MM-dd hh:mm:ss.SSS 格式的字符串。这种时间表示不包含任何时区信息，如 “2021-07-21 12:00:00.000”。
- 时区：地球上不同地理位置的标准时间。协调世界时（Universal Time Coordinated，UTC）或格林尼治时间是国际时间标准，其他时区通常表示为相对于 UTC 的偏移量，如 “UTC+8” 代表东八区时间。 UTC 时间戳：表示自 UNIX 纪元（即 UTC 时间 1970 年 1 月 1 日 0 点）起经过的毫秒数。例如，“1700000000000” 对应的日期时间是 “2023-11-14 22:13:20（UTC+0）”。 在 TDengine 中保存时序数据时，实际上保存的是 UTC 时间戳。TDengine 在写入数据时，时间戳的处理分为如下两种情况。
- RFC-3339 格式：当使用这种格式时，TDengine 能够正确解析带有时区信息的时间字符串为 UTC 时间戳。例如，“2018-10-03T14:38:05.000+08:00” 会被转换为 UTC 时间戳。
- 非 RFC-3339 格式：如果时间字符串不包含时区信息，TDengine 将使用应用程序所在的时区设置自动将时间转换为 UTC 时间戳。
在查询数据时，TDengine 客户端会根据应用程序当前的时区设置，自动将保存的UTC 时间戳转换成本地时间进行显示，确保用户在不同时区下都能看到正确的时间信息。
在查询数据时，TDengine 客户端会根据应用程序当前的时区设置，自动将保存的 UTC 时间戳转换成本地时间进行显示，确保用户在不同时区下都能看到正确的时间信息。
## 数据建模
@ -110,7 +110,7 @@ CREATE DATABASE power PRECISION 'ms' KEEP 3650 DURATION 10 BUFFER 16;
- `DURATION 10` ：每 10 天的数据放在一个数据文件中
- `BUFFER 16` ：写入使用大小为 16MB 的内存池。
在创建power数据库后，可以执行 USE 语句来使用切换数据库。
在创建 power 数据库后，可以执行 USE 语句来使用切换数据库。
```sql
use power;
@ -134,10 +134,10 @@ CREATE STABLE meters (
在 TDengine 中，创建超级表的 SQL 语句与关系型数据库类似。例如，上面的 SQL 中，`CREATE STABLE` 为关键字，表示创建超级表；接着，`meters` 是超级表的名称；在表名后面的括号中，定义超级表的列（列名、数据类型等），规则如下：
1. 第 1 列必须为时间戳列。例如：`ts timestamp` 表示，时间戳列名是 `t`s，数据类型为 `timestamp`；
2. 从第 2 列开始是采集量列。采集量的数据类型可以为整型、浮点型、字符串等。例如：`current float` 表示，采集量电流 `current`，数据类型为 `float`；
1. 第 1 列必须为时间戳列。例如：`ts timestamp` 表示，时间戳列名是 `ts`，数据类型为 `timestamp`；
2. 第 2 列开始是采集量列。采集量的数据类型可以为整型、浮点型、字符串等。例如：`current float` 表示，采集量电流 `current`，数据类型为 `float`。
最后，TAGS是关键字，表示标签，在 TAGS 后面的括号中，定义超级表的标签（标签名、数据类型等）。
最后，TAGS 是关键字，表示标签，在 TAGS 后面的括号中，定义超级表的标签（标签名、数据类型等）。
1. 标签的数据类型可以为整型、浮点型、字符串等。例如：`location varchar(64)` 表示，标签地区 `location`，数据类型为 `varchar(64)`；
2. 标签的名称不能与采集量列的名称相同。
@ -155,7 +155,7 @@ USING meters (
);
```
上面的 SQL 中，`CREATE TABLE` 为关键字，表示创建表；`d1001` 是子表的名称；`USING` 是关键字，表示要使用超级表作为模版；`meters` 是超级表的名称；在超级表名后的括号中，`location`, `group_id` 表示，是超级表的标签列名列表；`TAGS` 是关键字，在后面的括号中指定子表的标签列的值。`"California.SanFrancisco"` 和 `2` 表示子表 `d1001` 的位置为 `California.SanFrancisco`，分组 ID 为 `2` 。
上面的 SQL 中，`CREATE TABLE` 为关键字，表示创建表；`d1001` 是子表的名称；`USING` 是关键字，表示要使用超级表作为模版；`meters` 是超级表的名称；在超级表名后的括号中，`location`、`group_id` 表示，是超级表的标签列名列表；`TAGS` 是关键字，在后面的括号中指定子表的标签列的值。`"California.SanFrancisco"` 和 `2` 表示子表 `d1001` 的位置为 `California.SanFrancisco`，分组 ID 为 `2`。
当对超级表进行写入或查询操作时，用户可以使用伪列 tbname 来指定或输出对应操作的子表名。
@ -178,7 +178,7 @@ TAGS (
);
```
上面的 SQL 中，`INSERT INTO d1002` 表示，向子表 `d1002` 中写入数据；`USING meters` 表示，使用超级表 `meters` 作为模版；`TAGS ("California.SanFrancisco", 2)` 表示，子表 `d1002` 的标签值分别为 `California.SanFrancisco` 和 `2`；`VALUES (NOW, 10.2, 219, 0.32)` 表示，向子表 `d1002` 插入一行记录，值分别为NOW（当前时间戳）、10.2（电流）、219（电压）、0.32（相位）。在 TDengine 执行这条 SQL 时，如果子表 `d1002` 已经存在，则直接写入数据；当子表 `d1002` 不存在，会先自动创建子表，再写入数据。
上面的 SQL 中，`INSERT INTO d1002` 表示，向子表 `d1002` 中写入数据；`USING meters` 表示，使用超级表 `meters` 作为模版；`TAGS ("California.SanFrancisco", 2)` 表示，子表 `d1002` 的标签值分别为 `California.SanFrancisco` 和 `2`；`VALUES (NOW, 10.2, 219, 0.32)` 表示，向子表 `d1002` 插入一行记录，值分别为 NOW（当前时间戳）、10.2（电流）、219（电压）、0.32（相位）。在 TDengine 执行这条 SQL 时，如果子表 `d1002` 已经存在，则直接写入数据；当子表 `d1002` 不存在，会先自动创建子表，再写入数据。
### 创建普通表
@ -204,7 +204,7 @@ CREATE TABLE d1003(
);
```
上面的 SQL 表示，创建普通表 `d1003` ，表结构包括 `ts`、`current`、`voltage`、`phase`、`location`、`group_id`，共 6 个列。这样的数据模型，与关系型数据库完全一致。
上面的 SQL 表示，创建普通表 `d1003`，表结构包括 `ts`、`current`、`voltage`、`phase`、`location`、`group_id`，共 6 个列。这样的数据模型，与关系型数据库完全一致。
采用普通表作为数据模型意味着静态标签数据（如 location 和 group_id）会重复存储在表的每一行中。这种做法不仅增加了存储空间的消耗，而且在进行查询时，由于无法直接利用标签数据进行过滤，查询性能会显著低于使用超级表的数据模型。

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

@ -12,9 +12,9 @@ toc_max_heading_level: 4
### 一次写入一条
假设设备 ID 为 d1001 的智能电表在 2018 年 10 月 3 日 14:38:05 采集到数据：电流10.3A，电压 219V，相位 0.31。在第 3 章中，我们已经在 TDengine 的 power 数据库中创建了属于超级表 meters 的子表 d1001。接下来可以通过下面的 insert 语句在子表 d1001 中写入时序数据。
假设设备 ID 为 d1001 的智能电表在 2018 年 10 月 3 日 14:38:05 采集到数据：电流 10.3A，电压 219V，相位 0.31。在第 3 章中，我们已经在 TDengine 的 power 数据库中创建了属于超级表 meters 的子表 d1001。接下来可以通过下面的 insert 语句在子表 d1001 中写入时序数据。
1. 可以通过下面的 INSERT 语句向子表d1001中写入时序数据。
1. 可以通过下面的 INSERT 语句向子表 d1001 中写入时序数据。
```sql
insert into d1001 (ts, current, voltage, phase) values ( "2018-10-03 14:38:05", 10.3, 219, 0.31)
@ -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)
```
### 零代码写入
@ -120,7 +120,7 @@ values( "d1001, "2018-10-03 14:38:05", 10.2, 220, 0.23, "California.SanFrancisco
## 更新
可以通过写入重复时间戳的一条数据来更新时序数据，新写入的数据会替换旧值。 下面的 SQL，通过指定列的方式，向子表 `d1001` 中写入 1 行数据；当子表 `d1001` 中已经存在日期时间为 `2018-10-03 14:38:05` 的数据时，`current`（电流）的新值22，会替换旧值。
可以通过写入重复时间戳的一条数据来更新时序数据，新写入的数据会替换旧值。下面的 SQL，通过指定列的方式，向子表 `d1001` 中写入 1 行数据；当子表 `d1001` 中已经存在日期时间为 `2018-10-03 14:38:05` 的数据时，`current`（电流）的新值 22，会替换旧值。
```sql
INSERT INTO d1001 (ts, current) VALUES ("2018-10-03 14:38:05", 22);
@ -128,7 +128,7 @@ INSERT INTO d1001 (ts, current) VALUES ("2018-10-03 14:38:05", 22);
## 删除
为方便用户清理由于设备故障等原因产生的异常数据，TDengine 支持根据时间戳删除时序数据。 下面的 SQL，将超级表 `meters` 中所有时间戳早于 `2021-10-01 10:40:00.100` 的数据删除。数据删除后不可恢复，请慎重使用。为了确保删除的数据确实是自己要删除的，建议可以先使用 select 语句加 where 后的删除条件查看要删除的数据内容，确认无误后再执行 delete 。
为方便用户清理由于设备故障等原因产生的异常数据，TDengine 支持根据时间戳删除时序数据。下面的 SQL，将超级表 `meters` 中所有时间戳早于 `2021-10-01 10:40:00.100` 的数据删除。数据删除后不可恢复，请慎重使用。为了确保删除的数据确实是自己要删除的，建议可以先使用 select 语句加 where 后的删除条件查看要删除的数据内容，确认无误后再执行 delete 。
```sql
delete from meters where ts < '2021-10-01 10:40:00.100' ;

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

@ -14,7 +14,7 @@ toc_max_heading_level: 4
taosBenchmark --start-timestamp=1600000000000 --tables=100 --records=10000000 --time-step=10000
```
上面的命令，taosBenchmark 工具在 TDengine 中生成了一个用于测试的数据库，产生共 10 亿条时序数据。时序数据的时间戳从 `1600000000000`（2020-09-13T20:26:40+08:00）开始，包含 `100` 个设备（子表），每个设备有 `10000000` 条数据，时序数据的采集频率是 10 秒/ 条。
上面的命令，taosBenchmark 工具在 TDengine 中生成了一个用于测试的数据库，产生共 10 亿条时序数据。时序数据的时间戳从 `1600000000000`（2020-09-13T20:26:40+08:00）开始，包含 `100` 个设备（子表），每个设备有 `10000000` 条数据，时序数据的采集频率是 10 秒/条。
在 TDengine 中，用户可以通过 WHERE 语句指定条件，查询时序数据。以智能电表的数据为例
@ -74,22 +74,22 @@ GROUP BY groupid;
Query OK, 10 row(s) in set (0.042446s)
```
**注意**: group by 子句在聚合数据时，并不保证结果集按照特定顺序排列。为了获得有序的结果集，可以使用 order by 子句对结果进行排序。这样，可以根据需要调整输出结果的顺序，以满足特定的业务需求或报告要求。
**注意**：group by 子句在聚合数据时，并不保证结果集按照特定顺序排列。为了获得有序的结果集，可以使用 order by 子句对结果进行排序。这样，可以根据需要调整输出结果的顺序，以满足特定的业务需求或报告要求。
TDengine 提供了多种内置的聚合函数。如下表所示：
| 聚合函数 | 功能说明 |
|:----------------------:|:--------------------------------------------------------------:|
|APERCENTILE | 统计表/超级表中指定列的值的近似百分比分位数，与 PERCENTILE 函数相似，但是返回近似结果。 |
|AVG | 统计指定字段的平均值 |
|COUNT | 统计指定字段的记录行数 |
|APERCENTILE | 统计表/超级表中指定列的值的近似百分比分位数，与 PERCENTILE 函数相似，但是返回近似结果。|
|AVG | 统计指定字段的平均值。|
|COUNT | 统计指定字段的记录行数。|
|ELAPSED|elapsed 函数表达了统计周期内连续的时间长度，和 twa 函数配合使用可以计算统计曲线下的面积。在通过 INTERVAL 子句指定窗口的情况下，统计在给定时间范围内的每个窗口内有数据覆盖的时间范围；如果没有 INTERVAL 子句，则返回整个给定时间范围内的有数据覆盖的时间范围。注意，ELAPSED 返回的并不是时间范围的绝对值，而是绝对值除以 time_unit 所得到的单位个数。|
|LEASTSQUARES | 统计表中某列的值的拟合直线方程。start_val 是自变量初始值，step_val 是自变量的步长值。 |
|LEASTSQUARES | 统计表中某列的值的拟合直线方程。start_val 是自变量初始值，step_val 是自变量的步长值。|
|SPREAD | 统计表中某列的最大值和最小值之差。|
|STDDEV | 统计表中某列的均方差。 |
|SUM | 统计表/超级表中某列的和。 |
|HYPERLOGLOG | 采用 hyperloglog 算法，返回某列的基数。该算法在数据量很大的情况下，可以明显降低内存的占用，求出来的基数是个估算值，标准误差（标准误差是多次实验，每次的平均数的标准差，不是与真实结果的误差）为 0.81%。在数据量较少的时候该算法不是很准确，可以使用 select count（data） from （select unique（col） as data from table） 的方法。 |
|HISTOGRAM | 统计数据按照用户指定区间的分布。 |
|STDDEV | 统计表中某列的均方差。|
|SUM | 统计表/超级表中某列的和。|
|HYPERLOGLOG | 采用 hyperloglog 算法，返回某列的基数。该算法在数据量很大的情况下，可以明显降低内存的占用，求出来的基数是个估算值，标准误差（标准误差是多次实验，每次的平均数的标准差，不是与真实结果的误差）为 0.81%。在数据量较少的时候该算法不是很准确，可以使用 select count(data) from (select unique(col) as data from table) 的方法。|
|HISTOGRAM | 统计数据按照用户指定区间的分布。|
|PERCENTILE | 统计表中某列的值百分比分位数。|
## 数据切分查询
@ -101,12 +101,12 @@ PARTITION BY part_list
`part_list` 可以是任意的标量表达式，包括列、常量、标量函数和它们的组合。
TDengine 按如下方式处理数据切分子句。
TDengine 按如下方式处理数据切分子句：
1. 数据切分子句位于 WHERE 子句之后；
2. 数据切分子句将表数据按指定的维度进行切分，每个切分的分片进行指定的计算。计算由之后的子句定义（窗口子句、GROUP BY 子句或 SELECT 子句）；
3. 数据切分子句可以和窗口切分子句（或 GROUP BY 子句）一起使用，此时后面的子句作用在每个切分的分片上。
数据切分的 SQL 如下：s
数据切分的 SQL 如下：
```sql
SELECT location, avg(voltage)
@ -141,6 +141,7 @@ Query OK, 10 row(s) in set (2.415961s)
- 状态窗口（status window）
- 会话窗口（session window）
- 事件窗口（event window）
- 计数窗口（count window）
窗口划分逻辑如下图所示：
@ -152,14 +153,15 @@ Query OK, 10 row(s) in set (2.415961s)
window_clause: {
SESSION(ts_col, tol_val)
| STATE_WINDOW(col)
| INTERVAL(interval_val [, interval_offset]) [SLIDING (sliding_val)] [FILL(fill_mod_and_val)]
| INTERVAL(interval_val [, interval_offset]) [SLIDING (sliding_val)] [WATERMARK(watermark_val)] [FILL(fill_mod_and_val)]
| EVENT_WINDOW START WITH start_trigger_condition END WITH end_trigger_condition
| COUNT_WINDOW(count_val[, sliding_val])
}
```
**注意** 在使用窗口子句时应注意以下规则：
1. 窗口子句位于数据切分子句之后，不可以和 GROUP BY 子句一起使用。
2. 窗口子句将数据按窗口进行切分，对每个窗口进行 SELECT 列表中的表达式的计算，SELECT 列表中的表达式只能包含：常量；伪列：_wstart 伪列、_wend 伪列和 _wduration 伪列；聚合函数（包括选择函数和可以由参数确定输出行数的时序特有函数）
2. 窗口子句将数据按窗口进行切分，对每个窗口进行 SELECT 列表中的表达式的计算，SELECT 列表中的表达式只能包含：常量；伪列：_wstart、_wend 和 _wduration；聚合函数：包括选择函数和可以由参数确定输出行数的时序特有函数。
3. WHERE 语句可以指定查询的起止时间和其他过滤条件。
### 时间戳伪列
@ -177,16 +179,15 @@ INTERVAL(interval_val [, interval_offset])
```
时间窗口子句包括 3 个子句：
- INTERVAL 子句：用于产生相等时间周期的窗口，interval_val 指定每个时间窗口的大小，interval_offset 指定；
- INTERVAL 子句：用于产生相等时间周期的窗口，interval_val 指定每个时间窗口的大小，interval_offset 指定窗口偏移量；
- SLIDING 子句：用于指定窗口向前滑动的时间；
- FILL：用于指定窗口区间数据缺失的情况下，数据的填充模式。
对于时间窗口，interval_val 和 sliding_val 都表示时间段， 语法上支持三种方式。例如：
1. INTERVAL(1s, 500a) SLIDING(1s)，带时间单位的形式，其中的时间单位是单字符表示， 分别为： a （毫秒）， b （纳秒）， d （天）， h （小时）， m （分钟）， n （月）， s （秒）， u （微秒）， w （周）， y （年）；
对于时间窗口，interval_val 和 sliding_val 都表示时间段，语法上支持三种方式。例如：
1. INTERVAL(1s, 500a) SLIDING(1s)，带时间单位的形式，其中的时间单位是单字符表示，分别为：a（毫秒）、b（纳秒），d（天）、h（小时）、m（分钟）、n（月）、s（秒）、u（微秒）、w（周）、y（年）；
2. INTERVAL(1000, 500) SLIDING(1000)，不带时间单位的形式，将使用查询库的时间精度作为默认时间单位，当存在多个库时默认采用精度更高的库；
3. INTERVAL('1s', '500a') SLIDING('1s')，带时间单位的字符串形式，字符串内部不能有任何空格等其它字符。
示例 SQL 如下：
```sql
SELECT tbname, _wstart, _wend, avg(voltage)
@ -220,7 +221,7 @@ Query OK, 12 row(s) in set (0.021265s)
#### 滑动窗口
每次执行的查询是一个时间窗口，时间窗口随着时间流动向前滑动。在定义连续查询的时候需要指定时间窗口（time window ）大小和每次前向增量时间（forward sliding times）。如下图，[t0s， t0e] ，[t1s ， t1e]， [t2s， t2e] 是分别是执行三次连续查询的时间窗口范围，窗口的前向滑动的时间范围 sliding time 标识 。查询过滤、聚合等操作按照每个时间窗口为独立的单位执行。
每次执行的查询是一个时间窗口，时间窗口随着时间流动向前滑动。在定义连续查询的时候需要指定时间窗口（time window ）大小和每次前向增量时间（forward sliding times）。如下图，[t0s, t0e]、[t1s, t1e]、[t2s, t2e] 是分别是执行三次连续查询的时间窗口范围，窗口的前向滑动的时间范围 sliding time 标识。查询过滤、聚合等操作按照每个时间窗口为独立的单位执行。
![时间窗口示意图](./sliding-window.png)
@ -238,7 +239,7 @@ SELECT COUNT(*) FROM temp_tb_1 INTERVAL(1m) SLIDING(2m);
**使用时间窗口需要注意**
1. 聚合时间段的窗口宽度由关键词 INTERVAL 指定，最短时间间隔 10 毫秒（10a）；并且支持偏移 offset（偏移必须小于间隔），也即时间窗口划分与“UTC 时刻 0”相比的偏移量。SLIDING 语句用于指定聚合时间段的前向增量，也即每次窗口向前滑动的时长。
2. 使用 INTERVAL 语句时，除非极特殊的情况，都要求把客户端和服务端的 taos.cfg 配置文件中的 timezone 参数配置为相同的取值，以避免时间处理函数频繁进行跨时区转换而导致的严重性能影响。
2. 使用 INTERVAL 语句时，除非极特殊的情况，都要求把客户端和服务端的 timezone 参数配置为相同的取值，以避免时间处理函数频繁进行跨时区转换而导致的严重性能影响。
3. 返回的结果中时间序列严格单调递增。
示例：
@ -274,7 +275,7 @@ Query OK, 11 row(s) in set (0.013153s)
#### 翻转窗口
当 SLIDING 与 INTERVAL 相等的时候，滑动窗口即为翻转窗口。翻转窗口和滑动窗口的区别在于，滑动窗口因为 interval_val 和 sliding_val 不同，不同时间窗口之间，会存在数据重叠，翻转窗口则没有数据重叠。本质上，翻转窗口就是按照 interval_val 进行了时间窗口划分，INTERVAL(1m)和INTERVAL(1m) SLIDING(1m)是等效的。
当 SLIDING 与 INTERVAL 相等的时候，滑动窗口即为翻转窗口。翻转窗口和滑动窗口的区别在于，滑动窗口因为 interval_val 和 sliding_val 不同，不同时间窗口之间，会存在数据重叠，翻转窗口则没有数据重叠。本质上，翻转窗口就是按照 interval_val 进行了时间窗口划分，INTERVAL(1m) 和 INTERVAL(1m) SLIDING(1m) 是等效的。
示例：
@ -304,7 +305,7 @@ Query OK, 5 row(s) in set (0.016812s)
#### FILL 子句
1. 不进行填充：NONE（默认填充模式）。
2. VALUE 填充：固定值填充，此时需要指定填充的数值。例如：FILL(VALUE, 1.23)。这里需要注意，最终填充的值受由相应列的类型决定，如 FILL(VALUE, 1.23)，相应列为 INT 类型，则填充值为 1, 若查询列表中有多列需要 FILL, 则需要给每一个 FILL 列指定 VALUE, 如 `SELECT _wstart, min(c1), max(c1) FROM ... FILL(VALUE, 0, 0)`, 注意, SELECT 表达式中只有包含普通列时才需要指定 FILL VALUE, 如 `_wstart`, `_wstart+1a`, `now`, `1+1` 以及使用 partition by 时的 partition key (如 tbname)都不需要指定 VALUE, 如 `timediff(last(ts), _wstart)` 则需要指定VALUE。
2. VALUE 填充：固定值填充，此时需要指定填充的数值。例如：FILL(VALUE, 1.23)。这里需要注意，最终填充的值受由相应列的类型决定，如 FILL(VALUE, 1.23)，相应列为 INT 类型，则填充值为 1，若查询列表中有多列需要 FILL，则需要给每一个 FILL 列指定 VALUE，如 `SELECT _wstart, min(c1), max(c1) FROM ... FILL(VALUE, 0, 0)`。注意，SELECT 表达式中只有包含普通列时才需要指定 FILL VALUE，如 `_wstart`、`_wstart+1a`、`now`、`1+1` 以及使用 partition by 时的 partition key (如 tbname)都不需要指定 VALUE,，如 `timediff(last(ts), _wstart)` 则需要指定VALUE。
3. PREV 填充：使用前一个非 NULL 值填充数据。例如：FILL(PREV)。
4. NULL 填充：使用 NULL 填充数据。例如：FILL(NULL)。
5. LINEAR 填充：根据前后距离最近的非 NULL 值做线性插值填充。例如：FILL(LINEAR)。
@ -313,11 +314,11 @@ Query OK, 5 row(s) in set (0.016812s)
以上填充模式中，除了 NONE 模式默认不填充值之外，其他模式在查询的整个时间范围内如果没有数据 FILL 子句将被忽略，即不产生填充数据，查询结果为空。这种行为在部分模式（PREV、NEXT、LINEAR）下具有合理性，因为在这些模式下没有数据意味着无法产生填充数值。
对另外一些模式（NULL、VALUE）来说，理论上是可以产生填充数值的，至于需不需要输出填充数值，取决于应用的需求。所以为了满足这类需要强制填充数据或 NULL 的应用的需求，同时不破坏现有填充模式的行为兼容性，TDengine 还支持两种新的填充模式：
1. NULL_F: 强制填充 NULL 值
2. VALUE_F: 强制填充 VALUE 值
1. NULL_F：强制填充 NULL 值
2. VALUE_F：强制填充 VALUE 值
NULL、 NULL_F、 VALUE、 VALUE_F 这几种填充模式针对不同场景区别如下：
1. INTERVAL 子句： NULL_F， VALUE_F 为强制填充模式；NULL， VALUE 为非强制模式。在这种模式下下各自的语义与名称相符
NULL、NULL_F、VALUE、VALUE_F 这几种填充模式针对不同场景区别如下：
1. INTERVAL 子句：NULL_F、VALUE_F 为强制填充模式；NULL、VALUE 为非强制模式。在这种模式下下各自的语义与名称相符
2. 流计算中的 INTERVAL 子句：NULL_F 与 NULL 行为相同，均为非强制模式；VALUE_F 与 VALUE 行为相同，均为非强制模式。即流计算中的 INTERVAL 没有强制模式
3. INTERP 子句：NULL 与 NULL_F 行为相同，均为强制模式；VALUE 与 VALUE_F 行为相同，均为强制模式。即 INTERP 中没有非强制模式。
@ -405,7 +406,7 @@ 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 秒）。
会话窗口根据记录的时间戳主键的值来确定是否属于同一个会话。如下图所示，如果设置时间戳的连续的间隔小于等于 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)
@ -452,7 +453,7 @@ Query OK, 10 row(s) in set (0.043489s)
事件窗口无法关闭时，不构成一个窗口，不会被输出。即有数据满足 start_trigger_condition，此时窗口打开，但后续数据都不能满足 end_trigger_condition，这个窗口无法被关闭，这部分数据不够成一个窗口，不会被输出。
如果直接在超级表上进行事件窗口查询，TDengine 会将超级表的数据汇总成一条时间线，然后进行事件窗口的计算。 如果需要对子查询的结果集进行事件窗口查询，那么子查询的结果集需要满足按时间线输出的要求，且可以输出有效的时间戳列。
如果直接在超级表上进行事件窗口查询，TDengine 会将超级表的数据汇总成一条时间线，然后进行事件窗口的计算。如果需要对子查询的结果集进行事件窗口查询，那么子查询的结果集需要满足按时间线输出的要求，且可以输出有效的时间戳列。
以下面的 SQL 语句为例，事件窗口切分如下图所示。
@ -474,7 +475,7 @@ EVENT_WINDOW START WITH voltage >= 225 END WITH voltage < 235
LIMIT 5;
```
上面的 SQL，查询超级表meters中，时间戳大于等于2022-01-01T00:00:00+08:00，且时间戳小于2022-01-01T00:10:00+08:00的数据；数据先按照子表名tbname进行数据切分，再根据事件窗口条件：电压大于等于 225V，且小于 235V 进行切分；最后，取每个分片的前 5 行的数据作为结果，返回子表名、窗口开始时间、窗口结束时间、窗口宽度、窗口内数据条数。查询结果如下：
上面的 SQL，查询超级表 meters 中，时间戳大于等于 2022-01-01T00:00:00+08:00，且时间戳小于 2022-01-01T00:10:00+08:00 的数据；数据先按照子表名 tbname 进行数据切分，再根据事件窗口条件：电压大于等于 225V，且小于 235V 进行切分；最后，取每个分片的前 5 行的数据作为结果，返回子表名、窗口开始时间、窗口结束时间、窗口宽度、窗口内数据条数。查询结果如下：
```text
tbname | _wstart | _wend | _wduration | count(*) |
@ -529,25 +530,25 @@ Query OK, 10 row(s) in set (0.062794s)
时序数据特有函数是 TDengine 针对时序数据查询场景专门设计的一组函数。在通用数据库中，要实现类似的功能通常需要编写复杂的查询语句，而且效率较低。为了降低用户的使用成本和简化查询过程，TDengine 将这些功能以内置函数的形式提供，从而实现了高效且易于使用的时序数据处理能力。时序数据特有函数如下表所示。
| 函数 | 功能说明 |
|:---------------:|:--------------------------------------------------------------------:|
|CSUM | 累加和（Cumulative sum），忽略 NULL 值。 |
|DERIVATIVE | 统计表中某列数值的单位变化率。其中单位时间区间的长度可以通过 time_interval 参数指定，最小可以是 1 秒（1s）；ignore_negative 参数的值可以是 0 或 1，为 1 时表示忽略负值。 |
|DIFF | 统计表中某列的值与前一行对应值的差。 ignore_negative 取值为 0|1 ， 可以不填，默认值为 0。 不忽略负值。ignore_negative 为 1 时表示忽略负数。|
|IRATE | 计算瞬时增长率。使用时间区间中最后两个样本数据来计算瞬时增长速率；如果这两个值呈递减关系，那么只取最后一个数用于计算，而不是使用二者差值。 |
|MAVG | 计算连续 k 个值的移动平均数（moving average）。如果输入行数小于 k，则无结果输出。参数 k 的合法输入范围是 1≤ k ≤ 1000。|
|STATECOUNT | 返回满足某个条件的连续记录的个数，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加 1，条件为 false 则重置为 -1，如果数据为 NULL，跳过该条数据。 |
| 函数 | 功能说明 |
|:------------:|:--------------------------------------------------------------------:|
|CSUM | 累加和（Cumulative sum），忽略 NULL 值。|
|DERIVATIVE | 统计表中某列数值的单位变化率。其中单位时间区间的长度可以通过 time_interval 参数指定，最小可以是 1 秒（1s）；ignore_negative 参数的值可以是 0 或 1，为 1 时表示忽略负值。|
|DIFF | 统计表中某列的值与前一行对应值的差。ignore_negative 取值为 0|1 ，可以不填，默认值为 0。不忽略负值。ignore_negative 为 1 时表示忽略负数。|
|IRATE | 计算瞬时增长率。使用时间区间中最后两个样本数据来计算瞬时增长速率；如果这两个值呈递减关系，那么只取最后一个数用于计算，而不是使用二者差值。|
|MAVG | 计算连续 k 个值的移动平均数（moving average）。如果输入行数小于 k，则无结果输出。参数 k 的合法输入范围是 1≤ k ≤ 1000。|
|STATECOUNT | 返回满足某个条件的连续记录的个数，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加 1，条件为 false 则重置为 -1，如果数据为 NULL，跳过该条数据。|
|STATEDURATION | 返回满足某个条件的连续记录的时间长度，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加上两个记录之间的时间长度（第一个满足条件的记录时间长度记为 0），条件为 false 则重置为 -1，如果数据为 NULL，跳过该条数据|
|TWA | 时间加权平均函数。统计表中某列在一段时间内的时间加权平均。 |
|TWA | 时间加权平均函数。统计表中某列在一段时间内的时间加权平均。|
## 嵌套查询
嵌套查询，也称为 subquery（子查询），是指在一个 SQL 中，内层查询的计算结果可以作为外层查询的计算对象来使用。TDengine 支持在 from 子句中使用非关联 subquery。非关联是指 subquery 不会用到父查询中的参数。在 select 查询的 from 子句之后，可以接一个独立的 select 语句，这个 select 语句被包含在英文圆括号内。通过使用嵌套查询，你可以在一个查询中引用另一个查询的结果，从而实现更复杂的数据处理和分析。以智能电表为例进行说明，SQL 如下
```sql
SELECT max(voltage),*
SELECT max(voltage), *
FROM (
SELECT tbname,last_row(ts),voltage,current,phase,groupid,location
SELECT tbname, last_row(ts), voltage, current, phase, groupid, location
FROM meters
PARTITION BY tbname
)
@ -559,12 +560,12 @@ GROUP BY groupid;
TDengine 的嵌套查询遵循以下规则：
1. 内层查询的返回结果将作为“虚拟表”供外层查询使用，此虚拟表建议起别名，以便于外层查询中方便引用。
2. 外层查询支持直接通过列名或列名的形式引用内层查询的列或伪列。
3. 在内层和外层查询中，都支持普通的表间/超级表间 JOIN。内层查询的计算结果也可以再参与数据子表的 JOIN 操作。
3. 在内层和外层查询中，都支持普通表间/超级表间 JOIN。内层查询的计算结果也可以再参与数据子表的 JOIN 操作。
4. 内层查询支持的功能特性与非嵌套的查询语句能力是一致的。内层查询的 ORDER BY 子句一般没有意义，建议避免这样的写法以免无谓的资源消耗。
5. 与非嵌套的查询语句相比，外层查询所能支持的功能特性存在如下限制：
6. 如果内层查询的结果数据未提供时间戳，那么计算过程隐式依赖时间戳的函数在外层会无法正常工作。例如：INTERP， DERIVATIVE， IRATE， LAST_ROW， FIRST， LAST， TWA， STATEDURATION， TAIL， UNIQUE。
7. 如果内层查询的结果数据不是按时间戳有序，那么计算过程依赖数据按时间有序的函数在外层会无法正常工作。例如：LEASTSQUARES， ELAPSED， INTERP， DERIVATIVE， IRATE， TWA， DIFF， STATECOUNT， STATEDURATION， CSUM， MAVG， TAIL， UNIQUE。
8. 计算过程需要两遍扫描的函数，在外层查询中无法正常工作。例如：此类函数包括：PERCENTILE。
6. 如果内层查询的结果数据未提供时间戳，那么计算过程隐式依赖时间戳的函数在外层会无法正常工作。例如：INTERP、DERIVATIVE、IRATE、LAST_ROW、FIRST、LAST、TWA、STATEDURATION、TAIL、UNIQUE。
7. 如果内层查询的结果数据不是按时间戳有序，那么计算过程依赖数据按时间有序的函数在外层会无法正常工作。例如：LEASTSQUARES、ELAPSED、INTERP、DERIVATIVE、IRATE、TWA、DIFF、STATECOUNT、STATEDURATION、CSUM、MAVG、TAIL、UNIQUE。
8. 计算过程需要两遍扫描的函数，在外层查询中无法正常工作。例如：PERCENTILE。
## UNION 子句
@ -573,11 +574,11 @@ TDengine 支持 UNION 操作符。也就是说，如果多个 SELECT 子句返
示例：
```sql
(SELECT tbname,* FROM d1 limit 1)
(SELECT tbname, * FROM d1 limit 1)
UNION ALL
(SELECT tbname,* FROM d11 limit 2)
(SELECT tbname, * FROM d11 limit 2)
UNION ALL
(SELECT tbname,* FROM d21 limit 3);
(SELECT tbname, * FROM d21 limit 3);
```
上面的 SQL，分别查询：子表 d1 的 1 条数据，子表 d11 的 2 条数据，子表 d21 的 3 条数据，并将结果合并。返回的结果如下：
@ -594,7 +595,7 @@ UNION ALL
Query OK, 6 row(s) in set (0.006438s)
```
在同一个 sql 语句中，最多支持 100 个 UNION 子句。
在同一个 SQL 语句中，最多支持 100 个 UNION 子句。
## 关联查询
@ -640,9 +641,9 @@ select a.* from meters a left asof join meters b on timetruncate(a.ts, 1s) < tim
### 语法说明
在接下来的内容中，我们将通过统一的方式并行介绍 Left Join 和 Right Join 系列。因此，在后续关于 Outer、Semi、Anti-Semi、ASOF、Window 等系列内容的介绍中，我们采用了“ Left/Right”这种表述方式来同时涵盖 Left Join 和 Right Join 的相关知识。这里的“ /”符号前的描述专指应用于 Left Join，而“ /”符号后的描述则专指应用于 Right Join。通过这种表述方式，我们可以更加清晰地展示这两种 Join 操作的特点和用法。
在接下来的内容中，我们将通过统一的方式并行介绍 Left Join 和 Right Join 系列。因此，在后续关于 Outer、Semi、Anti-Semi、ASOF、Window 等系列内容的介绍中，我们采用了“Left/Right”这种表述方式来同时涵盖 Left Join 和 Right Join 的相关知识。这里的“/”符号前的描述专指应用于 Left Join，而“/”符号后的描述则专指应用于 Right Join。通过这种表述方式，我们可以更加清晰地展示这两种 Join 操作的特点和用法。
例如，当我们提及“左 / 右表”时，对于 Left Join，它特指左表，而对于 Right Join，它则特指右表。同理，当我们提及“右 / 左表”时，对于 Left Join，它特指右表，而对于 Right Join，它则特指左表。
例如，当我们提及“左/右表”时，对于 Left Join，它特指左表，而对于 Right Join，它则特指右表。同理，当我们提及“右/左表”时，对于 Left Join，它特指右表，而对于 Right Join，它则特指左表。
### Join 功能
@ -650,13 +651,13 @@ select a.* from meters a left asof join meters b on timetruncate(a.ts, 1s) < tim
| Join 类型 | 定义 |
|:------------------------:|:--------------------------------------------------------:|
|Inner Join | 内连接，只有左右表中同时符合连接条件的数据才会被返回，可以视为两张表符合连接条件的数据的交集 |
|Left/Right Outer Join | 左 / 右（外）连接，既包含左右表中同时符合连接条件的数据集合，也包括左 / 右表中不符合连接条件的数据集合 |
|Left/Right Semi Join | 左 / 右半连接，通常表达的是 in、exists 的含义，即对左 / 右表任意一条数据来说，只有当右 / 左表中存在任一符合连接条件的数据时才返回左 / 右表行数据 |
|Inner Join | 内连接，只有左右表中同时符合连接条件的数据才会被返回，可以视为两张表符合连接条件的数据的交集 |
|Left/Right Outer Join | 左 / 右（外）连接，既包含左右表中同时符合连接条件的数据集合，也包括左 / 右表中不符合连接条件的数据集合 |
|Left/Right Semi Join | 左 / 右半连接，通常表达的是 in、exists 的含义，即对左 / 右表任意一条数据来说，只有当右 / 左表中存在任一符合连接条件的数据时才返回左 / 右表行数据 |
|Left/Right Anti-Semi Join | 左 / 右反连接，同左 / 右半连接的逻辑正好相反，通常表达的是 not in、not exists 的含义，即对左 / 右表任意一条数据来说，只有当右 / 左表中不存在任何符合连接条件的数据时才返回左 / 右表行数据 |
|left/Right ASOF Join | 左 / 右不完全匹配连接，不同于其他传统 Join 操作的完全匹配模式，ASOF Join 允许以指定的匹配模式进行不完全匹配，即按照主键时间戳最接近的方式进行匹配 |
|Left/Right Window Join | 左 / 右窗口连接，根据左 / 右表中每一行的主键时间戳和窗口边界构造窗口并据此进行窗口连接，支持在窗口内进行投影、标量和聚合操作 |
|Full Outer Join | 全（外）连接，既包含左右表中同时符合连接条件的数据集合，也包括左右表中不符合连接条件的数据集合 |
|left/Right ASOF Join | 左 / 右不完全匹配连接，不同于其他传统 Join 操作的完全匹配模式，ASOF Join 允许以指定的匹配模式进行不完全匹配，即按照主键时间戳最接近的方式进行匹配 |
|Left/Right Window Join | 左 / 右窗口连接，根据左 / 右表中每一行的主键时间戳和窗口边界构造窗口并据此进行窗口连接，支持在窗口内进行投影、标量和聚合操作 |
|Full Outer Join | 全（外）连接，既包含左右表中同时符合连接条件的数据集合，也包括左右表中不符合连接条件的数据集合 |
### 约束和限制

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

@ -12,7 +12,7 @@ toc_max_heading_level: 4
为实现上述功能，TDengine 会为预写数据日志（Write-Ahead Logging，WAL）文件自动创建索引，以支持快速随机访问，并提供了灵活可配置的文件切换与保留机制。用户可以根据需求指定 WAL 文件的保留时间和大小。通过这些方法，WAL 被改造成一个保留事件到达顺序的、可持久化的存储引擎。对于以主题形式创建的查询，TDengine 将从 WAL 读取数据。在消费过程中，TDengine 根据当前消费进度从 WAL 直接读取数据，并使用统一的查询引擎实现过滤、变换等操作，然后将数据推送给消费者。
从 3.2.0.0 版本开始，数据订阅支持 vnode 迁移和分裂。 由于数据订阅依赖 wal文件，而在 vnode 迁移和分裂的过程中，wal 并不会同步过去，所以迁移或分裂后，之前没消费完的 wal数据后消费不到。所以请保证之前把数据全部消费完后，再进行 vnode 迁移或分裂，否则，消费会丢失数据。
从 3.2.0.0 版本开始，数据订阅支持 vnode 迁移和分裂。由于数据订阅依赖 wal 文件，而在 vnode 迁移和分裂的过程中，wal 文件并不会进行同步。因此，在迁移或分裂操作完成后，您将无法继续消费之前尚未消费完 wal 数据。请务必在执行 vnode 迁移或分裂之前，将所有 wal 数据消费完毕。
## 主题类型
@ -31,7 +31,7 @@ CREATE TOPIC [IF NOT EXISTS] topic_name as subquery
3. 若发生表结构变更，新增的列不出现在结果中。
4. 对于 select *，则订阅展开为创建时所有的列（子表、普通表为数据列，超级表为数据列加标签列）
假设需要订阅所有智能电表中电压值大于 200 的数据，而且仅仅返回时间戳、电流、电压 3 个采集量（不返回相位），那么可以通过下面的 SQL 创建 power_topic 这个主题。
假设需要订阅所有智能电表中电压值大于 200 的数据，且仅仅返回时间戳、电流、电压 3 个采集量（不返回相位），那么可以通过下面的 SQL 创建 power_topic 这个主题。
```sql
CREATE TOPIC power_topic AS SELECT ts, current, voltage FROM power.meters WHERE voltage > 200;
```
@ -45,21 +45,21 @@ CREATE TOPIC [IF NOT EXISTS] topic_name [with meta] AS STABLE stb_name [where_co
与使用 `SELECT * from stbName` 订阅的区别是：
1. 不会限制用户的表结构变更，即表结构变更以及变更后的新数据都能够订阅到
1. 不会限制用户的表结构变更，即表结构变更以及变更后的新数据都能够订阅到。
2. 返回的是非结构化的数据，返回数据的结构会随着超级表的表结构变化而变化。
3. with meta 参数可选，选择时将返回创建超级表，子表等语句，主要用于 taosx 做超级表迁移。
4. where_condition 参数可选，选择时将用来过滤符合条件的子表，订阅这些子表。where 条件里不能有普通列，只能是 tag 或 tbname，where 条件里可以用函数，用来过滤 tag，但是不能是聚合函数，因为子表 tag 值无法做聚合。也可以是常量表达式，比如 2 > 1（订阅全部子表），或者 false（订阅 0 个子表）。
3. with meta 参数可选，选择时将返回创建超级表，子表等语句，主要用于 taosX 做超级表迁移。
4. where_condition 参数可选，选择时将用来过滤符合条件的子表，订阅这些子表。where 条件里不能有普通列，只能是 tag 或 tbname，where 条件里可以用函数，用来过滤 tag，但是不能是聚合函数，因为子表 tag 值无法做聚合。可以是常量表达式，比如 2 > 1（订阅全部子表），或者 false（订阅 0 个子表）。
5. 返回数据不包含标签。
### 数据库主题
订阅一个数据库里所有数据，其语法如下
订阅一个数据库里所有数据，其语法如下：
```sql
CREATE TOPIC [IF NOT EXISTS] topic_name [with meta] AS DATABASE db_name;
```
通过该语句可创建一个包含数据库所有表数据的订阅
1. with meta 参数可选，选择时将返回数据库里所有超级表，子表、普通表的元数据创建、删除、修改语句，主要用于 taosx 做数据库迁移。
通过该语句可创建一个包含数据库所有表数据的订阅：
1. with meta 参数可选，选择时将返回数据库里所有超级表，子表、普通表的元数据创建、删除、修改语句，主要用于 taosX 做数据库迁移。
2. 超级表订阅和库订阅属于高级订阅模式，容易出错，如确实要使用，请咨询技术支持人员。
## 删除主题
@ -128,7 +128,7 @@ TDengine 的数据订阅功能支持回放（replay）功能，允许用户按
2023/09/22 00:00:08.000
```
使用数据订阅的回放功能时需要注意如下几项。
使用数据订阅的回放功能时需要注意如下几项：
- 数据订阅的回放功能仅查询订阅支持数据回放，超级表和库订阅不支持回放。
- 回放不支持进度保存。
- 因为数据回放本身需要处理时间，所以回放的精度存在几十毫秒的误差。

18
docs/zh/06-advanced/02-cache.md
View File

@ -29,14 +29,14 @@ TDengine 采用时间驱动的缓存管理策略，将最新数据优先存储
## TDengine 的读缓存配置
在创建数据库时，用户可以选择是否启用缓存机制以存储该数据库中每张子表的最新数据。这一缓存机制由数据库创建参数 cachemodel 进行控制。参数 cachemodel 具有如 下 4 种情况：
在创建数据库时，用户可以选择是否启用缓存机制以存储该数据库中每张子表的最新数据。这一缓存机制由数据库创建参数 cachemodel 进行控制。参数 cachemodel 具有如下 4 种情况：
- none：不缓存
- last_row：缓存子表最近一行数据，这将显著改善 last_row 函数的性能
- last_value：缓存子表每一列最近的非 NULL 值，这将显著改善无特殊影响（比如 WHERE,ORDER BY,GROUP BY, INTERVAL）时的 last 函数的性能
- last_value：缓存子表每一列最近的非 NULL 值，这将显著改善无特殊影响（比如 WHERE、ORDER BY、GROUP BY、INTERVAL）时的 last 函数的性能
- both：同时缓存最近的行和列，即等同于上述 cachemodel 值为 last_row 和 last_value 的行为同时生效
当使用数据库读缓存时，可以使用参数 cachesize 来配置每个 vnode 的内存大小。
- cachesize：表示每个 vnode 中用于缓存子表最近数据的内存大小。默认为 1 ，范围是[1，65536]，单位是 MB。需要根据机器内存合理配置。
- cachesize：表示每个 vnode 中用于缓存子表最近数据的内存大小。默认为 1，范围是 [1，65536]，单位是 MB。需要根据机器内存合理配置。
关于数据库的具体创建，相关参数和操作说明请参考[创建数据库](../../reference/taos-sql/database/)
@ -48,25 +48,25 @@ TDengine 采用时间驱动的缓存管理策略，将最新数据优先存储
# taosBenchmark -d power -Q --start-timestamp=1600000000000 --tables=10000 --records=10000 --time-step=10000 -y
```
上面的命令，taosBenchmark 工具在 TDengine 中生成了一个用于测试的 电表数据库 power，产生共 10 亿条时序数据。时序数据的时间戳从 `1600000000000（2020-09-13T20:26:40+08:00）`开始，超级表为 `meter`s，包含 10000 个设备（子表），每个设备有 10000 条数据，时序数据的采集频率是 10 秒/ 条。
上面的命令，taosBenchmark 工具在 TDengine 中生成了一个用于测试的 电表数据库 power，产生共 10 亿条时序数据。时序数据的时间戳从 `1600000000000（2020-09-13T20:26:40+08:00）` 开始，超级表为 `meters`，包含 10000 个设备（子表），每个设备有 10000 条数据，时序数据的采集频率是 10 秒/条。
查询任意一个电表的最新的电流和时间戳数据，执行如下 SQL
```sql
taos> select last(ts,current) from meters;
taos> select last(ts, current) from meters;
last(ts) | last(current) |
=================================================
2020-09-15 00:13:10.000 | 1.1294620 |
Query OK, 1 row(s) in set (0.353815s)
taos> select last_row(ts,current) from meters;
taos> select last_row(ts, current) from meters;
last_row(ts) | last_row(current) |
=================================================
2020-09-15 00:13:10.000 | 1.1294620 |
Query OK, 1 row(s) in set (0.344070s)
```
希望使用缓存来查询任意一个电表的最新时间戳数据，执行如下 SQL ，并检查数据库的缓存生效。
希望使用缓存来查询任意一个电表的最新时间戳数据，执行如下 SQL，并检查数据库的缓存生效。
```sql
taos> alter database power cachemodel 'both' ;
@ -82,13 +82,13 @@ Query OK, 1 row(s) in set (0.000282s)
再次查询电表的最新的实时数据，第一次查询会做缓存计算，后续的查询时延就大大缩减。
```sql
taos> select last(ts,current) from meters;
taos> select last(ts, current) from meters;
last(ts) | last(current) |
=================================================
2020-09-15 00:13:10.000 | 1.1294620 |
Query OK, 1 row(s) in set (0.044021s)
taos> select last_row(ts,current) from meters;
taos> select last_row(ts, current) from meters;
last_row(ts) | last_row(current) |
=================================================
2020-09-15 00:13:10.000 | 1.1294620 |

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

@ -60,20 +60,20 @@ subquery 支持会话窗口、状态窗口、时间窗口、事件窗口与计
3. INTERVAL 是时间窗口，又可分为滑动时间窗口和翻转时间窗口。INTERVAL 子句用于指定窗口相等时间周期，SLIDING 字句用于指定窗口向前滑动的时间。当 interval_val 与 sliding_val 相等的时候，时间窗口即为翻转时间窗口，否则为滑动时间窗口，注意：sliding_val 必须小于等于 interval_val。
4. EVENT_WINDOW 是事件窗口，根据开始条件和结束条件来划定窗口。当 start_trigger_condition 满足时则窗口开始，直到 end_trigger_condition 满足时窗口关闭。 start_trigger_condition 和 end_trigger_condition 可以是任意 TDengine 支持的条件表达式，且可以包含不同的列。
4. EVENT_WINDOW 是事件窗口，根据开始条件和结束条件来划定窗口。当 start_trigger_condition 满足时则窗口开始，直到 end_trigger_condition 满足时窗口关闭。start_trigger_condition 和 end_trigger_condition 可以是任意 TDengine 支持的条件表达式，且可以包含不同的列。
5. COUNT_WINDOW 是计数窗口，按固定的数据行数来划分窗口。 count_val 是常量，是正整数，必须大于等于 2，小于 2147483648。 count_val 表示每个 COUNT_WINDOW 包含的最大数据行数，总数据行数不能整除 count_val 时，最后一个窗口的行数会小于 count_val 。 sliding_val 是常量，表示窗口滑动的数量，类似于 INTERVAL 的 SLIDING 。
5. COUNT_WINDOW 是计数窗口，按固定的数据行数来划分窗口。count_val 是常量，是正整数，必须大于等于 2，小于 2147483648。count_val 表示每个 COUNT_WINDOW 包含的最大数据行数，总数据行数不能整除 count_val 时，最后一个窗口的行数会小于 count_val。sliding_val 是常量，表示窗口滑动的数量，类似于 INTERVAL 的 SLIDING 。
窗口的定义与时序数据窗口查询中的定义完全相同，具体可参考 TDengine 窗口函数部分。
如下 SQL 将创建一个流计算，执行后 TDengine 会自动创建名为avg_vol 的超级表，此流计算以 1min 为时间窗口、30s 为前向增量统计这些智能电表的平均电压，并将来自 meters 的数据的计算结果写入 avg_vol，不同分区的数据会分别创建子表并写入不同子表。
如下 SQL 将创建一个流计算，执行后 TDengine 会自动创建名为 avg_vol 的超级表，此流计算以 1min 为时间窗口、30s 为前向增量统计这些智能电表的平均电压，并将来自 meters 的数据的计算结果写入 avg_vol，不同分区的数据会分别创建子表并写入不同子表。
```sql
CREATE STREAM avg_vol_s INTO avg_vol AS
SELECT _wstart, count(*), avg(voltage) FROM power.meters PARTITION BY tbname INTERVAL(1m) SLIDING(30s);
```
本节涉及的相关参数的说明如下。
- stb_name 是保存计算结果的超级表的表名，如果该超级表不存在，则会自动创建；如果已存在，则检查列的 schema 信息。详见 6.3.8 节。
- stb_name 是保存计算结果的超级表的表名，如果该超级表不存在，则会自动创建；如果已存在，则检查列的 schema 信息。
- tags 子句定义了流计算中创建标签的规则。通过 tags 字段可以为每个分区对应的子表生成自定义的标签值。
## 流式计算的规则和策略

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

@ -3,6 +3,9 @@ title: 预测算法
description: 预测算法
---
import fc_result from '../pic/fc.png';
import fc_result_figure from '../pic/fc-result.png';
时序数据预测处理以持续一个时间段的时序数据作为输入，预测接下来一个连续时间区间内时间序列数据趋势。用户可以指定输出的（预测）时间序列数据点的数量，因此其输出的结果行数不确定。为此，TDengine 使用新 SQL 函数 `FORECAST` 提供时序数据预测服务。基础数据（用于预测的历史时间序列数据）是该函数的输入，预测结果是该函数的输出。用户可以通过 `FORECAST` 函数调用 Anode 提供的预测算法提供的服务。
在后续章节中，使用时序数据表`foo`作为示例，介绍预测和异常检测算法的使用方式，`foo` 表的模式如下：
@ -106,3 +109,37 @@ taos> select _flow, _fhigh, _frowts, forecast(i32) from foo;
- PatchTST (Patch Time Series Transformer)
- Temporal Fusion Transformer
- TimesNet
## 算法有效性评估工具
TDgpt 提供预测分析算法有效性评估工具 `analytics_compare`，调用该工具并设置合适的参数，能够使用 TDengine 中的数据作为回测依据，评估不同预测算法或相同的预测算法在不同的参数或训练模型的下的预测有效性。预测有效性的评估使用 `MSE` 和 `MAE` 指标作为依据，后续还将增加 `MAPE`指标。
```ini
[forecast]
# 训练数据的周期，每个周期包含多少个输入点
period = 10
# 使用范围内最后 10 条记录作为预测结果
rows = 10
# 训练数据开始时间
start_time = 1949-01-01T00:00:00
# 训练数据结束时间
end_time = 1960-12-01T00:00:00
# 输出结果的起始时间
res_start_time = 1730000000000
# 是否绘制预测结果图
gen_figure = true
```
算法对比分析运行完成以后，生成 fc-results.xlsx 文件，其中包含了调用算法的预测分析误差、执行时间、调用参数等信息。如下图所示：
<img src={fc_result} width="760" alt="预测对比结果" />
如果设置了 `gen_figure` 为 true，分析结果中还会有绘制的分析预测结果图（如下图所示）。
<img src={fc_result_figure} width="540" alt="预测对比结果" />

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

@ -4,6 +4,8 @@ description: 异常检测算法
---
import ad from '../pic/anomaly-detection.png';
import ad_result from '../pic/ad-result.png';
import ad_result_figure from '../pic/ad-result-figure.png';
TDengine 中定义了异常（状态）窗口来提供异常检测服务。异常窗口可以视为一种特殊的**事件窗口（Event Window）**，即异常检测算法确定的连续异常时间序列数据所在的时间窗口。与普通事件窗口区别在于——时间窗口的起始时间和结束时间均是分析算法识别确定，不是用户给定的表达式进行判定。因此，在 `WHERE` 子句中使用 `ANOMALY_WINDOW` 关键词即可调用时序数据异常检测服务，同时窗口伪列（`_WSTART`, `_WEND`, `_WDURATION`）也能够像其他时间窗口一样用于描述异常窗口的起始时间(`_WSTART`)、结束时间(`_WEND`)、持续时间(`_WDURATION`)。例如：
@ -67,3 +69,38 @@ Query OK, 1 row(s) in set (0.028946s)
### 内置异常检测算法
分析平台内置了6个异常检查模型，分为3个类别，分别是[基于统计学的算法](./02-statistics-approach.md)、[基于数据密度的算法](./03-data-density.md)、以及[基于机器学习的算法](./04-machine-learning.md)。在不指定异常检测使用的方法的情况下，默认调用 IQR 进行异常检测。
### 异常检测算法有效性比较工具
TDgpt 提供自动化的工具对比不同数据集的不同算法监测有效性，针对异常检测算法提供查全率（recall）和查准率（precision）两个指标衡量不同算法的有效性。
通过在配置文件中(analysis.ini)设置以下的选项可以调用需要使用的异常检测算法，异常检测算法测试用数据的时间范围、是否生成标注结果的图片、调用的异常检测算法以及相应的参数。
调用异常检测算法比较之前，需要人工手动标注异常监测数据集的结果，即设置[anno_res]选项的数值，第几个数值是异常点，需要标注在数组中，如下测试集中，第 9 个点是异常点，我们就标注异常结果为 [9].
```bash
[ad]
# training data start time
start_time = 2021-01-01T01:01:01
# training data end time
end_time = 2021-01-01T01:01:11
# draw the results or not
gen_figure = true
# annotate the anomaly_detection result
anno_res = [9]
# algorithms list that is involved in the comparion
[ad.algos]
ksigma={"k": 2}
iqr={}
grubbs={}
lof={"algo":"auto", "n_neighbor": 3}
```
对比程序执行完成以后，会自动生成名称为`ad_result.xlsx` 的文件，第一个卡片是算法运行结果（如下图所示），分别包含了算法名称、执行调用参数、查全率、查准率、执行时间 5 个指标。
<img src={ad_result} width="760" alt="异常检测对比结果" />
如果设置了 `gen_figure` 为 `true`，比较程序会自动将每个参与比较的算法分析结果采用图片方式呈现出来（如下图所示为 ksigma 的异常检测结果标注）。
<img src={ad_result_figure} width="540" alt="异常检测标注图" />

2
docs/zh/06-advanced/06-TDgpt/06-dev/03-ad.md
View File

@ -47,7 +47,7 @@ class _MyAnomalyDetectionService(AbstractAnomalyDetectionService):
return super().set_params(params)
```
将该文件保存在 `./lib/taosanalytics/algo/ad/` 目录下，然后重启 taosanode 服务。在 TDengine 命令行接口 taos 中执行 `SHOW ANODES FULL` 就能够看到新加入的算法，然后就可以通过 SQL 语句调用该算法。
将该文件保存在 `./lib/taosanalytics/algo/ad/` 目录下，然后重启 taosanode 服务。在 TDengine CLI 中执行 `SHOW ANODES FULL` 就能够看到新加入的算法，然后就可以通过 SQL 语句调用该算法。
```SQL
--- 对 col 列进行异常检测，通过指定 algo 参数为 myad 来调用新添加的异常检测类

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 61 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

4
docs/zh/07-develop/01-connect/index.md
View File

@ -20,7 +20,7 @@ import VerifyLinux from "../../14-reference/05-connector/_verify_linux.mdx";
import VerifyMacOS from "../../14-reference/05-connector/_verify_macos.mdx";
import VerifyWindows from "../../14-reference/05-connector/_verify_windows.mdx";
TDengine 提供了丰富的应用程序开发接口，为了便于用户快速开发自己的应用，TDengine 支持了多种编程语言的连接器，其中官方连接器包括支持 C/C++、Java、Python、Go、Node.js、C#、Rust、Lua（社区贡献）和 PHP （社区贡献）的连接器。这些连接器支持使用原生接口（taosc）和 REST 接口（部分语言暂不支持）连接 TDengine 集群。社区开发者也贡献了多个非官方连接器，例如 ADO.NET 连接器、Lua 连接器和 PHP 连接器。另外 TDengine 还可以直接调用 taosadapter 提供的 REST API 接口，进行数据写入和查询操作。
TDengine 提供了丰富的应用程序开发接口，为了便于用户快速开发自己的应用，TDengine 支持了多种编程语言的连接器，其中官方连接器包括支持 C/C++、Java、Python、Go、Node.js、C#、Rust、Lua（社区贡献）和 PHP （社区贡献）的连接器。这些连接器支持使用原生接口（taosc）和 REST 接口（部分语言暂不支持）连接 TDengine 集群。社区开发者也贡献了多个非官方连接器，例如 ADO.NET 连接器、Lua 连接器和 PHP 连接器。另外 TDengine 还可以直接调用 taosAdapter 提供的 REST API 接口，进行数据写入和查询操作。
## 连接方式
@ -33,7 +33,7 @@ TDengine 提供了丰富的应用程序开发接口，为了便于用户快速
![TDengine connection type](connection-type-zh.webp)
无论使用何种方式建立连接，连接器都提供了相同或相似的 API 操作数据库，都可以执行 SQL 语句，只是初始化连接的方式稍有不同，用户在使用上不会感到什么差别。
各种连接方式和各语言连接器支持情况请参考：[连接器功能特性](../../reference/connector/#功能特性)
各种连接方式和各语言连接器支持情况请参考 [连接器功能特性](../../reference/connector/#功能特性)
关键不同点在于：

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

@ -299,7 +299,7 @@ writer.write(lineDemo, SchemalessProtocolType.LINE, SchemalessTimestampType.NANO
## 查询写入的数据
运行上节的样例代码，会在 power 数据库中自动建表，我们可以通过 taos shell 或者应用程序来查询数据。下面给出用 taos shell 查询超级表和 meters 表数据的样例。
运行上节的样例代码，会在 power 数据库l中自动建表，我们可以通过 TDengine CLI 或者应用程序来查询数据。下面给出用 TDengine CLI 查询超级表和 meters 表数据的样例。
```shell
taos> show power.stables;

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

@ -10,7 +10,7 @@ import TabItem from "@theme/TabItem";
TDengine 提供了类似于消息队列产品的数据订阅和消费接口。在许多场景中，采用 TDengine 的时序大数据平台，无须再集成消息队列产品，从而简化应用程序设计并降低运维成本。本章介绍各语言连接器数据订阅的相关 API 以及使用方法。 数据订阅的基础知识请参考 [数据订阅](../../advanced/subscription/)
## 创建主题
请用 taos shell 或者 参考 [执行 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` 所选择的列组成。
@ -39,10 +39,13 @@ TDengine 消费者的概念跟 Kafka 类似，消费者通过订阅主题来接
| `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） | 默认关闭 |
| `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] |
| `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 为 起效 |
下面是各语言连接器创建参数：

8
docs/zh/07-develop/index.md
View File

@ -5,19 +5,19 @@ description: 让开发者能够快速上手的指南
开发一个应用，如果你准备采用 TDengine 作为时序数据处理的工具，那么有如下几个事情要做：
1. 确定应用到 TDengine 的连接方式。无论你使用何种编程语言，你总是可以使用 REST 接口, 但也可以使用每种编程语言独有的连接器进行方便的连接。
1. 确定应用到 TDengine 的连接方式。无论你使用何种编程语言，你总是可以使用 REST 接口，但也可以使用每种编程语言独有的连接器进行方便的连接。
2. 根据自己的应用场景，确定数据模型。根据数据特征，决定建立一个还是多个库；分清静态标签、采集量，建立正确的超级表，建立子表。
3. 决定插入数据的方式。TDengine 支持使用标准的 SQL 写入，但同时也支持 Schemaless 模式写入，这样不用手工建表，可以将数据直接写入。
4. 根据业务要求，看需要撰写哪些 SQL 查询语句。
5. 如果你要基于时序数据做轻量级的实时统计分析，包括各种监测看板，那么建议你采用 TDengine 3.0 的流式计算功能，而不用额外部署 Spark, Flink 等复杂的流式计算系统。
5. 如果你要基于时序数据做轻量级的实时统计分析，包括各种监测看板，那么建议你采用 TDengine 3.0 的流式计算功能，而不用额外部署 Spark、Flink 等复杂的流式计算系统。
6. 如果你的应用有模块需要消费插入的数据，希望有新的数据插入时，就能获取通知，那么建议你采用 TDengine 提供的数据订阅功能，而无需专门部署 Kafka 或其他消息队列软件。
7. 在很多场景下（如车辆管理），应用需要获取每个数据采集点的最新状态，那么建议你采用 TDengine 的 Cache 功能，而不用单独部署 Redis 等缓存软件。
8. 如果你发现 TDengine 的函数无法满足你的要求，那么你可以使用用户自定义函数（UDF）来解决问题。
本部分内容就是按照上述顺序组织的。为便于理解，TDengine 为每个功能和每个支持的编程语言都提供了示例代码，位于 [示例代码](https://github.com/taosdata/TDengine/tree/main/docs/examples)。所有示例代码都会有 CI 保证正确性，脚本位于 [示例代码 CI](https://github.com/taosdata/TDengine/tree/main/tests/docs-examples-test)。
如果你希望深入了解 SQL 的使用，需要查看[SQL 手册](../reference/taos-sql/)。如果想更深入地了解各连接器的使用，请阅读[连接器参考指南](../reference/connector/)。如果还希望想将 TDengine 与第三方系统集成起来，比如 Grafana, 请参考[第三方工具](../third-party/)。
如果你希望深入了解 SQL 的使用，需要查看 [SQL 手册](../reference/taos-sql/)。如果想更深入地了解各连接器的使用，请阅读 [连接器参考指南](../reference/connector/)。如果还希望想将 TDengine 与第三方系统集成起来，比如 Grafana，请参考 [第三方工具](../third-party/)。
如果在开发过程中遇到任何问题，请点击每个页面下方的["反馈问题"](https://github.com/taosdata/TDengine/issues/new/choose), 在 GitHub 上直接递交 Issue。
如果在开发过程中遇到任何问题，请点击每个页面下方的 [反馈问题](https://github.com/taosdata/TDengine/issues/new/choose)，在 GitHub 上直接递交 Issue。
```mdx-code-block
import DocCardList from '@theme/DocCardList';

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

@ -87,7 +87,7 @@ RawDataSize = numOfTables × rowSizePerTable × rowsPerTable
**技巧** 如何估算 TDengine 压缩率
```text
用户可以利用性能测试工具 taosBenchmark 来评估 TDengine 的数据压缩效果。通过使用 -f 选项指定写入配置文件，taosBenchmark 可以将指定数量的 CSV 样例数据写入指定的库参数和表结构中。
在完成数据写入后，用户可以在 taos shell 中执行 flush database 命令，将所有数据强制写入硬盘。接着，通过 Linux 操作系统的 du 命令获取指定 vnode 的数据文件夹大小。最后，将原始数据大小除以实际存储的数据大小，即可计算出真实的压缩率。
在完成数据写入后，用户可以在 TDengine CLI 中执行 flush database 命令，将所有数据强制写入硬盘。接着，通过 Linux 操作系统的 du 命令获取指定 vnode 的数据文件夹大小。最后，将原始数据大小除以实际存储的数据大小，即可计算出真实的压缩率。
```
通过如下命令可以获得 TDengine 占用的存储空间。

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

@ -58,7 +58,7 @@ serverPort 6030
#### 5. 启动
按照前述步骤启动第 1 个 dnode，例如 h1.taosdata.com。接着在终端中执行 taos，启动 TDengine 的 CLI 程序 taos，并在其中执行 show dnodes 命令，以查看当前集群中的所有 dnode 信息。
按照前述步骤启动第 1 个 dnode，例如 h1.taosdata.com。接着在终端中执行 taos，启动 TDengine CLI 程序 taos，并在其中执行 show dnodes 命令，以查看当前集群中的所有 dnode 信息。
```shell
taos> show dnodes;
@ -71,7 +71,7 @@ taos> show dnodes;
#### 6. 添加 dnode
按照前述步骤，在每个物理节点启动 taosd。每个 dnode 都需要在 taos.cfg 文件中将 firstEp 参数配置为新建集群首个节点的 endpoint，在本例中是 h1.taosdata.com:6030。在第 1 个 dnode 所在机器，在终端中运行 taos，打开 TDengine 的 CLI 程序 taos，然后登录TDengine 集群，执行如下 SQL。
按照前述步骤，在每个物理节点启动 taosd。每个 dnode 都需要在 taos.cfg 文件中将 firstEp 参数配置为新建集群首个节点的 endpoint，在本例中是 h1.taosdata.com:6030。在第 1 个 dnode 所在机器，在终端中运行 taos，打开 TDengine CLI 程序 taos，然后登录TDengine 集群，执行如下 SQL。
```shell
create dnode "h2.taosdata.com:6030"
@ -86,13 +86,13 @@ show dnodes;
在日志中，请确认输出的 dnode 的 fqdn 和端口是否与你刚刚尝试添加的 endpoint 一致。如果不一致，请修正为正确的 endpoint。遵循上述步骤，你可以持续地将新的 dnode 逐个加入集群，从而扩展集群规模并提高整体性能。确保在添加新节点时遵循正确的流程，这有助于维持集群的稳定性和可靠性。
**Tips**
- 任何已经加入集群的 dnode 都可以作为后续待加入节点的 firstEp。firstEp 参数仅仅在该 dnode 首次加入集群时起作用，加入集群后，该 dnode 会保存最新的 mnode 的 endpoint 列表，后续不再依赖这个参数。之后配置文件中的 firstEp 参数主要用于客户端连接，如果没有为 TDengine 的 CLI 设置参数，则默认连接由 firstEp 指定的节点。
- 任何已经加入集群的 dnode 都可以作为后续待加入节点的 firstEp。firstEp 参数仅仅在该 dnode 首次加入集群时起作用，加入集群后，该 dnode 会保存最新的 mnode 的 endpoint 列表，后续不再依赖这个参数。之后配置文件中的 firstEp 参数主要用于客户端连接，如果没有为 TDengine CLI 设置参数，则默认连接由 firstEp 指定的节点。
- 两个没有配置 firstEp 参数的 dnode 在启动后会独立运行。这时无法将其中一个dnode 加入另外一个 dnode，形成集群。
- TDengine 不允许将两个独立的集群合并成新的集群。
#### 7. 添加 mnode
在创建 TDengine 集群时，首个 dnode 将自动成为集群的 mnode，负责集群的管理和协调工作。为了实现 mnode 的高可用性，后续添加的 dnode 需要手动创建 mnode。请注意，一个集群最多允许创建 3 个 mnode，且每个 dnode 上只能创建一个 mnode。当集群中的 dnode 数量达到或超过 3 个时，你可以为现有集群创建 mnode。在第 1个 dnode 中，首先通过 TDengine 的 CLI 程序 taos 登录 TDengine，然后执行如下 SQL。
在创建 TDengine 集群时，首个 dnode 将自动成为集群的 mnode，负责集群的管理和协调工作。为了实现 mnode 的高可用性，后续添加的 dnode 需要手动创建 mnode。请注意，一个集群最多允许创建 3 个 mnode，且每个 dnode 上只能创建一个 mnode。当集群中的 dnode 数量达到或超过 3 个时，你可以为现有集群创建 mnode。在第 1个 dnode 中，首先通过 TDengine CLI 程序 taos 登录 TDengine，然后执行如下 SQL。
```shell
create mnode on dnode <dnodeId>

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

@ -17,8 +17,8 @@ TDengine 面向多种写入场景，而很多写入场景下，TDengine 的存
### 语法
```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;
@ -32,6 +32,7 @@ KILL COMPACT compact_id;
- 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 任务

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

@ -203,7 +203,7 @@ toc_max_heading_level: 4
通过 “工具” 页面，用户可以了解如下 TDengine 周边工具的使用方法。
- TDengine CLI。
- taosBenchmark。
- taosDump。
- taosdump。
- TDengine 与 BI 工具的集成，例如 Google Data Studio、Power BI、永洪 BI 等。
- TDengine 与 Grafana、Seeq 的集成。

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

@ -61,7 +61,7 @@ TDengine Enterprise 的备份和恢复功能包括以下几个概念：
## 2.2. 数据备份
通过浏览器访问 taosExplorer 服务，访问地址通常为 TDengine 集群所在 IP 地址的端口 6060，如 http://localhost:6060。 在
通过浏览器访问 taosExplorer 服务，访问地址通常为 TDengine 集群所在 IP 地址的端口 6060，如 `http://localhost:6060`。 在
taosExplorer 服务页面中，进入“系统管理 - 备份”页面，在“备份计划”标签页下，点击“创建备份计划”，填写备份计划的相关信息。
需要填写的信息包括：
@ -76,6 +76,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`个备份文件。
创建成功后，备份计划会开始按照配置的参数运行。在“备份计划”下的列表中，可以查看已创建的备份计划。
备份计划支持以下操作：

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

@ -23,7 +23,7 @@ TDengine 支持 WAL 机制，实现数据的容错能力，保证数据的高可
- 第 1 步，在集群 A 中创建一个数据库 db1，并向该数据库持续写入数据。
- 第 2 步， 通过 Web 浏览器访问集群 A 的 taosExplorer 服务， 访问地址通常 为TDengine 集群所在 IP 地址的端口 6060，如 http://localhost:6060。
- 第 2 步， 通过 Web 浏览器访问集群 A 的 taosExplorer 服务， 访问地址通常 为TDengine 集群所在 IP 地址的端口 6060，如 `http://localhost:6060`。
- 第 3 步，访问 TDengine 集群 B，创建一个与集群 A 中数据库 db1 参数配置相同的数据库 db2。

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 服务使用标准端口，同步任务使用原生连接。

7
docs/zh/10-third-party/01-collection/12-flink.md vendored
View File

@ -24,6 +24,8 @@ Flink Connector 支持所有能运行 Flink 1.19 及以上版本的平台。
## 版本历史
| Flink Connector 版本 | 主要变化 | TDengine 版本 |
| ------------------| ------------------------------------ | ---------------- |
| 2.1.0 | 修复不同数据源varchar类型写入问题| - |
| 2.0.2 | Table Sink 支持 RowKind.UPDATE_BEFORE、RowKind.UPDATE_AFTER 和 RowKind.DELETE 类型| - |
| 2.0.1 | Sink 支持对所有继承自 RowData 并已实现的类型进行数据写入| - |
| 2.0.0 | 1. 支持 SQL 查询 TDengine 数据库中的数据<br/> 2. 支持 CDC 订阅 TDengine 数据库中的数据<br/> 3. 支持 Table SQL 方式读取和写入 TDengine 数据库| 3.3.5.1 及以上版本 |
| 1.0.0 | 支持 Sink 功能，将来着其他数据源的数据写入到 TDengine| 3.3.2.0 及以上版本|
@ -83,7 +85,8 @@ TDengine 目前支持时间戳、数字、字符、布尔类型，与 Flink RowD
| SMALLINT | Short |
| TINYINT | Byte |
| BOOL | Boolean |
| BINARY | byte[] |
| VARCHAR | StringData |
| BINARY | StringData |
| NCHAR | StringData |
| JSON | StringData |
| VARBINARY | byte[] |
@ -112,7 +115,7 @@ env.getCheckpointConfig().setCheckpointingMode(CheckpointingMode.AT_LEAST_ONCE);
<dependency>
<groupId>com.taosdata.flink</groupId>
<artifactId>flink-connector-tdengine</artifactId>
<version>2.0.1</version>
<version>2.1.0</version>
</dependency>
```

111
docs/zh/10-third-party/05-bi/03-powerbi.md vendored
View File

@ -1,78 +1,79 @@
---
title: 与 PowerBI 的集成
title: 与 PowerBI 集成
sidebar_label: PowerBI
toc_max_heading_level: 4
---
Power BI是由Microsoft提供的一种商业分析工具。通过配置使用ODBC连接器，Power BI可以快速访问TDengine的数据。用户可以将标签数据、原始时序数据或按时间聚合后的时序数据从TDengine导入到Power BI，制作报表或仪表盘，整个过程不需要任何代码编写过程。
Power BI 是由 Microsoft 提供的一种商业分析工具。通过配置使用 ODBC 连接器，Power BI 可以快速访问 TDengine 的数据。用户可以将标签数据、原始时序数据或按时间聚合后的时序数据从 TDengine 导入到 Power BI，制作报表或仪表盘，整个过程不需要任何代码编写过程。
## 前置条件
安装完成Power BI Desktop软件并运行（如未安装，请从其官方地址下载最新的Windows操作系统 32/64 位版本）。
准备以下环境：
- TDengine 3.3.4.0 以上版本集群已部署并正常运行（企业及社区版均可）。
- taosAdapter 能够正常运行，详细参考 [taosAdapter 参考手册](../../../reference/components/taosadapter)。
- 从 TDengine 官网下载最新的 Windows 操作系统 X64 客户端驱动程序并进行安装，详细参考 [安装 ODBC 驱动](../../../reference/connector/odbc/#安装)。
- 安装完成 Power BI Desktop 软件并运行（如未安装，请从其官方地址下载最新的 Windows 操作系统 32/64 位版本）。
## 安装 ODBC 驱动
## 配置数据源
从TDengine官网下载最新的Windows操作系统X64客户端驱动程序，并安装在运行Power BI的机器上。安装成功后可在“ODBC数据源（32位）”或者“ODBC数据源（64位）”管理工具中看到 TDengine 驱动程序。
**第 1 步**，在 Windows 操作系统的开始菜单中搜索并打开【ODBC数据源（64位）】管理工具并进行配置。详细参考 [配置ODBC数据源](../../../reference/connector/odbc/#配置数据源)。
## 配置ODBC数据源
**第 2 步**，打开 Power BI 并登录后，点击【主页】->【获取数据】->【其他】->【ODBC】->【连接】，添加数据源。
配置ODBC数据源的操作步骤如下。
**第 3 步**，选择刚才创建的数据源名称，比如【MyTDengine】，如果需要输入 SQL，则可以点击【高级选项】选项卡，在展开的对话框的编辑框中输入 SQL 语句。点击【确定】按钮，即可连接到配置好的数据源。
第1步，在Windows操作系统的开始菜单中搜索并打开“ODBC数据源（32位）”或者“ODBC数据源（64位）”管理工具。
第2步，点击“用户DSN”选项卡→“添加”按钮，进入“创建新数据源”对话框。
第3步，在“选择您想为其安装数据源的驱动程序”列表中选择“TDengine”，点击“完成”按钮，进入TDengine ODBC数据源配置页面。填写如下必要信息。
- DSN：数据源名称，必填，比如“MyTDengine”。
- 连接类型：勾选“WebSocket”复选框。
- URL：ODBC 数据源 URL，必填，比如“http://127.0.0.1:6041”。
- 数据库：表示需要连接的数据库，可选，比如“test”。
- 用户名：输入用户名，如果不填，默认为“root”。
- 密码：输入用户密码，如果不填，默认为“taosdata”。
**第 4 步**，进入【导航器】后，可以浏览对应数据库的数据表/视图并加载数据。
第4步，点击“测试连接”按钮，测试连接情况，如果成功连接，则会提示“成功连接到http://127.0.0.1:6041”。
第5步，点击“确定”按钮，即可保存配置并退出。
## 数据分析
## 导入TDengine数据到Power BI
### 使用说明
将TDengine数据导入Power BI的操作步骤如下:
第1步，打开Power BI并登录后，点击“主页”→“获取数据”→“其他”→“ODBC”→“连接”，添加数据源。
第2步，选择刚才创建的数据源名称，比如“MyTDengine”，如果需要输入SQL，则可以点击“高级选项”选项卡，在展开的对话框的编辑框中输入SQL语句。点击“确定”按钮，即可连接到配置好的数据源。
第3步，进入“导航器”后，可以浏览对应数据库的数据表/视图并加载数据。
为了充分发挥 Power BI 在分析 TDengine中 数据方面的优势，用户需要先理解维度、度量、窗口切分查询、数据切分查询、时序和相关性等核心概念，之后通过自定义的 SQL 导入数据。
- 维度：通常是分类（文本）数据，描述设备、测点、型号等类别信息。在 TDengine 的超级表中，使用标签列存储数据的维度信息，可以通过形如 `select distinct tbname, tag1, tag2 from supertable` 的 SQL 语法快速获得维度信息。
- 度量：可以用于进行计算的定量（数值）字段，常见计算有求和、取平均值和最小值等。如果测点的采集周期为1s，那么一年就有 3000 多万条记录，把这些数据全部导入 Power BI 会严重影响其执行效率。在 TDengine 中，用户可以使用数据切分查询、窗口切分查询等语法，结合与窗口相关的伪列，把降采样后的数据导入 Power BI 中，具体语法请参阅 TDengine 官方文档的特色查询功能部分。
- 窗口切分查询：比如温度传感器每秒采集一次数据，但须查询每隔 10min 的温度平均值，在这种场景下可以使用窗口子句来获得需要的降采样查询结果，对应的 SQL 形如 `select tbname, _wstart date，avg(temperature) temp from table interval(10m)`，其中，`_wstart` 是伪列，表示时间窗口起始时间，10m 表示时间窗口的持续时间，`avg(temperature)` 表示时间窗口内的聚合值。
- 数据切分查询：如果需要同时获取很多温度传感器的聚合数值，可对数据进行切分，然后在切分出的数据空间内进行一系列的计算，对应的 SQL 形如 `partition by part_list`。数据切分子句最常见的用法是在超级表查询中按标签将子表数据进行切分，将每个子表的数据独立出来，形成一条条独立的时间序列，方便针对各种时序场景的统计分析。
- 时序：在绘制曲线或者按照时间聚合数据时，通常需要引入日期表。日期表可以从 Excel 表格中导入，也可以在 TDengine 中执行 SQL 获取，例如 `select _wstart date, count(*) cnt from test.meters where ts between A and B interval(1d) fill(0)`，其中 fill 字句表示数据缺失情况下的填充模式，伪列 _wstart 则为要获取的日期列。
- 相关性：告诉数据之间如何关联，如度量和维度可以通过 tbname 列关联在一起，日期表和度量则可以通过 date 列关联，配合形成可视化报表。
为了充分发挥Power BI在分析TDengine中数据方面的优势，用户需要先理解维度、度量、窗口切分查询、数据切分查询、时序和相关性等核心概念，之后通过自定义的SQL导入数据。
- 维度：通常是分类（文本）数据，描述设备、测点、型号等类别信息。在TDengine的超级表中，使用标签列存储数据的维度信息，可以通过形如“select distinct tbname, tag1, tag2 from supertable”的SQL语法快速获得维度信息。
- 度量：可以用于进行计算的定量（数值）字段，常见计算有求和、取平均值和最小值等。如果测点的采集周期为1s，那么一年就有3000多万条记录，把这些数据全部导入Power BI会严重影响其执行效率。在TDengine中，用户可以使用数据切分查询、窗口切分查询等语法，结合与窗口相关的伪列，把降采样后的数据导入Power BI中，具体语法请参阅TDengine官方文档的特色查询功能部分。
- 窗口切分查询：比如温度传感器每秒采集一次数据，但须查询每隔10min的温度平均值，在这种场景下可以使用窗口子句来获得需要的降采样查询结果，对应的SQL形如`select tbname, _wstart date，avg(temperature) temp from table interval(10m)`，其中，_wstart是伪列，表示时间窗口起始时间，10m表示时间窗口的持续时间，avg(temperature)表示时间窗口内的聚合值。
- 数据切分查询：如果需要同时获取很多温度传感器的聚合数值，可对数据进行切分，然后在切分出的数据空间内进行一系列的计算，对应的SQL形如 `partition by part_list`。数据切分子句最常见的用法是在超级表查询中按标签将子表数据进行切分，将每个子表的数据独立出来，形成一条条独立的时间序列，方便针对各种时序场景的统计分析。
- 时序：在绘制曲线或者按照时间聚合数据时，通常需要引入日期表。日期表可以从Excel表格中导入，也可以在TDengine中执行SQL获取，例如 `select _wstart date, count(*) cnt from test.meters where ts between A and B interval(1d) fill(0)`，其中fill字句表示数据缺失情况下的填充模式，伪列_wstart则为要获取的日期列。
- 相关性：告诉数据之间如何关联，如度量和维度可以通过tbname列关联在一起，日期表和度量则可以通过date列关联，配合形成可视化报表。
### 智能电表样例
## 智能电表样例
TDengine 采用了一种独特的数据模型，以优化时序数据的存储和查询性能。该模型利用超级表作为模板，为每台设备创建一张独立的表。每张表在设计时考虑了高度的可扩展性，最多可包含 4096 个数据列和 128 个标签列。这种设计使得 TDengine 能够高效地处理大量时序数据，同时保持数据的灵活性和易用性。
TDengine采用了一种独特的数据模型，以优化时序数据的存储和查询性能。该模型利用超级表作为模板，为每台设备创建一张独立的表。每张表在设计时考虑了高度的可扩展性，最多可包含4096个数据列和128个标签列。这种设计使得TDengine能够高效地处理大量时序数据，同时保持数据的灵活性和易用性。
以智能电表为例，假设每块电表每秒产生一条记录，那么每天将产生 86400 条记录。对于 1000 块智能电表来说，每年产生的记录将占用大约 600GB 的存储空间。面对如此庞大的数据量，Power BI 等商业智能工具在数据分析和可视化方面发挥着重要作用。
以智能电表为例，假设每块电表每秒产生一条记录，那么每天将产生86 400条记录。对于1000块智能电表来说，每年产生的记录将占用大约600GB的存储空间。面对如此庞大的数据量，Power BI等商业智能工具在数据分析和可视化方面发挥着重要作用。
在 Power BI 中，用户可以将 TDengine 表中的标签列映射为维度列，以便对数据进行分组和筛选。同时，数据列的聚合结果可以导入为度量列，用于计算关键指标和生成报表。通过这种方式，Power BI 能够帮助决策者快速获取所需的信息，深入了解业务运营情况，从而制定更加明智的决策。
在Power BI中，用户可以将TDengine表中的标签列映射为维度列，以便对数据进行分组和筛选。同时，数据列的聚合结果可以导入为度量列，用于计算关键指标和生成报表。通过这种方式，Power BI能够帮助决策者快速获取所需的信息，深入了解业务运营情况，从而制定更加明智的决策。
根据如下步骤，便可以体验通过 Power BI 生成时序数据报表的功能。
根据如下步骤，便可以体验通过Power BI生成时序数据报表的功能。
第1步，使用TDengine的taosBenchMark快速生成1000块智能电表3天的数据，采集频率为1s。
```shell
taosBenchmark -t 1000 -n 259200 -S 1000 -y
```
第2步，导入维度数据。在Power BI中导入表的标签列，取名为tags，通过如下SQL获取超级表下所有智能电表的标签数据。
```sql
select distinct tbname device, groupId, location from test.meters
```
第3步，导入度量数据。在Power BI中，按照1小时的时间窗口，导入每块智能电表的电流均值、电压均值、相位均值，取名为data，SQL如下。
```sql
select tbname, _wstart ws, avg(current), avg(voltage), avg(phase) from test.meters PARTITION by tbname interval(1h)
```
第4步，导入日期数据。按照1天的时间窗口，获得时序数据的时间范围及数据计数，SQL如下。需要在Power Query编辑器中将date列的格式从“文本”转化为“日期”。
```sql
select _wstart date, count(*) from test.meters interval(1d) having count(*)>0
```
第5步，建立维度和度量的关联关系。打开模型视图，建立表tags和data的关联关系，将tbname设置为关联数据列。
第6步，建立日期和度量的关联关系。打开模型视图，建立数据集date和data的关联关系，关联的数据列为date和datatime。
第7步，制作报告。在柱状图、饼图等控件中使用这些数据。
**第 1 步**，使用 TDengine 的 taosBenchMark 快速生成 1000 块智能电表 3 天的数据，采集频率为 1s。
由于TDengine处理时序数据的超强性能，使得用户在数据导入及每日定期刷新数据时，都可以得到非常好的体验。更多有关Power BI视觉效果的构建方法，请参照Power BI的官方文档。
```shell
taosBenchmark -t 1000 -n 259200 -S 1000 -y
```
**第 2 步**，导入维度数据。在 Power BI 中导入表的标签列，取名为 tags，通过如下 SQL 获取超级表下所有智能电表的标签数据。
```sql
select distinct tbname device, groupId, location from test.meters
```
**第 3 步**，导入度量数据。在 Power BI 中，按照 1 小时的时间窗口，导入每块智能电表的电流均值、电压均值、相位均值，取名为 data，SQL如下。
```sql
select tbname, _wstart ws, avg(current), avg(voltage), avg(phase) from test.meters PARTITION by tbname interval(1h)
```
**第 4 步**，导入日期数据。按照 1 天的时间窗口，获得时序数据的时间范围及数据计数，SQL 如下。需要在 Power Query 编辑器中将 date 列的格式从“文本”转化为“日期”。
```sql
select _wstart date, count(*) from test.meters interval(1d) having count(*)>0
```
**第 5 步**，建立维度和度量的关联关系。打开模型视图，建立表 tags 和 data 的关联关系，将 tbname 设置为关联数据列。
**第 6 步**，建立日期和度量的关联关系。打开模型视图，建立数据集 date 和 data 的关联关系，关联的数据列为 date 和 datatime。
**第 7 步**，制作报告。在柱状图、饼图等控件中使用这些数据。
由于TDengine处理时序数据的超强性能，使得用户在数据导入及每日定期刷新数据时，都可以得到非常好的体验。更多有关 Power BI 视觉效果的构建方法，请参照 Power BI 的官方文档。

73
docs/zh/10-third-party/05-bi/05-yhbi.md vendored
View File

@ -1,46 +1,55 @@
---
title: 与永洪 BI 的集成
title: 与永洪 BI 集成
sidebar_label: 永洪 BI
toc_max_heading_level: 4
---
永洪 BI 是一个专为各种规模企业打造的全业务链大数据分析解决方案，旨在帮助用户轻松发掘大数据价值，获取深入的洞察力。该平台以其灵活性和易用性而广受好评，无论企业规模大小，都能从中受益。
为了实现与 TDengine 的高效集成，永洪 BI 提供了 JDBC 连接器。用户只须按照简单的步骤配置数据源，即可将 TDengine 作为数据源添加到永洪BI中。这一过程不仅快速便捷，还能确保数据的准确性和稳定性。
为了实现与 TDengine 的高效集成，永洪 BI 提供了 JDBC 连接器。用户只须按照简单的步骤配置数据源，即可将 TDengine 作为数据源添加到永洪 BI 中。这一过程不仅快速便捷，还能确保数据的准确性和稳定性。
一旦数据源配置完成，永洪BI便能直接从TDengine中读取数据，并利用其强大的数据处理和分析功能，为用户提供丰富的数据展示、分析和预测能力。这意味着用户无须编写复杂的代码或进行烦琐的数据转换工作，即可轻松获取所需的业务洞察。
一旦数据源配置完成，永洪 BI 便能直接从 TDengine 中读取数据，并利用其强大的数据处理和分析功能，为用户提供丰富的数据展示、分析和预测能力。这意味着用户无须编写复杂的代码或进行烦琐的数据转换工作，即可轻松获取所需的业务洞察。
## 前置条件
准备以下环境：
- TDengine 3.3.2.0 以上版本集群已部署并正常运行（企业及社区版均可）。
- taosAdapter 能够正常运行，详细参考 [taosAdapter 参考手册](../../../reference/components/taosadapter)。
- 确保永洪 BI 已经安装并运行（如果未安装，请到永洪科技官方下载页面下载）。
- 安装JDBC驱动。从 maven.org 下载 TDengine JDBC 连接器文件 “taos-jdbcdriver-3.4.0-dist.jar”，并安装在永洪 BI 的机器上。
- 安装 JDBC 驱动。从 maven.org 下载 TDengine JDBC 连接器文件 `taos-jdbcdriver-3.4.0-dist.jar` 及以上版本。
## 配置JDBC数据源
## 配置数据源
配置JDBC数据源的步骤如下。
配置JDBC数据源的步骤如下:
第1步，在打开的永洪BI中点击“添加数据源”按钮，选择SQL数据源中的“GENERIC”类型。
第2步，点击“选择自定义驱动”按钮，在“驱动管理”对话框中点击“驱动列表”旁边的“+”，输入名称“MyTDengine”。然后点击“上传文件”按钮，上传刚刚下载的TDengine JDBC连接器文件“taos-jdbcdriver-3.2.7-dist.jar”，并选择“com.taosdata.jdbc.
rs.RestfulDriver”驱动，最后点击“确定”按钮，完成驱动添加步骤。
第3步，复制下面的内容到“URL”字段。
```text
jdbc:TAOS-RS://127.0.0.1:6041?user=root&password=taosdata
```
第4步，在“认证方式”中点击“无身份认证”单选按钮。
第5步，在数据源的高级设置中修改“Quote 符号”的值为反引号（`）。
第6步，点击“测试连接”按钮，弹出“测试成功”对话框。点击“保存”按钮，输入“MyTDengine”来保存TDengine数据源。
**第 1 步**，在打开的永洪 BI 中点击【添加数据源】按钮，选择 SQL 数据源中的 “GENERIC” 类型。
## 创建TDengine数据集
**第 2 步**，点击【选择自定义驱动】按钮，在【驱动管理】对话框中点击【驱动列表】旁边的 “+”，输入名称 “MyTDengine”。然后点击【上传文件】按钮，上传刚刚下载的 TDengine JDBC 连接器文件 `taos-jdbcdriver-3.2.7-dist.jar`，并选择 `com.taosdata.jdbc.rs.RestfulDriver` 驱动，最后点击“确定”按钮，完成驱动添加步骤。
创建TDengine数据集的步骤如下。
**第 3 步**，复制下面的内容到【URL】字段。
第1步，在永洪BI中点击“添加数据源”按钮，展开刚刚创建的数据源，并浏览TDengine中的超级表。
第2步，可以将超级表的数据全部加载到永洪BI中，也可以通过自定义SQL导入部分数据。
第3步，当勾选“数据库内计算”复选框时，永洪BI将不再缓存TDengine的时序数据，并在处理查询时将SQL请求发送给TDengine直接处理。
```text
jdbc:TAOS-RS://127.0.0.1:6041?user=root&password=taosdata
```
当导入数据后，永洪BI会自动将数值类型设置为“度量”列，将文本类型设置为“维度”列。而在TDengine的超级表中，由于将普通列作为数据的度量，将标签列作为数据的维度，因此用户可能需要在创建数据集时更改部分列的属性。TDengine在支持标准SQL的基础之上还提供了一系列满足时序业务场景需求的特色查询语法，例如数据切分查询、窗口切分查询等，具体操作步骤请参阅TDengine的官方文档。通过使用这些特色查询，当永洪BI将SQL查询发送到TDengine时，可以大大提高数据访问速度，减少网络传输带宽。
**第 4 步**，在【认证方式】中点击【无身份认证】单选按钮。
**第 5 步**，在数据源的高级设置中修改 “Quote 符号” 的值为反引号（`）。
**第 6 步**，点击【测试连接】按钮，弹出【测试成功】对话框。点击【保存】按钮，输入 “MyTDengine” 来保存 TDengine 数据源。
**第 7 步**，在永洪 BI 中点击【添加数据源】按钮，展开刚刚创建的数据源，并浏览 TDengine 中的超级表。
**第 8 步**，可以将超级表的数据全部加载到永洪 BI 中，也可以通过自定义 SQL 导入部分数据。
**第 9 步**，当勾选【数据库内计算】复选框时，永洪 BI 将不再缓存 TDengine 的时序数据，并在处理查询时将 SQL 请求发送给 TDengine 直接处理。
## 数据分析
当导入数据后，永洪 BI 会自动将数值类型设置为 “度量” 列，将文本类型设置为 “维度” 列。而在 TDengine 的超级表中，由于将普通列作为数据的度量，将标签列作为数据的维度，因此用户可能需要在创建数据集时更改部分列的属性。TDengine 在支持标准 SQL 的基础之上还提供了一系列满足时序业务场景需求的特色查询语法，例如数据切分查询、窗口切分查询等，具体操作步骤请参阅 TDengine 的官方文档。通过使用这些特色查询，当永洪 BI 将 SQL 查询发送到 TDengine 时，可以大大提高数据访问速度，减少网络传输带宽。
在永洪 BI 中，你可以创建 “参数” 并在 SQL 中使用，通过手动、定时的方式动态执行这些 SQL，即可实现可视化报告的刷新效果。如下 SQL 可以从 TDengine 实时读取数据。
在永洪BI中，你可以创建“参数”并在SQL中使用，通过手动、定时的方式动态执行这些SQL，即可实现可视化报告的刷新效果。如下SQL可以从TDengine实时读取数据。
```sql
select _wstart ws, count(*) cnt from supertable where tbname=?{metric} and ts = ?{from} and ts < ?{to} interval(?{interval})
```
@ -49,17 +58,15 @@ select _wstart ws, count(*) cnt from supertable where tbname=?{metric} and ts =
1. `_wstart`：表示时间窗口起始时间。
2. `count（*）`：表示时间窗口内的聚合值。
3. `?{interval}`：表示在 SQL 语句中引入名称为 `interval` 的参数，当 BI 工具查询数据时，会给 `interval` 参数赋值，如果取值为 1m，则表示按照 1 分钟的时间窗口降采样数据。
4. `?{metric}`：该参数用来指定查询的数据表名称，当在 BI 工具中把某个“下拉参数组件”的 ID 也设置为 metric 时，该“下拉参数组件”的被选择项将会和该参数绑定在一起，实现动态选择的效果。
5. `?{from}` 和 `？{to}`：这两个参数用来表示查询数据集的时间范围，可以与“文本参数组件”绑定。
您可以在 BI 工具的“编辑参数”对话框中修改“参数”的数据类型、数据范围、默认取值，并在“可视化报告”中动态设置这些参数的值。
4. `?{metric}`：该参数用来指定查询的数据表名称，当在 BI 工具中把某个 “下拉参数组件” 的 ID 也设置为 metric 时，该 “下拉参数组件” 的被选择项将会和该参数绑定在一起，实现动态选择的效果。
5. `?{from}` 和 `？{to}`：这两个参数用来表示查询数据集的时间范围，可以与 “文本参数组件” 绑定。
您可以在 BI 工具的【编辑参数】对话框中修改 “参数” 的数据类型、数据范围、默认取值，并在 “可视化报告” 中动态设置这些参数的值。
## 21.4.5 制作可视化报告
制作可视化报告的步骤如下:
制作可视化报告的步骤如下。
1. 在永洪 BI 工具中点击“制作报告”，创建画布。
2. 拖动可视化组件到画布中，例如“表格组件”。
3. 在“数据集”侧边栏中选择待绑定的数据集，将数据列中的“维度”和“度量”按需绑定到“表格组件”。
4. 点击“保存”后，即可查看报告。
1. 在永洪 BI 工具中点击【制作报告】，创建画布。
2. 拖动可视化组件到画布中，例如 “表格组件”。
3. 在【数据集】侧边栏中选择待绑定的数据集，将数据列中的 “维度” 和 “度量” 按需绑定到 “表格组件”。
4. 点击【保存】后，即可查看报告。
5. 更多有关永洪 BI 工具的信息，请查询永洪科技官方帮助文档。

118
docs/zh/10-third-party/05-bi/09-seeq.md vendored
View File

@ -1,48 +1,50 @@
---
sidebar_label: Seeq
title: 与 Seeq 的集成
title: 与 Seeq 集成
toc_max_heading_level: 4
---
Seeq 是制造业和工业互联网（IIOT）高级分析软件。Seeq 支持在工艺制造组织中使用机器学习创新的新功能。这些功能使组织能够将自己或第三方机器学习算法部署到前线流程工程师和主题专家使用的高级分析应用程序，从而使单个数据科学家的努力扩展到许多前线员工。
通过 TDengine Java connector， Seeq 可以轻松支持查询 TDengine 提供的时序数据，并提供数据展现、分析、预测等功能。
通过 `TDengine Java connector`， Seeq 可以轻松支持查询 TDengine 提供的时序数据，并提供数据展现、分析、预测等功能。
## 前置条件
- Seeq 已经安装。从 [Seeq 官网](https://www.seeq.com/customer-download)下载相关软件，例如 Seeq Server 和 Seeq Data Lab 等。Seeq Data Lab 需要安装在和 Seeq Server 不同的服务器上，并通过配置和 Seeq Server 互联。详细安装配置指令参见[Seeq 知识库]( https://support.seeq.com/kb/latest/cloud/)。
准备以下环境：
- TDengine 3.1.0.3 以上版本集群已部署并正常运行（企业及社区版均可）。
- taosAdapter 能够正常运行，详细参考 [taosAdapter 参考手册](../../../reference/components/taosadapter)。
- Seeq 已经安装。从 [Seeq 官网](https://www.seeq.com/customer-download)下载相关软件，例如 `Seeq Server` 和 `Seeq Data Lab` 等。`Seeq Data Lab` 需要安装在和 `Seeq Server` 不同的服务器上，并通过配置和 `Seeq Server` 互联。详细安装配置指令参见 [Seeq 知识库]( https://support.seeq.com/kb/latest/cloud/)。
- 安装 JDBC 驱动。从 `maven.org` 下载 `TDengine JDBC` 连接器文件 `taos-jdbcdriver-3.2.5-dist.jar` 及以上版本。
- TDengine 本地实例已安装。 请参考[官网文档](../../../get-started)。 若使用 TDengine Cloud，请在 https://cloud.taosdata.com 申请帐号并登录查看如何访问 TDengine Cloud。
## 配置数据源
## 配置 Seeq 访问 TDengine
1. 查看 data 存储位置
**第 1 步**，查看 data 存储位置
```
sudo seeq config get Folders/Data
```
2. 从 maven.org 下载 TDengine Java connector 包，目前最新版本为[3.2.5](https://repo1.maven.org/maven2/com/taosdata/jdbc/taos-jdbcdriver/3.2.5/taos-jdbcdriver-3.2.5-dist.jar)，并拷贝至 data 存储位置的 plugins\lib 中。
**第 2 步**，将 `maven.org` 下载 `TDengine Java connector` 包并拷贝至 data 存储位置的 `plugins\lib` 中。
3. 重新启动 seeq server
**第 3 步**，重新启动 seeq server
```
sudo seeq restart
```
4. 输入 License
**第 4 步**，输入 License
使用浏览器访问 ip:34216 并按照说明输入 license。
## 使用 Seeq 分析 TDengine 时序数据
本章节演示如何使用 Seeq 软件配合 TDengine 进行时序数据分析。
## 数据分析
### 场景介绍
示例场景为一个电力系统，用户每天从电站仪表收集用电量数据，并将其存储在 TDengine 集群中。现在用户想要预测电力消耗将会如何发展，并购买更多设备来支持它。用户电力消耗随着每月订单变化而不同，另外考虑到季节变化，电力消耗量会有所不同。这个城市位于北半球，所以在夏天会使用更多的电力。我们模拟数据来反映这些假定。
### 数据 Schema
### 数据准备
**第 1 步**，在 TDengine 中创建表。
```
CREATE STABLE meters (ts TIMESTAMP, num INT, temperature FLOAT, goods INT) TAGS (device NCHAR(20));
@ -51,20 +53,16 @@ CREATE TABLE goods (ts1 TIMESTAMP, ts2 TIMESTAMP, goods FLOAT);
![Seeq demo schema](./seeq/seeq-demo-schema.webp)
### 构造数据方法
**第 2 步**，在 TDengine 中构造数据。
```
python mockdata.py
taos -s "insert into power.goods select _wstart, _wstart + 10d, avg(goods) from power.meters interval(10d);"
```
源代码托管在[GitHub 仓库](https://github.com/sangshuduo/td-forecasting)。
源代码托管在 [GitHub 仓库](https://github.com/sangshuduo/td-forecasting)。
## 使用 Seeq 进行数据分析
### 配置数据源（Data Source）
使用 Seeq 管理员角色的帐号登录，并新建数据源。
**第 3 步**，使用 Seeq 管理员角色的帐号登录，并新建数据源。
- Power
@ -246,7 +244,7 @@ taos -s "insert into power.goods select _wstart, _wstart + 10d, avg(goods) from
### 使用 Seeq Workbench
登录 Seeq 服务页面并新建 Seeq Workbench，通过选择数据源搜索结果和根据需要选择不同的工具，可以进行数据展现或预测，详细使用方法参见[官方知识库](https://support.seeq.com/space/KB/146440193/Seeq+Workbench)。
登录 Seeq 服务页面并新建 Seeq Workbench，通过选择数据源搜索结果和根据需要选择不同的工具，可以进行数据展现或预测，详细使用方法参见 [官方知识库](https://support.seeq.com/space/KB/146440193/Seeq+Workbench)。
![Seeq Workbench](./seeq/seeq-demo-workbench.webp)
@ -319,78 +317,10 @@ plt.show()
![Seeq forecast result](./seeq/seeq-forecast-result.webp)
## 配置 Seeq 数据源连接 TDengine Cloud
### 方案总结
配置 Seeq 数据源连接 TDengine Cloud 和连接 TDengine 本地安装实例没有本质的不同，只要登录 TDengine Cloud 后选择“编程 - Java”并拷贝带 token 字符串的 JDBC 填写为 Seeq Data Source 的 DatabaseJdbcUrl 值。
注意使用 TDengine Cloud 时 SQL 命令中需要指定数据库名称。
通过集成 Seeq 和 TDengine，可以充分利用 TDengine 高效的存储和查询性能，同时也可以受益于 Seeq 提供给用户的强大数据可视化和分析功能。
### 用 TDengine Cloud 作为数据源的配置内容示例：
这种集成使用户能够充分利用 TDengine 的高性能时序数据存储和检索，确保高效处理大量数据。同时，Seeq 提供高级分析功能，如数据可视化、异常检测、相关性分析和预测建模，使用户能够获得有价值的洞察并基于数据进行决策。
```
{
"QueryDefinitions": [
{
"Name": "CloudVoltage",
"Type": "SIGNAL",
"Sql": "SELECT ts, voltage FROM test.meters",
"Enabled": true,
"TestMode": false,
"TestQueriesDuringSync": true,
"InProgressCapsulesEnabled": false,
"Variables": null,
"Properties": [
{
"Name": "Name",
"Value": "Voltage",
"Sql": null,
"Uom": "string"
},
{
"Name": "Interpolation Method",
"Value": "linear",
"Sql": null,
"Uom": "string"
},
{
"Name": "Maximum Interpolation",
"Value": "2day",
"Sql": null,
"Uom": "string"
}
],
"CapsuleProperties": null
}
],
"Type": "GENERIC",
"Hostname": null,
"Port": 0,
"DatabaseName": null,
"Username": "root",
"Password": "taosdata",
"InitialSql": null,
"TimeZone": null,
"PrintRows": false,
"UseWindowsAuth": false,
"SqlFetchBatchSize": 100000,
"UseSSL": false,
"JdbcProperties": null,
"GenericDatabaseConfig": {
"DatabaseJdbcUrl": "jdbc:TAOS-RS://gw.cloud.taosdata.com?useSSL=true&token=41ac9d61d641b6b334e8b76f45f5a8XXXXXXXXXX",
"SqlDriverClassName": "com.taosdata.jdbc.rs.RestfulDriver",
"ResolutionInNanoseconds": 1000,
"ZonedColumnTypes": []
}
}
```
### TDengine Cloud 作为数据源的 Seeq Workbench 界面示例
![Seeq workbench with TDengine cloud](./seeq/seeq-workbench-with-tdengine-cloud.webp)
## 方案总结
通过集成Seeq和TDengine，可以充分利用TDengine高效的存储和查询性能，同时也可以受益于Seeq提供给用户的强大数据可视化和分析功能。
这种集成使用户能够充分利用TDengine的高性能时序数据存储和检索，确保高效处理大量数据。同时，Seeq提供高级分析功能，如数据可视化、异常检测、相关性分析和预测建模，使用户能够获得有价值的洞察并基于数据进行决策。
综合来看，Seeq和TDengine共同为制造业、工业物联网和电力系统等各行各业的时序数据分析提供了综合解决方案。高效数据存储和先进的分析相结合，赋予用户充分发挥时序数据潜力的能力，推动运营改进，并支持预测和规划分析应用。
综合来看，Seeq 和 TDengine 共同为制造业、工业物联网和电力系统等各行各业的时序数据分析提供了综合解决方案。高效数据存储和先进的分析相结合，赋予用户充分发挥时序数据潜力的能力，推动运营改进，并支持预测和规划分析应用。

82
docs/zh/10-third-party/05-bi/11-superset.md vendored
View File

@ -4,38 +4,39 @@ title: 与 Superset 集成
---
‌Apache Superset‌ 是一个现代的企业级商业智能（BI）Web 应用程序，主要用于数据探索和可视化。它由 Apache 软件基金会支持，是一个开源项目，它拥有活跃的社区和丰富的生态系统。Apache Superset 提供了直观的用户界面，使得创建、分享和可视化数据变得简单，同时支持多种数据源和丰富的可视化选项‌。
通过 TDengine 的 Python 连接器, ‌Apache ‌Superset‌ 可支持 TDengine 数据源并提供数据展现、分析等功能
通过 TDengine 的 Python 连接器, ‌Apache ‌Superset‌ 可支持 TDengine 数据源并提供数据展现、分析等功能。
## 前置条件
准备以下环境：
- TDengine 集群已部署并正常运行（企业及社区版均可）
- taosAdapter 能够正常运行。详细参考 [taosAdapter 使用手册](../../../reference/components/taosadapter)
- Apache Superset v2.1.0 或以上版本已安装。安装 Apache Superset 请参考 [官方文档](https://superset.apache.org/)
- TDengine 3.2.3.0 及以上版本集群已部署并正常运行（企业及社区版均可）。
- taosAdapter 能够正常运行，详细参考 [taosAdapter 使用手册](../../../reference/components/taosadapter)。
- Apache Superset v2.1.0 或以上版本已安装，安装 Apache Superset 请参考 [官方文档](https://superset.apache.org/)。
- 安装 Python 连接器驱动，详细参考 [TDengine Python Connector](../../../reference/connector/python)。
## 安装 TDengine Python 连接器
TDengine Python 连接器从 `v2.1.18` 起带 Superset 连接驱动，会安装至 Superset 相应目录下并向 Superset 提供数据源服务
Superset 与 TDengine 之间使用 WebSocket 协议连接，需安装支持此协议的 `taos-ws-py` 组件, 全部安装脚本如下：
```bash
pip3 install taospy
pip3 install taos-ws-py
```
## 配置 TDengine 数据源
**第 1 步**，进入新建数据库连接页面 "Superset" → "Setting" → "Database Connections" → "+DATABASE"
**第 2 步**，选择 TDengine 数据库连接。"SUPPORTED DATABASES" 下拉列表中选择 "TDengine" 项。
:::tip
注意：若下拉列表中无 "TDengine" 项，请检查安装顺序，确保 `TDengine Python 连接器` 在 `Superset` 安装之后再安装。
TDengine Python 连接器从 `v2.1.18` 起带 Superset 连接驱动，会安装至 Superset 相应目录下并向 Superset 提供数据源服务。
:::
## 配置数据源
**第 1 步**，进入新建数据库连接页面【Superset】 -> 【Setting】->【Database Connections ->【+DATABASE】。
**第 2 步**，选择 TDengine 数据库连接。【SUPPORTED DATABASES】下拉列表中选择 `TDengine` 项。
:::tip
注意：若下拉列表中无 `TDengine` 项，请检查安装顺序，确保 `TDengine Python 连接器` 在 `Superset` 安装之后再安装。
:::
**第 3 步**，"DISPLAY NAME" 中填写连接名称，任意填写即可。
**第 4 步**，"SQLALCHEMY URL" 项为关键连接信息串，务必填写正确。
**第 3 步**，【DISPLAY NAME】中填写连接名称，任意填写即可。
**第 4 步**，【SQLALCHEMY URL】项为关键连接信息串，务必填写正确。
```bash
taosws://用户名:密码@主机名:端口号
```
| 参数名称 | <center>参数说明</center> |
|:------- |:-------------------------------- |
| 用户名 | 登录 TDengine 数据库用户名 |
@ -43,32 +44,33 @@ taosws://用户名:密码@主机名:端口号
| 主机名 | TDengine 数据库所在主机名称 |
| 端口号 | 提供 WebSocket 服务的端口，默认：6041 |
示例：
本机安装 TDengine 数据库，WebSocket 服务端口 6041，使用默认用户名密码，"SQLALCHEMY URL" 应为：
示例：
本机安装 TDengine 数据库，WebSocket 服务端口 6041，使用默认用户名密码，`SQLALCHEMY URL` 应为：
```bash
taosws://root:taosdata@localhost:6041
```
**第 5 步**，配置好连接串，点击 “TEST CONNECTION” 测试连接是否成功，测试通过后点击 “CONNECT” 按钮，完成连接。
**第 5 步**，配置好连接串，点击【TEST CONNECTION】测试连接是否成功，测试通过后点击【CONNECT】按钮，完成连接。
## 数据分析
## 开始使用
### 数据准备
TDengine 数据源与其它数据源使用上无差别，这里简单介绍下数据查询：
1. Superset 界面点击右上角 “+” 号按钮，选择 “SQL query”, 进入查询界面
2. 左上角 “DATABASE” 下拉列表中选择前面已创建好的 “TDengine” 数据源
3. “SCHEMA” 下拉列表，选择要操作的数据库名（系统库不显示）
4. “SEE TABLE SCHEMA” 选择要操作的超级表名或普通表名（子表不显示）
5. 随后会在下方显示选定表的 SCHEMA 信息
6. 在 SQL 编辑器区域可输入符合 TDengine 语法的任意 SQL 语句执行
TDengine 数据源与其它数据源使用上无差别，这里简单介绍下数据查询：
## 示例效果
1. `Superset` 界面点击右上角【+】号按钮，选择 `SQL query`, 进入查询界面。
2. 左上角【DATABASE】下拉列表中选择前面已创建好的 `TDengine` 数据源。
3. 【SCHEMA】下拉列表，选择要操作的数据库名（系统库不显示）。
4. 【SEE TABLE SCHEMA】选择要操作的超级表名或普通表名（子表不显示）。
5. 随后会在下方显示选定表的 `SCHEMA` 信息。
6. 在 `SQL` 编辑器区域可输入符合 `TDengine` 语法的任意 `SQL` 语句执行。
我们选择 Superset Chart 模板中较流行的两个模板做了效果展示，以智能电表数据为例：
### 智能电表样例
1. "Aggregate" 类型，展示在第 4 组中指定时间段内每分钟采集电压值(voltage)最大值
我们选择【Superset Chart】模板中较流行的两个模板做了效果展示，以智能电表数据为例：
![superset-demo1](./superset-demo1.jpeg)
2. "RAW RECORDS" 类型，展示在第 4 组中指定时间段内 current, voltage 的采集值
![superset-demo2](./superset-demo2.jpeg)
1. `Aggregate` 类型，展示在第 4 组中指定时间段内每分钟采集电压值(voltage)最大值。
![superset-demo1](./superset-demo1.jpeg)
2. `RAW RECORDS` 类型，展示在第 4 组中指定时间段内 current, voltage 的采集值。
![superset-demo2](./superset-demo2.jpeg)

32
docs/zh/10-third-party/05-bi/12-tableau.md vendored
View File

@ -3,33 +3,41 @@ sidebar_label: Tableau
title: 与 Tableau 集成
---
Tableau 是一款知名的商业智能工具，它支持多种数据源，可方便地连接、导入和整合数据。并且可以通过直观的操作界面，让用户创建丰富多样的可视化图表，并具备强大的分析和筛选功能，为数据决策提供有力支持。
Tableau 是一款知名的商业智能工具，它支持多种数据源，可方便地连接、导入和整合数据。并且可以通过直观的操作界面，让用户创建丰富多样的可视化图表，并具备强大的分析和筛选功能，为数据决策提供有力支持。用户可通过 TDengine ODBC Connector 将标签数据、原始时序数据或者经时间聚合后的时序数据从 TDengine 导入到 Tableau，用以制作报表或仪表盘，且整个过程无需编写任何代码。
## 前置条件
准备以下环境：
- TDengine 3.3.5.4以上版本集群已部署并正常运行（企业及社区版均可）
- taosAdapter 能够正常运行。详细参考 [taosAdapter 使用手册](../../../reference/components/taosadapter)
- Tableau 桌面版安装并运行（如未安装，请下载并安装 Windows 操作系统 32/64 位 [Tableau 桌面版](https://www.tableau.com/products/desktop/download) ）。安装 Tableau 桌面版请参考 [官方文档](https://www.tableau.com)。
- ODBC 驱动安装成功。详细参考[安装 ODBC 驱动](../../../reference/connector/odbc/#安装)
- ODBC 数据源配置成功。详细参考[配置ODBC数据源](../../../reference/connector/odbc/#配置数据源)
- TDengine 3.3.5.8 以上版本集群已部署并正常运行（企业及社区版均可）。
- taosAdapter 能够正常运行。详细参考 [taosAdapter 参考手册](../../../reference/components/taosadapter)。
- Tableau 桌面版安装并运行（如未安装，请下载并安装 Windows 操作系统 64 位 [Tableau 桌面版](https://www.tableau.com/products/desktop/download) ）。安装 Tableau 桌面版请参考 [官方文档](https://www.tableau.com)。
- 从 TDengine 官网下载最新的 Windows 操作系统 X64 客户端驱动程序，并进行安装。详细参考 [安装 ODBC 驱动](../../../reference/connector/odbc/#安装)。
## 加载和分析 TDengine 数据
**第 1 步**，在 Windows 系统环境下启动 Tableau，之后在其连接页面中搜索 “ODBC”，并选择 “其他数据库 (ODBC)”。
## 配置数据源
**第 2 步**，点击 DNS 单选框，接着选择已配置好的数据源(MyTDengine)，然后点击连接按钮。待连接成功后，删除字符串附加部分的内容，最后点击登录按钮即可。
**第 1 步**，在Windows操作系统的开始菜单中搜索并打开“ODBC数据源（64位）”管理工具并进行配置。详细参考[配置ODBC数据源](../../../reference/connector/odbc/#配置数据源)。
:::tip
需要注意的是，在为 Tableau 配置 ODBC 数据源时，TDengine ODBC 数据源配置页面中的【数据库】配置项为必填项，需选择一个可成功连接的数据库。
:::
**第 2 步**，在 Windows 系统环境下启动 Tableau，之后在其连接页面中搜索 “ODBC”，并选择 “其他数据库 (ODBC)”。 对于 Tableau 的使用的ODBC数据源，在其 TDengine ODBC 数据源配置页面的【数据库】的配置项为必填，需要选择可以连接的数据库。
**第 3 步**，点击 `DSN` 单选框，接着选择已配置好的数据源(MyTDengine)，然后点击`连接`按钮。待连接成功后，删除字符串附加部分的内容，最后点击`登录`按钮即可。
![tableau-odbc](./tableau/tableau-odbc.jpg)
**第 3 步**，在弹出的工作簿页面中，会显示已连接的数据源。点击数据库的下拉列表，会显示需要进行数据分析的数据库。在此基础上，点击表选项中的查找按钮，即可将该数据库下的所有表显示出来。然后，拖动需要分析的表到右侧区域，即可显示出表结构。
## 数据分析
**第 1 步**，在工作簿页面中，选择已连接的数据源。点击数据库的下拉列表，会显示需要进行数据分析的数据库。在此基础上，点击表选项中的查找按钮，即可将该数据库下的所有表显示出来。然后，拖动需要分析的表到右侧区域，即可显示出表结构。
![tableau-workbook](./tableau/tableau-table.jpg)
**第 4 步**，点击下方的"立即更新"按钮，即可将表中的数据展示出来。
**第 2 步**，点击下方的"立即更新"按钮，即可将表中的数据展示出来。
![tableau-workbook](./tableau/tableau-data.jpg)
**第 5 步**，点击窗口下方的"工作表"，弹出数据分析窗口， 并展示分析表的所有字段,将字段拖动到行列即可展示出图表。
**第 3 步**，点击窗口下方的"工作表"，弹出数据分析窗口， 并展示分析表的所有字段,将字段拖动到行列即可展示出图表。
![tableau-workbook](./tableau/tableau-analysis.jpg)

40
docs/zh/10-third-party/05-bi/13-excel.md vendored Normal file
View File

@ -0,0 +1,40 @@
---
sidebar_label: Excel
title: 与 Excel 集成
---
通过配置使用 ODBC 连接器，Excel 可以快速访问 TDengine 的数据。用户可以将标签数据、原始时序数据或按时间聚合后的时序数据从 TDengine 导入到 Excel，用以制作报表整个过程不需要任何代码编写过程。
## 前置条件
准备以下环境：
- TDengine 3.3.5.8 以上版本集群已部署并正常运行（企业及社区版均可）。
- taosAdapter 能够正常运行，详细参考 [taosAdapter 参考手册](../../../reference/components/taosadapter)。
- Excel 安装并运行, 如未安装，请下载并安装, 具体操作请参考 Microsoft 官方文档。
- 从 TDengine 官网下载最新的 Windows 操作系统 X64 客户端驱动程序并进行安装，详细参考 [安装 ODBC 驱动](../../../reference/connector/odbc/#安装)。
## 配置数据源
**第 1 步**，在 Windows 操作系统的开始菜单中搜索并打开【ODBC数据源（64位）】管理工具并进行配置。详细参考 [配置ODBC数据源](../../../reference/connector/odbc/#配置数据源)。
**第 2 步**，在 Windows 系统环境下启动 Excel，之后选择【数据】->【获取数据】->【自其他源】->【从ODBC】。
![excel-odbc](./excel/odbc-menu.jpg)
**第 3 步**，在弹出窗口的【数据源名称(DSN)】下拉列表中选择需要连接的数据源后，点击【确定】按钮。
![excel-odbc](./excel/odbc-select.jpg)
**第 4 步**，输入 TDengine 的用户名密码。
![excel-odbc](./excel/odbc-config.jpg)
**第 5 步**，在弹出的【导航器】对话框中，选择要加载的库表, 并点击【加载】完成数据加载。
![excel-odbc](./excel/odbc-load.jpg)
## 数据分析
选中导入的数据，在【插入】选项卡中选择柱状图，并且在右侧的【数据透视图】中配置数据字段。
![excel-odbc](./excel/odbc-data.jpg)

BIN
docs/zh/10-third-party/05-bi/excel/odbc-config.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 305 KiB

BIN
docs/zh/10-third-party/05-bi/excel/odbc-data.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 753 KiB

BIN
docs/zh/10-third-party/05-bi/excel/odbc-load.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.3 MiB

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