What are Operations

• Operations provide management functionality that is Not available in the context of the session, for example:

  • Create/delete a database
  • Execute administrative tasks
  • Assign permissions
  • Change server configuration, and more.

• The operations are executed on the DocumentStore and are Not part of the session transaction.

• There are some client tasks, such as patching documents, that can be carried out either via the Session (session.advanced.patch()) or via an Operation on the DocumentStore (PatchOperation).

• Sending the request:
  Each Operation is an encapsulation of a RavenCommand.
  The RavenCommand creates the HTTP request message to be sent to the relevant server endpoint.
  The DocumentStore OperationExecutor sends the request and processes the results.
• Target node:
  By default, the operation will be executed on the server node that is defined by the client configuration.
  However, server-maintenance operations can be executed on a specific node by using the for_node method.
• Target database:
  By default, operations work on the default database defined in the DocumentStore.
  However, common operations & maintenance operations can operate on a different database by using the for_database method.
• Transaction scope:
  Operations execute as a single-node transaction.
  If needed, data will then replicate to the other nodes in the database-group.
• Background operations:
  Some operations may take a long time to complete and can be awaited for completion.
  Learn more below.

• All common operations implement the IOperation interface.
  The operation is executed within the database scope.
  Use for_database to operate on a specific database other than the default defined in the store.

• These operations include set-based operations such as PatchOperation, CounterBatchOperation,
  document-extensions related operations such as getting/putting an attachment, and more.
  See all available operations below.

• To execute a common operation request,
  use the send method on the operations property in the DocumentStore.

Example:

# Define operation, e.g. get all counters info for a document
get_counters_op = GetCountersOperation("products/1-A")

# Execute the operation by passing the operation to operations.send
all_counters_result = store.operations.send(get_counters_op)

# Access the operation result
number_of_counters = len(all_counters_result.counters)

Syntax:

# Available overloads:
def send(self, operation: IOperation[_Operation_T], session_info: SessionInfo = None) -> _Operation_T: ...

def send_async(self, operation: IOperation[OperationIdResult]) -> Operation: ...

def send_patch_operation(self, operation: PatchOperation, session_info: SessionInfo) -> PatchStatus: ...

def send_patch_operation_with_entity_class(
    self, entity_class: _T, operation: PatchOperation, session_info: Optional[SessionInfo] = None
) -> PatchOperation.Result[_T]: ...

• All maintenance operations implement the IMaintenanceOperation interface.
  The operation is executed within the database scope.
  Use for_database to operate on a specific database other than the default defined in the store.

• These operations include database management operations such as setting client configuration,
  managing indexes & ongoing-tasks operations, getting stats, and more.
  See all available maintenance operations below.

• To execute a maintenance operation request,
  use the send method on the maintenance property in the DocumentStore.

Example:

# Define operation, e.g. stop an index
stop_index_op = StopIndexOperation("Orders/ByCompany")

# Execute the operation by passing the operation to maintenance.send
store.maintenance.send(stop_index_op)

# This specific operation returns void
# You can send another operation to verify the index running status
index_stats_op = GetIndexStatisticsOperation("Orders/ByCompany")
index_stats = store.maintenance.send(index_stats_op)
status = index_stats.status  # will be "Paused"

Syntax:

def send(
    self, operation: Union[VoidMaintenanceOperation, MaintenanceOperation[_Operation_T]]
) -> Optional[_Operation_T]: ...

def send_async(self, operation: MaintenanceOperation[OperationIdResult]) -> Operation: ...

• All server-maintenance operations implement the IServerOperation interface.
  The operation is executed within the server scope.
  Use for_node to operate on a specific node other than the default defined in the client configuration.

• These operations include server management and configuration operations.
  See all available operations below.

• To execute a server-maintenance operation request,
  use the send method on the maintenance.server property in the DocumentStore.

Example:

# Define operation, e.g. get the server build number
get_build_number_op = GetBuildNumberOperation()

# Execute the operation by passing to maintenance.server.send
build_number_result = store.maintenance.server.send(get_build_number_op)

# Access the operation result
version = build_number_result.build_version

Syntax:

def send(self, operation: ServerOperation[_T_OperationResult]) -> Optional[_T_OperationResult]: ...

def send_async(self, operation: ServerOperation[OperationIdResult]) -> Operation: ...

test_examples(self):
with self.embedded_server.get_document_store("WhatAreOperations") as store:
    # region operations_ex
    # Define operation, e.g. get all counters info for a document
    get_counters_op = GetCountersOperation("products/1-A")

    # Execute the operation by passing the operation to operations.send
    all_counters_result = store.operations.send(get_counters_op)

    # Access the operation result
    number_of_counters = len(all_counters_result.counters)