diff --git a/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.dotnet.markdown index 7fcc7dcdf3..643cd34943 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.dotnet.markdown @@ -6,7 +6,7 @@ * Use `DeleteByQueryOperation` to delete a large number of documents that match the provided query in a single server call. * **Dynamic behavior**: - The deletion of documents matching the specified query is run in batches of size 1024. + The deletion of documents matching the specified query is performed in batches of size 1024. During the deletion process, documents that are added/modified **after** the delete operation has started may also be deleted if they match the query criteria. diff --git a/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.js.markdown index 9d0a4e8df6..287eeef906 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.js.markdown @@ -5,14 +5,14 @@ * Use `DeleteByQueryOperation` to delete a large number of documents that match the provided query in a single server call. -* __Dynamic behavior__: - The deletion of documents matching the specified query is run in batches of size 1024. - During the deletion process, documents that are added/modified __after__ the delete operation has started +* **Dynamic behavior**: + The deletion of documents matching the specified query is performed in batches of size 1024. + During the deletion process, documents that are added/modified **after** the delete operation has started may also be deleted if they match the query criteria. -* __Background operation__: +* **Background operation**: This operation is performed in the background on the server. - If needed, you can __wait__ for the operation to complete. See: [Wait for completion](../../../client-api/operations/what-are-operations#wait-for-completion). + If needed, you can **wait** for the operation to complete. See: [Wait for completion](../../../client-api/operations/what-are-operations#wait-for-completion). * In this page: * [Delete by dynamic query](../../../client-api/operations/common/delete-by-query#delete-by-dynamic-query) @@ -25,7 +25,7 @@ {NOTE: } -__Delete all documents in collection__: +**Delete all documents in collection**: {CODE-TABS} {CODE-TAB:nodejs:DeleteOperation delete_by_query_0@client-api\Operations\Common\deleteByQuery.js /} @@ -38,7 +38,7 @@ from "Orders" {NOTE: } -__Delete with filtering__: +**Delete with filtering**: {CODE-TABS} {CODE-TAB:nodejs:DeleteOperation delete_by_query_1@client-api\Operations\Common\deleteByQuery.js /} @@ -53,7 +53,7 @@ from "Orders" where Freight > 30 {PANEL: Delete by index query} -* `DeleteByQueryOperation` can only be performed on a __Map-index__. +* `DeleteByQueryOperation` can only be performed on a **Map-index**. An exception is thrown when executing the operation on a Map-Reduce index. * A few overloads are available, see the following examples: @@ -62,7 +62,7 @@ from "Orders" where Freight > 30 {NOTE: } -__A sample Map-index__: +**A sample Map-index**: {CODE:nodejs the_index@client-api\Operations\Common\deleteByQuery.js /} @@ -70,7 +70,7 @@ __A sample Map-index__: {NOTE: } -__Delete documents via an index query__: +**Delete documents via an index query**: {CODE-TABS} {CODE-TAB:nodejs:DeleteOperation delete_by_query_2@client-api\Operations\Common\deleteByQuery.js /} @@ -84,7 +84,7 @@ from index "Products/ByPrice" where Price > 10 {NOTE: } -__Delete with options__: +**Delete with options**: {CODE-TABS} {CODE-TAB:nodejs:DeleteOperation delete_by_query_4@client-api\Operations\Common\deleteByQuery.js /} @@ -106,9 +106,9 @@ from index "Products/ByPrice" where Price > 10 | Parameter | Type | Description | |-------------------|-----------------------------|------------------------------------------------------------| -| __queryToDelete__ | string | The RQL query to perform | -| __queryToDelete__ | `IndexQuery` | Holds all the information required to query an index | -| __options__ | `object` | Object holding different setting options for the operation | +| **queryToDelete** | `string` | The RQL query to perform | +| **queryToDelete** | `IndexQuery` | Holds all the information required to query an index | +| **options** | `object` | Object holding different setting options for the operation | {CODE:nodejs syntax_2@client-api\Operations\Common\DeleteByQuery.js /} diff --git a/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.php.markdown b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.php.markdown new file mode 100644 index 0000000000..a6ea51ef21 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.php.markdown @@ -0,0 +1,114 @@ +# Delete by Query Operation +--- + +{NOTE: } + +* Use `DeleteByQueryOperation` to delete a large number of documents that match the provided query in a single server call. + +* **Dynamic behavior**: + The deletion of documents matching the specified query is performed in batches of size 1024. + During the deletion process, documents that are added/modified **after** the delete operation has started + may also be deleted if they match the query criteria. + +* **Background operation**: + This operation is performed in the background on the server. + +* In this page: + * [Delete by dynamic query](../../../client-api/operations/common/delete-by-query#delete-by-dynamic-query) + * [Delete by index query](../../../client-api/operations/common/delete-by-query#delete-by-index-query) + * [Syntax](../../../client-api/operations/common/delete-by-query#syntax) + +{NOTE/} + +{PANEL: Delete by dynamic query} + +#### Delete all documents in a collection: + +{CODE-TABS} +{CODE-TAB:php:DeleteByQueryOperation delete_by_query_0@ClientApi\Operations\Common\DeleteByQuery.php /} +{CODE-TAB-BLOCK:sql:RQL} +from "Orders" +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +--- + +#### Delete with filtering: + +{CODE-TABS} +{CODE-TAB:php:DeleteByQueryOperation delete_by_query_1@ClientApi\Operations\Common\DeleteByQuery.php /} +{CODE-TAB-BLOCK:sql:RQL} +from "Orders" where Freight > 30 +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{PANEL/} + +{PANEL: Delete by index query} + +* `DeleteByQueryOperation` can only be performed on a **Map-index**. + An exception is thrown when executing the operation on a Map-Reduce index. + +* A few overloads are available, see the following examples: + +--- + +#### A sample Map-index: + +{CODE:php the_index@ClientApi\Operations\Common\DeleteByQuery.php /} + +--- + +#### Delete documents via an index query: + +{CODE-TABS} +{CODE-TAB:php:RQL delete_by_query_2@ClientApi\Operations\Common\DeleteByQuery.php /} +{CODE-TAB:php:IndexQuery delete_by_query_3@ClientApi\Operations\Common\DeleteByQuery.php /} +{CODE-TAB-BLOCK:sql:RQL} +from index "Products/ByPrice" where Price > 10 +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +--- + +#### Delete with options: + +{CODE-TABS} +{CODE-TAB:php:QueryOperationOptions delete_by_query_6@ClientApi\Operations\Common\DeleteByQuery.php /} +{CODE-TAB-BLOCK:sql:RQL} +from index "Products/ByPrice" where Price > 10 +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{PANEL/} + +{PANEL: Syntax} + +{CODE:php syntax_1@ClientApi\Operations\Common\DeleteByQuery.php /} +
+ +| Parameter | Type | Description | +|-------------------|---------------------------|--------------------------| +| **$queryToDelete** | `string` | The RQL query to perform | +| **$queryToDelete** | `IndexQuery` | Holds all the information required to query an index | +| **$options** | `?QueryOperationOptions` | Object holding different setting options for the operation | + +{CODE:php syntax_2@ClientApi\Operations\Common\DeleteByQuery.php /} + +{PANEL/} + + +## Related Articles + +### Operations + +- [What are Operations](../../../client-api/operations/what-are-operations) + +### Client API + +- [How to Query](../../../client-api/session/querying/how-to-query) + +### Querying + +- [What is RQL](../../../client-api/session/querying/what-is-rql) +- [Querying an index](../../../indexes/querying/query-index) diff --git a/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.python.markdown index 934a34ea54..42ecbb0303 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.python.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/common/delete-by-query.python.markdown @@ -6,7 +6,7 @@ * Use `DeleteByQueryOperation` to delete a large number of documents that match the provided query in a single server call. * **Dynamic behavior**: - The deletion of documents matching the specified query is run in batches of size 1024. + The deletion of documents matching the specified query is performed in batches of size 1024. During the deletion process, documents that are added/modified **after** the delete operation has started may also be deleted if they match the query criteria. diff --git a/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/compare-exchange/overview.php.markdown b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/compare-exchange/overview.php.markdown new file mode 100644 index 0000000000..54e288a373 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/compare-exchange/overview.php.markdown @@ -0,0 +1,185 @@ +# Compare Exchange Overview +--- + +{NOTE: } + +* Compare Exchange items are **key/value pairs** where the key is unique across your database. + +* Compare-exchange operations require cluster consensus to ensure consistency across all nodes. + Once a consensus is reached, the compare-exchange items are distributed through the Raft algorithm to all nodes in the database group. + +* Compare-exchange items can be used to coordinate work between sessions that are trying to modify a shared resource (such as a document) at the same time. + +* Compare-exchange items are [not replicated externally](../../../client-api/operations/compare-exchange/overview#why-compare-exchange-items-are-not-replicated-to-external-databases) to other databases. + +* In this page: +* [What Compare Exchange Items Are](../../../client-api/operations/compare-exchange/overview#what-compare-exchange-items-are) +* [Creating and Managing Compare-Exchange Items](../../../client-api/operations/compare-exchange/overview#creating-and-managing-compare-exchange-items) +* [Why Compare-Exchange Items are Not Replicated to External Databases](../../../client-api/operations/compare-exchange/overview#why-compare-exchange-items-are-not-replicated-to-external-databases) +* [Example I - Email Address Reservation](../../../client-api/operations/compare-exchange/overview#example-i---email-address-reservation) +* [Example II - Reserve a Shared Resource](../../../client-api/operations/compare-exchange/overview#example-ii---reserve-a-shared-resource) +* [Example III - Ensuring Unique Values without Using Compare Exchange](../../../client-api/operations/compare-exchange/overview#example-iii---ensuring-unique-values-without-using-compare-exchange) + +{NOTE/} + +--- + +{PANEL: What Compare Exchange Items Are} + +Compare Exchange items are key/value pairs where the key servers a unique value across your database. + +* Each compare-exchange item contains: + * **A key** - A unique string identifier in the database scope. + * **A value** - Can be any object (a number, string, array, or any valid JSON object). + * **Metadata** - Data that is associated with the compare-exchange item. + Must be a valid JSON object. + * For example, the metadata can be used to set expiration time for the compare-exchange item. + Learn more in [compare-exchange expiration](../../../client-api/operations/compare-exchange/compare-exchange-expiration). + * **Raft index** - The compare-exchange item's version. + Any change to the value or metadata will increase this number. + +* Creating and modifying a compare-exchange item is an atomic, thread-safe [compare-and-swap](https://en.wikipedia.org/wiki/Compare-and-swap) interlocked + compare-exchange operation. + +{PANEL/} + +{PANEL: Creating and Managing Compare-Exchange Items} + +Compare exchange items are created and managed with any of the following approaches: + +* **Document Store Operations** + You can manage a compare-exchange item as an [Operation on the document store](../../../client-api/operations/compare-exchange/put-compare-exchange-value). + This can be done within or outside of a session (cluster-wide or single-node session). + * When inside a session: + If the session fails, the compare-exchange operation can still succeed + because store Operations do not rely on the success of the session. + You will need to delete the compare-exchange item explicitly upon session failure if you don't want the compare-exchange item to persist. + +* **Cluster-Wide Sessions** + You can manage a compare-exchange item from inside a [Cluster-Wide session](../../../client-api/session/cluster-transaction/compare-exchange). + If the session fails, the compare-exchange item creation also fails. + None of the nodes in the group will have the new compare-exchange item. + + +* **Atomic Guards** + When creating documents using a cluster-wide session RavenDB automatically creates [Atomic Guards](../../../client-api/session/cluster-transaction/atomic-guards), + which are compare-exchange items that guarantee ACID transactions. + See [Cluster-wide vs. Single-node](../../../client-api/session/cluster-transaction/overview#cluster-wide-transaction-vs.-single-node-transaction) for a session comparision overview. + +* **Studio** + Compare-exchange items can be created from the [Studio](../../../studio/database/documents/compare-exchange-view#the-compare-exchange-view) as well. + +{PANEL/} + +{PANEL: Why Compare-Exchange Items are Not Replicated to External Databases } + +* Each cluster defines its policies and configurations, and should ideally have sole responsibility for managing its own documents. + Read [Consistency in a Globally Distributed System](https://ayende.com/blog/196769-B/data-ownership-in-a-distributed-system) + to learn more about why global database modeling is more efficient this way. + +* When creating a compare-exchange item a Raft consensus is required from the nodes in the database group. + Externally replicating such data is problematic as the target database may reside within a cluster that is in an + unstable state where Raft decisions cannot be made. In such a state, the compare-exchange item will not be persisted in the target database. + +* Conflicts between documents that occur between two databases are solved with the help of the documents + Change-Vector. Compare-exchange conflicts cannot be handled properly as they do not have a similar + mechanism to resolve conflicts. + +* To ensure unique values between two databases without using compare-exchange items see [Example III](../../../client-api/operations/compare-exchange/overview#example-iii---ensuring-unique-values-without-using-compare-exchange). + +{PANEL/} + +{PANEL: Example I - Email Address Reservation} + +The following example shows how to use compare-exchange to create documents with unique values. +The scope is within the database group on a single cluster. + +Compare-exchange items are not externally replicated to other databases. +To establish uniqueness without using compare-exchange see [Example III](../../../client-api/operations/compare-exchange/overview#example-iii---ensuring-unique-values-without-using-compare-exchange). + +{CODE:php email@Server\CompareExchange.php /} + +**Implications**: + +* The `User` object is saved as a document, hence it can be indexed, queried, etc. + +* This compare-exchange item was [created as an operation](../../../client-api/operations/compare-exchange/put-compare-exchange-value) + rather than with a [cluster-wide session](../../../client-api/session/cluster-transaction/overview). + Thus, if `session.saveChanges` fails, then the email reservation is _not_ rolled back automatically. + It is your responsibility to do so. + +* The compare-exchange value that was saved can be accessed in a query using `CmpXchg`: + {CODE-TABS} + {CODE-TAB:php:query query_cmpxchg@Server\CompareExchange.php /} + {CODE-TAB:php:documentQuery document_query_cmpxchg@Server\CompareExchange.php /} + {CODE-TAB-BLOCK:sql:RQL} + from Users as s where id() == cmpxchg("emails/ayende@ayende.com") + {CODE-TAB-BLOCK/} + {CODE-TABS/} + {PANEL/} + +{PANEL: Example II - Reserve a Shared Resource} + +In the following example, we use compare-exchange to reserve a shared resource. +The scope is within the database group on a single cluster. + +The code also checks for clients which never release resources (i.e. due to failure) by using timeout. + +{CODE:php shared_resource@Server\CompareExchange.php /} + +{PANEL/} + +{PANEL: Example III - Ensuring Unique Values without Using Compare Exchange} + +Unique values can also be ensured without using compare-exchange. + +The below example shows how to achieve that by using **reference documents**. +The reference documents' IDs will contain the unique values instead of the compare-exchange items. + +Using reference documents is especially useful when [External Replication](../../../server/ongoing-tasks/external-replication) +is defined between two databases that need to be synced with unique values. +The reference documents will replicate to the destination database, +as opposed to compare-exchange items, which are not externally replicated. + +{NOTE: } +Sessions which process fields that must be unique should be set to [TransactionMode::clusterWide()](../../../client-api/session/cluster-transaction/overview). +{NOTE/} + +{CODE:php create_uniqueness_control_documents@Server\CompareExchange.php /} +{PANEL/} + +## Related Articles + +### Client API + +- [Get a Compare-Exchange Value](../../../client-api/operations/compare-exchange/get-compare-exchange-value) +- [Get Compare-Exchange Values](../../../client-api/operations/compare-exchange/get-compare-exchange-values) +- [Put a Compare-Exchange Value](../../../client-api/operations/compare-exchange/delete-compare-exchange-value) +- [Delete a Compare-Exchange Value](../../../client-api/operations/compare-exchange/delete-compare-exchange-value) +- [Atomic Guards](../../../client-api/session/cluster-transaction/atomic-guards) +- [Resolving Document Conflicts](../../../client-api/cluster/document-conflicts-in-client-side) + + +### Studio + +- [Compare Exchange View](../../../studio/database/documents/compare-exchange-view) + +### Server + +- [Conflict Resolution](../../../server/clustering/replication/replication-conflicts) +- [Cluster-Wide Transactions](../../../server/clustering/cluster-transactions) + +--- + +### Code Walkthrough + +- [Create CmpXchg Item](https://demo.ravendb.net/demos/python/compare-exchange/create-compare-exchange) +- [Index CmpXchg Values](https://demo.ravendb.net/demos/python/compare-exchange/index-compare-exchange) + +--- + +### Ayende @ Rahien Blog + +- [Consistency in a Globally Distributed System](https://ayende.com/blog/196769-B/data-ownership-in-a-distributed-system) + + diff --git a/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/maintenance/get-stats.php.markdown b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/maintenance/get-stats.php.markdown new file mode 100644 index 0000000000..857dd1e802 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/maintenance/get-stats.php.markdown @@ -0,0 +1,95 @@ +# Get Statistics + +--- + +{NOTE: } + +* Statistics can be retrieved for the database and for collections. + +* By default, statistics are retrieved for the database defined in the Document Store. + To get database and collection statistics for another database use [forDatabase](../../../client-api/operations/maintenance/get-stats#get-stats-for-another-database). + +* In this page: + * [Get collection statistics](../../../client-api/operations/maintenance/get-stats#get-collection-statistics) + * [Get detailed collection statistics](../../../client-api/operations/maintenance/get-stats#get-detailed-collection-statistics) + * [Get database statistics](../../../client-api/operations/maintenance/get-stats#get-database-statistics) + * [Get detailed database statistics](../../../client-api/operations/maintenance/get-stats#get-detailed-database-statistics) + * [Get statistics for another database](../../../client-api/operations/maintenance/get-stats#get-statistics-for-another-database) +{NOTE/} + +--- + +{PANEL: Get collection statistics} + +To get **collection statistics**, use `GetCollectionStatisticsOperation`: +{CODE:php stats_1@ClientApi\Operations\Maintenance\GetStats.php /} + +--- + +Statistics are returned in the `CollectionStatistics` object. +{CODE:php stats_1_results@ClientApi\Operations\Maintenance\GetStats.php /} + +{PANEL/} + +{PANEL: Get detailed collection statistics} + +To get **detailed collection statistics**, use `GetDetailedCollectionStatisticsOperation`: +{CODE:php stats_2@ClientApi\Operations\Maintenance\GetStats.php /} + +--- + +Statistics are returned in the `DetailedCollectionStatistics` object. +{CODE:php stats_2_results@ClientApi\Operations\Maintenance\GetStats.php /} + +{PANEL/} + +{PANEL: Get database statistics} + +To get **database statistics**, use `GetStatisticsOperation`: +{CODE:php stats_3@ClientApi\Operations\Maintenance\GetStats.php /} + +--- + +Statistics are returned in the `DatabaseStatistics` object. +{CODE:php stats_3_results@ClientApi\Operations\Maintenance\GetStats.php /} + +{PANEL/} + +{PANEL: Get detailed database statistics} + +To get **detailed database statistics**, use `GetDetailedStatisticsOperation`: +{CODE:php stats_4@ClientApi\Operations\Maintenance\GetStats.php /} + +--- + +Statistics are returned in the `DetailedDatabaseStatistics` object. +{CODE:php stats_4_results@ClientApi\Operations\Maintenance\GetStats.php /} + +{PANEL/} + +{PANEL: Get statistics for another database} + +* By default, you get statistics for the database defined in your Document Store. +* Use `forDatabase` to get database and collection statistics for another database. +* `forDatabase` can be used with **any** of the above statistics options. + +{CODE:php stats_5@ClientApi\Operations\Maintenance\GetStats.php /} + +* Learn more about switching operations to another database [here](../../../client-api/operations/how-to/switch-operations-to-a-different-database). + +{PANEL/} + +## Related Articles + +### Operations + +- [What are Operations](../../../client-api/operations/what-are-operations) +- [Switch operation to another database](../../../client-api/operations/how-to/switch-operations-to-a-different-database) + +### FAQ + +- [What is a Collection](../../../client-api/faq/what-is-a-collection) + +### Client API + +- [Get Query Statistics](../../../client-api/session/querying/how-to-get-query-statistics) diff --git a/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/what-are-operations.php.markdown b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/what-are-operations.php.markdown new file mode 100644 index 0000000000..c8eab34979 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/what-are-operations.php.markdown @@ -0,0 +1,395 @@ +# 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](../../client-api/what-is-a-document-store)** + and the **[session](../../client-api/session/what-is-a-session-and-how-does-it-work)**. + 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](../../client-api/operations/what-are-operations#why-use-operations) + * [How operations work](../../client-api/operations/what-are-operations#how-operations-work) +
+ * **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) + +{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()](../../client-api/operations/patching/single-document#array-manipulation)) + or via an Operation on the DocumentStore ([PatchOperation](../../client-api/operations/patching/single-document#operations-api)). + +{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](../../client-api/configuration/load-balance/overview#client-logic-for-choosing-a-node). + However, server-maintenance operations can be executed on a specific node by using the [forNode](../../client-api/operations/how-to/switch-operations-to-a-different-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 [forDatabase](../../client-api/operations/how-to/switch-operations-to-a-different-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](../../client-api/operations/what-are-operations#wait-for-completion). + +{PANEL/} + +{PANEL: Common operations} + +* All common operations implement the `IOperation` interface. + The operation is executed within the **database scope**. + Use [forDatabase](../../client-api/operations/how-to/switch-operations-to-a-different-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](../../client-api/operations/what-are-operations#operations-list). + +* To execute a common operation request, + use the `send` method on the `operations` property in the DocumentStore. + +#### Example: + +{CODE:php operations_ex@ClientApi\Operations\WhatAreOperations.php /} + +##### Syntax: + +{CODE:php operations_send@ClientApi\Operations\WhatAreOperations.php /} + +{NOTE: } + + **The following common operations are available:** + +--- + +* **Attachments**: +        [PutAttachmentOperation](../../client-api/operations/attachments/put-attachment) +        [GetAttachmentOperation](../../client-api/operations/attachments/get-attachment) +        [DeleteAttachmentOperation](../../client-api/operations/attachments/delete-attachment) + +* **Counters**: +        [CounterBatchOperation](../../client-api/operations/counters/counter-batch) +        [GetCountersOperation](../../client-api/operations/counters/get-counters) + +* **Time series**: +        [TimeSeriesBatchOperation](../../document-extensions/timeseries/client-api/operations/append-and-delete) +        [GetMultipleTimeSeriesOperation](../../document-extensions/timeseries/client-api/operations/get) +        [GetTimeSeriesOperation](../../document-extensions/timeseries/client-api/operations/get) +        GetTimeSeriesStatisticsOperation + +* **Revisions**: +        [GetRevisionsOperation](../../document-extensions/revisions/client-api/operations/get-revisions) + +* **Patching**: +        [PatchOperation](../../client-api/operations/patching/single-document) +        [PatchByQueryOperation](../../client-api/operations/patching/set-based) + +* **Delete by query**: +        [DeleteByQueryOperation](../../client-api/operations/common/delete-by-query) + +* **Compare-exchange**: +        [PutCompareExchangeValueOperation](../../client-api/operations/compare-exchange/put-compare-exchange-value) +        [GetCompareExchangeValueOperation](../../client-api/operations/compare-exchange/get-compare-exchange-value) +        [GetCompareExchangeValuesOperation](../../client-api/operations/compare-exchange/get-compare-exchange-values) +        [DeleteCompareExchangeValueOperation](../../client-api/operations/compare-exchange/delete-compare-exchange-value) + +{NOTE/} +{PANEL/} + +{PANEL: Maintenance operations} + +* All maintenance operations implement the `IMaintenanceOperation` interface. + The operation is executed within the **database scope**. + Use [forDatabase](../../client-api/operations/how-to/switch-operations-to-a-different-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](../../client-api/operations/what-are-operations#maintenance-list). + +* To execute a maintenance operation request, + use the `send` method on the `maintenance` property in the DocumentStore. + +#### Example: + +{CODE:php maintenance_ex@ClientApi\Operations\WhatAreOperations.php /} + +##### Syntax: + +{CODE:php maintenance_send@ClientApi\Operations\WhatAreOperations.php /} + +{NOTE: } + + **The following maintenance operations are available:** + +--- + +* **Statistics**: +        [GetStatisticsOperation](../../client-api/operations/maintenance/get-stats#get-database-stats) +        [GetDetailedStatisticsOperation](../../client-api/operations/maintenance/get-stats#get-detailed-database-stats) +        [GetCollectionStatisticsOperation](../../client-api/operations/maintenance/get-stats#get-collection-stats) +        [GetDetailedCollectionStatisticsOperation](../../client-api/operations/maintenance/get-stats#get-detailed-collection-stats) + +* **Client Configuration**: +        [PutClientConfigurationOperation](../../client-api/operations/maintenance/configuration/put-client-configuration) +        [GetClientConfigurationOperation](../../client-api/operations/maintenance/configuration/get-client-configuration) + +* **Indexes**: +        [PutIndexesOperation](../../client-api/operations/maintenance/indexes/put-indexes) +        [SetIndexesLockOperation](../../client-api/operations/maintenance/indexes/set-index-lock) +        [SetIndexesPriorityOperation](../../client-api/operations/maintenance/indexes/set-index-priority) +        [GetIndexErrorsOperation](../../client-api/operations/maintenance/indexes/get-index-errors) +        [GetIndexOperation](../../client-api/operations/maintenance/indexes/get-index) +        [GetIndexesOperation](../../client-api/operations/maintenance/indexes/get-indexes) +        [GetTermsOperation](../../client-api/operations/maintenance/indexes/get-terms) +        GetIndexPerformanceStatisticsOperation +        GetIndexStatisticsOperation +        GetIndexesStatisticsOperation +        GetIndexingStatusOperation +        GetIndexStalenessOperation +        [GetIndexNamesOperation](../../client-api/operations/maintenance/indexes/get-index-names) +        [StartIndexOperation](../../client-api/operations/maintenance/indexes/start-index) +        [StartIndexingOperation](../../client-api/operations/maintenance/indexes/start-indexing) +        [StopIndexOperation](../../client-api/operations/maintenance/indexes/stop-index) +        [StopIndexingOperation](../../client-api/operations/maintenance/indexes/stop-indexing) +        [ResetIndexOperation](../../client-api/operations/maintenance/indexes/reset-index) +        [DeleteIndexOperation](../../client-api/operations/maintenance/indexes/delete-index) +        [DeleteIndexErrorsOperation](../../client-api/operations/maintenance/indexes/delete-index-errors) +        [DisableIndexOperation](../../client-api/operations/maintenance/indexes/disable-index) +        [EnableIndexOperation](../../client-api/operations/maintenance/indexes/enable-index) +        [IndexHasChangedOperation](../../client-api/operations/maintenance/indexes/index-has-changed) + +* **Analyzers**: +        PutAnalyzersOperation +        DeleteAnalyzerOperation + +* **Ongoing tasks**: +        GetOngoingTaskInfoOperation +        DeleteOngoingTaskOperation +        ToggleOngoingTaskStateOperation + +* **ETL tasks**: +        AddEtlOperation +        UpdateEtlOperation +        [ResetEtlOperation](../../client-api/operations/maintenance/etl/reset-etl) + +* **Replication tasks**: +        PutPullReplicationAsHubOperation +        GetPullReplicationTasksInfoOperation +        GetReplicationHubAccessOperation +        GetReplicationPerformanceStatisticsOperation +        RegisterReplicationHubAccessOperation +        UnregisterReplicationHubAccessOperation +        UpdateExternalReplicationOperation +        UpdatePullReplicationAsSinkOperation + +* **Backup**: +        BackupOperation +        GetPeriodicBackupStatusOperation +        StartBackupOperation +        UpdatePeriodicBackupOperation + +* **Connection strings**: +        PutConnectionStringOperation +        RemoveConnectionStringOperation + +* **Transaction recording**: +        StartTransactionsRecordingOperation +        StopTransactionsRecordingOperation +        ReplayTransactionsRecordingOperation + +* **Database settings**: +        [PutDatabaseSettingsOperation](../../client-api/operations/maintenance/configuration/database-settings-operation#put-database-settings-operation) +        [GetDatabaseSettingsOperation](../../client-api/operations/maintenance/configuration/database-settings-operation#get-database-settings-operation) + +* **Identities**: +        [GetIdentitiesOperation](../../client-api/operations/maintenance/identities/get-identities) +        [NextIdentityForOperation](../../client-api/operations/maintenance/identities/increment-next-identity) +        [SeedIdentityForOperation](../../client-api/operations/maintenance/identities/seed-identity) + +* **Time series**: +        ConfigureTimeSeriesOperation +        ConfigureTimeSeriesPolicyOperation +        ConfigureTimeSeriesValueNamesOperation +        RemoveTimeSeriesPolicyOperation + +* **Revisions**: +        [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions) + +* **Sorters**: +        [PutSortersOperation](../../client-api/operations/maintenance/sorters/put-sorter) +        DeleteSorterOperation + +* **Misc**: +        ConfigureExpirationOperation +        ConfigureRefreshOperation +        UpdateDocumentsCompressionConfigurationOperation +        DatabaseHealthCheckOperation +        GetOperationStateOperation +        CreateSampleDataOperation + +{NOTE/} +{PANEL/} + +{PANEL: Server-maintenance operations} + +* All server-maintenance operations implement the `IServerOperation` interface. + The operation is executed within the **server scope**. + Use [forNode](../../client-api/operations/how-to/switch-operations-to-a-different-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](../../client-api/operations/what-are-operations#server-list). + +* To execute a server-maintenance operation request, + use the `send` method on the `maintenance.server` property in the DocumentStore. + +#### Example: + +{CODE:php server_ex@ClientApi\Operations\WhatAreOperations.php /} + +##### Syntax: + +{CODE:php server_send@ClientApi\Operations\WhatAreOperations.php /} + +{NOTE: } + + **The following server-maintenance operations are available:** + +--- + +* **Client certificates**: +        [PutClientCertificateOperation](../../client-api/operations/server-wide/certificates/put-client-certificate) +        [CreateClientCertificateOperation](../../client-api/operations/server-wide/certificates/create-client-certificate) +        [GetCertificatesOperation](../../client-api/operations/server-wide/certificates/get-certificates) +        [DeleteCertificateOperation](../../client-api/operations/server-wide/certificates/delete-certificate) +        EditClientCertificateOperation +        GetCertificateMetadataOperation +        ReplaceClusterCertificateOperation + +* **Server-wide client configuration**: +        [PutServerWideClientConfigurationOperation](../../client-api/operations/server-wide/configuration/put-serverwide-client-configuration) +        [GetServerWideClientConfigurationOperation](../../client-api/operations/server-wide/configuration/get-serverwide-client-configuration) + +* **Database management**: +        [CreateDatabaseOperation](../../client-api/operations/server-wide/create-database) +        [DeleteDatabasesOperation](../../client-api/operations/server-wide/delete-database) +        [ToggleDatabasesStateOperation](../../client-api/operations/server-wide/toggle-databases-state) +        [GetDatabaseNamesOperation](../../client-api/operations/server-wide/get-database-names) +        [AddDatabaseNodeOperation](../../client-api/operations/server-wide/add-database-node) +        [PromoteDatabaseNodeOperation](../../client-api/operations/server-wide/promote-database-node) +        [ReorderDatabaseMembersOperation](../../client-api/operations/server-wide/reorder-database-members) +        [CompactDatabaseOperation](../../client-api/operations/server-wide/compact-database) +        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](../../client-api/operations/server-wide/sorters/put-sorter-server-wide) +        DeleteServerWideSorterOperation + +* **Logs & debug**: +        SetLogsConfigurationOperation +        GetLogsConfigurationOperation +        GetClusterDebugInfoPackageOperation +        [GetBuildNumberOperation](../../client-api/operations/server-wide/get-build-number) +        GetServerWideOperationStateOperation + +* **Traffic watch**: +        PutTrafficWatchConfigurationOperation +        GetTrafficWatchConfigurationOperation + +* **Revisions**: +        [ConfigureRevisionsForConflictsOperation](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration) + +* **Misc**: +        ModifyConflictSolverOperation +        OfflineMigrationOperation + +{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**. + +--- + +#### Wait for completion: + +{CODE:php wait_timeout_ex@ClientApi\Operations\WhatAreOperations.php /} + +##### Syntax: + +{CODE:php waitForCompletion_syntax@ClientApi\Operations\WhatAreOperations.php /} + +| Parameter | Type | Description | +|-------------|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **$duration** | `Duration` or `int` | | + +{PANEL/} + +## Related articles + +### Document Store + +- [What is a Document Store](../../client-api/what-is-a-document-store) + +### Operations + +- [How to Switch Operations to a Different Database](../../client-api/operations/how-to/switch-operations-to-a-different-database) +- [How to Switch Operations to a Different Node](../../client-api/operations/how-to/switch-operations-to-a-different-node) diff --git a/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/what-are-operations.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/what-are-operations.python.markdown index ccfa934148..04c1ff32bb 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/what-are-operations.python.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/client-api/operations/what-are-operations.python.markdown @@ -20,9 +20,6 @@ * [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#kill-operation) {NOTE/} diff --git a/Documentation/5.4/Samples/php/ClientApi/Operations/Common/DeleteByQuery.php b/Documentation/5.4/Samples/php/ClientApi/Operations/Common/DeleteByQuery.php new file mode 100644 index 0000000000..427760f422 --- /dev/null +++ b/Documentation/5.4/Samples/php/ClientApi/Operations/Common/DeleteByQuery.php @@ -0,0 +1,201 @@ +price; + } + + public function setPrice(float $price): void + { + $this->price = $price; + } +} + +class Products_ByPrice extends AbstractIndexCreationTask +{ + public function __construct() + { + parent::__construct(); + + $this->map = "from product in products select new {price = product.PricePerUnit}"; + } +} + +# endregion + + +class DeleteByQuery +{ + public function examples(): void + { + $store = new DocumentStore(); + try { + # region delete_by_query_0 + // Define the delete by query operation, pass an RQL querying a collection + $deleteByQueryOp = new DeleteByQueryOperation("from 'Orders'"); + + // Execute the operation by passing it to Operations.Send + $operation = $store->operations()->send($deleteByQueryOp); + + // All documents in collection 'Orders' will be deleted from the server. + # endregion + } finally { + $store->close(); + } + + $store = new DocumentStore(); + try { + # region delete_by_query_1 + // Define the delete by query operation, pass an RQL querying a collection + $deleteByQueryOp = new DeleteByQueryOperation("from 'Orders' where Freight > 30"); + + // Execute the operation by passing it to Operations.Send + $operation = $store->operations()->send($deleteByQueryOp); + + // * All documents matching the specified RQL will be deleted from the server. + + // * Since the dynamic query was made with a filtering condition, + // an auto-index is generated (if no other matching auto-index already exists). + # endregion + } finally { + $store->close(); + } + + $store = new DocumentStore(); + try { + # region delete_by_query_2 + // Define the delete by query operation, pass an RQL querying the index + $deleteByQueryOp = new DeleteByQueryOperation("from index 'Products/ByPrice' where Price > 10"); + + // Execute the operation by passing it to Operations.Send + $operation = $store->operations()->send($deleteByQueryOp); + + + // All documents with document-field PricePerUnit > 10 will be deleted from the server. + # endregion + } finally { + $store->close(); + } + + $store = new DocumentStore(); + try { + # region delete_by_query_3 + // Define the delete by query operation + $deleteByQueryOp = new DeleteByQueryOperation( + // Provide an RQL querying the index + new IndexQuery("from index 'Products/ByPrice' where Price > 10") + ); + + // Execute the operation by passing it to Operations.Send + $operation = $store->operations()->send($deleteByQueryOp); + + // All documents with document-field PricePerUnit > 10 will be deleted from the server. + # endregion + } finally { + $store->close(); + } + + $store = new DocumentStore(); + try { + # region delete_by_query_6 + + // OPTIONS: Specify the options for the operation + // (See all other available options in the Syntax section below) + $options = new QueryOperationOptions(); + // Allow the operation to operate even if index is stale + $options->setAllowStale(true); + // Get info in the operation result about documents that were deleted + $options->setRetrieveDetails(true); + + // Define the delete by query operation + $deleteByQueryOp = new DeleteByQueryOperation( + new IndexQuery("from index 'Products/ByPrice' where Price > 10"), // QUERY: Specify the query + $options // OPTIONS: + ); + + // Execute the operation by passing it to Operations.Send + /** @var Operation $operation */ + $operation = $store->operations()->sendAsync($deleteByQueryOp); + + // Wait for operation to complete + /** @var BulkOperationResult $result */ + $result = $operation->waitForCompletion(Duration::ofSeconds(15)); + + // * All documents with document-field PricePerUnit > 10 will be deleted from the server. + + // * Details about deleted documents are available: + $details = $result->getDetails(); + $documentIdThatWasDeleted = $details[0]->getId(); + # endregion + } finally { + $store->close(); + } + } +} diff --git a/Documentation/5.4/Samples/php/ClientApi/Operations/Maintenance/GetStats.php b/Documentation/5.4/Samples/php/ClientApi/Operations/Maintenance/GetStats.php new file mode 100644 index 0000000000..5b6bb2c710 --- /dev/null +++ b/Documentation/5.4/Samples/php/ClientApi/Operations/Maintenance/GetStats.php @@ -0,0 +1,186 @@ +maintenance()->send((new GetCollectionStatisticsOperation()); + # endregion + } finally { + $store->close(); + } + + $store = new DocumentStore(); + try { + # region stats_2 + // Pass an instance of class `GetDetailedCollectionStatisticsOperation` to the store + /** @var DetailedCollectionStatistics $stats */ + $stats = $store->maintenance()->send(new GetDetailedCollectionStatisticsOperation()); + # endregion + } finally { + $store->close(); + } + + $store = new DocumentStore(); + try { + # region stats_3 + // Pass an instance of class `GetStatisticsOperation` to the store + /** @var DatabaseStatistics $stats */ + $stats = $store->maintenance()->send(new GetStatisticsOperation()); + # endregion + } finally { + $store->close(); + } + + $store = new DocumentStore(); + try { + # region stats_4 + // Pass an instance of class `GetDetailedStatisticsOperation` to the store + /** @var DetailedDatabaseStatistics $stats */ + $stats = $store->maintenance()->send(new GetDetailedStatisticsOperation()); + # endregion + } finally { + $store->close(); + } + + $store = new DocumentStore(); + try { + # region stats_5 + // Get stats for 'AnotherDatabase': + /** @var DatabaseStatistics $stats */ + $stats = $store->maintenance()->forDatabase("AnotherDatabase")->send(new GetStatisticsOperation()); + # endregion + } finally { + $store->close(); + } + } +} + +/* +# region stats_1_results +// Collection stats results: +class CollectionStatistics +{ + // Total # of documents in all collections + private ?int $countOfDocuments = null; + // Total # of conflicts + private ?int $countOfConflicts = null; + // Total # of documents per collection + private array $collections = []; + + // ... getters and setters +} +# endregion +*/ + +/* +# region stats_2_results +// Detailed collection stats results: +public class DetailedCollectionStatistics +{ + // Total # of documents in all collections + public long CountOfDocuments { get; set; } + // Total # of conflicts + public long CountOfConflicts { get; set; } + // Collection details per collection + public Dictionary Collections { get; set; } +} + +// Details per collection +class CollectionDetails +{ + private ?string $name = null; + private ?int $countOfDocuments = null; + private ?Size $size = null; + private ?Size $documentsSize = null; + private ?Size $tombstonesSize = null; + private ?Size $revisionsSize = null; + + // ... getters and setters +} +# endregion +*/ + +/* +# region stats_3_results +// Database stats results: +class DatabaseStatistics implements ResultInterface +{ + private ?int $lastDocEtag = null; // Last document etag in database + private ?int $lastDatabaseEtag = null; // Last database etag + + private ?int $countOfIndexes = null; // Total # of indexes in database + private ?int $countOfDocuments = null; // Total # of documents in database + private ?int $countOfRevisionDocuments = null; // Total # of revision documents in database + private ?int $countOfDocumentsConflicts = null; // Total # of documents conflicts in database + private ?int $countOfTombstones = null; // Total # of tombstones in database + private ?int $countOfConflicts = null; // Total # of conflicts in database + private ?int $countOfAttachments = null; // Total # of attachments in database + private ?int $countOfUniqueAttachments = null; // Total # of unique attachments in database + private ?int $countOfCounterEntries = null; // Total # of counter-group entries in database + private ?int $countOfTimeSeriesSegments = null; // Total # of time-series segments in database + + // List of stale index names in database + public function getStaleIndexes(): IndexInformationArray + { + return IndexInformationArray::fromArray( + array_map( + function (IndexInformation $index) { + return $index->isStale(); + }, + $this->indexes->getArrayCopy()) + ); + } + + // Statistics for each index in database + private ?IndexInformationArray $indexes = null; + + private ?string $databaseChangeVector = null; // Global change vector of the database + private ?string $databaseId = null; // Database identifier + private bool $is64Bit = false; // Indicates if process is 64-bit + private ?string $pager = null; // Component handling the memory-mapped files + private ?DateTimeInterface $lastIndexingTime = null; // Last time of indexing an item + private ?Size $sizeOnDisk = null; // Database size on disk + private ?Size $tempBuffersSizeOnDisk = null; // Temp buffers size on disk + private ?int $numberOfTransactionMergerQueueOperations = null; + + // ... getters and setters +} +# endregion +*/ + +/* +# region stats_4_results +// Detailed database stats results: +class DetailedDatabaseStatistics extends DatabaseStatistics implements ResultInterface +{ + // Total # of identities in database + private ?int $countOfIdentities = null; + // Total # of compare-exchange items in database + private ?int $countOfCompareExchange = null; + // Total # of cmpXchg tombstones in database + private ?int $countOfCompareExchangeTombstones = null; + // Total # of TS deleted ranges values in database + private ?int $countOfTimeSeriesDeletedRanges = null; + + // ... getters and setters +} +# endregion +*/ diff --git a/Documentation/5.4/Samples/php/ClientApi/Operations/WhatAreOperations.php b/Documentation/5.4/Samples/php/ClientApi/Operations/WhatAreOperations.php new file mode 100644 index 0000000000..ff62e3d963 --- /dev/null +++ b/Documentation/5.4/Samples/php/ClientApi/Operations/WhatAreOperations.php @@ -0,0 +1,146 @@ +operations()->send($getCountersOp); + + // Access the operation result + $numberOfCounters = count($allCountersResult->getCounters()); + # endregion + + # region maintenance_ex + // Define operation, e.g. stop an index + $stopIndexOp = new StopIndexOperation("Orders/ByCompany"); + + // Execute the operation by passing the operation to Maintenance.Send + $documentStore->maintenance()->send($stopIndexOp); + + // This specific operation returns void + // You can send another operation to verify the index running status + $indexStatsOp = new GetIndexStatisticsOperation("Orders/ByCompany"); + /** @var IndexStats $indexStats */ + $indexStats = $documentStore->maintenance()->send($indexStatsOp); + + /** @var IndexRunningStatus $status */ + $status = $indexStats->getStatus(); // will be "Paused" + # endregion + + # region server_ex + // Define operation, e.g. get the server build number + $getBuildNumberOp = new GetBuildNumberOperation(); + + // Execute the operation by passing the operation to Maintenance.Server.Send + /** @var BuildNumber $buildNumberResult */ + $buildNumberResult = $documentStore->maintenance()->server()->send($getBuildNumberOp); + + // Access the operation result + $version = $buildNumberResult->getBuildVersion(); + # endregion + + } finally { + $documentStore->close(); + } + } + + # region wait_timeout_ex + public function WaitForCompletionWithTimeout(DocumentStore $documentStore, Duration $duration) + { + // Define operation, e.g. delete all discontinued products + // Note: This operation implements interface: 'OperationInterface' + $deleteByQueryOp = new DeleteByQueryOperation("from Products where Discontinued = true"); + + // Execute the operation + // Send returns an 'Operation' object that can be awaited on + + /** @var Operation $operation */ + $operation = $documentStore->operations()->sendAsync($deleteByQueryOp); + + try { + // Call method 'waitForCompletion()' to wait for the operation to complete. + + /** @var BulkOperationResult $result */ + $result = $operation->waitForCompletion($duration); + + // The operation has finished within the specified timeframe + $numberOfItemsDeleted = $result->getTotal(); // Access the operation result + + + } catch (TimeoutException $exception) { + // The operation did Not finish within the specified timeframe + } + + } + # endregion +} diff --git a/Documentation/5.4/Samples/php/Server/CompareExchange.php b/Documentation/5.4/Samples/php/Server/CompareExchange.php new file mode 100644 index 0000000000..0866695a4d --- /dev/null +++ b/Documentation/5.4/Samples/php/Server/CompareExchange.php @@ -0,0 +1,286 @@ +setEmail($email); + + $session = $store->openSession(); + try { + $session->store($user); + + // At this point, the user document has an Id assigned + + // Try to reserve a new user email + // Note: This operation takes place outside of the session transaction, + // It is a cluster-wide reservation + + /** @var CompareExchangeResult $cmpXchgResult */ + $cmpXchgResult = $store->operations()->send(new PutCompareExchangeValueOperation("emails/" . $email, $user->getId(), 0)); + + if (!$cmpXchgResult->isSuccessful()) { + throw new RuntimeException("Email is already in use"); + } + + // At this point we managed to reserve/save the user email - + // The document can be saved in SaveChanges + $session->saveChanges(); + } finally { + $session->close(); + } + # endregion + + + $session = $store->openSession(); + try { + # region query_cmpxchg + $query = $session->advanced()->rawQuery(User::class, + "from Users as s where id() == cmpxchg(\"emails/ayende@ayende.com\")") + ->toList(); + # endregion + + # region document_query_cmpxchg + $q = $session->advanced() + ->documentQuery(User::class) + ->whereEquals("id", CmpXchg::value("emails/ayende@ayende.com")); + # endregion + } finally { + $session->close(); + } + + } finally { + $store->close(); + } + } +} + +class User +{ + private ?string $email = null; + private ?string $id = null; + private ?int $age = null; + + public function getEmail(): ?string + { + return $this->email; + } + + public function setEmail(?string $email): void + { + $this->email = $email; + } + + public function getId(): ?string + { + return $this->id; + } + + public function setId(?string $id): void + { + $this->id = $id; + } + + public function getAge(): ?int + { + return $this->age; + } + + public function setAge(?int $age): void + { + $this->age = $age; + } +} + +# region shared_resource +class SharedResource +{ + private ?DateTime $reservedUntil = null; + + public function getReservedUntil(): ?DateTime + { + return $this->reservedUntil; + } + + public function setReservedUntil(?DateTime $reservedUntil): void + { + $this->reservedUntil = $reservedUntil; + } +} + +class CompareExchangeSharedResource +{ + private ?DocumentStore $store = null; + + public function printWork(): void + { + // Try to get hold of the printer resource + $reservationIndex = $this->lockResource($this->store, "Printer/First-Floor", Duration::ofMinutes(20)); + + try { + // Do some work for the duration that was set. + // Don't exceed the duration, otherwise resource is available for someone else. + } finally { + $this->releaseResource($this->store, "Printer/First-Floor", $reservationIndex); + } + } + + /** throws InterruptedException */ + public function lockResource(DocumentStoreInterface $store, ?string $resourceName, Duration $duration): int + { + while (true) { + $now = new DateTime(); + + $resource = new SharedResource(); + $resource->setReservedUntil($now->add($duration->toDateInterval())); + + /** @var CompareExchangeResult $saveResult */ + $saveResult = $store->operations()->send( + new PutCompareExchangeValueOperation($resourceName, $resource, 0)); + + if ($saveResult->isSuccessful()) { + // resourceName wasn't present - we managed to reserve + return $saveResult->getIndex(); + } + + // At this point, Put operation failed - someone else owns the lock or lock time expired + if ($saveResult->getValue()->getReservedUntil() < $now) { + // Time expired - Update the existing key with the new value + /** @var CompareExchangeResult takeLockWithTimeoutResult */ + $takeLockWithTimeoutResult = $store->operations()->send( + new PutCompareExchangeValueOperation($resourceName, $resource, $saveResult->getIndex())); + + if ($takeLockWithTimeoutResult->isSuccessful()) { + return $takeLockWithTimeoutResult->getIndex(); + } + } + + // Wait a little bit and retry + usleep(20000); + } + } + + public function releaseResource(DocumentStoreInterface $store, ?string $resourceName, int $index): void + { + $deleteResult = $store->operations()->send( + new DeleteCompareExchangeValueOperation(SharedResource::class, $resourceName, $index) + ); + + // We have 2 options here: + // $deleteResult->isSuccessful is true - we managed to release resource + // $deleteResult->isSuccessful is false - someone else took the lock due to timeout + } +} + +# endregion + + +# region create_uniqueness_control_documents +// When you create documents that must contain a unique value such as a phone or email, etc., +// you can create reference documents that will have that unique value in their IDs. +// To know if a value already exists, all you need to do is check whether a reference document with such ID exists. + +public + +class PhoneReference +{ + public ?string $id = null; + public ?string $companyId = null; + + public function getId(): ?string + { + return $this->id; + } + + public function setId(?string $id): void + { + $this->id = $id; + } + + public function getCompanyId(): ?string + { + return $this->companyId; + } + + public function setCompanyId(?string $companyId): void + { + $this->companyId = $companyId; + } +} + +// The reference document class +class UniquePhoneReference +{ + public function sample(): void + { + // A company document class that must be created with a unique 'Phone' field + $newCompany = new Company(); + $newCompany->setName("companyName"); + $newCompany->setPhone("phoneNumber"); + + $newContact = new Contact(); + $newContact->setName("contactName"); + $newContact->setTitle("contactTitle"); + + $newCompany->setContact($newContact); + + $this->createCompanyWithUniquePhone($newCompany); + } + + public function createCompanyWithUniquePhone(Company $newCompany): void + { + // Open a cluster-wide session in your document store + $sessionOptions = new SessionOptions(); + $sessionOptions->setTransactionMode(TransactionMode::clusterWide()); + $session = DocumentStoreHolder::getStore()->openSession($sessionOptions); + + try { + // Check whether the new company phone already exists + // by checking if there is already a reference document that has the new phone in its ID. + $phoneRefDocument = $session->load(PhoneReference::class, "phones/" . $newCompany->getPhone()); + if ($phoneRefDocument != null) { + $msg = "Phone '" . $newCompany->getPhone() . "' already exists in ID: " . $phoneRefDocument->getCompanyId(); + throw new ConcurrencyException($msg); + } + + // If the new phone number doesn't already exist, store the new entity + $session->store($newCompany); + // Store a new reference document with the new phone value in its ID for future checks. + $newPhoneReference = new PhoneReference(); + $newPhoneReference->setCompanyId($newCompany->getId()); + $session->store($newPhoneReference, "phones/" . $newCompany->getPhone()); + + // May fail if called concurrently with the same phone number + $session->saveChanges(); + } finally { + $session->close(); + } + } +} +# endregion diff --git a/Documentation/6.2/Raven.Documentation.Pages/client-api/operations/what-are-operations.php.markdown b/Documentation/6.2/Raven.Documentation.Pages/client-api/operations/what-are-operations.php.markdown new file mode 100644 index 0000000000..a7b70829ec --- /dev/null +++ b/Documentation/6.2/Raven.Documentation.Pages/client-api/operations/what-are-operations.php.markdown @@ -0,0 +1,401 @@ +# 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](../../client-api/what-is-a-document-store)** + and the **[session](../../client-api/session/what-is-a-session-and-how-does-it-work)**. + 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](../../client-api/operations/what-are-operations#why-use-operations) + * [How operations work](../../client-api/operations/what-are-operations#how-operations-work) +
+ * **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) + +{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()](../../client-api/operations/patching/single-document#array-manipulation)) + or via an Operation on the DocumentStore ([PatchOperation](../../client-api/operations/patching/single-document#operations-api)). + +{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](../../client-api/configuration/load-balance/overview#client-logic-for-choosing-a-node). + However, server-maintenance operations can be executed on a specific node by using the [forNode](../../client-api/operations/how-to/switch-operations-to-a-different-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 [forDatabase](../../client-api/operations/how-to/switch-operations-to-a-different-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](../../client-api/operations/what-are-operations#wait-for-completion). + +{PANEL/} + +{PANEL: Common operations} + +* All common operations implement the `IOperation` interface. + The operation is executed within the **database scope**. + Use [forDatabase](../../client-api/operations/how-to/switch-operations-to-a-different-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](../../client-api/operations/what-are-operations#operations-list). + +* To execute a common operation request, + use the `send` method on the `operations` property in the DocumentStore. + +#### Example: + +{CODE:php operations_ex@ClientApi\Operations\WhatAreOperations.php /} + +##### Syntax: + +{CODE:php operations_send@ClientApi\Operations\WhatAreOperations.php /} + +{NOTE: } + + **The following common operations are available:** + +--- + +* **Attachments**: +        [PutAttachmentOperation](../../client-api/operations/attachments/put-attachment) +        [GetAttachmentOperation](../../client-api/operations/attachments/get-attachment) +        [DeleteAttachmentOperation](../../client-api/operations/attachments/delete-attachment) + +* **Counters**: +        [CounterBatchOperation](../../client-api/operations/counters/counter-batch) +        [GetCountersOperation](../../client-api/operations/counters/get-counters) + +* **Time series**: +        [TimeSeriesBatchOperation](../../document-extensions/timeseries/client-api/operations/append-and-delete) +        [GetMultipleTimeSeriesOperation](../../document-extensions/timeseries/client-api/operations/get) +        [GetTimeSeriesOperation](../../document-extensions/timeseries/client-api/operations/get) +        GetTimeSeriesStatisticsOperation + +* **Revisions**: +        [GetRevisionsOperation](../../document-extensions/revisions/client-api/operations/get-revisions) + +* **Patching**: +        [PatchOperation](../../client-api/operations/patching/single-document) +        [PatchByQueryOperation](../../client-api/operations/patching/set-based) + +* **Delete by query**: +        [DeleteByQueryOperation](../../client-api/operations/common/delete-by-query) + +* **Compare-exchange**: +        [PutCompareExchangeValueOperation](../../client-api/operations/compare-exchange/put-compare-exchange-value) +        [GetCompareExchangeValueOperation](../../client-api/operations/compare-exchange/get-compare-exchange-value) +        [GetCompareExchangeValuesOperation](../../client-api/operations/compare-exchange/get-compare-exchange-values) +        [DeleteCompareExchangeValueOperation](../../client-api/operations/compare-exchange/delete-compare-exchange-value) + +{NOTE/} +{PANEL/} + +{PANEL: Maintenance operations} + +* All maintenance operations implement the `IMaintenanceOperation` interface. + The operation is executed within the **database scope**. + Use [forDatabase](../../client-api/operations/how-to/switch-operations-to-a-different-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](../../client-api/operations/what-are-operations#maintenance-list). + +* To execute a maintenance operation request, + use the `send` method on the `maintenance` property in the DocumentStore. + +#### Example: + +{CODE:php maintenance_ex@ClientApi\Operations\WhatAreOperations.php /} + +##### Syntax: + +{CODE:php maintenance_send@ClientApi\Operations\WhatAreOperations.php /} + +{NOTE: } + + **The following maintenance operations are available:** + +--- + +* **Statistics**: +        [GetStatisticsOperation](../../client-api/operations/maintenance/get-stats#get-database-stats) +        [GetDetailedStatisticsOperation](../../client-api/operations/maintenance/get-stats#get-detailed-database-stats) +        [GetCollectionStatisticsOperation](../../client-api/operations/maintenance/get-stats#get-collection-stats) +        [GetDetailedCollectionStatisticsOperation](../../client-api/operations/maintenance/get-stats#get-detailed-collection-stats) + +* **Client Configuration**: +        [PutClientConfigurationOperation](../../client-api/operations/maintenance/configuration/put-client-configuration) +        [GetClientConfigurationOperation](../../client-api/operations/maintenance/configuration/get-client-configuration) + +* **Indexes**: +        [PutIndexesOperation](../../client-api/operations/maintenance/indexes/put-indexes) +        [SetIndexesLockOperation](../../client-api/operations/maintenance/indexes/set-index-lock) +        [SetIndexesPriorityOperation](../../client-api/operations/maintenance/indexes/set-index-priority) +        [GetIndexErrorsOperation](../../client-api/operations/maintenance/indexes/get-index-errors) +        [GetIndexOperation](../../client-api/operations/maintenance/indexes/get-index) +        [GetIndexesOperation](../../client-api/operations/maintenance/indexes/get-indexes) +        [GetTermsOperation](../../client-api/operations/maintenance/indexes/get-terms) +        GetIndexPerformanceStatisticsOperation +        GetIndexStatisticsOperation +        GetIndexesStatisticsOperation +        GetIndexingStatusOperation +        GetIndexStalenessOperation +        [GetIndexNamesOperation](../../client-api/operations/maintenance/indexes/get-index-names) +        [StartIndexOperation](../../client-api/operations/maintenance/indexes/start-index) +        [StartIndexingOperation](../../client-api/operations/maintenance/indexes/start-indexing) +        [StopIndexOperation](../../client-api/operations/maintenance/indexes/stop-index) +        [StopIndexingOperation](../../client-api/operations/maintenance/indexes/stop-indexing) +        [ResetIndexOperation](../../client-api/operations/maintenance/indexes/reset-index) +        [DeleteIndexOperation](../../client-api/operations/maintenance/indexes/delete-index) +        [DeleteIndexErrorsOperation](../../client-api/operations/maintenance/indexes/delete-index-errors) +        [DisableIndexOperation](../../client-api/operations/maintenance/indexes/disable-index) +        [EnableIndexOperation](../../client-api/operations/maintenance/indexes/enable-index) +        [IndexHasChangedOperation](../../client-api/operations/maintenance/indexes/index-has-changed) + +* **Analyzers**: +        PutAnalyzersOperation +        DeleteAnalyzerOperation + +* **Ongoing tasks**: +        [GetOngoingTaskInfoOperation](../../client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations#get-ongoing-task-info) +        [ToggleOngoingTaskStateOperation](../../client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations#toggle-ongoing-task-state) +        [DeleteOngoingTaskOperation](../../client-api/operations/maintenance/ongoing-tasks/ongoing-task-operations#delete-ongoing-task) + +* **ETL tasks**: +        AddEtlOperation +        UpdateEtlOperation +        [ResetEtlOperation](../../client-api/operations/maintenance/etl/reset-etl) + +* **Replication tasks**: +        PutPullReplicationAsHubOperation +        GetPullReplicationTasksInfoOperation +        GetReplicationHubAccessOperation +        GetReplicationPerformanceStatisticsOperation +        RegisterReplicationHubAccessOperation +        UnregisterReplicationHubAccessOperation +        UpdateExternalReplicationOperation +        UpdatePullReplicationAsSinkOperation + +* **Backup**: +        BackupOperation +        GetPeriodicBackupStatusOperation +        StartBackupOperation +        UpdatePeriodicBackupOperation + +* **Connection strings**: +        [PutConnectionStringOperation](../../client-api/operations/maintenance/connection-strings/add-connection-string) +        [RemoveConnectionStringOperation](../../client-api/operations/maintenance/connection-strings/remove-connection-string) +        [GetConnectionStringsOperation](../../client-api/operations/maintenance/connection-strings/get-connection-string) + +* **Transaction recording**: +        StartTransactionsRecordingOperation +        StopTransactionsRecordingOperation +        ReplayTransactionsRecordingOperation + +* **Database settings**: +        [PutDatabaseSettingsOperation](../../client-api/operations/maintenance/configuration/database-settings-operation#put-database-settings-operation) +        [GetDatabaseSettingsOperation](../../client-api/operations/maintenance/configuration/database-settings-operation#get-database-settings-operation) + +* **Identities**: +        [GetIdentitiesOperation](../../client-api/operations/maintenance/identities/get-identities) +        [NextIdentityForOperation](../../client-api/operations/maintenance/identities/increment-next-identity) +        [SeedIdentityForOperation](../../client-api/operations/maintenance/identities/seed-identity) + +* **Time series**: +        ConfigureTimeSeriesOperation +        ConfigureTimeSeriesPolicyOperation +        ConfigureTimeSeriesValueNamesOperation +        RemoveTimeSeriesPolicyOperation + +* **Revisions**: +        [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions) + +* **Sorters**: +        [PutSortersOperation](../../client-api/operations/maintenance/sorters/put-sorter) +        DeleteSorterOperation + +* **Sharding**: +        [AddPrefixedShardingSettingOperation](../../sharding/administration/sharding-by-prefix#add-prefixes-after-database-creation) +        [DeletePrefixedShardingSettingOperation](../../sharding/administration/sharding-by-prefix#removing-prefixes) +        [UpdatePrefixedShardingSettingOperation](../../sharding/administration/sharding-by-prefix#updating-shard-configurations-for-prefixes) + +* **Misc**: +        ConfigureExpirationOperation +        ConfigureRefreshOperation +        UpdateDocumentsCompressionConfigurationOperation +        DatabaseHealthCheckOperation +        GetOperationStateOperation +        CreateSampleDataOperation + +{NOTE/} +{PANEL/} + +{PANEL: Server-maintenance operations} + +* All server-maintenance operations implement the `IServerOperation` interface. + The operation is executed within the **server scope**. + Use [forNode](../../client-api/operations/how-to/switch-operations-to-a-different-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](../../client-api/operations/what-are-operations#server-list). + +* To execute a server-maintenance operation request, + use the `send` method on the `maintenance.server` property in the DocumentStore. + +#### Example: + +{CODE:php server_ex@ClientApi\Operations\WhatAreOperations.php /} + +##### Syntax: + +{CODE:php server_send@ClientApi\Operations\WhatAreOperations.php /} + +{NOTE: } + + **The following server-maintenance operations are available:** + +--- + +* **Client certificates**: +        [PutClientCertificateOperation](../../client-api/operations/server-wide/certificates/put-client-certificate) +        [CreateClientCertificateOperation](../../client-api/operations/server-wide/certificates/create-client-certificate) +        [GetCertificatesOperation](../../client-api/operations/server-wide/certificates/get-certificates) +        [DeleteCertificateOperation](../../client-api/operations/server-wide/certificates/delete-certificate) +        EditClientCertificateOperation +        GetCertificateMetadataOperation +        ReplaceClusterCertificateOperation + +* **Server-wide client configuration**: +        [PutServerWideClientConfigurationOperation](../../client-api/operations/server-wide/configuration/put-serverwide-client-configuration) +        [GetServerWideClientConfigurationOperation](../../client-api/operations/server-wide/configuration/get-serverwide-client-configuration) + +* **Database management**: +        [CreateDatabaseOperation](../../client-api/operations/server-wide/create-database) +        [DeleteDatabasesOperation](../../client-api/operations/server-wide/delete-database) +        [ToggleDatabasesStateOperation](../../client-api/operations/server-wide/toggle-databases-state) +        [GetDatabaseNamesOperation](../../client-api/operations/server-wide/get-database-names) +        [AddDatabaseNodeOperation](../../client-api/operations/server-wide/add-database-node) +        [PromoteDatabaseNodeOperation](../../client-api/operations/server-wide/promote-database-node) +        [ReorderDatabaseMembersOperation](../../client-api/operations/server-wide/reorder-database-members) +        [CompactDatabaseOperation](../../client-api/operations/server-wide/compact-database) +        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](../../client-api/operations/server-wide/sorters/put-sorter-server-wide) +        DeleteServerWideSorterOperation + +* **Logs & debug**: +        SetLogsConfigurationOperation +        GetLogsConfigurationOperation +        GetClusterDebugInfoPackageOperation +        [GetBuildNumberOperation](../../client-api/operations/server-wide/get-build-number) +        GetServerWideOperationStateOperation + +* **Traffic watch**: +        PutTrafficWatchConfigurationOperation +        GetTrafficWatchConfigurationOperation + +* **Revisions**: +        [ConfigureRevisionsForConflictsOperation](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration) + +* **Misc**: +        ModifyConflictSolverOperation +        OfflineMigrationOperation + +{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**. + +--- + +#### Wait for completion: + +{CODE:php wait_timeout_ex@ClientApi\Operations\WhatAreOperations.php /} + +##### Syntax: + +{CODE:php waitForCompletion_syntax@ClientApi\Operations\WhatAreOperations.php /} + +| Parameter | Type | Description | +|-------------|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **$duration** | `Duration` or `int` |
  • **When a duration is specified** -
    The server will throw a `TimeoutException` if the peration 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 the operation to complete indefinitely.
| + +{PANEL/} + +## Related articles + +### Document Store + +- [What is a Document Store](../../client-api/what-is-a-document-store) + +### Operations + +- [How to Switch Operations to a Different Database](../../client-api/operations/how-to/switch-operations-to-a-different-database) +- [How to Switch Operations to a Different Node](../../client-api/operations/how-to/switch-operations-to-a-different-node) diff --git a/Documentation/6.2/Samples/php/ClientApi/Operations/WhatAreOperations.php b/Documentation/6.2/Samples/php/ClientApi/Operations/WhatAreOperations.php new file mode 100644 index 0000000000..ff62e3d963 --- /dev/null +++ b/Documentation/6.2/Samples/php/ClientApi/Operations/WhatAreOperations.php @@ -0,0 +1,146 @@ +operations()->send($getCountersOp); + + // Access the operation result + $numberOfCounters = count($allCountersResult->getCounters()); + # endregion + + # region maintenance_ex + // Define operation, e.g. stop an index + $stopIndexOp = new StopIndexOperation("Orders/ByCompany"); + + // Execute the operation by passing the operation to Maintenance.Send + $documentStore->maintenance()->send($stopIndexOp); + + // This specific operation returns void + // You can send another operation to verify the index running status + $indexStatsOp = new GetIndexStatisticsOperation("Orders/ByCompany"); + /** @var IndexStats $indexStats */ + $indexStats = $documentStore->maintenance()->send($indexStatsOp); + + /** @var IndexRunningStatus $status */ + $status = $indexStats->getStatus(); // will be "Paused" + # endregion + + # region server_ex + // Define operation, e.g. get the server build number + $getBuildNumberOp = new GetBuildNumberOperation(); + + // Execute the operation by passing the operation to Maintenance.Server.Send + /** @var BuildNumber $buildNumberResult */ + $buildNumberResult = $documentStore->maintenance()->server()->send($getBuildNumberOp); + + // Access the operation result + $version = $buildNumberResult->getBuildVersion(); + # endregion + + } finally { + $documentStore->close(); + } + } + + # region wait_timeout_ex + public function WaitForCompletionWithTimeout(DocumentStore $documentStore, Duration $duration) + { + // Define operation, e.g. delete all discontinued products + // Note: This operation implements interface: 'OperationInterface' + $deleteByQueryOp = new DeleteByQueryOperation("from Products where Discontinued = true"); + + // Execute the operation + // Send returns an 'Operation' object that can be awaited on + + /** @var Operation $operation */ + $operation = $documentStore->operations()->sendAsync($deleteByQueryOp); + + try { + // Call method 'waitForCompletion()' to wait for the operation to complete. + + /** @var BulkOperationResult $result */ + $result = $operation->waitForCompletion($duration); + + // The operation has finished within the specified timeframe + $numberOfItemsDeleted = $result->getTotal(); // Access the operation result + + + } catch (TimeoutException $exception) { + // The operation did Not finish within the specified timeframe + } + + } + # endregion +}