Public API for the Concord distributed key-value store.
Concord is a CP (Consistent + Partition-tolerant) distributed KV store
built on the Raft consensus algorithm via the ra library.
Examples
iex> Concord.put("user:123", %{name: "Alice"})
:ok
iex> Concord.get("user:123")
{:ok, %{name: "Alice"}}
iex> Concord.delete("user:123")
:okSummary
Functions
Deletes a key from the cluster.
Conditionally deletes a key only if it matches the expected value.
Deletes multiple keys from the cluster atomically.
Retrieves a value by key from the cluster.
Returns all key-value pairs in the store. Use sparingly on large datasets.
Returns all key-value pairs with their TTL information. Use sparingly on large datasets.
Retrieves multiple values by key from the cluster.
Gets a value along with its remaining TTL.
Lists keys matching a prefix or range selector.
Returns cluster members information.
Returns key-value pairs for all keys starting with the given prefix.
Stores a key-value pair in the cluster.
Conditionally updates a key only if it matches the expected value (compare-and-swap).
Stores multiple key-value pairs in the cluster atomically.
Stores multiple key-value pairs with a TTL atomically.
Stores a key-value pair with an explicit TTL in seconds.
Returns the current cluster revision.
Returns cluster status information.
Extends the TTL of an existing key by the specified number of seconds.
Extends the TTL of multiple keys atomically.
Gets the remaining TTL for a key in seconds.
Commits a transaction atomically.
Functions
Deletes a key from the cluster.
Options
:timeout- Operation timeout in milliseconds (default: 5000)
Conditionally deletes a key only if it matches the expected value.
Options
:timeout- Operation timeout in milliseconds (default: 5000):token- Authentication token (required if auth is enabled)
Examples
# Only delete if current value matches
Concord.delete_if("lock", expected: "my_lock_id")
# => :ok
# Fails if value doesn't match
Concord.delete_if("lock", expected: "different_id")
# => {:error, :condition_failed}
# Delete with predicate
Concord.delete_if("temp:file",
condition: fn value -> value.created_at < cutoff_time end
)Deletes multiple keys from the cluster atomically.
Either all operations succeed or all fail together.
Options
:timeout- Operation timeout in milliseconds (default: 5000):token- Authentication token (required if auth is enabled)
Examples
iex> Concord.delete_many(["key1", "key2"])
{:ok, %{"key1" => :ok, "key2" => :ok}}Retrieves a value by key from the cluster.
Options
:timeout- Operation timeout in milliseconds (default: 5000):consistency- Read consistency level (default: :leader):eventual- Fastest, may return stale data (reads from any node):leader- Balanced, reads from leader node:strong- Linearizable reads with heartbeat verification (slowest)
Returns all key-value pairs in the store. Use sparingly on large datasets.
Options
:timeout- Operation timeout in milliseconds (default: 5000):consistency- Read consistency level (default: :leader)
Returns all key-value pairs with their TTL information. Use sparingly on large datasets.
Options
:timeout- Operation timeout in milliseconds (default: 5000):consistency- Read consistency level (default: :leader)
Examples
iex> Concord.get_all_with_ttl(token: "token")
{:ok, %{"key1" => %{value: "val1", ttl: 3600}, "key2" => %{value: "val2", ttl: nil}}}Retrieves multiple values by key from the cluster.
Options
:timeout- Operation timeout in milliseconds (default: 5000):consistency- Read consistency level (default: :leader)
Examples
iex> Concord.get_many(["key1", "key2"])
{:ok, %{"key1" => {:ok, "value1"}, "key2" => {:error, :not_found}}}Gets a value along with its remaining TTL.
Options
:timeout- Operation timeout in milliseconds (default: 5000):consistency- Read consistency level (default: :leader)
Examples
iex> Concord.get_with_ttl("cache:user:123")
{:ok, {%{data: "value"}, 1800}}Lists keys matching a prefix or range selector.
See Concord.KV.list/1.
Returns cluster members information.
Returns key-value pairs for all keys starting with the given prefix.
Uses an efficient server-side scan on the ordered ETS table, avoiding loading all keys into memory. O(log N + K) where K is the number of matching keys.
Options
:timeout- Operation timeout in milliseconds (default: 5000):consistency- Read consistency level (default: :leader)
Examples
iex> Concord.prefix_scan("user:")
{:ok, [{"user:1", %{name: "Alice"}}, {"user:2", %{name: "Bob"}}]}Stores a key-value pair in the cluster.
Values are automatically compressed if they exceed the configured size threshold (default: 1KB). Compression is transparent and values are automatically decompressed when retrieved.
Options
:timeout- Operation timeout in milliseconds (default: 5000):ttl- Time-to-live in seconds (default: nil for no expiration):compress- Override automatic compression (true/false)
Conditionally updates a key only if it matches the expected value (compare-and-swap).
This provides atomic conditional updates, useful for implementing locks, counters, and other concurrent data structures.
Options
:timeout- Operation timeout in milliseconds (default: 5000):ttl- Time-to-live in seconds for the new value:compress- Override automatic compression (true/false)
Examples
# Only update if current value matches
Concord.put_if("counter", 1, expected: 0)
# => :ok
# Fails if value doesn't match
Concord.put_if("counter", 2, expected: 0)
# => {:error, :condition_failed}
# Conditional update with predicate
Concord.put_if("config", new_config,
condition: fn old_value -> old_value.version < new_config.version end
)Stores multiple key-value pairs in the cluster atomically.
Either all operations succeed or all fail together.
Options
:timeout- Operation timeout in milliseconds (default: 5000):token- Authentication token (required if auth is enabled)
Examples
iex> Concord.put_many([{"key1", "value1"}, {"key2", "value2"}])
{:ok, %{"key1" => :ok, "key2" => :ok}}Stores multiple key-value pairs with a TTL atomically.
Options
:timeout- Operation timeout in milliseconds (default: 5000):token- Authentication token (required if auth is enabled)
Examples
iex> Concord.put_many_with_ttl([{"key1", "value1"}, {"key2", "value2"}], 3600)
{:ok, %{"key1" => :ok, "key2" => :ok}}Stores a key-value pair with an explicit TTL in seconds.
Options
:timeout- Operation timeout in milliseconds (default: 5000):token- Authentication token (required if auth is enabled)
Examples
iex> Concord.put_with_ttl("cache:user:123", %{data: "value"}, 3600)
:okReturns the current cluster revision.
Returns cluster status information.
Options
:timeout- Operation timeout in milliseconds (default: 5000):consistency- Read consistency level (default: :leader)
Extends the TTL of an existing key by the specified number of seconds.
Options
:timeout- Operation timeout in milliseconds (default: 5000):token- Authentication token (required if auth is enabled)
Examples
iex> Concord.touch("cache:user:123", 1800)
:okExtends the TTL of multiple keys atomically.
Either all operations succeed or all fail together.
Options
:timeout- Operation timeout in milliseconds (default: 5000):token- Authentication token (required if auth is enabled)
Examples
iex> Concord.touch_many([{"key1", 1800}, {"key2", 3600}])
{:ok, %{"key1" => :ok, "key2" => :ok}}Gets the remaining TTL for a key in seconds.
Returns nil if the key has no expiration. Returns {:error, :not_found} if the key doesn't exist or has expired.
Options
:timeout- Operation timeout in milliseconds (default: 5000):consistency- Read consistency level (default: :leader)
Examples
iex> Concord.ttl("cache:user:123")
{:ok, 1800}Commits a transaction atomically.
See Concord.Txn.commit/2.