What are Operations
-
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 Commands API. -
RavenDB provides direct access to this lower-level API, allowing you to send requests
directly to the server via DocumentStore Operations instead of using the higher-level Session API. -
In this page:
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 DocumentStoreOperationExecutor
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 thesend
method on theoperations
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:
-
Attachments:
PutAttachmentOperation
GetAttachmentOperation
DeleteAttachmentOperation -
Counters:
CounterBatchOperation
GetCountersOperation -
Time series:
TimeSeriesBatchOperation
GetMultipleTimeSeriesOperation
GetTimeSeriesOperation
GetTimeSeriesStatisticsOperation -
Revisions:
GetRevisionsOperation -
Patching:
PatchOperation
PatchByQueryOperation -
Delete by query:
DeleteByQueryOperation -
Compare-exchange:
PutCompareExchangeValueOperation
GetCompareExchangeValueOperation
GetCompareExchangeValuesOperation
DeleteCompareExchangeValueOperation
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 thesend
method on themaintenance
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:
-
Statistics:
GetStatisticsOperation
GetDetailedStatisticsOperation
GetCollectionStatisticsOperation
GetDetailedCollectionStatisticsOperation -
Client Configuration:
PutClientConfigurationOperation
GetClientConfigurationOperation -
Indexes:
PutIndexesOperation
SetIndexesLockOperation
SetIndexesPriorityOperation
GetIndexErrorsOperation
GetIndexOperation
GetIndexesOperation
GetTermsOperation
GetIndexPerformanceStatisticsOperation
GetIndexStatisticsOperation
GetIndexesStatisticsOperation
GetIndexingStatusOperation
GetIndexStalenessOperation
GetIndexNamesOperation
StartIndexOperation
StartIndexingOperation
StopIndexOperation
StopIndexingOperation
ResetIndexOperation
DeleteIndexOperation
DeleteIndexErrorsOperation
DisableIndexOperation
EnableIndexOperation
IndexHasChangedOperation -
Analyzers:
PutAnalyzersOperation
DeleteAnalyzerOperation -
Ongoing tasks:
GetOngoingTaskInfoOperation
ToggleOngoingTaskStateOperation
DeleteOngoingTaskOperation -
ETL tasks:
AddEtlOperation
UpdateEtlOperation
ResetEtlOperation -
Replication tasks:
PutPullReplicationAsHubOperation
GetPullReplicationTasksInfoOperation
GetReplicationHubAccessOperation
GetReplicationPerformanceStatisticsOperation
RegisterReplicationHubAccessOperation
UnregisterReplicationHubAccessOperation
UpdateExternalReplicationOperation
UpdatePullReplicationAsSinkOperation -
Backup:
BackupOperation
GetPeriodicBackupStatusOperation
StartBackupOperation
UpdatePeriodicBackupOperation -
Connection strings:
PutConnectionStringOperation
RemoveConnectionStringOperation
GetConnectionStringsOperation -
Transaction recording:
StartTransactionsRecordingOperation
StopTransactionsRecordingOperation
ReplayTransactionsRecordingOperation -
Database settings:
PutDatabaseSettingsOperation
GetDatabaseSettingsOperation -
Identities:
GetIdentitiesOperation
NextIdentityForOperation
SeedIdentityForOperation -
Time series:
ConfigureTimeSeriesOperation
ConfigureTimeSeriesPolicyOperation
ConfigureTimeSeriesValueNamesOperation
RemoveTimeSeriesPolicyOperation -
Revisions:
ConfigureRevisionsOperation -
Sorters:
PutSortersOperation
DeleteSorterOperation -
Sharding:
AddPrefixedShardingSettingOperation
DeletePrefixedShardingSettingOperation
UpdatePrefixedShardingSettingOperation -
Misc:
ConfigureExpirationOperation
ConfigureRefreshOperation
UpdateDocumentsCompressionConfigurationOperation
DatabaseHealthCheckOperation
GetOperationStateOperation
CreateSampleDataOperation
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 thesend
method on themaintenance.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:
-
Client certificates:
PutClientCertificateOperation
CreateClientCertificateOperation
GetCertificatesOperation
DeleteCertificateOperation
EditClientCertificateOperation
GetCertificateMetadataOperation
ReplaceClusterCertificateOperation -
Server-wide client configuration:
PutServerWideClientConfigurationOperation
GetServerWideClientConfigurationOperation -
Database management:
CreateDatabaseOperation
DeleteDatabasesOperation
ToggleDatabasesStateOperation
GetDatabaseNamesOperation
AddDatabaseNodeOperation
PromoteDatabaseNodeOperation
ReorderDatabaseMembersOperation
CompactDatabaseOperation
GetDatabaseRecordOperation
SetDatabasesLockOperation
CreateDatabaseOperationWithoutNameValidation
SetDatabaseDynamicDistributionOperation
ModifyDatabaseTopologyOperation
UpdateDatabaseOperation
UpdateUnusedDatabasesOperation -
Server-wide ongoing tasks:
DeleteServerWideTaskOperation
ToggleServerWideTaskStateOperation -
Server-wide replication tasks:
PutServerWideExternalReplicationOperation
GetServerWideExternalReplicationOperation
GetServerWideExternalReplicationsOperation -
Server-wide backup tasks:
PutServerWideBackupConfigurationOperation
GetServerWideBackupConfigurationOperation
GetServerWideBackupConfigurationsOperation
RestoreBackupOperation -
Server-wide analyzers:
PutServerWideAnalyzersOperation
DeleteServerWideAnalyzerOperation -
Server-wide sorters:
PutServerWideSortersOperation
DeleteServerWideSorterOperation -
Logs & debug:
SetLogsConfigurationOperation
GetLogsConfigurationOperation
GetClusterDebugInfoPackageOperation
GetBuildNumberOperation
GetServerWideOperationStateOperation -
Traffic watch:
PutTrafficWatchConfigurationOperation
GetTrafficWatchConfigurationOperation -
Revisions:
ConfigureRevisionsForConflictsOperation -
Misc:
ModifyConflictSolverOperation
OfflineMigrationOperation
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 thesend
method will return a promise forOperationCompletionAwaiter
object,
which can then be awaited for completion or aborted (killed).
// 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();
// 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()