0
# Database Operations
1

2
Manage Notion databases including creation, updates, and retrieval of database schemas and metadata.
3

4
## Capabilities
5

6
### Retrieve Database
7

8
Get a database by its ID, including schema information and properties.
9

10
```typescript { .api }
11
/**
12
 * Retrieve a database by ID
13
 * @param args - Database retrieval parameters
14
 * @returns Promise resolving to database object
15
 */
16
databases.retrieve(args: GetDatabaseParameters): Promise<GetDatabaseResponse>;
17

18
interface GetDatabaseParameters {
19
  /** ID of the database to retrieve */
20
  database_id: string;
21
}
22

23
type GetDatabaseResponse = DatabaseObjectResponse;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
// Get database schema and metadata
30
const database = await notion.databases.retrieve({
31
  database_id: "database-id-here",
32
});
33

34
console.log(database.title); // Database title
35
console.log(database.properties); // Property schema
36
```
37

38
### Create Database
39

40
Create a new database with specified properties and schema.
41

42
```typescript { .api }
43
/**
44
 * Create a new database
45
 * @param args - Database creation parameters
46
 * @returns Promise resolving to created database
47
 */
48
databases.create(args: CreateDatabaseParameters): Promise<CreateDatabaseResponse>;
49

50
interface CreateDatabaseParameters {
51
  /** Parent page for the database */
52
  parent: {
53
    type: "page_id";
54
    page_id: string;
55
  };
56
  /** Database title */
57
  title?: RichTextItemResponse[];
58
  /** Database properties schema */
59
  properties: Record<string, PropertySchema>;
60
  /** Database icon */
61
  icon?: {
62
    type: "emoji";
63
    emoji: string;
64
  } | {
65
    type: "external";
66
    external: { url: string };
67
  } | {
68
    type: "file";
69
    file: { url: string; expiry_time: string };
70
  };
71
  /** Database cover image */
72
  cover?: {
73
    type: "external";
74
    external: { url: string };
75
  } | {
76
    type: "file";
77
    file: { url: string; expiry_time: string };
78
  };
79
  /** Database description */
80
  description?: RichTextItemResponse[];
81
  /** Whether database is inline */
82
  is_inline?: boolean;
83
}
84

85
type CreateDatabaseResponse = DatabaseObjectResponse;
86
```
87

88
**Usage Examples:**
89

90
```typescript
91
// Create a task database
92
const database = await notion.databases.create({
93
  parent: { type: "page_id", page_id: "parent-page-id" },
94
  title: [{ text: { content: "Task Database" } }],
95
  properties: {
96
    Name: {
97
      title: {},
98
    },
99
    Status: {
100
      select: {
101
        options: [
102
          { name: "Not started", color: "gray" },
103
          { name: "In progress", color: "yellow" },
104
          { name: "Complete", color: "green" },
105
        ],
106
      },
107
    },
108
    Priority: {
109
      number: {
110
        format: "number",
111
      },
112
    },
113
    "Due Date": {
114
      date: {},
115
    },
116
    Assignee: {
117
      people: {},
118
    },
119
  },
120
});
121

122
// Create database with cover and description
123
const database = await notion.databases.create({
124
  parent: { type: "page_id", page_id: "parent-id" },
125
  title: [{ text: { content: "Project Tracker" } }],
126
  description: [{ text: { content: "Track project progress and milestones" } }],
127
  icon: { type: "emoji", emoji: "📊" },
128
  cover: {
129
    type: "external",
130
    external: { url: "https://example.com/cover.jpg" },
131
  },
132
  properties: {
133
    "Project Name": { title: {} },
134
    Progress: {
135
      number: { format: "percent" },
136
    },
137
  },
138
});
139
```
140

141
### Update Database
142

143
Update database title, description, properties, or other metadata.
144

145
```typescript { .api }
146
/**
147
 * Update a database's schema and metadata
148
 * @param args - Database update parameters
149
 * @returns Promise resolving to updated database
150
 */
151
databases.update(args: UpdateDatabaseParameters): Promise<UpdateDatabaseResponse>;
152

153
interface UpdateDatabaseParameters {
154
  /** ID of the database to update */
155
  database_id: string;
156
  /** Updated database title */
157
  title?: RichTextItemResponse[];
158
  /** Updated database description */
159
  description?: RichTextItemResponse[];
160
  /** Updated database properties schema */
161
  properties?: Record<string, PropertySchema | null>;
162
  /** Updated database icon */
163
  icon?: {
164
    type: "emoji";
165
    emoji: string;
166
  } | {
167
    type: "external";
168
    external: { url: string };
169
  } | {
170
    type: "file";
171
    file: { url: string; expiry_time: string };
172
  } | null;
173
  /** Updated database cover */
174
  cover?: {
175
    type: "external";
176
    external: { url: string };
177
  } | {
178
    type: "file";
179
    file: { url: string; expiry_time: string };
180
  } | null;
181
  /** Archive the database */
182
  archived?: boolean;
183
}
184

185
type UpdateDatabaseResponse = DatabaseObjectResponse;
186
```
187

188
**Usage Examples:**
189

190
```typescript
191
// Update database title and description
192
const updatedDatabase = await notion.databases.update({
193
  database_id: "database-id",
194
  title: [{ text: { content: "Updated Task Database" } }],
195
  description: [{ text: { content: "Updated description" } }],
196
});
197

198
// Add new property to database
199
const updatedDatabase = await notion.databases.update({
200
  database_id: "database-id",
201
  properties: {
202
    "New Property": {
203
      rich_text: {},
204
    },
205
  },
206
});
207

208
// Remove property from database
209
const updatedDatabase = await notion.databases.update({
210
  database_id: "database-id",
211
  properties: {
212
    "Old Property": null, // Remove property
213
  },
214
});
215

216
// Update database icon
217
const updatedDatabase = await notion.databases.update({
218
  database_id: "database-id",
219
  icon: {
220
    type: "emoji",
221
    emoji: "🗂️",
222
  },
223
});
224
```
225

226
## Types
227

228
```typescript { .api }
229
interface DatabaseObjectResponse {
230
  object: "database";
231
  id: string;
232
  created_time: string;
233
  created_by: PartialUserObjectResponse;
234
  last_edited_time: string;
235
  last_edited_by: PartialUserObjectResponse;
236
  title: RichTextItemResponse[];
237
  description: RichTextItemResponse[];
238
  icon?: {
239
    type: "emoji";
240
    emoji: string;
241
  } | {
242
    type: "external";
243
    external: { url: string };
244
  } | {
245
    type: "file";
246
    file: { url: string; expiry_time: string };
247
  };
248
  cover?: {
249
    type: "external";
250
    external: { url: string };
251
  } | {
252
    type: "file";
253
    file: { url: string; expiry_time: string };
254
  };
255
  properties: Record<string, PropertySchema>;
256
  parent: {
257
    type: "page_id";
258
    page_id: string;
259
  } | {
260
    type: "workspace";
261
    workspace: true;
262
  };
263
  url: string;
264
  archived: boolean;
265
  is_inline: boolean;
266
  public_url?: string;
267
}
268

269
interface PartialDatabaseObjectResponse {
270
  object: "database";
271
  id: string;
272
}
273

274
type PropertySchema = 
275
  | { type: "title"; title: Record<string, never> }
276
  | { type: "rich_text"; rich_text: Record<string, never> }
277
  | { type: "number"; number: { format: "number" | "number_with_commas" | "percent" | "dollar" | "canadian_dollar" | "euro" | "pound" | "yen" | "ruble" | "rupee" | "won" | "yuan" | "real" | "lira" | "rupiah" | "franc" | "hong_kong_dollar" | "new_zealand_dollar" | "krona" | "norwegian_krone" | "mexican_peso" | "rand" | "new_taiwan_dollar" | "danish_krone" | "zloty" | "baht" | "forint" | "koruna" | "shekel" | "chilean_peso" | "philippine_peso" | "dirham" | "colombian_peso" | "riyal" | "ringgit" | "leu" | "argentine_peso" | "uruguayan_peso" } }
278
  | { type: "select"; select: { options: { name: string; color: string }[] } }
279
  | { type: "multi_select"; multi_select: { options: { name: string; color: string }[] } }
280
  | { type: "date"; date: Record<string, never> }
281
  | { type: "people"; people: Record<string, never> }
282
  | { type: "files"; files: Record<string, never> }
283
  | { type: "checkbox"; checkbox: Record<string, never> }
284
  | { type: "url"; url: Record<string, never> }
285
  | { type: "email"; email: Record<string, never> }
286
  | { type: "phone_number"; phone_number: Record<string, never> }
287
  | { type: "formula"; formula: { expression: string } }
288
  | { type: "relation"; relation: { database_id: string; synced_property_name?: string; synced_property_id?: string } }
289
  | { type: "rollup"; rollup: { relation_property_name: string; relation_property_id: string; rollup_property_name: string; rollup_property_id: string; function: "count" | "count_values" | "empty" | "not_empty" | "unique" | "show_unique" | "percent_empty" | "percent_not_empty" | "sum" | "average" | "median" | "min" | "max" | "range" | "earliest_date" | "latest_date" | "date_range" | "checked" | "unchecked" | "percent_checked" | "percent_unchecked" | "count_per_group" | "percent_per_group" | "show_original" } }
290
  | { type: "created_time"; created_time: Record<string, never> }
291
  | { type: "created_by"; created_by: Record<string, never> }
292
  | { type: "last_edited_time"; last_edited_time: Record<string, never> }
293
  | { type: "last_edited_by"; last_edited_by: Record<string, never> }
294
  | { type: "status"; status: { options: { name: string; color: string }[]; groups: { name: string; color: string; option_ids: string[] }[] } }
295
  | { type: "unique_id"; unique_id: { prefix?: string } }
296
  | { type: "verification"; verification: Record<string, never> };
297
```