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

FreeBSD Manual Pages

  
 
  

home | help
MONGOC_DATABASE_COMMAND(3)	   libmongoc	    MONGOC_DATABASE_COMMAND(3)

WARNING:
	  Deprecated  since  version  1.29.0:  This function is	deprecated and
	  should     not     be	    used      in      new      code.	   Use
	  mongoc_database_command_simple() instead.

SYNOPSIS
	  mongoc_cursor_t *
	  mongoc_database_command (mongoc_database_t *database,
				   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);

DESCRIPTION
       This  function  creates	a  cursor  which will execute the command when
       mongoc_cursor_next() is called on it. The database'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.

       This function is	not considered a retryable read	operation.

PARAMETERS
        database: A mongoc_database_t.

        flags:	Unused.

        skip: Unused.

        limit:	Unused.

        batch_size: Unused.

        command: A bson_t containing the command.

        fields: Unused.

        read_prefs:  An  optional mongoc_read_prefs_t.	Otherwise, the command
	 uses mode MONGOC_READ_PRIMARY.

MIGRATING
       mongoc_database_command() is deprecated.

       The following example uses mongoc_database_command():

       Before

	  const	bson_t *reply;
	  bson_t *cmd =	BCON_NEW ("find", "foo", "filter", "{",	"}");
	  mongoc_cursor_t *cursor = mongoc_database_command (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_database_command_simple()	instead, as shown below:

       After

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

AUTHOR
       MongoDB,	Inc

COPYRIGHT
       2009-present, MongoDB, Inc.

1.30.2				 Apr 12, 2025	    MONGOC_DATABASE_COMMAND(3)

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

home | help