analyzeShardKey (database command数据库命令)

Metrics About Shard Key Characteristics关于分片关键特征的指标

keyCharacteristic consists of the metrics about the cardinality, frequency, and monotonicity of the shard key. These metrics are only returned when keyCharacteristics is true.由关于分片键的基数、频率和单调性的度量组成。只有当keyCharacteristics为true时，才会返回这些指标。

The metrics are calculated when analyzeShardKey is run based on documents sampled from the collection. The calculation requires the shard key to have a supporting index. 当analyzeShardKey基于从集合中采样的文档运行时，会计算这些指标。计算需要分片键有一个支持索引。If there is no supporting index, no metrics are returned.如果没有支持索引，则不会返回任何指标。

You can configure sampling with the sampleRate and sampleSize fields. 您可以使用sampleRate和sampleSize字段配置采样。Both are optional, but only one can be specified. 两者都是可选的，但只能指定一个。When both sampleRate and sampleSize are unspecified, MongoDB uses the value of the analyzeShardKeyCharacteristicsDefaultSampleSize parameter, which has a default value of 10 million.当未指定sampleRate和sampleSize时，MongoDB使用analyzeShardKeyCharacteristicsDefaultSampleSize参数的值，该参数的默认值为1000万。

To calculate metrics based on all documents in the collection, set the sampleRate to 1.要基于集合中的所有文档计算度量，请将sampleRate设置为1。

Metrics About the Read and Write Distribution读写分布的度量

readWriteDistribution contains metrics about the query routing patterns and the hotness of shard key ranges. These metrics are based on sampled queries.包含有关查询路由模式和分片键范围热度的指标。这些指标基于抽样查询。

To configure query sampling for a collection, use the configureQueryAnalyzer command. 要为集合配置查询采样，请使用configureQueryAnalyzer命令。The read and write distribution metrics are only returned if readWriteDistribution is true. 只有当readWriteDistribution为true时，才会返回读写分布度量。The metrics are calculated when analyzeShardKey is run and the metrics use the sampled read and write queries. If there are no sampled queries, read and write distribution metrics aren't returned.在运行analyzeShardKey时计算度量，度量使用采样的读写查询。如果没有采样查询，则不会返回读写分布指标。

• If there are no sampled read queries, the command returns writeDistribution but omits readDistribution.如果没有采样读取查询，则该命令返回writeDistribution，但省略readDistribution。
• If there are no sampled write queries, the command returns readDistribution but omits writeDistribution.如果没有采样写查询，则该命令返回readDistribution，但省略writeDistribution。

To return read and write distribution metrics for a collection using analyzeShardKey, you must configure the query analyzer to sample the queries run on the collection. 要使用analyzeShardKey返回集合的读写分布指标，您必须配置查询分析器以对在集合上运行的查询进行采样。Otherwise, analyzeShardKey returns the read and write distribution metrics as 0 values. To configure the query analyzer, see configureQueryAnalyzer (database command).否则，analyzeShardKey将读写分布指标返回为0值。要配置查询分析器，请参阅configureQueryAnalyzer（数据库命令）。

Non-Blocking Behavior非阻塞行为

analyzeShardKey does not block reads or writes to the collection.不会阻止对集合的读取或写入。

Query Sampling查询采样

The quality of the metrics about the read and write distribution is determined by how representative the workload is when query sampling occurs. For some applications, returning representative metrics may require leaving query sampling on for several days.关于读写分布的度量质量取决于查询采样时工作负载的代表性。对于某些应用程序，返回代表性指标可能需要让查询采样持续几天。

Supporting Indexes支持指标

The supporting index required by analyzeShardKey is different from the supporting index required by the shardCollection command.analyzeShardKey所需的支持索引与shardCollection命令所需的支撑索引不同。

This table shows the supporting indexes for the same shard key for both analyzeShardKey and shardCollection:此表显示了analyzeShardKey和shardCollection的同一分片键的支持索引：

This allows you to analyze a shard key that may not yet have a supporting index required for sharding it.这允许您分析可能还没有分片所需的支持索引的分片键。

Both analyzeShardKey and shardCollection have the following index requirements:analyzedShardKey和shardCollection都有以下索引要求：

• Index has a simple collation索引有一个简单的排序规则
• Index is not multi-key索引不是多键
• Index is not sparse索引不是稀疏的
• Index is not partial索引不是部分的

To create supporting indexes, use the db.collection.createIndex() method.要创建支持索引，请使用db.collection.createIndex()方法。

Read Preference读取首选项

To minimize the performance, run analyzeShardKey with the secondary or secondaryPreferred read preference. 为了最大限度地降低性能，请使用secondary或secondaryPreferred读取项运行analyzeShardKey。On a sharded cluster, mongos automatically sets the read preference to secondaryPreferred if not specified.在分片集群上，如果没有指定，mongos会自动将读取首选项设置为secondaryPreferred。

Limitations局限性

• You cannot run analyzeShardKey on Atlas flex clusters.您无法在Atlas flex集群上运行analyzeShardKey。
• You cannot run analyzeShardKey on standalone deployments.您无法在独立部署上运行analyzeShardKey。
• You cannot run analyzeShardKey directly against a --shardsvr replica set. When running on a sharded cluster, analyzeShardKey must run against a mongos.您不能直接对--shardsvr副本集运行analyzeShardKey。在分片集群上运行时，analyzeShardKey必须与mongos运行。
• You cannot run analyzeShardKey against time series collections.您无法对时间序列集合运行analyzeShardKey。
• You cannot run analyzeShardKey against collections with Queryable Encryption.您无法对具有可查询加密的集合运行analyzeShardKey。

keyCharacteristics

This is the structure of the keyCharacteristics document that is returned when keyCharacteristics is set to true:这是当keyCharacteristics设置为true时返回的keyCharacteristics文档的结构：

{
   keyCharacteristics: {
      numDocsTotal: <integer>,
      numOrphanDocs: <integer>,
      avgDocSizeBytes: <integer>,
      numDocsSampled: <integer>,
      isUnique: <bool>,
      numDistinctValues: <integer>,
      mostCommonValues: [
        { value: <shardkeyValue>, frequency: <integer> },
        ...
      ],
      monotonicity: {
        recordIdCorrelationCoefficient: <double>,
        type: "monotonic"|"not monotonic"|"unknown",
    }
  }
}

readWriteDistribution

This is the structure of the document that is returned when readWriteDistribution is set to true:这是当readWriteDistribution设置为true时返回的文档结构：

{
   readDistribution: {
     sampleSize: {
       total: <integer>,
       find: <integer>,
       aggregate: <integer>,
       count: <integer>,
       distinct: <integer>
     },
     percentageOfSingleShardReads: <double>,
     percentageOfMultiShardReads: <double>,
     percentageOfScatterGatherReads: <double>,
     numReadsByRange: [
       <integer>,
       ...
     ]
   },
   writeDistribution: {
     sampleSize: {
       total: <integer>,
       update: <integer>,
       delete: <integer>,
       findAndModify: <integer>
     },
     percentageOfSingleShardWrites: <double>,
     percentageOfMultiShardWrites: <double>,
     percentageOfScatterGatherWrites: <double>,
     numWritesByRange: [
       <integer>,
       ...
     ],
     percentageOfShardKeyUpdates: <double>,
     percentageOfSingleWritesWithoutShardKey: <double>,
     percentageOfMultiWritesWithoutShardKey: <double>
   }
}

To return read and write distribution metrics for a collection using analyzeShardKey, you must configure the query analyzer to sample the queries run on the collection. 要使用analyzeShardKey返回集合的读写分布指标，您必须配置查询分析器以对在集合上运行的查询进行采样。Otherwise, analyzeShardKey returns the read and write distribution metrics as 0 values. 否则，analyzeShardKey将读写分布指标返回为0值。To configure the query analyzer, see configureQueryAnalyzer (database command).要配置查询分析器，请参阅configureQueryAnalyzer（数据库命令）。

Background Information背景信息

• The app has 1500 users.该应用程序有1500名用户。
• There are 30 last names and 45 first names, some more common than others.有30个姓氏和45个名字，有些比其他名字更常见。
• There are three celebrity users.有三位名人用户。
• Each user follows exactly five other users and has a very high probability of following at least one celebrity user.每个用户只关注另外五个用户，并且很有可能关注至少一个名人用户。

Sample Workload示例工作量

• Each user posts about two posts a day at random times. They edit each post once, right after it is posted.每个用户每天随机发布大约两条帖子。他们在每篇帖子发布后立即编辑一次。
• Each user logs in every six hours to read their own profile and posts by the users they follow from the past 24 hours. They also reply under a random post from the past three hours.每个用户每六个小时登录一次，阅读他们自己的个人资料以及他们在过去24小时内关注的用户的帖子。他们还随机回复了过去三个小时的帖子。
• For every user, the app removes posts that are more than three days old at midnight.对于每个用户，该应用程序都会在午夜删除超过三天的帖子。

Workload Query Patterns工作负载查询模式

This workload has the following query patterns:此工作负载具有以下查询模式：

• find command with filter 带筛选器的命令{ userId: , firstName: , lastName: }
• find command with filter 带筛选器的命令{ $or: [{ userId: , firstName: , lastName:, date: { $gte: }, ] }
• findAndModify command with filter { userId: , firstName: , lastName: , date: } to update the body and date field.使用筛选器{ userId: , firstName: , lastName: , date: }的命令更新正文和日期字段。
• update command with multi: false and filter { userId: , firstName: , lastName: , date: { $gte: , $lt: } } to update the body and date field.使用multi:false和筛选器{ userId: , firstName: , lastName: , date: { $gte: , $lt: } }的update命令来更新正文和日期字段。
• delete command with multi: true and filter { userId: , firstName: , lastName: , date: { $lt: } }带multi:true和筛选器{ userId: , firstName: , lastName: , date: { $lt: } }的delete命令

Below are example metrics returned by analyzeShardKey command for some candidate shard keys, with sampled queries collected from seven days of workload.下面是analyzeShardKey命令返回的一些候选分片键的示例指标，其中包含从七天的工作负载中集合的采样查询。

{ _id: 1 } keyCharacteristics

This example uses the analyzeShardKey command to provide metrics on the { _id: 1 } shard key on the social.post collection.此示例使用analyzeShardKey命令提供social.post集合上{ _id: 1 }分片键的度量。

The following code block uses db.collection.configureQueryAnalyzer() to turn on query sampling:以下代码块使用db.collection.configureQueryAnalyzer()打开查询采样：

use social
db.post.configureQueryAnalyzer(
   {
      mode: "full",
      samplesPerSecond: 5
   }
)

After db.collection.configureQueryAnalyzer() collects query samples, the following code block uses the analyzeShardKey command to sample 10,000 documents and calculate results:db.collection.configureQueryAnalyzer()集合查询样本后，以下代码块使用analyzeShardKey命令对10000个文档进行采样并计算结果：

use social
db.post.analyzeShardKey(
   { _id: 1 },
   {
      keyCharacteristics: true,
      readWriteDistribution: false,
      sampleSize: 10000
   }
)

{ lastName: 1 } keyCharacteristics

This analyzeShardKey command provides metrics on the { lastName: 1 } shard key on the social.post collection:此analyzeShardKey命令提供social.post集合上{ lastName: 1 }分片键的度量：

use social
db.post.analyzeShardKey(
   { lastName: 1 },
   {
      keyCharacteristics: true,
      readWriteDistribution: false
   }
)

The output for this example resembles the following:此示例的输出类似于以下内容：

{
   "keyCharacteristics": {
     "numDocsTotal" : 9039,
     "avgDocSizeBytes" : 153,
     "numDocsSampled" : 9039,
     "isUnique" : false,
     "numDistinctValues" : 30,
     "mostCommonValues" : [
         {
           "value" : {
               "lastName" : "Smith"
           },
           "frequency" : 1013
         },
         {
           "value" : {
               "lastName" : "Johnson"
           },
           "frequency" : 984
         },
         {
           "value" : {
               "lastName" : "Jones"
           },
           "frequency" : 962
         },
         {
           "value" : {
               "lastName" : "Brown"
           },
           "frequency" : 925
         },
         {
           "value" : {
               "lastName" : "Davies"
           },
           "frequency" : 852
         }
     ],
     "monotonicity" : {
       "recordIdCorrelationCoefficient" : 0.0771959161,
       "type" : "not monotonic"
   },
 }
}

{ userId: 1 } keyCharacteristics

This analyzeShardKey command provides metrics on the { userId: 1 } shard key on the social.post collection:此analyzeShardKey命令提供social.post集合上{ userId: 1 }分片键的度量：

use social
db.post.analyzeShardKey(
   { userId: 1 },
   {
      keyCharacteristics: true,
      readWriteDistribution: false
   }
)

The output for this example resembles the following:此示例的输出类似于以下内容：

{
  "keyCharacteristics": {
    "numDocsTotal" : 9039,
    "avgDocSizeBytes" : 162,
    "numDocsSampled" : 9039,
    "isUnique" : false,
    "numDistinctValues" : 1495,
    "mostCommonValues" : [
      {
        "value" : {
          "userId" : UUID("aadc3943-9402-4072-aae6-ad551359c596")
        },
        "frequency" : 15
      },
     {
       "value" : {
         "userId" : UUID("681abd2b-7a27-490c-b712-e544346f8d07")
       },
       "frequency" : 14
     },
     {
       "value" : {
         "userId" : UUID("714cb722-aa27-420a-8d63-0d5db962390d")
       },
       "frequency" : 14
     },
     {
       "value" : {
         "userId" : UUID("019a4118-b0d3-41d5-9c0a-764338b7e9d1")
       },
       "frequency" : 14
     },
     {
       "value" : {
         "userId" : UUID("b9c9fbea-3c12-41aa-bc69-eb316047a790")
       },
       "frequency" : 14
     }
   ],
   "monotonicity" : {
     "recordIdCorrelationCoefficient" : -0.0032039729,
     "type" : "not monotonic"
   },
 }
}

{ userId: 1 } readWriteDistribution

This analyzeShardKey command provides metrics on the { userId: 1 } shard key on the social.post collection:此analyzeShardKey命令提供social.post集合上{ userId: 1 }分片键的度量：

use social
db.post.analyzeShardKey(
   { userId: 1 },
   {
      keyCharacteristics: false,
      readWriteDistribution: true
   }
)

The output for this example resembles the following:此示例的输出类似于以下内容：

{
   "readDistribution" : {
     "sampleSize" : {
       "total" : 61363,
       "find" : 61363,
       "aggregate" : 0,
       "count" : 0,
       "distinct" : 0
     },
     "percentageOfSingleShardReads" : 50.0008148233,
     "percentageOfMultiShardReads" : 49.9991851768,
     "percentageOfScatterGatherReads" : 0,
     "numReadsByRange" : [
       688,
       775,
       737,
       776,
       652,
       671,
       1332,
       1407,
       535,
       428,
       985,
       573,
       1496,
       ...
       ],
     },
   "writeDistribution" : {
     "sampleSize" : {
       "total" : 49638,
       "update" : 30680,
       "delete" : 7500,
       "findAndModify" : 11458
     },
     "percentageOfSingleShardWrites" : 100,
     "percentageOfMultiShardWrites" : 0,
     "percentageOfScatterGatherWrites" : 0,
     "numWritesByRange" : [
       389,
       601,
       430,
       454,
       462,
       421,
       668,
       833,
       493,
       300,
       683,
       460,
       ...
      ],
      "percentageOfShardKeyUpdates" : 0,
      "percentageOfSingleWritesWithoutShardKey" : 0,
      "percentageOfMultiWritesWithoutShardKey" : 0
    }
}