diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/attachments/bulk-insert.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/attachments/bulk-insert.dotnet.markdown new file mode 100644 index 0000000000..32faa8f501 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/attachments/bulk-insert.dotnet.markdown @@ -0,0 +1,68 @@ +# Bulk Insert Attachments + +--- + +{NOTE: } + +* [BulkInsert](../../client-api/bulk-insert/how-to-work-with-bulk-insert-operation) is RavenDB's high-performance data insertion operation. + Use its `AttachmentsFor` interface to add attachments to documents with great speed. + +* In this page: + * [Usage flow](../../document-extensions/attachments/bulk-insert#usage-flow) + * [Usage example](../../document-extensions/attachments/bulk-insert#usage-example) + * [Syntax](../../document-extensions/attachments/bulk-insert#syntax) + +{NOTE/} + +{PANEL: Usage flow} + +* Create a `BulkInsert` instance. + +* Pass the Document ID to the instance's `AttachmentsFor` method. + +* To add an attachment, call `Store`. + Pass it the attachment's name, stream, and type (optional). + The `Store` function can be called repeatedly as necessary. + +* Note: + If an attachment with the specified name already exists on the document, + the bulk insert operation will overwrite it. + +{PANEL/} + +{PANEL: Usage example} + +In this example, we attach a file to all User documents that match a query. + +{CODE-TABS} +{CODE-TAB:csharp:BulkInsert_Attachments bulk_insert_attachment@DocumentExtensions\Attachments\BulkInsert.cs /} +{CODE-TAB:csharp:User_Class user_class@DocumentExtensions\Attachments\BulkInsert.cs /} +{CODE-TABS/} + +{PANEL/} + +{PANEL: Syntax} + +{CODE AttachmentsFor-definition@DocumentExtensions\Attachments\BulkInsert.cs /} + +| Parameter | Type | Description | +|------------|----------|----------------------------------------------------------| +| `id` | `string` | The document ID to which the attachment should be added. | + +{CODE AttachmentsFor.Store-definition@DocumentExtensions\Attachments\BulkInsert.cs /} + +| Parameter | Type | Description | +|---------------|----------|------------------------------------| +| `name` | `string` | Name of attachment | +| `stream` | `Stream` | The attachment's stream | +| `contentType` | `string` | Type of attachment (default: null) | + +{PANEL/} + +## Related articles + +### Attachments + +- [Storing](../../document-extensions/attachments/storing) +- [Loading](../../document-extensions/attachments/loading) +- [Deleting](../../document-extensions/attachments/deleting) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/attachments/bulk-insert.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/attachments/bulk-insert.js.markdown new file mode 100644 index 0000000000..09dc5900f0 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/attachments/bulk-insert.js.markdown @@ -0,0 +1,68 @@ +# Bulk Insert Attachments + +--- + +{NOTE: } + +* [BulkInsert](../../client-api/bulk-insert/how-to-work-with-bulk-insert-operation) is RavenDB's high-performance data insertion operation. + Use its `attachmentsFor` interface to add attachments to documents with great speed. + +* In this page: + * [Usage flow](../../document-extensions/attachments/bulk-insert#usage-flow) + * [Usage example](../../document-extensions/attachments/bulk-insert#usage-example) + * [Syntax](../../document-extensions/attachments/bulk-insert#syntax) + +{NOTE/} + +{PANEL: Usage flow} + +* Create a `bulkInsert` instance. + +* Pass the Document ID to the instance's `attachmentsFor` method. + +* To add an attachment, call `store`. + Pass it the attachment's name, content, and type (optional). + The `store` function can be called repeatedly as necessary. + +* Note: + If an attachment with the specified name already exists on the document, + the bulk insert operation will overwrite it. + +{PANEL/} + +{PANEL: Usage example} + +In this example, we attach a file to all User documents that match a query. + +{CODE-TABS} +{CODE-TAB:nodejs:BulkInsert_Attachments bulk_insert_attachment@documentExtensions\attachments\bulkInsert.js /} +{CODE-TAB:nodejs:User_Class user_class@documentExtensions\attachments\bulkInsert.js /} +{CODE-TABS/} + +{PANEL/} + +{PANEL: Syntax} + +{CODE:nodejs syntax_1@documentExtensions\attachments\bulkInsert.js /} + +| Parameter | Type | Description | +|------------|----------|----------------------------------------------------------| +| `id` | `string` | The document ID to which the attachment should be added. | + +{CODE:nodejs syntax_2@documentExtensions\attachments\bulkInsert.js /} + +| Parameter | Type | Description | +|---------------|----------|------------------------------------| +| `name` | `string` | Name of attachment | +| `bytes` | `Buffer` | The attachment's content | +| `contentType` | `string` | Type of attachment (default: null) | + +{PANEL/} + +## Related articles + +### Attachments + +- [Storing](../../document-extensions/attachments/storing) +- [Loading](../../document-extensions/attachments/loading) +- [Deleting](../../document-extensions/attachments/deleting) diff --git a/Documentation/5.4/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/Attachments/BulkInsert.cs b/Documentation/5.4/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/Attachments/BulkInsert.cs new file mode 100644 index 0000000000..38074c129c --- /dev/null +++ b/Documentation/5.4/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/Attachments/BulkInsert.cs @@ -0,0 +1,137 @@ +using System.Linq; +using Raven.Client.Documents; +using Xunit; +using Xunit.Abstractions; +using System.Collections.Generic; +using Raven.Client.Documents.Linq; +using Raven.Client.ServerWide.Operations; +using Raven.Client.ServerWide; +using System.IO; +using System.Text; + +namespace Documentation.Samples.DocumentExtensions.TimeSeries +{ + public class BulkInsertAttachments + { + private BulkInsertAttachments(ITestOutputHelper output) + { + } + + public DocumentStore getDocumentStore() + { + DocumentStore store = new DocumentStore + { + Urls = new[] { "http://localhost:8080" }, + Database = "TestDatabase" + }; + store.Initialize(); + + var parameters = new DeleteDatabasesOperation.Parameters + { + DatabaseNames = new[] { "TestDatabase" }, + HardDelete = true, + }; + store.Maintenance.Server.Send(new DeleteDatabasesOperation(parameters)); + store.Maintenance.Server.Send(new CreateDatabaseOperation(new DatabaseRecord("TestDatabase"))); + + return store; + } + + [Fact] + public async void AppendUsingBulkInsert() + { + using (var store = getDocumentStore()) + { + // Create documents to bulk-insert to + using (var session = store.OpenSession()) + { + var user1 = new User + { + Name = "Lilly", + Age = 20 + }; + session.Store(user1); + + var user2 = new User + { + Name = "Betty", + Age = 25 + }; + session.Store(user2); + + var user3 = new User + { + Name = "Robert", + Age = 29 + }; + session.Store(user3); + + session.SaveChanges(); + } + + #region bulk_insert_attachment + List users; + + // Choose user profiles for which to attach a file + using (var session = store.OpenSession()) + { + users = session.Query() + .Where(u => u.Age < 30) + .ToList(); + } + + // Prepare content to attach + byte[] byteArray = Encoding.UTF8.GetBytes("some contents here"); + var stream = new MemoryStream(byteArray); + + // Create a BulkInsert instance + using (var bulkInsert = store.BulkInsert()) + { + for (var i = 0; i < users.Count; i++) + { + string userId = users[i].Id; + + // Call 'AttachmentsFor', pass the document ID for which to attach the file + var attachmentsBulkInsert = bulkInsert.AttachmentsFor(userId); + + // Call 'Store' to add the file to the BulkInsert instance + // The data stored in bulkInsert will be streamed to the server in batches + attachmentsBulkInsert.Store("AttachmentName", stream); + } + } + #endregion + } + } + + #region user_class + public class User + { + public string Id { get; set; } + public string Name { get; set; } + public string LastName { get; set; } + public string AddressId { get; set; } + public int Count { get; set; } + public int Age { get; set; } + } + #endregion + + #region AttachmentsFor-definition + public AttachmentsBulkInsert AttachmentsFor(string id) + #endregion + { + return new AttachmentsBulkInsert(); + } + + public struct AttachmentsBulkInsert + { + } + + #region AttachmentsFor.Store-definition + public void Store(string name, Stream stream, string contentType = null) + #endregion + { + } + + } +} + diff --git a/Documentation/5.4/Samples/nodejs/documentExtensions/attachments/bulkInsert.js b/Documentation/5.4/Samples/nodejs/documentExtensions/attachments/bulkInsert.js new file mode 100644 index 0000000000..602c03bfb6 --- /dev/null +++ b/Documentation/5.4/Samples/nodejs/documentExtensions/attachments/bulkInsert.js @@ -0,0 +1,64 @@ +import { DocumentStore } from "ravendb"; + +const documentStore = new DocumentStore(); + +async function bulkInsertAttachments() { + { + //region bulk_insert_attachment + // Open a session + const session = documentStore.openSession(); + + // Choose user profiles for which to attach a file + const users = await session.query({ collection: "users" }) + .whereLessThan("age", 30) + .all(); + + // Prepare content that will be attached + const text = "Some contents here"; + const byteArray = Buffer.from(text); + + // Create a bulkInsert instance + const bulkInsert = documentStore.bulkInsert(); + + try { + for (let i = 0; i < users.length; i++) { + + // Call `attachmentsFor`, pass the document ID for which to attach the file + const attachmentsBulkInsert = bulkInsert.attachmentsFor(users[i].id); + + // Call 'store' to attach the byte array to the bulkInsert instance + // The data stored in bulkInsert will be streamed to the server in batches + await attachmentsBulkInsert.store("attachmentName", byteArray); + } + } finally { + // Call finish to send all remaining data to the server + await bulkInsert.finish(); + } + //endregion + } +} + +//region syntax_1 +attachmentsFor(id); +//endregion + +//region syntax_2 +store(name, bytes); +store(name, bytes, contentType); +//endregion + +//region user_class +class User { + constructor( + id = null, + age = 0, + name = '' + ) { + Object.assign(this, { + id, + age, + name + }); + } +} +//endregion