Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

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
    Example: http

    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
    Example: 9102

    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
    Update Index Settings

    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.

    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.

    Settings

    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.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 performance impact. 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 is 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 details, 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 snapshotting 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 snapshotting 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 snapshotting 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 snapshotting 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 snapshotting 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 snapshotting 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 snapshotting interval for the initial build (ms).

    Default: 5000

    Integer (int32)

    indexer.settings.persisted_snapshot_init_build.interval
    optional

    The persisted snapshotting 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 snapshotting 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 details, 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.

    Storage Mode

    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)

    Storage Mode

    Composite Schema

    One of …​ Schema

    ENTERPRISE EDITION

    If you are using 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.

    String

    or

    COMMUNITY EDITION

    If you are using Community Edition, the default (and only) value is forestdb.

    String

    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.