Index Settings REST API

  • reference

Overview

The Index Settings REST API is provided by the Index Service. This API enables you to retrieve or set Index Service settings.

Changes automatically propagate to all Index Service nodes, and will be remembered across node and cluster restarts.

Unless otherwise noted, you should only change the Index Service settings when advised to do so by Couchbase Support.

Version information

Version: 8.0

Host information

{scheme}://{host}:{port}

The URL scheme, host, and port are as follows.

Component Description

scheme

The URL scheme. Use https for secure access.

Values: http, https

host

The host name or IP address of a node running the Index Service.

Example: localhost

port

The Index Service REST port. Use 19102 for secure access.

Values: 9102, 19102

Examples on this page

In the HTTP request examples:

  • $HOST is the host name or IP address of a node running the Index Service.

  • $USER is the user name of any authorized user — see Security.

  • $PASSWORD is the password to connect to Couchbase Server.

Resources

This section describes the operations available with this REST API.

Retrieve Index Settings

GET /settings

Description

Returns Index Service settings.

Produces
  • application/json

Responses

HTTP Code Description Schema

200

Success. Returns an object giving Index Service settings.

404

Not found. The URL may be specified incorrectly.

401

Unauthorized. Failure to authenticate.

Security

Type Name

http (basic)

Default

Example HTTP Request

The example below retrieves the current index settings.

Curl request
curl -X GET http://$HOST:9102/settings \
  -u $USER:$PASSWORD

Example HTTP Response

Response 200
{
  "indexer.settings.allow_large_keys": true,
  "indexer.settings.bufferPoolBlockSize": 16384,
  "indexer.settings.build.batch_size": 5,
  "indexer.settings.compaction.abort_exceed_interval": false,
  "indexer.settings.compaction.check_period": 30,
  "indexer.settings.compaction.compaction_mode": "circular",
  "indexer.settings.compaction.days_of_week": "Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday",
  "indexer.settings.compaction.interval": "00:00,00:00",
  "indexer.settings.compaction.min_frag": 30,
  "indexer.settings.compaction.min_size": 524288000,
  "indexer.settings.compaction.plasma.manual": false,
  "indexer.settings.compaction.plasma.optional.decrement": 5,
  "indexer.settings.compaction.plasma.optional.min_frag": 20,
  "indexer.settings.compaction.plasma.optional.quota": 25,
  "indexer.settings.corrupt_index_num_backups": 1,
  "indexer.settings.cpuProfDir": "",
  "indexer.settings.cpuProfile": false,
  "indexer.settings.defer_build": false,
  "indexer.settings.eTagPeriod": 240,
  "indexer.settings.enable_corrupt_index_backup": false,
  "indexer.settings.enable_page_bloom_filter": true,
  "indexer.settings.enable_shard_affinity": false,
  "indexer.settings.fast_flush_mode": true,
  "indexer.settings.gc_percent": 100,
  "indexer.settings.inmemory_snapshot.fdb.interval": 200,
  "indexer.settings.inmemory_snapshot.interval": 200,
  "indexer.settings.inmemory_snapshot.moi.interval": 10,
  "indexer.settings.largeSnapshotThreshold": 200,
  "indexer.settings.log_level": "info",
  "indexer.settings.maxNumPartitions": 64,
  "indexer.settings.maxVbQueueLength": 0,
  "indexer.settings.max_array_seckey_size": 10240,
  "indexer.settings.max_cpu_percent": 0,
  "indexer.settings.max_seckey_size": 4608,
  "indexer.settings.max_writer_lock_prob": 20,
  "indexer.settings.memProfDir": "",
  "indexer.settings.memProfile": false,
  "indexer.settings.memory_quota": 536870912,
  "indexer.settings.minVbQueueLength": 30,
  "indexer.settings.moi.debug": false,
  "indexer.settings.moi.persistence_threads": 4,
  "indexer.settings.moi.recovery.max_rollbacks": 2,
  "indexer.settings.moi.recovery_threads": 8,
  "indexer.settings.num_replica": 0,
  "indexer.settings.percentage_memory_quota": 0,
  "indexer.settings.persisted_snapshot.fdb.interval": 5000,
  "indexer.settings.persisted_snapshot.interval": 5000,
  "indexer.settings.persisted_snapshot.moi.interval": 600000,
  "indexer.settings.persisted_snapshot_init_build.fdb.interval": 5000,
  "indexer.settings.persisted_snapshot_init_build.interval": 5000,
  "indexer.settings.persisted_snapshot_init_build.moi.interval": 600000,
  "indexer.settings.plasma.recovery.max_rollbacks": 2,
  "indexer.settings.rebalance.blob_storage_bucket": "",
  "indexer.settings.rebalance.blob_storage_prefix": "",
  "indexer.settings.rebalance.blob_storage_region": "",
  "indexer.settings.rebalance.blob_storage_scheme": "",
  "indexer.settings.rebalance.redistribute_indexes": false,
  "indexer.settings.recovery.max_rollbacks": 2,
  "indexer.settings.scan_getseqnos_retries": 30,
  "indexer.settings.scan_timeout": 120000,
  "indexer.settings.send_buffer_size": 1024,
  "indexer.settings.serverless.indexLimit": 201,
  "indexer.settings.sliceBufSize": 1600,
  "indexer.settings.smallSnapshotThreshold": 30,
  "indexer.settings.snapshotListeners": 4,
  "indexer.settings.snapshotRequestWorkers": 4,
  "indexer.settings.statsLogDumpInterval": 60,
  "indexer.settings.storage_mode": "plasma",
  "indexer.settings.storage_mode.disable_upgrade": false,
  "indexer.settings.thresholds.mem_high": 70,
  "indexer.settings.thresholds.mem_low": 50,
  "indexer.settings.thresholds.units_high": 60,
  "indexer.settings.thresholds.units_low": 40,
  "indexer.settings.units_quota": 10000,
  "indexer.settings.wal_size": 4096,
  "projector.settings.log_level": "info",
  "queryport.client.settings.backfillLimit": 5120,
  "queryport.client.settings.closeActiveConnections": true,
  "queryport.client.settings.minPoolSizeWM": 1000,
  "queryport.client.settings.poolOverflow": 30,
  "queryport.client.settings.poolSize": 5000,
  "queryport.client.settings.relConnBatchSize": 100
}

Update Index Settings

POST /settings

Description

Updates Index Service settings.

Consumes
  • application/json

Parameters

Body Parameter

Name Description Schema

Body
required

An object specifying Index Service settings. You only need to specify the settings you want to change; settings which are not specified are left unchanged.

Responses

HTTP Code Description Schema

200

Success. Returns OK and no object.

401

Unauthorized. Failure to authenticate.

404

Not found. The URL may be specified incorrectly.

Security

Type Name

http (basic)

Default

Example HTTP Requests

Defer Index Builds by Default

This example specifies the default setting for deferred builds.

Curl request
curl -X POST http://$HOST:9102/settings \
  -u $USER:$PASSWORD \
  -H 'content-type: application/json' \
  -d '{"indexer.settings.defer_build": true}'
Set the Indexer Scan Timeout

This example sets the indexer scan timeout.

Curl request
curl -X POST http://$HOST:9102/settings \
  -u $USER:$PASSWORD \
  -H 'content-type: application/json' \
  -d '{"indexer.settings.scan_timeout": 15000}'
Modify Index Batch Size

This example modifies the index batch size for rebalance.

Curl request
curl -X POST http://$HOST:9102/settings \
  -u $USER:$PASSWORD \
  -H 'content-type: application/json' \
  -d '{ "indexer.rebalance.transferBatchSize": 7 }'

Definitions

This section describes the properties consumed and returned by this REST API.

Settings

Object

Property Schema

indexer.​plasma.​LSSSegmentFileSize
optional

For standard indexes using Plasma, the maximum size for Log Structured Store segment files, in bytes. Index compaction and space reclamation are triggered when the segment file size reaches this value.

The default value is 512 MiB on Microsoft Windows and 4 GiB on GNU Linux and macOS. Specifying a lower value (for example, 64 MiB) may trigger index compaction more frequently in cases where an index uses a lot of disk space, or index fragmentation is high.

This setting only applies to indexes created after the setting is changed. For existing indexes, you must rebuild the index after changing the setting.

For more information, see Standard Index Storage.

Example: 67108864

Integer (int32)

indexer.​rebalance.​transferBatchSize
optional

Sets the batch size Couchbase Server uses when rebuilding index files during rebalance. This setting has no effect on file-based rebalance.

Couchbase Server breaks the rebuilding of indexes during a rebalance into batches to limit the effect on performance. This setting controls the maximum number of indexes that a rebalance rebuilds concurrently. You must have the Full Admin or the Cluster Admin role to set this value.

For an overview of rebalance as it affects the Index Service, including an overview of smart batching, see Rebalance.

Default: 3
Example: 7

Integer (int32)

indexer.​settings.​allow_large_keys
optional

Whether the size of index keys is unlimited.

  • If true, index keys may have unlimited size.
  • If false, the maximum size for index keys and array index keys is specified by indexer.settings.max_seckey_size and indexer.settings.max_array_seckey_size.

In Couchbase Server 6.5 and later, the Index Service does not need to restart when you update this setting.

Default: true

Boolean

indexer.​settings.​bufferPoolBlockSize
optional

Buffer pool block size.

Default: 16384

Integer (int32)

indexer.​settings.​build.​batch_size
optional

Build batch size.

Default: 5

Integer (int32)

indexer.​settings.​compaction.​abort_exceed_interval
optional

Whether to abort index compaction if it's still running after the end of the index compaction interval.

Default: false

Boolean

indexer.​settings.​compaction.​check_period
optional

An interval, specifying how frequently the Index Service checks whether the compaction threshold has been reached (seconds).

Default: 30

Integer (int32)

indexer.​settings.​compaction.​compaction_mode
optional

The compaction mode for indexes.

Values: "standard", "circular"
Default: "circular"

String

indexer.​settings.​compaction.​days_of_week
optional

The days of the week on which circular compaction is to run, if specified. Individual values must be day-names, each specified with an initial capital, and otherwise lower-case. Multiple values must be separated by a single comma, with no spaces.

Default: "Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday"
Example: "Saturday,Sunday"

String

indexer.​settings.​compaction.​interval
optional

A string in the form fromHour:fromMinute,toHour:toMinute, specifying the interval during which index compaction can run.

  • fromHour — An integer between 0 and 23 inclusive, specifying the starting hour of the interval.
  • fromMinute — An integer between 0 and 59 inclusive, specifying the starting minute of the interval, within the specified starting hour.
  • toHour — An integer between 0 and 23 inclusive, specifying the concluding hour of the interval.
  • toMinute — An integer between 0 and 59 inclusive, specifying the concluding minute of the interval, within the specified concluding hour.

The default value means any time.

Default: "00:00,00:00"
Example: "01:00,05:59"

String

indexer.​settings.​compaction.​min_frag
optional

The minimum fragmentation threshold to trigger compaction (percentage).

Default: 30
Minimum: 5

Integer (int32)

indexer.​settings.​compaction.​min_size
optional

Compaction minimum file size.

Default: 524288000

Integer (int32)

indexer.​settings.​compaction.​plasma.​manual
optional

For standard indexes using Plasma, whether compaction should be triggered manually.

Default: false

Boolean

indexer.​settings.​compaction.​plasma.​optional.​decrement
optional

For standard indexes using Plasma, the optional decrement.

Default: 5

Integer (int32)

indexer.​settings.​compaction.​plasma.​optional.​min_frag
optional

For standard indexes using Plasma, the minimum fragmentation threshold to trigger compaction (percentage).

Default: 20

Integer (int32)

indexer.​settings.​compaction.​plasma.​optional.​quota
optional

For standard indexes using Plasma, the optional quota.

Default: 25

Integer (int32)

indexer.​settings.​corrupt_index_num_backups
optional

Corrupt index number of backups.

Default: 1

Integer (int32)

indexer.​settings.​cpuProfDir
optional

The name of the directory where local CPU usage profiling information is captured.

String

indexer.​settings.​cpuProfile
optional

Whether the Index Service should capture local CPU usage profiling information.

Default: false

Boolean

indexer.​settings.​defer_build
optional

The default setting for the defer_build option for index creation.

  • If this setting is true, and you create an index without specifying defer_build, the index is not built immediately.
  • If this setting false, and you create an index without specifying defer_build, the index is built immediately.

You can override this setting by specifying the defer_build option when you create an index.

Default: false

Boolean

indexer.​settings.​eTagPeriod
optional

The ETag (entity tag) period.

Default: 240

Integer (int32)

indexer.​settings.​enable_corrupt_index_backup
optional

Whether corrupt index backup is enabled.

Default: false

Boolean

indexer.​settings.​enable_page_bloom_filter
optional

Whether Bloom filters are enabled for memory management.

For more information, see Per Page Bloom Filters.

Default: true

Boolean

indexer.​settings.​enable_shard_affinity
optional

Selects the index rebalance method. See Index Rebalance Methods.

  • If false (the default), Index Service nodes rebuild indexes that are newly assigned to them during a rebalance.

  • If true, Couchbase Server moves a reassigned index's files between Index Service nodes.

If set to true, when you create an index, you can use the WITH clause to specify which node should contain the index. However, when you alter an index, you cannot use the WITH clause to specify which node should contain the index.

Default: false

Boolean

indexer.​settings.​fast_flush_mode
optional

Whether fast flush mode is enabled.

Default: true

Boolean

indexer.​settings.​gc_percent
optional

Garbage collection percentage.

Default: 100

Integer (int32)

indexer.​settings.​inmemory_snapshot.​fdb.​interval
optional

For standard indexes using Forestdb, the in-memory snapshot interval (ms). This determines the earliest possibility of a scan seeing a given KV mutation.

Default: 200
Minimum: 1 (exclusive)

Integer (int32)

indexer.​settings.​inmemory_snapshot.​interval
optional

The in-memory snapshot interval (ms). This determines the earliest possibility of a scan seeing a given KV mutation.

Default: 200
Minimum: 1 (exclusive)

Integer (int32)

indexer.​settings.​inmemory_snapshot.​moi.​interval
optional

For memory-optimized indexes, the in-memory snapshot interval (ms). This determines the earliest possibility of a scan seeing a given KV mutation.

Default: 10
Minimum: 1 (exclusive)

Integer (int32)

indexer.​settings.​largeSnapshotThreshold
optional

The large snapshot threshold.

Default: 200

Integer (int32)

indexer.​settings.​log_level
optional

Indexer logging level.

Values: "silent", "fatal", "error", "warn", "info", "verbose", "timing", "debug", "trace"
Default: "info"

String

indexer.​settings.​maxNumPartitions
optional

Maximum number of partitions.

Default: 64

Integer (int32)

indexer.​settings.​maxVbQueueLength
optional

Maximum vBucket queue length.

Default: 0

Integer (int32)

indexer.​settings.​max_array_seckey_size
optional

If indexer.settings.allow_large_keys is false, this setting specifies the maximum size for array index keys.

In Couchbase Server 6.5 and later, the Index Service does not need to restart when you update this setting.

Default: 10240

Integer (int32)

indexer.​settings.​max_cpu_percent
optional

The CPU capacity that the Index Service should use (percentage). If set to 0, the indexer will use all CPUs.

Default: 0

Integer (int32)

indexer.​settings.​max_seckey_size
optional

If indexer.settings.allow_large_keys is false, this setting specifies the maximum size for index keys.

In Couchbase Server 6.5 and later, the Index Service does not need to restart when you update this setting.

Default: 4608

Integer (int32)

indexer.​settings.​max_writer_lock_prob
optional

Maximum writer lock prob.

Default: 20

Integer (int32)

indexer.​settings.​memProfDir
optional

The name of the directory where local memory usage profiling information is captured.

String

indexer.​settings.​memProfile
optional

Whether the Index Service should capture local memory usage profiling information.

Default: false

Boolean

indexer.​settings.​memory_quota
optional

How much RAM is allocated to the Index Service for the current node.

Default: 536870912

Integer (int32)

indexer.​settings.​minVbQueueLength
optional

Minimum vBucket queue length.

Default: 30

Integer (int32)

indexer.​settings.​moi.​debug
optional

Debug memory-optimized index storage.

Default: false

Boolean

indexer.​settings.​moi.​persistence_threads
optional

For memory-optimized index storage, the number of persistence threads.

Default: 4

Integer (int32)

indexer.​settings.​moi.​recovery.​max_rollbacks
optional

For memory-optimized index storage, the maximum number of committed rollback points.

Default: 2

Integer (int32)

indexer.​settings.​moi.​recovery_threads
optional

For memory-optimized index storage, the number of recovery threads.

Default: 8

Integer (int32)

indexer.​settings.​num_replica
optional

The default number of index replicas to be created by the Index Service whenever CREATE INDEX is invoked.

Default: 0
Example: 2

Integer (int32)

indexer.​settings.​percentage_memory_quota
optional

Percentage memory quota.

Default: 0

Integer (int32)

indexer.​settings.​persisted_snapshot.​fdb.​interval
optional

For standard indexes using Forestdb, the persisted snapshot interval (ms). This must be a multiple of the in-memory snapshot interval.

Default: 5000
Minimum: 100

Integer (int32)

indexer.​settings.​persisted_snapshot.interval
optional

The persisted snapshot interval (ms). This must be a multiple of the in-memory snapshot interval.

Default: 5000
Minimum: 100

Integer (int32)

indexer.​settings.​persisted_snapshot.​moi.​interval
optional

For memory-optimized indexes, the persisted snapshot interval (ms). This must be a multiple of the in-memory snapshot interval.

Default: 600000
Minimum: 100

Integer (int32)

indexer.​settings.​persisted_snapshot_init_build.​fdb.​interval
optional

For standard indexes using Forestdb, the persisted snapshot interval for the initial build (ms).

Default: 5000

Integer (int32)

indexer.​settings.​persisted_snapshot_init_build.​interval
optional

The persisted snapshot interval for the initial build (ms).

Default: 5000

Integer (int32)

indexer.​settings.​persisted_snapshot_init_build.​moi.​interval
optional

For memory-optimized indexes, the persisted snapshot interval for the initial build (ms).

Default: 600000

Integer (int32)

indexer.​settings.​plasma.​recovery.​max_rollbacks
optional

For standard indexes using Plasma, the maximum number of committed rollback points.

Default: 2

Integer (int32)

indexer.​settings.​rebalance.​blob_storage_bucket
optional

Rebalance blob storage bucket.

Default: ""

String

indexer.​settings.​rebalance.​blob_storage_prefix
optional

Rebalance blob storage prefix.

Default: ""

String

indexer.​settings.​rebalance.​blob_storage_region
optional

Rebalance blob storage region.

Default: ""

String

indexer.​settings.​rebalance.​blob_storage_scheme
optional

Rebalance blob storage scheme.

Default: ""

String

indexer.​settings.​rebalance.​redistribute_indexes
optional

Whether to redistribute indexes on rebalance.

  • When true, Couchbase Server redistributes indexes when rebalance occurs, in order to optimize performance.

  • When false (the default), such redistribution does not occur.

For more information, see Rebalance.

Default: false

Boolean

indexer.​settings.​recovery.​max_rollbacks
optional

The maximum number of committed rollback points.

Default: 2

Integer (int32)

indexer.​settings.​scan_getseqnos_retries
optional

Scan get sequence numbers retries.

Default: 30

Integer (int32)

indexer.​settings.​scan_timeout
optional

The default timeout for the indexer, in milliseconds. This is distinct from the Query Service timeout. The Index Service has its own timeout because index scans consume resources such as memory and CPU while holding snapshots and performing range scan.

An index scan may time out if the Index Service timeout is lower than the Query Service timeout.

Default: 120000

Integer (int32)

indexer.​settings.​send_buffer_size
optional

Send buffer size.

Default: 1024

Integer (int32)

indexer.​settings.​serverless.​indexLimit
optional

Serverless index limit.

Default: 201

Integer (int32)

indexer.​settings.​sliceBufSize
optional

Slice buffer size.

Default: 1600

Integer (int32)

indexer.​settings.​smallSnapshotThreshold
optional

Small snapshot threshold.

Default: 30

Integer (int32)

indexer.​settings.​snapshotListeners
optional

Snapshot listeners.

Default: 4

Integer (int32)

indexer.​settings.​snapshotRequestWorkers
optional

Snapshot request workers.

Default: 4

Integer (int32)

indexer.​settings.​statsLogDumpInterval
optional

Statistics log dump interval.

Default: 60

Integer (int32)

indexer.​settings.​storage_mode
optional

The storage mode to be used for the Index Service on this node.


If you're using Couchbase Server Enterprise Edition, the possible values are:

  • plasma (the default) — Sets the index storage mode to use the Plasma storage engine, which can utilize both memory and persistent storage for index maintenance and index scans.

  • memory_optimized — Sets the index storage mode to use memory optimized Global Secondary Indexes, which can perform index maintenance and index scan faster at in-memory speeds.

This setting can only be changed while there are no index nodes in the cluster. To change from standard GSI to memory optimized GSI or vice versa, you need to remove all the Index Service nodes in the cluster.


If you're using Couchbase Server Community Edition, the default (and only) value is forestdb.

Values: "plasma", "memory_optimized", "forestdb"

String

indexer.​settings.​storage_mode.​disable_upgrade
optional

Whether upgrade of the index storage mode is disabled.

Default: false

Boolean

indexer.​settings.​thresholds.​mem_high
optional

High memory threshold.

Default: 70

Integer (int32)

indexer.​settings.​thresholds.​mem_low
optional

Low memory threshold.

Default: 50

Integer (int32)

indexer.​settings.​thresholds.​units_high
optional

High units threshold.

Default: 60

Integer (int32)

indexer.​settings.​thresholds.​units_low
optional

Low units threshold.

Default: 40

Integer (int32)

indexer.​settings.​units_quota
optional

Units quota.

Default: 10000

Integer (int32)

indexer.​settings.​wal_size
optional

Write-ahead log size.

Default: 4096

Integer (int32)

projector.​settings.​log_level
optional

Projector logging level.

Default: "info"

String

queryport.​client.​settings.​backfillLimit
optional

The maximum size of the backfill file (MB).

  • A value of 0 disables backfill.
  • A value of -1 means the size is unlimited.

The maximum size is limited only by the available disk space.

Default: 5120

Integer (int32)

queryport.​client.​settings.​closeActiveConnections
optional

Whether to close active connections.

Default: true

Boolean

queryport.​client.​settings.​minPoolSizeWM
optional

Minimum pool size.

Default: 1000

Integer (int32)

queryport.​client.​settings.​poolOverflow
optional

Maximum number of connections in a pool.

Default: 30

Integer (int32)

queryport.​client.​settings.​poolSize
optional

Number of simultaneous active connections in a pool.

Default: 5000

Integer (int32)

queryport.​client.​settings.​relConnBatchSize
optional

Connection batch size.

Default: 100

Integer (int32)

Security

The Index Settings API supports admin credentials. Pass your credentials through HTTP headers (HTTP basic authentication).

Default

Users must have the Full Admin or Cluster Admin role, with Cluster Read and Bucket INDEX List privileges.

Type: http

Refer to Roles for more details.