.\" 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_COLLECTION_UPDATE_ONE" "3" "May 07, 2024" "1.27.1" "libmongoc" .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .EX bool mongoc_collection_update_one (mongoc_collection_t *collection, const bson_t *selector, const bson_t *update, const bson_t *opts, bson_t *reply, bson_error_t *error); .EE .UNINDENT .UNINDENT .SH PARAMETERS .INDENT 0.0 .IP \(bu 2 \fBcollection\fP: A \fI\%mongoc_collection_t\fP\&. .IP \(bu 2 \fBselector\fP: A \fI\%bson_t\fP containing the query to match the document for updating. .IP \(bu 2 \fBupdate\fP: A \fI\%bson_t\fP containing the update to perform. If updating with a pipeline, a \fI\%bson_t\fP array. .IP \(bu 2 \fBreply\fP: A maybe\-\fBNULL\fP pointer to \fI\%overwritable storage\fP for a \fI\%bson_t\fP to contain the results. .IP \(bu 2 \fBerror\fP: An optional location for a \fI\%bson_error_t\fP or \fBNULL\fP\&. .UNINDENT .sp \fBopts\fP may be NULL or a BSON document with additional command options: .INDENT 0.0 .IP \(bu 2 \fBwriteConcern\fP: Construct a \fI\%mongoc_write_concern_t\fP and use \fI\%mongoc_write_concern_append()\fP to add the write concern to \fBopts\fP\&. See the example code for \fI\%mongoc_client_write_command_with_opts()\fP\&. .IP \(bu 2 \fBsessionId\fP: First, construct a \fI\%mongoc_client_session_t\fP with \fI\%mongoc_client_start_session()\fP\&. You can begin a transaction with \fI\%mongoc_client_session_start_transaction()\fP, optionally with a \fI\%mongoc_transaction_opt_t\fP that overrides the options inherited from \fBcollection\fP, and use \fI\%mongoc_client_session_append()\fP to add the session to \fBopts\fP\&. See the example code for \fI\%mongoc_client_session_t\fP\&. .IP \(bu 2 \fBvalidate\fP: Construct a bitwise\-or of all desired \fI\%bson_validate_flags_t\fP\&. Set to \fBfalse\fP to skip client\-side validation of the provided BSON documents. .IP \(bu 2 \fBcomment\fP: A \fI\%bson_value_t\fP specifying the comment to attach to this command. The comment will appear in log messages, profiler output, and currentOp output. Requires MongoDB 4.4 or later. .IP \(bu 2 \fBbypassDocumentValidation\fP: Set to \fBtrue\fP to skip server\-side schema validation of the provided BSON documents. .IP \(bu 2 \fBcollation\fP: Configure textual comparisons. See \fI\%Setting Collation Order\fP, and \fI\%the MongoDB Manual entry on Collation\fP\&. Collation requires MongoDB 3.2 or later, otherwise an error is returned. .IP \(bu 2 \fBhint\fP: A document or string that specifies the index to use to support the query predicate. .IP \(bu 2 \fBupsert\fP: When true, creates a new document if no document matches the query. .IP \(bu 2 \fBlet\fP: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language. .IP \(bu 2 \fBarrayFilters\fP: An array of filters specifying to which array elements an update should apply. .UNINDENT .SH DESCRIPTION .sp This function updates at most one document in \fBcollection\fP that matches \fBselector\fP\&. .sp To update multiple documents see \fI\%mongoc_collection_update_many()\fP\&. .sp If you pass a non\-NULL \fBreply\fP, it is filled out with fields \fBmatchedCount\fP, \fBmodifiedCount\fP, and optionally \fBupsertedId\fP if applicable. If there is a server error then \fBreply\fP contains either a \(dqwriteErrors\(dq array with one subdocument or a \(dqwriteConcernErrors\(dq array. The reply must be freed with \fI\%bson_destroy()\fP\&. .SH ERRORS .sp Errors are propagated via the \fBerror\fP parameter. .SH RETURNS .sp Returns \fBtrue\fP if successful. Returns \fBfalse\fP and sets \fBerror\fP if there are invalid arguments or a server or network error. .sp A write concern timeout or write concern error is considered a failure. .SH EXAMPLE .sp example\-update.c .INDENT 0.0 .INDENT 3.5 .sp .EX #include \(dqmongoc/mongoc.h\(dq int main (void) { bson_t *to_insert = BCON_NEW (\(dq_id\(dq, BCON_INT32 (1)); bson_t *selector = BCON_NEW (\(dq_id\(dq, \(dq{\(dq, \(dq$gt\(dq, BCON_INT32 (0), \(dq}\(dq); bson_t *update = BCON_NEW (\(dq$set\(dq, \(dq{\(dq, \(dqx\(dq, BCON_INT32 (1), \(dq}\(dq); const bson_t *next_doc; char *to_str; bson_error_t error = {0}; mongoc_cursor_t *cursor; mongoc_client_t *client; mongoc_collection_t *coll; const char *uri_string = \(dqmongodb://localhost:27017/?appname=example\-update\(dq; mongoc_uri_t *uri = mongoc_uri_new_with_error (uri_string, &error); if (!uri) { fprintf (stderr, \(dqfailed to parse URI: %s\en\(dq \(dqerror message: %s\en\(dq, uri_string, error.message); return EXIT_FAILURE; } client = mongoc_client_new_from_uri (uri); if (!client) { return EXIT_FAILURE; } coll = mongoc_client_get_collection (client, \(dqdb\(dq, \(dqexample_coll\(dq); mongoc_client_set_error_api (client, 2); /* insert a document */ if (!mongoc_collection_insert_one (coll, to_insert, NULL, NULL, &error)) { fprintf (stderr, \(dqinsert failed: %s\en\(dq, error.message); return EXIT_FAILURE; } if (!mongoc_collection_update_one (coll, selector, update, NULL, NULL, &error)) { fprintf (stderr, \(dqupdate failed: %s\en\(dq, error.message); return EXIT_FAILURE; } to_str = bson_as_relaxed_extended_json (to_insert, NULL); printf (\(dqinserted: %s\en\(dq, to_str); bson_free (to_str); cursor = mongoc_collection_find_with_opts (coll, selector, NULL, NULL); BSON_ASSERT (mongoc_cursor_next (cursor, &next_doc)); printf (\(dqafter update, collection has the following document:\en\(dq); to_str = bson_as_relaxed_extended_json (next_doc, NULL); printf (\(dq%s\en\(dq, to_str); bson_free (to_str); BSON_ASSERT (mongoc_collection_drop (coll, NULL)); bson_destroy (to_insert); bson_destroy (update); bson_destroy (selector); mongoc_collection_destroy (coll); mongoc_uri_destroy (uri); mongoc_client_destroy (client); return EXIT_SUCCESS; } .EE .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 .nf \fI\%MongoDB update command documentation\fP for more information on the update options. .fi .sp .nf \fI\%mongoc_collection_update_many()\fP .fi .sp .nf \fI\%mongoc_collection_replace_one()\fP .fi .sp .UNINDENT .UNINDENT .SH AUTHOR MongoDB, Inc .SH COPYRIGHT 2017-present, MongoDB, Inc .\" Generated by docutils manpage writer. .