跳到主要内容
版本:nightly

如何为 GreptimeDB 开发一个 gRPC SDK

GreptimeDB 的 gRPC SDK 只需要处理写请求即可。读请求是标准 SQL 或 PromQL ,可以由任何 JDBC 客户端或 Prometheus 客户端处理。这也是为什么所有的 GreptimeDB SDK 都命名为 "greptimedb-ingester-<language>"。请确保你的 GreptimeDB SDK 遵循相同的命名约定。

GreptimeDatabase 服务

GreptimeDB 自定义了一个 gRPC 服务:GreptimeDatabase 。你只需要实现这个服务即可。你可以在这里 找到它的 Protobuf 定义。

GreptimeDatabase 有 2 个 RPC 方法:

service GreptimeDatabase {
rpc Handle(GreptimeRequest) returns (GreptimeResponse);

rpc HandleRequests(stream GreptimeRequest) returns (GreptimeResponse);
}

Handle 方法是一个 unary 调用:当 GreptimeDB 服务接收到一个 GreptimeRequest 请求后,它立刻处理该请求并返回一个相应的 GreptimeResponse

HandleRequests 方法则是一个 "[Client Streaming RPC][3]" 方式的调用。 它可以接受一个连续的 GreptimeRequest 请求流,持续地发给 GreptimeDB 服务。 GreptimeDB 服务会在收到流中的每个请求时立刻进行处理,并最终(流结束时)返回一个总结性的 GreptimeResponse。 通过 HandleRequests,我们可以获得一个非常高的请求吞吐量。

GreptimeRequest

GreptimeRequest 是一个 Protobuf 消息,定义如下:

message GreptimeRequest {
RequestHeader header = 1;
oneof request {
InsertRequests inserts = 2;
QueryRequest query = 3;
DdlRequest ddl = 4;
DeleteRequests deletes = 5;
RowInsertRequests row_inserts = 6;
RowDeleteRequests row_deletes = 7;
}
}

RequestHeader 是必需,它包含了一些上下文,鉴权和其他信息。"oneof" 的字段包含了发往 GreptimeDB 服务的请求。

注意我们有两种类型的插入请求,一种是以 "列" 的形式(InsertRequests),另一种是以 "行" 的形式(RowInsertRequests )。通常我们建议使用 "行" 的形式,因为它对于表的插入更自然,更容易使用。但是,如果需要一次插入大量列,或者有大量的 "null" 值需要插入,那么最好使用 "列" 的形式。

GreptimeResponse

GreptimeResponse 是一个 Protobuf 消息,定义如下:

message GreptimeResponse {
ResponseHeader header = 1;
oneof response {AffectedRows affected_rows = 2;}
}

ResponseHeader 包含了返回值的状态码,以及错误信息(如果有的话)。"oneof" 的字段目前只有 "affected rows"。

GreptimeDB 现在有很多 SDK,你可以参考这里获取一些示例。