From 808dec1fdfc8a951eefee3f317d9447eb4f5f2af Mon Sep 17 00:00:00 2001 From: luofucong Date: Tue, 21 Mar 2023 13:32:46 +0800 Subject: [PATCH 1/6] docs: update "How to write gRPC SDK for GreptimeDB" --- .../how-to/how-to-write-sdk.md | 30 ++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/developer-guide/how-to/how-to-write-sdk.md b/docs/developer-guide/how-to/how-to-write-sdk.md index 0520fa6a9..0da1888ce 100644 --- a/docs/developer-guide/how-to/how-to-write-sdk.md +++ b/docs/developer-guide/how-to/how-to-write-sdk.md @@ -1,9 +1,37 @@ # How to write a gRPC SDK for GreptimeDB -GreptimeDB builds its gRPC interface on top of [Apache Arrow Flight](https://arrow.apache.org/docs/format/Flight.html). If you want to write a gRPC SDK for GreptimeDB in a programming language you are familiar with, read on! +There are two gRPC services exposed by GreptimeDB. One is defined by GreptimeDB, the other is built on top +of [Apache Arrow Flight](https://arrow.apache.org/docs/format/Flight.html). If you want to write a gRPC SDK for +GreptimeDB in a programming language you are familiar with, read on! > Currently, we only have gRPC SDK written in Java, and you can find more details [here](../user-guide/java-sdk.md). +## `GreptimeDatabase` Service + +GreptimeDB defines a custom gRPC service `GreptimeDatabase`. You can find its protobuf +definitions [here](https://github.com/GreptimeTeam/greptime-proto). It contains two RPC methods: + +```protobuf +service GreptimeDatabase { + rpc Handle(GreptimeRequest) returns (GreptimeResponse); + + rpc HandleRequests(stream GreptimeRequest) returns (GreptimeResponse); +} +``` + +The `Handle` method is for unary call: GreptimeDB server replies with a `GreptimeResponse` immediately after received +and handled a `GreptimeRequest`. + +The `HandleRequests` acts in +a "[Client streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#client-streaming-rpc)" style. It ingests a +stream of `GreptimeRequest`, and handles them on the fly. After all the requests are handled, it returns a +summarized `GreptimeResponse`. Through `HandleRequests`, we can achieve a very high throughput of requests handling. + +However, currently the `GreptimeDatabase` service can **only** handle insertion requests. For query requests, we need to +implement the [Apache Arrow Flight](https://arrow.apache.org/docs/format/Flight.html) gRPC client as well. + +## [Apache Arrow Flight](https://arrow.apache.org/docs/format/Flight.html) Service + First, you can find our protobuf definitions for GreptimeDB requests and responses in this [repo](https://github.com/GreptimeTeam/greptime-proto#for-sdk-developers). The section named "For SDK developers" in the README of that repo is worth reading. Then check your programming language to see whether Arrow Flight RPC officially supports it. Currently, it supports C++, Java, Go, C# and Rust and might add more supported languages, so stay tuned with its [Implementation Status](https://arrow.apache.org/docs/status.html#flight-rpc). If you can't find the language you are using, you have to write a client from sketch (starting from Arrow Flight's raw gRPC service protobuf [definition](https://arrow.apache.org/docs/format/Flight.html#protocol-buffer-definitions)). From b61d111f33f802dddca8424fadd0ec9476321020 Mon Sep 17 00:00:00 2001 From: LFC Date: Wed, 22 Mar 2023 17:17:01 +0800 Subject: [PATCH 2/6] Update docs/developer-guide/how-to/how-to-write-sdk.md Co-authored-by: xiaomin tang --- docs/developer-guide/how-to/how-to-write-sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-guide/how-to/how-to-write-sdk.md b/docs/developer-guide/how-to/how-to-write-sdk.md index 0da1888ce..5132fc44c 100644 --- a/docs/developer-guide/how-to/how-to-write-sdk.md +++ b/docs/developer-guide/how-to/how-to-write-sdk.md @@ -8,7 +8,7 @@ GreptimeDB in a programming language you are familiar with, read on! ## `GreptimeDatabase` Service -GreptimeDB defines a custom gRPC service `GreptimeDatabase`. You can find its protobuf +GreptimeDB defines a custom gRPC service called `GreptimeDatabase`. You can find its protobuf definitions [here](https://github.com/GreptimeTeam/greptime-proto). It contains two RPC methods: ```protobuf From 5b8122f5ac5326d65e1418b212d81d8f325e09b2 Mon Sep 17 00:00:00 2001 From: LFC Date: Wed, 22 Mar 2023 17:17:34 +0800 Subject: [PATCH 3/6] Update docs/developer-guide/how-to/how-to-write-sdk.md Co-authored-by: xiaomin tang --- docs/developer-guide/how-to/how-to-write-sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-guide/how-to/how-to-write-sdk.md b/docs/developer-guide/how-to/how-to-write-sdk.md index 5132fc44c..772459442 100644 --- a/docs/developer-guide/how-to/how-to-write-sdk.md +++ b/docs/developer-guide/how-to/how-to-write-sdk.md @@ -19,7 +19,7 @@ service GreptimeDatabase { } ``` -The `Handle` method is for unary call: GreptimeDB server replies with a `GreptimeResponse` immediately after received +The `Handle` method is for unary call: When a `GreptimeRequest` is received and processed by the GreptimeDB and handled a `GreptimeRequest`. The `HandleRequests` acts in From 5acc5e6161dfd94252d9dde5a2f014265cb1d97f Mon Sep 17 00:00:00 2001 From: LFC Date: Wed, 22 Mar 2023 17:17:56 +0800 Subject: [PATCH 4/6] Update docs/developer-guide/how-to/how-to-write-sdk.md Co-authored-by: xiaomin tang --- docs/developer-guide/how-to/how-to-write-sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-guide/how-to/how-to-write-sdk.md b/docs/developer-guide/how-to/how-to-write-sdk.md index 772459442..bb2a13ab3 100644 --- a/docs/developer-guide/how-to/how-to-write-sdk.md +++ b/docs/developer-guide/how-to/how-to-write-sdk.md @@ -20,7 +20,7 @@ service GreptimeDatabase { ``` The `Handle` method is for unary call: When a `GreptimeRequest` is received and processed by the GreptimeDB -and handled a `GreptimeRequest`. +server, it responds with a `GreptimeResponse` immediately. The `HandleRequests` acts in a "[Client streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#client-streaming-rpc)" style. It ingests a From c8325d9aeabf7512565d5974c1e67351d0fb9432 Mon Sep 17 00:00:00 2001 From: LFC Date: Wed, 22 Mar 2023 17:18:12 +0800 Subject: [PATCH 5/6] Update docs/developer-guide/how-to/how-to-write-sdk.md Co-authored-by: xiaomin tang --- docs/developer-guide/how-to/how-to-write-sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-guide/how-to/how-to-write-sdk.md b/docs/developer-guide/how-to/how-to-write-sdk.md index bb2a13ab3..43b46a500 100644 --- a/docs/developer-guide/how-to/how-to-write-sdk.md +++ b/docs/developer-guide/how-to/how-to-write-sdk.md @@ -24,7 +24,7 @@ server, it responds with a `GreptimeResponse` immediately. The `HandleRequests` acts in a "[Client streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#client-streaming-rpc)" style. It ingests a -stream of `GreptimeRequest`, and handles them on the fly. After all the requests are handled, it returns a +stream of `GreptimeRequest`, and handles them on the fly. After all the requests have been handled, it returns a summarized `GreptimeResponse`. Through `HandleRequests`, we can achieve a very high throughput of requests handling. However, currently the `GreptimeDatabase` service can **only** handle insertion requests. For query requests, we need to From d755b9ce560e9b54d9e7daa5fe562af23d6b0c1f Mon Sep 17 00:00:00 2001 From: LFC Date: Wed, 22 Mar 2023 17:18:22 +0800 Subject: [PATCH 6/6] Update docs/developer-guide/how-to/how-to-write-sdk.md Co-authored-by: xiaomin tang --- docs/developer-guide/how-to/how-to-write-sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-guide/how-to/how-to-write-sdk.md b/docs/developer-guide/how-to/how-to-write-sdk.md index 43b46a500..3049d9e3a 100644 --- a/docs/developer-guide/how-to/how-to-write-sdk.md +++ b/docs/developer-guide/how-to/how-to-write-sdk.md @@ -27,7 +27,7 @@ a "[Client streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#clien stream of `GreptimeRequest`, and handles them on the fly. After all the requests have been handled, it returns a summarized `GreptimeResponse`. Through `HandleRequests`, we can achieve a very high throughput of requests handling. -However, currently the `GreptimeDatabase` service can **only** handle insertion requests. For query requests, we need to +However, currently the `GreptimeDatabase` service can **only** handle insert requests. For query requests, we need to implement the [Apache Arrow Flight](https://arrow.apache.org/docs/format/Flight.html) gRPC client as well. ## [Apache Arrow Flight](https://arrow.apache.org/docs/format/Flight.html) Service