Skip to content

Commit 30891f3

Browse files
ebenezerdonebenezerdon
authored
Merge branch 'main' into blog-bulk-api
2 parents 43aa6d3 + 3175e85 commit 30891f3

File tree

6 files changed

+353
-0
lines changed

6 files changed

+353
-0
lines changed

‎src/routes/blog/post/announcing-bulk-api/+page.markdoc

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
layout: post
3+
title: "Announcing Bulk API: Handle heavy data workloads with ease"
4+
description: Perform multiple database operations in a single API call. Enjoy faster writes and better performance for heavy server-side workloads.
5+
date: 2025-07-03
6+
cover: /images/blog/announcing-bulk-api/cover.png
7+
timeToRead: 5
8+
author: jake-barnby
9+
category: announcement
10+
featured: false
11+
---
12+
13+
We're excited to introduce another Appwrite Databases feature, **Bulk API**. Explicitly designed to handle heavy write workloads, Bulk API dramatically improves performance by allowing multiple database operations in a single API call.
14+
15+
# Faster development with bulk actions
16+
17+
Previously, writing or modifying large amounts of data in Appwrite Databases required sending one request per document. This method was inefficient, slow, and resource-intensive, especially when dealing with thousands of records.
18+
19+
With the new Bulk API, you can create, update, or delete multiple documents in one go, vastly speeding up your workflows and reducing network overhead.
20+
21+
# Optimized for server-side workloads
22+
23+
Bulk API is crafted for server-side applications, particularly those with significant data demands. Whether you’re importing large datasets, performing batch updates, or cleaning out old records, Bulk API streamlines your workload, drastically cutting down the number of requests and enhancing your application's performance.
24+
25+
This will have immediate and impactful benefits such as:
26+
27+
- **Speed improvements**: Rapidly handle thousands of operations simultaneously.
28+
- **Lower network overhead**: Significantly fewer API requests needed, making your application faster and more efficient.
29+
- **Seamless integration**: Works effortlessly using Appwrite Cloud or hosting yourself.
30+
31+
{% info title="Please Note" %}
32+
Bulk operations can only be performed via the server-side SDKs. The client-side SDKs do not support bulk operations.
33+
{% /info %}
34+
35+
# How it works
36+
37+
Utilizing the Bulk API is straightforward. You can use it to:
38+
39+
- Create multiple documents in a single request using the `createDocuments` method
40+
- Update multiple documents in a single request using the `updateDocuments` method
41+
- Delete multiple documents in a single request using the `deleteDocuments` method
42+
- Upsert multiple documents in a single request using the `upsertDocuments` method
43+
44+
Here is a code example for creating multiple documents in a single request:
45+
46+
47+
```server-nodejs
48+
const sdk = require('node-appwrite');
49+
50+
const client = new sdk.Client()
51+
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
52+
.setProject('<PROJECT_ID>')
53+
.setKey('<API_KEY>');
54+
55+
const databases = new sdk.Databases(client);
56+
57+
const result = await databases.createDocuments(
58+
'<DATABASE_ID>',
59+
'<COLLECTION_ID>',
60+
[
61+
{
62+
$id: sdk.ID.unique(),
63+
name: 'Document 1',
64+
},
65+
{
66+
$id: sdk.ID.unique(),
67+
name: 'Document 2',
68+
}
69+
]
70+
);
71+
```
72+
73+
74+
# Built for intensive data tasks
75+
76+
Bulk API was designed to move large volumes of data in and out of Appwrite. By simplifying and speeding up these tasks, Bulk API unlocks previously challenging use-cases, expanding what's possible with Appwrite.
77+
78+
With Bulk API, your high-performance data operations are faster, simpler, and more efficient.
79+
80+
# More resources
81+
- [Read the documentation to get started](/docs/products/databases/bulk-operations)
82+
- [Introducing Database Backups](/blog/post/introducing-database-backups)
83+
- [More Database blogs](https://appwrite.io/blog?search=database)

‎src/routes/docs/products/databases/+layout.svelte

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,11 @@
5858
label: 'Backups',
5959
href: '/docs/products/databases/backups'
6060
},
61+
{
62+
label: 'Bulk Operations',
63+
href: '/docs/products/databases/bulk-operations',
64+
new: isNewUntil('31 Jul 2025')
65+
},
6166
{
6267
label: 'CSV Imports',
6368
href: '/docs/products/databases/csv-imports',

‎src/routes/docs/products/databases/bulk-operations/+page.markdoc

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
---
2+
layout: article
3+
title: Bulk Operations
4+
description: Perform bulk operations on documents within your collections for efficient data handling.
5+
---
6+
7+
Appwrite Databases supports bulk operations for documents, allowing you to create, update, or delete multiple documents in a single request. This can significantly improve performance for apps as it allows you to reduce the number of API calls needed while working with large data sets.
8+
9+
As of now, bulk operations can only be performed via the server-side SDKs. The client-side SDKs do not support bulk operations.
10+
11+
# Create documents {% #create-documents %}
12+
13+
{% info title="Permissions required" %}
14+
You must grant **create** permissions to users at the **collection level** before users can create documents.
15+
[Learn more about permissions](/docs/products/databases/permissions)
16+
{% /info %}
17+
18+
You can create multiple documents in a single request using the `createDocuments` method.
19+
20+
{% multicode %}
21+
```server-nodejs
22+
const sdk = require('node-appwrite');
23+
24+
const client = new sdk.Client()
25+
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
26+
.setProject('<PROJECT_ID>')
27+
.setKey('<API_KEY>');
28+
29+
const databases = new sdk.Databases(client);
30+
31+
const result = await databases.createDocuments(
32+
'<DATABASE_ID>',
33+
'[COLLECTION_ID]',
34+
[
35+
{
36+
documentId: sdk.ID.unique(),
37+
data: { name: 'Document 1' }
38+
},
39+
{
40+
documentId: sdk.ID.unique(),
41+
data: { name: 'Document 2' }
42+
}
43+
]
44+
);
45+
```
46+
47+
```server-python
48+
from appwrite.client import Client
49+
from appwrite.services.databases import Databases
50+
51+
client = Client()
52+
client.set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
53+
client.set_project('<PROJECT_ID>')
54+
client.set_key('<API_KEY>')
55+
56+
databases = Databases(client)
57+
58+
result = databases.create_documents(
59+
database_id = '<DATABASE_ID>',
60+
collection_id = '<COLLECTION_ID>',
61+
documents = [
62+
{
63+
'documentId': appwrite.ID.unique(),
64+
'data': { 'name': 'Document 1' }
65+
},
66+
{
67+
'documentId': appwrite.ID.unique(),
68+
'data': { 'name': 'Document 2' }
69+
}
70+
]
71+
)
72+
```
73+
{% /multicode %}
74+
75+
# Update documents {% #update-documents %}
76+
77+
{% info title="Permissions required" %}
78+
You must grant **update** permissions to users at the **collection level** before users can update documents.
79+
[Learn more about permissions](/docs/products/databases/permissions)
80+
{% /info %}
81+
82+
You can update multiple documents in a single request using the `updateDocuments` method.
83+
84+
{% multicode %}
85+
```server-nodejs
86+
const sdk = require('node-appwrite');
87+
88+
const client = new sdk.Client()
89+
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
90+
.setProject('<PROJECT_ID>')
91+
.setKey('<API_KEY>');
92+
93+
const databases = new sdk.Databases(client);
94+
95+
const result = await databases.updateDocuments(
96+
'<DATABASE_ID>',
97+
'[COLLECTION_ID]',
98+
{
99+
{
100+
documentId: 'document-id-1',
101+
data: { name: 'Updated Document 1' }
102+
},
103+
{
104+
documentId: 'document-id-2',
105+
data: { name: 'Updated Document 2' }
106+
}
107+
}
108+
);
109+
```
110+
111+
```server-python
112+
from appwrite.client import Client
113+
from appwrite.services.databases import Databases
114+
115+
client = Client()
116+
client.set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
117+
client.set_project('<PROJECT_ID>')
118+
client.set_key('<API_KEY>')
119+
120+
databases = Databases(client)
121+
122+
result = databases.update_documents(
123+
database_id = '<DATABASE_ID>',
124+
collection_id = '<COLLECTION_ID>',
125+
data = {
126+
{
127+
'documentId': 'document-id-1',
128+
'data': { 'name': 'New Document 1' }
129+
},
130+
{
131+
'documentId': 'document-id-2',
132+
'data': { 'name': 'New Document 2' }
133+
}
134+
}
135+
)
136+
```
137+
{% /multicode %}
138+
139+
# Upsert documents {% #upsert-documents %}
140+
141+
{% info title="Permissions required" %}
142+
You must grant **create** and **update** permissions to users at the **collection level** before users can create documents.
143+
[Learn more about permissions](/docs/products/databases/permissions)
144+
{% /info %}
145+
146+
You can upsert multiple documents in a single request using the `upsertDocuments` method.
147+
148+
{% multicode %}
149+
```server-nodejs
150+
const sdk = require('node-appwrite');
151+
152+
const client = new sdk.Client()
153+
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
154+
.setProject('<PROJECT_ID>')
155+
.setKey('<API_KEY>');
156+
157+
const databases = new sdk.Databases(client);
158+
159+
const result = await databases.upsertDocuments(
160+
'<DATABASE_ID>',
161+
'[COLLECTION_ID]',
162+
[
163+
{
164+
documentId: sdk.ID.unique(),
165+
data: { name: 'New Document 1' }
166+
},
167+
{
168+
documentId: 'document-id-2', // Existing document ID
169+
data: { name: 'New Document 2' }
170+
}
171+
]
172+
);
173+
```
174+
175+
```server-python
176+
from appwrite.client import Client
177+
from appwrite.services.databases import Databases
178+
179+
client = Client()
180+
client.set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
181+
client.set_project('<PROJECT_ID>')
182+
client.set_key('<API_KEY>')
183+
184+
databases = Databases(client)
185+
186+
result = databases.upsert_documents(
187+
database_id = '<DATABASE_ID>',
188+
collection_id = '<COLLECTION_ID>',
189+
documents = [
190+
{
191+
'documentId': appwrite.ID.unique(),
192+
'data': { 'name': 'Document 1' }
193+
},
194+
{
195+
'documentId': 'document-id-2', # Existing document ID
196+
'data': { 'name': 'New Document 2' }
197+
}
198+
]
199+
)
200+
```
201+
{% /multicode %}
202+
203+
# Delete documents {% #delete-documents %}
204+
205+
{% info title="Permissions required" %}
206+
You must grant **delete** permissions to users at the **collection level** before users can delete documents.
207+
[Learn more about permissions](/docs/products/databases/permissions)
208+
{% /info %}
209+
210+
You can delete multiple documents in a single request using the `deleteDocuments` method.
211+
212+
{% multicode %}
213+
```server-nodejs
214+
const sdk = require('node-appwrite');
215+
216+
const client = new sdk.Client()
217+
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
218+
.setProject('<PROJECT_ID>')
219+
.setKey('<API_KEY>');
220+
221+
const databases = new sdk.Databases(client);
222+
223+
const result = await databases.deleteDocuments(
224+
'<DATABASE_ID>',
225+
'[COLLECTION_ID]',
226+
[] // Queries
227+
);
228+
```
229+
230+
```server-python
231+
from appwrite.client import Client
232+
from appwrite.services.databases import Databases
233+
234+
client = Client()
235+
client.set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
236+
client.set_project('<PROJECT_ID>')
237+
client.set_key('<API_KEY>')
238+
239+
databases = Databases(client)
240+
241+
result = databases.delete_documents(
242+
database_id = '<DATABASE_ID>',
243+
collection_id = '<COLLECTION_ID>',
244+
queries = []
245+
)
246+
```
247+
{% /multicode %}
248+
249+
{% info title="Queries for deletion" %}
250+
251+
When deleting documents, you must specify queries to filter which documents to delete.
252+
253+
If no queries are provided, all documents in the collection will be deleted.
254+
255+
[Learn more about queries](/docs/products/databases/queries).
256+
257+
{% /info %}

‎src/routes/docs/products/databases/documents/+page.markdoc

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -264,3 +264,11 @@ Read, update, and delete permissions can be granted at both the collection and d
264264
Users only need to be granted access at either the collection or document level to access documents.
265265

266266
[Learn about configuring permissions](/docs/products/databases/permissions).
267+
268+
# Bulk operations {% #bulk-operations %}
269+
270+
In Appwrite, you can perform bulk operations on documents within a collection. This allows you to create, update, or delete multiple documents in a single request.
271+
272+
As of now, bulk operations can only be performed via the server-side SDKs. The client-side SDKs do not support bulk operations.
273+
274+
[Learn more about bulk operations](/docs/products/databases/bulk-operations).

‎static/images/blog/announcing-bulk-api/cover.png

98.4 KB
Loading

‎static/images/changelog/2025-07-03.png

98.4 KB
Loading

0 commit comments

Comments
 (0)