Managing Indexes
Aerospike provides tools for managing secondary indexes. These include :
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>] [ctx <context>]
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.
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.
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
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;"'
Set Indexes
In server 5.6 and later, you can index membership of records to their set by creating a set index. Using a set index improves the performance of set-level operations, such as scanning all records in the set.
- For more information on set indexes, see Set Index Architecture.
- To manage set indexes, see Managing Sets in a Namespace
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>
- Version 6.0.0 and later
- Version 5.7 and below
NAME | DESCRIPTION | Comments |
---|---|---|
entries | Number of objects in the secondary index tree. | For unique indexes, this value should equal the number of keys. |
memory_used | Total memory used by a secondary index. | Use this to check system memory usage. |
load_pct | Percentage indicating the progress of secondary index populate phase. | |
load_time | Time taken to populate the secondary index. | |
stat_gc_recs | Number of records garbage collected from the secondary index. |
NAME | DESCRIPTION | Comments |
---|---|---|
keys | Number of primary keys indexed to this index. | Statistics to monitor the quantity of unique keys in a secondary index. |
entries | Number of objects in the secondary index tree. | For unique indexes, this value should equal the number of keys. |
ibtr_memory_used | Total memory used by a secondary index. | Use this to check system memory memory usage. |
nbtr_memory_used | Total memory used by a secondary index. | Use this to check system memory memory usage. |
stat_gc_recs | Number of records garbage collected from the secondary index. |
Displaying Performance Histograms for Secondary Indexes
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
Deprecated in version 3.14 and above.
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.
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:
Name | Description | Minimum | Maximum | Default |
---|---|---|---|---|
si-gc-period | Interval between two iterations of index garbage collection. Value is in milliseconds. | 0 | - | 1000 |
si-gc-max-units | Maximum number of elements reviewed in each garbage collection cycle. | 0 | - | 1000 |
si-data-max-memory | Maximum amount of memory used by a specific index. Value is in bytes. | 0 | ULONG_MAX | ULONG_MAX |
si-tracing | Tracing level for this index. | 0 | 4 | 0 |
si-histogram | Enable 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
}
}
You must create the secondary index before you add the stanza to aerospike.conf.
Index Limits
Refer to Known Limitations