Skip to main content

Managing Indexes

Aerospike provides tools for managing secondary indexes. These include :

  • asadm, the best choice for managing your Aerospike cluster.
  • aql, an SQL-like alternative to asadm.

Create and Manage Index​

Asadm provides the ability to create indexes using the manage sindex create command:

manage sindex create <bin-type> <index-name> ns <ns> [set <set>] bin <bin-name> [in <index-type>]

For details on this command, see asadm – Index Management.

Listing Indexes​

Use asadm to list indexes in the database:

Admin+> show sindex
~~~~Secondary Indexes (2021-09-07 22:45:05 UTC)~~~~
  Index|Namespace| Set| Bin|    Bin|Index   |State
   Name|         |    |    |   Type| Type   |     
ind2   |test     |demo|bin2|NUMERIC|DEFAULT |RW   
ind3   |test     |NULL|bin2|NUMERIC|DEFAULT |RW   
ind4   |test     |demo|bin3|NUMERIC|DEFAULT |RW   
ind1   |abcd     |demo|bin1|NUMERIC|DEFAULT |RW   
Number of rows: 4

Use asadm to list information about a single index:

Admin+> show sindex like ind1
~~~~Secondary Indexes (2021-09-07 22:45:05 UTC)~~~~
  Index|Namespace| Set| Bin|    Bin|Index   |State
   Name|         |    |    |   Type| Type   |     
ind1   |abcd     |demo|bin1|NUMERIC|DEFAULT |RW   
Number of rows: 1

Dropping Indexes​

Use asadm to drop indexes from the cluster:

manage sindex delete <index-name> ns <ns> [set <set>]

For more information on the delete command, see asadm – Index Management.

info

Index DDL changes are synchronous operations. When you run an index command, the nodes in the cluster consult each other and then run the command on each node. When the command is complete, verify the state of the index before using it.

info

You should consider whether or not you need a secondary index before creating one. You should avoid creating several indexes at one time, or creating indexes while nodes are migrating.

Repairing Indexes​

note

Deprecated in versions 3.14 and above.

If you find an index with sync_state=need_sync and state=RW, you should use asinfo to repair it.

Use Aerospike Info (asinfo) to repair the index:

$ asadm -e 'enable; asinfo -v "sindex-repair:ns=test;indexname=ind_name;set=set_name;"'

Index Memory Management​

Aerospike Secondary indexes exist entirely in memory. If you use secondary indexes, verify that the nodes in the cluster have enough memory for the indexes. For more information on memory allocation for secondary indexes, see capacity planning. If the namespace size is not configured to take into account the memory requirements of secondary indexes, and the memory high water mark is breached, the cluster may evict data or stop writes. You can limit the amount of memory used by secondary indexes to prevent the namespace from running out of memory.

Index Monitoring​

Important statistics to monitor:​

aql> stat index <namespace> <indexname>
NAMEDESCRIPTIONComments
entriesNumber of objects in the secondary index tree.For unique indexes, this value should equal the number of keys.
memory_usedTotal memory used by a secondary index.Use this to check system memory usage.
load_pctPercentage indicating the progress of secondary index populate phase.
load_timeTime taken to populate the secondary index.
stat_gc_recsNumber of records garbage collected from the secondary index.

Displaying Performance Histograms for Secondary Indexes​

note

Deprecated in version 6.0 and above.

To enable secondary index performance histograms:

asadm -e 'enable; "asinfo -v "sindex-histogram:ns=<namespace>;[set=demo];indexname=<index name>;enable=true"'

To disable secondary index performance histograms:

asadm -e 'enable; asinfo -v "sindex-histogram:ns=<namespace>;[set=demo];indexname=<index name>;enable=false"'

'enable=true' writes the secondary index performance histogram to the log.

'enable=false' stops writing the secondary index performance histogram to the log.

Displaying Performance Histograms for Secondary Indexes Garbage Collection​

note

Deprecated in version 3.14 and above.

note

Tools package 6.0.x or later is required to use asadm's manage config commands. Otherwise, use the equivalent asinfo - set-config command.

To enable secondary index garbage collection performance histograms:

Asadm+> manage config service param sindex-gc-enable-histogram to true

To disable secondary index garbage collection performance histograms:

Asadm+> manage config service param sindex-gc-enable-histogram to false

'enable=true' writes the secondary index garbage collection histogram to the log.

'enable=false' stops writing the secondary index garbage collection histogram to the log.

Static Configuration for Index Management.​

note

Deprecated in versions 3.14 and above.

If there are index-specific tuning configurations that you would like to persist, you may add them in a "si" stanza in the specific namespace.

You may add the following parameters to aerospike.conf:

NameDescriptionMinimumMaximumDefault
si-gc-periodInterval between two iterations of index garbage collection. Value is in milliseconds.0-1000
si-gc-max-unitsMaximum number of elements reviewed in each garbage collection cycle.0-1000
si-data-max-memoryMaximum amount of memory used by a specific index. Value is in bytes.0ULONG_MAXULONG_MAX
si-tracingTracing level for this index.040
si-histogramEnable and disable si-histogram mapping of this index for reads and writes in the server log.--False

You can edit the settings in the namespace section of the configuration file.

The following example shows the static configuration for the secondary index ind1:

namespace test {
    ...
    si ind1 {
       si-gc-period 100
       si-gc-max-units 10000
       si-tracing 0
       si-histogram false
    }
}
note

You must create the secondary index before you add the stanza to aerospike.conf.

Index Limits​

Refer to Known Limitations