query_knobs.idl

# Copyright (C) 2019-present MongoDB, Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the Server Side Public License, version 1,
# as published by MongoDB, Inc.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# Server Side Public License for more details.
#
# You should have received a copy of the Server Side Public License
# along with this program. If not, see
# <http://www.mongodb.com/licensing/server-side-public-license>.
#
# As a special exception, the copyright holders give permission to link the
# code of portions of this program with the OpenSSL library under certain
# conditions as described in each individual source file and distribute
# linked combinations including the program with the OpenSSL library. You
# must comply with the Server Side Public License in all respects for
# all of the code used other than as permitted herein. If you modify file(s)
# with this exception, you may extend this exception to your version of the
# file(s), but you are not obligated to do so. If you do not wish to do so,
# delete this exception statement from your version. If you delete this
# exception statement from all source files in the program, then also delete
# it in the license file.
#

global:
  cpp_namespace: "mongo"
  cpp_includes:
    - "mongo/db/query/plan_cache_size_parameter.h"
    - "mongo/platform/atomic_proxy.h"
    - "mongo/platform/atomic_word.h"

server_parameters:

  #
  # multi-plan ranking
  #
  internalQueryPlanEvaluationWorks:
    description: "Max number of times we call work() on plans before comparing them, for small collections."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryPlanEvaluationWorks"
    cpp_vartype: AtomicWord<int>
    default: 10000
    validator:
      gt: 0

  internalQueryPlanEvaluationCollFraction:
    description: "For large collections, the number times we work() candidate plans is taken as this fraction of the collection size."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryPlanEvaluationCollFraction"
    cpp_vartype: AtomicDouble
    default: 0.3
    validator:
      gte: 0.0
      lte: 1.0

  internalQueryPlanEvaluationMaxResults:
    description: "Stop working plans once a plan returns this many results."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryPlanEvaluationMaxResults"
    cpp_vartype: AtomicWord<int>
    default: 101
    validator:
      gte: 0

  internalQueryForceIntersectionPlans:
    description: "Do we give a big ranking bonus to intersection plans?"
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryForceIntersectionPlans"
    cpp_vartype: AtomicWord<bool>
    default: false

  internalQueryPlannerEnableIndexIntersection:
    description: "Do we have ixisect on at all?"
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryPlannerEnableIndexIntersection"
    cpp_vartype: AtomicWord<bool>
    default: true

  internalQueryPlannerEnableHashIntersection:
    description: "Do we use hash-based intersection for rooted $and queries?"
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryPlannerEnableHashIntersection"
    cpp_vartype: AtomicWord<bool>
    default: false

  #
  # Plan cache
  #

  internalQueryCacheMaxEntriesPerCollection:
    description: "The maximum number of entries allowed in a given collection's plan cache."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryCacheMaxEntriesPerCollection"
    cpp_vartype: AtomicWord<int>
    deprecated_name: "internalQueryCacheSize"
    default: 5000
    validator:
      gte: 0

  internalQueryCacheMaxSizeBytesBeforeStripDebugInfo:
    description: "Limits the amount of debug info stored across all plan caches in the system. Once
    the estimate of the number of bytes used across all plan caches exceeds this threshold, then
    debug info is not stored alongside new cache entries, in order to limit plan cache memory
    consumption. If plan cache entries are freed and the estimate once again dips below this
    threshold, then new cache entries will once again have debug info associated with them."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryCacheMaxSizeBytesBeforeStripDebugInfo"
    cpp_vartype: AtomicWord<long long>
    default:
      expr: 512 * 1024 * 1024
    validator:
      gte: 0

  internalQueryCacheEvictionRatio:
    description: "How many times more works must we perform in order to justify plan cache eviction and replanning?"
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryCacheEvictionRatio"
    cpp_vartype: AtomicDouble
    default: 10.0
    validator:
      gte: 0.0

  internalQueryCacheWorksGrowthCoefficient:
    description: "How quickly the the 'works' value in an inactive cache entry will grow. It grows exponentially. The value of this server parameter is the base."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryCacheWorksGrowthCoefficient"
    cpp_vartype: AtomicDouble
    default: 2.0
    validator:
      gt: 1.0

  internalQueryCacheDisableInactiveEntries:
    description: "Whether or not cache entries can be marked as 'inactive'."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryCacheDisableInactiveEntries"
    cpp_vartype: AtomicWord<bool>
    default: false

  planCacheSize:
    description: "The maximum amount of memory that the system will allocate for the plan cache.
      It takes value value in one of the two formats:
      1. <number>% indicates a percentage of the physical memory available to the process. E.g.: 15%.
      2. <number>(MB|GB), indicates the amount of memory in MB or GB. E.g.: 1.5GB, 100MB.
      The defualt value is 5% which means 5% of the physical memory available to the process."
    set_at: [ startup, runtime ]
    cpp_varname: "planCacheSize"
    cpp_vartype: synchronized_value<std::string>
    default: "5%"
    on_update: plan_cache_util::onPlanCacheSizeUpdate
    validator:
      callback: plan_cache_util::validatePlanCacheSize

  #
  # Parsing
  #

  internalPipelineLengthLimit:
    description: "The maximum length allowed for an an aggregation pipeline."
    set_at: [ startup ]
    cpp_varname: "internalPipelineLengthLimit"
    cpp_vartype: int
    default:
      expr: 'kDebugBuild ? 200 : 1000'
    validator:
      gt: 0

  internalMaxSubPipelineViewDepth:
    description: "The maximum length allowed for an an aggregation sub-pipeline view."
    set_at: [ startup, runtime ]
    cpp_varname: "internalMaxSubPipelineViewDepth"
    cpp_vartype: AtomicWord<long long>
    default: 20
    test_only: true
    validator:
      gt: 0

  internalPartialFilterExpressionMaxDepth:
    description: "The maximum depth allowed for a partialFilterExpression."
    set_at: [ startup, runtime ]
    cpp_varname: "internalPartialFilterExpressionMaxDepth"
    cpp_vartype: AtomicWord<long long>
    default: 4
    validator:
      gt: 0

  #
  # Planning and enumeration
  #
  internalQueryPlannerMaxIndexedSolutions:
    description: "How many indexed solutions will QueryPlanner::plan output?"
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryPlannerMaxIndexedSolutions"
    cpp_vartype: AtomicWord<int>
    default: 64
    validator:
      gte: 0

  internalQueryEnumerationPreferLockstepOrEnumeration:
    description: "If set to true, instructs the plan enumerator to enumerate contained $ors in a
    special order. $or enumeration can generate an exponential number of plans, and is therefore
    limited at some arbitrary cutoff controlled by a parameter. When this limit is hit, the order of
    enumeration is important. For example, a query like the following has a 'contained $or' (within
    an $and): {a: 1, $or: [{b: 1, c: 1}, {b: 2, c: 2}]} For this query if there are indexes
    a_b={a: 1, b: 1} and a_c={a: 1, c: 1}, the normal enumeration order would output assignments
    [a_b, a_b], [a_c, a_b], [a_b, a_c], then [a_c, a_c]. This flag will instruct the enumerator to
    instead prefer a different order. It's hard to summarize, but perhaps the phrases 'lockstep
    enumeration', 'simultaneous advancement', or 'parallel iteration' will help the reader. The
    effect is to give earlier enumeration to plans which use the same choice across all branches. In
    this order, we would get assignments [a_b, a_b], [a_c, a_c], [a_c, a_b], then [a_b, a_c]. This
    is thought to be helpful in general, but particularly in cases where all children of the $or use
    the same fields and have the same indexes available, as in this example."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryEnumerationPreferLockstepOrEnumeration"
    cpp_vartype: AtomicWord<bool>
    default: false

  internalQueryEnumerationMaxOrSolutions:
    description: "How many solutions will the enumerator consider at each OR?"
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryEnumerationMaxOrSolutions"
    cpp_vartype: AtomicWord<int>
    default: 10
    validator:
      gte: 0

  internalQueryEnumerationMaxIntersectPerAnd:
    description: "How many intersections will the enumerator consider at each AND?"
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryEnumerationMaxIntersectPerAnd"
    cpp_vartype: AtomicWord<int>
    default: 3
    validator:
      gte: 0

  internalQueryPlanOrChildrenIndependently:
    description: "Do we want to plan each child of the OR independently?"
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryPlanOrChildrenIndependently"
    cpp_vartype: AtomicWord<bool>
    default: true

  internalQueryMaxScansToExplode:
    description: "How many index scans are we willing to produce in order to obtain a sort order during explodeForSort?"
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryMaxScansToExplode"
    cpp_vartype: AtomicWord<int>
    default: 200
    validator:
      gte: 0

  internalQueryPlannerGenerateCoveredWholeIndexScans:
    description: "Allow the planner to generate covered whole index scans, rather than falling back to a COLLSCAN."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryPlannerGenerateCoveredWholeIndexScans"
    cpp_vartype: AtomicWord<bool>
    default: false

  internalQueryIgnoreUnknownJSONSchemaKeywords:
    description: "Ignore unknown JSON Schema keywords."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryIgnoreUnknownJSONSchemaKeywords"
    cpp_vartype: AtomicWord<bool>
    default: false

  #
  # Query execution
  #
  internalQueryMaxBlockingSortMemoryUsageBytes:
    description: "The maximum amount of memory a query (e.g. a find or aggregate command) is willing
    to use to execute a blocking sort, measured in bytes. If disk use is allowed, then it may be
    possible to sort more data, but this limit will still constrain the memory consumption."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryMaxBlockingSortMemoryUsageBytes"
    cpp_vartype: AtomicWord<int>
    default:
      expr: 100 * 1024 * 1024
    validator:
      gte: 0

  internalQueryExecYieldIterations:
    description: "Yield after this many \"should yield?\" checks."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryExecYieldIterations"
    cpp_vartype: AtomicWord<int>
    default: 1000

  internalQueryExecYieldPeriodMS:
    description: "Yield if it's been at least this many milliseconds since we last yielded."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryExecYieldPeriodMS"
    cpp_vartype: AtomicWord<int>
    default: 10
    validator:
      gte: 0

  internalQueryFacetBufferSizeBytes:
    description: "The number of bytes to buffer at once during a $facet stage."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryFacetBufferSizeBytes"
    cpp_vartype: AtomicWord<int>
    default:
      expr: 100 * 1024 * 1024
    validator:
      gt: 0

  internalQueryFacetMaxOutputDocSizeBytes:
    description: "The number of bytes to buffer at once during a $facet stage."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryFacetMaxOutputDocSizeBytes"
    cpp_vartype: AtomicWord<long long>
    default:
      expr: 100 * 1024 * 1024
    validator:
      gt: 0

  internalLookupStageIntermediateDocumentMaxSizeBytes:
    description: "Maximum size of the result set that we cache from the foreign collection during a $lookup."
    set_at: [ startup, runtime ]
    cpp_varname: "internalLookupStageIntermediateDocumentMaxSizeBytes"
    cpp_vartype: AtomicWord<long long>
    default:
      expr: 100 * 1024 * 1024
    validator:
      gte: { expr: BSONObjMaxInternalSize}

  internalDocumentSourceGroupMaxMemoryBytes:
    description: "Maximum size of the data that the $group aggregation stage will cache in-memory before spilling to disk."
    set_at: [ startup, runtime ]
    cpp_varname: "internalDocumentSourceGroupMaxMemoryBytes"
    cpp_vartype: AtomicWord<long long>
    default:
      expr: 100 * 1024 * 1024
    validator:
      gt: 0

  internalDocumentSourceSetWindowFieldsMaxMemoryBytes:
    description: "Maximum size of the data that the $setWindowFields aggregation stage will cache in-memory before throwing an error."
    set_at: [ startup, runtime ]
    cpp_varname: "internalDocumentSourceSetWindowFieldsMaxMemoryBytes"
    cpp_vartype: AtomicWord<long long>
    default:
      expr: 100 * 1024 * 1024
    validator:
      gt: 0

  internalInsertMaxBatchSize:
    description: "Maximum number of documents that we will insert in a single batch."
    set_at: [ startup, runtime ]
    cpp_varname: "internalInsertMaxBatchSize"
    cpp_vartype: AtomicWord<int>
    default:
      expr: internalQueryExecYieldIterations.load() / 2
      is_constexpr: false
    validator:
      gt: 0

  internalDocumentSourceCursorBatchSizeBytes:
    description: "Maximum amount of data that DocumentSourceCursor will cache from the underlying PlanExecutor before pipeline processing."
    set_at: [ startup, runtime ]
    cpp_varname: "internalDocumentSourceCursorBatchSizeBytes"
    cpp_vartype: AtomicWord<int>
    default:
      expr: 4 * 1024 * 1024
    validator:
      gte: 0

  internalDocumentSourceLookupCacheSizeBytes:
    description: "Maximum amount of non-correlated foreign-collection data that the $lookup stage will cache before abandoning the cache and executing the full pipeline on each iteration."
    set_at: [ startup, runtime ]
    cpp_varname: "internalDocumentSourceLookupCacheSizeBytes"
    cpp_vartype: AtomicWord<int>
    default:
      expr: 100 * 1024 * 1024
    validator:
      gte: 0

  internalQueryProhibitBlockingMergeOnMongoS:
    description: "If true, blocking stages such as $group or non-merging $sort will be prohibited from running on mongoS."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryProhibitBlockingMergeOnMongoS"
    cpp_vartype: AtomicWord<bool>
    default: false

  internalQueryMaxJsEmitBytes:
    description: "Limits the vector of values emitted from a single document's call to JsEmit to the
        given size in bytes."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryMaxJsEmitBytes"
    cpp_vartype: AtomicWord<int>
    default:
      expr: 100 * 1024 * 1024
    validator:
        gt: 0

  internalQueryMaxPushBytes:
    description: "Limits the vector of values pushed into a single array while grouping with the
        $push accumulator."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryMaxPushBytes"
    cpp_vartype: AtomicWord<int>
    default:
      expr: 100 * 1024 * 1024
    validator:
        gt: 0

  internalQueryMaxRangeBytes:
    description: "Limits the vector of values pushed into a single array while generating $range
        result."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryMaxRangeBytes"
    cpp_vartype: AtomicWord<int>
    default:
      expr: 100 * 1024 * 1024
    validator:
        gt: 0

  internalQueryMaxAddToSetBytes:
    description: "Limits the vector of values pushed into a single array while grouping with the
        $addToSet accumulator."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryMaxAddToSetBytes"
    cpp_vartype: AtomicWord<int>
    default:
      expr: 100 * 1024 * 1024
    validator:
        gt: 0

  internalQueryJavaScriptHeapSizeLimitMB:
    description: "Limits the JavaScript heap size used in aggregation. Will defer to the global 'jsHeapLimitMB' limit if the global limit is smaller."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryJavaScriptHeapSizeLimitMB"
    cpp_vartype: AtomicWord<int>
    default:
      expr: 100

  internalQueryJavaScriptFnTimeoutMillis:
    description: "Limits the maximum allowed time a user-defined javascript function can run in a query."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryJavaScriptFnTimeoutMillis"
    cpp_vartype: AtomicWord<int>
    default:
      expr: 60 * 1000
    validator:
        gt: 0

  internalQueryDesugarWhereToFunction:
    description: "When true, desugars $where to $expr/$function."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryDesugarWhereToFunction"
    cpp_vartype: AtomicWord<bool>
    default: false

  internalQueryDefaultDOP:
    description: "Default degree of parallelism. This an internal experimental parameter and should not be changed on live systems."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryDefaultDOP"
    cpp_vartype: AtomicWord<int>
    default: 1
    test_only: true
    validator:
      gt: 0

  internalQueryEnableLoggingV2OplogEntries:
    description: "If true, this node may log $v:2 delta-style oplog entries."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryEnableLoggingV2OplogEntries"
    cpp_vartype: AtomicWord<bool>
    default: true

  internalQuerySlotBasedExecutionMaxStaticIndexScanIntervals:
    description: "Limits the number of statically known intervals that SBE can decompose index bounds into when possible."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQuerySlotBasedExecutionMaxStaticIndexScanIntervals"
    cpp_vartype: AtomicWord<int>
    default:
      expr: 1000
    validator:
        gt: 0

  internalQueryEnableCSTParser:
    description: "If true, use the grammar-based parser and CST to parse queries."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryEnableCSTParser"
    cpp_vartype: AtomicWord<bool>
    default: false

  internalQueryMaxDocValidationErrorConsideredValues:
    description: "Limits the number of values reported in the 'consideredValues' array when
    generating a descriptive document validation error."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryMaxDocValidationErrorConsideredValues"
    cpp_vartype: AtomicWord<int>
    default:
        expr: 10
    validator:
        gt: 0

  internalQueryExplainSizeThresholdBytes:
    description: "Number of bytes after which explain should start truncating portions of its
    output."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryExplainSizeThresholdBytes"
    cpp_vartype: AtomicWord<int>
    default:
      expr: 10 * 1024 * 1024
    validator:
        gt: 0
        lte: { expr: BSONObjMaxInternalSize }

  internalQuerySlotBasedExecutionHashAggMemoryUseCheckMargin:
    description: "The memory check in HashAgg stage is done on every T'th processed record, where T
    is calculated adaptively based on the estimated memory used and its recent growth. This setting
    defines the percent of the remaining available memory to be used before the next check, given
    the estimated growth speed per advance [see internalQuerySlotBasedExecutionHashAggApproxMemoryUseInBytesBeforeSpill]."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQuerySBEAggMemoryUseCheckMargin"
    cpp_vartype: AtomicDouble
    default:
      expr: 0.7
    validator:
        gt: 0.0
        lte: 1.0

  internalQuerySlotBasedExecutionHashAggMemoryCheckPerAdvanceAtMost:
    description: "The memory check in HashAgg stage is done on every T'th processed record, where T
    is calculated adaptively based on the estimated memory used and its recent growth. This setting
    defines the lower bound for T [see internalQuerySlotBasedExecutionHashAggApproxMemoryUseInBytesBeforeSpill]."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQuerySBEAggMemoryCheckPerAdvanceAtMost"
    cpp_vartype: AtomicWord<long long>
    default:
      expr: 2
    validator:
        gt: 0

  internalQuerySlotBasedExecutionHashAggMemoryCheckPerAdvanceAtLeast:
    description: "The memory check in HashAgg stage is done on every T'th processed record, where T
    is calculated adaptively based on the estimated memory used and its recent growth. This setting
    defines the upper bound for T. If this setting is less than [see internalQuerySlotBasedExecutionHashAggMemoryCheckPerAdvanceAtMost],
    the check will be done on every internalQuerySlotBasedExecutionHashAggMemoryCheckPerAdvanceAtLeast'th
    processed record [see internalQuerySlotBasedExecutionHashAggApproxMemoryUseInBytesBeforeSpill]."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQuerySBEAggMemoryCheckPerAdvanceAtLeast"
    cpp_vartype: AtomicWord<long long>
    default:
      expr: 1024
    validator:
        gt: 0

  internalQuerySlotBasedExecutionHashAggApproxMemoryUseInBytesBeforeSpill:
    description: "The max size in bytes that the hash table in a HashAgg stage can be
    estimated to be before we spill to disk."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQuerySBEAggApproxMemoryUseInBytesBeforeSpill"
    cpp_vartype: AtomicWord<long long>
    default:
      expr: 100 * 1024 * 1024
    validator:
        gt: 0

  internalQueryForceClassicEngine:
    description: "If true, the system will use the classic execution engine for all queries,
    otherwise eligible queries will execute using the SBE execution engine."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryForceClassicEngine"
    cpp_vartype: AtomicWord<bool>
    default: false

  internalQueryAppendIdToSetWindowFieldsSort:
    description: "If true, appends _id to the sort stage generated by desugaring $setWindowFields to ensure deterministic sort order."
    set_at: [startup, runtime]
    cpp_varname: "internalQueryAppendIdToSetWindowFieldsSort"
    cpp_vartype: AtomicWord<bool>
    default: false

  internalQueryTopNAccumulatorBytes:
    description: "Limits the vector of values pushed into a single array while grouping with the 'N' family of accumulators."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryTopNAccumulatorBytes"
    cpp_vartype: AtomicWord<int>
    default:
        expr: 100 * 1024 * 1024
    validator:
        gt: 0

  enableSearchMeta:
    description: "Exists for backwards compatibility in startup parameters,
      enabling this was required on 4.4 to access SEARCH_META variables. Does not do anything."
    set_at: [ startup, runtime ]
    cpp_varname: "enableSearchMeta"
    cpp_vartype: AtomicWord<bool>
    default: true

  enableTimeoutOfInactiveSessionCursors:
    description: "If true, cursors opened within sessions are eligible for inactive cursor timeout."
    set_at: [ startup, runtime ]
    cpp_varname: "enableTimeoutOfInactiveSessionCursors"
    cpp_vartype: AtomicWord<bool>
    default: false

  internalQueryMaxAllowedDensifyDocs:
    description: "Limits the number of documents that $densify is allowed to generate."
    set_at: [ startup, runtime ]
    cpp_varname: "internalQueryMaxAllowedDensifyDocs"
    cpp_vartype: AtomicWord<int>
    default:  500000
    validator:
        gt: 0

  internalDocumentSourceDensifyMaxMemoryBytes:
    description: "Limits the number of bytes densification can use to store partition information."
    set_at: [ startup, runtime ]
    cpp_varname: "internalDocumentSourceDensifyMaxMemoryBytes"
    cpp_vartype: AtomicWord<int>
    default:
        expr: 100 * 1024 * 1024
    validator:
        gt: 0