0
# Core Operations
1

2
Primary CRUD operations for interacting with collections and managing content. These operations form the foundation of all content management workflows in Payload.
3

4
## Capabilities
5

6
### Create Operation
7

8
Creates a new document in the specified collection.
9

10
```typescript { .api }
11
/**
12
 * Creates a new document in the specified collection
13
 * @param options - Creation options including collection, data, and configuration
14
 * @returns Promise resolving to the created document
15
 */
16
function create<T>(options: CreateOptions<T>): Promise<T>;
17

18
interface CreateOptions<T> {
19
  /** The collection slug to create the document in */
20
  collection: string;
21
  /** The data for the new document */
22
  data: Partial<T>;
23
  /** How many levels deep to populate relationships (default: 0) */
24
  depth?: number;
25
  /** Locale for the operation */
26
  locale?: string;
27
  /** Fallback locale if content not found in specified locale */
28
  fallbackLocale?: string;
29
  /** User context for access control */
30
  user?: User;
31
  /** Whether to override access control (requires proper permissions) */
32
  overrideAccess?: boolean;
33
  /** Whether to include hidden fields in the response */
34
  showHiddenFields?: boolean;
35
  /** Express request object for context */
36
  req?: PayloadRequest;
37
  /** Whether to save as draft */
38
  draft?: boolean;
39
  /** File path for file uploads */
40
  filePath?: string;
41
  /** File object for uploads */
42
  file?: File;
43
  /** Whether to overwrite existing files */
44
  overwriteExistingFiles?: boolean;
45
  /** Disable verification email for auth collections */
46
  disableVerificationEmail?: boolean;
47
}
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
import payload from "payload";
54

55
// Create a blog post
56
const post = await payload.create({
57
  collection: "posts",
58
  data: {
59
    title: "My First Post",
60
    content: "Hello, world!",
61
    status: "draft",
62
    author: userId,
63
  },
64
});
65

66
// Create with relationships populated
67
const postWithAuthor = await payload.create({
68
  collection: "posts",
69
  data: {
70
    title: "Post with Author",
71
    content: "Content here",
72
    author: authorId,
73
  },
74
  depth: 1, // Populate the author relationship
75
});
76

77
// Create with specific locale
78
const localizedPost = await payload.create({
79
  collection: "posts",
80
  data: {
81
    title: "Mon Premier Article",
82
    content: "Contenu en français",
83
  },
84
  locale: "fr",
85
});
86
```
87

88
### Find Operations
89

90
Query documents from collections with flexible filtering, sorting, and pagination.
91

92
```typescript { .api }
93
/**
94
 * Find documents with criteria
95
 * @param options - Find options including collection, query parameters, and configuration
96
 * @returns Promise resolving to paginated documents
97
 */
98
function find<T>(options: FindOptions): Promise<PaginatedDocs<T>>;
99

100
/**
101
 * Find a specific document by ID
102
 * @param options - Find by ID options
103
 * @returns Promise resolving to the document
104
 */
105
function findByID<T>(options: FindByIDOptions): Promise<T>;
106

107
interface FindOptions {
108
  /** The collection slug to query */
109
  collection: string;
110
  /** Query conditions */
111
  where?: Where;
112
  /** Sort field and direction (e.g., "-createdAt", "title") */
113
  sort?: string;
114
  /** Maximum number of documents to return */
115
  limit?: number;
116
  /** Page number for pagination (1-based) */
117
  page?: number;
118
  /** How many levels deep to populate relationships */
119
  depth?: number;
120
  /** Locale for the operation */
121
  locale?: string;
122
  /** Fallback locale if content not found in specified locale */
123
  fallbackLocale?: string;
124
  /** User context for access control */
125
  user?: User;
126
  /** Whether to override access control */
127
  overrideAccess?: boolean;
128
  /** Whether to include hidden fields */
129
  showHiddenFields?: boolean;
130
  /** Express request object for context */
131
  req?: PayloadRequest;
132
  /** Current depth for recursive calls */
133
  currentDepth?: number;
134
  /** Whether to enable pagination */
135
  pagination?: boolean;
136
  /** Whether to include draft documents */
137
  draft?: boolean;
138
  /** Disable error throwing */
139
  disableErrors?: boolean;
140
}
141

142
interface FindByIDOptions {
143
  /** The collection slug */
144
  collection: string;
145
  /** Document ID to find */
146
  id: string | number;
147
  /** How many levels deep to populate relationships */
148
  depth?: number;
149
  /** Locale for the operation */
150
  locale?: string;
151
  /** Fallback locale if content not found in specified locale */
152
  fallbackLocale?: string;
153
  /** User context for access control */
154
  user?: User;
155
  /** Whether to override access control */
156
  overrideAccess?: boolean;
157
  /** Whether to include hidden fields */
158
  showHiddenFields?: boolean;
159
}
160

161
interface PaginatedDocs<T> {
162
  /** Array of documents */
163
  docs: T[];
164
  /** Total number of documents matching the query */
165
  totalDocs: number;
166
  /** Number of documents per page */
167
  limit: number;
168
  /** Total number of pages */
169
  totalPages: number;
170
  /** Current page number */
171
  page: number;
172
  /** Starting counter for current page */
173
  pagingCounter: number;
174
  /** Whether there is a previous page */
175
  hasPrevPage: boolean;
176
  /** Whether there is a next page */
177
  hasNextPage: boolean;
178
  /** Previous page number (if available) */
179
  prevPage?: number;
180
  /** Next page number (if available) */
181
  nextPage?: number;
182
}
183
```
184

185
**Usage Examples:**
186

187
```typescript
188
// Find all published posts
189
const publishedPosts = await payload.find({
190
  collection: "posts",
191
  where: {
192
    status: {
193
      equals: "published",
194
    },
195
  },
196
  sort: "-createdAt",
197
  limit: 10,
198
});
199

200
// Find with complex where conditions
201
const featuredPosts = await payload.find({
202
  collection: "posts",
203
  where: {
204
    and: [
205
      {
206
        status: {
207
          equals: "published",
208
        },
209
      },
210
      {
211
        featured: {
212
          equals: true,
213
        },
214
      },
215
    ],
216
  },
217
});
218

219
// Find with populated relationships
220
const postsWithAuthors = await payload.find({
221
  collection: "posts",
222
  depth: 2, // Populate author and author's profile
223
});
224

225
// Find by ID
226
const specificPost = await payload.findByID({
227
  collection: "posts",
228
  id: "60f7b8c4e4b0b8001f5e4b0a",
229
  depth: 1,
230
});
231
```
232

233
### Update Operation
234

235
Updates an existing document in the specified collection.
236

237
```typescript { .api }
238
/**
239
 * Update an existing document
240
 * @param options - Update options including collection, ID, data, and configuration
241
 * @returns Promise resolving to the updated document
242
 */
243
function update<T>(options: UpdateOptions<T>): Promise<T>;
244

245
interface UpdateOptions<T> {
246
  /** The collection slug */
247
  collection: string;
248
  /** Document ID to update */
249
  id?: string | number;
250
  /** Query conditions (alternative to ID) */
251
  where?: Where;
252
  /** Updated data (partial update) */
253
  data: Partial<T>;
254
  /** How many levels deep to populate relationships */
255
  depth?: number;
256
  /** Locale for the operation */
257
  locale?: string;
258
  /** Fallback locale if content not found in specified locale */
259
  fallbackLocale?: string;
260
  /** User context for access control */
261
  user?: User;
262
  /** Whether to override access control */
263
  overrideAccess?: boolean;
264
  /** Whether to include hidden fields */
265
  showHiddenFields?: boolean;
266
}
267
```
268

269
**Usage Examples:**
270

271
```typescript
272
// Update by ID
273
const updatedPost = await payload.update({
274
  collection: "posts",
275
  id: postId,
276
  data: {
277
    title: "Updated Title",
278
    status: "published",
279
  },
280
});
281

282
// Update with query conditions
283
const publishedPosts = await payload.update({
284
  collection: "posts",
285
  where: {
286
    status: {
287
      equals: "draft",
288
    },
289
  },
290
  data: {
291
    status: "published",
292
  },
293
});
294

295
// Update with populated relationships
296
const postWithAuthor = await payload.update({
297
  collection: "posts",
298
  id: postId,
299
  data: {
300
    content: "Updated content",
301
  },
302
  depth: 1,
303
});
304
```
305

306
### Delete Operation
307

308
Deletes a document from the specified collection.
309

310
```typescript { .api }
311
/**
312
 * Delete a document
313
 * @param options - Delete options including collection and ID
314
 * @returns Promise resolving to the deleted document
315
 */
316
function delete<T>(options: DeleteOptions): Promise<T>;
317

318
interface DeleteOptions {
319
  /** The collection slug */
320
  collection: string;
321
  /** Document ID to delete */
322
  id?: string | number;
323
  /** Query conditions (alternative to ID) */
324
  where?: Where;
325
  /** How many levels deep to populate relationships in response */
326
  depth?: number;
327
  /** Locale for the operation */
328
  locale?: string;
329
  /** Fallback locale if content not found in specified locale */
330
  fallbackLocale?: string;
331
  /** User context for access control */
332
  user?: User;
333
  /** Whether to override access control */
334
  overrideAccess?: boolean;
335
  /** Whether to include hidden fields */
336
  showHiddenFields?: boolean;
337
}
338
```
339

340
**Usage Examples:**
341

342
```typescript
343
// Delete by ID
344
const deletedPost = await payload.delete({
345
  collection: "posts",
346
  id: postId,
347
});
348

349
// Delete with query conditions
350
const deletedDrafts = await payload.delete({
351
  collection: "posts",
352
  where: {
353
    status: {
354
      equals: "draft",
355
    },
356
  },
357
});
358
```
359

360
## Query System
361

362
### Where Conditions
363

364
Complex query conditions for filtering documents.
365

366
```typescript { .api }
367
interface Where {
368
  [key: string]: any;
369
  /** Logical AND conditions */
370
  and?: Where[];
371
  /** Logical OR conditions */
372
  or?: Where[];
373
}
374

375
// Field operators
376
interface FieldOperators {
377
  /** Exact match */
378
  equals?: any;
379
  /** Not equal */
380
  not_equals?: any;
381
  /** Greater than */
382
  greater_than?: number | Date;
383
  /** Greater than or equal */
384
  greater_than_equal?: number | Date;
385
  /** Less than */
386
  less_than?: number | Date;
387
  /** Less than or equal */
388
  less_than_equal?: number | Date;
389
  /** Text contains (case-insensitive) */
390
  like?: string;
391
  /** Array contains value */
392
  contains?: any;
393
  /** Value exists in array */
394
  in?: any[];
395
  /** Value not in array */
396
  not_in?: any[];
397
  /** Field exists */
398
  exists?: boolean;
399
  /** Geographic near query */
400
  near?: {
401
    point: [number, number]; // [longitude, latitude]
402
    maxDistance?: number;
403
    minDistance?: number;
404
  };
405
}
406
```
407

408
**Query Examples:**
409

410
```typescript
411
// Complex where conditions
412
const complexQuery = await payload.find({
413
  collection: "posts",
414
  where: {
415
    or: [
416
      {
417
        and: [
418
          {
419
            status: {
420
              equals: "published",
421
            },
422
          },
423
          {
424
            createdAt: {
425
              greater_than: "2023-01-01",
426
            },
427
          },
428
        ],
429
      },
430
      {
431
        featured: {
432
          equals: true,
433
        },
434
      },
435
    ],
436
  },
437
});
438

439
// Text search
440
const searchResults = await payload.find({
441
  collection: "posts",
442
  where: {
443
    title: {
444
      like: "react",
445
    },
446
  },
447
});
448

449
// Array queries
450
const taggedPosts = await payload.find({
451
  collection: "posts",
452
  where: {
453
    tags: {
454
      contains: "javascript",
455
    },
456
  },
457
});
458
```