feat(shell-api): add collection.getShardLocation helper method MONGOSH-1996 (#2467)

Author: nirinchev

.github/workflows/smoke-tests.yml

@@ -17,7 +17,7 @@ jobs:
         node: [20.x, 22.x, 23.x]
       fail-fast: false
     runs-on: ${{ matrix.runner }}-latest
-    timeout-minutes: 15
+    timeout-minutes: 20 # Installing dependencies on windows can take a while
     env:
       npm_config_loglevel: verbose
       npm_config_foreground_scripts: "true"

packages/autocomplete/src/index.spec.ts

@@ -371,6 +371,8 @@ describe('completer.completer', function () {
               'checkMetadataConsistency',
               'analyzeShardKey',
               'configureQueryAnalyzer',
+              // 8.0+
+              'getShardLocation',
             ].includes(c)
         )
         .map((c) => `${i}${c}`);

packages/i18n/src/locales/en_US.ts

@@ -873,6 +873,12 @@ const translations: Catalog = {
                 'Prints the data distribution statistics for a sharded collection.',
               example: 'db.coll.getShardDistribution()',
             },
+            getShardLocation: {
+              link: 'https://mongodb.com/docs/manual/reference/method/db.collection.getShardLocation',
+              description:
+                'Returns a document containing the shards where this collection is located as well as whether the collection itself is sharded.',
+              example: 'db.coll.getShardLocation()',
+            },
             analyzeShardKey: {
               link: 'https://mongodb.com/docs/manual/reference/method/db.collection.analyzeShardKey',
               description:

packages/shell-api/src/collection.spec.ts

@@ -2363,6 +2363,75 @@ describe('Collection', function () {
       });
     });
 
+    describe('getShardLocation', function () {
+      let collections: Document[];
+      let serviceProviderCursor: StubbedInstance<ServiceProviderAggregationCursor>;
+
+      beforeEach(function () {
+        collections = [];
+        serviceProviderCursor =
+          stubInterface<ServiceProviderAggregationCursor>();
+        serviceProvider.aggregateDb.returns(serviceProviderCursor);
+
+        serviceProviderCursor.toArray.resolves(collections);
+      });
+
+      it('calls $listClusterCatalog', async function () {
+        collections = [
+          {
+            ns: collection.getFullName(),
+            shards: ['foo', 'bar'],
+            sharded: true,
+          },
+        ];
+        serviceProviderCursor.toArray.resolves(collections);
+
+        const shardLocation = await collection.getShardLocation();
+        expect(shardLocation).to.deep.equal({
+          shards: ['foo', 'bar'],
+          sharded: true,
+        });
+
+        expect(serviceProvider.aggregateDb).to.have.been.calledOnce;
+        const args = serviceProvider.aggregateDb.getCall(0).args;
+        expect(args[0]).to.equal(database.getName());
+        expect(args[1]).to.deep.equal([
+          {
+            $listClusterCatalog: {
+              shards: true,
+            },
+          },
+          {
+            $match: {
+              ns: collection.getFullName(),
+            },
+          },
+          {
+            $project: {
+              _id: 0,
+              shards: 1,
+              sharded: 1,
+            },
+          },
+        ]);
+      });
+
+      it('throws for non-existent collection', async function () {
+        try {
+          await collection.getShardLocation();
+          expect.fail('Expected getShardLocation to throw');
+        } catch (err) {
+          if (err instanceof MongoshRuntimeError) {
+            expect(err.message).to.include(
+              `Error finding location information for ${collection.getFullName()}`
+            );
+          } else {
+            expect.fail('Expected error to be a MongoshRuntimeError');
+          }
+        }
+      });
+    });
+
     describe('analyzeShardKey', function () {
       it('calls serviceProvider.runCommand on the admin database', async function () {
         await collection.analyzeShardKey({ myKey: 1 });
@@ -2999,6 +3068,11 @@ describe('Collection', function () {
       watch: { i: 1 },
       getSearchIndexes: { i: 3 },
       checkMetadataConsistency: { m: 'runCursorCommand', i: 2 },
+      getShardLocation: {
+        i: 2,
+        m: 'aggregateDb',
+        e: true,
+      },
     };
     const ignore: (keyof (typeof Collection)['prototype'])[] = [
       'getShardDistribution',

packages/shell-api/src/collection.ts

@@ -2282,6 +2282,51 @@ export class Collection<
     );
   }
 
+  @returnsPromise
+  @topologies([Topologies.Sharded])
+  @apiVersions([])
+  @serverVersions(['8.0.10', ServerVersions.latest])
+  async getShardLocation(): Promise<{
+    shards: string[];
+    sharded: boolean;
+  }> {
+    this._emitCollectionApiCall('getShardLocation', {});
+
+    const result = await (
+      await this._database.aggregate([
+        {
+          $listClusterCatalog: {
+            shards: true,
+          },
+        },
+        {
+          $match: {
+            ns: this.getFullName(),
+          },
+        },
+        {
+          $project: {
+            _id: 0,
+            shards: 1,
+            sharded: 1,
+          },
+        },
+      ])
+    ).toArray();
+
+    if (result.length > 0) {
+      return {
+        shards: result[0].shards,
+        sharded: result[0].sharded,
+      };
+    }
+
+    throw new MongoshRuntimeError(
+      `Error finding location information for ${this.getFullName()}`,
+      CommonErrors.CommandFailed
+    );
+  }
+
   @serverVersions(['3.1.0', ServerVersions.latest])
   @topologies([Topologies.ReplSet, Topologies.Sharded])
   @apiVersions([1])