Configure mongot

Configure mongot

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

Configure mongot

Use a YAML configuration file to configure mongot for MongoDB Search and Vector Search deployments.

Tip:

For the MongoDB Controllers for Kubernetes Operator deployments, you can use the MongoDBSearch custom resource to configure mongot. For more information, see [MongoDBSearch.](https://www.mongodb.com/docs/kubernetes/current/reference/fts-vs-settings.md#std-label-k8s-fts-vs-settings

The following example shows the full configuration structure with all available settings for self-managed mongot deployments with MongoDB Community:

syncSource:
   replicaSet: <object>
      hostAndPort: <string or list of strings>
      x509: <object>
         caFile: <string>
         tlsCertificateKeyFile: <string>
         tlsCertificateKeyFilePasswordFile: <string>
      scramAuth: <object>
         username: <string>
         passwordFile: <string>
         authSource: <string>
         tls: <object>
            enabled: <boolean>
            caFile: <string>
            tlsCertificateKeyFile: <string>
            tlsCertificateKeyFilePasswordFile: <string>
   router: <object>
      hostAndPort: <string or list of strings>
      x509: <object>
         caFile: <string>
         tlsCertificateKeyFile: <string>
         tlsCertificateKeyFilePasswordFile: <string>
      scramAuth: <object>
         username: <string>
         passwordFile: <string>
         authSource: <string>
         tls: <object>
            enabled: <boolean>
            caFile: <string>
            tlsCertificateKeyFile: <string>
            tlsCertificateKeyFilePasswordFile: <string>
   replicationReader:
      readPreference: <string>
      tagSets: <string or list of strings>
storage: <object>
   dataPath: <string>
server: <object>
   grpc: <object>
      address: <string>
      tls: <object>
         mode: <string>
         certificateKeyFile: <string>
         certificateKeyFilePasswordFile: <string>
         caFile: <string>
   name: <string>
metrics: <object>
   enabled: <boolean>
   address: <string>
healthCheck: <object>
   address: <string>
logging: <object>
   verbosity: <string>
   logPath: <string>
embedding:
   providerEndpoint: <string>
   queryKeyFile: <string>
   indexingKeyFile: <string>
   isAutoEmbeddingViewWriter: <boolean>
advancedConfigs: <object>
   indexing: <object>
      lucene: <object>
         refresh: <object>
            intervalMs: <int>
         mergePolicy: <object>
            tiered: <object>
               vectorMergePolicy: <object>
                  mergeBudgetMb: <int>
         mergeScheduler: <object>
            concurrent: <object>
               maxThreadCount: <int>
         fieldLimit: <int>
   querying: <object>
      lucene: <object>
         maxClauseLimit: <int>
         vectorFloorSegmentMB: <double>
   replication: <object>
      mongodb: <object>
         numConcurrentInitialSyncs: <int>
         numConcurrentChangeStreams: <int>
         numIndexingThreads: <int>
         numConcurrentSynonymSyncs: <int>
         pauseAllInitialSyncs: <boolean>
         pauseInitialSyncOnIndexIds: <list of strings>
         changeStreamMaxTimeMs: <int>
         changeStreamCursorMaxTimeSec: <int>
         numChangeStreamDecodingThreads: <int>
      initialSync: <object>
         bufferless: <object>
            enableNaturalOrderScan: <boolean>
   diskMonitor: <object>
      pauseReplicationThreshold: <double>
      resumeReplicationThreshold: <double>
      crashThreshold: <double>
      pauseInitialSyncThreshold: <double>
      resumeInitialSyncThreshold: <double>
   autoEmbedding: <object>
      materializedView: <object>
         numConcurrentChangeStreams: <int>
         numIndexingThreads: <int>
         numEmbeddingThreads: <int>
         numConcurrentInitialSyncs: <int>
         matViewWriterMaxConnections: <int>
         mvWriteRateLimitRps: <int>
         embeddingProviderRpsLimit: <int>
         maxInFlightEmbeddingGetMores: <int>
         embeddingGetMoreBatchSize: <int>
         changeStreamMaxTimeMs: <int>
         changeStreamCursorMaxTimeSec: <int>
         numChangeStreamDecodingThreads: <int>
         requestRateLimitBackoffMs: <int>
         globalMemoryBudgetHeapPercent: <int>
         perBatchMemoryBudgetHeapPercent: <int>
   cursor: <object>
      idleCursorHandlingRateMs: <int>
      cursorIdleTimeMs: <int>
   ftdc: <object>
      enabled: <boolean>
      directorySizeMb: <int>
      fileSizeMb: <int>
      collectionPeriodMillis: <int>

Required Settings

This section describes settings required for all mongot deployments. If you define only the required settings, mongot uses the defaults for all optional settings.

Type: Object

Replication connections to mongod for mongot.

Type: String or List of Strings

One or more host and port specifiers used to construct the seed list in the mongod connection string. Regardless of the number of specifiers provided, mongot establishes the connection in replica set mode, not standalone mode.

Type: String

Path that mongot must use as a base path for storing index data and the local index catalog.

Type: Object

Settings for the mongot query servers.

Type: Object

Listen server settings for gRPC communication between mongot and mongod.

Type: String

Address on which the gRPC listen server listens. Use the following format:

<host>:<port>

In self-managed deployments, this address must be reachable by the mongod processes that send search and index management traffic to mongot. Configure it so it matches the host and port that mongod uses for its mongotHost and searchIndexManagementHostAndPort settings.

For single-host development, localhost is the safest default. If mongod and mongot run on different hosts, set server.grpc.address to an interface that mongod can reach.

Warning:

Depending on your system topology, it may be necessary to bind the mongot query server to an interface accessible from your MongoDb Cluster. While binding to the 0.0.0.0 IP address is permitted, it exposes the server to all public networks and carries the risk of unauthorized access.

To enhance security, consider restricting server.grpc.address to specific interfaces that are controlled and protected at the network layer such as localhost or other trusted internal addresses.

Optional Settings

This section describes optional and conditionally required settings for mongot. If you omit these settings, mongot uses the specified default value when applicable.

Replica Set Authentication Settings

Type: Object

Necessity: Required if you do not use syncSource.replicaSet.scramAuth

X.509 certificate settings for authenticating mongot with mongod.

Type: String

Necessity: Required if you use syncSource.replicaSet.x509

Certificate Authority (CA) file that contains trusted certificates for verifying the certificate presented by mongod. The file must contain an X.509 certificate collection in PEM format.

Type: String

Necessity: Required if you use syncSource.replicaSet.x509

Path to the PEM file that contains the X.509 certificate and private key for authenticating mongot with mongod. Required when you configure syncSource.replicaSet.x509.

Type: String

Necessity: Optional

Path to the file that contains the password to decrypt the certificate key file specified in syncSource.replicaSet.x509.tlsCertificateKeyFile.

Type: Object

Necessity: Required if you do not use syncSource.replicaSet.x509

Settings for SCRAM authentication.

Type: String

Necessity: Required

The username to authenticate with.

Type: String

Necessity: Required

Path to a file that contains the password to authenticate with.

Type: String

Necessity: Optional

Default: admin

Name of the database associated with the mongot authentication credentials.

Type: Object

Necessity: Optional

Default: false

Settings for TLS.

Type: Boolean

Necessity: Required if you specify syncSource.replicaSet.scramAuth.tls

Flag to enable TLS authentication. Set to true to enable TLS authentication.

Type: String

Necessity: Optional

Certificate Authority (CA) file that contains trusted certificates for verifying the certificate presented by mongod. The file must contain an X.509 certificate collection in PEM format.

Type: String

Necessity: Optional

Path to the PEM file that contains the X.509 certificate and private key for authenticating mongot with mongod.

Type: String

Necessity: Optional

Path to the file that contains the password to decrypt the certificate key file specified in syncSource.replicaSet.scramAuth.tls.tlsCertificateKeyFile.

Sharded Clusters Settings

Type: Object

Replication connections to mongos for mongot. If omitted, mongot assumes it is running in a non-sharded environment. Required for sharded cluster deployments.

Type: Object

Necessity: Required if you do not use syncSource.router.scramAuth

X.509 certificate settings for authenticating mongot with mongos.

Type: String

Necessity: Required if you use syncSource.router.x509

Certificate Authority (CA) file that contains trusted certificates for verifying the certificate presented by mongos. The file must contain an X.509 certificate collection in PEM format.

Type: String

Necessity: Required if you use syncSource.router.x509

Path to the PEM file that contains the X.509 certificate and private key for authenticating mongot with mongos. Required when you configure syncSource.router.x509.

Type: String

Necessity: Optional

Path to the file that contains the password to decrypt the certificate key file specified in syncSource.router.x509.tlsCertificateKeyFile.

Type: Object

Necessity: Required if you do not use syncSource.router.x509

Settings for SCRAM authentication.

Type: String

Necessity: Required

The username to authenticate with.

Type: String

Necessity: Required

Path to a file that contains the password to authenticate with.

Type: String

Necessity: Optional

Name of the database associated with the mongot authentication credentials. If unspecified, authSource defaults to admin.

Type: Object

Necessity: Optional

Default: false

Settings for TLS.

Type: Boolean

Necessity: Required if you specify syncSource.router.scramAuth.tls

Flag to enable TLS authentication. Set to true to enable TLS authentication.

Type: String

Necessity: Optional

Certificate Authority (CA) file that contains trusted certificates for verifying the certificate presented by mongos. The file must contain an X.509 certificate collection in PEM format.

Type: String

Necessity: Optional.

Path to the PEM file that contains the X.509 certificate and private key for authenticating mongot with mongos.

Type: String

Path to the file that contains the password to decrypt the certificate key file specified in syncSource.router.scramAuth.tls.tlsCertificateKeyFile.

Replication Read Preference Settings

Type: Object

Controls the read preference that mongot uses when reading from the replica set for replication.

To filter reads by replica set member tags, specify syncSource.replicationReader.tagSets.

Type: String

Default: secondaryPreferred

Read preference mongot uses for replication operations. You can specify the following values:

primary
primaryPreferred
secondary
secondaryPreferred
nearest

Note:

Index management commands always use primary read preference, regardless of this setting.

Type: Array

Array of tag sets that filter which replica set members receive replication reads. You cannot configure this setting if syncSource.replicationReader.readPreference is primary.

Each element of tagSets is an array of { name: <name>, value: <value> } objects that match replica set member tags. mongot evaluates tag sets in order and uses the first tag set that matches a member. For example:

tagSets:
  - [ { name: hostname, value: mongod1 },
      { name: region, value: us-east-1 } ]

gRPC Server Settings

The [server.grpc.address](https://www.mongodb.com/docs/search/self-managed/current/configuration/reference.md#mongodb-setting-server.grpc.address setting is required. All other server.grpc settings are optional.

Type: Object

TLS (Transport Layer Security) configuration options for the gRPC listen server.

Type: String

TLS (Transport Layer Security) mode for the gRPC server. Must be one of the following values:

“TLS”
“mTLS”
“disabled”

Required when you configure server.grpc.tls.

Type: String

PEM file that contains a valid X.509 certificate for mongot using a PKCS#8 private key. mongod validates this certificate using a Certificate Authority (CA) file that you specify with the --tlsCAFile option. Required when server.grpc.tls.mode is “TLS” or “mTLS”.

Type: String

Path to the file that contains the password to decrypt the certificate key file specified in server.grpc.tls.certificateKeyFile.

Type: String

Certificate Authority (CA) file that contains trusted certificates for verifying the certificate presented by mongod. The file must contain an X.509 certificate collection in PEM format. Required when server.grpc.tls.mode is “mTLS”.

Type: String

User-provided name to identify a mongot instance. MongoDB uses server.name to identify mongot hosts across programmatic interfaces such as [$listSearchIndexes](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSearchIndexes.md#mongodb-pipeline-pipe.-listSearchIndexes. If you omit this setting, MongoDB generates a name automatically.

Metrics Settings

Type: Object

Settings for the mongot Prometheus metrics endpoint listener.

Type: Boolean

Default: false

Flag that enables the Prometheus metrics endpoint. If you set this to false, MongoDB parses and validates the syntax of the other settings in the metrics block but does not start the Prometheus metrics listener. Required when you configure metrics.

Type: String

Default: localhost:9946

Socket address (IPv4 or IPv6) on which the Prometheus /metrics endpoint is exposed. Use the following format:

<host>:<port>

Health Checks Settings

Type: Object

Settings for the mongot health check endpoint. You cannot disable the health check endpoint, but you can configure its listen address.

Type: String

Default: localhost:8080

Address on which the health check listener listens. Use the following format:

<host>:<port>

Logging Settings

Type: Object

Options for logging.

Type: String

Default: INFO

Verbosity of logging. The value must be a valid Logback log level.

Type: String

Path to a file where mongot writes logs using a Logback file appender. If you omit this setting, MongoDB does not create or configure a log file appender.

Automated Embedding Settings

Basic Settings

Configure the following settings to enable Automated Embedding.

Note:

queryKeyFile and indexingKeyFile work as a pair. If you do not configure either file, mongot logs a warning and disables auto-embedding.
providerEndpoint is optional. When set, mongot applies it as an override for the configured embedding service endpoint.
isAutoEmbeddingViewWriter defaults to false if you omit it.

Type: String

URL of the embedding provider endpoint. Optional override for the default embedding provider endpoint. Use this if you want mongot to send embedding requests to a specific provider endpoint instead of the default endpoint.

Type: String

Path to the file that contains the key for the query-time embedding requests. Required for Automated Embedding.

Type: String

Path to the file that contains the key for the index-time embedding requests. Required for Automated Embedding.

Type: Boolean

Flag to designate the leader mongot instance responsible for writing the automated embedding View. If true, this mongot instance acts as the writer for auto-embedding materialized-view updates.

For single-instance deployments, set this to true to enable the instance to write the automated embeddings View.

If you have multiple mongot instances for replica sets or sharded clusters, ensure that only one instance writes the automated embedding View to prevent duplication or conflicts. Set the value to:

true to designate a mongot instance as the leader responsible for writing the auto-embeddings View.
false to designate a mongot instance as a follower that does not write the auto-embeddings View.

Advanced Settings

Type: Integer

Necessity: Optional

Default: 2 times the host's CPU core count

Maximum number of steady-state change streams that the materialized view replication process can have outstanding at any one time. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: The host's CPU core count, with a minimum of 1

Number of threads used to write embedding data into the materialized view's indexes. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: The host's CPU core count, with a minimum of 1

Number of threads used to request embeddings from the embedding provider. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: Half of advancedConfigs.replication.mongodb.numConcurrentInitialSyncs. If the result is less than 1, then it uses 1. If you don not setn advancedConfigs.replication.mongodb.numConcurrentInitialSyncsn also, then it defaults to 1.

Maximum number of Automated Embedding indexes that can run their initial sync at the same time. Limiting concurrency reduces the load placed on the source mongod node and embedding provider during initial builds. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: 4

Maximum number of connections used to write to the materialized view collection. Must be a positive integer no greater than 16.

Type: Integer

Necessity: Optional

Default: No limit

Maximum number of bulk write commits per second to the materialized view collection on this node. Use this setting to limit write throughput to the source mongod node. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: No limit

Maximum number of requests per second this node can send to the embedding provider. This is a node-level limit. Must be a positive integer no greater than 100.

Type: Integer

Necessity: Optional

Default: 3

Maximum number of embedding-provider getMore operations that can be in flight concurrently for the materialized view.

Lower values reduce concurrent provider and memory pressure but can reduce embedding throughput. Higher values can improve throughput but may increase resource usage. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: 2000

Number of documents returned in each embedding-provider getMore batch.

Larger batches can improve throughput by reducing request overhead but might increase memory usage and request latency. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: 700

Maximum time, in milliseconds, that a materialized-view change-stream request can run before it times out.

Lower values can improve responsiveness to stalled operations but might increase request and resume frequency. Higher values can reduce request churn but might delay stall detection. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: 1200

Maximum lifetime, in seconds, of a change-stream cursor used by materialized-view replication.

Higher values can reduce cursor recreation. Lower values can detect long-lived or stalled cursors sooner. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: 3

Number of threads used to decode change-stream events for the materialized view. Higher values can improve event-processing throughput but increase CPU usage. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: 250

Backoff interval, in milliseconds, that mongot applies after embedding requests are rate-limited.

Increasing this value reduces repeated requests and provider pressure during throttling but can increase embedding update latency. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: 80

Percentage of the mongot heap that automated-embedding materialized-view processing can use globally.

Lower values reserve more heap for other mongot operations but can reduce automated-embedding throughput. Higher values can increase throughput but reduce memory available to other operations. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: 40

Percentage of the mongot heap that a single automated-embedding batch can use.

This setting limits the memory impact of an individual batch. Configure it consistently with advancedConfigs.autoEmbedding.materializedView.globalMemoryBudgetHeapPercent. Must be a positive integer.

Advanced Indexing Settings

Type: Integer

Necessity: Optional

Default: 1000

Interval, in milliseconds, that mongot waits before refreshing an index to make recently indexed changes visible to queries. Lower values reduce the delay between writing a document and being able to query it, at the cost of more frequent refresh work. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: 10% of the host's total memory

Memory budget, in megabytes, available to background merges of vector index segments. A larger budget allows more segments to be merged together at once, which can improve query performance but uses more memory during merges. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: The number of CPU cores available to the host

Maximum number of threads that can perform index segment merges concurrently. Higher values allow more merges to run in parallel. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: No limit

Maximum number of indexed fields allowed in an index. Use this setting to guard against unbounded field growth in indexes. Must be at least 3.

Advanced Querying Settings

Type: Integer

Necessity: Optional

Default: 1024

Maximum number of clauses a single query can expand to. mongot rejects queries that expand beyond this limit. Raising this limit allows larger queries but increases their memory and CPU cost. Must be a positive integer.

Type: Double

Necessity: Optional

Default: 64.0

Floor segment size, in megabytes, used by the merge policy for MongoDB Vector Search indexes. mongot merges segments smaller than advancedConfigs.querying.lucene.vectorFloorSegmentMB together more aggressively to reduce the total number of segments and improve query performance. Value must be a positive number.

Advanced Replication Settings

Type: Integer

Necessity: Optional

Default: The lesser of the host's CPU core count and 2

Maximum number of indexes that can run their initial sync at the same time. Limiting concurrency reduces the load placed on the source mongod node while many indexes build simultaneously. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: 2 times the host's CPU core count

Maximum number of steady-state change streams that can have outstanding requests to the source mongod node at any one time. This setting controls how many indexes can pull updates concurrently after their initial sync completes. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: Half the host's CPU core count, with a minimum of 1

Number of threads used to write replicated documents and changes into indexes. Higher values can improve indexing throughput but might increase CPU and memory usage. Value must be a positive integer.

Type: Integer

Necessity: Optional

Default: 2

Maximum number of synonym source collections that can sync concurrently. Must be a positive integer.

Type: Boolean

Necessity: Optional

Default: false

Flag that pauses all new initial-sync operations when set to true. Use this setting to prevent additional index builds from increasing disk or resource usage during recovery or maintenance.

This setting applies across the deployment and does not provide per-host control. To apply a change to this setting, perform a rolling restart of your mongot instances.

Type: Array of Strings

Necessity: Optional

Default: None

Index IDs for which mongot pauses initial sync. Use this setting to defer selected index builds while allowing other indexes to continue synchronizing.

Each value must identify a search index. This setting applies across the deployment rather than to an individual host. To apply a change to this setting, perform a rolling restart of your mongot instances.

Type: Integer

Necessity: Optional

Default: 500

Maximum time, in milliseconds, that mongot allows an individual change-stream request to run before it times out.

Lower values can cause mongot to retry or resume change streams more frequently. Higher values can reduce request churn but may delay detection of stalled operations. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: 900

Maximum lifetime, in seconds, of a replication change-stream cursor.

Adjust this value only when tuning change-stream resource usage or cursor stability. Higher values can reduce cursor recreation. Lower values can detect long-lived or stalled cursors sooner. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: 4

Number of threads mongot uses to decode replication change-stream events. Higher values can improve change-stream processing throughput but increase CPU usage. Must be a positive integer.

Type: Boolean

Necessity: Optional

Default: false

Flag that enables natural-order scans for bufferless initial sync when set to true.

Natural-order scans change how mongot reads documents during initial sync. Evaluate the effect on initial-sync performance and source-node load before you enable this setting in production.

Advanced Disk Monitor Settings

The disk-monitor settings use a fraction of disk capacity. For example, 0.90 represents 90% disk usage. Configure the resume thresholds below their corresponding pause thresholds to prevent repeated pause and resume cycles.

Note:

Changes to these settings take effect only after you restart mongot.

Type: Double

Necessity: Optional

Default: 0.90

Disk-utilization threshold at which mongot pauses replication. Pausing replication prevents additional replicated index data from increasing disk usage while the host is under disk pressure.

Type: Double

Necessity: Optional

Default: 0.85

Disk-utilization threshold below which mongot resumes replication after disk pressure causes replication to pause. Set this value lower than advancedConfigs.diskMonitor.pauseReplicationThreshold.

Type: Double

Necessity: Optional

Default: 0.95

Critical disk-utilization threshold at which mongot crashes to protect the host from disk exhaustion. Set this threshold as a last-resort safety limit above the pause thresholds.

Type: Double

Necessity: Optional

Default: 0.85

Disk-utilization threshold at which mongot pauses initial-sync operations. Use this setting to prevent new index builds from consuming additional disk space when the host is already under disk pressure.

Type: Double

Necessity: Optional

Default: 0.80

Disk-utilization threshold below which mongot resumes initial-sync operations after disk pressure causes them to pause. Set this value lower than advancedConfigs.diskMonitor.pauseInitialSyncThreshold.

Advanced Cursor Settings

Type: Integer

Necessity: Optional

Default: 1800000

Interval, in milliseconds, at which mongot checks for idle cursors. Lower values allow mongot to identify idle cursors sooner but increase cursor-management work. Must be a positive integer.

Type: Integer

Necessity: Optional

Default: 3600000

Duration, in milliseconds, that a cursor can remain idle before mongot treats it as idle. Lower values allow mongot to reclaim cursor resources sooner but may affect clients that intentionally wait between requests. Must be a positive integer.

Advanced FTDC Settings

Type: Boolean

Necessity: Optional

Default: true

Flag that enables full-time diagnostic data capture (FTDC). FTDC diagnostic data collection is enabled by default. When false, mongot creates no FTDC reporter at bootstrap, so it captures no diagnostic data.

Type: Integer

Necessity: Optional

Default: 100

Maximum total size, in megabytes, of the FTDC archive directory. Must be at least 10 and greater than advancedConfigs.ftdc.fileSizeMb.

Type: Integer

Necessity: Optional

Default: 10

Maximum size, in megabytes, of an individual FTDC archive file. Must be at least 1 and less than advancedConfigs.ftdc.directorySizeMb.

Type: Integer

Necessity: Optional

Default: 1000

Sampling interval, in milliseconds, that controls how often mongot collects metrics into FTDC. Must be at least 100.

@mongodb-js/agent-engine-sdk-memory

Configure mongot