feat: a brief placeholder document for log-query endpoint (#1489)

Signed-off-by: Ruihang Xia <[email protected]> Co-authored-by: Yiran <[email protected]> Co-authored-by: Copilot <[email protected]> Co-authored-by: jeremyhi <[email protected]>
GreptimeTeam · Feb 27, 2025 · 1d14278 · 1d14278
1 parent 9b2f15f
commit 1d14278
Show file tree

Hide file tree

Showing 5 changed files with 213 additions and 2 deletions.
diff --git a/docs/user-guide/query-data/log-query.md b/docs/user-guide/query-data/log-query.md
@@ -0,0 +1,104 @@
+---
+keywords: [log query, logs, search, experimental, HTTP endpoint]
+description: Documentation for GreptimeDB's experimental log query endpoint, which provides a dedicated HTTP interface for searching and processing log data.
+---
+
+# Log Query (Experimental)
+
+::: warning
+The log query endpoint feature is currently experimental and may change in future releases.
+:::
+
+GreptimeDB provides a dedicated HTTP endpoint to query log data. This feature allows you to search and process log entries using a simple query interface. This is an add-on feature to existing GreptimeDB capabilities like SQL queries and Flow computations. You can still use your existing tools and workflows to query log data like before.
+
+## Endpoint
+
+```http
+POST /v1/logs
+```
+
+## Headers
+- [Authorization](/user-guide/protocols/http.md#authentication)
+- `Content-Type`: `application/json`
+
+## Request Format
+
+The request body should be a JSON object (this is subject to change in patch version within the experimental phase). For the latest request format, please refer to the [implementation](https://github.com/GreptimeTeam/greptimedb/blob/main/src/log-query/src/log_query.rs):
+
+## Response
+
+This endpoint has the same response format as the SQL query endpoint. Please refer to the [SQL query response](/user-guide/protocols/http/#response) for more details.
+
+## Limitations
+
+- Maximum result limit: 1000 entries
+- Only supports tables with timestamp and string columns
+
+## Example
+
+The following example demonstrates how to query log data using the log query endpoint (notice that in this experimental phase the following example might be outdated).
+
+```shell
+curl -X "POST" "http://localhost:4000/v1/logs" \
+    -H "Content-Type: application/json" \
+    -d $'
+    {
+        "table": {
+            "catalog_name": "greptime",
+            "schema_name": "public",
+            "table_name": "my_logs"
+        },
+        "time_filter": {
+            "start": "2025-01-23"
+        },
+        "limit": {
+            "fetch": 1
+        },
+        "columns": [
+            "message"
+        ],
+        "filters": [
+            {
+                "column_name": "message",
+                "filters": [
+                    {
+                       "Contains": "production"
+                    }
+                ]
+            }
+        ],
+        "context": "None",
+        "exprs": []
+    }
+'
+```
+
+In this query, we are searching for log entries in the `greptime.public.my_logs` table that contain the word `production` in `message` field. We also specify the time filter to fetch logs in `2025-01-23`, and limit the result to 1 entry.
+
+The response will be similar to the following:
+
+```json
+{
+  "output": [
+    {
+      "records": {
+        "schema": {
+          "column_schemas": [
+            {
+              "name": "message",
+              "data_type": "String"
+            }
+          ]
+        },
+        "rows": [
+          [
+            "Everything is in production"
+          ]
+        ],
+        "total_rows": 1
+      }
+    }
+  ],
+  "execution_time_ms": 30
+}
+```
diff --git a/docs/user-guide/query-data/overview.md b/docs/user-guide/query-data/overview.md
@@ -1,6 +1,6 @@
 ---
-keywords: [query languages, PromQL, SQL, views, CTE, query libraries, external data]
-description: Overview of query languages supported by GreptimeDB, including PromQL and SQL, and recommended libraries for querying data.
+keywords: [query languages, PromQL, SQL, views, CTE, query libraries, external data, log query]
+description: Overview of query languages and features supported by GreptimeDB, including PromQL, SQL, and log query capabilities.
 ---
 
 # Overview
@@ -9,6 +9,7 @@ description: Overview of query languages supported by GreptimeDB, including Prom
 
 - [PromQL](./promql.md)
 - [SQL](./sql.md)
+- [Log Query](./log-query.md) (Experimental)
 
 Since v0.9, GreptimeDB supports view and CTE just like other databases, used to simplify queries:
 

diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/query-data/log-query.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/query-data/log-query.md
@@ -0,0 +1,104 @@
+---
+keywords: [日志查询, 日志, 搜索, 实验功能, HTTP 接口]
+description: GreptimeDB 实验性日志查询接口的说明文档，该接口提供了专门用于搜索和处理日志数据的 HTTP 服务。
+---
+
+# 日志查询（实验功能）
+
+::: warning
+日志查询接口目前仍处于实验阶段，在未来的版本中可能会有所调整。
+:::
+
+GreptimeDB 提供了一个专门用于查询日志数据的 HTTP 接口。通过这个功能，你可以使用简单的查询界面来搜索和处理日志记录。这是对 GreptimeDB 现有功能（如 SQL 查询和 Flow 计算）的补充。你仍然可以像之前一样使用已有的工具和工作流程来查询日志数据。
+
+## 接口地址
+
+```http
+POST /v1/logs
+```
+
+## 请求头
+- [认证](/user-guide/protocols/http.md#authentication)
+- `Content-Type`: `application/json`
+
+## 请求格式
+
+请求体应为 JSON 格式（在实验阶段可能会随补丁版本有所变化）。关于最新的请求格式，请参考[源代码实现](https://github.com/GreptimeTeam/greptimedb/blob/main/src/log-query/src/log_query.rs)：
+
+## 响应格式
+
+此接口的响应格式与 SQL 查询接口相同。详情请参阅 [SQL 查询响应格式](/user-guide/protocols/http/#response)。
+
+## 使用限制
+
+- 最大结果数量：1000 条记录
+- 仅支持包含时间戳和字符串列的表格
+
+## 使用示例
+
+以下示例展示了如何使用日志查询接口来查询日志数据（请注意，在实验性阶段这个例子可能会失效）：
+
+```shell
+curl -X "POST" "http://localhost:4000/v1/logs" \
+    -H "Content-Type: application/json" \
+    -d $'
+    {
+        "table": {
+            "catalog_name": "greptime",
+            "schema_name": "public",
+            "table_name": "my_logs"
+        },
+        "time_filter": {
+            "start": "2025-01-23"
+        },
+        "limit": {
+            "fetch": 1
+        },
+        "columns": [
+            "message"
+        ],
+        "filters": [
+            {
+                "column_name": "message",
+                "filters": [
+                    {
+                       "Contains": "production"
+                    }
+                ]
+            }
+        ],
+        "context": "None",
+        "exprs": []
+    }
+'
+```
+
+在这个查询中，我们在 `greptime.public.my_logs` 表中搜索 `message` 字段包含 `production` 的日志记录。我们还设定了时间过滤条件，只获取 `2025-01-23` 当天的日志，并将结果限制为仅返回 1 条记录。
+
+响应结果类似于以下内容：
+
+```json
+{
+  "output": [
+    {
+      "records": {
+        "schema": {
+          "column_schemas": [
+            {
+              "name": "message",
+              "data_type": "String"
+            }
+          ]
+        },
+        "rows": [
+          [
+            "Everything is in production"
+          ]
+        ],
+        "total_rows": 1
+      }
+    }
+  ],
+  "execution_time_ms": 30
+}
+```
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/query-data/overview.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/query-data/overview.md
@@ -9,6 +9,7 @@ description: 介绍 GreptimeDB 支持的查询语言和推荐的查询库。
 
 - [SQL](./sql.md)
 - [PromQL](promql.md)
+- [Log Query](./log-query.md) (实验性功能)
 
 从 v0.9 开始， GreptimeDB 开始支持查询视图和公共表表达式（CTE），用于简化查询语句：
 

diff --git a/sidebars.ts b/sidebars.ts
@@ -96,6 +96,7 @@ const sidebars: SidebarsConfig = {
             'user-guide/query-data/view',
             'user-guide/query-data/cte',
             'user-guide/query-data/query-external-data',
+            'user-guide/query-data/log-query',
           ],
         },
         { type: 'category', label: 'Manage Data', items: ['user-guide/manage-data/overview', 'user-guide/manage-data/data-index'] },