0
# Data Source Operations
1

2
Query and manage data sources (database content) with filtering, sorting, and pagination capabilities.
3

4
## Capabilities
5

6
### Query Data Source
7

8
Query a database for pages matching specific criteria with filtering, sorting, and pagination.
9

10
```typescript { .api }
11
/**
12
 * Query a data source (database) for pages
13
 * @param args - Query parameters including filters and sorting
14
 * @returns Promise resolving to query results
15
 */
16
dataSources.query(args: QueryDataSourceParameters): Promise<QueryDataSourceResponse>;
17

18
interface QueryDataSourceParameters {
19
  /** ID of the database to query */
20
  data_source_id: string;
21
  /** Filter criteria for pages */
22
  filter?: FilterObject;
23
  /** Sort criteria for results */
24
  sorts?: SortObject[];
25
  /** Pagination cursor */
26
  start_cursor?: string;
27
  /** Page size (max 100) */
28
  page_size?: number;
29
  /** Properties to include in response */
30
  filter_properties?: string[];
31
}
32

33
type QueryDataSourceResponse = {
34
  object: "list";
35
  results: PageObjectResponse[];
36
  next_cursor: string | null;
37
  has_more: boolean;
38
  type: "page_or_database";
39
  page_or_database: Record<string, unknown>;
40
};
41
```
42

43
**Usage Examples:**
44

45
```typescript
46
// Basic query
47
const pages = await notion.dataSources.query({
48
  data_source_id: "database-id",
49
});
50

51
// Query with filter
52
const filteredPages = await notion.dataSources.query({
53
  data_source_id: "database-id",
54
  filter: {
55
    property: "Status",
56
    select: {
57
      equals: "In Progress",
58
    },
59
  },
60
});
61

62
// Query with multiple filters and sorting
63
const results = await notion.dataSources.query({
64
  data_source_id: "database-id",
65
  filter: {
66
    and: [
67
      {
68
        property: "Status",
69
        select: {
70
          equals: "Complete",
71
        },
72
      },
73
      {
74
        property: "Priority",
75
        number: {
76
          greater_than: 3,
77
        },
78
      },
79
    ],
80
  },
81
  sorts: [
82
    {
83
      property: "Created",
84
      direction: "descending",
85
    },
86
  ],
87
  page_size: 50,
88
});
89

90
// Paginated query
91
const nextPage = await notion.dataSources.query({
92
  data_source_id: "database-id",
93
  start_cursor: "cursor-token",
94
  page_size: 25,
95
});
96
```
97

98
### Retrieve Data Source
99

100
Get data source metadata and schema information.
101

102
```typescript { .api }
103
/**
104
 * Retrieve a data source by ID
105
 * @param args - Data source retrieval parameters
106
 * @returns Promise resolving to data source object
107
 */
108
dataSources.retrieve(args: GetDataSourceParameters): Promise<GetDataSourceResponse>;
109

110
interface GetDataSourceParameters {
111
  /** ID of the data source to retrieve */
112
  data_source_id: string;
113
}
114

115
type GetDataSourceResponse = DataSourceObjectResponse;
116
```
117

118
**Usage Examples:**
119

120
```typescript
121
// Get data source information
122
const dataSource = await notion.dataSources.retrieve({
123
  data_source_id: "data-source-id",
124
});
125
```
126

127
### Create Data Source
128

129
Create a new data source from an existing database.
130

131
```typescript { .api }
132
/**
133
 * Create a new data source
134
 * @param args - Data source creation parameters
135
 * @returns Promise resolving to created data source
136
 */
137
dataSources.create(args: CreateDataSourceParameters): Promise<CreateDataSourceResponse>;
138

139
interface CreateDataSourceParameters {
140
  /** Parent page for the data source */
141
  parent: {
142
    type: "page_id";
143
    page_id: string;
144
  };
145
  /** Database to use as source */
146
  database_id: string;
147
  /** Data source view configuration */
148
  view?: {
149
    type: "table" | "board" | "timeline" | "calendar" | "gallery" | "list";
150
  };
151
}
152

153
type CreateDataSourceResponse = DataSourceObjectResponse;
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
// Create data source from database
160
const dataSource = await notion.dataSources.create({
161
  parent: { type: "page_id", page_id: "parent-page-id" },
162
  database_id: "source-database-id",
163
  view: { type: "table" },
164
});
165
```
166

167
### Update Data Source
168

169
Update data source configuration and settings.
170

171
```typescript { .api }
172
/**
173
 * Update a data source
174
 * @param args - Data source update parameters
175
 * @returns Promise resolving to updated data source
176
 */
177
dataSources.update(args: UpdateDataSourceParameters): Promise<UpdateDataSourceResponse>;
178

179
interface UpdateDataSourceParameters {
180
  /** ID of the data source to update */
181
  data_source_id: string;
182
  /** Updated view configuration */
183
  view?: {
184
    type: "table" | "board" | "timeline" | "calendar" | "gallery" | "list";
185
  };
186
  /** Archive the data source */
187
  archived?: boolean;
188
}
189

190
type UpdateDataSourceResponse = DataSourceObjectResponse;
191
```
192

193
**Usage Examples:**
194

195
```typescript
196
// Update data source view type
197
const updatedDataSource = await notion.dataSources.update({
198
  data_source_id: "data-source-id",
199
  view: { type: "board" },
200
});
201

202
// Archive data source
203
const archivedDataSource = await notion.dataSources.update({
204
  data_source_id: "data-source-id",
205
  archived: true,
206
});
207
```
208

209
## Types
210

211
```typescript { .api }
212
interface DataSourceObjectResponse {
213
  object: "data_source";
214
  id: string;
215
  created_time: string;
216
  created_by: PartialUserObjectResponse;
217
  last_edited_time: string;
218
  last_edited_by: PartialUserObjectResponse;
219
  archived: boolean;
220
  parent: {
221
    type: "page_id";
222
    page_id: string;
223
  };
224
  database_id: string;
225
  view: {
226
    type: "table" | "board" | "timeline" | "calendar" | "gallery" | "list";
227
  };
228
}
229

230
interface PartialDataSourceObjectResponse {
231
  object: "data_source";
232
  id: string;
233
}
234

235
type FilterObject = 
236
  | PropertyFilter
237
  | CompoundFilter;
238

239
interface PropertyFilter {
240
  property: string;
241
  title?: TextFilter;
242
  rich_text?: TextFilter;
243
  number?: NumberFilter;
244
  checkbox?: CheckboxFilter;
245
  select?: SelectFilter;
246
  multi_select?: MultiSelectFilter;
247
  date?: DateFilter;
248
  people?: PeopleFilter;
249
  files?: FilesFilter;
250
  url?: TextFilter;
251
  email?: TextFilter;
252
  phone_number?: TextFilter;
253
  relation?: RelationFilter;
254
  created_by?: PeopleFilter;
255
  created_time?: DateFilter;
256
  last_edited_by?: PeopleFilter;
257
  last_edited_time?: DateFilter;
258
  formula?: FormulaFilter;
259
  rollup?: RollupFilter;
260
  status?: StatusFilter;
261
  unique_id?: UniqueIdFilter;
262
  verification?: VerificationFilter;
263
}
264

265
interface CompoundFilter {
266
  and?: FilterObject[];
267
  or?: FilterObject[];
268
}
269

270
interface TextFilter {
271
  equals?: string;
272
  does_not_equal?: string;
273
  contains?: string;
274
  does_not_contain?: string;
275
  starts_with?: string;
276
  ends_with?: string;
277
  is_empty?: true;
278
  is_not_empty?: true;
279
}
280

281
interface NumberFilter {
282
  equals?: number;
283
  does_not_equal?: number;
284
  greater_than?: number;
285
  less_than?: number;
286
  greater_than_or_equal_to?: number;
287
  less_than_or_equal_to?: number;
288
  is_empty?: true;
289
  is_not_empty?: true;
290
}
291

292
interface CheckboxFilter {
293
  equals?: boolean;
294
  does_not_equal?: boolean;
295
}
296

297
interface SelectFilter {
298
  equals?: string;
299
  does_not_equal?: string;
300
  is_empty?: true;
301
  is_not_empty?: true;
302
}
303

304
interface MultiSelectFilter {
305
  contains?: string;
306
  does_not_contain?: string;
307
  is_empty?: true;
308
  is_not_empty?: true;
309
}
310

311
interface DateFilter {
312
  equals?: string;
313
  before?: string;
314
  after?: string;
315
  on_or_before?: string;
316
  on_or_after?: string;
317
  past_week?: Record<string, never>;
318
  past_month?: Record<string, never>;
319
  past_year?: Record<string, never>;
320
  next_week?: Record<string, never>;
321
  next_month?: Record<string, never>;
322
  next_year?: Record<string, never>;
323
  is_empty?: true;
324
  is_not_empty?: true;
325
}
326

327
interface PeopleFilter {
328
  contains?: string;
329
  does_not_contain?: string;
330
  is_empty?: true;
331
  is_not_empty?: true;
332
}
333

334
interface FilesFilter {
335
  is_empty?: true;
336
  is_not_empty?: true;
337
}
338

339
interface RelationFilter {
340
  contains?: string;
341
  does_not_contain?: string;
342
  is_empty?: true;
343
  is_not_empty?: true;
344
}
345

346
interface FormulaFilter {
347
  string?: TextFilter;
348
  checkbox?: CheckboxFilter;
349
  number?: NumberFilter;
350
  date?: DateFilter;
351
}
352

353
interface RollupFilter {
354
  any?: PropertyFilter;
355
  every?: PropertyFilter;
356
  none?: PropertyFilter;
357
  number?: NumberFilter;
358
  date?: DateFilter;
359
}
360

361
interface StatusFilter {
362
  equals?: string;
363
  does_not_equal?: string;
364
  is_empty?: true;
365
  is_not_empty?: true;
366
}
367

368
interface UniqueIdFilter {
369
  equals?: number;
370
  does_not_equal?: number;
371
  greater_than?: number;
372
  less_than?: number;
373
  greater_than_or_equal_to?: number;
374
  less_than_or_equal_to?: number;
375
}
376

377
interface VerificationFilter {
378
  equals?: "verified" | "unverified";
379
  does_not_equal?: "verified" | "unverified";
380
}
381

382
interface SortObject {
383
  property?: string;
384
  timestamp?: "created_time" | "last_edited_time";
385
  direction: "ascending" | "descending";
386
}
387
```