Manage sets

This page describes how to manage sets and set indexes in an Aerospike namespace.

An Aerospike set is similar to a table in a relational database, except you do not define a schema for it.

• Sets are created dynamically and implicitly by the first record inserted into the set, a behavior which can be restricted through the use of role-based access control.
• While records can be created without a set name, you can configure the namespace to disallow-null-setname.

Caution

Truncation, expiration, and eviction are discouraged for strong consistency (CP mode) namespaces.

Managing set indexes

Starting with Database 8.1.2, you can create and remove set indexes using the same commands as secondary indexes, sindex-create and sindex-delete, with the sindex-admin privilege. This allows set index management on Aerospike Cloud, where the sys-admin role is not available.

The legacy method using enable-index configuration or the set-config info command is deprecated but remains supported for backward compatibility.

Adding a set index

• Preferred method (Database 8.1.2 and later): Use sindex-create. This requires the sindex-admin privilege (same as secondary indexes) and works on Aerospike Cloud.

asadm -e "enable; asinfo -v 'sindex-create:namespace=test;set=demo;indexname=demo-idx;indextype=set'"

• Use manage sindex create for a set index:

asadm -e "enable; manage sindex create demo-idx ns test set demo"

Note

Set indexes created with sindex-create require an index name. The same command is used for secondary indexes and set indexes.

Deprecated methods:

• manage config:

asadm -e "enable; manage config namespace test set demo param enable-index to true"

• The set-config info command:

asadm -e "enable; asinfo -v 'set-config:context=namespace;id=test;set=demo;enable-index=true' "

Removing a set index

Preferred method (Database 8.1.2 and later): Use sindex-delete with the index name. Requires sindex-admin privilege.

Use manage sindex delete:

Admin+> manage sindex delete demo-idx ns test set demo

Or use the sindex-delete info command:

asadm -e "enable; asinfo -v 'sindex-delete:namespace=test;set=demo;indexname=demo-idx'"

Note

A set index can only be removed using the same method that created it. An index created with sindex-create must be deleted with sindex-delete. An index created with set-config enable-index=true must be disabled with set-config enable-index=false. Attempting to cross methods fails with a warning.

Deprecated method: Using asadm to revert the enable-index set configuration:

Admin> enable
Admin+> manage config namespace test set demo param enable-index to false

And using the raw info command:

Admin> enable
Admin+> asinfo -v 'set-config:context=namespace;id=test;set=demo;enable-index=false'

Backward compatibility

You can create set indexes using either the new sindex-create method or the deprecated enable-index / set-config method. Both methods can coexist, but each method’s indexes are managed independently:

• A set index created via sindex-create can only be deleted via sindex-delete. Setting enable-index to false via set-config has no effect on it.
• A set index created via set-config enable-index=true can only be disabled via set-config enable-index=false. sindex-delete has no effect on it.
• SMD always takes priority when it has an entry for the set; set-config is only used when SMD has no entry.
• If no SMD entry exists for the set, enable-index via set-config controls whether the set index is active.

Monitoring set indexes

The memory cost of enabling a set index is described in the capacity planning guide.

To limit the combined memory usage by all indexes (primary, set, secondary) at the namespace level, use the indexes-memory-budget configuration parameter.

Setting limits on the number of objects and storage used by a set is described in Limiting set growth.

The memory used by all set indexes in a namespace is provided by the memory_used_set_index_bytes metric and also the “memory-usage” server log ticker line.

Managing expiration and eviction

You can modify namespace data retention aspects like expiration, eviction and TTL at the set level.

Note

Configuration parameters are applied per-node. asadm sends the same info command to all the nodes in the cluster.

Defining set-level record TTL

Starting with Database 7.0.0, you can specify a default time-to-live (default-ttl) configuration option at the set level, which overrides any default-ttl option specified at the namespace level.

asadm -e "enable; manage config namespace test set demo param default-ttl 60D"

See Specify a set-level default TTL for static configuration.

Protecting a set from evictions

To protect a set from evictions you can statically or dynamically disable-eviction. When evictions are in effect for a namespace, sets with evictions disabled are skipped, regardless of the void-time of the records.

asadm -e "enable; manage config namespace test set demo param disable-eviction to true"

See Disable eviction on sets for static configuration.

Limiting set growth

To prevent a single set from exhausting storage, you can dynamically limit its growth using configuration parameters. This ensures high-density datasets do not impact the rest of your namespace.

Note

Configuration parameters are applied per-node, and thresholds are checked separately on each cluster node. Stop-writes behavior occurs independently on each node that exceeds the defined threshold. When using asadm, the same dynamic configuration is sent to all nodes in the cluster.

Limiting set storage size

To limit the total storage used by a set, use stop-writes-size. If a cluster node breaches this threshold, it refuses client writes to that set. Deletions, replica writes, and migration writes remain permitted.

Once the limit is reached, the server refuses all additional writes, including those that would decrease record size. To exit this state, you must increase or remove the limit, or delete records.

While the limit is breached, record deletions using UDFs, delete-all-bins operations, or background queries are rejected. You must use standard record deletes, batch deletes, or wait for Namespace Supervisor (NSUP) expiration.

asadm -e "enable; manage config namespace test set demo param stop-writes-size to 250M"

Or using the raw info command:

asadm -e "enable; asinfo -v 'set-config:context=namespace;id=test;set=demo;stop-writes-size=250M' "

See Define a data size maximum on a set for static configuration.

Limiting the set record count

Use stop-writes-count to limit the total number of records in a set. If a node breaches this threshold, client writes are refused, though deletions and system writes (replica/migration) are still allowed.

asadm -e "enable; manage config namespace test set demo param stop-writes-count to 1000000"

Or using the raw info command:

asadm -e "enable; asinfo -v 'set-config:context=namespace;id=test;set=demo;stop-writes-count=1000000' "

See Define a set object count for static configuration.

Viewing stop-write status

To determine if a set has reached its limit or why client writes are being refused, use the following methods:

• Use asadm (recommended) This provides a cluster-wide view of specific metrics and the percentage of the threshold used.

Admin> show stop-writes for test employees

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Stop Writes (2025-05-19 04:16:15 UTC)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                         Show all stop writes - add 'for <namespace> [<set>]' for a shorter list.
           Config|Namespace|      Set|           Node|Stop-Writes|         Metric|  Usage%|   Usage|Threshold
stop-writes-count|test     |employees|10.0.1.127:3100|False      |objects        |      --|10.000 K|       --
stop-writes-size |test     |employees|10.0.1.127:3100|True       |data_used_bytes|117.84 %|1.178 MB| 1.000 MB
Number of rows: 2

• Use asinfo (node-specific) To check the raw status on a single node, query the set statistics directly:

asinfo -v "sets/test/employees" | tr ';' '\n' | grep "stop-writes"

• Server logs The server logs a WARNING when a threshold is crossed, which is useful for post-mortem analysis.

WARNING (nsup): {test:employees} breached stop-writes-size limit

Truncating a set in a namespace

Use the asadm or asinfo tools to issue a truncate command to one Aerospike cluster node at a time.

Caution

To use the truncate command in a namespace that is also enabled with transactions, you must first verify that all transactions are paused as described in Pause and drain transactions before truncating.

Truncate with asadm

Using the asadm command-line interface:

asadm
Seed:        [('127.0.0.1', 3000, None)]
Aerospike Interactive Shell, version 2.11.0

Found 1 nodes
Online:  127.0.0.1:3000

Admin> info set
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Set Information (2023-03-26 22:59:40 UTC)~~~~~~~~~~~~~~~~~~~~~~~~~~~
Namespace| Set|           Node|  Memory|    Disk|~~~~~Quota~~~~~~| Objects|   Stop| Disable|  Set
         |    |               |    Used|    Used|     Total|Used%|        | Writes|Eviction|Index
         |    |               |        |        |          |     |        |  Count|        |
test     |demo|127.0.0.1:3000 |1.236 MB|0.000 B |250.000 MB|0.0 %|99.711 K|1000000|True    |No
test     |demo|               |1.236 MB|0.000 B |250.000 MB|0.0 %|99.711 K|       |        |
Number of rows: 1

Admin> enable
Admin+> manage truncate ns test set demo
You're about to truncate up to 0 records from set demo for namespace test
Confirm that you want to proceed by typing 6cdc8c, or cancel by typing anything else.
6cdc8c
Successfully started truncation for set demo of namespace test
Admin+> info set
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Set Information (2023-03-26 23:04:08 UTC)~~~~~~~~~~~~~~~~~~~~~~~~~~
Namespace| Set|           Node|  Memory|    Disk|~~~~~Quota~~~~~~|Objects|   Stop| Disable|  Set
         |    |               |    Used|    Used|     Total|Used%|       | Writes|Eviction|Index
         |    |               |        |        |          |     |       |  Count|        |
test     |demo|127.0.0.1:3000 |0.000 B |0.000 B |250.000 MB|0.0 %|0.000  |1000000|True    |No
test     |demo|               |0.000 B |0.000 B |250.000 MB|0.0 %|0.000  |       |        |
Number of rows: 1

In non-interactive mode

asadm --enable -e "manage truncate ns test set demo --no-warn"

Truncate with asinfo

The following command truncates a single node, and is then communicated to the other nodes as shared metadata (SMD):

asinfo -h 127.0.0.1 -v "truncate:namespace=test;set=demo"

Pause and drain transactions before truncating

Use the following steps to truncate sets in a namespace with transactions enabled.

1. Pause the transactions using one of the following commands.

   asadm -e "enable; manage config namespace <NAMESPACE_NAME> param disable-mrt-writes to true"

   or

   asadm -e "enable; asinfo -v 'set-config:context=namespace;id=<NAMESPACE_NAME>;disable-mrt-writes=true'"

2. Run the following command to examine the special monitor set.

   asadm -e "show statistics sets for <NAMESPACE_NAME> <ERO~MRT like objects -t"

   or

   asadm -e "enable; asinfo -v 'sets/<NAMESPACE_NAME>/<ERO~MRT'" and in response objects=? shows the count

3. When the number of records given by the “objects” value is zero, transactions are stopped. The character between the O and the M in the set name is a tilde not a dash.

Mechanism

The mechanism involved in truncating a namespace, or a set within a namespace, is distinct from NSUP.

Note

Prior to Database 6.3.0, the truncate info command started a single background thread on each of the nodes in the cluster. Starting with Database 6.3.0, the truncate info command starts a number of threads for each truncation job equal to the value of the truncate-threads configuration parameter. The truncate threads then traverse the primary index of the namespace and remove the necessary records.

In Database 6.3.0 and later:

• Set truncation is optimized to use set indexes to rapidly find all the records belonging to the set being truncated. This optimization significantly increases the speed of set truncation, with the caveat that it is skipped if the set has tombstones.

• The truncate command takes an optional last update time (LUT) threshold parameter, lut which limits the truncation to records with an LUT earlier than the specified timestamp . If no timestamp is specified, the “now” timestamp of the receiving node is used.

• Set truncation can be issued repeatedly. It updates the effective last update time of an affected set, and is reflected in the lut field of the set information.

• For truncation on sets with secondary indexes, each record data is actively read, and any secondary index entries associated with the record are also removed. See Manage sindexes.

• In the Enterprise Edition, truncation is durable and preserves record deletions through a cold-restart. In the Community Edition, similar to record deletes, records in previously truncated sets are not durable and deletes can return through a cold start.

Truncate undo

Use the truncate-undo and truncate-namespace-undo commands to remove the truncate related entry(ies) in SMD to allow for potential recovery of inadvertently truncated records upon a subsequent cold restart. Truncated records that have been overwritten on persistent storage are not recoverable.

During cluster change

If nodes return to the cluster during or after a truncate or truncate-namespace command has run, the SMD subsystem provides information on what has been truncated. The nodes will match the truncation level of the rest of the cluster by truncating data based on the LUT received through the SMD subsystem.

During migrations, records are checked against the truncation criteria based on the timestamp saved in the SMD truncate file for the specific set and/or namespace as partitions migrate across nodes. If they meet the truncation criteria, the records are discarded. In this way, truncate and truncate-namespace are completely robust during cluster memberships changes.

When nodes are executing truncate or truncate-namespace, incoming transactions are only executed if the LUT of the accessed record is older than the execution time of any truncation command (pending or completed). From an application’s perspective, as soon as a truncation command starts, whether directly, through an SMD update, or when a node joins a cluster, the would-be truncated record cannot be differentiated from an already truncated record, and the command works as if it were instantaneous. This is possible as records accessed through any transactions are checked against the LUTs stored in the SMD subsystem.

Manage sindexes

The presence of sindexes can slow down truncation. Delete any sindexes before running truncate or truncate-namespace, as described in the following table.

Storage Engine	Versions	Description
All Flash	Prior to Database 5.7.0.20	Before you truncate, delete the secondary index (sindex) associated with the set to avoid performance impact.
	Database 6.0.0 prior to 6.0.0.4	Before you truncate, delete the sindex associated with the set to avoid performance impact.
	Database 5.7.0.20 and later and Database 6.0.0.4 and later	Do not delete sindex before truncating. Truncation updates the secondary index on the fly.
Other storage engines (including persistent memory, data-in-memory, data-in-index, memory-only, and shadow device)	Database prior to 5.7.0	Before you truncate, delete the sindex associated with the set to avoid performance impact.
	Database 5.7.0 and later	Do not delete any sindex prior to truncating a set. Deleting a secondary index while a truncation is in progress could impact performance.

Note

If using the client APIs to perform the truncation, the LUT (last update time) is accurate to 1 millisecond (ms) resolution.

Reclaiming unused sets

The total number of sets in a namespace is limited to 1023 in Database 6.x.x and earlier, and 4095 in Database 7.x and later. Deleting a set metadata to reclaim space from this limit requires durably deleting all the data in the set and cold restarting the node. See How to clear up set names when they exceed the limit for details.