MONGOC_DATABAS...IONS_WITH_OPTS(3)

💅 mongoc_database_find_collections_with_opts(3) — libmongoc

✨ SYNOPSIS ✨

          mongoc_cursor_t *
          mongoc_database_find_collections_with_opts (mongoc_database_t *database,
                                                      const bson_t *opts);

Okay bestie, this one fetches a cursor containing documents, and each document corresponds to a collection on this database.

To get collection names only, use mongoc_database_get_collection_names_with_opts() instead.

This function is considered a retryable read operation. Upon a transient error (a network error, errors due to replica set failover, etc.) the operation is safely retried once. If retryreads is false in the URI (see mongoc_uri_t) the retry behavior does not apply. Periodt.

🌸 PARAMETERS 🌸

• database — a mongoc_database_t. That's the database we're snooping around in.
• opts — a bson_t containing additional options.

opts may be NULL or a BSON document with additional command options:

• sessionId — First, construct a mongoc_client_session_t with mongoc_client_start_session(). You can begin a transaction with mongoc_client_session_start_transaction(), optionally with a mongoc_transaction_opt_t that overrides the options inherited from database, and use mongoc_client_session_append() to add the session to opts. See the example code for mongoc_client_session_t.
• serverId — To target a specific server, include an int32 "serverId" field. Obtain the id by calling mongoc_client_select_server(), then mongoc_server_description_id() on its return value.

For a list of all options, see the MongoDB Manual entry on the listCollections command.

😭 ERRORS 😭

Use mongoc_cursor_error() on the returned cursor to check for errors.

🫶 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.

In the returned cursor each result corresponds to the server's representation of a collection in this database.

The cursor functions mongoc_cursor_set_limit(), mongoc_cursor_set_batch_size(), and mongoc_cursor_set_max_await_time_ms() have no use on the returned cursor. Not me trying them anyway 💀.

🎀 EXAMPLES 🎀

          {
             bson_t opts = BSON_INITIALIZER;
             bson_t name_filter;
             const bson_t *doc;
             bson_iter_t iter;
             bson_error_t error;
             mongoc_cursor_t *cursor;

             BSON_APPEND_DOCUMENT_BEGIN (&opts, "filter", &name_filter);
             /* find collections with names like "abbbbc" */
             BSON_APPEND_REGEX (&name_filter, "name", "ab+c", NULL);
             bson_append_document_end (&opts, &name_filter);

             cursor = mongoc_database_find_collections_with_opts (database, &opts);
             while (mongoc_cursor_next (cursor, &doc)) {
                bson_iter_init_find (&iter, doc, "name");
                printf ("found collection: %s\n", bson_iter_utf8 (&iter, NULL));
             }

             if (mongoc_cursor_error (cursor, &error)) {
                fprintf (stderr, "%s\n", error.message);
             }

             mongoc_cursor_destroy (cursor);
             bson_destroy (&opts);
          }

👑 SEE ALSO 👑

mongoc_database_get_collection_names_with_opts()

🦋 AUTHOR 🦋

MongoDB, Inc

🌈 COPYRIGHT 🌈

2009-present, MongoDB, Inc.

---

libmongoc manual · version 2.5.6 · dated Oct 09, 202… 💖