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

FreeBSD Manual Pages

  
 
  

home | help
MONGOC_CLIENT_COMMAND(3)	   libmongoc	      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.

1.30.2				 Apr 12, 2025	      MONGOC_CLIENT_COMMAND(3)

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

home | help