Session: Saving changes

Pending session operations e.g. store, delete and many others will not be send to the server until save_changes is called.

Whenever you execute save_changes() to send a batch of operations like put, update, or delete in a request,
the server will wrap these operations in a transaction upon execution in the database.

Either all operations will be saved as a single, atomic transaction or none of them will be.
Once save_changes() returns successfully, it is guaranteed that all changes are persisted in the database.

Syntax

def save_changes(self) -> None:
    ...

Example

session.store(Employee(first_name="John", last_name="Doe"))

session.save_changes()

Waiting for Indexes

You can ask the server to wait until the indexes are caught up with changes made within the current session before the save_changes returns.

  • You can set a timeout (default: 15 seconds).
  • You can specify whether you want to throw on timeout (default: False).
  • You can specify indexes that you want to wait for. If you don't specify anything here, RavenDB will automatically select just the indexes that are impacted by this write.

def _build_wait(idx_wait_opt_builder: InMemoryDocumentSessionOperations.IndexesWaitOptsBuilder) -> None:
    idx_wait_opt_builder.with_timeout(timedelta(seconds=30))
    idx_wait_opt_builder.throw_on_timeout(True)
    idx_wait_opt_builder.wait_for_indexes("index/1", "index/2")

# this function can be also passed as a lambda
session.advanced.wait_for_indexes_after_save_changes(_build_wait)

session.store(Employee(first_name="John", last_name="Doe"))

session.save_changes()

Waiting for Replication - Write Assurance

Sometimes you might need to ensure that changes made in the session will be replicated to more than one node of the cluster before the save_changes returns. It can be useful if you have some writes that are really important so you want to be sure the stored values will reside on multiple machines. Also it might be necessary to use when you customize the read balance behavior and need to ensure the next request from the user will be able to read what he or she just wrote (the next open session might access a different node).

You can ask the server to wait until the replication is caught up with those particular changes.

  • You can set a timeout (default: 15 seconds).
  • You can specify whether you want to throw on timeout, which may happen in case of network issues (default: True).
  • You can specify to how many replicas (nodes) the currently saved write must be replicated, before the save_changes returns (default: 1).
  • You can specify whether the save_changes will return only when the current write was replicated to majority of the nodes (default: False).

def _build_wait(
    repl_wait_builder: InMemoryDocumentSessionOperations.ReplicationWaitOptsBuilder,
) -> None:
    repl_wait_builder.with_timeout(timedelta(seconds=30))
    repl_wait_builder.throw_on_timeout(False)  # default True
    repl_wait_builder.number_of_replicas(2)  # minimum replicas to replicate
    repl_wait_builder.majority(False)

# this function can be also passed as a lambda
session.advanced.wait_for_replication_after_save_changes(_build_wait)

session.store(Employee(first_name="John", last_name="Doe"))
session.save_changes()

Important

The wait_for_replication_after_save_changes method waits only for replicas which are part of the cluster. It means that external replication destinations are not counted towards the number specified in replicas parameter, since they are not part of the cluster.

Important

Even if RavenDB was not able to write your changes to the number of replicas you specified, the data has been already written to some nodes. You will get an error but data is already there.

This is a powerful feature, but you need to be aware of the possible pitfalls of using it.

Transaction Mode - Cluster Wide

Setting TransactionMode to TransactionMode.CLUSTER_WIDE will enable the Cluster Transactions feature.

With this feature enabled the session will support the following write commands:

  • store
  • delete
  • create_compare_exchange_value
  • update_compare_exchange_value
  • delete_compare_exchange_value

Here is an example of creating a unique user with cluster wide.

DocumentStore = DocumentStoreFake
with DocumentStore() as store:
    with store.open_session(
        session_options=SessionOptions(
            # default is:    TransactionMode.SINGLE_NODE
            transaction_mode=TransactionMode.CLUSTER_WIDE
        )
    ) as session:
        user = Employee(first_name="John", last_name="Doe")
        session.store(user)

        # this transaction is now conditional on this being
        # successfully created (so, no other users with this name)
        # it also creates an association to the new user's id
        session.advanced.cluster_transaction.create_compare_exchange_value("usernames/John", user.Id)

        session.save_changes()