subspace

Documentation

Overview

Package subspace provides a convenient way to use FoundationDB tuples to define namespaces for different categories of data. The namespace is specified by a prefix tuple which is prepended to all tuples packed by the subspace. When unpacking a key with the subspace, the prefix tuple will be removed from the result.

As a best practice, API clients should use at least one subspace for application data. For general guidance on subspace usage, see the Subspaces section of the Developer Guide (https://apple.github.io/foundationdb/developer-guide.html#subspaces).

Index

• type Subspace
  • func AllKeys() Subspace
  • func FromBytes(b []byte) Subspace
  • func Sub(el ...tuple.TupleElement) Subspace

Types

type Subspace

type Subspace interface {
	// Sub returns a new Subspace whose prefix extends this Subspace with the
	// encoding of the provided element(s). If any of the elements are not a
	// valid tuple.TupleElement, Sub will panic.
	Sub(el ...tuple.TupleElement) Subspace

	// Bytes returns the literal bytes of the prefix of this Subspace.
	Bytes() []byte

	// Pack returns the key encoding the specified Tuple with the prefix of this
	// Subspace prepended.
	Pack(t tuple.Tuple) fdb.Key

	// PackWithVersionstamp returns the key encoding the specified tuple in
	// the subspace so that it may be used as the key in fdb.Transaction's
	// SetVersionstampedKey() method. The passed tuple must contain exactly
	// one incomplete tuple.Versionstamp instance or the method will return
	// with an error. The behavior here is the same as if one used the
	// tuple.PackWithVersionstamp() method to appropriately pack together this
	// subspace and the passed tuple.
	PackWithVersionstamp(t tuple.Tuple) (fdb.Key, error)

	// Unpack returns the Tuple encoded by the given key with the prefix of this
	// Subspace removed. Unpack will return an error if the key is not in this
	// Subspace or does not encode a well-formed Tuple.
	Unpack(k fdb.KeyConvertible) (tuple.Tuple, error)

	// Contains returns true if the provided key starts with the prefix of this
	// Subspace, indicating that the Subspace logically contains the key.
	Contains(k fdb.KeyConvertible) bool

	// All Subspaces implement fdb.KeyConvertible and may be used as
	// FoundationDB keys (corresponding to the prefix of this Subspace).
	fdb.KeyConvertible

	// All Subspaces implement fdb.ExactRange and fdb.Range, and describe all
	// keys strictly within the subspace that encode tuples. Specifically,
	// this will include all keys in [prefix + '\x00', prefix + '\xff').
	fdb.ExactRange
}

Subspace represents a well-defined region of keyspace in a FoundationDB database.

func AllKeys

func AllKeys() Subspace

AllKeys returns the Subspace corresponding to all keys in a FoundationDB database.

func FromBytes

func FromBytes(b []byte) Subspace

FromBytes returns a new Subspace from the provided bytes.

func Sub

func Sub(el ...tuple.TupleElement) Subspace

Sub returns a new Subspace whose prefix is the encoding of the provided element(s). If any of the elements are not a valid tuple.TupleElement, a runtime panic will occur.