> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  other tabs: query-planner, query-planner-extended, execution-stats
-->

# Diagnostic Commands

## `buildInfo`

For the [buildInfo](https://www.mongodb.com/docs/manual/reference/command/buildInfo.md#std-label-buildinfo-database-command) command, the response contains the following fields:

| Field | Description |
| --- | --- |
| `ok` | Returns `1` for success or `0` for failure. |
| `version` | MongoDB client compatibility version. This is the earliest version of the MongoDB client with which the Data Federation service is compatible. |
| `versionArray` | MongoDB client compatibility version in array format. |
| `dataLake.version` | Version number of Data Federation. |
| `dataLake.gitVersion` | Git version of the Data Federation service. |
| `dataLake.date` | Build timestamp of the Data Federation service. |
| `dataLake.mongoSQLVersion` | `mongoSQL` version of the Data Federation service. |

**Example:**

```json
{
  "ok" : <return>,
  "version" : "<version-number>",
  "versionArray" : [
    <number>,
    <number>,
    <number>,
    <number>
  ],
  "dataLake" : {
    "version" : "<version-number>",
    "gitVersion" : "<version-number>",
    "date" : "<timestamp>",
    "mongoSQLVersion" : "<version-number>"
  }
}
```

## `collStats`

For the [collStats](https://www.mongodb.com/docs/manual/reference/command/collStats.md#std-label-collstats-database-command) command, Atlas Data Federation omits the following fields in the response:

- `avgObjSize`

- `capped`

- `max`

- `maxSize`

- `wiredTiger`

- `nindexes`

- `totalIndexSize`

- `indexSizes`

Atlas Data Federation includes the following fields in the response. You can use these fields to verify what partitions are used to populate a collection, understand how recently the stats were computed, and determine if Atlas Data Federation truncated the output document.

| Field | Description |
| --- | --- |
| `dataLake.partitionCount` | Number of partitions. |
| `dataLake.avgPartitionSize` | Average size of all partitions. |
| `dataLake.partitions.format` | File format of the partition. |
| `dataLake.partitions.attributes` | Filtering attributes of the partition. |
| `dataLake.partitions.count` | Number of documents in the partition. |
| `dataLake.partitions.size` | Size, in bytes, of the partition. |
| `dataLake.partitions.source` | Cloud storage URL, which contains the backing data of the partition. |
| `dataLake.partitions.version` | MongoDB version of the Atlas cluster. The `collStats` command returns this only for [Atlas Cluster](https://www.mongodb.com/docs/atlas/data-federation/config/adf-config-file-formats.md#std-label-adf-configuration-file-atlas) data stores. The value has the following format: `<major-version-number>.<minor-version-number>.<patch-version-number>` For example, `7.0.1`. |
| `cacheMetadata` | Information about how recently Atlas Data Federation computed the statistics. |
| `cacheMetadata.computeTime` | Time in [ISODate](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-ISODate) format when the computation for the stats started. |
| `cacheMetadata.automaticRefreshInProgress` | Flag that indicates whether a background job is running now to refresh the cache. |
| `truncated` | Flag that indicates whether Atlas Data Federation enforced the maximum document size limit of 16MiB. The flag value can be one of the following: `true` - if the output document size exceeded the limit and was therefore truncated to include only enough partitions that allowed the document to comply with the size limit. If `true`, the `partitionCount` and `avgPartitionSize` values that Atlas Data Federation returns may be smaller than the actual values.; `false` - if Atlas Data Federation returns the entire document. |

**Example:**

```json
{
  ...
  "partitionCount": <number of partitions>,
  "avgPartitionSize": <average size of all partitions>,
  "partitions": [
    {
        "format": <file format>,
        "attributes": <filtering attributes>,
        "count": <number of documents in partition>,
        "source": <cloud storage URL>,
        "size": <size, in bytes, of the partition>
      },
    ...
  ],
  "truncated": false,
  "cacheMetadata": {
    computeTime: ISODate("2021-07-25T15:10:33.513Z"),
    automaticRefreshInProgress: false
  },
  ...
}
```

Atlas Data Federation introduces an optional boolean parameter, `sync`, to bypass the cache and fetch the most recent storage statistics for a given collection. The following values are valid for the `sync` parameter:

- `true` - to bypass the cache and return the most recent storage statistics

- `false` - to return cached data

If the `sync` parameter is omitted, defaults to `false`.

**Example:**

```js
db.runCommand( {collStats: "<string>", sync: true|false} )
```

To learn more about the parameters supported by this command, see [collStats.](https://www.mongodb.com/docs/manual/reference/command/collStats.md#std-label-collstats-database-command)

## `connectionStatus`

For [connectionStatus](https://www.mongodb.com/docs/manual/reference/command/connectionStatus.md#std-label-connectionstatus-database-command) command, Atlas Data Federation returns information about the current connection, specifically the state of authenticated users and their available [roles.](https://www.mongodb.com/docs/atlas/reference/user-roles/)

**Note:**

Only one user can authenticate on a connection to a federated database instance at any given time. If a user authenticates and then runs the `db.auth()` command, Data Federation replaces the previous user's permissions with the new user's permissions.

The [connectionStatus](https://www.mongodb.com/docs/manual/reference/command/connectionStatus/) command shows only the newly authenticated user in the `authenticatedUsers` output field.

## `dbStats`

For [dbStats](https://www.mongodb.com/docs/manual/reference/command/dbStats.md#std-label-dbstats-database-command) command, Atlas Data Federation introduces an optional boolean parameter, `sync`, to bypass the cache and fetch the most recent storage statistics for a given database. The following values are valid for the `sync` parameter:

- `true` - to bypass the cache and return the most recent storage statistics

- `false` - to use the cached data also

If the `sync` parameter is omitted, defaults to `false`.

**Example:**

```js
db.runCommand( {dbStats: 1, sync: true|false} )
```

To learn more about the parameters supported by this command, see [dbStats.](https://www.mongodb.com/docs/manual/reference/command/dbStats.md#std-label-dbstats-database-command)

Atlas Data Federation command omits the followig fields in the response:

- `object`

- `avgObjSize`

- `fsUsedSize`

- `fsTotalSize`

The commands adds the following fields in the response. You can use these fields to determine whether the command returned stale data.

| Field | Description |
| --- | --- |
| `cacheMetadata` | Contains information on how recently the stats were computed. |
| `cacheMetadata.computeTime` | Time in [ISODate](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-ISODate) format when the computation for the stats started. |
| `cacheMetadata.automaticRefreshInProgress` | Flag that indicates whether a background job is running now to refresh the cache. |

## `explain`

The [explain](https://www.mongodb.com/docs/manual/reference/command/explain.md#std-label-explain-database-command) command returns information that describes the Data Federation query plan. The `explain` output differs from MongoDB in that it provides information about the data partitions used to satisfy the query.

The following commands can be explained in Data Federation:

- `aggregate()`

- `count()`

- `find()`

### Usage

Atlas Data Federation supports the following `verbosity` modes:

- `queryPlanner` - provides information on the query plan. If the verbosity is not specified, Atlas Data Federation defaults to this mode.

- `queryPlannerExtended` - provides detailed information on the query plan including information about the object-storage objects, such as the object-storage object names and sizes that will be queried.

- `executionStats` - provides query execution statistics and performance.

Atlas Data Federation doesn't support the `allPlansExecution` mode.

**Example:**

The following example shows how to use the `explain` command to get information about the [aggregate](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#std-label-aggregate-database-command) command, including detailed information on the query plan.

```js
db.runCommand({ "explain": { "aggregate": "user", "verbosity":
"queryPlannerExtended", "pipeline": [ ], "cursor": {} }})
```

The following example shows how to append a method to the `explain` method, such as the [`find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.find.md#mongodb-method-db.collection.find) method, to get query execution statistics on the query.

```js
db.users.explain("executionStats").find({"type": "admin"})
```

### Output

When you run `explain`, Atlas Data Federation returns the following additional fields for other partitions:

| Output Field Name | Description |
| --- | --- |
| `stats` | Document that describes the number and total size of partitions that Atlas Data Federation might open for the query. |
| `stats.size` | Total size of partitions that Atlas Data Federation might open for the query. |
| `stats.numberOfPartitions` | Number of partitions that Atlas Data Federation might open for the query. |
| `truncated` | Boolean that indicates whether the `explain` output is truncated. The `explain` total output document size is limited to 16 MiB. |
| `plan` | Document that contains the query execution plan for the query. The document contains nested execution plan nodes, each of which is a document describing the plan node. The nested plan node documents contain internal description of Atlas Data Federation's query execution, and include various node kinds that are subject to change. Contact MongoDB support if you need more help with understanding the query plan. |

### queryPlanner (default)

In the `queryPlanner` mode, the results returned by `explain` provide detailed information on the partitions in the federated database instance.

```js
{
  ok: 1,
  stats: { size: '66 B', numberOfPartitions: 2 },
  truncated: false,
  plan: {
    kind: 'region',
    region: 'aws/us-east-1',
    node: {
      kind: 'data',
      size: '66 B',
      numberOfPartitions: 2,
      partitionsTruncated: false,
      partitions: [
        {
          source: 'projectID:cluster',
          provider: 'atlas',
          size: '4 B',
          database: 'locations',
          collection: 'nyc'
        },
        {
          source: 'dls:projectID',
          provider: 'dls:aws',
          size: '62 B',
          metadataLocation: { provider: 'aws', region: 'us-east-1' },
          dataSetName: 'v1$atlas$archive$etc',
          optimizationPlan: { kind: 'everything' }
        }
      ]
    }
  }
}
```

The `explain` command returns the following additional fields for Atlas partitions:

| Output | Description |
| --- | --- |
| `database` | Database that that Atlas Data Federation queried. |
| `collection` | Collection that that Atlas Data Federation queried. |
| `pipeline` | Aggregation pipeline that Atlas Data Federation executed. |

The `explain` command returns the following additional field for Online Archive partitions:

| Output Field Name | Description |
| --- | --- |
| `optimizationPlan` | Details on Online Archive optimizations. Queries will likely be optimized when they contain fields that match the configured partition keys for an Online Archive. |

## `getLog`

For [getLog](https://www.mongodb.com/docs/manual/reference/command/getLog.md#std-label-getlog-database-command) command, Atlas Data Federation returns a successful response, but doesn't includes log data.

## `getMore`

For [getMore](https://www.mongodb.com/docs/manual/reference/command/getMore.md#std-label-manual-reference-commands-getMore) command, Atlas Data Federation returns subsequent batches of documents currently pointed to by a cursor, when used in conjunction with commands that return a cursor, e.g. [find](https://www.mongodb.com/docs/manual/reference/command/find.md#std-label-find-database-command) and [aggregate.](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#std-label-aggregate-database-command)

## `hostInfo`

For [hostInfo](https://www.mongodb.com/docs/manual/reference/command/hostInfo.md#std-label-hostinfo-database-command) command, Atlas Data Federation returns only the following subset of fields from the standard MongoDB response:

```json
{
  "ok" : <return>,
  "system" : {
    "currentTime" : ISODate("<timestamp>"),
    "hostname" : "<hostname>",
    "cpuAddrSize" : <number>,
    "memSizeMB" : <number>,
    "numCores" : <number>,
    "cpuArch" : "<identifier>",
  },
  "os" : {
    "type" : "<string>",
    "name" : "<string>",
  },
  "extra" : { }
}
```

## `ping`

For [ping](https://www.mongodb.com/docs/manual/reference/command/ping.md#std-label-ping-database-command) command, Atlas Data Federation tests whether a server is responding to commands.

## `whatsmyuri`

For [whatsmyuri](https://www.mongodb.com/docs/manual/reference/command/whatsmyuri.md#std-label-whatsmyuri-database-command) command, Atlas Data Federation returns the client IP address.