Skip to content

Latest commit

 

History

History
472 lines (350 loc) · 25.8 KB

what-are-operations.dotnet.markdown

File metadata and controls

472 lines (350 loc) · 25.8 KB
Raw

What are Operations

{NOTE: }

  • The RavenDB Client API is built with the notion of layers.
    At the top, and what you will usually interact with, are the DocumentStore and the Session.
    They in turn are built on top of the lower-level Operations and RavenCommands API.

  • RavenDB provides access to this lower-level API, so that instead of using the higher session API,
    you can generate requests directly to the server by executing operations on the DocumentStore.

  • In this page:


    * __Operation types__: * [Common operations](../../client-api/operations/what-are-operations#common-operations) * [Maintenance operations](../../client-api/operations/what-are-operations#maintenance-operations) * [Server-maintenance operations](../../client-api/operations/what-are-operations#server-maintenance-operations) * [Manage lengthy operations](../../client-api/operations/what-are-operations#manage-lengthy-operations) * [Wait for completion](../../client-api/operations/what-are-operations#wait-for-completion) * [Kill operation](../../client-api/operations/what-are-operations#killOperation)

{NOTE/}

{PANEL: Why use 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).

{PANEL/}

{PANEL: How operations work}

  • 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 ForNode 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 ForDatabase 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.

{PANEL/}

{PANEL: Common operations}

{NOTE: }

  • All common operations implement the IOperation interface.
    The operation is executed within the database scope.
    Use ForDatabase 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:

{CODE-TABS} {CODE-TAB:csharp:Sync operations_ex@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TAB:csharp:Async operations_ex_async@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TABS/}

{NOTE/}

{NOTE: }

Send syntax:

{CODE-TABS} {CODE-TAB:csharp:Sync operations_send@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TAB:csharp:Async operations_send_async@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TABS/}

{NOTE/}

{NOTE: }

The following common operations are available:

{NOTE/} {PANEL/}

{PANEL: Maintenance operations}

{NOTE: }

  • All maintenance operations implement the IMaintenanceOperation interface.
    The operation is executed within the database scope.
    Use ForDatabase 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:

{CODE-TABS} {CODE-TAB:csharp:Sync maintenance_ex@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TAB:csharp:Async maintenance_ex_async@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TABS/}

{NOTE/}

{NOTE: }

Send syntax:

{CODE-TABS} {CODE-TAB:csharp:Sync maintenance_send@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TAB:csharp:Async maintenance_send_async@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TABS/}

{NOTE/}

{NOTE: }

The following maintenance operations are available:

{NOTE/} {PANEL/}

{PANEL: Server-maintenance operations}

{NOTE: }

  • All server-maintenance operations implement the IServerOperation interface.
    The operation is executed within the server scope.
    Use ForNode 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:

{CODE-TABS} {CODE-TAB:csharp:Sync server_ex@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TAB:csharp:Async server_ex_async@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TABS/}

{NOTE/}

{NOTE: }

Send syntax:

{CODE-TABS} {CODE-TAB:csharp:Sync server_send@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TAB:csharp:Async server_send_async@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TABS/}

{NOTE/}

{NOTE: }

The following server-maintenance operations are available:

{NOTE/} {PANEL/}

{PANEL: Manage lengthy operations}

  • Some operations that run in the server background may take a long time to complete.

  • For Operations that implement an interface with type OperationIdResult,
    executing the operation via the Send method will return an Operation object,
    which can be awaited for completion or aborted (killed).

{NOTE: }

Wait for completion:

{CODE-TABS} {CODE-TAB:csharp:With_Timeout wait_timeout_ex@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TAB:csharp:With_Timout_async wait_timeout_ex_async@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TAB:csharp:With_CancellationToken wait_token_ex@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TAB:csharp:With_CancellationToken_async wait_token_ex_async@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TABS/}

Syntax:

{CODE-TABS} {CODE-TAB:csharp:Sync waitForCompletion_syntax@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TAB:csharp:Async waitForCompletion_syntax_async@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TABS/}

Parameter Type Description
timeout TimeSpan
  • When timespan is specified -
    The server will throw a TimeoutException if operation has Not completed within the specified time frame.
    The operation itself continues to run in the background,
    no rollback action takes place.
  • null -
    WaitForCompletion will wait for operation to complete forever.
token CancellationToken
  • When cancellation token is specified -
    The server will throw a TimeoutException if operation has Not completed at cancellation time.
    The operation itself continues to run in the background,
    no rollback action takes place.
Return type
IOperationResult The operation result content.

{NOTE/}

{NOTE: }

Kill operation:

{CODE-TABS} {CODE-TAB:csharp:Kill kill_ex@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TAB:csharp:Kill_async kill_ex_async@ClientApi\Operations\WhatAreOperations.cs /} {CODE-TABS/}

Syntax:

{CODE kill_syntax@ClientApi\Operations\WhatAreOperations.cs /}

Parameter Type Description
token CancellationToken Provide a cancellation token if needed to abort the KillAsync method

{NOTE/} {PANEL/}

Related articles

Document Store

Operations