---
name: "mongoc_client_command"
section: "3"
platform: "linux"
package: "libmongoc-doc"
version: "1.30.4-1+deb13u3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/mongoc_client_command"
---

# mongoc\_client\_command(3)

**WARNING:**

Deprecated since version 1.29.0: This function is deprecated and should not be used in new code. Use *mongoc\_client\_command\_simple()* instead.

## SYNOPSIS

```
mongoc_cursor_t *
mongoc_client_command (mongoc_client_t *client,
                       const char *db_name,
                       mongoc_query_flags_t flags,
                       uint32_t skip,
                       uint32_t limit,
                       uint32_t batch_size,
                       const bson_t *query,
                       const bson_t *fields,
                       const mongoc_read_prefs_t *read_prefs);
```

This function is not considered a retryable read operation.

## DESCRIPTION

This function creates a cursor which will execute the command when *mongoc\_cursor\_next()* is called on it. The client's read preference, read concern, and write concern are not applied to the command, and *mongoc\_cursor\_next()* will not check the server response for a write concern error or write concern timeout.

If *mongoc\_cursor\_next()* returns **false**, then retrieve error details with *mongoc\_cursor\_error()* or *mongoc\_cursor\_error\_document()*.

## PARAMETERS

- •

  **client**: A *mongoc\_client\_t*.

- •

  **db\_name**: The name of the database to run the command on.

- •

  **flags**: Unused.

- •

  **skip**: Unused.

- •

  **limit**: Unused.

- •

  **batch\_size**: Unused.

- •

  **query**: A *bson\_t* containing the command specification.

- •

  **fields**: Unused.

- •

  **read\_prefs**: An optional *mongoc\_read\_prefs\_t*. Otherwise, the command uses mode **MONGOC\_READ\_PRIMARY**.

## MIGRATING

*mongoc\_client\_command()* is deprecated.

The following example uses *mongoc\_client\_command()*:

Before

```
const bson_t *reply;
bson_t *cmd = BCON_NEW ("find", "foo", "filter", "{", "}");
mongoc_cursor_t *cursor = mongoc_client_command (client,
                                                 "db",
                                                 MONGOC_QUERY_NONE /* unused */,
                                                 0 /* unused */,
                                                 0 /* unused */,
                                                 0 /* unused */,
                                                 cmd,
                                                 NULL /* unused */,
                                                 NULL /* read prefs */);
// Expect cursor to return exactly one document for the command reply.
EXPECT (mongoc_cursor_next (cursor, &reply));
bson_error_t error;
if (mongoc_cursor_error (cursor, &error)) {
   FAIL ("Expected no error, got: %s\n", error.message);
}
// Expect successful reply to contain "ok": 1
bson_iter_t iter;
EXPECT (bson_iter_init_find (&iter, reply, "ok") && bson_iter_as_int64 (&iter) == 1);
// Expect cursor to return no other documents.
EXPECT (!mongoc_cursor_next (cursor, &reply));
mongoc_cursor_destroy (cursor);
bson_destroy (cmd);
```

The above code block may be rewritten to use *mongoc\_client\_command\_simple()* instead, as shown below:

After

```
bson_t reply;
bson_error_t error;
bson_t *cmd = BCON_NEW ("find", "foo", "filter", "{", "}");
if (!mongoc_client_command_simple (client, "db", cmd, NULL /* read prefs */, &reply, &error)) {
   FAIL ("Expected no error, got: %s\n", error.message);
}
// Expect successful reply to contain "ok": 1
bson_iter_t iter;
EXPECT (bson_iter_init_find (&iter, &reply, "ok") && bson_iter_as_int64 (&iter) == 1);
bson_destroy (&reply);
bson_destroy (cmd);
```

## RETURNS

A *mongoc\_cursor\_t*.

The cursor should be freed with *mongoc\_cursor\_destroy()*.

## AUTHOR

MongoDB, Inc

## COPYRIGHT

2009-present, MongoDB, Inc.