Skip to content

Commit

Permalink
Merge pull request #1949 from Danielle9897/RDoc-2637-fixCommandsArticles
Browse files Browse the repository at this point in the history
RDoc-3116 & RDoc-3117 Client API > Commands [Fix articles] (C# & Node.js)
  • Loading branch information
ppekrol authored Nov 27, 2024
2 parents 6d205bf + db9d705 commit 1598fe5
Show file tree
Hide file tree
Showing 50 changed files with 4,344 additions and 122 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,12 @@
"Path": "get-document-metadata-only.markdown",
"Name": "...get document metadata only",
"DiscussionId": "8c1f8ce8-f09e-4076-850f-c5bc9317633b",
"Mappings": []
"Mappings": [
{
"Version": 6.0,
"Key": "client-api/commands/documents/get"
}
],
"LastSupportedVersion": "5.4"
}
]
Original file line number Diff line number Diff line change
Expand Up @@ -58,11 +58,13 @@ Transactional behavior with RavenDB is divided into two modes:

* __Single requests__:
In this mode, a user can perform all requested operations (read and/or write) in a single request.

* _Multiple writes_:
A batch of multiple write operations will be executed atomically in a single transaction via calling `SaveChanges()` which generates a single HTTP request to the database.

* _Multiple reads & writes_:

* __Multiple writes__:
A batch of multiple write operations will be executed atomically in a single transaction when calling [SaveChanges()](../../client-api/session/saving-changes).
Multiple operations can also be executed in a single transaction using the low-level [SingleNodeBatchCommand](../../client-api/commands/batches/how-to-send-multiple-commands-using-a-batch).
In both cases, a single HTTP request is sent to the database.

* __Multiple reads & writes__:
Performing interleaving reads and writes or conditional execution can be achieved by [running a patching script](../../client-api/operations/patching/single-document).
In the script you can read documents, make decisions based on their content and update or put document(s) within the scope of a single transaction.
If you only need to modify a document in a transaction, [JSON Patch syntax](../../client-api/operations/patching/json-patch-syntax) allows you to do that.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,46 +1,52 @@
[
{
"Path": "setup-aggressive-caching.markdown",
"Name": "...setup aggressive caching",
"DiscussionId": "c2ab774a-213a-433c-9f3c-867dc4dcf2d9",
"Mappings": [
{
"Version": 2.0,
"Key": "client-api/advanced/aggressive-caching"
}
]
},
{
"Path": "store-dates.markdown",
"Name": "...store dates",
"DiscussionId": "73c9f0f3-2b5b-4a53-8fab-b5c2bf66c46b",
"Mappings": []
},
{
"Path": "handle-document-relationships.markdown",
"Name": "...handle document relationships",
"DiscussionId": "2659925a-cb64-4685-a2ef-91f4c6d80784",
"Mappings": [
{
"Version": 3.5,
"Key": "indexes/querying/handling-document-relationships"
},
{
"Version": 1.0,
"Key": "client-api/querying/handling-document-relationships"
}
]
},
{
"Path": "use-low-level-commands.markdown",
"Name": "...use low-level commands",
"DiscussionId": "62dd8114-3cb7-487e-9371-5d5f6d37bdcc",
"Mappings": []
},
{
"Path": "integrate-with-excel.markdown",
"Name": "...integrate with Excel",
"DiscussionId": "22806718-be83-429b-bdc0-9e220caaa733",
"Mappings": []
}
]
{
"Path": "setup-aggressive-caching.markdown",
"Name": "...setup aggressive caching",
"DiscussionId": "c2ab774a-213a-433c-9f3c-867dc4dcf2d9",
"Mappings": [
{
"Version": 2.0,
"Key": "client-api/advanced/aggressive-caching"
}
]
},
{
"Path": "store-dates.markdown",
"Name": "...store dates",
"DiscussionId": "73c9f0f3-2b5b-4a53-8fab-b5c2bf66c46b",
"Mappings": []
},
{
"Path": "handle-document-relationships.markdown",
"Name": "...handle document relationships",
"DiscussionId": "2659925a-cb64-4685-a2ef-91f4c6d80784",
"Mappings": [
{
"Version": 3.5,
"Key": "indexes/querying/handling-document-relationships"
},
{
"Version": 1.0,
"Key": "client-api/querying/handling-document-relationships"
}
]
},
{
"Path": "use-low-level-commands.markdown",
"Name": "...use low-level commands",
"DiscussionId": "62dd8114-3cb7-487e-9371-5d5f6d37bdcc",
"Mappings": [
{
"Version": 6.0,
"Key": "client-api/commands/overview"
}
],
"LastSupportedVersion": "5.4"
},
{
"Path": "integrate-with-excel.markdown",
"Name": "...integrate with Excel",
"DiscussionId": "22806718-be83-429b-bdc0-9e220caaa733",
"Mappings": []
}
]
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ has been concurrently modified on different nodes during network partition to pr
Every document in RavenDB has a corresponding change vector.
This change vector is updated by RavenDB every time the document is changed.
This happens when on document creation and
any modification such as `PUT`, `PATCH`, 'DELETE' or their bulk versions.
any modification such as `PUT`, `PATCH`, `DELETE` or their bulk versions.
A delete operation will also cause RavenDB to update the document change vector,
however, at that point, the change vector will belong to
the document tombstone (since the document itself has already been deleted).
Expand All @@ -74,7 +74,7 @@ This is mostly used internally inside RavenDB for many purposes
subscription has already seen, what was sent to an ETL destination, etc)
but can also be very useful for clients.

In particular, the change vector is _guaranteed_ to change whenever the document changes and can be used as part of optimistic concurrency checks. A document modification can all specify an expected change vector for a document (with an empty change vector signifying that the document does not exists). In such a case, all operations in the
In particular, the change vector is _guaranteed_ to change whenever the document changes and can be used as part of optimistic concurrency checks. A document modification can all specify an expected change vector for a document (with an empty change vector signifying that the document does not exist). In such a case, all operations in the
transaction will be aborted and no changes will be applied to any of the documents modified in the transaction.

{PANEL/}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@
{NOTE: }

* Each document in a RavenDB database has a unique string associated with it, called an **identifier**.
Every entity that you store, using either a [session](../session/what-is-a-session-and-how-does-it-work)
or a [put document command](../commands/documents/put), is assigned such an identifier.
Every entity that you store, using either a [session](../../client-api/session/what-is-a-session-and-how-does-it-work)
or a [put document command](../../client-api/commands/documents/put), is assigned such an identifier.

* RavenDB supports [several options](../../server/kb/document-identifier-generation) of storing a document and assigning
it an identifier.
Expand Down Expand Up @@ -234,7 +234,7 @@ The commands API gives you full freedom in selecting the identifier generation s

RavenDB ver. 4.2 and higher provides high-level [operations](../../client-api/operations/what-are-operations#operations-what-are-the-operations)
that you may set IDs with, in addition to the
low-level [commands](../../client-api/how-to/use-low-level-commands#client-api-how-to-use-low-level-commands)
low-level [commands](../../client-api/document-identifiers/working-with-document-identifiers#using-commands)
we have described above.
There is no operational difference between using operations and commands, since the high-level operations actually
execute low-level commands. However, using operations may produce a clearer, more concise code.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,25 +1,25 @@
[
{
"Path": "get.markdown",
"Name": "Get",
"DiscussionId": "eafb1bd0-dd05-449e-bacc-0d5747d96385",
"Mappings": []
},
{
"Path": "put.markdown",
"Name": "Put",
"DiscussionId": "ed032e64-6fe9-4528-a4c0-893dbf4d2bf8",
"Mappings": []
},
{
"Path": "delete.markdown",
"Name": "Delete",
"DiscussionId": "603df172-c032-48c6-8f8a-ef40e721c3c0",
"Mappings": []
},
{
"Path": "/how-to",
"Name": "How to...",
"Mappings": []
}
]
{
"Path": "get.markdown",
"Name": "Get",
"DiscussionId": "eafb1bd0-dd05-449e-bacc-0d5747d96385",
"Mappings": []
},
{
"Path": "put.markdown",
"Name": "Put",
"DiscussionId": "ed032e64-6fe9-4528-a4c0-893dbf4d2bf8",
"Mappings": []
},
{
"Path": "delete.markdown",
"Name": "Delete",
"DiscussionId": "603df172-c032-48c6-8f8a-ef40e721c3c0",
"Mappings": []
},
{
"Path": "/how-to",
"Name": "How to...",
"Mappings": []
}
]
Original file line number Diff line number Diff line change
@@ -1,12 +1,23 @@
[
[
{
"Path": "overview.markdown",
"Name": "Commands Overview",
"DiscussionId": "77145453-b931-4323-a10f-62899c835b4d",
"Mappings": [
{
"Version": 4.0,
"Key": "client-api/how-to/use-low-level-commands"
}
]
},
{
"Path": "/documents",
"Name": "Documents",
"Name": "Document Commands",
"Mappings": []
},
{
"Path": "/batches",
"Name": "Batches",
"Name": "Batching Commands",
"Mappings": []
}
]
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
[
{
"Path": "how-to-send-multiple-commands-using-a-batch.markdown",
"Name": "Send Multiple Commands",
"DiscussionId": "2b6e99a2-6807-4ffc-85d0-e39477a2ddb7",
"Mappings": []
}
]
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
# Send Multiple Commands in a Batch
---

{NOTE: }

* Use the low-level `SingleNodeBatchCommand` to send **multiple commands** in a **single request** to the server.
This reduces the number of remote calls and allows several operations to share the same transaction.

* All the commands sent in the batch are executed as a **single transaction** on the node the client communicated with.
If any command fails, the entire batch is rolled back, ensuring data integrity.

* The commands are replicated to other nodes in the cluster only AFTER the transaction is successfully completed on that node.

* In this page:
* [Examples](../../../client-api/commands/batches/how-to-send-multiple-commands-using-a-batch#examples)
* [Available batch commands](../../../client-api/commands/batches/how-to-send-multiple-commands-using-a-batch#available-batch-commands)
* [Syntax](../../../client-api/commands/batches/how-to-send-multiple-commands-using-a-batch#syntax)

{NOTE/}

---

{PANEL: Examples}

{CONTENT-FRAME: }

#### Send multiple commands - using the Store's request executor:

---

{CODE-TABS}
{CODE-TAB:csharp:Sync batch_1@ClientApi\Commands\Batches\SendMultipleCommands.cs /}
{CODE-TAB:csharp:Async batch_1_async@ClientApi\Commands\Batches\SendMultipleCommands.cs /}
{CODE-TABS/}

{CONTENT-FRAME/}
{CONTENT-FRAME: }

#### Send multiple commands - using the Session's request executor:

---

* `SingleNodeBatchCommand` can also be executed using the session's request executor.

* Note that the transaction created for the HTTP request when executing `SingleNodeBatchCommand`
is separate from the transaction initiated by the session's [SaveChanges](../../../client-api/session/saving-changes) method, even if both are called within the same code block.
Learn more about transactions in RavenDB in [Transaction support](../../../client-api/faq/transaction-support).

{CODE-TABS}
{CODE-TAB:csharp:Sync batch_2@ClientApi\Commands\Batches\SendMultipleCommands.cs /}
{CODE-TAB:csharp:Async batch_2_async@ClientApi\Commands\Batches\SendMultipleCommands.cs /}
{CODE-TABS/}

{CONTENT-FRAME/}
{PANEL/}

{PANEL: Available batch commands}

**The following commands can be sent in a batch via `SingleNodeBatchCommand`**:
(These commands implement the `ICommandData` interface).

* BatchPatchCommandData
* CopyAttachmentCommandData
* CountersBatchCommandData
* DeleteAttachmentCommandData
* DeleteCommandData
* DeleteCompareExchangeCommandData
* DeletePrefixedCommandData
* ForceRevisionCommandData
* IncrementalTimeSeriesBatchCommandData
* JsonPatchCommandData
* MoveAttachmentCommandData
* PatchCommandData
* PutAttachmentCommandData
* PutCommandData
* PutCompareExchangeCommandData
* TimeSeriesBatchCommandData

{PANEL/}

{PANEL: Syntax}

{CODE syntax_1@ClientApi\Commands\Batches\SendMultipleCommands.cs /}
{CODE syntax_2@ClientApi\Commands\Batches\SendMultipleCommands.cs /}
{CODE syntax_3@ClientApi\Commands\Batches\SendMultipleCommands.cs /}

{PANEL/}

## Related articles

### Transactions

- [Transaction Support](../../../client-api/faq/transaction-support)

### Commands

- [Put document](../../../client-api/commands/documents/put)
- [Delete document](../../../client-api/commands/documents/delete)

### Patching

- [How to Perform Single Document Patch Operations](../../../client-api/operations/patching/single-document)

### Attachments

- [What are Attachments](../../../document-extensions/attachments/what-are-attachments)
Loading

0 comments on commit 1598fe5

Please sign in to comment.