.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "MONGOC_COMMON_TASK_EXAMPLES" "3" "Feb 25, 2024" "1.26.0" "libmongoc"
.sp
Drivers for some other languages provide helper functions to perform certain common tasks. In the C Driver we must explicitly build commands to send to the server.
.SH SETUP
.sp
First we\(aqll write some code to insert sample data:
.sp
doc\-common\-insert.c
.INDENT 0.0
.INDENT 3.5
.sp
.EX
/* Don\(aqt try to compile this file on its own. It\(aqs meant to be #included
   by example code */

/* Insert some sample data */
bool
insert_data (mongoc_collection_t *collection)
{
   mongoc_bulk_operation_t *bulk;
   enum N { ndocs = 4 };
   bson_t *docs[ndocs];
   bson_error_t error;
   int i = 0;
   bool ret;

   bulk = mongoc_collection_create_bulk_operation_with_opts (collection, NULL);

   docs[0] = BCON_NEW (\(dqx\(dq, BCON_DOUBLE (1.0), \(dqtags\(dq, \(dq[\(dq, \(dqdog\(dq, \(dqcat\(dq, \(dq]\(dq);
   docs[1] = BCON_NEW (\(dqx\(dq, BCON_DOUBLE (2.0), \(dqtags\(dq, \(dq[\(dq, \(dqcat\(dq, \(dq]\(dq);
   docs[2] = BCON_NEW (
      \(dqx\(dq, BCON_DOUBLE (2.0), \(dqtags\(dq, \(dq[\(dq, \(dqmouse\(dq, \(dqcat\(dq, \(dqdog\(dq, \(dq]\(dq);
   docs[3] = BCON_NEW (\(dqx\(dq, BCON_DOUBLE (3.0), \(dqtags\(dq, \(dq[\(dq, \(dq]\(dq);

   for (i = 0; i < ndocs; i++) {
      mongoc_bulk_operation_insert (bulk, docs[i]);
      bson_destroy (docs[i]);
      docs[i] = NULL;
   }

   ret = mongoc_bulk_operation_execute (bulk, NULL, &error);

   if (!ret) {
      fprintf (stderr, \(dqError inserting data: %s\en\(dq, error.message);
   }

   mongoc_bulk_operation_destroy (bulk);
   return ret;
}

/* A helper which we\(aqll use a lot later on */
void
print_res (const bson_t *reply)
{
   char *str;
   BSON_ASSERT (reply);
   str = bson_as_canonical_extended_json (reply, NULL);
   printf (\(dq%s\en\(dq, str);
   bson_free (str);
}

.EE
.UNINDENT
.UNINDENT
.SH "EXPLAIN" COMMAND
.sp
This is how to use the \fBexplain\fP command in MongoDB 3.2+:
.sp
explain.c
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bool
explain (mongoc_collection_t *collection)
{
   bson_t *command;
   bson_t reply;
   bson_error_t error;
   bool res;

   command = BCON_NEW (\(dqexplain\(dq,
                       \(dq{\(dq,
                       \(dqfind\(dq,
                       BCON_UTF8 (COLLECTION_NAME),
                       \(dqfilter\(dq,
                       \(dq{\(dq,
                       \(dqx\(dq,
                       BCON_INT32 (1),
                       \(dq}\(dq,
                       \(dq}\(dq);
   res = mongoc_collection_command_simple (
      collection, command, NULL, &reply, &error);
   if (!res) {
      fprintf (stderr, \(dqError with explain: %s\en\(dq, error.message);
      goto cleanup;
   }

   /* Do something with the reply */
   print_res (&reply);

cleanup:
   bson_destroy (&reply);
   bson_destroy (command);
   return res;
}

.EE
.UNINDENT
.UNINDENT
.SH RUNNING THE EXAMPLES
.sp
common\-operations.c
.INDENT 0.0
.INDENT 3.5
.sp
.EX
/*
 * Copyright 2016 MongoDB, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the \(dqLicense\(dq);
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE\-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an \(dqAS IS\(dq BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


#include <mongoc/mongoc.h>
#include <stdio.h>


const char *COLLECTION_NAME = \(dqthings\(dq;

#include \(dq../doc\-common\-insert.c\(dq
#include \(dqexplain.c\(dq


int
main (int argc, char *argv[])
{
   mongoc_database_t *database = NULL;
   mongoc_client_t *client = NULL;
   mongoc_collection_t *collection = NULL;
   mongoc_uri_t *uri = NULL;
   bson_error_t error;
   char *host_and_port;
   int res = 0;

   if (argc < 2 || argc > 3) {
      fprintf (stderr,
               \(dqusage: %s MONGOD\-1\-CONNECTION\-STRING \(dq
               \(dq[MONGOD\-2\-HOST\-NAME:MONGOD\-2\-PORT]\en\(dq,
               argv[0]);
      fprintf (stderr,
               \(dqMONGOD\-1\-CONNECTION\-STRING can be \(dq
               \(dqof the following forms:\en\(dq);
      fprintf (stderr, \(dqlocalhost\et\et\et\etlocal machine\en\(dq);
      fprintf (stderr, \(dqlocalhost:27018\et\et\et\etlocal machine on port 27018\en\(dq);
      fprintf (stderr,
               \(dqmongodb://user:pass@localhost:27017\et\(dq
               \(dqlocal machine on port 27017, and authenticate with username \(dq
               \(dquser and password pass\en\(dq);
      return EXIT_FAILURE;
   }

   mongoc_init ();

   if (strncmp (argv[1], \(dqmongodb://\(dq, 10) == 0) {
      host_and_port = bson_strdup (argv[1]);
   } else {
      host_and_port = bson_strdup_printf (\(dqmongodb://%s\(dq, argv[1]);
   }

   uri = mongoc_uri_new_with_error (host_and_port, &error);
   if (!uri) {
      fprintf (stderr,
               \(dqfailed to parse URI: %s\en\(dq
               \(dqerror message:       %s\en\(dq,
               host_and_port,
               error.message);
      res = EXIT_FAILURE;
      goto cleanup;
   }

   client = mongoc_client_new_from_uri (uri);
   if (!client) {
      res = EXIT_FAILURE;
      goto cleanup;
   }

   mongoc_client_set_error_api (client, 2);
   database = mongoc_client_get_database (client, \(dqtest\(dq);
   collection = mongoc_database_get_collection (database, COLLECTION_NAME);

   printf (\(dqInserting data\en\(dq);
   if (!insert_data (collection)) {
      res = EXIT_FAILURE;
      goto cleanup;
   }

   printf (\(dqexplain\en\(dq);
   if (!explain (collection)) {
      res = EXIT_FAILURE;
      goto cleanup;
   }

cleanup:
   if (collection) {
      mongoc_collection_destroy (collection);
   }

   if (database) {
      mongoc_database_destroy (database);
   }

   if (client) {
      mongoc_client_destroy (client);
   }

   if (uri) {
      mongoc_uri_destroy (uri);
   }

   bson_free (host_and_port);
   mongoc_cleanup ();
   return res;
}

.EE
.UNINDENT
.UNINDENT
.sp
First launch two separate instances of mongod (must be done from separate shells):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ mongod
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ mkdir /tmp/db2
$ mongod \-\-dbpath /tmp/db2 \-\-port 27018 # second instance
.EE
.UNINDENT
.UNINDENT
.sp
Now compile and run the example program:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ cd examples/common_operations/$ gcc \-Wall \-o example common\-operations.c $(pkg\-config \-\-cflags \-\-libs libmongoc\-1.0)$ ./example localhost:27017 localhost:27018
Inserting data
explain
{
   \(dqexecutionStats\(dq : {
      \(dqallPlansExecution\(dq : [],
      \(dqexecutionStages\(dq : {
         \(dqadvanced\(dq : 19,
         \(dqdirection\(dq : \(dqforward\(dq ,
         \(dqdocsExamined\(dq : 76,
         \(dqexecutionTimeMillisEstimate\(dq : 0,
         \(dqfilter\(dq : {
            \(dqx\(dq : {
               \(dq$eq\(dq : 1
            }
         },
         \(dqinvalidates\(dq : 0,
         \(dqisEOF\(dq : 1,
         \(dqnReturned\(dq : 19,
         \(dqneedTime\(dq : 58,
         \(dqneedYield\(dq : 0,
         \(dqrestoreState\(dq : 0,
         \(dqsaveState\(dq : 0,
         \(dqstage\(dq : \(dqCOLLSCAN\(dq ,
         \(dqworks\(dq : 78
      },
      \(dqexecutionSuccess\(dq : true,
      \(dqexecutionTimeMillis\(dq : 0,
      \(dqnReturned\(dq : 19,
      \(dqtotalDocsExamined\(dq : 76,
      \(dqtotalKeysExamined\(dq : 0
   },
   \(dqok\(dq : 1,
   \(dqqueryPlanner\(dq : {
      \(dqindexFilterSet\(dq : false,
      \(dqnamespace\(dq : \(dqtest.things\(dq,
      \(dqparsedQuery\(dq : {
         \(dqx\(dq : {
            \(dq$eq\(dq : 1
         }
      },
      \(dqplannerVersion\(dq : 1,
      \(dqrejectedPlans\(dq : [],
      \(dqwinningPlan\(dq : {
         \(dqdirection\(dq : \(dqforward\(dq ,
         \(dqfilter\(dq : {
            \(dqx\(dq : {
               \(dq$eq\(dq : 1
            }
         },
         \(dqstage\(dq : \(dqCOLLSCAN\(dq
      }
   },
   \(dqserverInfo\(dq : {
      \(dqgitVersion\(dq : \(dq05552b562c7a0b3143a729aaa0838e558dc49b25\(dq ,
      \(dqhost\(dq : \(dqMacBook\-Pro\-57.local\(dq,
      \(dqport\(dq : 27017,
      \(dqversion\(dq : \(dq3.2.6\(dq
   }
}
.EE
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.