Skip to content

Commit 96e97fc

Browse files
ItzNotABugItzNotABug
authored
Merge pull request #2128 from appwrite/add-bulk-api-docs
2 parents f054015 + d734c5f commit 96e97fc

File tree

3 files changed

+270
-0
lines changed

3 files changed

+270
-0
lines changed

‎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).

0 commit comments

Comments
 (0)