Gnat.Jetstream.API.KV (gnat v1.12.1)

@type bucket_options() ::
  {:history, non_neg_integer()}
  | {:ttl, non_neg_integer()}
  | {:limit_marker_ttl, non_neg_integer()}
  | {:max_bucket_size, non_neg_integer()}
  | {:max_value_size, non_neg_integer()}
  | {:description, binary()}
  | {:replicas, non_neg_integer()}
  | {:storage, :file | :memory}
  | {:placement, Gnat.Jetstream.API.Stream.placement()}

Functions

contents(conn, bucket_name, opts \\ [])

@spec contents(conn :: Gnat.t(), bucket_name :: binary(), opts :: keyword()) ::
  {:ok, map()} | {:error, binary()}

Get all the non-deleted key-value pairs for a Bucket

Options

:batch - Number of messages to fetch per request (default: 250)
:domain - JetStream domain (default: nil)

Examples

iex> {:ok, %{"key1" => "value1"}} = Jetstream.API.KV.contents(:gnat, "my_bucket")
iex> {:ok, contents} = Jetstream.API.KV.contents(:gnat, "my_bucket", batch: 500)

create_bucket(conn, bucket_name, params \\ [])

@spec create_bucket(
  conn :: Gnat.t(),
  bucket_name :: binary(),
  params :: [bucket_options()]
) ::
  {:ok, Gnat.Jetstream.API.Stream.info()} | {:error, any()}

Create a new Key/Value bucket. Can include the following options

:history - How many historic values to keep per key (defaults to 1, max of 64)
:ttl - How long to keep values for (in nanoseconds)
:limit_marker_ttl - How long the bucket keeps markers when keys are removed by the TTL setting.
:max_bucket_size - The max number of bytes the bucket can hold
:max_value_size - The max number of bytes a value may be
:description - A description for the bucket
:replicas - How many replicas of the data to store
:storage - Storage backend to use (:file, :memory)
:placement - A map with :cluster (required) and :tags (optional)

Examples

iex> {:ok, info} = Jetstream.API.KV.create_bucket(:gnat, "my_bucket")

create_key(conn, bucket_name, key, value, opts \\ [])

@spec create_key(
  conn :: Gnat.t(),
  bucket_name :: binary(),
  key :: binary(),
  value :: binary(),
  opts :: keyword()
) :: :ok | {:error, any()}

Create a Key in a Key/Value Bucket

Options

:timeout - receive timeout for the request

Examples

iex> :ok = Jetstream.API.KV.create_key(:gnat, "my_bucket", "my_key", "my_value")

delete_bucket(conn, bucket_name)

@spec delete_bucket(conn :: Gnat.t(), bucket_name :: binary()) ::
  :ok | {:error, any()}

Delete a Key/Value bucket

Examples

iex> :ok = Jetstream.API.KV.delete_bucket(:gnat, "my_bucket")

delete_key(conn, bucket_name, key, opts \\ [])

@spec delete_key(
  conn :: Gnat.t(),
  bucket_name :: binary(),
  key :: binary(),
  opts :: keyword()
) :: :ok | {:error, any()}

Delete a Key from a K/V Bucket

Examples

iex> :ok = Jetstream.API.KV.delete_key(:gnat, "my_bucket", "my_key")

get_value(conn, bucket_name, key)

@spec get_value(conn :: Gnat.t(), bucket_name :: binary(), key :: binary()) ::
  binary() | {:error, any()} | nil

Get the value for a key in a particular K/V bucket

Examples

iex> "my_value" = Jetstream.API.KV.get_value(:gnat, "my_bucket", "my_key")

info(conn, bucket_name, opts \\ [])

@spec info(conn :: Gnat.t(), bucket_name :: binary(), keyword()) ::
  {:ok, Gnat.Jetstream.API.Stream.info()} | {:error, any()}

Information about the state of the bucket's Stream.

Opts

:domain - (default nil) the domain of the bucket

is_kv_bucket_stream?(stream_name)

This function is deprecated. Use Gnat.Jetstream.API.KV.kv_bucket_stream?/1 instead.

@spec is_kv_bucket_stream?(stream_name :: binary()) :: boolean()

keys(conn, bucket_name, opts \\ [])

@spec keys(conn :: Gnat.t(), bucket_name :: binary(), opts :: keyword()) ::
  {:ok, [binary()]} | {:error, binary()}

Get all the non-deleted keys for a Bucket

Options

:batch - Number of messages to fetch per request (default: 250)
:domain - JetStream domain (default: nil)

Examples

iex> {:ok, ["key1", "key2"]} = Jetstream.API.KV.keys(:gnat, "my_bucket")
iex> {:ok, keys} = Jetstream.API.KV.keys(:gnat, "my_bucket", batch: 500)

kv_bucket_stream?(stream_name)

@spec kv_bucket_stream?(stream_name :: binary()) :: boolean()

Returns true if the provided stream is a KV bucket, false otherwise

Parameters

stream_name - the stream name to test

list_buckets(conn)

@spec list_buckets(conn :: Gnat.t()) :: {:error, term()} | {:ok, [String.t()]}

Returns a list of all the buckets in the KV

purge_key(conn, bucket_name, key, opts \\ [])

@spec purge_key(
  conn :: Gnat.t(),
  bucket_name :: binary(),
  key :: binary(),
  opts :: keyword()
) :: :ok | {:error, any()}

Purge a Key from a K/V bucket. This will remove any revision history the key had

Examples

iex> :ok = Jetstream.API.KV.purge_key(:gnat, "my_bucket", "my_key")

put_value(conn, bucket_name, key, value, opts \\ [])

@spec put_value(
  conn :: Gnat.t(),
  bucket_name :: binary(),
  key :: binary(),
  value :: binary(),
  opts :: keyword()
) :: :ok | {:error, any()}

Put a value into a Key in a K/V Bucket

Examples

iex> :ok = Jetstream.API.KV.put_value(:gnat, "my_bucket", "my_key", "my_value")

unwatch(pid)

Stops a previously running monitor. This will unsubscribe from the key changes and remove the ephemeral consumer

Examples

iex> :ok = Jetstream.API.KV.unwatch(pid)

watch(conn, bucket_name, handler)

Starts a monitor for key changes in a given bucket. Supply a handler that will receive key change notifications.

Examples

iex> {:ok, _pid} = Jetstream.API.KV.watch(:gnat, "my_bucket", fn action, key, value ->
...>  IO.puts("#{action} taken on #{key}")
...> end)