path: root/src/mongo/s/analyze_shard_key_cmd.idl

# Copyright (C) 2022-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::analyze_shard_key"
  cpp_includes:
    - "mongo/client/read_preference.h"
    - "mongo/s/analyze_shard_key_util.h"

imports:
  - "mongo/client/read_preference_setting.idl"
  - "mongo/db/basic_types.idl"
  - "mongo/db/keypattern.idl"

enums:
  MonotonicityType:
    description: "The monotonicity type of a shard key."
    type: string
    values:
      kMonotonic: "monotonic"
      kNotMonotonic: "not monotonic"
      kUnknown: "unknown"

structs:
  ValueFrequencyMetrics:
    description: "The value and frequency of a shard key value."
    strict: false
    fields:
      value:
        type: object_owned
      frequency:
        type: long
        validator: { gt: 0 }

  MonotonicityMetrics:
    description: "The metrics about the monotonicity of a shard key, i.e. whether its value is
                  monotonically changing in insertion order."
    strict: false
    fields:
      recordIdCorrelationCoefficient:
        type: double
        description: "The RecordId correlation coefficient calculated by the monotonicity check.
                      This is only set if the monotonicity check occurred, i.e. if the shard key
                      has a supporting index and the collection is not clustered."
        validator:
          gte: -1
          lte: 1
        optional: true
      type:
        type: MonotonicityType
        description: "The monotonicity type."

  KeyCharacteristicsMetrics:
    description: "The metrics about the characteristics of a shard key."
    strict: false
    fields:
      numDocs:
        type: long
        description: "The number of the documents in the collection."
        validator: { gte: 0 }
        optional: true
      isUnique:
        type: bool
        description: "Whether the shard key index enforces a uniqueness constraint."
        optional: true
      numDistinctValues:
        type: long
        description: "The number of distinct shard key values in the collection."
        validator: { gte: 0 }
        optional: true
      mostCommonValues:
        type: array<ValueFrequencyMetrics>
        description: "The value and frequency of the most common shard key values."
        optional: true
      monotonicity:
        type: MonotonicityMetrics
        description: "The monotonicity metrics for the shard key."
        optional: true
      avgDocSizeBytes:
        type: long
        description: "The average document size in bytes."
        validator: { gte: 0 }
        optional: true
      numOrphanDocs:
        type: long
        description: "The number of the orphan documents in the collection."
        validator: { gte: 0 }
        optional: true

  ReadSampleSize:
    description: "The number of sampled read queries by command name."
    strict: false
    fields:
      total:
        type: long
        validator: { gte: 0 }
        default: 0
      find:
        type: long
        validator: { gte: 0 }
        default: 0
      aggregate:
        type: long
        validator: { gte: 0 }
        default: 0
      count:
        type: long
        validator: { gte: 0 }
        default: 0
      distinct:
        type: long
        validator: { gte: 0 }
        default: 0

  WriteSampleSize:
    description: "The number of sampled write queries by command name."
    strict: false
    fields:
      total:
        type: long
        validator: { gte: 0 }
        default: 0
      update:
        type: long
        validator: { gte: 0 }
        default: 0
      delete:
        type: long
        validator: { gte: 0 }
        default: 0
      findAndModify:
        type: long
        validator: { gte: 0 }
        default: 0

  ReadDistributionMetrics:
    description: "The metrics about the read distribution calculated using sampled read queries."
    strict: false
    fields:
      sampleSize:
        type: ReadSampleSize
      numSingleShardReads:
        type: long
        cpp_name: numSingleShard
        validator: { gte: 0 }
        optional: true
      percentageOfSingleShardReads:
        type: double
        cpp_name: percentageOfSingleShard
        validator:
          gte: 0
          lte: 100
        optional: true
      numMultiShardReads:
        type: long
        cpp_name: numMultiShard
        validator: { gte: 0 }
        optional: true
      percentageOfMultiShardReads:
        type: double
        cpp_name: percentageOfMultiShard
        validator:
          gte: 0
          lte: 100
        optional: true
      numScatterGatherReads:
        type: long
        cpp_name: numScatterGather
        validator: { gte: 0 }
        optional: true
      percentageOfScatterGatherReads:
        type: double
        cpp_name: percentageOfScatterGather
        validator:
          gte: 0
          lte: 100
        optional: true
      numReadsByRange:
        type: array<long>
        cpp_name: numByRange
        description: "The number of dispatched read requests for each chunk range sorted from
                      MinKey to MaxKey."
        optional: true

  WriteDistributionMetrics:
    description: "The metrics about the write distribution calculated using sampled write queries."
    strict: false
    fields:
      sampleSize:
        type: WriteSampleSize
      numSingleShardWrites:
        type: long
        cpp_name: numSingleShard
        validator: { gte: 0 }
        optional: true
      percentageOfSingleShardWrites:
        type: double
        cpp_name: percentageOfSingleShard
        validator:
          gte: 0
          lte: 100
        optional: true
      numMultiShardWrites:
        type: long
        cpp_name: numMultiShard
        validator: { gte: 0 }
        optional: true
      percentageOfMultiShardWrites:
        type: double
        cpp_name: percentageOfMultiShard
        validator:
          gte: 0
          lte: 100
        optional: true
      numScatterGatherWrites:
        type: long
        cpp_name: numScatterGather
        validator: { gte: 0 }
        optional: true
      percentageOfScatterGatherWrites:
        type: double
        cpp_name: percentageOfScatterGather
        validator:
          gte: 0
          lte: 100
        optional: true
      numWritesByRange:
        type: array<long>
        cpp_name: numByRange
        description: "The number of dispatched write requests for each chunk range sorted from
                      MinKey to MaxKey."
        optional: true
      numShardKeyUpdates:
        type: long
        validator: { gte: 0 }
        optional: true
      percentageOfShardKeyUpdates:
        type: double
        validator:
          gte: 0
          lte: 100
        optional: true
      numSingleWritesWithoutShardKey:
        type: long
        validator: { gte: 0 }
        optional: true
      percentageOfSingleWritesWithoutShardKey:
        type: double
        validator:
          gte: 0
          lte: 100
        optional: true
      numMultiWritesWithoutShardKey:
        type: long
        validator: { gte: 0 }
        optional: true
      percentageOfMultiWritesWithoutShardKey:
        type: double
        validator:
          gte: 0
          lte: 100
        optional: true

  analyzeShardKeyResponse:
    description: "The response for the 'analyzeShardKey' command."
    strict: false
    inline_chained_structs: true
    chained_structs:
      KeyCharacteristicsMetrics: keyCharacteristics
    fields:
      readDistribution:
        type: ReadDistributionMetrics
        optional: true
      writeDistribution:
        type: WriteDistributionMetrics
        optional: true
      note:
        description: "The note about how to interpret the metrics."
        type: string
        optional: true

commands:
  analyzeShardKey:
    description: "The command for calculating metrics for evaluating a shard key for a collection."
    command_name: analyzeShardKey
    strict: false
    namespace: type
    api_version: ""
    type: namespacestring
    fields:
      key:
        type: KeyPattern
        description: "The shard key to evaluate."
        validator:
          callback: validateShardKeyPattern
      $readPreference:
        type: readPreference
        cpp_name: readPreference
        description: >-
            The read preference to use for metrics calculation. The default is set to
            "secondaryPreferred" to minimize the impact on user workloads.
        default: ReadPreferenceSetting{ReadPreference::SecondaryPreferred}