Skip to main content
Aerospike 8 introduces a new era of real-time transaction processingLearn more
Loading

Managing sets in a namespace

This page describes how to manage sets in a namespace.

Overview​

An Aerospike set is similar to a table in a relational database, except you do not need to define a schema for a set. Sets are created dynamically and implicitly on the first record insertion in set. For more see Data Model.

caution

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

Assigning a default TTL to a set​

As of Database 7.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.

The asadm command to dynamically specify default-ttl is:

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

See Data Retention for more details about record TTL.

Protecting a set from evictions​

A set can be protected from evictions with a dynamic configuration. If evictions are in effect for a namespace, sets with evictions disabled will be skipped, regardless of the void-time of the records.

The asadm command to dynamically disable set evictions is:

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

Or using the older info command:

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

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

Capping the size of a set​

Starting with Aerospike 6.3, you can use the stop-writes-size configuration parameter to specify a size limit for a set. If this threshold is breached, client writes to the set are refused. Deletions, replica writes, and migration writes are still allowed when the set is in stop-writes mode.

Once the limit is reached, the server does not allow any additional writes, even those that would decrease the size of a record. There are two ways to get under the stop-writes-size limit: increase or remove the limit, or delete records. However, record deletions using UDF, delete-all-bins ops, or background ops queries will also be rejected – only regular record deletes (including batch deletes) and nsup deletes will be allowed.

The asadm command to dynamically cap the size of a set is:

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

Or using the older info command:

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

Configuration parameters are applied per-node. asadm sends the same info command limiting the set size to all the nodes in the cluster. The cluster-wide size quota for the set is number-of-cluster-nodes x stop-writes-size.

The threshold is checked and stop-writes triggered independently on each node.

Use show stop-writes to view the configured cap and to see how close you are to crossing the limit.

note

Tools package 8.4.x or later is required to use `show stop-writes.

Capping the number of records in a set​

A set can be capped to a maximum number of records. If this threshold is breached, client writes to the set are refused. Deletions, replica writes, and migration writes are still allowed when the set is in stop-writes mode.

The asadm command to dynamically cap the number of records in a set is:

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

Or using the older info command:

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

Configuration parameters are applied per-node. asadm sends the same info command limiting the number of records in the set to all the nodes in the cluster. The cluster-wide record-count quota for the set is number-of-cluster-nodes x stop-writes-count.

The threshold is checked and stop-writes triggered independently on each node.

Use show stop-writes to view the configured cap and to see how close you are to crossing the limit.

note

Tools package 8.4.x or later is required to use `show stop-writes.

Adding and Removing a Set Index​

Introduced in Aerospike Database 5.6, a set index can be dynamically configured in the set context through declaring enable-index to be true. This may significantly improve performance when scanning the records in the set.

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

Or using the older info command:

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

Removing the set index is simply a matter of changing the value to false, which is also the default for each set.

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

Or using the older info command:

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

Monitoring Set Indexes​

The memory used for all set indexes in a namespace is available using the memory_used_set_index_bytes namespace statistic and also using the "memory-usage" server log ticker line.

Clearing a Set​

The total number of sets in a namespace is limited to 1023 in Database 6.0 and earlier, and 4095 in Database 7. 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.

Truncating a set in a namespace​

Use the asadm, asinfo, or aql 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'"

  1. 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
  1. 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, the truncate info command started a single background thread on each of the nodes in the cluster. Starting with Database 6.3, 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 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 EngineVersionsDescription
All FlashPrior to Database 5.7.0.20Before you truncate, delete the secondary index (sindex) associated with the set to avoid performance impact.
Database 6.0 prior to 6.0.0.4Before 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 laterDo 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.7Before you truncate, delete the sindex associated with the set to avoid performance impact.
Database 5.7 and laterDo 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.