refineCollectionShardKey

On this page本页内容

Definition定义

refineCollectionShardKey

New in version 4.4.版本4.4中的新功能。

Modifies the collection’s shard key by adding new field(s) as a suffix to the existing key. Refining a collection’s shard key can address situations where the existing key has led to jumbo (i.e. indivisible) chunks due to insufficient cardinality.

Data Distribution

As part of refining the shard key, the refineCollectionShardKey command updates the chunk ranges and zone ranges to incorporate the new fields without modifying the range values of the existing key fields. That is, the refinement of the shard key does not immediately affect the distribution of chunks across shards or zones. Any future chunk splits or migration occur as part of the routine sharding operations.

Syntax语法

Note

To use the refineCollectionShardKey command, the sharded cluster must have feature compatibility version (fcv) of 4.4.

The refineCollectionShardKey command must be run against the admin database and has the following form:

db.adminCommand( {
   refineCollectionShardKey: "<database>.<collection>",
   key: { <existing key specification>, <suffix1>: <1|"hashed">, ... }
} )

Command Fields

The refineCollectionShardKey command has the following fields:

Field字段Type类型Description描述
refineCollectionShardKey string

The namespace of the sharded collection in the form "<database>.<collection>".

key document

The document that specifies the field or fields to use as the new shard key for the collection.

{ <existing key specification>, <suffix1>: <1|"hashed">, ... }

Important

For the suffix fields, set the field values to either:

See also参阅

Shard Keys

Access Control

When running with access control, the user must have the refineCollectionShardKey privilege actions on database and/or collection to run the command. That is, a user must have a role that grants the following privilege:

{ resource: { db: <database>, collection: <collection> }, actions: [ "refineCollectionShardKey" ] }

The built-in clusterManager role provides the appropriate privileges.

Considerations考虑事项

Index Considerations

  • Index Existence

    An index that supports the command’s specified key must exist prior to running the command.

    A supporting index is an index that starts with the new shard key specification; i.e. the index prefix matches the new shard key specification. That is, to change the shard key to { x: 1, y: 1 } from { x: 1 }, and index that starts with { x: 1, y: 1 } must exist; e.g.

    • { x: 1, y: 1 }
    • { x: 1, y: 1, a: 1, b: 1}

    Note

    • The supporting index cannot be a partial index.
    • The supporting index cannot be a sparse index.
    • If the collection uses a non-simple collation, the supporting index must specify { locale: "simple" } collation.
  • Unique Index

    If the current shard index has a uniqueness constraint, the new shard key index must also have a unique constraint.

    After creating the unique index to support the new shard key, drop the old shard key index before running refineCollectionShardKey.
    Also, if the current shard index has a unique constraint, then the new shard key cannot specify "hashed" for any of its fields.
    See also Sharded Collection and Unique Indexes.
  • Index Collation

    If the sharded collection has a non-simple default collation, then the index must include a collation document with { locale : "simple" }. At least one of the indexes whose fields support the shard key pattern must have the simple collation.

Examples示例

To set up the example in the test database:

  1. Enable sharding on the database, if sharding is not already enabled:

    sh.enableSharding("test")
  2. Use following shardCollection operation to shard the orders collection in the test database. The operation uses the customer_id field as the initial shard key:

    db.adminCommand( { shardCollection: "test.orders", key: { customer_id: 1 } } )

To modify the shard key to be the customer_id field and the order_id field { customer_id: 1, order_id: 1 },

  1. Create the index to support the new shard key if the index does not already exist.

    db.getSiblingDB("test").orders.createIndex( { customer_id: 1, order_id: 1 } )
  2. Run refineCollectionShardKey command to add the order_id field as a suffix:

    db.adminCommand( {
   refineCollectionShardKey: "test.orders",
   key: { customer_id: 1, order_id: 1 }
} )

Upon successful completion of the command, the shard key for the collection has changed to { customer_id: 1, order_id: 1 }. To verify, you can run sh.status().

Tip

After you refine the shard key, it may be that not all documents in the collection have the suffix field(s). To populate the missing shard key field(s), see Missing Shard Key.

Before refining the shard key, ensure that all or most documents in the collection have the suffix fields, if possible, to avoid having to populate the field afterwards.

Collection with non-simple Collation

To set up the example in the test database:

  1. Enable sharding on the database, if sharding is not already enabled:

    sh.enableSharding("test")
  2. Create the cafés collection in the test database, specifying French fr as the default collation.

    db.getSiblingDB("test").createCollection( "cafés", { collation: { locale: "fr" } } );
  3. Shard the collection using customer_id field as the initial shard key. Because the collection has a default fr collation and not a simple collation, the shardCollection command must include a collation: { locale: "simple" } option:

    db.adminCommand( {
   shardCollection: "test.cafés",
   key: { customer_id: 1 },
   collation: { locale: "simple" }
} )

To modify the shard key to be both the customer_id field and the order_id field { customer_id: 1, order_id: 1 },

  1. Create the index to support the new shard key if the index does not already exist. Because the collection uses a non-simple collation, the index must include the collation: { locale: "simple" } option.

    db.getSiblingDB("test").cafés.createIndex(
   { customer_id: 1, order_id: 1 },
   { collation: { locale: "simple" } }
)
  2. Run refineCollectionShardKey command to add the order_id field as a suffix:

    db.adminCommand( {
   refineCollectionShardKey: "test.cafés",
   key: { customer_id: 1, order_id: 1 }
} )

Upon successful completion of the command, the shard key for the collection has changed to { customer_id: 1, order_id: 1 }. To verify, you can run sh.status().

Tip

After you refine the shard key, it may be that not all documents in the collection have the suffix field(s). To populate the missing shard key field(s), see Missing Shard Key.

Before refining the shard key, ensure that all or most documents in the collection have the suffix fields, if possible, to avoid having to populate the field afterwards.

See also参阅

Shard Keys