Client Design

openGemini2024年6月30日大约 4 分钟约 1232 字

背景

由于Influxdb 1.X的客户端已经基本处于维护状态，同时openGemini仍在不断发展中，为了能够更好地支持openGemini，如支持对接多个服务端地址、支持对接Apache Arrow Flight协议等，社区决定开发属于openGemini自己的客户端SDK。

客户端SDK规划功能

  • 支持对接多个服务端地址
  • 支持对接Apache Arrow Flight协议
  • 支持Sql查询、结构化查询、写入、批量写入等，详见下文UML图
  • 默认超时，连接超时10秒，读写超时30秒

本文的方法假定编程语言不支持重载，如编程语言支持重载，可以对方法名进行一些优化调整。

客户端构造参数设计

contains
1
many
contains
contains
OpenGeminiClient
+ List<Address> addresses
+ AuthConfig authConfig // nullable, if null, means no auth
+ BatchConfig batchConfig // nullable, if null, means batch is disabled
+ timeout
+ connectTimeout
+ enum contentType // json, csv, msgpack
+ enum compressMethod // gzip, zstd, br
+ TlsConfig tlsConfig // nullable, language specific
+ GrpcConfig grpcConfig // if null, call WriteByGrpc will nothing to do, otherwise send write request by gRPC
+void close()
Address
+ String host
+ int Port // in rust, it is u16
AuthConfig
+ AuthType authType // enum Password, Token. The server currently does not support the Token type, and the SDK implementation for Token is incomplete.
+ String username
+ String password
+ String token
BatchConfig
+ Duration batchInterval // must be greater than 0
+ int batchSize // must be greater than 0
GrpcConfig
+ List<Address> addresses
+ AuthConfig authConfig
+ BatchConfig batchConfig
+ enum compressMethod // gzip, zstd, br
+ TlsConfig tlsConfig
+ timeout

Database & RetentionPolicy管理设计

OpenGeminiClient
+void CreateDatabase(String database)
+void CreateDatabaseWithRp(String database, rpConfig RpConfig)
+String[] ShowDatabases()
+void DropDatabase(String database)
+void CreateRetentionPolicy(String database, RpConfig rpConfig, bool isDefault)
+void UpdateRetentionPolicy(String database, RpConfig rpConfig, bool isDefault)
+RetentionPolicy[] ShowRetentionPolicies(String database)
+void DropRetentionPolicy(String database, String retentionPolicy)
+void CreateMeasurement(CreateMeasurementBuilder builder)
+String[] ShowMeasurements(ShowMeasurementBuilder builder)
+void DropMeasurement(String database, String retentionPolicy, String measurement)
+Map[String]String[] ShowTagKeys(ShowTagKeysBuilder builder)
+String[] ShowTagValues(ShowTagValuesBuilder builder)
+Map[String]Map[String]String ShowFieldKeys(String database, Option measurement)
+String[] ShowSeries(ShowSeriesBuilder builder)
RpConfig
+ String Name // non-null
+ String Duration // non-null
+ String ShardGroupDuration // nullable
+ String IndexDuration // nullable
CreateMeasurementBuilder
+CreateMeasurementBuilder Tags(String[] tags)
+CreateMeasurementBuilder FieldMap(map[String]FieldType fields)
+CreateMeasurementBuilder ShardType(ShardType shardType)
+CreateMeasurementBuilder ShardKeys(String[] shardKeys)
+CreateMeasurementBuilder FullTextIndex()
+CreateMeasurementBuilder IndexList(String[] indexes)
+CreateMeasurementBuilder EngineType(EngineType engineType)
+CreateMeasurementBuilder PrimaryKey(String[] primaryKeys)
+CreateMeasurementBuilder SortKeys(String[] sortKeys)
+String build()
ShowMeasurementBuilder
+ShowMeasurementBuilder Filter(ComparisonOperator operator, String regex)
+String build()
«enum»
FieldType
Bool // BOOL
Int64 // INT64
Float64 // FLOAT64
String // STRING
«enum»
ShardType
Hash // HASH
Range // RANGE
«enum»
EngineType
ColumnStore // columnstore
ShowTagKeysBuilder
ShowTagKeysBuilder Database(String database)
ShowTagKeysBuilder Measurement(String measurement)
ShowTagKeysBuilder RetentionPolicy(String rp)
ShowTagKeysBuilder Limit(int limit)
ShowTagKeysBuilder Offset(int offset)
ShowTagValuesBuilder
ShowTagValuesBuilder Database(String database)
ShowTagValuesBuilder Measurement(String measurement)
ShowTagValuesBuilder RetentionPolicy(String rp)
ShowTagValuesBuilder Limit(int limit)
ShowTagValuesBuilder Offset(int offset)
ShowTagValuesBuilder With(String[] keys)
ShowTagValuesBuilder Where(String key, ComparisonOperator operator, String value)
ShowSeriesBuilder
ShowSeriesBuilder Database(String database)
ShowSeriesBuilder Measurement(String measurement)
ShowSeriesBuilder RetentionPolicy(String rp)
ShowSeriesBuilder Limit(int limit)
ShowSeriesBuilder Offset(int offset)
ShowTagValuesBuilder Where(String key, ComparisonOperator operator, String value)

写入点位设计

查询设计

Query
+ String database
+ String retentionPolicy
+ String command

查询构造器设计

QueryBuilder
+static Create() : QueryBuilder
+Select(Expression[] selectExprs) : QueryBuilder
+From(String[] from) : QueryBuilder
+Where(Condition where) : QueryBuilder
+GroupBy(Expression[] groupByExpressions) : QueryBuilder
+OrderBy(order: SortOrder) : QueryBuilder
+Limit(limit: int64) : QueryBuilder
+Offset(offset: int64) : QueryBuilder
+Timezone(timezone: *time.Location) : QueryBuilder
+Build() : Query
«interface»
Expression
ConstantExpression
- Object value
StarExpression
FunctionExpression
- FunctionEnum function
- Expression[] arguments
AsExpression
- String alias
- Expression expression
ArithmeticExpression
- Expression Left
- Expression Right
- Operator ArithmeticOperator
«interface»
Condition
ComparisonCondition
- String column
- ComparisonOperator operator
- Object value
CompositeCondition
- LogicalOperator logicalOperator
- Condition[] conditions
«enum»
SortOrder
Asc
Desc
«enum»
ComparisonOperator
Equals
NotEquals
GreaterThan
LessThan
GreaterThanOrEquals
LessThanOrEquals
«enum»
LogicalOperator
And
Or
«enum»
FunctionEnum
Mean
Count
Sum
Min
Max
Time
FieldExpression
Query

Ping 设计

OpenGeminiClient
+Pong ping(int index) : // index selects one from multiple servers
Pong
+ String version

Inner Http client 设计

使用类似InnerHttpClient的设计，将鉴权、负载均衡、重试等逻辑封装在内部，对client提供简单的接口。增强模块化和代码清晰度。

InnerHttpClient
+void executeHttpGetByIdx(int idx, ...) : // specify server index
+void executeHttpRequestByIdx(int idx, String method, ...) : // specify server index
+void executeHttpGet(String method, ...) : // load balance
+void executeHttpRequest(String method, ...) : // load balance
-void executeHttpRequestInner(String url, String method, ...) : // inner method
executeHttpGetByIdx
executeHttpRequestByIdx
executeHttpRequestInner
executeHttpGet
executeHttpRequest

错误处理

错误信息

场景1 http请求失败

$operation request failed, error: $error_details

场景2 http响应码不符合预期

$operation error resp, code: $code, body: $body

场景3 其他异常

$operation failed, error: $error_details
# example:
writePoint failed, unmarshall response body error: json: cannot unmarshal number ...
openGemini is a Cloud Native Computing Foundation sandbox project.

The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page. 2025 © openGemini Project Authors. All rights reserved.

OpenGeminiClient
+WritePoint(String database, Point point)
+WritePointWithRp(String database, String rp, Point point)
+WriteBatchPoints(String database, BatchPoints batchPoints)
+WriteBatchPointsWithRp(String database, String rp, BatchPoints batchPoints)
+WriteByGrpc(req WriteRequest) : // WriteRequest build from RecordBuilder
BatchPoints
+ List<Point> points
+AddPoint(Point)
Point
+ String measurement
+ Precision precision // enum, second, millisecond, microsecond, nanosecond, default is nanosecond
+ Time time // language specific
Syntax error in graphmermaid version 10.0.2
QueryResult
+ List<SeriesResult> results
+ String error
SeriesResult
+ List<Series> series // Series is an uncountable noun.
+ String error
Series
+ String name
Syntax error in graphmermaid version 10.0.2