Link Search Menu Expand Document Documentation Menu
Documentation

Index settings

Index settings apply to individual indexes, and their names begin with index.. For cluster settings that apply to all indexes in the cluster, see Cluster settings for indexes.

You specify index settings when creating an index. Index settings can be static or dynamic. The following table describes when and how you can update each type of setting.

Setting type When you can update it How to update it
Static When the index is closed Close the index, update the setting using the Update Index Settings API, and then reopen the index. For more information, see Updating a static index setting.
Dynamic At any time Use the Update Index Settings API. For more information, see Updating a dynamic index setting.

Specifying a setting when creating an index

When creating an index, you can specify its static or dynamic settings as follows:

PUT /testindex
{
  "settings": {
    "index.number_of_shards": 1,
    "index.number_of_replicas": 2
  }
}

Updating a static index setting

You can update a static index setting only on a closed index. The following example demonstrates updating the index codec setting.

First, close an index:

POST /testindex/_close

Then update the settings by sending a request to the _settings endpoint:

PUT /testindex/_settings
{
  "index": {
    "codec": "zstd_no_dict",
    "codec.compression_level": 3
  }
}

Last, reopen the index to enable read and write operations:

POST /testindex/_open

For more information about updating settings, including supported query parameters, see Update settings.

Updating a dynamic index setting

You can update a dynamic index setting at any time through the API. For example, to update the refresh interval, use the following request:

PUT /testindex/_settings
{
  "index": {
    "refresh_interval": "2s"
  }
}

For more information about updating settings, including supported query parameters, see Update settings.

Static index settings

Static index settings are settings that you can update only on a closed index. Some static index settings are final. You can specify a final setting only when creating an index and cannot update it afterward, even on a closed index.

OpenSearch supports the following static index settings:

  • index.number_of_shards (Final, integer): The number of primary shards in the index. Default is 1.

  • index.number_of_routing_shards (Static, integer): The number of routing shards used to split an index.

  • index.shard.check_on_startup (Static, Boolean): Whether the index’s shards should be checked for corruption. Available options are false (do not check for corruption), checksum (check for physical corruption), and true (check for both physical and logical corruption). Default is false.

  • index.codec (Static, string): Determines how the index’s stored fields are compressed and stored on disk. This setting impacts the size of the index shards and the performance of the index operations.

    Valid values are:

    • default
    • best_compression
    • zstd (OpenSearch 2.9 and later)
    • zstd_no_dict(OpenSearch 2.9 and later)
    • qat_lz4 (OpenSearch 2.14 and later, on supported systems)
    • qat_deflate (OpenSearch 2.14 and later, on supported systems)
    • qat_zstd (OpenSearch 2.19.3 and later, on supported systems)

For zstd, zstd_no_dict, qat_lz4, qat_deflate, and qat_zstd, you can specify the compression level in the index.codec.compression_level setting. For more information, see Index codec settings. Optional. Default is default.

  • index.codec.compression_level (Static, integer): The compression level setting provides a trade-off between compression ratio and speed. A higher compression level results in a higher compression ratio (smaller storage size), but slower compression and decompression speeds lead to higher indexing and search latencies. This setting can only be specified if index.codec is set to zstd or zstd_no_dict in OpenSearch 2.9 and later; qat_lz4 or qat_deflate in OpenSearch 2.14 and later; or qat_zstd in OpenSearch 2.19.3 and later. Valid values are integers in the [1, 6] range. For more information, see Index codec settings. Optional. Default is 3.

  • index.routing_partition_size (Static, integer): The number of shards a custom routing value can go to. Routing helps an imbalanced cluster by relocating values to a subset of shards rather than a single shard. To enable routing, set this value to greater than 1 but less than index.number_of_shards. Default is 1.

  • index.sort.field (Final, string): Specifies the field used to sort documents at index time. The default sort order is asc (ascending). To change the order, set the index.sort.order parameter.

  • index.sort.order (Final, string): Specifies the document sort order at index time. Valid values are asc (ascending) and desc (descending). Default is asc. This setting requires index.sort.field to also be set.

  • index.sort.mode (Final, string): Controls how multi-valued fields are handled during sorting. Valid values are min (uses the lowest value) and max (uses the highest value).

  • index.sort.missing (Final, string): Determines how documents missing the sort field are handled. Valid values are _last (places documents without the field at the end) and _first (places documents without the field at the beginning).

  • index.load_fixed_bitset_filters_eagerly (Static, Boolean): Whether OpenSearch should preload cached filters. Available options are true and false. Default is true.

  • index.queries.cache.enabled (Static, Boolean): Enables or disables the query cache for the index. The query cache stores the results of frequently used filters on each data node. To configure the size of the query cache, use the node-level indices.queries.cache.size setting. Default is true.

  • index.query.parse.allow_unmapped_fields (Static, Boolean): Allows unmapped fields in query parsing. Default is true.

  • index.query_string.lenient (Static, Boolean): Enables lenient parsing for query strings. Default is false.

  • index.store.type (Static, string): The file system implementation that OpenSearch uses to store and read the index’s shard data on disk. Valid values are:

    • fs: OpenSearch selects the implementation for the operating environment. It uses hybridfs on 64-bit systems when memory mapping is allowed and niofs otherwise.
    • hybridfs: Reads most index files using memory mapping and reads the file types listed in the index.store.hybrid.nio.extensions setting using Java NIO.
    • mmapfs: Reads all index files using memory mapping. Memory mapping uses virtual address space in proportion to the size of the files, so make sure that the operating system allows enough memory map areas.
    • niofs: Reads all index files using Java NIO, without memory mapping.

    If memory mapping is disabled using the node.store.allow_mmap setting, OpenSearch rejects the hybridfs and mmapfs values. Default is fs.

  • index.store.stats_refresh_interval (Static, time unit): The refresh interval for index store statistics. Default is 10s.

  • index.check_pending_flush.enabled (Static, Boolean): This setting controls the Apache Lucene checkPendingFlushOnUpdate index writer setting, which specifies whether an indexing thread should check for pending flushes on an update in order to flush indexing buffers to disk. Default is true.

  • index.use_compound_file (Static, Boolean): This setting controls the Apache Lucene useCompoundFile index writer settings, which specifies whether newly written segment files will be packed into a compound file. Default is true.

  • index.append_only.enabled (Final, Boolean): Set to true to prevent any updates to documents in the index. Default is false.

  • index.derived_source.enabled (Final, Boolean): Set to true to dynamically generate the source without explicitly storing the _source field, which can optimize storage. Default is false. For more information, see Derived source.

  • index.mapping.ignore_malformed (Static, Boolean): Controls whether malformed fields are ignored during document parsing. When enabled, documents with malformed field values are indexed successfully, with the malformed fields either ignored or set to null depending on the field type. When disabled, documents with malformed fields are rejected. This setting provides a default behavior that can be overridden at the field level. Default is false.

  • index.soft_deletes.enabled (Final, Boolean): Enables soft deletes for the index. When enabled, deleted documents are marked as deleted rather than immediately removed, allowing for better recovery and replication performance. This setting is mandatory for OpenSearch 2.0+ indices and is enabled by default for legacy indices. Once set, this setting cannot be changed after index creation. Default is true.

  • index.store.preload (Static, list): Specifies which file extensions should be preloaded into the filesystem cache when the index is opened. This setting only works with the mmap directory implementation and provides best-effort caching. Preloading files can improve search performance by reducing disk I/O, but it consumes more memory. Common extensions include nvd (norms), dvd (doc values), and tim (terms index). Default is [] (empty list).

  • index.replication.type (Final, string): Defines the replication strategy used for the index. Valid values are:

    • DOCUMENT: Traditional document-based replication where individual documents are replicated
    • SEGMENT: Segment-based replication for improved performance and reduced network overhead This setting must be configured during index creation and cannot be changed afterward. Default is DOCUMENT.

  • index.merge.policy (Static, string): Selects the merge policy that controls how Lucene segments are merged. Valid values are tiered, log_byte_size, and default. The default value resolves to tiered for standard indexes. For time-series indexes, which OpenSearch identifies by the presence of a @timestamp field, default resolves to the policy named by the node-level indices.time_series_index.default_index_merge_policy setting. Default is default. For time-series data, such as log events, we recommend log_byte_size, which can improve query performance for range queries on the @timestamp field. To configure the selected policy, use the merge settings.

Dynamic index settings

Dynamic index settings are settings that you can update at any time.

OpenSearch supports the following dynamic index settings:

  • index.codec.qatmode (Dynamic, string): The hardware acceleration mode used for the qat_lz4, qat_deflate, and qat_zstd compression codecs. Valid values are auto and hardware. For more information, see Index codec settings. Optional. Default is auto (the recommended setting).

  • index.hidden (Dynamic, Boolean): Whether the index should be hidden. Hidden indexes are not returned as part of queries that have wildcards. Available options are true and false. Default is false.

  • index.soft_deletes.retention_lease.period (Dynamic, time unit): The maximum amount of time to retain a shard’s history of operations. Default is 12h.

  • index.bulk.adaptive_shard_selection.enabled (Dynamic, Boolean): Set to true to enable adaptive shard selection for bulk operations so that a single shard is chosen for append-only indexes. Default is false. For more information, see Adaptive shard selection for bulk indexing.

  • index.number_of_replicas (Dynamic, integer): The number of replica shards each primary shard should have. For example, if you have 4 primary shards and set index.number_of_replicas to 3, the index has 12 replica shards. If not set, defaults to cluster.default_number_of_replicas (which is 1 by default).

  • index.number_of_search_replicas (Dynamic, integer): The number of search replica shards that each primary shard should have. For example, if you have 4 primary shards and set index.number_of_search_replicas to 3, the index has 12 search replica shards. Default is 0.

  • index.auto_expand_replicas (Dynamic, string): Whether the cluster should automatically add replica shards based on the number of data nodes. Specify a lower bound and upper limit (for example, 0–9) or all for the upper limit. For example, if you have 5 data nodes and set index.auto_expand_replicas to 0–3, then the cluster does not automatically add another replica shard. However, if you set this value to 0-all and add 2 more nodes for a total of 7, the cluster will expand to now have 6 replica shards. Default is disabled.

  • index.auto_expand_search_replicas (Dynamic, string): Controls whether the cluster automatically adjusts the number of search replica shards based on the number of available search nodes. Specify the value as a range with a lower and upper bound, for example, 0-3 or 0-all. If you don’t specify a value, this feature is disabled.

    For example, if you have 5 data nodes and set index.auto_expand_search_replicas to 0-3, the index can have up to 3 search replicas and the cluster does not automatically add another search replica shard. However, if you set index.auto_expand_search_replicas to 0-all and add 2 more nodes, for a total of 7, the cluster will expand to now have 7 search replica shards. This setting is disabled by default.

  • index.blocks.write (Dynamic, Boolean): Specifies whether the index is read-only. Setting to true blocks all write requests and makes the index read-only. Default is false.

  • index.search.idle.after (Dynamic, time unit): The amount of time a shard should wait for a search or get request until it goes idle. Default is 30s.

  • index.search.default_pipeline (Dynamic, string): The name of the search pipeline that is used if no pipeline is explicitly set when searching an index. If a default pipeline is set and the pipeline doesn’t exist, then the index requests fail. Use the pipeline name _none to specify no default search pipeline. For more information, see Default search pipeline.

  • index.refresh_interval (Dynamic, time unit): How often the index should refresh, which publishes its most recent changes and makes them available for searching. Can be set to -1 to disable refreshing. Default is 1s.

    If you don’t set this setting explicitly, shards that haven’t received a search request for the period specified in index.search.idle.after stop refreshing in the background until the next search request arrives. This optimizes bulk indexing for indexes that aren’t being searched. To refresh on a fixed schedule regardless of search traffic, set index.refresh_interval to 1s explicitly. For more information, see Refresh interval.

  • index.max_result_window (Dynamic, integer): The maximum value of from + size for searches of the index. from is the starting index to search from, and size is the number of results to return. Default is 10000.

  • index.max_inner_result_window (Dynamic, integer): The maximum value of from + size that specifies the number of returned nested search hits and most relevant document aggregated during the query. from is the starting index to search from, and size is the number of top hits to return. Default is 100.

  • index.max_rescore_window (Dynamic, integer): The maximum value of window_size for rescore requests to the index. Rescore requests reorder the index’s documents and return a new score, which can be more precise. Default is the same as index.max_inner_result_window or 10000 by default.

  • index.max_docvalue_fields_search (Dynamic, integer): The maximum number of docvalue_fields allowed in a query. Default is 100.

  • index.max_script_fields (Dynamic, integer): The maximum number of script_fields allowed in a query. Default is 32.

  • index.max_ngram_diff (Dynamic, integer): The maximum difference between min_gram and max_gram values for the NGramTokenizer and NGramTokenFilter. Default is 1.

  • index.max_shingle_diff (Dynamic, integer): The maximum difference between max_shingle_size and min_shingle_size to feed into the shingle token filter. Default is 3.

  • index.max_refresh_listeners (Dynamic, integer): The maximum number of refresh listeners each shard is allowed to have.

  • index.analyze.max_token_count (Dynamic, integer): The maximum number of tokens that can be returned from the _analyze API operation. Default is 10000.

  • index.highlight.max_analyzed_offset (Dynamic, integer): The number of characters a highlight request can analyze. Default is 1000000.

  • index.max_terms_count (Dynamic, integer): The maximum number of terms a terms query can accept. Default is 65536.

  • index.max_regex_length (Dynamic, integer): The maximum character length of regex that can be in a regexp query. Default is 1000.

  • index.query.default_field (Dynamic, list): A field or list of fields that OpenSearch uses in queries in case a field isn’t specified in the parameters.

  • index.query.max_nested_depth (Dynamic, integer): The maximum number of nesting levels for nested queries. Default is 20. Minimum is 1 (single nested query).

  • index.requests.cache.enable (Dynamic, Boolean): Enables or disables the index request cache. Default is true. For more information, see Index request cache.

  • index.routing.allocation.enable (Dynamic, string): Specifies options for the index’s shard allocation. Available options are all (allow allocation for all shards), primaries (allow allocation only for primary shards), new_primaries (allow allocation only for new primary shards), and none (do not allow allocation). Default is all.

  • index.unassigned.node_left.delayed_timeout (Dynamic, time unit): Sets the amount of time OpenSearch waits before allocating a replica shard that became unassigned because a node left the cluster. This setting overrides the cluster-level cluster.routing.allocation.unassigned.node_left.delayed_timeout setting. If neither setting is configured, the default is 1m. Set to 0 to disable delayed allocation for the index.

  • index.priority (Dynamic, integer): The priority of the index when OpenSearch allocates unassigned shards, for example, after a cluster restart. OpenSearch allocates shards of system indexes first and then allocates shards of indexes with a higher index.priority before shards of indexes with a lower one. Indexes with the same priority are allocated in order of creation date, newest first, and then by index name. Must be 0 or greater. Default is 1.

  • index.routing.rebalance.enable (Dynamic, string): Enables shard rebalancing for the index. Available options are all (allow rebalancing for all shards), primaries (allow rebalancing only for primary shards), replicas (allow rebalancing only for replicas), and none (do not allow rebalancing). Default is all.

  • index.gc_deletes (Dynamic, time unit): The amount of time to retain a deleted document’s version number. Default is 60s.

  • index.default_pipeline (Dynamic, string): The default ingest node pipeline for the index. If the default pipeline is set and the pipeline does not exist, then index requests fail. The pipeline name _none specifies that the index does not have an ingest pipeline.

  • index.final_pipeline (Dynamic, string): The final ingest node pipeline for the index. If the final pipeline is set and the pipeline does not exist, then index requests fail. The pipeline name _none specifies that the index does not have an ingest pipeline.

  • index.optimize_doc_id_lookup.fuzzy_set.enabled (Dynamic, Boolean): This setting controls whether fuzzy_set should be enabled in order to optimize document ID lookups in index or search calls by using an additional data structure, in this case, the Bloom filter data structure. Enabling this setting improves performance for upsert and search operations that rely on document IDs by creating a new data structure (Bloom filter). The Bloom filter allows for the handling of negative cases (that is, IDs being absent in the existing index) through faster off-heap lookups. Note that creating a Bloom filter requires additional heap usage during indexing time. Default is false.

  • index.optimize_doc_id_lookup.fuzzy_set.false_positive_probability (Dynamic, double): Sets the false-positive probability for the underlying fuzzy_set (that is, the Bloom filter). A lower false-positive probability ensures higher throughput for upsert and get operations but results in increased storage and memory use. Allowed values range between 0.01 and 0.50. Default is 0.20.

  • index.routing.allocation.total_shards_per_node (Dynamic, integer): The maximum combined total number of primary and replica shards from a single index that can be allocated to a single node. Default is -1 (unlimited). Helps control per-index shard distribution across nodes by limiting the number of shards per node. Use with caution because shards from this index may remain unallocated if nodes reach their configured limits.

  • index.routing.allocation.total_primary_shards_per_node (Dynamic, integer): The maximum number of primary shards from a single index that can be allocated to a single node. This setting is applicable only for remote-backed clusters. Default is -1 (unlimited). Helps control per-index primary shard distribution across nodes by limiting the number of primary shards per node. Use with caution because primary shards from this index may remain unallocated if nodes reach their configured limits.

  • index.derived_source.translog.enabled (Dynamic, Boolean): Controls how documents are read from the translog for an index with derived source enabled. Defaults to the index.derived_source.enabled value. For more information, see Derived source.

  • index.flush_after_merge (Dynamic, byte unit): The size (in bytes) after which to flush after merge operations. Default is 512MB.

  • index.max_slices_per_pit (Dynamic, integer): The maximum number of slices per point-in-time search. Default is 1024.

  • index.unreferenced_file_cleanup.enabled (Dynamic, Boolean): Enables cleanup of index files that are not referenced. Default is true.

  • index.warmer.enabled (Dynamic, Boolean): Enables index warmer functionality. Default is true.

  • index.allocation.max_retries (Dynamic, integer): The maximum number of times shards can be retried for allocation before giving up. This setting prevents infinite allocation retry loops when shards cannot be allocated due to resource constraints or other issues. Default is 5. Range is 0 to Integer.MAX_VALUE.

  • index.max_adjacency_matrix_filters (Dynamic, integer): The maximum number of adjacency matrix filters allowed in aggregations. Adjacency matrix aggregations analyze relationships between different filters. Higher values allow more complex relationship analysis but consume more memory. Default is 100. Minimum is 2.

  • index.max_slices_per_scroll (Dynamic, integer): The maximum number of slices allowed per scroll request for this index. Slicing allows scroll operations to be parallelized across multiple slices for better performance. Higher values enable more parallelization but consume more resources. Default is 1024. Minimum is 1.

  • index.optimize_auto_generated_id (Dynamic, Boolean): Enables optimization for documents with auto-generated IDs. When enabled, OpenSearch can optimize indexing performance for documents that use automatically generated document IDs rather than custom IDs. This optimization may not apply immediately and depends on the engine state. Default is true.

  • index.translog.generation_threshold_size (Dynamic, byte unit): The size threshold that triggers the creation of a new translog generation. When the current translog generation reaches this size, OpenSearch creates a new generation file. Larger values can improve indexing performance by reducing the frequency of generation rollovers but may increase recovery time. Default is 64MB. Minimum is 64KB.

  • index.translog.durability (Dynamic, string): Controls when the translog is fsynced to disk and committed. Valid values are request and async. When set to request, OpenSearch fsyncs and commits the translog on the primary and every allocated replica before it acknowledges an index, delete, update, or bulk request, so every acknowledged write survives a node crash. When set to async, OpenSearch fsyncs and commits in the background at the interval set by index.translog.sync_interval, which reduces indexing overhead but discards any acknowledged writes made since the last commit if a node fails. Values are case insensitive. Default is request.

  • index.translog.sync_interval (Dynamic, time unit): The frequency at which the translog is fsynced to disk and committed. More frequent syncing provides better durability guarantees but may impact indexing performance. Less frequent syncing improves performance but increases the risk of data loss during failures. Default is 5s. Minimum is 100ms.

  • index.translog.flush_threshold_size (Dynamic, byte unit): The maximum total size of translog operations that are not yet committed to Lucene. When the translog reaches this size, OpenSearch flushes the index, which creates a new Lucene commit point and starts a new translog generation. Smaller values shorten recovery times because fewer operations must be replayed, but they trigger flushes more frequently. Default is 512mb. Minimum is 56b.

  • index.translog.retention.age (Dynamic, time unit): The maximum age of translog files to retain for operations-based peer recovery. Translog files older than this setting are deleted during translog cleanup. This setting applies only to indexes that have soft deletes disabled. Because soft deletes are required for all indexes created in OpenSearch 2.0 and later, the setting has no effect on current indexes. Default is -1 (retention disabled).

  • index.translog.retention.size (Dynamic, byte unit): The maximum total size of translog files to retain for operations-based peer recovery. When the total size exceeds this threshold, older files are deleted during cleanup. Like index.translog.retention.age, this setting applies only to indexes that have soft deletes disabled, so it has no effect on indexes created in OpenSearch 2.0 and later. Default is -1 (retention disabled).

  • index.soft_deletes.retention.operations (Dynamic, long): The maximum number of soft-deleted operations to retain in the index. Soft deletes allow for efficient replication and point-in-time recovery by marking documents as deleted rather than immediately removed. This setting controls how many soft-deleted operations are preserved before they are eligible for cleanup. Default is 0 (unlimited retention).

  • index.remote_store.translog.keep_extra_gen (Dynamic, integer): The number of extra translog generations to keep in the remote store beyond the minimum required for recovery. Higher values provide more recovery options but consume more storage space. This setting helps balance between storage costs and recovery flexibility in remote store configurations. Default is 0.

  • index.remote_store.translog.buffer_interval (Dynamic, time unit): The interval at which translog data is buffered before being uploaded to the remote store. More frequent uploads provide better durability but may impact performance. This setting works in conjunction with the cluster-level cluster.remote_store.translog.buffer_interval setting, with the index-level setting taking precedence. Default inherits from cluster setting.

  • index.blocks.read_only (Dynamic, Boolean): When set to true, makes the index read-only by blocking all write operations including indexing, updates, and deletes. Read operations like searches and gets continue to work normally. This setting is useful for temporarily preventing writes during maintenance or troubleshooting. Default is false.

  • index.routing.allocation.require.temp (Dynamic, string): Requires shards for this index to be allocated only to nodes with the specified temperature attribute. This setting is used for hot-warm architectures where different node types handle different data temperatures. The value should match a node attribute like hot, warm, or cold. No default value - when not set, shards can be allocated to any eligible node.

  • index.periodic_flush_interval (Dynamic, time unit): Triggers a flush periodically at the configured interval, storing all in-memory operations to segments on disk. OpenSearch automatically performs flush operations in the background based on conditions such as transaction log size. Default is -1, which disables periodic flush. For pull-based ingestion indexes, the default is 10m. See Pull-based ingestion. You can configure this setting if your workload requires predictable, time-based flush intervals.

Merge settings

Merge settings control how Lucene segments are merged. The index.merge.policy setting, which selects the merge policy, is static. All other merge settings are dynamic. For more information about selecting a merge policy, see index.merge.policy.

Tiered merge policy settings

When using the tiered merge policy (the default), the following settings control merge behavior:

  • index.merge.policy.max_merge_at_once (Dynamic, integer): Sets the maximum number of segments to be merged at a time during normal merging operations. Higher values can reduce the total number of merges but require more memory and I/O resources during each merge operation. Default is 30. Minimum is 2.

  • index.merge.policy.segments_per_tier (Dynamic, double): Controls the allowed number of segments per tier in the tiered merge policy. Smaller values result in more merging but fewer segments, which can improve search performance at the cost of increased indexing overhead. Default is 10.0. Minimum is 2.0.

  • index.merge.policy.floor_segment (Dynamic, byte unit): Sets the smallest segment size that the merge policy distinguishes. Segments smaller than this value are rounded up to it and treated as equally sized when the policy selects candidates for merging, so the smallest segments are grouped and merged early instead of accumulating as a long tail of tiny segments. Larger values merge small segments more aggressively, which lowers the total segment count but increases merge work. The value must be greater than 0. Default is 16mb.

  • index.merge.policy.max_merged_segment (Dynamic, byte unit): Sets the maximum size of a segment produced by a background merge. The merge policy stops merging a group of segments when the estimated result would exceed this size, so segments larger than this value are only produced by a force merge. Smaller values keep individual merges shorter but leave more segments in the index. Default is 5gb.

  • index.merge.policy.deletes_pct_allowed (Dynamic, double): Sets the percentage of deleted documents that the index is allowed to accumulate before the merge policy begins merging segments specifically to reclaim that space. Lower values reclaim disk space sooner but increase merge work. Default is 20.0. Valid values are from 5.0 to 50.0.

  • index.merge.policy.expunge_deletes_allowed (Dynamic, double): Sets the percentage of deleted documents a segment must contain before a force merge with only_expunge_deletes set to true rewrites it. Default is 10.0. Valid values are from 0.0 to 100.0. For more information, see Force Merge API.

  • index.merge.policy.reclaim_deletes_weight (Dynamic, double): Deprecated and no longer applied. OpenSearch accepts and stores the value but does not pass it to the merge policy, so changing it has no effect. Use index.merge.policy.deletes_pct_allowed to control when deleted documents are reclaimed. Default is 2.0. Minimum is 0.0.

Log byte size merge policy settings

When using the log_byte_size merge policy, the following settings control merge behavior:

  • index.merge.log_byte_size_policy.merge_factor (Dynamic, integer): Controls how many segments are merged at once during normal merging operations. Higher values lead to fewer, larger segments, which can improve search performance but use more resources during merging. Default is 10. Minimum is 2.

  • index.merge.log_byte_size_policy.min_merge (Dynamic, byte unit): Sets the minimum size threshold for segment merging. Segments smaller than this size are more aggressively merged. Smaller values lead to fewer small segments but more merge operations. Default is 16mb.

  • index.merge.log_byte_size_policy.max_merge_segment (Dynamic, byte unit): Controls the maximum size of segments created during normal merge operations. Larger segments improve query performance but require more memory and can increase merge times. Default is 5gb.

  • index.merge.log_byte_size_policy.max_merge_segment_forced_merge (Dynamic, byte unit): Sets the maximum segment size when performing forced merge operations (such as during index optimization). This allows forced merges to create larger segments than normal merges. Default is unlimited.

  • index.merge.log_byte_size_policy.max_merged_docs (Dynamic, integer): Sets the maximum number of documents that a single segment can contain. The merge policy skips any merge that would produce a segment exceeding this count, which caps segment size by document count rather than by bytes. Default is 2147483647, which places no practical limit on the number of documents per segment.

  • index.merge.log_byte_size_policy.no_cfs_ratio (Dynamic, double): Sets the largest share of the total index size that a segment can occupy and still be written in Lucene’s compound file format, which packs a segment’s files into a single file and reduces the number of open file handles. Segments larger than this share of the index are written as separate files. Set the value to 1.0 (or true) to use the compound format for all segments and 0.0 (or false) to disable it. Default is 0.1. Valid values are from 0.0 to 1.0.

Merge scheduler settings

The following settings control the merge scheduler, which determines how merge operations are executed:

  • index.merge.scheduler.max_thread_count (Dynamic, integer): Sets the maximum number of threads on a single shard that may be merging at once. This controls the concurrency of merge operations within each shard. Higher values can improve merge performance on systems with SSDs and multiple CPU cores, but may increase resource usage. If your index is on spinning platter drives, decrease this to 1. Default is Math.max(1, Math.min(4, node.processors / 2)), which works well for solid-state drives. Minimum is 1.

  • index.merge.scheduler.auto_throttle (Dynamic, Boolean): Enables automatic throttling of merge operations to prevent them from overwhelming the system. When enabled, OpenSearch automatically adjusts merge I/O rates based on incoming indexing load. Default is true.

  • index.merge_on_flush.enabled (Dynamic, Boolean): This setting controls Apache Lucene’s merge-on-refresh feature that aims to reduce the number of segments by performing merges on refresh (or in terms of OpenSearch, on flush). Default is true.

  • index.merge_on_flush.max_full_flush_merge_wait_time (Dynamic, time unit): This setting sets the amount of time to wait for merges when index.merge_on_flush.enabled is enabled. Default is 10s.

  • index.merge_on_flush.policy (Dynamic, string): This setting controls which merge policy should be used when index.merge_on_flush.enabled is enabled. Default is default.

Slow log settings

OpenSearch supports the following dynamic slow log settings for monitoring search and indexing performance.

Indexing slow log settings

  • index.indexing.slowlog.threshold.index.warn (Dynamic, time unit): Sets the time threshold for logging slow indexing operations at the WARN level. Indexing operations that take longer than this threshold are logged as warnings. Default is -1 (disabled).

  • index.indexing.slowlog.threshold.index.info (Dynamic, time unit): Sets the time threshold for logging slow indexing operations at the INFO level. Indexing operations that take longer than this threshold are logged for informational purposes. Default is -1 (disabled).

  • index.indexing.slowlog.threshold.index.debug (Dynamic, time unit): Sets the time threshold for logging slow indexing operations at the DEBUG level. This provides detailed debugging information for indexing performance analysis. Default is -1 (disabled).

  • index.indexing.slowlog.threshold.index.trace (Dynamic, time unit): Sets the time threshold for logging slow indexing operations at the TRACE level. This provides the most detailed logging for troubleshooting indexing performance issues. Default is -1 (disabled).

Search slow log settings

  • index.search.slowlog.threshold.query.warn (Dynamic, time unit): Sets the time threshold for logging slow search query operations at the WARN level. Query operations that take longer than this threshold are logged as warnings. Default is -1 (disabled).

  • index.search.slowlog.threshold.query.info (Dynamic, time unit): Sets the time threshold for logging slow search query operations at the INFO level. Query operations that take longer than this threshold are logged for informational purposes. Default is -1 (disabled).

  • index.search.slowlog.threshold.query.debug (Dynamic, time unit): Sets the time threshold for logging slow search query operations at the DEBUG level. This provides detailed debugging information for query performance analysis. Default is -1 (disabled).

  • index.search.slowlog.threshold.query.trace (Dynamic, time unit): Sets the time threshold for logging slow search query operations at the TRACE level. This provides the most detailed logging for troubleshooting query performance issues. Default is -1 (disabled).

  • index.search.slowlog.threshold.fetch.warn (Dynamic, time unit): Sets the time threshold for logging slow search fetch operations at the WARN level. Fetch operations that take longer than this threshold are logged as warnings. Default is -1 (disabled).

  • index.search.slowlog.threshold.fetch.info (Dynamic, time unit): Sets the time threshold for logging slow search fetch operations at the INFO level. Fetch operations that take longer than this threshold are logged for informational purposes. Default is -1 (disabled).

  • index.search.slowlog.threshold.fetch.debug (Dynamic, time unit): Sets the time threshold for logging slow search fetch operations at the DEBUG level. This provides detailed debugging information for fetch performance analysis. Default is -1 (disabled).

  • index.search.slowlog.threshold.fetch.trace (Dynamic, time unit): Sets the time threshold for logging slow search fetch operations at the TRACE level. This provides the most detailed logging for troubleshooting fetch performance issues. Default is -1 (disabled).

350 characters left

Have a question? .

Want to contribute? or .