diff --git a/ingester-protocol/src/main/java/io/greptime/options/GreptimeOptions.java b/ingester-protocol/src/main/java/io/greptime/options/GreptimeOptions.java index 8b7cfe7..17eb11c 100644 --- a/ingester-protocol/src/main/java/io/greptime/options/GreptimeOptions.java +++ b/ingester-protocol/src/main/java/io/greptime/options/GreptimeOptions.java @@ -178,22 +178,37 @@ public static final class Builder { // The request router private Router router; + /** + * Create a new builder with the given endpoints and database. + * + * @param endpoints the endpoints to connect to + * @param database The target database name. Default is "public". When a database name is provided, + * the DB will attempt to parse catalog and schema from it. The format is + * {@code [-]}, where: + *
    + *
  • If {@code [-]} is not provided, the entire database name is used as schema
    • + *
  • If {@code [-]} is provided, the name is split on "-" into catalog and schema
    • + *
+ */ public Builder(List endpoints, String database) { this.endpoints.addAll(endpoints); this.database = database; } /** - * Asynchronous thread pool, which is used to handle various asynchronous - * tasks in the SDK (You are using a purely asynchronous SDK). If you do not - * set it, there will be a default implementation, which you can reconfigure - * if the default implementation is not satisfied. - *

- * Note: We do not close it to free resources(if it needs to be closed), as we - * view it as shared. - * - * @param asyncPool async thread pool + * Sets the asynchronous thread pool used to handle various asynchronous tasks in the SDK. + * This SDK is purely asynchronous. If not set, a default implementation will be used. + * It's generally recommended to use the default configuration. + * + *

Default: {@link io.greptime.common.util.SerializingExecutor} - This executor does not start any additional threads, + * it only uses the current thread to batch process small tasks. + * + *

Note: The SDK treats the thread pool as a shared resource and will not actively close it + * to release resources (even if it needs to be closed). + * + * @param asyncPool the asynchronous thread pool to use * @return this builder + * @see io.greptime.common.util.SerializingExecutor */ public Builder asyncPool(Executor asyncPool) { this.asyncPool = asyncPool; @@ -201,9 +216,22 @@ public Builder asyncPool(Executor asyncPool) { } /** - * Sets the RPC options, in general, the default configuration is fine. + * Sets the RPC options. In general, the default configuration is fine. + * + *

This configuration only applies to Regular API, not to Bulk API. * - * @param rpcOptions the rpc options + *

Key parameters include: + *

    + *
  • useRpcSharedPool: Whether to use global RPC shared pool (default: false)
    • + *
  • defaultRpcTimeout: RPC request timeout (default: 60000ms)
    • + *
  • maxInboundMessageSize: Maximum inbound message size (default: 256MB)
    • + *
  • flowControlWindow: Flow control window size (default: 256MB)
    • + *
  • idleTimeoutSeconds: Idle timeout duration (default: 5 minutes)
    • + *
  • keepAliveTimeSeconds: Keep-alive ping interval (default: disabled)
    • + *
  • limitKind: gRPC layer concurrency limit algorithm (default: None)
    • + *
+ * + * @param rpcOptions the RPC options * @return this builder */ public Builder rpcOptions(RpcOptions rpcOptions) { @@ -215,7 +243,15 @@ public Builder rpcOptions(RpcOptions rpcOptions) { * Set `TlsOptions` to use secure connection between client and server. Set to `null` to use * plaintext connection instead. * - * @param tlsOptions for configure secure connection, set to null to use plaintext + *

Key parameters include: + *

    + *
  • clientCertChain: Client certificate chain file
    • + *
  • privateKey: Private key file
    • + *
  • privateKeyPassword: Private key password
    • + *
  • rootCerts: Root certificate file
    • + *
+ * + * @param tlsOptions TLS options for secure connection configuration, set to null to use plaintext * @return this builder */ public Builder tlsOptions(TlsOptions tlsOptions) { @@ -224,9 +260,14 @@ public Builder tlsOptions(TlsOptions tlsOptions) { } /** - * In some case of failure, a retry of write can be attempted. + * Maximum number of retries for write failures. Whether to retry depends on the error type + * {@link io.greptime.Status#isShouldRetry()}. + * + *

This configuration only applies to Regular API, not to Bulk API. * - * @param maxRetries max retries times + *

Default: 1 + * + * @param maxRetries the maximum number of retry attempts * @return this builder */ public Builder writeMaxRetries(int maxRetries) { @@ -237,7 +278,11 @@ public Builder writeMaxRetries(int maxRetries) { /** * Write flow limit: maximum number of data points in-flight. * - * @param maxInFlightWritePoints max in-flight points + *

This configuration only applies to Regular API, not to Bulk API. + * + *

Default: 655360 (10 * 65536) + * + * @param maxInFlightWritePoints the maximum number of in-flight write points * @return this builder */ public Builder maxInFlightWritePoints(int maxInFlightWritePoints) { @@ -247,15 +292,21 @@ public Builder maxInFlightWritePoints(int maxInFlightWritePoints) { /** * Write flow limit: the policy to use when the write flow limit is exceeded. - * The options: - * - `LimitedPolicy.DiscardPolicy`: discard the data if the limiter is full. - * - `LimitedPolicy.AbortPolicy`: abort if the limiter is full. - * - `LimitedPolicy.BlockingPolicy`: blocks if the limiter is full. - * - `LimitedPolicy.AbortOnBlockingTimeoutPolicy`: blocks the specified time if - * the limiter is full, abort if timeout. - * The default is `LimitedPolicy.AbortOnBlockingTimeoutPolicy` - * - * @param writeLimitedPolicy write limited policy + * + *

This configuration only applies to Regular API, not to Bulk API. + * + *

Available policies: + *

    + *
  • {@code DiscardPolicy}: Discard data if limiter is full
    • + *
  • {@code AbortPolicy}: Abort if limiter is full, throw exception
    • + *
  • {@code BlockingPolicy}: Block the write thread if limiter is full
    • + *
  • {@code BlockingTimeoutPolicy}: Block for specified time then proceed if limiter is full
    • + *
  • {@code AbortOnBlockingTimeoutPolicy}: Block for specified time, abort and throw exception if timeout
    • + *
+ * + *

Default: {@code AbortOnBlockingTimeoutPolicy} (3 seconds) + * + * @param writeLimitedPolicy the write flow control policy * @return this builder */ public Builder writeLimitedPolicy(LimitedPolicy writeLimitedPolicy) { @@ -264,11 +315,14 @@ public Builder writeLimitedPolicy(LimitedPolicy writeLimitedPolicy) { } /** - * The default rate limit value(points per second) for `StreamWriter`. It only takes + * The default rate limit value (points per second) for `StreamWriter`. It only takes * effect when we do not specify the `maxPointsPerSecond` when creating a `StreamWriter`. - * The default is 10 * 65536 * - * @param defaultStreamMaxWritePointsPerSecond default max write points per second + *

This configuration only applies to Regular API, not to Bulk API. + * + *

Default: 655360 (10 * 65536) + * + * @param defaultStreamMaxWritePointsPerSecond the default maximum write points per second for StreamWriter * @return this builder */ public Builder defaultStreamMaxWritePointsPerSecond(int defaultStreamMaxWritePointsPerSecond) { @@ -277,9 +331,13 @@ public Builder defaultStreamMaxWritePointsPerSecond(int defaultStreamMaxWritePoi } /** - * Use zero copy write in bulk write. + * Whether to use zero-copy optimization in bulk write operations. * - * @param useZeroCopyWriteInBulkWrite use zero copy write in bulk write + *

This configuration is effective for Bulk API. + * + *

Default: true + * + * @param useZeroCopyWriteInBulkWrite whether to use zero-copy write optimization in bulk operations * @return this builder */ public Builder useZeroCopyWriteInBulkWrite(boolean useZeroCopyWriteInBulkWrite) { @@ -288,10 +346,12 @@ public Builder useZeroCopyWriteInBulkWrite(boolean useZeroCopyWriteInBulkWrite) } /** - * Refresh frequency of route tables. The background refreshes all route tables - * periodically. By default, By default, the route tables will not be refreshed. + * Background refresh period for route tables (seconds). The background refreshes all route tables + * periodically. Route tables will not be refreshed if value is <= 0. + * + *

Default: 600 (10 minutes) * - * @param routeTableRefreshPeriodSeconds refresh period for route tables cache + * @param routeTableRefreshPeriodSeconds the refresh period for route tables cache in seconds * @return this builder */ public Builder routeTableRefreshPeriodSeconds(long routeTableRefreshPeriodSeconds) { @@ -300,11 +360,13 @@ public Builder routeTableRefreshPeriodSeconds(long routeTableRefreshPeriodSecond } /** - * Timeout for health check. The default is 1000ms. + * Timeout for health check operations (milliseconds). * If the health check is not completed within the specified time, the health * check will fail. * - * @param checkHealthTimeoutMs timeout for health check + *

Default: 1000 (1 second) + * + * @param checkHealthTimeoutMs the timeout for health check operations in milliseconds * @return this builder */ public Builder checkHealthTimeoutMs(long checkHealthTimeoutMs) { @@ -313,10 +375,11 @@ public Builder checkHealthTimeoutMs(long checkHealthTimeoutMs) { } /** - * Sets authentication information. If the DB is not required to authenticate, - * we can ignore this. + * Sets database authentication information. Can be ignored if database doesn't require authentication. + * + *

Default: null * - * @param authInfo the authentication information + * @param authInfo the database authentication information * @return this builder */ public Builder authInfo(AuthInfo authInfo) { @@ -325,10 +388,12 @@ public Builder authInfo(AuthInfo authInfo) { } /** - * Sets the request router. The internal default implementation works well. - * You don't need to set it unless you have special requirements. + * Sets custom request router. The internal default implementation works well. + * No need to set unless you have special requirements. + * + *

Default: Internal default implementation * - * @param router the request router + * @param router the custom request router implementation * @return this builder */ public Builder router(Router router) {