What are Operations



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).

How operations work

  • Sending the request:
    Each Operation creates an 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.

Common operations

  • 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:

// Define operation, e.g. get all counters info for a document
const getCountersOp = new GetCountersOperation("products/1-A");

// Execute the operation by passing the operation to operations.send
const allCountersResult = await documentStore.operations.send(getCountersOp);

// Access the operation result
const numberOfCounters = allCountersResult.counters.length;

Send syntax:

// Available overloads:
await send(operation);
await send(operation, sessionInfo);
await send(operation, sessionInfo, documentType);

await send(patchOperaton);
await send(patchOperation, sessionInfo);
await send(patchOperation, sessionInfo, resultType);

The following common operations are available:


Maintenance operations

  • 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:

// Define operation, e.g. stop an index 
const stopIndexOp = new StopIndexOperation("Orders/ByCompany");

// Execute the operation by passing the operation to maintenance.send
await documentStore.maintenance.send(stopIndexOp);

// This specific operation returns void
// You can send another operation to verify the index running status
const indexStatsOp = new GetIndexStatisticsOperation("Orders/ByCompany");
const indexStats = await documentStore.maintenance.send(indexStatsOp);
const status = indexStats.status; // will be "Paused"

Send syntax:

await send(operation);

The following maintenance operations are available:


Server-maintenance operations

  • 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:

// Define operation, e.g. get the server build number
const getBuildNumberOp = new GetBuildNumberOperation();

// Execute the operation by passing the operation to maintenance.server.send
const buildNumberResult = await documentStore.maintenance.server.send(getBuildNumberOp);

// Access the operation result
const version = buildNumberResult.buildVersion;

Send syntax:

await send(operation);

The following server-maintenance operations are available:


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 a promise for OperationCompletionAwaiter object,
    which can then be awaited for completion or aborted (killed).


Wait for completion:

// Define operation, e.g. delete all discontinued products 
// Note: This operation implements interface: 'IOperation<OperationIdResult>'
const deleteByQueryOp = new DeleteByQueryOperation("from Products where Discontinued = true");

// Execute the operation
// 'send' returns an object that can be awaited on
const asyncOperation = await documentStore.operations.send(deleteByQueryOp);

// Call method 'waitForCompletion' to wait for the operation to complete 
await asyncOperation.waitForCompletion();

Kill operation:

// Define operation, e.g. delete all discontinued products 
// Note: This operation implements interface: 'IOperation<OperationIdResult>'
const deleteByQueryOp = new DeleteByQueryOperation("from Products where Discontinued = true");

// Execute the operation
// 'send' returns an object that can be 'killed'
const asyncOperation = await documentStore.operations.send(deleteByQueryOp);

// Call method 'kill' to abort operation
await asyncOperation.kill();

Syntax:

await waitForCompletion();
await kill()