From b49870ddfbf7a782c915fd36b7591776ba7abb14 Mon Sep 17 00:00:00 2001
From: Maaz Ahmed <maaz.a@subcom.tech>
Date: Tue, 19 Dec 2023 11:58:51 +0530
Subject: [PATCH] doc: update README
---
README.md | 20 ++++++++++++++++++--
1 file changed, 18 insertions(+), 2 deletions(-)
diff --git a/README.md b/README.md
index 87bccb2..aabe234 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,13 @@
# mquery
-A Rust library for handling PROMQL (and possibly MetricsQL) queries.
+`mquery`, short for (M)etrics Query, is a Rust library for handling PROMQL (and possibly MetricsQL) queries.
+
+The library internally uses `prometheus-http-query` crate. As the name suggests, mquery is mainly focused on dealing with metrics queries and the resulting data, and nothing else. The aforementioned library is better suited when functionality related to the full HTTP API offered by Prometheus and other compatible solutions is required.
+
+The library supports raw queries (strings) as well as typed queries (builder API). The builder API is provided through the type `Metric` and `Scalar` types found in the `query` module. Note that the builder API doesn't prevent you from writing invalid queries, it only helps you avoid errors to a certain degree.
+
+Any additional utilities related to handling and processing the query data can be found in the `utils` module which is placed under the `utils` feature flag.
+
+A compile time query validation like the one found in the `sqlx` crate is on the roadmap.
## Usage Example
```rust
@@ -20,6 +28,9 @@ async fn main() {
.expect("operation failed");
}
```
+# Debugging
+When you keep getting the error `Client(ClientError("failed to parse response from server due to invalid media type"))` and cannot figure out what might be wrong, it is likely that the server URL is the culprit. Ensure that only the base URL to the server is passed to the `QueryManager` which shouldn't contain the API endpoint path like `/api/v1/query`.
+
# Testing
Requires a local Victoria Metrics server running at `http://127.0.0.1:8428/` for the integration tests to work.
@@ -28,8 +39,13 @@ Requires a local Victoria Metrics server running at `http://127.0.0.1:8428/` for
- [ ] Query Builder
- [x] Basic queries
- [ ] Operators
+ - [x] Binary Operators
+ - [x] Vector matching
+ - [ ] Aggregation operators
- [ ] Functions
- [ ] Runtime syntax checking
- [ ] Compile time syntax checking
-- [ ] Deserialize to custom data types (with the help of proc-macros?)
+- [x] ~~Deserialize~~ Convert to custom data types
+- [ ] ORM-like API to build queries using user defined types (derive macro)
- [ ] Encapsulated raw queries with methods for constructing interpolated versions
+- [ ] Processing multiple queries at once
--
GitLab