使用键值存储（Key/Value）

由于键值存储是在 JetStream 持久层之上构建的，你可以从你的 JetStream context 中获取 KeyValueManager 对象。

键必须与 NATS 主题采用相同格式，即它可以是以点分隔的标记列表（这意味着在监视存储桶时，你可以使用通配符来匹配键的层次结构），并且只能包含有效字符。值可以是任何字节数组。

创建和删除 KV 存储桶

你可以根据需要创建任意数量独立的键值存储实例，称为“存储桶”。存储桶通常是通过管理方式创建、清除或删除的（例如，使用 nats CLI 工具），但也可以使用以下 KeyValueManager 调用之一完成：

Go

// KeyValue will lookup and bind to an existing KeyValue store.
KeyValue(bucket string) (KeyValue, error)
// CreateKeyValue will create a KeyValue store with the following configuration.
CreateKeyValue(cfg *KeyValueConfig) (KeyValue, error)
// DeleteKeyValue will delete this KeyValue store (JetStream stream).
DeleteKeyValue(bucket string) error

Java

JavaScript

Python

C#

C

Getting

You can do a get to get the current value on a key, or ask to get a specific revision of the value.

Go

// Get returns the latest value for the key.
Get(key string) (entry KeyValueEntry, err error)
// GetRevision returns a specific revision value for the key.
GetRevision(key string, revision uint64) (entry KeyValueEntry, err error)

Java

Python

C#

C

Putting

The key is always a string, you can simply use Put to store a byte array, or the convenience PutString to put a string. For 'compare and set' functionality you can use Create and Update.

Go

Put(key string, value []byte) (revision uint64, err error)
// PutString will place the string for the key into the store.
PutString(key string, value string) (revision uint64, err error)
// Create will add the key/value pair if it does not exist.
Create(key string, value []byte) (revision uint64, err error)
// Update will update the value if the latest revision matches.
Update(key string, value []byte, last uint64) (revision uint64, err error)

Java

JavaScript

Python

C#

C

Deleting

You can delete a specific key, or purge the whole key/value bucket.

Go

// Delete will place a delete marker and leave all revisions.
Delete(key string) error
// Purge will place a delete marker and remove all previous revisions.
Purge(key string) error

Java

JavaScript

Python

C#

C

Getting all the keys

You can get the list of all the keys currently having a value associated using Keys()

Go

// Keys will return all keys.
Keys(opts ...WatchOpt) ([]string, error)

Java

JavaScript

C#

C

Getting the history for a key

The JetStream key/value store has a feature you don't usually find in key/value stores: the ability to keep a history of the values associated with a key (rather than just the current value). The depth of the history is specified when the key/value bucket is created, and the default is a history depth of 1 (i.e. no history).

Go

// History will return all historical values for the key.
History(key string, opts ...WatchOpt) ([]KeyValueEntry, error)

Java

JavaScript

C#

C

Watching for changes

Watching a key/value bucket is like subscribing to updates: you provide a callback and you can watch all of the keys in the bucket or specify which specific key(s) you want to be kept updated about.

Go

// Watch for any updates to keys that match the keys argument which could include wildcards.
// Watch will send a nil entry when it has received all initial values.
Watch(keys string, opts ...WatchOpt) (KeyWatcher, error)
// WatchAll will invoke the callback for all updates.
WatchAll(opts ...WatchOpt) (KeyWatcher, error)

Java

JavaScript

C#

C