SYNOPSIS

          mongoc_client_session_t *
          mongoc_client_start_session (mongoc_client_t *client,
                                       mongoc_session_opt_t *opts,
                                       bson_error_t *error)

       Create a session for a sequence of operations.

       Start  a  session with mongoc_client_start_session() <>, use the session for a sequence of operations and
       multi-document transactions, then free it with mongoc_client_session_destroy() <>. Any mongoc_cursor_t <>
       or mongoc_change_stream_t <> using a session must be destroyed before the session, and a session must  be
       destroyed before the mongoc_client_t <> it came from.

       By    default,    sessions    are    causally    consistent    <https://www.mongodb.com/docs/manual/core/
       read-isolation-consistency-recency/#causal-consistency>. To disable causal consistency, before starting a
       session   create   a   mongoc_session_opt_t   <>   with    mongoc_session_opts_new()    <>    and    call
       mongoc_session_opts_set_causal_consistency()  <>, then free the struct with mongoc_session_opts_destroy()
       <>.

       Unacknowledged writes are prohibited with sessions.

       A mongoc_client_session_t <> must be used by  only  one  thread  at  a  time.  Due  to  session  pooling,
       mongoc_client_start_session() <> may return a session that has been idle for some time and is about to be
       closed  after  its idle timeout. Use the session within one minute of acquiring it to refresh the session
       and avoid a timeout.

PARAMETERS

       • client: A mongoc_client_t <>.

       • opts: An optional mongoc_session_opt_t <>.

       • error: A bson_error_t <https://www.mongoc.org/libbson/current/bson_error_t.html>.

RETURNS

       If successful, this function returns a newly allocated mongoc_client_session_t <> that  should  be  freed
       with mongoc_client_session_destroy() <> when no longer in use. On error, returns NULL and sets error.

ERRORS

       This  function  can  fail if the driver is not built with crypto support, if opts is misconfigured, or if
       the session is configured with options that the server does not support.

Author

       MongoDB, Inc

Copyright

       2009-present, MongoDB, Inc.

2.2.1                                             Dec 11, 2025                    MONGOC_CLIENT_START_SESSION(3)