add influxdb doc (#65)

* influxql doc. * add default time column related config. * address CR. * add more notes * add cn docs * polish --------- Co-authored-by: jiacai2050 <dev@liujiacai.net>
apache · Mar 29, 2023 · 4d0d43f · 4d0d43f
1 parent 3eee9fa
commit 4d0d43f
Show file tree

Hide file tree

Showing 5 changed files with 163 additions and 0 deletions.
diff --git a/docs/src/cn/SUMMARY.md b/docs/src/cn/SUMMARY.md
@@ -40,6 +40,7 @@
   - [集群运维](operation/cluster.md)
 - [周边生态](ecosystem/README.md)
   - [Prometheus](ecosystem/prometheus.md)
+  - [InfluxDB](ecosystem/influxdb.md)
 
 # 开发者手册
 

diff --git a/docs/src/cn/ecosystem/influxdb.md b/docs/src/cn/ecosystem/influxdb.md
@@ -0,0 +1,80 @@
+# InfluxDB
+
+[InfluxDB](https://www.influxdata.com/products/influxdb-overview/) 是一个时间序列数据库，旨在处理高写入和查询负载。它是 TICK 堆栈的一个组成部分。InfluxDB 旨在用作涉及大量时间戳数据的任何用例的后备存储，包括 DevOps 监控、应用程序指标、物联网传感器数据和实时分析。
+
+CeresDB 支持 [InfluxDB v1.8](https://docs.influxdata.com/influxdb/v1.8/tools/api/#influxdb-1x-http-endpoints) 写入和查询 API。
+
+> 注意：用户需要将以下配置添加到服务器的配置中才能尝试 InfluxDB 写入/查询。
+
+```
+[server.default_schema_config]
+default_timestamp_column_name = "time"
+```
+
+# 写入
+
+```
+curl -i -XPOST "http://localhost:5440/influxdb/v1/write" --data-binary '
+demo,tag1=t1,tag2=t2 field1=90,field2=100 1679994647000
+demo,tag1=t1,tag2=t2 field1=91,field2=101 1679994648000
+demo,tag1=t11,tag2=t22 field1=90,field2=100 1679994647000
+demo,tag1=t11,tag2=t22 field1=91,field2=101 1679994648000
+'
+```
+
+Post 的内容采用的是 [InfluxDB line protocol](https://docs.influxdata.com/influxdb/v1.8/write_protocols/line_protocol_reference/) 格式。
+
+`measurement` 将映射到 CeresDB 中的一个表，在首次写入时 server 会自动进行建表。
+
+例如，在上面插入数据时，CeresDB 中将创建下表：
+
+```
+CREATE TABLE `demo` (
+    `tsid` uint64 NOT NULL,
+    `timestamp` timestamp NOT NULL,
+    `field1` double,
+    `field2` double,
+    `tag1` string TAG,
+    `tag2` string TAG,
+    PRIMARY KEY (tsid, timestamp),
+    timestamp KEY (timestamp))
+```
+
+## 注意事项
+
+- 暂时不支持诸如 `precision`， `db` 等查询参数
+
+# 查询
+
+```sh
+ curl -G 'http://localhost:5440/influxdb/v1/query' --data-urlencode 'q=SELECT * FROM "demo"'
+```
+
+查询结果和 InfluxDB 查询接口一致：
+
+```json
+{
+  "results": [
+    {
+      "statement_id": 0,
+      "series": [
+        {
+          "name": "demo",
+          "columns": ["time", "field1", "field2", "tag1", "tag2"],
+          "values": [
+            [1679994647000, 90.0, 100.0, "t1", "t2"],
+            [1679994647000, 90.0, 100.0, "t11", "t22"],
+            [1679994648000, 91.0, 101.0, "t1", "t2"],
+            [1679994648000, 91.0, 101.0, "t11", "t22"]
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 注意事项
+
+1. 暂时不支持诸如 `epoch`, `db` 等的查询参数
+2. 暂时不支持聚合查询，将在下一个版本中支持
diff --git a/docs/src/en/SUMMARY.md b/docs/src/en/SUMMARY.md
@@ -40,6 +40,7 @@
   - [Cluster](operation/cluster.md)
 - [Ecosystem](ecosystem/README.md)
   - [Prometheus](ecosystem/prometheus.md)
+  - [InfluxDB](ecosystem/influxdb.md)
 
 # Dev Guide
 

diff --git a/docs/src/en/ecosystem/README.md b/docs/src/en/ecosystem/README.md
@@ -5,3 +5,4 @@ CeresDB has an open ecosystem that encourages collaboration and innovation, allo
 Currently following systems are supported:
 
 - [Prometheus](prometheus.md)
+- [InfluxDB](influxdb.md)
diff --git a/docs/src/en/ecosystem/influxdb.md b/docs/src/en/ecosystem/influxdb.md
@@ -0,0 +1,80 @@
+# InfluxDB
+
+[InfluxDB](https://www.influxdata.com/products/influxdb-overview/) is a time series database designed to handle high write and query loads. It is an integral component of the TICK stack. InfluxDB is meant to be used as a backing store for any use case involving large amounts of timestamped data, including DevOps monitoring, application metrics, IoT sensor data, and real-time analytics.
+
+CeresDB support [InfluxDB v1.8](https://docs.influxdata.com/influxdb/v1.8/tools/api/#influxdb-1x-http-endpoints) write and query API.
+
+> Warn: users need to add following config to server's config in order to try InfluxDB write/query.
+
+```toml
+[server.default_schema_config]
+default_timestamp_column_name = "time"
+```
+
+# Write
+
+```shell
+curl -i -XPOST "http://localhost:5440/influxdb/v1/write" --data-binary '
+demo,tag1=t1,tag2=t2 field1=90,field2=100 1679994647000
+demo,tag1=t1,tag2=t2 field1=91,field2=101 1679994648000
+demo,tag1=t11,tag2=t22 field1=90,field2=100 1679994647000
+demo,tag1=t11,tag2=t22 field1=91,field2=101 1679994648000
+'
+```
+
+Post payload is in [InfluxDB line protocol](https://docs.influxdata.com/influxdb/v1.8/write_protocols/line_protocol_reference/) format.
+
+Measurement will be mapped to table in CeresDB, and it will be created automatically in first write.
+
+For example, when inserting data above, table below will be automatically created in CeresDB:
+
+```sql
+CREATE TABLE `demo` (
+    `tsid` uint64 NOT NULL,
+    `timestamp` timestamp NOT NULL,
+    `field1` double,
+    `field2` double,
+    `tag1` string TAG,
+    `tag2` string TAG,
+    PRIMARY KEY (tsid, timestamp),
+    timestamp KEY (timestamp))
+```
+
+## Note
+
+- Query string parameters such as `precision`, `db` aren't supported.
+
+# Query
+
+```shell
+ curl -G 'http://localhost:5440/influxdb/v1/query' --data-urlencode 'q=SELECT * FROM "demo"'
+```
+
+Query result is same with InfluxDB:
+
+```json
+{
+  "results": [
+    {
+      "statement_id": 0,
+      "series": [
+        {
+          "name": "demo",
+          "columns": ["time", "field1", "field2", "tag1", "tag2"],
+          "values": [
+            [1679994647000, 90.0, 100.0, "t1", "t2"],
+            [1679994647000, 90.0, 100.0, "t11", "t22"],
+            [1679994648000, 91.0, 101.0, "t1", "t2"],
+            [1679994648000, 91.0, 101.0, "t11", "t22"]
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Note
+
+1. Query string parameters such as `epoch`, `db`, `pretty` aren't supported.
+2. We don't support aggregator/group by now, will support those in next release.