Public entry point for the Aerospike Elixir driver.
Aerospike exposes the low-level API for starting a supervised cluster,
constructing keys, and running commands against that cluster. Most
applications should define an Aerospike.Repo module to bind this API to
one configured cluster; lower-level code can call this module directly when
it needs explicit control over the cluster name.
The main command families are:
get/3reads all bins for a keyget_header/2reads only record metadata for a keyput/4writes a bin mapput_payload/4sends a caller-built single-record write/delete frameapply_udf/6executes one record UDF against one keyregister_udf/3,register_udf/4,remove_udf/2,remove_udf/3, andlist_udfs/1/list_udfs/2manage server-side UDF packages and return explicit metadata/task handlestruncate/2,truncate/3, andtruncate/4expose one-node operator truncation helpers with explicit namespace and set formscreate_user/5,create_pki_user/4,drop_user/3,change_password/4,grant_roles/4,revoke_roles/4,query_user/3,query_users/2,create_role/4,drop_role/3,set_whitelist/4,set_quotas/5,grant_privileges/4,revoke_privileges/4,query_role/3, andquery_roles/2expose the enterprise security-admin seamadd/4,append/4, andprepend/4expose thin unary write helpers for common counter and string mutationsmetrics_enabled?/1,enable_metrics/2,disable_metrics/1,stats/1, andwarm_up/2expose opt-in runtime metrics and an explicit operator pool probe over the already-started workerstouch/2updates record metadatadelete/2removes a recordexists/2performs a header-only existence probeoperate/4runs simple, CDT-style, and expression operation lists built withAerospike.Op,Aerospike.Op.List,Aerospike.Op.Map,Aerospike.Op.Exp, andAerospike.Ctx- unary commands (
get/3,get_header/2,put/4,exists/2,touch/2,delete/2,operate/4,apply_udf/6,add/4,append/4, andprepend/4) accept%Aerospike.Exp{}via:filterfor server-side execution filtering Aerospike.Expbuilds server-side expression values, including values usable as expression-backed secondary-index sourcescreate_expression_index/5creates expression-backed secondary indexes on servers that support them and returns a pollable index taskbatch_get/4,batch_get_header/3,batch_exists/3,batch_get_operate/4,batch_delete/3, andbatch_udf/6operate on multiple keys and return per-key results in caller orderAerospike.Batchandbatch_operate/3expose a curated heterogeneous batch surface for mixing reads, writes, deletes, operations, and record UDF calls while returning one%Aerospike.BatchResult{}per inputchild_spec/1,close/2,key/3, andkey_digest/3round out the root lifecycle and key-construction boundaryinfo/3,info_node/4,nodes/1, andnode_names/1expose one-node operator reads over the published cluster view;info_node/4targets one named active node discovered fromnode_names/1ornodes/1set_xdr_filter/4sets or clears Enterprise XDR expression filters through a one-node info commandquery_stream!/3,query_all/3,query_count/3,query_aggregate/6, andquery_aggregate_result/6run secondary-index queries through the same node-preparation pipeline, with lazy outer streams but node-buffered record delivery and optional%Aerospike.Exp{}filters throughQuery.filter/2when a secondary-index predicate fromQuery.where/2is also used.query_execute/4andquery_udf/6run background query jobs on that same setup path and return pollable task handlesscan_stream/3,scan_stream!/3,scan_all/3,scan_all!/3,scan_count/3,scan_count!/3,scan_page/3, andscan_page!/3run scan fan-out across the same scan/runtime setup, again with lazy outer streams, node-buffered record delivery, and resumable pages- scan/query helpers that already support node targeting accept
node: node_nameinopts; discover names withnode_names/1ornodes/1
Quick-start shape:
{:ok, _sup} =
Aerospike.start_link(
name: :aerospike,
transport: Aerospike.Transport.Tcp,
hosts: ["127.0.0.1:3000"],
namespaces: ["test"],
pool_size: 2
)
Aerospike.Cluster.ready?(:aerospike)Scan and query stream helpers are lazy at the Enumerable boundary. The
runtime buffers each node's response before yielding that node's records
downstream.
Expression builders cover scalar, metadata, arithmetic, conditional, variable, CDT, bit, and HyperLogLog helper families. Public command and startup options are keyword-based and validated by the facade before command execution.
Summary
Types
Option accepted by one-node info/admin helpers.
Keyword options accepted by one-node info/admin helpers.
Additional local-source option for finalized aggregate queries.
Keyword options accepted by query_aggregate_result/6 and query_aggregate_result!/6.
Parent batch dispatch option.
Parent batch options accepted by batch_operate/3.
Batch read option accepted by homogeneous batch-read helpers.
Keyword options accepted by batch read helpers.
Batch read option accepted by per-entry batch reads.
Keyword options accepted by per-entry batch reads.
Batch write option accepted by per-entry batch writes.
Keyword options accepted by per-entry batch writes.
Batch write option accepted by homogeneous batch-write helpers.
Keyword options accepted by batch write helpers.
Identifier for a running cluster facade.
Commit acknowledgement level for write commands.
Option accepted by create_expression_index/5.
Keyword options accepted by create_expression_index/5.
Option accepted by create_index/4.
Keyword options accepted by create_index/4.
Role-creation option accepted by create_role/4.
Keyword options accepted by create_role/4.
Generation check behavior for write commands.
Secondary-index collection type.
Secondary-index particle/source type.
Option accepted by enable_metrics/2.
Keyword options accepted by enable_metrics/2.
Registered atom name for a running cluster.
One active cluster node as returned by nodes/1.
Node-targeting option accepted by scan/query helpers that support single-node execution.
Operation input accepted by operate/4.
Security privilege metadata used by role administration APIs.
AP namespace read consistency.
Strong-consistency namespace read consistency.
Read option accepted by get/4, get_header/3, and exists/3.
Keyword options accepted by read helpers.
Record existence behavior for write commands.
Retry option accepted by single-record, scan, and query command families.
Security role metadata returned by query_role/3 and query_roles/2.
Runtime option accepted by scan/query helpers that may target one node.
Keyword options accepted by scan and query helpers.
Runtime option accepted by all scan and query helpers.
Option accepted by security-admin helpers.
Keyword options accepted by security-admin helpers.
Non-negative timeout value in milliseconds.
Transaction options accepted by transaction/3 when a handle is not supplied.
Option accepted by truncate/3 and truncate/4.
Keyword options accepted by truncate helpers.
Record TTL accepted by write commands.
Security user metadata returned by query_user/3 and query_users/2.
Option accepted by warm_up/2.
Keyword options accepted by warm_up/2.
Write option accepted by single-record write, delete, UDF, and operate helpers.
Keyword options accepted by single-record write, delete, UDF, and operate helpers.
Functions
Aborts a transaction on the named cluster cluster.
Atomically adds numeric deltas in bins for key.
Deprecated alias for scan_all/3.
Deprecated alias for scan_all!/3.
Atomically appends string suffixes in bins for key.
Executes one record UDF against key.
Deletes multiple keys from cluster.
Checks existence for multiple keys from cluster.
Reads multiple keys from cluster in one batch request per target node.
Reads record headers for multiple keys from cluster.
Runs one read-only operation list for multiple keys from cluster.
Executes heterogeneous batch entries built with Aerospike.Batch.
Executes one record UDF for multiple keys from cluster.
Changes a security user's password.
Returns a child specification for one supervised cluster.
Stops the supervised cluster registered under the atom cluster.
Commits a transaction on the named cluster cluster.
Deprecated alias for scan_count/3.
Deprecated alias for scan_count!/3.
Creates an expression-backed secondary index and returns a pollable task handle.
Creates a secondary index and returns a pollable task handle.
Creates a PKI-authenticated security user.
Creates a security role.
Creates a password-authenticated security user.
Deletes key from cluster.
Disables internal runtime metrics for cluster.
Drops a secondary index.
Drops a security role.
Drops a security user.
Enables internal runtime metrics for cluster.
Returns whether key exists in cluster without reading bins.
Reads key from cluster.
Reads only record metadata for key from cluster.
Grants privileges to a security role.
Grants roles to a security user.
Sends one info command to one active cluster node and returns that node's reply.
Sends one info command to the named active cluster node and returns that node's reply.
Builds a key from namespace, set, and a user key.
Builds a key from namespace, set, and an existing 20-byte digest.
Lists the registered server-side UDF packages visible from one active node.
Returns whether internal runtime metrics are enabled for cluster.
Returns the published active cluster node-name snapshot.
Returns the published active cluster nodes with their direct-connect host and port.
Runs a constrained unary operate list for key.
Atomically prepends string prefixes in bins for key.
Writes bins for key to cluster.
Sends a caller-built single-record write/delete frame for key.
Same as put_payload/4 but returns :ok or raises Aerospike.Error.
Streams aggregate query values over the same node-buffered query
runtime used by query_stream/3.
Returns one finalized aggregate query result.
Same as query_aggregate_result/6 but returns the value or raises
Aerospike.Error.
Eagerly collects query records into a list.
Same as query_all/3 but returns the list or raises Aerospike.Error.
Counts query matches without materializing the records.
Same as query_count/3 but returns the count or raises Aerospike.Error.
Starts a background query write job that applies the given operations.
Returns one collected query page and a resumable cursor when more records remain.
Same as query_page/3 but returns the page or raises Aerospike.Error.
Queries one security role.
Queries all security roles visible to the authenticated cluster user.
Returns a lazy Stream of records from a secondary-index query.
Same as query_stream/3 but raises on error.
Starts a background query UDF job.
Queries one security user.
Queries all security users visible to the authenticated cluster user.
Uploads a UDF package from inline source or a readable local .lua path.
Removes a registered UDF package by server filename.
Revokes privileges from a security role.
Revokes roles from a security user.
Eagerly collects scan records into a list.
Same as scan_all/3 but returns the list or raises Aerospike.Error.
Counts scan matches without materializing the records.
Same as scan_count/3 but returns the count or raises Aerospike.Error.
Returns one collected scan page and a resumable cursor when more records remain.
Same as scan_page/3 but returns the page or raises Aerospike.Error.
Returns a lazy Stream of records from a scan.
Same as scan_stream/3 but raises on error.
Sets read and write quota limits for a security role.
Sets or clears a security role's client-address whitelist.
Sets or clears the Enterprise XDR filter for one datacenter and namespace.
Starts a supervised cluster.
Returns the current internal runtime metrics snapshot for cluster.
Deprecated alias for scan_stream!/3.
Updates key's header metadata in cluster.
Runs a function within a new transaction on the named cluster cluster.
Runs a function within a transaction on the named cluster cluster using a
provided handle or options.
Truncates all records in namespace.
Truncates all records in namespace and set.
Returns the current state of a transaction on the named cluster cluster.
Verifies that the active node pools can serve checkouts through the normal path.
Types
@type admin_opt() :: {:pool_checkout_timeout, timeout_ms()}
Option accepted by one-node info/admin helpers.
:pool_checkout_timeout bounds checkout from the selected node pool before
the one-node info/admin command is sent.
@type admin_opts() :: [admin_opt()]
Keyword options accepted by one-node info/admin helpers.
Additional local-source option for finalized aggregate queries.
Exactly one of these is required by query_aggregate_result/6: inline Lua
source via :source, or a readable local file path via :source_path.
@type aggregate_result_opts() :: [scan_query_runtime_opt() | aggregate_result_opt()]
Keyword options accepted by query_aggregate_result/6 and query_aggregate_result!/6.
@type batch_parent_opt() :: {:timeout, timeout_ms()} | {:socket_timeout, timeout_ms()} | {:max_concurrent_nodes, non_neg_integer()} | {:allow_partial_results, boolean()} | {:respond_all_keys, boolean()} | {:allow_inline, boolean()} | {:allow_inline_ssd, boolean()}
Parent batch dispatch option.
Parent options describe the batch request as a whole: deadline, node
concurrency, partial-result handling, response shape, and inline execution
hints. Per-record read/write policy belongs on batch_record_read_opt/0 and
batch_record_write_opt/0.
@type batch_parent_opts() :: [batch_parent_opt()]
Parent batch options accepted by batch_operate/3.
@type batch_read_opt() :: batch_parent_opt() | batch_record_read_opt()
Batch read option accepted by homogeneous batch-read helpers.
@type batch_read_opts() :: [batch_read_opt()]
Keyword options accepted by batch read helpers.
@type batch_record_read_opt() :: {:filter, Aerospike.Exp.t() | nil} | {:read_mode_ap, read_mode_ap()} | {:read_mode_sc, read_mode_sc()} | {:read_touch_ttl_percent, -1 | 0..100}
Batch read option accepted by per-entry batch reads.
These options are encoded with one batch read entry. Parent dispatch options
are only accepted by homogeneous batch read helpers and batch_operate/3.
@type batch_record_read_opts() :: [batch_record_read_opt()]
Keyword options accepted by per-entry batch reads.
@type batch_record_write_opt() :: {:ttl, ttl()} | {:generation, non_neg_integer()} | {:generation_policy, generation_policy()} | {:exists, record_exists_action()} | {:commit_level, commit_level()} | {:durable_delete, boolean()} | {:respond_per_op, boolean()} | {:send_key, boolean()} | {:filter, Aerospike.Exp.t() | nil} | {:read_mode_ap, read_mode_ap()} | {:read_mode_sc, read_mode_sc()} | {:read_touch_ttl_percent, -1 | 0..100}
Batch write option accepted by per-entry batch writes.
These options are encoded with one batch write/delete/UDF entry. Parent
dispatch options are only accepted by homogeneous batch write helpers and
batch_operate/3.
@type batch_record_write_opts() :: [batch_record_write_opt()]
Keyword options accepted by per-entry batch writes.
@type batch_write_opt() :: batch_parent_opt() | batch_record_write_opt()
Batch write option accepted by homogeneous batch-write helpers.
@type batch_write_opts() :: [batch_write_opt()]
Keyword options accepted by batch write helpers.
@type cluster() :: named_cluster() | pid()
Identifier for a running cluster facade.
Read-side helpers accept the registered cluster name or a pid
registered under that name. Arbitrary GenServer.server() forms are
not supported.
@type commit_level() :: :all | :master
Commit acknowledgement level for write commands.
:all waits for the server's configured replica commit level. :master
accepts acknowledgement from the master partition owner.
@type create_expression_index_opt() :: {:name, String.t()} | {:type, index_type()} | {:collection, index_collection()} | admin_opt()
Option accepted by create_expression_index/5.
:name and :type are required. Expression indexes use the provided
%Aerospike.Exp{} as their source and therefore do not accept :bin or
nested CDT :ctx.
@type create_expression_index_opts() :: [create_expression_index_opt()]
Keyword options accepted by create_expression_index/5.
@type create_index_opt() :: {:bin, String.t()} | {:name, String.t()} | {:type, index_type()} | {:collection, index_collection()} | {:ctx, [Aerospike.Ctx.step()]} | admin_opt()
Option accepted by create_index/4.
:bin, :name, and :type are required. :collection creates a collection
index over list values, map keys, or map values. :ctx targets a nested CDT
path built with Aerospike.Ctx.
@type create_index_opts() :: [create_index_opt()]
Keyword options accepted by create_index/4.
@type create_role_opt() :: {:whitelist, [String.t()]} | {:read_quota, non_neg_integer()} | {:write_quota, non_neg_integer()} | security_admin_opt()
Role-creation option accepted by create_role/4.
@type create_role_opts() :: [create_role_opt()]
Keyword options accepted by create_role/4.
@type generation_policy() :: :none | :expect_equal | :expect_gt
Generation check behavior for write commands.
:none disables generation checks. :expect_equal requires the server
record generation to equal :generation. :expect_gt requires it to be
greater than :generation. When :generation is positive and
:generation_policy is omitted, the driver defaults to :expect_equal.
@type index_collection() :: :list | :mapkeys | :mapvalues
Secondary-index collection type.
@type index_type() :: :numeric | :string | :geo2dsphere
Secondary-index particle/source type.
@type metrics_opt() :: {:reset, boolean()}
Option accepted by enable_metrics/2.
@type metrics_opts() :: [metrics_opt()]
Keyword options accepted by enable_metrics/2.
@type named_cluster() :: atom()
Registered atom name for a running cluster.
Lifecycle and transaction helpers resolve supervisor and ETS resources from
this name, so they do not currently accept arbitrary GenServer.server()
identities.
@type node_info() :: %{name: String.t(), host: String.t(), port: :inet.port_number()}
One active cluster node as returned by nodes/1.
@type node_opt() :: {:node, String.t()}
Node-targeting option accepted by scan/query helpers that support single-node execution.
@type operate_operation() :: {:write, String.t() | atom(), term()} | {:read, String.t() | atom()} | {:add, String.t() | atom(), integer() | float()} | {:append, String.t() | atom(), String.t()} | {:prepend, String.t() | atom(), String.t()} | :touch | :delete | Aerospike.Op.t()
Operation input accepted by operate/4.
@type privilege() :: Aerospike.Privilege.t()
Security privilege metadata used by role administration APIs.
@type read_mode_ap() :: :one | :all
AP namespace read consistency.
:one reads from one available replica. :all asks the server to consult
all relevant replicas for the read.
@type read_mode_sc() :: :session | :linearize | :allow_replica | :allow_unavailable
Strong-consistency namespace read consistency.
The default is :session. :linearize requests linearized reads.
:allow_replica and :allow_unavailable relax consistency for availability
when the server namespace configuration allows it.
@type read_opt() :: {:timeout, timeout_ms()} | {:socket_timeout, timeout_ms()} | retry_opt() | {:read_mode_ap, read_mode_ap()} | {:read_mode_sc, read_mode_sc()} | {:read_touch_ttl_percent, -1 | 0..100} | {:send_key, boolean()} | {:use_compression, boolean() | nil} | {:filter, Aerospike.Exp.t() | nil}
Read option accepted by get/4, get_header/3, and exists/3.
Read helpers accept timeout/retry opts, consistency opts, :send_key,
:use_compression, and a server-side expression :filter.
@type read_opts() :: [read_opt()]
Keyword options accepted by read helpers.
@type record_exists_action() ::
:update | :update_only | :create_or_replace | :replace_only | :create_only
Record existence behavior for write commands.
:update- create or update bins (default):update_only- update an existing record only:create_or_replace- create a new record or replace the existing record:replace_only- replace an existing record only:create_only- create only when the key is absent
@type retry_opt() :: {:max_retries, non_neg_integer()} | {:sleep_between_retries_ms, non_neg_integer()} | {:replica_policy, Aerospike.RetryPolicy.replica_policy()}
Retry option accepted by single-record, scan, and query command families.
:max_retries- retries after the first attempt:sleep_between_retries_ms- fixed delay between retry attempts:replica_policy- read retry routing policy,:masteror:sequence
Retry defaults are configured at cluster start and can be overridden per command where this type appears.
@type role_info() :: Aerospike.Role.t()
Security role metadata returned by query_role/3 and query_roles/2.
@type scan_query_opt() :: scan_query_runtime_opt() | node_opt()
Runtime option accepted by scan/query helpers that may target one node.
:node must be an active node name returned by node_names/1 or nodes/1.
Final aggregate reduction does not accept :node because it must consume all
server partials required to produce one local result.
@type scan_query_opts() :: [scan_query_opt()]
Keyword options accepted by scan and query helpers.
@type scan_query_runtime_opt() :: {:timeout, timeout_ms()} | {:socket_timeout, timeout_ms()} | retry_opt() | {:task_timeout, timeout_ms() | :infinity} | {:pool_checkout_timeout, timeout_ms()} | {:max_concurrent_nodes, non_neg_integer()} | {:records_per_second, non_neg_integer()} | {:include_bin_data, boolean()} | {:expected_duration, :long | :short | :long_relax_ap} | {:task_id, pos_integer()} | {:cursor, Aerospike.Cursor.t()}
Runtime option accepted by all scan and query helpers.
These options tune client runtime behavior and server scan/query fields: command deadlines, retries, task timeout, pool checkout timeout, fan-out concurrency, throttling, bin-data inclusion, expected duration, task id, and cursor resume state.
@type security_admin_opt() :: {:timeout, timeout_ms()} | {:pool_checkout_timeout, timeout_ms()}
Option accepted by security-admin helpers.
:timeout bounds the admin protocol operation. :pool_checkout_timeout
bounds checkout from the selected node pool before the command is sent.
@type security_admin_opts() :: [security_admin_opt()]
Keyword options accepted by security-admin helpers.
@type timeout_ms() :: non_neg_integer()
Non-negative timeout value in milliseconds.
:timeout is the total client-side budget for a command. :socket_timeout
is the per-attempt idle socket deadline; 0 asks the command path to use the
remaining total budget.
@type transaction_opts() :: [{:timeout, timeout_ms()}]
Transaction options accepted by transaction/3 when a handle is not supplied.
@type truncate_opt() :: {:before, DateTime.t()} | admin_opt()
Option accepted by truncate/3 and truncate/4.
:before limits truncation to records last updated before the given
timestamp. :pool_checkout_timeout bounds checkout for the admin request.
@type truncate_opts() :: [truncate_opt()]
Keyword options accepted by truncate helpers.
@type ttl() :: non_neg_integer() | :default | :never_expire | :dont_update
Record TTL accepted by write commands.
- non-negative integer - explicit TTL in seconds
:default- use the namespace default TTL:never_expire- ask the server to keep the record indefinitely:dont_update- preserve the existing record TTL
@type user_info() :: Aerospike.User.t()
Security user metadata returned by query_user/3 and query_users/2.
@type warm_up_opt() :: {:count, non_neg_integer()} | {:pool_checkout_timeout, timeout_ms()}
Option accepted by warm_up/2.
:count is the number of worker checkout probes per active node. 0 means
up to the configured pool size. :pool_checkout_timeout bounds each probe.
@type warm_up_opts() :: [warm_up_opt()]
Keyword options accepted by warm_up/2.
@type write_opt() :: {:timeout, timeout_ms()} | {:socket_timeout, timeout_ms()} | retry_opt() | {:ttl, ttl()} | {:generation, non_neg_integer()} | {:generation_policy, generation_policy()} | {:exists, record_exists_action()} | {:commit_level, commit_level()} | {:durable_delete, boolean()} | {:respond_per_op, boolean()} | {:send_key, boolean()} | {:read_mode_ap, read_mode_ap()} | {:read_mode_sc, read_mode_sc()} | {:read_touch_ttl_percent, -1 | 0..100} | {:use_compression, boolean() | nil} | {:filter, Aerospike.Exp.t() | nil} | {:txn, Aerospike.Txn.t()}
Write option accepted by single-record write, delete, UDF, and operate helpers.
Write helpers accept timeout/retry opts, record TTL and generation policy,
existence policy, commit level, durable delete, :respond_per_op, :send_key,
read-touch metadata opts used by mixed operations, per-command compression,
a server-side expression :filter, and an optional transaction handle.
@type write_opts() :: [write_opt()]
Keyword options accepted by single-record write, delete, UDF, and operate helpers.
Functions
@spec abort(named_cluster(), Aerospike.Txn.t()) :: {:ok, :aborted | :already_aborted} | {:error, Aerospike.Error.t()}
Aborts a transaction on the named cluster cluster.
Like commit/2, this requires a handle with initialized runtime tracking on
cluster. It is for an already-open transaction; it does not create one,
and it currently requires the registered cluster atom.
@spec add( cluster(), Aerospike.Key.key_input(), Aerospike.Record.bins_input(), write_opts() ) :: {:ok, Aerospike.Record.metadata()} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready | :no_master | :unknown_node}
Atomically adds numeric deltas in bins for key.
This is a thin unary write helper over the same routed write path as put/4.
The return shape stays aligned with the write family and does not expose
operate/4 record results.
Supported write opts include:
:timeout:socket_timeout:max_retries:sleep_between_retries_ms:ttl:generation:generation_policy—:none,:expect_equal, or:expect_gt:exists— one of:update,:update_only,:create_or_replace,:replace_only, or:create_only:commit_level—:allor:master:durable_delete— whentrue, write/delete commands that remove a record ask the server to leave a tombstone:respond_per_op:send_key:read_mode_ap:read_mode_sc:read_touch_ttl_percent:use_compression:filter— non-empty%Aerospike.Exp{}server-side filter expression, ornilfor no filter
Accepts %Aerospike.Key{} or {namespace, set, user_key}.
@spec all(cluster(), Aerospike.Scan.t(), scan_query_opts()) :: {:ok, [Aerospike.Record.t()]} | {:error, Aerospike.Error.t()}
Deprecated alias for scan_all/3.
@spec all!(cluster(), Aerospike.Scan.t(), scan_query_opts()) :: [Aerospike.Record.t()]
Deprecated alias for scan_all!/3.
@spec append( cluster(), Aerospike.Key.key_input(), Aerospike.Record.bins_input(), write_opts() ) :: {:ok, Aerospike.Record.metadata()} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready | :no_master | :unknown_node}
Atomically appends string suffixes in bins for key.
This stays on the unary write path and returns write metadata, not an
operate/4 record payload.
Supported write opts include:
:timeout:socket_timeout:max_retries:sleep_between_retries_ms:ttl:generation:generation_policy—:none,:expect_equal, or:expect_gt:exists— one of:update,:update_only,:create_or_replace,:replace_only, or:create_only:commit_level—:allor:master:durable_delete— whentrue, write/delete commands that remove a record ask the server to leave a tombstone:respond_per_op:send_key:read_mode_ap:read_mode_sc:read_touch_ttl_percent:use_compression:filter— non-empty%Aerospike.Exp{}server-side filter expression, ornilfor no filter
Accepts %Aerospike.Key{} or {namespace, set, user_key}.
@spec apply_udf( cluster(), Aerospike.Key.key_input(), String.t(), String.t(), list(), write_opts() ) :: {:ok, term()} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready | :no_master | :unknown_node}
Executes one record UDF against key.
This is a single-record command, not a background query job. It accepts the same write opts as the unary write family:
:timeout:socket_timeout:max_retries:sleep_between_retries_ms:ttl:generation:generation_policy:exists:commit_level:durable_delete:respond_per_op:send_key:read_mode_ap:read_mode_sc:read_touch_ttl_percent:use_compression:filter:txn
Accepts %Aerospike.Key{} or {namespace, set, user_key}.
Transport failures are not retried automatically once the request is on the
wire, because record UDFs may already have produced server-side effects.
Package lifecycle lives on register_udf/*, remove_udf/*, and list_udfs/2.
@spec batch_delete(cluster(), [Aerospike.Key.key_input()], batch_write_opts()) :: {:ok, [Aerospike.BatchResult.t()]} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready}
Deletes multiple keys from cluster.
The result list stays in the same order as keys. Each list item is a
%Aerospike.BatchResult{} with status: :ok for a deleted record or
status: :error for a per-key failure such as a missing key, routing
failure, or node transport error. Missing keys remain explicit error
results with the server result code; this helper does not collapse them to
booleans.
This helper accepts parent batch opts and encodable write fields such as
:generation_policy, :generation, :commit_level, :durable_delete,
:send_key, and :filter.
Accepts %Aerospike.Key{} values or {namespace, set, user_key} tuples.
@spec batch_exists(cluster(), [Aerospike.Key.key_input()], batch_read_opts()) :: {:ok, ok: boolean(), error: Aerospike.Error.t(), error: :no_master | :unknown_node} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready}
Checks existence for multiple keys from cluster.
The result list stays in the same order as keys. Each list item is
either {:ok, true} / {:ok, false} for the targeted key or an
indexed error for that key ({:error, %Aerospike.Error{}},
{:error, :no_master}, or {:error, :unknown_node}).
This helper accepts the same batch read opts as batch_get/4.
Accepts %Aerospike.Key{} values or {namespace, set, user_key} tuples.
@spec batch_get( cluster(), [Aerospike.Key.key_input()], :all | [String.t() | atom()], batch_read_opts() ) :: {:ok, ok: Aerospike.Record.t(), error: Aerospike.Error.t(), error: :no_master | :unknown_node} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready}
Reads multiple keys from cluster in one batch request per target node.
The result list stays in the same order as keys. Each list item is
either {:ok, %Aerospike.Record{}} for a hit or an indexed error for
that key ({:error, %Aerospike.Error{}}, {:error, :no_master}, or
{:error, :unknown_node}).
Pass :all to read every bin, or pass a non-empty list of string or atom bin
names to project only those bins. Batch opts include parent dispatch fields
such as :timeout, :socket_timeout, :max_concurrent_nodes,
:allow_partial_results, :respond_all_keys, :allow_inline, and
:allow_inline_ssd, plus encodable read fields such as :filter,
:read_mode_ap, :read_mode_sc, and :read_touch_ttl_percent.
Accepts %Aerospike.Key{} values or {namespace, set, user_key} tuples.
@spec batch_get_header(cluster(), [Aerospike.Key.key_input()], batch_read_opts()) :: {:ok, ok: Aerospike.Record.t(), error: Aerospike.Error.t(), error: :no_master | :unknown_node} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready}
Reads record headers for multiple keys from cluster.
The result list stays in the same order as keys. Each list item is
either {:ok, %Aerospike.Record{bins: %{}}} for a hit or an indexed
error for that key ({:error, %Aerospike.Error{}},
{:error, :no_master}, or {:error, :unknown_node}).
This helper accepts the same batch read opts as batch_get/4.
Accepts %Aerospike.Key{} values or {namespace, set, user_key} tuples.
@spec batch_get_operate( cluster(), [Aerospike.Key.key_input()], [Aerospike.Op.t()], batch_read_opts() ) :: {:ok, ok: Aerospike.Record.t(), error: Aerospike.Error.t(), error: :no_master | :unknown_node} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready}
Runs one read-only operation list for multiple keys from cluster.
The result list stays in the same order as keys. Each list item is
either {:ok, %Aerospike.Record{}} for a hit or an indexed error for
that key ({:error, %Aerospike.Error{}}, {:error, :no_master}, or
{:error, :unknown_node}). Missing keys remain explicit per-key
errors; this helper does not collapse misses to nil.
This helper accepts the same batch read opts as batch_get/4.
Accepts %Aerospike.Key{} values or {namespace, set, user_key} tuples.
@spec batch_operate(cluster(), [Aerospike.Batch.t()], batch_parent_opts()) :: {:ok, [Aerospike.BatchResult.t()]} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready}
Executes heterogeneous batch entries built with Aerospike.Batch.
The result list stays in the same order as the input entries. Each list item
is a %Aerospike.BatchResult{} with status: :ok for a successful row or
status: :error for a per-key failure such as a missing key, routing
failure, server error, or node transport error.
Parent batch policy opts are accepted in opts. Per-entry read/write policy
opts can be attached with the Aerospike.Batch builders.
@spec batch_udf( cluster(), [Aerospike.Key.key_input()], String.t(), String.t(), list(), batch_write_opts() ) :: {:ok, [Aerospike.BatchResult.t()]} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready}
Executes one record UDF for multiple keys from cluster.
The result list stays in the same order as keys. Each list item is a
%Aerospike.BatchResult{} with status: :ok for a successful UDF row or
status: :error for a per-key failure such as a missing key, missing UDF,
routing failure, or node transport error. Successful UDF rows may include a
returned %Aerospike.Record{} when the server sends return bins.
This helper accepts the same parent batch and write opts as
batch_delete/3.
Accepts %Aerospike.Key{} values or {namespace, set, user_key} tuples.
@spec change_password(cluster(), String.t(), String.t(), security_admin_opts()) :: :ok | {:error, Aerospike.Error.t()}
Changes a security user's password.
When user_name matches the credentials configured on cluster, the driver
uses the self-service password-change command and rotates the running
cluster's in-memory credentials for future reconnects. For other users it
uses the user-admin password-set command.
This requires Aerospike Enterprise with security enabled.
@spec child_spec([Aerospike.Cluster.Supervisor.option()]) :: Supervisor.child_spec()
Returns a child specification for one supervised cluster.
This delegates to the same cluster-supervisor implementation as
start_link/1, so the accepted options and validation boundary match.
@spec close(named_cluster(), timeout :: non_neg_integer()) :: :ok
Stops the supervised cluster registered under the atom cluster.
This targets the registered cluster supervisor name derived from cluster
and returns :ok when the supervisor exits or is already absent.
@spec commit(named_cluster(), Aerospike.Txn.t()) :: {:ok, :committed | :already_committed} | {:error, Aerospike.Error.t()}
Commits a transaction on the named cluster cluster.
This only works for a transaction handle whose tracking row is already
initialized on cluster. A fresh %Aerospike.Txn{} is not enough by itself.
In the current driver, public code initializes that runtime state only when
transaction/2 or transaction/3 enters its callback. Transaction
tracking is keyed off the started cluster name, so this helper currently
requires that registered atom.
@spec count(cluster(), Aerospike.Scan.t(), scan_query_opts()) :: {:ok, non_neg_integer()} | {:error, Aerospike.Error.t()}
Deprecated alias for scan_count/3.
@spec count!(cluster(), Aerospike.Scan.t(), scan_query_opts()) :: non_neg_integer()
Deprecated alias for scan_count!/3.
@spec create_expression_index( cluster(), String.t(), String.t(), Aerospike.Exp.t(), create_expression_index_opts() ) :: {:ok, Aerospike.IndexTask.t()} | {:error, Aerospike.Error.t()}
Creates an expression-backed secondary index and returns a pollable task handle.
Required options:
:name— non-empty index name.:type— one of:numeric,:string, or:geo2dsphere.
Optional options:
:collection— one of:list,:mapkeys, or:mapvalues.:pool_checkout_timeout— non-negative pool checkout timeout in milliseconds.
The source must be a %Aerospike.Exp{} with non-empty wire bytes. Expression
indexes use the expression as the source and therefore do not accept :bin.
Servers older than Aerospike 8.1 reject expression-backed index creation
before the create command is sent.
{:ok, task} =
Aerospike.create_expression_index(cluster, "test", "users", Exp.int_bin("age"),
name: "users_age_expr_idx",
type: :numeric
)
:ok = Aerospike.IndexTask.wait(task)@spec create_index(cluster(), String.t(), String.t(), create_index_opts()) :: {:ok, Aerospike.IndexTask.t()} | {:error, Aerospike.Error.t()}
Creates a secondary index and returns a pollable task handle.
Required options:
:bin— non-empty bin name.:name— non-empty index name.:type— one of:numeric,:string, or:geo2dsphere.
Optional options:
:collection— one of:list,:mapkeys, or:mapvalues.:ctx— non-empty nested CDT path built withAerospike.Ctx.:pool_checkout_timeout— non-negative pool checkout timeout in milliseconds.
Geo indexes use type: :geo2dsphere and can be queried with
Aerospike.Filter.geo_within/2 or Aerospike.Filter.geo_contains/2.
{:ok, task} =
Aerospike.create_index(cluster, "test", "places",
bin: "loc",
name: "places_loc_geo_idx",
type: :geo2dsphere
)
:ok = Aerospike.IndexTask.wait(task)@spec create_pki_user(cluster(), String.t(), [String.t()], security_admin_opts()) :: :ok | {:error, Aerospike.Error.t()}
Creates a PKI-authenticated security user.
The user is created with a no-password credential and is intended for TLS
certificate authentication. This requires Aerospike Enterprise with security
enabled, server support for PKI users, and a cluster connection
authenticated as a user that holds the user-admin privilege.
Supported opts are:
:timeout:pool_checkout_timeout
@spec create_role(cluster(), String.t(), [privilege()], create_role_opts()) :: :ok | {:error, Aerospike.Error.t()}
Creates a security role.
This requires Aerospike Enterprise with security enabled.
Supported opts are:
:whitelist— list of client address strings:read_quota— non-negative integer operations-per-second limit:write_quota— non-negative integer operations-per-second limit:timeout:pool_checkout_timeout
@spec create_user( cluster(), String.t(), String.t(), [String.t()], security_admin_opts() ) :: :ok | {:error, Aerospike.Error.t()}
Creates a password-authenticated security user.
This requires Aerospike Enterprise with security enabled and a cluster
connection authenticated as a user that holds the user-admin privilege.
Supported opts are:
:timeout:pool_checkout_timeout
@spec delete(cluster(), Aerospike.Key.key_input(), write_opts()) :: {:ok, boolean()} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready | :no_master | :unknown_node}
Deletes key from cluster.
Returns {:ok, true} when a record was deleted and {:ok, false}
when the key was already absent. Supported write opts are :timeout,
:socket_timeout, :max_retries, :sleep_between_retries_ms, :ttl,
:generation, :generation_policy, :exists, :commit_level,
:durable_delete, :respond_per_op, :send_key, :read_mode_ap,
:read_mode_sc, :read_touch_ttl_percent, :use_compression, and
:filter.
Accepts %Aerospike.Key{} or {namespace, set, user_key}.
@spec disable_metrics(cluster()) :: :ok | {:error, Aerospike.Error.t()}
Disables internal runtime metrics for cluster.
Counter rows remain in place so stats/1 still reports the last collected
values until metrics are re-enabled or reset.
@spec drop_index(cluster(), String.t(), String.t(), admin_opts()) :: :ok | {:error, Aerospike.Error.t()}
Drops a secondary index.
@spec drop_role(cluster(), String.t(), security_admin_opts()) :: :ok | {:error, Aerospike.Error.t()}
Drops a security role.
This requires Aerospike Enterprise with security enabled.
@spec drop_user(cluster(), String.t(), security_admin_opts()) :: :ok | {:error, Aerospike.Error.t()}
Drops a security user.
This requires Aerospike Enterprise with security enabled.
@spec enable_metrics(cluster(), metrics_opts()) :: :ok | {:error, Aerospike.Error.t()}
Enables internal runtime metrics for cluster.
Supported options:
:reset— boolean. Whentrue, clears the existing runtime counters before enabling collection.
@spec exists(cluster(), Aerospike.Key.key_input(), read_opts()) :: {:ok, boolean()} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready | :no_master | :unknown_node}
Returns whether key exists in cluster without reading bins.
Supported read opts are :timeout, :socket_timeout, :max_retries,
:sleep_between_retries_ms, :replica_policy, :read_mode_ap,
:read_mode_sc, :read_touch_ttl_percent, :send_key,
:use_compression, and :filter.
Accepts %Aerospike.Key{} or {namespace, set, user_key}.
@spec get( cluster(), Aerospike.Key.key_input(), :all | [String.t() | atom()], read_opts() ) :: {:ok, Aerospike.Record.t()} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready | :no_master | :unknown_node}
Reads key from cluster.
Pass :all to read every bin, or pass a non-empty list of string or atom bin
names to project only those bins.
Options:
:timeout— total op-budget milliseconds for the call, shared across the initial send and every retry. Default5_000.:socket_timeout— per-attempt socket idle deadline in milliseconds, capped by the remaining total budget.0uses the remaining total budget.:max_retries— overrides the cluster-default retry cap for this call.0disables retry entirely. SeeAerospike.RetryPolicy.:sleep_between_retries_ms— fixed delay between retry attempts.:replica_policy—:master(all attempts against the master) or:sequence(walk the replica list by attempt index).:read_mode_ap—:oneor:all.:read_mode_sc—:session,:linearize,:allow_replica, or:allow_unavailable.:read_touch_ttl_percent—-1,0, or an integer from1through100.:send_key— include the user key in the request whentrue.:use_compression— per-command compression override;nilkeeps the cluster/node default.:filter— non-empty%Aerospike.Exp{}server-side filter expression, ornilfor no filter.
Returns {:ok, %Aerospike.Record{}} on hit,
{:error, %Aerospike.Error{code: :key_not_found}} on miss, or a
routing atom (:cluster_not_ready, :no_master, :unknown_node)
when the cluster view cannot serve the request.
Accepts %Aerospike.Key{} or {namespace, set, user_key}.
@spec get_header(cluster(), Aerospike.Key.key_input(), read_opts()) :: {:ok, Aerospike.Record.t()} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready | :no_master | :unknown_node}
Reads only record metadata for key from cluster.
This is the explicit single-record header helper. It reuses the same unary
read path as get/3, but requests only generation/TTL metadata and returns
a %Aerospike.Record{} with bins: %{} on hit.
Options:
:timeout— total op-budget milliseconds for the call, shared across the initial send and every retry. Default5_000.:socket_timeout— per-attempt socket idle deadline in milliseconds, capped by the remaining total budget.0uses the remaining total budget.:max_retries— overrides the cluster-default retry cap for this call.0disables retry entirely. SeeAerospike.RetryPolicy.:sleep_between_retries_ms— fixed delay between retry attempts.:replica_policy—:master(all attempts against the master) or:sequence(walk the replica list by attempt index).:read_mode_ap—:oneor:all.:read_mode_sc—:session,:linearize,:allow_replica, or:allow_unavailable.:read_touch_ttl_percent—-1,0, or an integer from1through100.:send_key— include the user key in the request whentrue.:use_compression— per-command compression override;nilkeeps the cluster/node default.:filter— non-empty%Aerospike.Exp{}server-side filter expression, ornilfor no filter.
Returns {:ok, %Aerospike.Record{bins: %{}}} on hit,
{:error, %Aerospike.Error{code: :key_not_found}} on miss, or a
routing atom (:cluster_not_ready, :no_master, :unknown_node)
when the cluster view cannot serve the request.
Accepts %Aerospike.Key{} or {namespace, set, user_key}.
@spec grant_privileges(cluster(), String.t(), [privilege()], security_admin_opts()) :: :ok | {:error, Aerospike.Error.t()}
Grants privileges to a security role.
This requires Aerospike Enterprise with security enabled.
@spec grant_roles(cluster(), String.t(), [String.t()], security_admin_opts()) :: :ok | {:error, Aerospike.Error.t()}
Grants roles to a security user.
This requires Aerospike Enterprise with security enabled.
@spec info(cluster(), String.t(), admin_opts()) :: {:ok, String.t()} | {:error, Aerospike.Error.t()}
Sends one info command to one active cluster node and returns that node's reply.
@spec info_node(cluster(), String.t(), String.t(), admin_opts()) :: {:ok, String.t()} | {:error, Aerospike.Error.t()}
Sends one info command to the named active cluster node and returns that node's reply.
node_name must be one of the names returned by node_names/1 or
nodes/1. Stale or unknown names return an
%Aerospike.Error{code: :invalid_node} instead of falling back to a
different node.
{:ok, [node_name | _]} = Aerospike.node_names(:aerospike)
{:ok, response} = Aerospike.info_node(:aerospike, node_name, "statistics")Supported options:
:pool_checkout_timeout— non-negative pool checkout timeout in milliseconds.
@spec key(String.t(), String.t(), String.t() | integer()) :: Aerospike.Key.t()
Builds a key from namespace, set, and a user key.
This is a thin wrapper over Aerospike.Key.new/3.
@spec key_digest(String.t(), String.t(), <<_::160>>) :: Aerospike.Key.t()
Builds a key from namespace, set, and an existing 20-byte digest.
This is a thin wrapper over Aerospike.Key.from_digest/3.
@spec list_udfs(cluster(), admin_opts()) :: {:ok, [Aerospike.UDF.t()]} | {:error, Aerospike.Error.t()}
Lists the registered server-side UDF packages visible from one active node.
This is package lifecycle state, not record execution. Use apply_udf/6
to invoke one function against one key.
Returns whether internal runtime metrics are enabled for cluster.
Metrics are opt-in. The collector is initialized at cluster start so the
config rows exist early, but command, pool, and tender counters remain idle
until enable_metrics/2 is called.
Returns the published active cluster node-name snapshot.
Returns the published active cluster nodes with their direct-connect host and port.
@spec operate( cluster(), Aerospike.Key.key_input(), [operate_operation()], write_opts() ) :: {:ok, Aerospike.Record.t()} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready | :no_master | :unknown_node}
Runs a constrained unary operate list for key.
Supported operations:
{:write, bin, value}— simple bin write{:read, bin}— simple bin read{:add, bin, delta}— numeric increment{:append, bin, suffix}— string suffix mutation{:prepend, bin, prefix}— string prefix mutation:touch— refresh record metadata:delete— remove the record
The command routes per input batch: read-only lists use read routing; any list that includes a write uses write routing.
Supported opts are :timeout, :socket_timeout, :max_retries,
:sleep_between_retries_ms, :ttl, :generation, :generation_policy,
:exists, :commit_level, :durable_delete, :respond_per_op,
:send_key, :read_mode_ap, :read_mode_sc,
:read_touch_ttl_percent, :use_compression, and :filter.
Accepted operations include the simple tuple form plus the public
Aerospike.Op helpers for primitive, CDT, bit, HyperLogLog, and expression
operations. Returned operation values are accumulated into
%Aerospike.Record{bins: map} by bin name.
Aerospike.operate(cluster, key, [
Aerospike.Op.Exp.read("projected", Aerospike.Exp.int_bin("count")),
Aerospike.Op.Exp.write("computed", Aerospike.Exp.int(99))
])
Aerospike.operate(cluster, key, [
Aerospike.Op.List.append("profile", "signed-in",
ctx: [Aerospike.Ctx.map_key("events")]
)
])
Aerospike.operate(cluster, key, [
Aerospike.Op.Bit.count("flags", 0, 8),
Aerospike.Op.HLL.get_count("visitors")
])Accepts %Aerospike.Key{} or {namespace, set, user_key}.
@spec prepend( cluster(), Aerospike.Key.key_input(), Aerospike.Record.bins_input(), write_opts() ) :: {:ok, Aerospike.Record.metadata()} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready | :no_master | :unknown_node}
Atomically prepends string prefixes in bins for key.
This stays on the unary write path and returns write metadata, not an
operate/4 record payload.
Supported write opts include:
:timeout:socket_timeout:max_retries:sleep_between_retries_ms:ttl:generation:generation_policy—:none,:expect_equal, or:expect_gt:exists— one of:update,:update_only,:create_or_replace,:replace_only, or:create_only:commit_level—:allor:master:durable_delete— whentrue, write/delete commands that remove a record ask the server to leave a tombstone:respond_per_op:send_key:read_mode_ap:read_mode_sc:read_touch_ttl_percent:use_compression:filter— non-empty%Aerospike.Exp{}server-side filter expression, ornilfor no filter
Accepts %Aerospike.Key{} or {namespace, set, user_key}.
@spec put( cluster(), Aerospike.Key.key_input(), Aerospike.Record.bins_input(), write_opts() ) :: {:ok, Aerospike.Record.metadata()} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready | :no_master | :unknown_node}
Writes bins for key to cluster.
The driver accepts only a non-empty bin map and only scalar, list, map, bytes, geo, and HyperLogLog values supported by the command encoder. Supported write opts include:
:timeout:socket_timeout:max_retries:sleep_between_retries_ms:ttl:generation:generation_policy—:none,:expect_equal, or:expect_gt:exists— one of:update,:update_only,:create_or_replace,:replace_only, or:create_only:commit_level—:allor:master:durable_delete— whentrue, write/delete commands that remove a record ask the server to leave a tombstone:respond_per_op:send_key:read_mode_ap:read_mode_sc:read_touch_ttl_percent:use_compression:filter— non-empty%Aerospike.Exp{}server-side filter expression, ornilfor no filter
Accepts %Aerospike.Key{} or {namespace, set, user_key}.
@spec put_payload(cluster(), Aerospike.Key.key_input(), binary(), write_opts()) :: :ok | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready | :no_master | :unknown_node}
Sends a caller-built single-record write/delete frame for key.
This helper is intended for tooling, proxy, and replay scenarios.
payload must be a complete Aerospike wire frame for one write-shaped
command. The client uses key only to choose the write partition owner,
forwards payload unchanged, and parses only the standard write response.
The payload must already contain every server-visible write attribute, such
as generation, TTL, send-key, delete flags, filters, and any transaction
fields. Passing :txn validates the transaction option shape but does not
register the key with the transaction monitor or add transaction fields.
Supported write opts are validated for routing and I/O budgets:
:timeout:socket_timeout:max_retries:sleep_between_retries_ms:ttl:generation:generation_policy:exists:commit_level:durable_delete:respond_per_op:send_key:use_compression:filter:txn
Accepts %Aerospike.Key{} or {namespace, set, user_key}.
@spec put_payload!(cluster(), Aerospike.Key.key_input(), binary(), write_opts()) :: :ok
Same as put_payload/4 but returns :ok or raises Aerospike.Error.
@spec query_aggregate( cluster(), Aerospike.Query.t(), String.t(), String.t(), list(), scan_query_opts() ) :: {:ok, Enumerable.t()} | {:error, Aerospike.Error.t()}
Streams aggregate query values over the same node-buffered query
runtime used by query_stream/3.
The returned stream yields the aggregate values emitted by the server. It
does not run local Lua finalization. Use query_aggregate_result/6 when
the caller wants one locally finalized aggregate result.
@spec query_aggregate_result( cluster(), Aerospike.Query.t(), String.t(), String.t(), list(), aggregate_result_opts() ) :: {:ok, term() | nil} | {:error, Aerospike.Error.t()}
Returns one finalized aggregate query result.
This runs the same server aggregate query as query_aggregate/6, then
locally executes the package's Lua stream finalization over the
server-emitted aggregate values. Use query_aggregate/6 when callers need
the partial server values themselves.
The local Lua package source must be supplied with exactly one of:
:source- inline Lua source as a binary:source_path- readable local Lua source path
Source loading is local-only and separate from server UDF registration. The
client does not derive a local path from package and does not fetch source
from the server. Source option errors, unsupported local argument values, and
node: node_name fail with {:error, %Aerospike.Error{code: :invalid_argument}} before opening the server query stream.
The local reducer runs in a fresh bounded Lua state. The existing :timeout
option bounds local execution when it is a positive integer; otherwise a
finite default is used. Supported local stream helpers are map, filter,
aggregate, and reduce. Logging helpers are no-ops. Filesystem, OS,
package loading, dynamic loading, debug access, require, groupby, list,
bytes, and record/database mutation or lookup helpers fail explicitly with
%Aerospike.Error{code: :query_generic}.
Values crossing the local Lua boundary are limited to nil, booleans,
integers, floats, binaries, lists, and maps with scalar keys. Blob, geo, raw,
HLL, and other unsupported values fail instead of being coerced.
Example:
query =
Aerospike.Query.new("test", "users")
|> Aerospike.Query.where(Aerospike.Filter.range("age", 18, 65))
Aerospike.query_aggregate_result(
:aerospike,
query,
"user_stats",
"sum_age",
["age"],
source_path: "priv/udf/user_stats.lua",
timeout: 10_000
)Returns {:ok, nil} when local finalization produces no value. Returns an
error when finalization produces multiple values or local Lua execution fails.
@spec query_aggregate_result!( cluster(), Aerospike.Query.t(), String.t(), String.t(), list(), aggregate_result_opts() ) :: term() | nil
Same as query_aggregate_result/6 but returns the value or raises
Aerospike.Error.
@spec query_all(cluster(), Aerospike.Query.t(), scan_query_opts()) :: {:ok, [Aerospike.Record.t()]} | {:error, Aerospike.Error.t()}
Eagerly collects query records into a list.
query.max_records must be set because this helper advances through
the query in repeated page-sized steps until the cursor is exhausted.
Pass node: node_name in opts to query one active node, using a name
returned by node_names/1 or nodes/1.
@spec query_all!(cluster(), Aerospike.Query.t(), scan_query_opts()) :: [ Aerospike.Record.t() ]
Same as query_all/3 but returns the list or raises Aerospike.Error.
@spec query_count(cluster(), Aerospike.Query.t(), scan_query_opts()) :: {:ok, non_neg_integer()} | {:error, Aerospike.Error.t()}
Counts query matches without materializing the records.
This still walks the query stream and counts client-side. It is not a
separate server-side count primitive. Pass node: node_name in opts to
count records from one active node, using a name returned by node_names/1
or nodes/1.
@spec query_count!(cluster(), Aerospike.Query.t(), scan_query_opts()) :: non_neg_integer()
Same as query_count/3 but returns the count or raises Aerospike.Error.
@spec query_execute(cluster(), Aerospike.Query.t(), list(), scan_query_opts()) :: {:ok, Aerospike.ExecuteTask.t()} | {:error, Aerospike.Error.t()}
Starts a background query write job that applies the given operations.
This returns a pollable task handle, not a resumable record stream.
Pass node: node_name in opts to start the job on one active node,
using a name returned by node_names/1 or nodes/1.
@spec query_page(cluster(), Aerospike.Query.t(), scan_query_opts()) :: {:ok, Aerospike.Page.t()} | {:error, Aerospike.Error.t()}
Returns one collected query page and a resumable cursor when more records remain.
query.max_records is required because it seeds the partition-tracker
budget for the page walk. On multi-node queries that budget is
distributed across active nodes, so a page is resumable but not
guaranteed to contain exactly query.max_records records. The cursor
resumes partition progress from the prior page; it is not a stable
snapshot token. Pass node: node_name in opts to collect a page from one
active node, using a name returned by node_names/1 or nodes/1.
@spec query_page!(cluster(), Aerospike.Query.t(), scan_query_opts()) :: Aerospike.Page.t()
Same as query_page/3 but returns the page or raises Aerospike.Error.
@spec query_role(cluster(), String.t(), security_admin_opts()) :: {:ok, role_info() | nil} | {:error, Aerospike.Error.t()}
Queries one security role.
Returns {:ok, nil} when the named role does not exist.
This requires Aerospike Enterprise with security enabled.
@spec query_roles(cluster(), security_admin_opts()) :: {:ok, [role_info()]} | {:error, Aerospike.Error.t()}
Queries all security roles visible to the authenticated cluster user.
This requires Aerospike Enterprise with security enabled.
@spec query_stream(cluster(), Aerospike.Query.t(), scan_query_opts()) :: {:ok, Enumerable.t()} | {:error, Aerospike.Error.t()}
Returns a lazy Stream of records from a secondary-index query.
Like scan_stream/3, this is lazy only at the outer Enumerable boundary.
The current runtime buffers each node's query results before yielding
them to the caller. Pass node: node_name in opts to query one active
node, using a name returned by node_names/1 or nodes/1.
@spec query_stream!(cluster(), Aerospike.Query.t(), scan_query_opts()) :: Enumerable.t()
Same as query_stream/3 but raises on error.
@spec query_udf( cluster(), Aerospike.Query.t(), String.t(), String.t(), list(), scan_query_opts() ) :: {:ok, Aerospike.ExecuteTask.t()} | {:error, Aerospike.Error.t()}
Starts a background query UDF job.
This returns a pollable task handle, not a resumable record stream.
Pass node: node_name in opts to start the job on one active node,
using a name returned by node_names/1 or nodes/1.
@spec query_user(cluster(), String.t(), security_admin_opts()) :: {:ok, user_info() | nil} | {:error, Aerospike.Error.t()}
Queries one security user.
Returns {:ok, nil} when the named user does not exist.
This requires Aerospike Enterprise with security enabled.
@spec query_users(cluster(), security_admin_opts()) :: {:ok, [user_info()]} | {:error, Aerospike.Error.t()}
Queries all security users visible to the authenticated cluster user.
This requires Aerospike Enterprise with security enabled.
@spec register_udf(cluster(), String.t(), String.t(), admin_opts()) :: {:ok, Aerospike.RegisterTask.t()} | {:error, Aerospike.Error.t()}
Uploads a UDF package from inline source or a readable local .lua path.
Returns a pollable Aerospike.RegisterTask once the server accepts the
upload. The package may still be propagating, so call RegisterTask.wait/2
before relying on it from apply_udf/6 or background UDF jobs.
@spec remove_udf(cluster(), String.t(), admin_opts()) :: :ok | {:error, Aerospike.Error.t()}
Removes a registered UDF package by server filename.
This is idempotent: removing an already-absent package still returns :ok.
@spec revoke_privileges(cluster(), String.t(), [privilege()], security_admin_opts()) :: :ok | {:error, Aerospike.Error.t()}
Revokes privileges from a security role.
This requires Aerospike Enterprise with security enabled.
@spec revoke_roles(cluster(), String.t(), [String.t()], security_admin_opts()) :: :ok | {:error, Aerospike.Error.t()}
Revokes roles from a security user.
This requires Aerospike Enterprise with security enabled.
@spec scan_all(cluster(), Aerospike.Scan.t(), scan_query_opts()) :: {:ok, [Aerospike.Record.t()]} | {:error, Aerospike.Error.t()}
Eagerly collects scan records into a list.
Pass node: node_name in opts to scan one active node, using a name
returned by node_names/1 or nodes/1.
@spec scan_all!(cluster(), Aerospike.Scan.t(), scan_query_opts()) :: [ Aerospike.Record.t() ]
Same as scan_all/3 but returns the list or raises Aerospike.Error.
@spec scan_count(cluster(), Aerospike.Scan.t(), scan_query_opts()) :: {:ok, non_neg_integer()} | {:error, Aerospike.Error.t()}
Counts scan matches without materializing the records.
Pass node: node_name in opts to count records from one active node,
using a name returned by node_names/1 or nodes/1.
@spec scan_count!(cluster(), Aerospike.Scan.t(), scan_query_opts()) :: non_neg_integer()
Same as scan_count/3 but returns the count or raises Aerospike.Error.
@spec scan_page(cluster(), Aerospike.Scan.t(), scan_query_opts()) :: {:ok, Aerospike.Page.t()} | {:error, Aerospike.Error.t()}
Returns one collected scan page and a resumable cursor when more records remain.
scan.max_records is required because it seeds the partition-tracker
budget for the page walk. On multi-node scans that budget is distributed
across active nodes, so a page is resumable but not guaranteed to contain
exactly scan.max_records records. The cursor resumes partition progress
from the prior page; it is not a stable snapshot token. Pass
node: node_name in opts to collect a page from one active node, using
a name returned by node_names/1 or nodes/1.
@spec scan_page!(cluster(), Aerospike.Scan.t(), scan_query_opts()) :: Aerospike.Page.t()
Same as scan_page/3 but returns the page or raises Aerospike.Error.
@spec scan_stream(cluster(), Aerospike.Scan.t(), scan_query_opts()) :: {:ok, Enumerable.t()} | {:error, Aerospike.Error.t()}
Returns a lazy Stream of records from a scan.
The returned stream is lazy at the Enumerable boundary, but the current
runtime drains each node response fully before yielding that node's
records downstream. It does not promise frame-by-frame backpressure or
an explicit cancellation API. Pass node: node_name in opts to scan one
active node, using a name returned by node_names/1 or nodes/1.
@spec scan_stream!(cluster(), Aerospike.Scan.t(), scan_query_opts()) :: Enumerable.t()
Same as scan_stream/3 but raises on error.
@spec set_quotas( cluster(), String.t(), non_neg_integer(), non_neg_integer(), security_admin_opts() ) :: :ok | {:error, Aerospike.Error.t()}
Sets read and write quota limits for a security role.
Pass 0 for either quota to clear that limit. Quotas require server security
configuration with quotas enabled.
@spec set_whitelist(cluster(), String.t(), [String.t()], security_admin_opts()) :: :ok | {:error, Aerospike.Error.t()}
Sets or clears a security role's client-address whitelist.
Pass an empty list to clear the role's whitelist. This requires Aerospike Enterprise with security enabled.
@spec set_xdr_filter(cluster(), String.t(), String.t(), Aerospike.Exp.t() | nil) :: :ok | {:error, Aerospike.Error.t()}
Sets or clears the Enterprise XDR filter for one datacenter and namespace.
Pass a non-empty %Aerospike.Exp{} to set the filter, or nil to clear the
current filter. datacenter and namespace must be non-empty info-command
identifiers and cannot contain command delimiters.
Live application requires an Enterprise server with XDR configured. Community Edition or unconfigured clusters may reject the command after local validation.
filter = Exp.eq(Exp.int_bin("active"), Exp.int(1))
:ok = Aerospike.set_xdr_filter(cluster, "dc-west", "test", filter)
:ok = Aerospike.set_xdr_filter(cluster, "dc-west", "test", nil)@spec start_link([Aerospike.Cluster.Supervisor.option()]) :: Supervisor.on_start()
Starts a supervised cluster.
Internally this delegates to Aerospike.Cluster.Supervisor.start_link/1,
which boots the cluster-state owner, per-node pool supervisor, partition-map
writer, and tend-cycle process under one rest_for_one tree. The :name
option is the public cluster identity later passed to get/3,
Aerospike.Cluster.ready?/1, and the other facade/read-side helpers.
Required options: :name, :transport, :hosts, :namespaces.
Startup validation happens synchronously at this boundary. Shape
errors for required opts, retry/breaker knobs, TLS/connect opts, and
auth pairs fail start_link/1 immediately instead of surfacing later
from the first tend cycle or pool worker. The :name remains the
public cluster identity for facade calls such as get/3, info/3,
and Aerospike.Cluster.ready?/1.
Cluster lifecycle knobs:
:tend_trigger—:timer(default) or:manual.:tend_interval_ms— automatic tend period in milliseconds. Positive integer.:failure_threshold— consecutive tend failures before the tend cycle demotes a node. Non-negative integer.
Pool-level knobs (forwarded internally on each node-pool start):
:pool_size— workers per node. Positive integer.:min_connections_per_node— minimum warm connection target per node. Non-negative integer.0allows lazy worker creation.:idle_timeout_ms— milliseconds a worker may sit idle before the pool verification step evicts it. Positive integer. Defaults stay under Aerospike'sproto-fd-idle-ms.:max_idle_pings— bound on how many idle workers NimblePool may drop per verification cycle. Positive integer.
Breaker and retry knobs:
:circuit_open_threshold— consecutive node failures tolerated before new commands are refused. Non-negative integer.:max_concurrent_ops_per_node— in-flight plus queued command cap enforced per node. Positive integer.:max_retries— retries after the initial attempt. Non-negative integer.:sleep_between_retries_ms— fixed delay between retries. Non-negative integer.:replica_policy—:masteror:sequence.
Cluster feature toggles:
:use_compression— boolean cluster-wide request-compression opt-in, gated per node by advertised capabilities.:use_services_alternate— boolean toggle forpeers-clear-altdiscovery.:seed_only_cluster— boolean. When true, discovery is limited to configured seed addresses.:cluster_name— expected server cluster name. Nodes reporting a different name are rejected.:application_id— application identity sent to capable servers for server-side client correlation.
Auth opts:
:auth_mode—:internal(default),:external, or:pki. External and PKI modes requireAerospike.Transport.Tls.:user/:password— cluster-wide credentials. Must be passed together or omitted together. PKI auth uses the TLS client certificate and must omit both.:login_timeout_ms— startup/login read deadline in milliseconds.
TCP-level tuning knobs (passed verbatim to the TCP transport via the
:connect_opts keyword):
:connect_timeout_ms— handshake + write-buffer drain deadline.:info_timeout— read deadline applied to everyinfo/2call. Defaults to:connect_timeout_ms.:tcp_nodelay— boolean, defaulttrue.:tcp_keepalive— boolean, defaulttrue.:tcp_sndbuf/:tcp_rcvbuf— positive integer kernel buffer sizes. Unset lets the kernel pick.
Aerospike.Cluster.Supervisor documents the underlying validation and child
ownership details.
Returns the current internal runtime metrics snapshot for cluster.
The returned map is intentionally limited to the counters and cluster metadata the runtime collector actually records today. It is not a generalized exporter surface.
@spec stream!(cluster(), Aerospike.Scan.t(), scan_query_opts()) :: Enumerable.t()
Deprecated alias for scan_stream!/3.
@spec touch(cluster(), Aerospike.Key.key_input(), write_opts()) :: {:ok, Aerospike.Record.metadata()} | {:error, Aerospike.Error.t()} | {:error, :cluster_not_ready | :no_master | :unknown_node}
Updates key's header metadata in cluster.
Supported write opts are :timeout, :socket_timeout, :max_retries,
:sleep_between_retries_ms, :ttl, :generation, :generation_policy,
:exists, :commit_level, :durable_delete, :respond_per_op,
:send_key, :read_mode_ap, :read_mode_sc,
:read_touch_ttl_percent, :use_compression, and :filter.
Accepts %Aerospike.Key{} or {namespace, set, user_key}.
@spec transaction(named_cluster(), (Aerospike.Txn.t() -> term())) :: {:ok, term()} | {:error, Aerospike.Error.t()}
Runs a function within a new transaction on the named cluster cluster.
The callback owns the public transaction lifecycle. The driver initializes the
runtime tracking row before invoking fun, then commits on success or aborts
on any failure path. Do not call commit/2 or abort/2 from inside the
callback.
The %Aerospike.Txn{} passed to fun is safe only for sequential use within
that transaction. Do not share it across concurrent processes, and do not use
scans or queries with it; the current transaction proof covers only
transaction-aware single-record commands. This helper currently requires the
registered cluster atom.
@spec transaction( named_cluster(), Aerospike.Txn.t() | transaction_opts(), (Aerospike.Txn.t() -> term()) ) :: {:ok, term()} | {:error, Aerospike.Error.t()}
Runs a function within a transaction on the named cluster cluster using a
provided handle or options.
When txn_or_opts is a %Aerospike.Txn{}, the driver initializes fresh
runtime tracking for that handle on cluster at callback entry. Reusing the
same handle concurrently or against another cluster is unsupported. This
helper currently requires the registered cluster atom.
@spec truncate(cluster(), String.t(), truncate_opts()) :: :ok | {:error, Aerospike.Error.t()}
Truncates all records in namespace.
This sends one truncate info command through the shared admin seam. The server then distributes the truncate across the cluster.
Options:
:before—%DateTime{}— truncate only records whose last-update time is older than the provided timestamp:pool_checkout_timeout— non-negative integer checkout timeout in milliseconds for the one-node admin request
@spec truncate(cluster(), String.t(), String.t(), truncate_opts()) :: :ok | {:error, Aerospike.Error.t()}
Truncates all records in namespace and set.
Like truncate/3, this uses the shared one-node admin info seam. The optional
:before filter is forwarded to the server as a last-update cutoff.
Options:
:before—%DateTime{}— truncate only records whose last-update time is older than the provided timestamp:pool_checkout_timeout— non-negative integer checkout timeout in milliseconds for the one-node admin request
@spec txn_status(named_cluster(), Aerospike.Txn.t()) :: {:ok, :open | :verified | :committed | :aborted} | {:error, Aerospike.Error.t()}
Returns the current state of a transaction on the named cluster cluster.
This reflects only the in-flight states backed by the runtime tracking row.
After commit or abort, the driver cleans that row up, so txn_status/2
returns an error instead of a terminal :committed or :aborted state.
Like the other transaction lifecycle helpers, this currently requires the
registered cluster atom.
@spec warm_up(cluster(), warm_up_opts()) :: {:ok, map()} | {:error, Aerospike.Error.t()}
Verifies that the active node pools can serve checkouts through the normal path.
This is an explicit operator action; it does not toggle metrics and it does
not change the pool startup mode. The current driver pools are already eager at
cluster start. warm_up/2 simply proves that the active pools can hand out
the requested number of workers right now.
Supported options:
:count— non-negative integer.0(default) means "up to the configured pool size per active node".:pool_checkout_timeout— non-negative integer timeout in milliseconds for each checkout probe.