This is an automated email from the ASF dual-hosted git repository.
wangdan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-pegasus-website.git
The following commit(s) were added to refs/heads/master by this push:
new 06e8867b update go-client doc (#122)
06e8867b is described below
commit 06e8867b7b17334a95516a4798cb6a45d793cc16
Author: Samunroyu <[email protected]>
AuthorDate: Thu Nov 6 18:15:15 2025 +0800
update go-client doc (#122)
---
_docs/en/clients/go-client.md | 497 +++++++++++++++++++++++++++++++++++++++++-
_docs/zh/clients/go-client.md | 244 +++++++++++----------
2 files changed, 620 insertions(+), 121 deletions(-)
diff --git a/_docs/en/clients/go-client.md b/_docs/en/clients/go-client.md
index d8cf9c36..9e72631c 100644
--- a/_docs/en/clients/go-client.md
+++ b/_docs/en/clients/go-client.md
@@ -1,5 +1,500 @@
---
permalink: clients/go-client
---
+
+# Get the Go Client
-TRANSLATING
\ No newline at end of file
+Download:
+
+```bash
+go get github.com/apache/incubator-pegasus/go-client@<CommitId>
+# Example
+go get github.com/apache/incubator-pegasus/go-client@df0eb5a
+```
+
+Requirements:
+- Go 1.18+
+- Thrift 0.13
+
+# Client Configuration
+Creating a Go client instance requires configuration. Currently, only
parameter passing is supported.
+The configuration is simple — you only need to specify the meta servers.
+If you prefer file-based configuration, parse your config file yourself and
pass the parameters to the Go client.
+
+```go
+// Parameter configuration
+cfg := &pegasus.Config{
+ MetaServers: []string{"0.0.0.0:34601", "0.0.0.0:34601"},
+}
+c := pegasus.NewClient(*cfg)
+
+// File configuration
+cfgPath, _ := filepath.Abs("./example/pegasus-client-config.json")
+rawCfg, err := ioutil.ReadFile(cfgPath)
+if err != nil {
+ fmt.Println(err)
+ return
+}
+cfg := &pegasus.Config{}
+json.Unmarshal(rawCfg, cfg)
+c := pegasus.NewClient(*cfg)
+```
+
+# API Reference
+
+## Create Client instance
+```go
+// NewClient creates a new instance of pegasus client.
+// It panics if the configured addresses are illegal
+func NewClient(cfg Config) Client
+
+// Config is the configuration of pegasus client.
+type Config struct {
+ MetaServers []string `json:"meta_servers"`
+}
+```
+
+After using the client, remember to close it to release resources, for example:
+```go
+c := pegasus.NewClient(*cfg)
+
+...
+
+c.Close()
+```
+
+## Create TableConnector instance
+All data operations are defined in `TableConnector`.
+One client can open multiple `TableConnector` instances, each corresponding to
a table.
+```go
+// Open the specific pegasus table. If the table was opened before,
+// it will reuse the previous connection to the table.
+OpenTable(ctx context.Context, tableName string) (TableConnector, error)
+```
+
+## TableConnector API
+
+### Get
+Read a single row.
+```go
+// Get retrieves the entry for `hashKey` + `sortKey`.
+// Returns nil if no entry matches.
+// `hashKey` : CAN'T be nil or empty.
+// `sortKey` : CAN'T be nil but CAN be empty.
+Get(ctx context.Context, hashKey []byte, sortKey []byte) ([]byte, error)
+```
+Notes:
+- Parameters: `context`, `hashKey`, `sortKey`.
+- Returns: `value`, `error`. If `(nil, nil)` is returned, the key does not
exist.
+- Errors: network error, timeout, server error, etc. If the key does not
exist, `value` is nil without error.
+
+### Set and SetTTL
+Write a single row. `SetTTL` sets TTL for a single key-value.
+```go
+// Set the entry for `hashKey` + `sortKey` to `value`.
+// If Set is called or `ttl` == 0, no data expiration is specified.
+// `hashKey` : CAN'T be nil or empty.
+// `sortKey` / `value` : CAN'T be nil but CAN be empty.
+Set(ctx context.Context, hashKey []byte, sortKey []byte, value []byte) error
+SetTTL(ctx context.Context, hashKey []byte, sortKey []byte, value []byte, ttl
time.Duration) error
+```
+Notes:
+- Two interfaces are provided; the second allows specifying TTL time (in
seconds).
+- Parameters: `context`, `hashKey`, `sortKey`, `value`, `ttl`.
+- Returns: `error`.
+- Errors: network error, timeout, server error, etc.
+
+### Del
+Delete a single row.
+```go
+// Delete the entry for `hashKey` + `sortKey`.
+// `hashKey` : CAN'T be nil or empty.
+// `sortKey` : CAN'T be nil but CAN be empty.
+Del(ctx context.Context, hashKey []byte, sortKey []byte) error
+```
+Notes:
+- Parameters: `context`, `hashKey`, `sortKey`.
+- Errors: network error, timeout, server error, etc.
+
+### MultiGet and MultiGetOpt
+Read multiple rows under the same HashKey.
+```go
+// MultiGet/MultiGetOpt retrieves the multiple entries for `hashKey` +
`sortKeys[i]` atomically in one operation.
+// MultiGet is identical to MultiGetOpt except that the former uses
DefaultMultiGetOptions as `options`.
+//
+// If `sortKeys` are given empty or nil, all entries under `hashKey` will be
retrieved.
+// `hashKey` : CAN'T be nil or empty.
+// `sortKeys[i]` : CAN'T be nil but CAN be empty.
+//
+// The returned key-value pairs are sorted by sort key in ascending order.
+// Returns nil if no entries match.
+// Returns true if all data is fetched, false if only partial data is fetched.
+//
+MultiGet(ctx context.Context, hashKey []byte, sortKeys [][]byte) ([]*KeyValue,
bool, error)
+MultiGetOpt(ctx context.Context, hashKey []byte, sortKeys [][]byte, options
*MultiGetOptions) ([]*KeyValue, bool, error)
+```
+Notes:
+- Parameters: `context`, `hashKey`, `sortKeys`.
+- Returns: `kvs`, `bool` indicating whether all data fetched, `error`.
+- Errors: network error, timeout, server error, etc. If the key does not
exist, it does not report an error.
+- The `bool` indicates: if `maxFetchCount` or `maxFetchSize` is set, a single
query may return only part of the result. If all data satisfying the conditions
are fetched, returns `true`; otherwise `false`.
+
+```go
+// MultiGetOptions is the options for MultiGet and MultiGetRange, defaults to
DefaultMultiGetOptions.
+type MultiGetOptions struct {
+ StartInclusive bool
+ StopInclusive bool
+ SortKeyFilter Filter
+
+ // MaxFetchCount and MaxFetchSize limit the size of returned result.
+ // Max count of k-v pairs to be fetched. MaxFetchCount <= 0 means no limit.
+ MaxFetchCount int
+
+ // Max size of k-v pairs to be fetched. MaxFetchSize <= 0 means no limit.
+ MaxFetchSize int
+
+ // Query order
+ Reverse bool
+
+ // Whether to retrieve keys only, without value.
+ // Enabling this option will reduce the network load, improve the RPC
latency.
+ NoValue bool
+}
+
+// Filter is used to filter based on the key.
+type Filter struct {
+ Type FilterType
+ Pattern []byte
+}
+
+// Filter types
+const (
+ FilterTypeNoFilter = FilterType(rrdb.FilterType_FT_NO_FILTER)
+ FilterTypeMatchAnywhere = FilterType(rrdb.FilterType_FT_MATCH_ANYWHERE)
+ FilterTypeMatchPrefix = FilterType(rrdb.FilterType_FT_MATCH_PREFIX)
+ FilterTypeMatchPostfix = FilterType(rrdb.FilterType_FT_MATCH_POSTFIX)
+)
+```
+Notes:
+- MultiGetOptions:
+ - startInclusive: whether to include StartSortKey, default `true`.
+ - stopInclusive: whether to include StopSortKey, default `false`.
+ - SortKeyFilter: filter on sort key.
+ - maxFetchCount and maxFetchSize limit the amount of data read;
maxFetchCount is the maximum number of entries; maxFetchSize is the maximum
bytes. Stop reading once either is reached. Defaults: `maxFetchCount=100`,
`maxFetchSize=100000`.
+ - noValue: only returns HashKey and SortKey, without Value, default `false`.
+ - reverse: scan in reverse order. Results are still sorted ascending by sort
key within the returned list. Supported since Pegasus Server 1.8.0.
+- Filter:
+ - type: filtering type: no filter, match anywhere, match prefix, match
postfix.
+ - Pattern: filtering pattern. Empty is equivalent to no filter.
+- Filter types description:
+ - FilterTypeNoFilter: no filter
+ - FilterTypeMatchAnywhere: match anywhere
+ - FilterTypeMatchPrefix: prefix match
+ - FilterTypeMatchPostfix: postfix match
+
+### MultiGetRange and MultiGetRangeOpt
+Read multiple rows under the same HashKey with range query.
+```go
+// MultiGetRange retrieves the multiple entries under `hashKey`, between range
(`startSortKey`, `stopSortKey`),
+// atomically in one operation.
+//
+// startSortKey: nil or len(startSortKey) == 0 means start from begin.
+// stopSortKey: nil or len(stopSortKey) == 0 means stop to end.
+// `hashKey` : CAN'T be nil.
+//
+// The returned key-value pairs are sorted by sort keys in ascending order.
+// Returns nil if no entries match.
+// Returns true if all data is fetched, false if only partial data is fetched.
+MultiGetRange(ctx context.Context, hashKey []byte, startSortKey []byte,
stopSortKey []byte) ([]*KeyValue, bool, error)
+MultiGetRangeOpt(ctx context.Context, hashKey []byte, startSortKey []byte,
stopSortKey []byte, options *MultiGetOptions) ([]*KeyValue, bool, error)
+```
+Notes:
+- Parameters: `context`, `hashKey`, `startSortKey`, `stopSortKey`.
+- Returns: `kvs`, `bool` indicating whether all data fetched, `error`.
+- Errors: network error, timeout, server error, etc. If the key does not
exist, it does not report an error.
+
+### MultiSet and MultiSetOpt
+Write multiple rows under the same HashKey.
+```go
+// MultiSet sets the multiple entries for `hashKey` + `sortKeys[i]` atomically
in one operation.
+// `hashKey` / `sortKeys` / `values` : CAN'T be nil or empty.
+// `sortKeys[i]` / `values[i]` : CAN'T be nil but CAN be empty.
+MultiSet(ctx context.Context, hashKey []byte, sortKeys [][]byte, values
[][]byte) error
+MultiSetOpt(ctx context.Context, hashKey []byte, sortKeys [][]byte, values
[][]byte, ttl time.Duration) error
+```
+Notes:
+- `MultiSet` uses RocksDB `WriteBatch`, so it is atomic.
+- Two interfaces are provided; the second allows specifying TTL.
+- Parameters: `context`, `hashKey`, `sortKeys`, `values`, `ttl` (optional,
seconds).
+- Returns: `error`.
+- Errors: network error, timeout, server error, etc.
+
+### MultiDel
+```go
+// MultiDel deletes the multiple entries under `hashKey` all atomically in one
operation.
+// `hashKey` / `sortKeys` : CAN'T be nil or empty.
+// `sortKeys[i]` : CAN'T be nil but CAN be empty.
+MultiDel(ctx context.Context, hashKey []byte, sortKeys [][]byte) error
+```
+Notes:
+- `MultiDel` uses RocksDB `WriteBatch`, so it is atomic.
+- Parameters: `context`, `hashKey`, `sortKeys`.
+- Returns: `error`.
+- Errors: network error, timeout, server error, etc.
+
+### DelRange and DelRangeOpt
+```go
+// DelRange /DelRangeOpt deletes the multiple entries under `hashKey`, between
range (`startSortKey`, `stopSortKey`),
+// atomically in one operation.
+// DelRange is identical to DelRangeOpt except that the former uses
DefaultDelRangeOptions as `options`.
+//
+// startSortKey: nil or len(startSortKey) == 0 means to start from the first
entry in the sorted key range.
+// stopSortKey: nil or len(stopSortKey) == 0 means to stop at the last entry
in the sorted key range.
+// `hashKey` : CAN'T be nil or empty.
+DelRange(ctx context.Context, hashKey []byte, startSortKey []byte, stopSortKey
[]byte) error
+DelRangeOpt(ctx context.Context, hashKey []byte, startSortKey []byte,
stopSortKey []byte, options *DelRangeOptions) error
+
+// DelRangeOptions is the options for DelRange, defaults to
DefaultDelRangeOptions.
+type DelRangeOptions struct {
+ nextSortKey []byte
+ StartInclusive bool
+ StopInclusive bool
+ SortKeyFilter Filter
+}
+```
+Notes:
+- `DelRange` internally calls `MultiDel` multiple times. Each `MultiDel` is
atomic, but the overall `DelRange` may not be atomic.
+- Parameters: `context`, `hashKey`, `startSortKey`, `stopSortKey`.
+- Returns: `error`.
+- Errors: network error, timeout, server error, etc.
+- `DelRangeOptions`:
+ - `nextSortKey`: deletion proceeds in ascending order of sort keys. If
deletion fails midway, the first undeleted sort key is saved into `nextSortKey`.
+ - `StartInclusive`: whether to include `startSortKey`.
+ - `StopInclusive`: whether to include `stopSortKey`.
+ - `SortKeyFilter`: filter sort keys.
+
+### TTL
+Get TTL of a key.
+```go
+// Returns ttl(time-to-live) in seconds: -1 if ttl is not set; -2 if entry
doesn't exist.
+// `hashKey` : CAN'T be nil or empty.
+// `sortKey` : CAN'T be nil but CAN be empty.
+TTL(ctx context.Context, hashKey []byte, sortKey []byte) (int, error)
+```
+Notes:
+- Parameters: `context`, `hashKey`, `sortKey`.
+- Returns: `int`, `error`.
+- Errors: network error, timeout, server error, etc.
+
+### Exist
+Check whether a key exists.
+```go
+// Check value existence for the entry for `hashKey` + `sortKey`.
+// `hashKey`: CAN'T be nil or empty.
+Exist(ctx context.Context, hashKey []byte, sortKey []byte) (bool, error)
+```
+Notes:
+- Parameters: `context`, `hashKey`, `sortKey`.
+- Returns: `bool`, `error`.
+- Errors: network error, timeout, server error, etc.
+
+### GetScanner
+Get an iterator to scan all data under a HashKey (local scan).
+```go
+// Get Scanner for {startSortKey, stopSortKey} within hashKey.
+// startSortKey: nil or len(startSortKey) == 0 means start from begin.
+// stopSortKey: nil or len(stopSortKey) == 0 means stop to end.
+// `hashKey`: CAN'T be nil or empty.
+GetScanner(ctx context.Context, hashKey []byte, startSortKey []byte,
stopSortKey []byte, options *ScannerOptions) (Scanner, error)
+
+// ScannerOptions is the options for GetScanner and GetUnorderedScanners.
+type ScannerOptions struct {
+ BatchSize int // internal buffer batch size
+ StartInclusive bool // if the startSortKey is included
+ StopInclusive bool // if the stopSortKey is included
+ HashKeyFilter Filter
+ SortKeyFilter Filter
+ NoValue bool // only fetch hash_key and sort_key, but not fetch
value
+}
+```
+Notes:
+- Parameters: `context`, `hashKey`, `startSortKey`, `stopSortKey`,
`ScannerOptions`.
+ - `startSortKey` and `stopSortKey` specify the range; use `ScannerOptions`
to configure open/closed intervals.
+ - If `startSortKey` is nil, start from the beginning; if `stopSortKey` is
nil, scan to the end.
+- `ScannerOptions`:
+ - `BatchSize`: number of entries per batch fetched from server, default 1000.
+ - `StartInclusive`: whether to include `startSortKey`, default `true`.
+ - `StopInclusive`: whether to include `stopSortKey`, default `false`.
+ - `HashKeyFilter`: filter on hash key, default none.
+ - `SortKeyFilter`: filter on sort key, default none.
+ - `NoValue`: return only hash and sort keys without values, default `false`.
+- Returns: `Scanner`, `error`.
+- Errors: network error, timeout, server error, etc.
+
+### GetUnorderedScanners
+Get iterators to scan the entire table (global scan).
+```go
+// Get Scanners for all data in pegasus, the count of scanners will
+// be no more than maxSplitCount
+GetUnorderedScanners(ctx context.Context, maxSplitCount int, options
*ScannerOptions) ([]Scanner, error)
+```
+Notes:
+- Parameters: `context`, `maxSplitCount`, `ScannerOptions`.
+ - `maxSplitCount` determines the number of returned iterators. When multiple
iterators are returned, each can access a portion of the table. This enables
concurrent scanning or use in MapReduce. Set to 1 if multiple iterators are not
needed.
+- Returns: array of `Scanner`, `error`.
+- Errors: network error, timeout, server error, etc.
+
+### Next
+Fetch the next entry during scan.
+```go
+// Scanner defines the interface of client-side scanning.
+type Scanner interface {
+ // Grabs the next entry.
+ Next(ctx context.Context) (completed bool, hashKey []byte, sortKey []byte,
value []byte, err error)
+
+ Close() error
+}
+```
+Notes:
+- Parameters: `context`.
+- Returns: `completed`, `hashKey`, `sortKey`, `value`, `err`.
+ - `completed`: `true` indicates scan finished.
+- Errors: network error, timeout, server error, etc.
+
+### CheckAndSet
+Atomic CAS (Compare-And-Swap) on data under a single HashKey (single-row
atomic operation). See [Single Row Atomic Operations](/api/single-atomic).
+This operation first checks the value of a SortKey (`checkSortKey`) against
some condition:
+- If the condition is met, set the value of another SortKey (`setSortKey`) to
the new value.
+- If the condition is not met, do not perform the set operation.
+
+`checkSortKey` and `setSortKey` can be identical or different.
+You can set `CheckAndSetOptions.ReturnCheckValue` to return the value of
`checkSortKey`. If `checkSortKey` and `setSortKey` are the same and the set
succeeds, the returned value is the old value before setting.
+
+```go
+// Atomically check and set value by key from the cluster. The value will be
set if and only if check passed.
+// The sort key for checking and setting can be the same or different.
+//
+// `checkSortKey`: The sort key for checking.
+// `setSortKey`: The sort key for setting.
+// `checkOperand`:
+CheckAndSet(ctx context.Context, hashKey []byte, checkSortKey []byte,
checkType CheckType,
+ checkOperand []byte, setSortKey []byte, setValue []byte, options
*CheckAndSetOptions) (*CheckAndSetResult, error)
+
+// The value checking types
+const (
+ CheckTypeNoCheck = CheckType(rrdb.CasCheckType_CT_NO_CHECK)
+
+ // existence
+ CheckTypeValueNotExist =
CheckType(rrdb.CasCheckType_CT_VALUE_NOT_EXIST) // value is not exist
+ CheckTypeValueNotExistOrEmpty =
CheckType(rrdb.CasCheckType_CT_VALUE_NOT_EXIST_OR_EMPTY) // value is not exist
or value is empty
+ CheckTypeValueExist =
CheckType(rrdb.CasCheckType_CT_VALUE_EXIST) // value is exist
+ CheckTypeValueNotEmpty =
CheckType(rrdb.CasCheckType_CT_VALUE_NOT_EMPTY) // value is exist and
not empty
+
+ // match
+ CheckTypeMatchAnywhere =
CheckType(rrdb.CasCheckType_CT_VALUE_MATCH_ANYWHERE) // operand matches
anywhere in value
+ CheckTypeMatchPrefix =
CheckType(rrdb.CasCheckType_CT_VALUE_MATCH_PREFIX) // operand matches prefix
in value
+ CheckTypeMatchPostfix =
CheckType(rrdb.CasCheckType_CT_VALUE_MATCH_POSTFIX) // operand matches
postfix in value
+
+ // bytes compare
+ CheckTypeBytesLess =
CheckType(rrdb.CasCheckType_CT_VALUE_BYTES_LESS) // bytes compare:
value < operand
+ CheckTypeBytesLessOrEqual =
CheckType(rrdb.CasCheckType_CT_VALUE_BYTES_LESS_OR_EQUAL) // bytes compare:
value <= operand
+ CheckTypeBytesEqual =
CheckType(rrdb.CasCheckType_CT_VALUE_BYTES_EQUAL) // bytes compare:
value == operand
+ CheckTypeBytesGreaterOrEqual =
CheckType(rrdb.CasCheckType_CT_VALUE_BYTES_GREATER_OR_EQUAL) // bytes compare:
value >= operand
+ CheckTypeBytesGreater =
CheckType(rrdb.CasCheckType_CT_VALUE_BYTES_GREATER) // bytes compare:
value > operand
+
+ // int compare: first transfer bytes to int64; then compare by int value
+ CheckTypeIntLess =
CheckType(rrdb.CasCheckType_CT_VALUE_INT_LESS) // int compare:
value < operand
+ CheckTypeIntLessOrEqual =
CheckType(rrdb.CasCheckType_CT_VALUE_INT_LESS_OR_EQUAL) // int compare:
value <= operand
+ CheckTypeIntEqual =
CheckType(rrdb.CasCheckType_CT_VALUE_INT_EQUAL) // int compare:
value == operand
+ CheckTypeIntGreaterOrEqual =
CheckType(rrdb.CasCheckType_CT_VALUE_INT_GREATER_OR_EQUAL) // int compare:
value >= operand
+ CheckTypeIntGreater =
CheckType(rrdb.CasCheckType_CT_VALUE_BYTES_GREATER) // int compare:
value > operand
+)
+
+// CheckAndSetOptions is the options of a CAS.
+type CheckAndSetOptions struct {
+ SetValueTTLSeconds int // time to live in seconds of the set value, 0
means no ttl.
+ ReturnCheckValue bool // if return the check value in results.
+}
+
+// CheckAndSetResult is the result of a CAS.
+type CheckAndSetResult struct {
+ // true if set value succeed.
+ SetSucceed bool
+
+ // the actual value if set value failed; null means the actual value is
not exist.
+ CheckValue []byte
+
+ // if the check value is exist; can be used only when checkValueReturned
is true.
+ CheckValueExist bool
+
+ // return the check value if exist; can be used only when checkValueExist
is true.
+ CheckValueReturned bool
+}
+```
+Notes:
+- Parameters: `context`, `hashKey`, `checkSortKey`, `checkType`,
`checkOperand`, `setSortKey`, `setValue`, `CheckAndSetOptions`.
+ - `checkSortKey`, `checkType`, `checkOperand`: specify the check condition.
+ - `setSortKey`, `setValue`: specify the new value to set once the condition
passes.
+ - `options`:
+ - `SetValueTTLSeconds`: TTL of the new value; must be `>= 0`, `0` means no
TTL; `< 0` returns error.
+ - `ReturnCheckValue`: whether to return the value of `checkSortKey`.
+- Returns: `CheckAndSetResult`, `error`.
+ - `SetSucceed`: whether set succeeded.
+ - `CheckValue`: value of `checkSortKey`; meaningful only when
`checkValueExist = true`.
+ - `CheckValueExist`: whether `checkSortKey` exists; meaningful only when
`checkValueReturned = true`.
+ - `CheckValueReturned`: whether `checkSortKey` value was returned.
+- Errors: network error, timeout, server error, etc.
+
+### SortKeyCount
+Get the number of sort keys under a HashKey.
+```go
+// Returns the count of sortkeys under hashkey.
+// `hashKey`: CAN'T be nil or empty.
+SortKeyCount(ctx context.Context, hashKey []byte) (int64, error)
+```
+Notes:
+- Parameters: `context`, `hashKey`.
+- Returns: the count of sort keys under the HashKey.
+- Errors: network error, timeout, server error, etc.
+
+### Incr
+Atomic increment/decrement on a single row. See [Single Row Atomic
Operations](/api/single-atomic).
+This operation reads the value as a byte string, converts it to `int64`, adds
`increment`, converts the result back to a byte string, and sets it as the new
value.
+When `increment` is positive, it is atomic increment; when negative, atomic
decrement.
+```go
+// Atomically increment value by key from the cluster.
+// Returns the new value.
+// `hashKey` / `sortKeys` : CAN'T be nil or empty
+Incr(ctx context.Context, hashKey []byte, sortKey []byte, increment int64)
(int64, error)
+```
+Notes:
+- Parameters: `context`, `hashKey`, `sortKey`, `increment`.
+- Returns: new value after operation, `error`.
+- Errors: network error, timeout, server error, etc. Also errors in the
following cases:
+ - Old value cannot be converted to `int64` (invalid number or overflow).
+ - Result of old value plus `increment` overflows `int64`.
+- Other:
+ - If old value does not exist, treat it as `0`, so new value equals
`increment`.
+ - TTL: If old value exists, new value keeps the same TTL as old; if old
value does not exist, new value has no TTL.
+
+### BatchGet
+Read a batch of keys; a batched wrapper of `Get`. This method concurrently
sends asynchronous requests to the server and waits for results. If any request
fails, it aborts early and returns error. When error is returned, `values` are
undefined.
+```go
+// Gets values from a batch of CompositeKeys. Internally it distributes each
key
+// into a Get call and wait until all returned.
+//
+// `keys`: CAN'T be nil or empty, `hashkey` in `keys` can't be nil or empty
either.
+// The returned values are in sequence order of each key, aka `keys[i] =>
values[i]`.
+// If keys[i] is not found, or the Get failed, values[i] is set nil.
+//
+// Returns a non-nil `err` once there's a failed Get call. It doesn't mean all
calls failed.
+//
+// NOTE: this operation is not guaranteed to be atomic
+BatchGet(ctx context.Context, keys []CompositeKey) (values [][]byte, err error)
+```
+Notes:
+- Parameters: `context`, `CompositeKey`.
+- Returns: `values`, `error`. If read succeeds, `values[i]` holds the result
for `keys[i]`; if value does not exist, it is `nil`.
+- Errors: network error, timeout, server error, etc.
+- Other:
+ - This method is not atomic; partial success and partial failure may occur.
An error is returned if any call fails.
\ No newline at end of file
diff --git a/_docs/zh/clients/go-client.md b/_docs/zh/clients/go-client.md
index 9eb4a2fd..62168794 100644
--- a/_docs/zh/clients/go-client.md
+++ b/_docs/zh/clients/go-client.md
@@ -2,7 +2,7 @@
permalink: clients/go-client
---
-# 获取go客户端
+# 获取 go 客户端
下载：
@@ -17,9 +17,9 @@ go get github.com/apache/incubator-pegasus/go-client@df0eb5a
* Thrift 0.13
# 客户端配置
-创建go client实例需要配置相关参数，目前仅支持参数传递方式。
-go client的配置参数非常简单，仅需要指定meta servers。
-用户如果需要文件配置，需自行将参数从文件从解析，再传入go client。
+创建 go client 实例需要配置相关参数，目前仅支持参数传递方式。
+go client 的配置参数非常简单，仅需要指定 meta servers。
+用户如果需要文件配置，需自行将参数从文件从解析，再传入 go client。
```go
// 参数配置
cfg := &pegasus.Config{
@@ -41,7 +41,7 @@ c := pegasus.NewClient(*cfg)
# 接口定义
-## 创建Client实例
+## 创建 Client 实例
```go
// NewClient creates a new instance of pegasus client.
// It panics if the configured addresses are illegal
@@ -53,25 +53,25 @@ type Config struct {
}
```
-使用完毕后，记得close client以释放资源，譬如：
+使用完毕后，记得 close client 以释放资源，譬如：
```go
c := pegasus.NewClient(*cfg)
...
-c.Close();
+c.Close()
```
-## 创建TableConnector实例
-go client 操作数据的接口都在TableConnector中定义。
-一个client可以有多个TableConnector实例，每一个TableConnector对应一张表。
+## 创建 TableConnector 实例
+go client 操作数据的接口都在 TableConnector 中定义。
+一个 client 可以有多个 TableConnector 实例，每一个 TableConnector 对应一张表。
```go
// Open the specific pegasus table. If the table was opened before,
// it will reuse the previous connection to the table.
OpenTable(ctx context.Context, tableName string) (TableConnector, error)
```
-## TableConnector接口
+## TableConnector 接口
### Get
读单行数据。
@@ -83,12 +83,12 @@ OpenTable(ctx context.Context, tableName string)
(TableConnector, error)
Get(ctx context.Context, hashKey []byte, sortKey []byte) ([]byte, error)
```
注：
-* 参数：需传入context、hashKey、sortKey。
-* 返回值：value、error. 如果返回(nil,nil)，表示key对应的数据不存在。
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型(key对应数据不存在返回nil)。
+* 参数：需传入 `context`、`hashKey`、`sortKey`。
+* 返回值：`value`、`error`。 如果返回 (nil,nil)，表示 key 对应的数据不存在。
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型 (key 对应数据不存在返回 nil)。
### Set and SetTTL
-写单行数据, SetTTL可以设置单条kv的TTL。
+写单行数据, SetTTL 可以设置单条 kv 的 TTL。
```go
// Set the entry for `hashKey` + `sortKey` to `value`.
// If Set is called or `ttl` == 0, no data expiration is specified.
@@ -98,10 +98,10 @@ Set(ctx context.Context, hashKey []byte, sortKey []byte,
value []byte) error
SetTTL(ctx context.Context, hashKey []byte, sortKey []byte, value []byte, ttl
time.Duration) error
```
注：
-* 提供了两个版本的接口，其中第二个接口可以指定TTL时间。
-* 参数：需传入context、hashKey、sortKey、value, ttl单位为秒(s)
-* 返回值：error
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型。
+* 提供了两个版本的接口，其中第二个接口可以指定 TTL 时间。
+* 参数：需传入 `context`、`hashKey`、`sortKey`、`value`、`ttl`。 `ttl` 单位为秒(s)。
+* 返回值：`error`。
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型。
### Del
删除单行数据
@@ -112,11 +112,12 @@ SetTTL(ctx context.Context, hashKey []byte, sortKey
[]byte, value []byte, ttl ti
Del(ctx context.Context, hashKey []byte, sortKey []byte) error
```
注：
-* 参数：需传入context、hashKey、sortKey。
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型。
+* 参数：需传入 `context`、`hashKey`、`sortKey`。
+* 返回值：`error`。
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型。
### MultiGet and MultiGetOpt
-读**同一HashKey下**的多行数据。
+读**同一 HashKey 下**的多行数据。
```go
// MultiGet/MultiGetOpt retrieves the multiple entries for `hashKey` +
`sortKeys[i]` atomically in one operation.
// MultiGet is identical to MultiGetOpt except that the former uses
DefaultMultiGetOptions as `options`.
@@ -133,10 +134,11 @@ MultiGet(ctx context.Context, hashKey []byte, sortKeys
[][]byte) ([]*KeyValue, b
MultiGetOpt(ctx context.Context, hashKey []byte, sortKeys [][]byte, options
*MultiGetOptions) ([]*KeyValue, bool, error)
```
注:
-* 参数：需传入context、hashKey、sortKeys。
-* 返回值：得到的kvs、bool值代表是否all fetched, error
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型(key对应数据不存在不会报错)。
-*
bool值表示:如果用户指定了maxFetchCount或者maxFetchSize，单次查询可能只获取到部分结果。如果所有满足条件的数据都已经获取到，则返回true；否则返回false。
+* 参数：需传入 `context`、`hashKey`、`sortKeys`。
+* 返回值：得到的 kvs、bool 值代表是否 all fetched, error
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型 (key 对应数据不存在不会报错)。
+* bool 值表示:如果用户指定了 `maxFetchCount` 或者
`maxFetchSize`，单次查询可能只获取到部分结果。如果所有满足条件的数据都已经获取到，则返回 `true`；否则返回 `false`。
+
``` go
// MultiGetOptions is the options for MultiGet and MultiGetRange, defaults to
DefaultMultiGetOptions.
type MultiGetOptions struct {
@@ -174,24 +176,25 @@ const (
)
```
注：
-* MultiGetOptions说明：
- * startInclusive：是否包含StartSortKey，默认为true。
- * stopInclusive：是否包含StopSortKey，默认为false。
- * SortKeyFilter: SortKey过滤项
- *
maxFetchCount和maxFetchSize用于限制读取的数据量，maxFetchCount表示最多读取的数据条数，maxFetchSize表示最多读取的数据字节数，两者任一达到限制就停止读取.
MaxFetchCount 默认为100, MaxFetchSize 默认为100000
- * noValue：只返回HashKey和SortKey，不返回Value数据，默认为false。
- * reverse：是否逆向扫描数据库，从后往前查找数据。但是查找得到的结果在list中还是按照SortKey从小到大顺序存放。从Pegasus
Server 1.8.0 时开始支持。
+* MultiGetOptions 说明：
+ * startInclusive: 是否包含 StartSortKey，默认为 `true`。
+ * stopInclusive: 是否包含 StopSortKey，默认为 `false`。
+ * SortKeyFilter: SortKey 过滤项
+ * maxFetchCount 和 maxFetchSize 用于限制读取的数据量，maxFetchCount
表示最多读取的数据条数，maxFetchSize 表示最多读取的数据字节数，两者任一达到限制就停止读取. MaxFetchCount 默认为 100,
MaxFetchSize 默认为 100000
+ * noValue: 只返回 HashKey 和 SortKey，不返回 Value 数据，默认为false。
+ * reverse: 是否逆向扫描数据库，从后往前查找数据。但是查找得到的结果在list 中还是按照 SortKey 从小到大顺序存放。从
Pegasus Server 1.8.0 时开始支持。
* Filter说明：
* type: 过滤类型，包括无过滤、任意位置匹配、前缀匹配和后缀匹配
* Pattern: 过滤模式串，空串相当于无过滤。
* Filter types 说明：
- * FilterTypeNoFilter：无过滤
- * FilterTypeMatchAnywhere： 任意位置匹配
- * FilterTypeMatchPrefix： 前缀匹配
+ * FilterTypeNoFilter: 无过滤
+ * FilterTypeMatchAnywhere: 任意位置匹配
+ * FilterTypeMatchPrefix: 前缀匹配
* FilterTypeMatchPostfix: 后缀匹配
### MultiGetRange and MultiGetRangeOpt
-读**同一HashKey下**的多行数据，支持范围查询。
+读**同一 HashKey 下**的多行数据，支持范围查询。
+
``` go
// MultiGetRange retrieves the multiple entries under `hashKey`, between range
(`startSortKey`, `stopSortKey`),
// atomically in one operation.
@@ -206,14 +209,15 @@ const (
MultiGetRange(ctx context.Context, hashKey []byte, startSortKey []byte,
stopSortKey []byte) ([]*KeyValue, bool, error)
MultiGetRangeOpt(ctx context.Context, hashKey []byte, startSortKey []byte,
stopSortKey []byte, options *MultiGetOptions) ([]*KeyValue, bool, error)
```
+
注：
-* 参数：需传入context、hashKey、startSortKey、stopSortKey
-* 返回值：kvs、bool值代表是否all fetched, error
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型(key对应数据不存在不会报错)。
+* 参数：需传入 `context`、`hashKey`、`startSortKey`、`stopSortKey`
+* 返回值：`kvs`、`bool` 值代表是否 all fetched, error
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型 (key 对应数据不存在不会报错)。
### MultiSet and MultiSetOpt
-写同一HashKey下的多行数据。
+写**同一 HashKey 下**的多行数据。
``` go
// MultiSet sets the multiple entries for `hashKey` + `sortKeys[i]` atomically
in one operation.
// `hashKey` / `sortKeys` / `values` : CAN'T be nil or empty.
@@ -222,11 +226,11 @@ MultiSet(ctx context.Context, hashKey []byte, sortKeys
[][]byte, values [][]byte
MultiSetOpt(ctx context.Context, hashKey []byte, sortKeys [][]byte, values
[][]byte, ttl time.Duration) error
```
注：
-* MultiSet调用了rocksdb的WriteBatch接口，因此MultiSet是一个原子操作
-* 提供了两个版本的接口，其中第二个接口可以指定TTL时间。
-* 参数：需传入context、hashKey、sortKeys、values、ttl(可选，单位为s)
+* `MultiSet` 调用了 rocksdb 的 WriteBatch 接口，因此 `MultiSet` 是一个原子操作
+* 提供了两个版本的接口，其中第二个接口可以指定 TTL 时间。
+* 参数：需传入 `context`、`hashKey`、`sortKeys`、`values`、`ttl` (可选，单位为 s)
* 返回值：error
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型
### MultiDel
``` go
@@ -236,10 +240,10 @@ MultiSetOpt(ctx context.Context, hashKey []byte, sortKeys
[][]byte, values [][]b
MultiDel(ctx context.Context, hashKey []byte, sortKeys [][]byte) error
```
注：
-* MultiDel调用了rocksdb的WriteBatch接口，因此MultiDel是一个原子操作
-* 参数：需传入context、hashKey、sortKeys
+* `MultiDel` 调用了 rocksdb 的 WriteBatch 接口，因此 `MultiDel` 是一个原子操作
+* 参数：需传入 `context`、`hashKey`、`sortKeys`
* 返回值：error
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型
### DelRange and DelRangeOpt
``` go
@@ -262,18 +266,18 @@ type DelRangeOptions struct {
}
```
注：
-* DelRange实际调用了多次MultiDel, 每次MultiDel是原子的，但是DelRange整体可能不是原子的。
-* 参数：需传入context、hashKey、startSortKey、stopSortKey
+* `DelRange` 实际调用了多次 `MultiDel`, 每次 `MultiDel` 是原子的，但是 `DelRange` 整体可能不是原子的。
+* 参数：需传入 `context`、`hashKey`、`startSortKey`、`stopSortKey`
* 返回值：error
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型
-* DelRangeOptions：
- * nextSortKey：
DelRange会按照sortkey的大小顺序进行删除，假如删除过程中失败，会将未删除成功第一个sortkey保存在nextSortKey
- * StartInclusive: 删除时是否包括startSortKey
- * StopInclusive: 删除时是否包括stopSortKey
- * SortKeyFilter: 可以对Sortkey进行筛选
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型
+* `DelRangeOptions`:
+ * `nextSortKey`: `DelRange` 会按照 sortkey 的大小顺序进行删除，假如删除过程中失败，会将未删除成功第一个
sortkey 保存在 `nextSortKey`
+ * `StartInclusive`: 删除时是否包括 `startSortKey`
+ * `StopInclusive`: 删除时是否包括 `stopSortKey`
+ * `SortKeyFilter`: 可以对 Sortkey 进行筛选
### TTL
-获取某个key的TTL。
+获取某个 key 的TTL。
``` go
// Returns ttl(time-to-live) in seconds: -1 if ttl is not set; -2 if entry
doesn't exist.
// `hashKey` : CAN'T be nil or empty.
@@ -281,24 +285,24 @@ type DelRangeOptions struct {
TTL(ctx context.Context, hashKey []byte, sortKey []byte) (int, error)
```
注：
-* 参数：需传入context、hashKey、sortKey
-* 返回值：int,error
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型
+* 参数：需传入 `context`、`hashKey`、`sortKey`
+* 返回值：`int` 代表 ttl 时间，单位为 s；`error` 代表异常信息
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型
### Exist
-判断某个key是否存在。
+判断某个 key 是否存在。
``` go
// Check value existence for the entry for `hashKey` + `sortKey`.
// `hashKey`: CAN'T be nil or empty.
Exist(ctx context.Context, hashKey []byte, sortKey []byte) (bool, error)
```
注：
-* 参数：需传入context、hashKey、sortKey
-* 返回值：bool,error
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型
+* 参数：需传入 `context`、`hashKey`、`sortKey`
+* 返回值：`bool` 代表 key 是否存在；`error` 代表异常信息
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型
### GetScanner
-获取遍历某个HashKey下所有数据的迭代器，用于局部扫描。
+获取遍历某个 HashKey 下所有数据的迭代器，用于局部扫描。
``` go
// Get Scanner for {startSortKey, stopSortKey} within hashKey.
// startSortKey: nil or len(startSortKey) == 0 means start from begin.
@@ -317,18 +321,18 @@ type ScannerOptions struct {
}
```
注：
-* 参数：需传入context、hashKey、startSortKey、stopSortKey、ScannnerOptions
- * startSortKey和stopSortKey用于指定scan的返回，并通过ScanOptions指定区间的开闭。
- * 如果startSortKey为null，表示从头开始；如果stopSortKey为null，表示一直读到尾。
- * ScannnerOptions说明：
- * BatchSize： 从server端读取数据时每批数据的个数，默认值为1000
- * startInclusive：是否包含startSortKey，默认为true
- * stopInclusive： 是否包含stopSortKey，默认为false
- * HashKeyFilter: hashkey的筛选，默认无筛选
- * SortKeyFilter: sortkey的筛选，默认无筛选
- * NoValue: 只返回HashKey和SortKey，不返回Value数据，默认为false
-* 返回值：迭代器Scanner, error
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型
+* 参数: 需传入 `context`、`hashKey`、`startSortKey`、`stopSortKey`、`ScannerOptions`
+ * `startSortKey` 和 `stopSortKey` 用于指定 scan 的返回，并通过 `ScannerOptions`
指定区间的开闭。
+ * 如果 `startSortKey` 为 null，表示从头开始；如果 `stopSortKey` 为 null，表示一直读到尾。
+ * `ScannerOptions` 说明:
+ * `BatchSize`: 从 server 端读取数据时每批数据的个数，默认值为 1000
+ * `StartInclusive`:是否包含 `startSortKey`，默认为 true
+ * `StopInclusive`: 是否包含 `stopSortKey`，默认为 false
+ * `HashKeyFilter`: hashkey 的筛选，默认无筛选
+ * `SortKeyFilter`: sortkey 的筛选，默认无筛选
+ * `NoValue`： 只返回 HashKey 和 SortKey，不返回 Value 数据，默认为 false
+* 返回值：迭代器 `Scanner`、`error`
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型
### GetUnorderedScanners
获取遍历整个表的所有数据的迭代器，用于全局扫描。
@@ -338,13 +342,13 @@ type ScannerOptions struct {
GetUnorderedScanners(ctx context.Context, maxSplitCount int, options
*ScannerOptions) ([]Scanner, error)
```
注：
-* 参数：需传入context、maxSplitCount、ScannnerOptions
- *
maxSplitCount：用于决定返回的迭代器的个数。当返回多个迭代器时，每个迭代器可以访问表中的部分数据。通过返回迭代器列表，用户可以进行并发scan或者在MapReduce中使用。如果不需要多个迭代器，可以将其设置为1。
-* 返回值：迭代器Scanner数组, error
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型
+* 参数: 需传入 `context`、`maxSplitCount`、`ScannnerOptions`
+ * `maxSplitCount`:
用于决定返回的迭代器的个数。当返回多个迭代器时，每个迭代器可以访问表中的部分数据。通过返回迭代器列表，用户可以进行并发scan 或者在 MapReduce
中使用。如果不需要多个迭代器，可以将其设置为1。
+* 返回值：迭代器 Scanner 数组, error
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型
### Next
-在scan操作时，同步获取下一条数据。
+在 scan 操作时，同步获取下一条数据。
``` go
// Scanner defines the interface of client-side scanning.
type Scanner interface {
@@ -355,19 +359,19 @@ type Scanner interface {
}
```
注：
-* 参数：需传入context
-* 返回值：completed、hashKey、sortKey、value、err
- * completed: true表示遍历结束.
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型
+* 参数: 需传入 `context`
+* 返回值：`completed`、`hashKey`、`sortKey`、`value`、`err`
+ * `completed`: `true` 表示遍历结束.
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型
### CheckAndSet
-单hashKey数据的原子CAS操作（可以理解为单行原子操作）。详细说明参见[单行原子操作](/api/single-atomic#cas操作)。
-该操作先对某个SortKey（称之为checkSortKey）的value做条件检查：
-* 如果检查的条件满足，则将另一个SortKey（称之为setSortKey）的value设置为新值。
-* 如果检查的条件不满足，则不执行set操作。
+单 hashKey 数据的原子 CAS 操作（可以理解为单行原子操作）。详细说明参见[单行原子操作](/api/single-atomic#cas操作)。
+该操作先对某个 SortKey（称之为 checkSortKey）的 value 做条件检查：
+* 如果检查的条件满足，则将另一个 SortKey（称之为 setSortKey）的 value 设置为新值。
+* 如果检查的条件不满足，则不执行 set 操作。
-checkSortKey和setSortKey可以相同也可以不同。
-用户还可以设置`CheckAndSetOptions.ReturnCheckValue`来获取CheckSortKey对应的value。如果CheckSortKey和SetSortKey相同并且set成功，则获取set之前的旧值。
+`checkSortKey` 和 `setSortKey` 可以相同也可以不同。
+用户还可以设置 `CheckAndSetOptions.ReturnCheckValue` 来获取 `CheckSortKey` 对应的 value。如果
`CheckSortKey` 和 `SetSortKey` 相同并且 set 成功，则获取 set 之前的旧值。
``` go
// Atomically check and set value by key from the cluster. The value will be
set if and only if check passed.
@@ -431,35 +435,35 @@ type CheckAndSetResult struct {
}
```
注：
-*
参数：需传入context、hashKey、checkSortKey、checkType、checkOperand、setSortKey、setValue、CheckAndSetOptions
- * checkSortKey、checkType、checkOperand：用于指定检查的条件。
- * setSortKey、setValue：用于指定条件检查成功后要set的新值。
- * options：其他选项，包括：
- * SetValueTTLSeconds：新值的TTL时间；TTL必须>=0，0表示不设置TTL限制。当<0时返回报错。
- * ReturnCheckValue：是否需要返回CheckSortKey对应的value。
-* 返回值：CheckAndSetResult、error
- * SetSucceed: 是否set成功。
- * CheckValue: CheckSortKey对应的value值；该域只有在checkValueExist=true时有意义。
- * CheckValueExist:
CheckSortKey对应的value是否存在；该域只有在checkValueReturned=true时有意义。
- * CheckValueReturned: 是否返回了CheckSortKey对应的value。
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型
+* 参数：需传入
`context`、`hashKey`、`checkSortKey`、`checkType`、`checkOperand`、`setSortKey`、`setValue`、`CheckAndSetOptions`
+ * `checkSortKey`、`checkType`、`checkOperand`：用于指定检查的条件。
+ * `setSortKey`、`setValue`：用于指定条件检查成功后要 set 的新值。
+ * `options`：其他选项，包括：
+ * `SetValueTTLSeconds`：新值的 TTL 时间；TTL 必须 >= 0，0 表示不设置 TTL 限制。当 < 0
时返回报错。
+ * `ReturnCheckValue`：是否需要返回 `CheckSortKey` 对应的 value。
+* 返回值：`CheckAndSetResult`、`error`
+ * `SetSucceed`: 是否 set 成功。
+ * `CheckValue`: `CheckSortKey` 对应的 value 值；该域只有在 `CheckValueExist` 为
`true` 时有意义。
+ * `CheckValueExist`: `CheckSortKey` 对应的 value 是否存在；该域只有在
`ReturnCheckValue` 为 `true` 时有意义。
+ * `ReturnCheckValue`: 是否返回了 `CheckSortKey` 对应的 value。
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型
### SortKeyCount
-获取某个HashKey下所有SortKey的个数。
+获取某个 HashKey 下所有 SortKey 的个数。
``` go
// Returns the count of sortkeys under hashkey.
// `hashKey`: CAN'T be nil or empty.
SortKeyCount(ctx context.Context, hashKey []byte) (int64, error)
```
注：
-* 参数：需传入context、hashKey
-* 返回值：返回HashKey下所有SortKey的个数
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型
+* 参数：需传入 `context`、`hashKey`
+* 返回值：返回 `HashKey` 下所有 `SortKey` 的个数
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型
### Incr
单行原子增(减)操作。详细说明参见[单行原子操作](/api/single-atomic#cas操作)。
-该操作先将key所指向的value的字节串转换为int64类型, 然后加上increment，将结果转换为字节串设置为新值。
-当参数increment为正数时，即原子加；当参数increment为负数时，即原子减。
+该操作先将 key 所指向的 value 的字节串转换为 int64 类型, 然后加上 increment，将结果转换为字节串设置为新值。
+当参数 increment 为正数时，即原子加；当参数 increment 为负数时，即原子减。
``` go
// Atomically increment value by key from the cluster.
// Returns the new value.
@@ -467,17 +471,17 @@ SortKeyCount(ctx context.Context, hashKey []byte) (int64,
error)
Incr(ctx context.Context, hashKey []byte, sortKey []byte, increment int64)
(int64, error)
```
注：
-* 参数：需传入context、hashKey、sortkey、increment
+* 参数：需传入 `context`、`hashKey`、`sortKey`、`increment`
* 返回值：操作成功后的新值、error
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型。另外以下情况也会抛出异常：
- * 旧值转换为int64时出错，譬如不是合法的数字或者超出int64范围。
- * 旧值加上increment后的结果超出int64范围。
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 error 获取具体错误类型。另外以下情况也会抛出异常：
+ * 旧值转换为 int64 时出错，譬如不是合法的数字或者超出 int64 范围。
+ * 旧值加上 increment 后的结果超出 int64 范围。
* 其他说明：
- * 如果旧值不存在，则把旧值当做0处理，即新值等于increment。
- * TTL语义：如果旧值存在，新值的TTL和旧值保持一致；如果旧值不存在，新值将不设TTL。
+ * 如果旧值不存在，则把旧值当做 0 处理，即新值等于 increment。
+ * TTL 语义：如果旧值存在，新值的 TTL 和旧值保持一致；如果旧值不存在，新值将不设 TTL。
### BatchGet
-读取一批数据，对get函数的批量封装。该函数并发地向server发送异步请求，并等待结果。如果有任意一个请求失败，就提前终止并抛出异常。如果抛出了异常，则values中的结果是未定义的。
+读取一批数据，对 get 函数的批量封装。该函数并发地向 server
发送异步请求，并等待结果。如果有任意一个请求失败，就提前终止并抛出异常。如果抛出了异常，则 values 中的结果是未定义的。
``` go
// Gets values from a batch of CompositeKeys. Internally it distributes each
key
// into a Get call and wait until all returned.
@@ -492,8 +496,8 @@ Incr(ctx context.Context, hashKey []byte, sortKey []byte,
increment int64) (int6
BatchGet(ctx context.Context, keys []CompositeKey) (values [][]byte, err error)
```
注：
-* 参数：需传入context、CompositeKey
-* 返回值：Values、error。如果读取成功，Values[i]中存放Keys[i]对应的结果，如果value不存在则为null。
-* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型。
+* 参数：需传入 `context`、`keys`
+* 返回值：`values`、`error`。如果读取成功，`values[i]` 中存放 `keys[i]` 对应的结果，如果 value 不存在则为
`nil`。
+* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问 `error` 获取具体错误类型。
* 其他说明：
* 该方法不是原子的，有可能出现部分成功部分失败的情况，只要任意一个失败都会抛出异常。
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
