From 6fc4ec35372df9ec246bfbaf97f3d5b204d0e3cc Mon Sep 17 00:00:00 2001 From: Ruihang Xia Date: Wed, 22 Jan 2025 22:21:52 +0800 Subject: [PATCH 1/3] feat: a brief placeholder document for log-query endpoint Signed-off-by: Ruihang Xia --- docs/user-guide/query-data/log-query.md | 33 +++++++++++++++++++++++++ docs/user-guide/query-data/overview.md | 5 ++-- sidebars.ts | 1 + 3 files changed, 37 insertions(+), 2 deletions(-) create mode 100644 docs/user-guide/query-data/log-query.md diff --git a/docs/user-guide/query-data/log-query.md b/docs/user-guide/query-data/log-query.md new file mode 100644 index 000000000..905529b22 --- /dev/null +++ b/docs/user-guide/query-data/log-query.md @@ -0,0 +1,33 @@ +--- +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 processing 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/#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 diff --git a/docs/user-guide/query-data/overview.md b/docs/user-guide/query-data/overview.md index 4fc7e8028..229207176 100644 --- 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/sidebars.ts b/sidebars.ts index 86115a68d..ac31034d7 100644 --- 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'] }, From b3c95a9f910ae613acc09e2c11eeac70b0e5cad1 Mon Sep 17 00:00:00 2001 From: Ruihang Xia Date: Thu, 23 Jan 2025 11:30:25 +0800 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Yiran Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/user-guide/query-data/log-query.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/query-data/log-query.md b/docs/user-guide/query-data/log-query.md index 905529b22..8a5eab55c 100644 --- a/docs/user-guide/query-data/log-query.md +++ b/docs/user-guide/query-data/log-query.md @@ -5,9 +5,11 @@ description: Documentation for GreptimeDB's experimental log query endpoint, whi # Log Query (Experimental) -> Warning: The log query endpoint feature is currently experimental and may change in future releases. +::: 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 processing 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. +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 @@ -16,7 +18,7 @@ POST /v1/logs ``` ## Headers -- [Authorization](/user-guide/protocols/http/#authentication) +- [Authorization](/user-guide/protocols/http.md#authentication) - `Content-Type`: `application/json` ## Request Format From 9b7303201cbe413a34dd24c5e6bcd02fb3c8055e Mon Sep 17 00:00:00 2001 From: Ruihang Xia Date: Thu, 23 Jan 2025 11:43:22 +0800 Subject: [PATCH 3/3] add cURL example Signed-off-by: Ruihang Xia --- docs/user-guide/query-data/log-query.md | 69 +++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/docs/user-guide/query-data/log-query.md b/docs/user-guide/query-data/log-query.md index 8a5eab55c..311c0094e 100644 --- a/docs/user-guide/query-data/log-query.md +++ b/docs/user-guide/query-data/log-query.md @@ -33,3 +33,72 @@ This endpoint has the same response format as the SQL query endpoint. Please ref - 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. + +```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 +} +```