0
# Collection Operations
1

2
Database and collection view management for querying structured data, including filtering, sorting, and pagination. Perfect for working with Notion databases.
3

4
## Capabilities
5

6
### Get Collection Data
7

8
Fetches data for a specific collection instance (database view) with support for filtering, sorting, and pagination.
9

10
```typescript { .api }
11
/**
12
 * Fetches data for a specific collection instance
13
 * @param collectionId - The collection (database) ID
14
 * @param collectionViewId - The specific view ID within the collection
15
 * @param collectionView - The collection view configuration object
16
 * @param options - Options for controlling data fetching
17
 * @returns Promise resolving to collection instance data
18
 */
19
async getCollectionData(
20
  collectionId: string,
21
  collectionViewId: string,
22
  collectionView: any,
23
  options?: GetCollectionDataOptions
24
): Promise<CollectionInstance>;
25

26
interface GetCollectionDataOptions {
27
  /** Type of collection view (e.g., 'table', 'board', 'list') */
28
  type?: CollectionViewType;
29
  /** Maximum number of items to fetch (default: 999) */
30
  limit?: number;
31
  /** Search query to filter results (default: '') */
32
  searchQuery?: string;
33
  /** User timezone for date formatting */
34
  userTimeZone?: string;
35
  /** Whether to load content cover images (default: true) */
36
  loadContentCover?: boolean;
37
  /** HTTP client options for this request */
38
  kyOptions?: KyOptions;
39
}
40

41
interface CollectionInstance {
42
  result: CollectionQueryResult;
43
  recordMap: RecordMap;
44
}
45
```
46

47
**Usage Examples:**
48

49
```typescript
50
import { NotionAPI } from "notion-client";
51

52
const api = new NotionAPI();
53

54
// First get page data to find collection info
55
const page = await api.getPage("database-page-id");
56
const collectionId = "2d8aec23-8281-4a94-9090-caaf823dd21a";
57
const collectionViewId = "ab639a5a-853e-45e1-9ef7-133b486c0acf";
58
const collectionView = page.collection_view[collectionViewId]?.value;
59

60
// Fetch collection data with default options
61
const collectionData = await api.getCollectionData(
62
  collectionId,
63
  collectionViewId,
64
  collectionView
65
);
66

67
// Fetch limited collection data with search
68
const filteredCollection = await api.getCollectionData(
69
  collectionId,
70
  collectionViewId,
71
  collectionView,
72
  {
73
    limit: 50,
74
    searchQuery: "important",
75
    loadContentCover: false
76
  }
77
);
78

79
// Fetch collection data for specific timezone
80
const localizedCollection = await api.getCollectionData(
81
  collectionId,
82
  collectionViewId,
83
  collectionView,
84
  {
85
    userTimeZone: "Europe/London"
86
  }
87
);
88

89
// Access collection results
90
console.log("Collection items:", collectionData.result);
91
console.log("Collection blocks:", Object.keys(collectionData.recordMap.block));
92
```
93

94
### Fetch Relation Pages
95

96
Fetches pages that are referenced through relation properties in collection items. Useful for getting complete data when databases reference other pages.
97

98
```typescript { .api }
99
/**
100
 * Fetches pages referenced in collection relations
101
 * @param recordMap - The extended record map containing collection data
102
 * @param kyOptions - HTTP client options
103
 * @returns Promise resolving to additional block data
104
 */
105
async fetchRelationPages(
106
  recordMap: ExtendedRecordMap,
107
  kyOptions?: KyOptions
108
): Promise<BlockMap>;
109

110
interface BlockMap {
111
  [blockId: string]: BlockRecord;
112
}
113
```
114

115
**Usage Examples:**
116

117
```typescript
118
import { NotionAPI } from "notion-client";
119

120
const api = new NotionAPI();
121

122
// Get page with collections
123
const page = await api.getPage("database-page-id");
124

125
// Fetch additional relation pages
126
const relationBlocks = await api.fetchRelationPages(page);
127

128
// Merge relation pages into main record map
129
page.block = { ...page.block, ...relationBlocks };
130

131
console.log("Total blocks after relations:", Object.keys(page.block).length);
132
```
133

134
### Extract Relation Page IDs
135

136
Utility method to extract page IDs from relation properties in a block. Used internally but can be useful for custom processing.
137

138
```typescript { .api }
139
/**
140
 * Extracts relation page IDs from a block value
141
 * @param blockValue - The block value containing properties
142
 * @param collectionSchema - The collection schema defining property types
143
 * @returns Set of page IDs found in relation properties
144
 */
145
extractRelationPageIdsFromBlock(
146
  blockValue: any,
147
  collectionSchema: any
148
): Set<string>;
149
```
150

151
**Usage Examples:**
152

153
```typescript
154
import { NotionAPI } from "notion-client";
155

156
const api = new NotionAPI();
157

158
// Get collection data
159
const page = await api.getPage("database-page-id");
160
const collectionId = "collection-id";
161
const collection = page.collection[collectionId]?.value;
162
const schema = collection?.schema;
163

164
// Extract relation IDs from a specific block
165
const blockValue = page.block["some-block-id"]?.value;
166
const relationIds = api.extractRelationPageIdsFromBlock(blockValue, schema);
167

168
console.log("Related page IDs:", Array.from(relationIds));
169
```
170

171
## Collection View Types
172

173
Collection views in Notion can have different display types:
174

175
```typescript { .api }
176
type CollectionViewType = 
177
  | "table"      // Table view with rows and columns
178
  | "board"      // Kanban board view
179
  | "list"       // List view
180
  | "gallery"    // Gallery/card view
181
  | "calendar"   // Calendar view
182
  | "timeline";  // Timeline view
183
```
184

185
## Working with Collection Filters
186

187
Collections support complex filtering through the collection view configuration:
188

189
**Usage Examples:**
190

191
```typescript
192
// Example of accessing collection filters from a view
193
const collectionView = page.collection_view[collectionViewId]?.value;
194

195
// Property filters (simple filters)
196
const propertyFilters = collectionView?.format?.property_filters || [];
197
console.log("Property filters:", propertyFilters);
198

199
// Query filters (advanced filters)
200
const queryFilters = collectionView?.query2?.filter?.filters || [];
201
console.log("Query filters:", queryFilters);
202

203
// Sorting configuration
204
const sorts = collectionView?.query2?.sort || [];
205
console.log("Sort configuration:", sorts);
206
```
207

208
## Collection Query Results
209

210
The result structure contains detailed information about the collection data:
211

212
**Usage Examples:**
213

214
```typescript
215
const collectionData = await api.getCollectionData(
216
  collectionId,
217
  collectionViewId,
218
  collectionView
219
);
220

221
// Access different result types
222
const result = collectionData.result as any;
223

224
// For table/list views
225
if (result.type === "results") {
226
  console.log("Block IDs:", result.blockIds);
227
  console.log("Total items:", result.total);
228
}
229

230
// For board views
231
if (result.reducerResults) {
232
  const boardColumns = result.reducerResults;
233
  Object.keys(boardColumns).forEach(columnKey => {
234
    const columnData = boardColumns[columnKey];
235
    console.log(`Column ${columnKey}:`, columnData);
236
  });
237
}
238

239
// Access the actual page/block data
240
const blocks = collectionData.recordMap.block;
241
Object.keys(blocks).forEach(blockId => {
242
  const block = blocks[blockId]?.value;
243
  if (block?.type === "page") {
244
    console.log("Page properties:", block.properties);
245
  }
246
});
247
```