diff --git a/openGemini.github.io b/openGemini.github.io deleted file mode 160000 index 7ca72bd6..00000000 --- a/openGemini.github.io +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 7ca72bd65544f93de353c494d1abdbbb79f6b31e diff --git a/src/guide/develop/client_design.md b/src/guide/develop/client_design.md index 35276a37..85ae13fb 100644 --- a/src/guide/develop/client_design.md +++ b/src/guide/develop/client_design.md @@ -198,6 +198,128 @@ classDiagram BatchPoints "1" *-- "many" Point: contains ``` +# Execute interface design + +The Execute interface provides a unified SQL execution interface that automatically routes different types of statements to appropriate underlying methods. This design supports SQL-like statements including INSERT, SELECT, CREATE, DROP, and other database operations with parameter support and type safety. + +```mermaid +classDiagram + class OpenGeminiClient { + + ExecuteResult Execute(Statement statement) + + ExecuteResult ExecuteContext(Context ctx, Statement statement) + } + + class Statement { + + String database + + String command + + Map~String, Object~ params + + String retentionPolicy + } + + class ExecuteResult { + + QueryResult queryResult + + int64 affectedRows + + StatementType statementType + + Error error + } + + class StatementType { + <> + StatementTypeUnknown + StatementTypeQuery // SELECT, SHOW, EXPLAIN → routed to Query() + StatementTypeCommand // CREATE, DROP, ALTER → routed to Query() + StatementTypeInsert // INSERT → routed to Write methods + + String() String + + IsQueryLike() bool + + IsWriteLike() bool + } + + OpenGeminiClient --> Statement : uses + OpenGeminiClient --> ExecuteResult : returns + ExecuteResult --> StatementType : contains + ExecuteResult --> QueryResult : contains +``` + +## Statement routing logic + +```mermaid +flowchart TD + A[Execute Statement] --> B{Parse Statement Type} + B -->|SELECT, SHOW, EXPLAIN, DESCRIBE, WITH| C[StatementTypeQuery] + B -->|CREATE, DROP, ALTER, UPDATE, DELETE| D[StatementTypeCommand] + B -->|INSERT| E[StatementTypeInsert] + B -->|Other| F[StatementTypeUnknown] + + C --> G[Route to Query method] + D --> G[Route to Query method] + E --> H[Route to Write methods] + F --> I[Return error] + + G --> J[Return QueryResult + AffectedRows=0/1] + H --> K[Return AffectedRows=point count] + I --> L[Return error result] +``` + +## Parameter support + +The Execute interface supports parameterized statements with automatic type conversion: + +```mermaid +classDiagram + class ParameterTypes { + <> + String // "value" → value + Integer // 42 → 42i + UInteger // 42 → 42u + Float // 3.14 → 3.14 + Boolean // true → true + } + + class ParameterProcessor { + + replaceParams(command String, params Map) String + + convertParamValue(value Object) String + + validateParams(command String, params Map) Error + } + + Statement --> ParameterProcessor : uses + ParameterProcessor --> ParameterTypes : converts +``` + +## Usage examples + +### Basic usage +```go +result, err := client.Execute(opengemini.Statement{ + Database: "mydb", + Command: "SELECT * FROM weather LIMIT 10", +}) +``` + +### Parameterized query +```go +result, err := client.Execute(opengemini.Statement{ + Database: "mydb", + Command: "SELECT * FROM weather WHERE location=$loc AND temp>$temp", + Params: map[string]any{ + "loc": "beijing", + "temp": 25.0, + }, +}) +``` + +### Parameterized insert +```go +result, err := client.Execute(opengemini.Statement{ + Database: "mydb", + Command: "INSERT weather,location=$location temperature=$temp,humidity=$hum", + Params: map[string]any{ + "location": "shanghai", + "temp": 30.2, + "hum": 70, + }, +}) +``` + # Query design ```mermaid @@ -253,33 +375,39 @@ The interceptor pattern defines a standardized interface to hook into client ope ```mermaid -Interceptor interface { - Query(ctx context.Context, query *InterceptorQuery) InterceptorClosure - Write(ctx context.Context, write *InterceptorWrite) InterceptorClosure -} +classDiagram + class Interceptor { + <> + + Query(ctx context.Context, query *InterceptorQuery) InterceptorClosure + + Write(ctx context.Context, write *InterceptorWrite) InterceptorClosure + } ``` ## Define the base client class,associated with the Interceptor interface The base  Client  class manages a collection of interceptors, allowing dynamic registration and execution of interceptor logic during client operations. ```mermaid -class Client { -- []Interceptor interceptors -} +classDiagram + class Client { + - interceptors: List~Interceptor~ + } ``` ## Define the interceptor implementation class integrating OpenTelemetry,implementing the Interceptor interface The OtelClient class implements the Interceptor interface, embedding OpenTelemetry logic to capture traces, metrics, and logs for client operations. ```mermaid -class OtelClient { - Interceptor -} +classDiagram + class OtelClient { + <> + } + OtelClient ..|> Interceptor : implements ``` ## Tracing system core module ```mermaid +classDiagram class TraceContext { + traceId: String + parentTraceId: String @@ -387,7 +515,7 @@ class OtelClient { ## Usage Example(Go language examples) -```mermaid +```go func main() { var ctx = context.Background() shutdown, err := setupOtelSDK(ctx) diff --git a/src/zh/guide/develop/client_design.md b/src/zh/guide/develop/client_design.md index 7ba583e7..1430ed2d 100644 --- a/src/zh/guide/develop/client_design.md +++ b/src/zh/guide/develop/client_design.md @@ -199,6 +199,128 @@ classDiagram BatchPoints "1" *-- "many" Point: contains ``` +# Execute 接口设计 + +Execute 接口提供了一个统一的 SQL 执行接口，可以自动将不同类型的语句路由到相应的底层方法。该设计支持类 SQL 语句，包括 INSERT、SELECT、CREATE、DROP 和其他数据库操作，并提供参数支持和类型安全。 + +```mermaid +classDiagram + class OpenGeminiClient { + + ExecuteResult Execute(Statement statement) + + ExecuteResult ExecuteContext(Context ctx, Statement statement) + } + + class Statement { + + String database + + String command + + Map~String, Object~ params + + String retentionPolicy + } + + class ExecuteResult { + + QueryResult queryResult + + int64 affectedRows + + StatementType statementType + + Error error + } + + class StatementType { + <> + StatementTypeUnknown + StatementTypeQuery // SELECT, SHOW, EXPLAIN → 路由到 Query() + StatementTypeCommand // CREATE, DROP, ALTER → 路由到 Query() + StatementTypeInsert // INSERT → 路由到 Write 方法 + + String() String + + IsQueryLike() bool + + IsWriteLike() bool + } + + OpenGeminiClient --> Statement : 使用 + OpenGeminiClient --> ExecuteResult : 返回 + ExecuteResult --> StatementType : 包含 + ExecuteResult --> QueryResult : 包含 +``` + +## 语句路由逻辑 + +```mermaid +flowchart TD + A[执行语句] --> B{解析语句类型} + B -->|SELECT, SHOW, EXPLAIN, DESCRIBE, WITH| C[StatementTypeQuery] + B -->|CREATE, DROP, ALTER, UPDATE, DELETE| D[StatementTypeCommand] + B -->|INSERT| E[StatementTypeInsert] + B -->|其他| F[StatementTypeUnknown] + + C --> G[路由到 Query 方法] + D --> G[路由到 Query 方法] + E --> H[路由到 Write 方法] + F --> I[返回错误] + + G --> J[返回 QueryResult + AffectedRows=0/1] + H --> K[返回 AffectedRows=数据点数量] + I --> L[返回错误结果] +``` + +## 参数支持 + +Execute 接口支持参数化语句并自动进行类型转换： + +```mermaid +classDiagram + class ParameterTypes { + <> + String // "value" → value + Integer // 42 → 42i + UInteger // 42 → 42u + Float // 3.14 → 3.14 + Boolean // true → true + } + + class ParameterProcessor { + + replaceParams(command String, params Map) String + + convertParamValue(value Object) String + + validateParams(command String, params Map) Error + } + + Statement --> ParameterProcessor : 使用 + ParameterProcessor --> ParameterTypes : 转换 +``` + +## 使用示例 + +### 基本用法 +```go +result, err := client.Execute(opengemini.Statement{ + Database: "mydb", + Command: "SELECT * FROM weather LIMIT 10", +}) +``` + +### 参数化查询 +```go +result, err := client.Execute(opengemini.Statement{ + Database: "mydb", + Command: "SELECT * FROM weather WHERE location=$loc AND temp>$temp", + Params: map[string]any{ + "loc": "beijing", + "temp": 25.0, + }, +}) +``` + +### 参数化插入 +```go +result, err := client.Execute(opengemini.Statement{ + Database: "mydb", + Command: "INSERT weather,location=$location temperature=$temp,humidity=$hum", + Params: map[string]any{ + "location": "shanghai", + "temp": 30.2, + "hum": 70, + }, +}) +``` + # 查询设计 ```mermaid @@ -236,33 +358,39 @@ classDiagram 拦截器模式定义了标准化接口，用于挂钩客户端操作（查询/写入）并注入遥测逻辑。 ```mermaid -Interceptor interface { - Query(ctx context.Context, query *InterceptorQuery) InterceptorClosure - Write(ctx context.Context, write *InterceptorWrite) InterceptorClosure -} +classDiagram + class Interceptor { + <> + + Query(ctx context.Context, query *InterceptorQuery) InterceptorClosure + + Write(ctx context.Context, write *InterceptorWrite) InterceptorClosure + } ``` ## 定义基础客户端类，关联拦截器接口 基础 Client 类管理一组拦截器，允许在客户端操作期间动态注册和执行拦截器逻辑。 ```mermaid -class Client { -- []Interceptor interceptors -} +classDiagram + class Client { + - interceptors: List~Interceptor~ + } ``` ## 定义集成 OpenTelemetry 的拦截器实现类，实现 Interceptor 接口 OtelClient 类实现 Interceptor 接口，嵌入 OpenTelemetry 逻辑以捕获客户端操作的跟踪、指标和日志。 ```mermaid -class OtelClient { - Interceptor -} +classDiagram + class OtelClient { + <> + } + OtelClient ..|> Interceptor : implements ``` ## 追踪系统核心模块 ```mermaid +classDiagram class TraceContext { + traceId: String + parentTraceId: String @@ -370,7 +498,7 @@ class OtelClient { ## 使用示例(Go language examples) -```mermaid +```go func main() { var ctx = context.Background() shutdown, err := setupOtelSDK(ctx)