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..311c0094e --- /dev/null +++ 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. + +```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 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'] },