struct

NATS::KV::Bucket

Inherits Struct / Value / Object

Instance methods

[]=(key : String, value : Data)

Set the value of a key

Source
[]?(key : String) : Bytes | Nil

Get the value of a key, if it exists (not counting Delete operations), stripping away all metadata to return only the value. If you need metadata such as revision, timestamp, or operation, or if you need to be able to get deleted keys, you should use Bucket#get instead.

Source
create(key : String, value : String)

Creates the given key with the given value if and only if the key does not yet exist.

Source
created
Source
delete(key : String)

Deletes the given key from the KV store. Inside the NATS server, this is implemented as adding another message to the stream that signifies deletion.

Source
description

An optional description of the purpose of this bucket

Source
each_key(pattern : String = ">", &)
Source
get(key : String, *, revision : Int | Nil = nil, ignore_deletes = false) : Entry | Nil

Get the entry for a key as a KV::Entry - returns nil if the key does not exist or if it's been deleted with ignore_deletes set to true.

Important: If you do not set ignore_deletes, you may get a deleted key. This is because the keys are stored in a stream and deleting the key sets an operation flag (implemented in the NATS server as a KV-Operation message header) and this method retrieves the last entry in the stream for this key. ignore_deletes simply tells the client to ignore deleted messages.

Source
get(keys : Enumerable(String), *, revision : Int | Nil = nil, ignore_deletes = false)
Source
get!(key : String, *, revision : Int | Nil = nil, ignore_deletes = false) : Entry

Get the value of a key as a KV::Entry - raises KeyError if the key does not exist or if it's been deleted with ignore_deletes set to true.

Source
history(key : String)

Get the history

Source
history

The number of revisions NATS will retain for this key

Source
keys(pattern : String = ">")

List all known keys for this bucket, returned as a Set(String).

Source
last_update
Source
max_bytes

The maximum size in bytes of this bucket in memory or on disk

Source
max_value_size

The maximum number of bytes in a value

Source
name

The name of this bucket

Source
placement
Source
purge(key : String)

Purges the given key from the KV store. Inside the NATS server, this is implemented as rolling up all versions of this key into a single message with its KV::Entry#operation value (KV-Operation header) set to KV::Entry::Operation::Purge.

Source
put(key : String, value : Data, ttl : Time::Span | Nil = nil)

Set the value of a key

Source
replicas

The number of NATS nodes to which this KV bucket will be replicated

Source
set(key : String, value : Data, ttl : Time::Span | Nil = nil)

Assign value to key in bucket asynchronously, not waiting for acknowledgement from the NATS server.

WARNING: Without acknowledgement, there is no guarantee the server received the value. Use with caution.

Source
size
Source
storage

Where NATS stores the data for this bucket

Source
stream_name

The name of the underlying JetStream stream.

Source
ttl

The maximum length of time NATS will retain a value or revision for a key

Source
update(key : String, value : String, revision : Int64)

Updates the given key with the given value if and only if it exists and is currently at the given revision. If you do not have the latest revision, this method returns nil so you can perform domain-specific conflict resolution. If you need to set the key regardless of revision, use Bucket#put instead.

Source
values
Source
watch(key : String, *, ignore_deletes = false, include_history = true)

Watch the given key (or wildcard) for changes and yielding them to the block. By default, this will also yield deleted messages. To avoid that, pass ignore_deletes: true.

bucket.watch("session.*") do |entry|
  _prefix, session_id = entry.subject.split('.', 2)
  if entry.operation.deleted?
    # do deleted things
  else
    # the session was updated
  end
end

This method blocks until the yielded Watch is stopped (use watch.stop), so if you want to run it in the background, you will need to run this method inside a spawn block.

You can also use this method to wait for a specific key to change once:

watch = bucket.watch(my_key)
watch.each do |entry|
  # react to the key change

  watch.stop if entry.latest? # exit the block
end
Source

Nested types