FeoxDB.Term (feox_db v0.2.0)

Copy Markdown View Source

Stores arbitrary Erlang terms in a FeoxDB store, using the External Term Format (ETF) for both keys and values.

Values whose encoding is larger than FeoxDB's per-value limit are split into chunks transparently: put/4 writes the chunks under internal keys followed by a small manifest under the key itself, and get/2 reassembles them. Callers never see the chunks.

{:ok, store} = FeoxDB.open()
:ok = FeoxDB.Term.put(store, {:user, 1}, %{name: "Ada"})
{:ok, %{name: "Ada"}} = FeoxDB.Term.get(store, {:user, 1})

A store used through this module should only be accessed through this module: chunks live under keys that start with a 0 byte and every encoded key starts with the ETF version byte (131), so binary keys written with FeoxDB.insert/4 can collide with either.

Values are decoded with :erlang.binary_to_term/2's :safe option, so a value referencing an atom that does not exist in the reading VM returns {:error, :corrupted_data} instead of creating it.

A chunked overwrite writes the new chunks before the manifest that points at them and only then deletes the old chunks, so a concurrent get/2 sees either the old or the new value.

Summary

Functions

Deletes key and any chunks of its value.

Returns the term stored under key.

Returns whether key exists in the store.

Stores value under key, both arbitrary terms.

Returns a lazy stream of every {key, value} pair in the store, in ETF key order. Chunked values are reassembled; entries deleted while the stream runs are skipped.

Functions

delete(store, key)

@spec delete(FeoxDB.store(), term()) :: :ok | {:error, FeoxDB.error_reason()}

Deletes key and any chunks of its value.

get(store, key)

@spec get(FeoxDB.store(), term()) :: {:ok, term()} | {:error, FeoxDB.error_reason()}

Returns the term stored under key.

member?(store, key)

@spec member?(FeoxDB.store(), term()) :: boolean() | {:error, FeoxDB.error_reason()}

Returns whether key exists in the store.

put(store, key, value, opts \\ [])

@spec put(FeoxDB.store(), term(), term(), keyword()) ::
  :ok | {:error, FeoxDB.error_reason()}

Stores value under key, both arbitrary terms.

Options

  • :ttl - expiry in seconds, as in FeoxDB.insert/4.
  • :chunk_size - maximum bytes stored per record before the value is split into chunks. Defaults to (and may not exceed) the FeoxDB value size limit.

stream(store)

@spec stream(FeoxDB.store()) :: Enumerable.t({term(), term()})

Returns a lazy stream of every {key, value} pair in the store, in ETF key order. Chunked values are reassembled; entries deleted while the stream runs are skipped.