Skip to content

RDoc-3767 Copy attachments via Patch Scripts #2371

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Danielle9897 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

RDoc-3767 Copy attachments via Patch Scripts #2371

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions docs/client-api/operations/patching/content/_single-document-csharp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -300,6 +300,7 @@ See the more comprehensive list at [Knowledge Base: JavaScript Engine](../../../
| **deleteCounter** | Document; counter name | Deletes the counter |
| **spatial.distance** | Two points by latitude and longitude; spatial units | Find the distance between to points on the earth |
| **timeseries** | Document; the time series' name | Returns the specified time series object |
| **attachments** | Document; attachment name | Returns an attachment object providing `delete()`, `remote()`, and `copyFrom()` methods for managing the specified attachment via patching |



Expand Down Expand Up @@ -997,9 +998,12 @@ session.SaveChanges();

* When cloning a document via patching, only the document's fields are copied to the new document.
Attachments, counters, time series data, and revisions from the source document will Not be copied automatically.
* To manage time series & counters via patching, you can use the pre-defined JavaScript methods listed here:
[Counters methods](../../../../server/kb/javascript-engine.mdx#counter-operations) & [Time series methods](../../../../server/kb/javascript-engine.mdx#time-series-operations).
* Note: When [Cloning a document via the Studio](../../../../studio/database/documents/create-new-document.mdx#clone-an-existing-document),
* To manage counters, time series, and attachments via patching, you can use the pre-defined JavaScript methods listed here:
* [Counters methods](../../../../server/kb/javascript-engine.mdx#counter-operations)
* [Time series methods](../../../../server/kb/javascript-engine.mdx#time-series-operations).
* [Attachments methods](../../../../server/kb/javascript-engine.mdx#attachment-operations).
* Note:
When [Cloning a document via the Studio](../../../../studio/database/documents/create-new-document.mdx#clone-an-existing-document),
attachments, counters, time Series, and revisions will be copied automatically.

**Archived documents:**
Expand Down
10 changes: 7 additions & 3 deletions docs/client-api/operations/patching/content/_single-document-java.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,6 +185,7 @@ more comprehensive list at [Knowledge Base: JavaScript Engine](../../../../serve
| **counterRaw** | Document; counter name | Returns the specified counter in the specified document as a key-value pair |
| **incrementCounter** | Document; counter name | Increases the value of the counter by one |
| **deleteCounter** | Document; counter name | Deletes the counter |
| **attachments** | Document; attachment name | Returns an attachment object providing `delete()`, `remote()`, and `copyFrom()` methods for managing the specified attachment via patching |



Expand Down Expand Up @@ -650,9 +651,12 @@ store.operations().send(new PatchOperation("employees/1-A", null, patchRequest))

* When cloning a document via patching, only the document's fields are copied to the new document.
Attachments, counters, time series data, and revisions from the source document will Not be copied automatically.
* To manage time series & counters via patching, you can use the pre-defined JavaScript methods listed here:
[Counters methods](../../../../server/kb/javascript-engine.mdx#counter-operations) & [Time series methods](../../../../server/kb/javascript-engine.mdx#time-series-operations).
* Note: When [Cloning a document via the Studio](../../../../studio/database/documents/create-new-document.mdx#clone-an-existing-document),
* To manage counters, time series, and attachments via patching, you can use the pre-defined JavaScript methods listed here:
* [Counters methods](../../../../server/kb/javascript-engine.mdx#counter-operations)
* [Time series methods](../../../../server/kb/javascript-engine.mdx#time-series-operations).
* [Attachments methods](../../../../server/kb/javascript-engine.mdx#attachment-operations).
* Note:
When [Cloning a document via the Studio](../../../../studio/database/documents/create-new-document.mdx#clone-an-existing-document),
attachments, counters, time Series, and revisions will be copied automatically.

**Archived documents:**
Expand Down
9 changes: 6 additions & 3 deletions docs/client-api/operations/patching/content/_single-document-nodejs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1086,9 +1086,12 @@ await documentStore.operations.send(patchOp);

* When cloning a document via patching, only the document's fields are copied to the new document.
Attachments, counters, time series data, and revisions from the source document will Not be copied automatically.
* To manage time series & counters via patching, you can use the pre-defined JavaScript methods listed here:
[Counters methods](../../../../server/kb/javascript-engine.mdx#counter-operations) & [Time series methods](../../../../server/kb/javascript-engine.mdx#time-series-operations).
* Note: When [Cloning a document via the Studio](../../../../studio/database/documents/create-new-document.mdx#clone-an-existing-document),
* To manage counters, time series, and attachments via patching, you can use the pre-defined JavaScript methods listed here:
* [Counters methods](../../../../server/kb/javascript-engine.mdx#counter-operations)
* [Time series methods](../../../../server/kb/javascript-engine.mdx#time-series-operations).
* [Attachments methods](../../../../server/kb/javascript-engine.mdx#attachment-operations).
* Note:
When [Cloning a document via the Studio](../../../../studio/database/documents/create-new-document.mdx#clone-an-existing-document),
attachments, counters, time Series, and revisions will be copied automatically.

**Archived documents:**
Expand Down
116 changes: 112 additions & 4 deletions docs/document-extensions/attachments/content/_copy-move-rename-csharp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ import Panel from '@site/src/components/Panel';

* In this article:
* [Copy attachment to another document](../../../document-extensions/attachments/copy-move-rename.mdx#copy-attachment-to-another-document)
* [Copy attachment - via the session](../../../document-extensions/attachments/copy-move-rename.mdx#copy-attachments---via-the-session)
* [Copy attachment - via patching](../../../document-extensions/attachments/copy-move-rename.mdx#copy-attachments---via-patching)
* [Move attachment to another document](../../../document-extensions/attachments/copy-move-rename.mdx#move-attachment-to-another-document)
* [Rename attachment](../../../document-extensions/attachments/copy-move-rename.mdx#rename-attachment)
* [Syntax](../../../document-extensions/attachments/copy-move-rename.mdx#syntax)
Expand All @@ -20,9 +22,6 @@ import Panel from '@site/src/components/Panel';

<Panel heading="Copy attachment to another document">

* Use the session's `Advanced.Attachments.Copy` method to copy an attachment from one document to another.
You can assign any name to the copied attachment in the target document, it doesn't have to match the source name.

* **Copying LOCAL attachments**:
The target document's metadata is updated to reference the same attachment.
The binary content is Not duplicated, it remains stored once in the database,
Expand All @@ -33,7 +32,14 @@ import Panel from '@site/src/components/Panel';
The attachment is Not re-uploaded or duplicated in the remote destination,
even if the copied attachment has a different name in the target document.

* An exception is thrown in any of the following cases:
---

### Copy attachments - via the session

* Use the session's `Advanced.Attachments.Copy` method to copy an attachment from one document to another.
You can assign any name to the copied attachment in the target document, it doesn't have to match the source name.

* **An exception is thrown** in any of the following cases:
* The source document does not exist.
* The destination document does not exist.
* The specified attachment is not found in the source document.
Expand Down Expand Up @@ -84,6 +90,84 @@ using (var asyncSession = store.OpenAsyncSession())
</TabItem>
</Tabs>

---

### Copy attachments - via patching

* Use `attachments(targetDocument, targetAttachmentName).copyFrom(sourceDocId, sourceAttachmentName)` to copy an attachment between documents within a patch script.
The method copies the attachment from the source document and assigns it to the target document under the specified name.

* In both [single-document patches](../../../client-api/operations/patching/single-document.mdx)
and [patch-by-query operations](../../../client-api/operations/patching/set-based.mdx),
the copy is performed entirely server-side,
without requiring the attachment to be downloaded and re-uploaded through the client.

* **An exception is thrown** in the following case:
* An attachment with the specified name already exists on the target document.

* **No exception is thrown** in the following cases:
* The source document does not exist.
* The source attachment does not exist.
* The destination document does not exist.

<Tabs groupId='languageSyntax'>
<TabItem value="Copy_attachment_via_patch" label="Copy_attachment_via_patch">
```csharp
// Define the patch request
var patchRequest = new PatchRequest
{
// Copy attachment 'photo.jpg' from 'employees/1' to the patched document
// and name it 'photo-copy.jpg' in the target document
Script = "attachments(this, args.targetName).copyFrom(args.sourceDocId, args.sourceName);",
Values =
{
{ "sourceDocId", "employees/1" },
{ "sourceName", "photo.jpg" },
{ "targetName", "photo-copy.jpg" }
}
};

// Execute the patch operation on the target document
store.Operations.Send(new PatchOperation("employees/2", null, patchRequest));
```
</TabItem>
<TabItem value="Copy_attachment_via_patch_async" label="Copy_attachment_via_patch_async">
```csharp
// Define the patch request
var patchRequest = new PatchRequest
{
// Copy attachment 'photo.jpg' from 'employees/1' to the patched document
// and name it 'photo-copy.jpg' in the target document
Script = "attachments(this, args.targetName).copyFrom(args.sourceDocId, args.sourceName);",
Values =
{
{ "sourceDocId", "employees/1" },
{ "sourceName", "photo.jpg" },
{ "targetName", "photo-copy.jpg" }
}
};

// Execute the patch operation asynchronously on the target document
await store.Operations.SendAsync(new PatchOperation("employees/2", null, patchRequest));
```
</TabItem>
<TabItem value="Copy_attachment_via_patch_by_query" label="Copy_attachment_via_patch_by_query">
```csharp
// Copy an attachment to ALL documents in a collection using a patch-by-query operation
var op = store.Operations.Send(new PatchByQueryOperation(new IndexQuery
{
Query = @"
from Employees as e
update {
attachments(e, 'photo-copy.jpg').copyFrom('employees/1', 'photo.jpg');
}"
}));

op.WaitForCompletion();
```
</TabItem>
</Tabs>

</Panel>

<Panel heading="Move attachment to another document">
Expand Down Expand Up @@ -260,5 +344,29 @@ void Rename(string documentId, string name, string newName);
| **documentId** | `string` | The document ID that holds the attachment. |
| **name** | `string` | The current name of the attachment. |
| **newName** | `string` | The new name to assign to the attachment. |

---

#### Copy attachment via patch script

<TabItem>
```javascript
attachments(document, attachmentName).copyFrom(sourceDocId, sourceName)
```
</TabItem>

| Parameter | Type | Description |
|--------------------|----------|-------------|
| **document** | `object` | The target document entity (use `this` for the current document being patched). |
| **attachmentName** | `string` | The name to assign to the copied attachment in the target document. |
| **sourceDocId** | `string` | The ID of the source document that holds the attachment to copy. |
| **sourceName** | `string` | The name of the attachment to copy from the source document. |

| Return value | Description |
|--------------|-------------|
| `true` | The attachment was copied successfully. |
| `false` | The source document or the source attachment was not found. No exception is thrown. |

See [JavaScript engine](../../../server/kb/javascript-engine.mdx) for the full list of JavaScript methods available in RavenDB.

</Panel>
9 changes: 5 additions & 4 deletions docs/server/kb/javascript-engine.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,10 +128,11 @@ RavenDB provides the following set of predefined functions:

### **Attachment operations**:

| Method Signature | Return type | Description |
|-----------------------------------------------------------------------------|-------------|-----------------------------------------------------------------------------------------------------------------|
| **attachments(document, attachmentName).remote(destinationID, uploadTime)** | `void` | Updates the document's metadata with remote parameters to schedule the attachment for upload to remote storage.<br/>See [Schedule attachment for remote upload](../../document-extensions/attachments/store-attachments/store-attachments-remote.mdx#schedule-existing-attachments-for-remote-upload). |
| **attachments(document, attachmentName).delete()** | `void` | Deletes the specified attachment from the document.<br/>See [Delete attachment via patching](../../document-extensions/attachments/delete-attachment.mdx#delete-attachment---via-a-patch). |
| Method Signature | Return type | Description |
|----------------------------------------------------------------------------------|-------------|-----------------------------------------------------------------------------------------------------------------|
| **attachments(document, attachmentName)<br/>.remote(destinationID, uploadTime)** | `void` | Updates the document's metadata with remote parameters to schedule the attachment for upload to remote storage.<br/>See [Schedule attachment for remote upload](../../document-extensions/attachments/store-attachments/store-attachments-remote.mdx#schedule-existing-attachments-for-remote-upload). |
| **attachments(document, attachmentName)<br/>.delete()** | `void` | Deletes the specified attachment from the document.<br/>See [Delete attachment via patching](../../document-extensions/attachments/delete-attachment.mdx#delete-attachment---via-a-patch). |
| **attachments(targetDocument, targetAttachmentName)<br/>.copyFrom(sourceDocId, sourceName)** | `boolean` | Copies an attachment from a source document to the target document with the specified name.<br/>Returns `true` on success, `false` if the source attachment does not exist.<br/>See [Copy attachment via patching](../../document-extensions/attachments/copy-move-rename.mdx#copy-attachments---via-patching). |

---

Expand Down
Loading