This is an automated email from the ASF dual-hosted git repository.
laiyingchun 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 e48c4e54 Fix go client doc format (#115)
e48c4e54 is described below
commit e48c4e54cc2873ba8917c7de9b936c8ee4b6dcae
Author: Dan Wang <[email protected]>
AuthorDate: Tue May 27 22:55:49 2025 +0800
Fix go client doc format (#115)
---
_docs/zh/clients/go-client.md | 475 +++++++++++++++++++++---------------------
1 file changed, 237 insertions(+), 238 deletions(-)
diff --git a/_docs/zh/clients/go-client.md b/_docs/zh/clients/go-client.md
index 9efaa906..7179efcb 100644
--- a/_docs/zh/clients/go-client.md
+++ b/_docs/zh/clients/go-client.md
@@ -12,9 +12,9 @@ go get
github.com/apache/incubator-pegasus/go-client@<CommitId>
go get github.com/apache/incubator-pegasus/go-client@df0eb5a
```
-注：
- * thrift 0.13
- * Go1.18+
+要求：
+* Go 1.18+
+* Thrift 0.13
# 客户端配置
创建go client实例需要配置相关参数，目前仅支持参数传递方式。
@@ -22,23 +22,25 @@ go client的配置参数非常简单，仅需要指定meta servers。
用户如果需要文件配置，需自行将参数从文件从解析，再传入go client。
```go
// 参数配置
- cfg := &pegasus.Config{
- MetaServers: []string{"0.0.0.0:34601", "0.0.0.0:34601"},
- }
- c := pegasus.NewClient(*cfg)
+cfg := &pegasus.Config{
+ MetaServers: []string{"0.0.0.0:34601", "0.0.0.0:34601"},
+}
+c := pegasus.NewClient(*cfg)
// 文件配置
- 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)
+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)
```
+
# 接口定义
+
## 创建Client实例
```go
// NewClient creates a new instance of pegasus client.
@@ -52,32 +54,33 @@ type Config struct {
```
使用完毕后，记得close client以释放资源，譬如：
-
```go
c := pegasus.NewClient(*cfg)
-...
+
...
+
c.Close();
```
## 创建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)
+// 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接口
-### get
+
+### Get
读单行数据。
```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)
+// 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)
```
注：
* 参数：需传入context、hashKey、sortKey。
@@ -87,12 +90,12 @@ go client 操作数据的接口都在TableConnector中定义。
### Set | SetTTL
写单行数据, SetTTL可以设置单条kv的TTL。
```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
+// 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
```
注：
* 提供了两个版本的接口，其中第二个接口可以指定TTL时间。
@@ -103,10 +106,10 @@ go client 操作数据的接口都在TableConnector中定义。
### Del
删除单行数据
```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
+// 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
```
注：
* 参数：需传入context、hashKey、sortKey。
@@ -115,19 +118,19 @@ go client 操作数据的接口都在TableConnector中定义。
### MultiGet | MultiGetOpt
读**同一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)
+// 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)
```
注:
* 参数：需传入context、hashKey、sortKeys。
@@ -135,36 +138,40 @@ go client 操作数据的接口都在TableConnector中定义。
* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型(key对应数据不存在不会报错)。
*
bool值表示:如果用户指定了maxFetchCount或者maxFetchSize，单次查询可能只获取到部分结果。如果所有满足条件的数据都已经获取到，则返回true；否则返回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)
- )
+// 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)
+)
```
注：
* MultiGetOptions说明：
@@ -186,19 +193,18 @@ go client 操作数据的接口都在TableConnector中定义。
### MultiGetRange | MultiGetRangeOpt
读**同一HashKey下**的多行数据，支持范围查询。
``` 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)
+// 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)
```
注：
* 参数：需传入context、hashKey、startSortKey、stopSortKey
@@ -209,12 +215,11 @@ go client 操作数据的接口都在TableConnector中定义。
### MultiSet | MultiSetOpt
写同一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
-
+// 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
```
注：
* MultiSet调用了rocksdb的WriteBatch接口，因此MultiSet是一个原子操作
@@ -225,10 +230,10 @@ go client 操作数据的接口都在TableConnector中定义。
### 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
+// 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
```
注：
* MultiDel调用了rocksdb的WriteBatch接口，因此MultiDel是一个原子操作
@@ -238,23 +243,23 @@ go client 操作数据的接口都在TableConnector中定义。
### DelRange | 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
- }
+// 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
+}
```
注：
* DelRange实际调用了多次MultiDel, 每次MultiDel是原子的，但是DelRange整体可能不是原子的。
@@ -268,12 +273,12 @@ go client 操作数据的接口都在TableConnector中定义。
* 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.
- // `sortKey` : CAN'T be nil but CAN be empty.
- TTL(ctx context.Context, hashKey []byte, sortKey []byte) (int, error)
+// 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)
```
注：
* 参数：需传入context、hashKey、sortKey
@@ -281,11 +286,11 @@ go client 操作数据的接口都在TableConnector中定义。
* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问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)
+// 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
@@ -295,21 +300,21 @@ go client 操作数据的接口都在TableConnector中定义。
### GetScanner
获取遍历某个HashKey下所有数据的迭代器，用于局部扫描。
``` 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
- }
+// 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
+}
```
注：
* 参数：需传入context、hashKey、startSortKey、stopSortKey、ScannnerOptions
@@ -325,13 +330,12 @@ go client 操作数据的接口都在TableConnector中定义。
* 返回值：迭代器Scanner, error
* 异常：如果出现异常，譬如网络错误、超时错误、服务端错误等，可以访问error获取具体错误类型
-
### GetUnorderedScanners
获取遍历整个表的所有数据的迭代器，用于全局扫描。
``` 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)
+// 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)
```
注：
* 参数：需传入context、maxSplitCount、ScannnerOptions
@@ -342,13 +346,13 @@ go client 操作数据的接口都在TableConnector中定义。
### Next
在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)
+// 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
- }
+ Close() error
+}
```
注：
* 参数：需传入context
@@ -359,76 +363,72 @@ go client 操作数据的接口都在TableConnector中定义。
### CheckAndSet
单hashKey数据的原子CAS操作（可以理解为单行原子操作）。详细说明参见[单行原子操作](/api/single-atomic#cas操作)。
该操作先对某个SortKey（称之为checkSortKey）的value做条件检查：
- * 如果检查的条件满足，则将另一个SortKey（称之为setSortKey）的value设置为新值。
- * 如果检查的条件不满足，则不执行set操作。
+* 如果检查的条件满足，则将另一个SortKey（称之为setSortKey）的value设置为新值。
+* 如果检查的条件不满足，则不执行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.
- // 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
- }
+// 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
+}
```
注：
*
参数：需传入context、hashKey、checkSortKey、checkType、checkOperand、setSortKey、setValue、CheckAndSetOptions
@@ -446,11 +446,10 @@ checkSortKey和setSortKey可以相同也可以不同。
### SortKeyCount
获取某个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)
+// Returns the count of sortkeys under hashkey.
+// `hashKey`: CAN'T be nil or empty.
+SortKeyCount(ctx context.Context, hashKey []byte) (int64, error)
```
注：
* 参数：需传入context、hashKey
@@ -462,10 +461,10 @@ checkSortKey和setSortKey可以相同也可以不同。
该操作先将key所指向的value的字节串转换为int64类型, 然后加上increment，将结果转换为字节串设置为新值。
当参数increment为正数时，即原子加；当参数increment为负数时，即原子减。
``` 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)
+// 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)
```
注：
* 参数：需传入context、hashKey、sortkey、increment
@@ -480,17 +479,17 @@ checkSortKey和setSortKey可以相同也可以不同。
### BatchGet
读取一批数据，对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.
- //
- // `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)
+// 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)
```
注：
* 参数：需传入context、CompositeKey
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
