Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MONGOC_CLIENT_...MAND_WITH_OPTS(3) libmongocMONGOC_CLIENT_...MAND_WITH_OPTS(3)

SYNOPSIS
	  bool
	  mongoc_client_read_command_with_opts (mongoc_client_t	*client,
						const char *db_name,
						const bson_t *command,
						const mongoc_read_prefs_t *read_prefs,
						const bson_t *opts,
						bson_t *reply,
						bson_error_t *error);

       Execute	a  command  on	the server, applying logic that	is specific to
       commands	that read, and taking the MongoDB server version into account.
       To send a raw command to	the server without  any	 of  this  logic,  use
       mongoc_client_command_simple().

       Use this	function for commands that read	such as	"count"	or "distinct".

       Read preferences, read concern, and collation can be overridden by var-
       ious sources. In	a transaction, read concern and	write concern are pro-
       hibited	in  opts  and the read preference must be primary or NULL. The
       highest-priority	sources	for these options are listed first in the fol-
       lowing table. No	write concern is applied.
		  +------------------+--------------+-----------+
		  | Read Preferences | Read Concern | Collation	|
		  +------------------+--------------+-----------+
		  | read_prefs	     | opts	    | opts	|
		  +------------------+--------------+-----------+
		  | Transaction	     | Transaction  |		|
		  +------------------+--------------+-----------+
		  | client	     |		    |		|
		  +------------------+--------------+-----------+

       See the example for transactions	and for	the  "distinct"	 command  with
       opts.

       reply is	always initialized, and	must be	freed with bson_destroy().

       This  function  is considered a retryable read operation.  Upon a tran-
       sient 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.

       Retry  logic  occurs  regardless	 of  the  underlying command. Retrying
       mapReduce has the potential for degraded	performance.  Retrying a  get-
       More command has	the potential to miss results. For those commands, use
       generic	command	 helpers  (like	mongoc_client_command_with_opts()) in-
       stead.

PARAMETERS
        client: A mongoc_client_t.

        db_name: The name of the database to run the command on.

        command: A bson_t containing the command specification.

        read_prefs: An	optional mongoc_read_prefs_t.

        opts: A bson_t	containing additional options.

        reply:	A maybe-NULL pointer to	overwritable storage for a  bson_t  to
	 contain the results.

        error:	An optional location for a bson_error_t	or NULL.

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

        readConcern:	 Construct    a	   mongoc_read_concern_t    and	   use
	 mongoc_read_concern_append() to add the read concern to opts. See the
	 example code for mongoc_client_read_command_with_opts(). Read concern
	 requires MongoDB 3.2 or later,	otherwise an error is returned.

        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
	 client, and use mongoc_client_session_append()	to add the session  to
	 opts. See the example code for	mongoc_client_session_t.

        collation:  Configure	textual	comparisons. See Setting Collation Or-
	 der, and the MongoDB Manual entry on  Collation.  Collation  requires
	 MongoDB 3.2 or	later, otherwise an error is returned.

        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.

       Consult	the  MongoDB  Manual  entry on Database	Commands for each com-
       mand's arguments.

ERRORS
       Errors are propagated via the error parameter.

RETURNS
       Returns true if successful. Returns false and sets error	if  there  are
       invalid arguments or a server or	network	error.

EXAMPLE
       example-command-with-opts.c

	  /*

	  Demonstrates how to prepare options for mongoc_client_read_command_with_opts and
	  mongoc_client_write_command_with_opts. First it calls	"cloneCollectionAsCapped"
	  command with "writeConcern" option, then "distinct" command with "collation" and
	  "readConcern"	options,

	  Start	a MongoDB 3.4 replica set with --enableMajorityReadConcern and insert two
	  documents:

	  $ mongo
	  MongoDB Enterprise replset:PRIMARY> db.my_collection.insert({x: 1, y:	"One"})
	  WriteResult({	"nInserted" : 1	})
	  MongoDB Enterprise replset:PRIMARY> db.my_collection.insert({x: 2, y:	"Two"})
	  WriteResult({	"nInserted" : 1	})

	  Build	and run	the example:

	  gcc example-command-with-opts.c -o example-command-with-opts $(pkg-config
	  --cflags --libs libmongoc-1.0)
	  ./example-command-with-opts [CONNECTION_STRING]
	  cloneCollectionAsCapped: { "ok" : 1 }
	  distinct: { "values" : [ 1, 2	], "ok"	: 1 }

	  */

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

	  int
	  main (int argc, char *argv[])
	  {
	     mongoc_client_t *client;
	     const char	*uri_string = "mongodb://127.0.0.1/?appname=client-example";
	     mongoc_uri_t *uri;
	     bson_t *cmd;
	     bson_t *opts;
	     mongoc_write_concern_t *write_concern;
	     mongoc_read_prefs_t *read_prefs;
	     mongoc_read_concern_t *read_concern;
	     bson_t reply;
	     bson_error_t error;
	     char *json;

	     mongoc_init ();

	     if	(argc >	1) {
		uri_string = argv[1];
	     }

	     uri = mongoc_uri_new_with_error (uri_string, &error);
	     if	(!uri) {
		fprintf	(stderr,
			 "failed to parse URI: %s\n"
			 "error	message:       %s\n",
			 uri_string,
			 error.message);
		return EXIT_FAILURE;
	     }

	     client = mongoc_client_new_from_uri (uri);
	     if	(!client) {
		return EXIT_FAILURE;
	     }

	     mongoc_client_set_error_api (client, 2);

	     cmd = BCON_NEW ("cloneCollectionAsCapped",
			     BCON_UTF8 ("my_collection"),
			     "toCollection",
			     BCON_UTF8 ("my_capped_collection"),
			     "size",
			     BCON_INT64	(1024 *	1024));

	     /*	include	write concern "majority" in command options */
	     write_concern = mongoc_write_concern_new ();
	     mongoc_write_concern_set_wmajority	(write_concern,	10000 /* wtimeoutMS */);
	     opts = bson_new ();
	     mongoc_write_concern_append (write_concern, opts);

	     if	(mongoc_client_write_command_with_opts (client,	"test",	cmd, opts, &reply, &error)) {
		json = bson_as_canonical_extended_json (&reply,	NULL);
		printf ("cloneCollectionAsCapped: %s\n", json);
		bson_free (json);
	     } else {
		fprintf	(stderr, "cloneCollectionAsCapped: %s\n", error.message);
	     }

	     bson_free (cmd);
	     bson_free (opts);

	     /*	distinct values	of "x" in "my_collection" where	"y" sorts after	"one" */
	     cmd = BCON_NEW ("distinct",
			     BCON_UTF8 ("my_collection"),
			     "key",
			     BCON_UTF8 ("x"),
			     "query",
			     "{",
			     "y",
			     "{",
			     "$gt",
			     BCON_UTF8 ("one"),
			     "}",
			     "}");

	     read_prefs	= mongoc_read_prefs_new	(MONGOC_READ_SECONDARY);

	     /*	"One" normally sorts before "one"; make	"One" sort after "one" */
	     opts = BCON_NEW ("collation", "{",	"locale", BCON_UTF8 ("en_US"), "caseFirst", BCON_UTF8 ("lower"), "}");

	     /*	add a read concern to "opts" */
	     read_concern = mongoc_read_concern_new ();
	     mongoc_read_concern_set_level (read_concern, MONGOC_READ_CONCERN_LEVEL_MAJORITY);

	     mongoc_read_concern_append	(read_concern, opts);

	     if	(mongoc_client_read_command_with_opts (client, "test", cmd, read_prefs,	opts, &reply, &error)) {
		json = bson_as_canonical_extended_json (&reply,	NULL);
		printf ("distinct: %s\n", json);
		bson_free (json);
	     } else {
		fprintf	(stderr, "distinct: %s\n", error.message);
	     }

	     bson_destroy (cmd);
	     bson_destroy (opts);
	     bson_destroy (&reply);
	     mongoc_read_prefs_destroy (read_prefs);
	     mongoc_read_concern_destroy (read_concern);
	     mongoc_write_concern_destroy (write_concern);
	     mongoc_uri_destroy	(uri);
	     mongoc_client_destroy (client);

	     mongoc_cleanup ();

	     return EXIT_SUCCESS;
	  }

AUTHOR
       MongoDB,	Inc

COPYRIGHT
       2009-present, MongoDB, Inc.

1.30.2				 Apr 12, 202MONGOC_CLIENT_...MAND_WITH_OPTS(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mongoc_client_read_command_with_opts&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help