---
name: "mongoc_collection_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_collection_command"
---

# mongoc\_collection\_command(3)

**WARNING:**

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

## SYNOPSIS

```
mongoc_cursor_t *
mongoc_collection_command (mongoc_collection_t *collection,
                           mongoc_query_flags_t flags,
                           uint32_t skip,
                           uint32_t limit,
                           uint32_t batch_size,
                           const bson_t *command,
                           const bson_t *fields,
                           const mongoc_read_prefs_t *read_prefs);
```

This function is not considered a retryable read operation.

## PARAMETERS

- •

  **collection**: A *mongoc\_collection\_t*.

- •

  **flags**: Unused.

- •

  **skip**: Unused.

- •

  **limit**: Unused.

- •

  **batch\_size**: Unused.

- •

  **command**: A *bson\_t* containing the command to execute.

- •

  **fields**: Unused.

- •

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

## MIGRATING

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

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

Before

```
const bson_t *reply;
bson_t *cmd = BCON_NEW ("find", "foo", "filter", "{", "}");
mongoc_cursor_t *cursor = mongoc_collection_command (coll,
                                                     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\_collection\_command\_simple()* instead, as shown below:

After

```
bson_t reply;
bson_error_t error;
bson_t *cmd = BCON_NEW ("find", "foo", "filter", "{", "}");
if (!mongoc_collection_command_simple (coll, 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

This function returns a newly allocated *mongoc\_cursor\_t* that should be freed with *mongoc\_cursor\_destroy()* when no longer in use. The returned *mongoc\_cursor\_t* is never **NULL**, even on error. The user must call *mongoc\_cursor\_next()* on the returned *mongoc\_cursor\_t* to execute the initial command.

Cursor errors can be checked with *mongoc\_cursor\_error\_document()*. It always fills out the *bson\_error\_t* if an error occurred, and optionally includes a server reply document if the error occurred server-side.

**WARNING:**

Failure to handle the result of this function is a programming error.

## AUTHOR

MongoDB, Inc

## COPYRIGHT

2009-present, MongoDB, Inc.