0
# Search Operations
1

2
Full-text search capabilities across Notion workspaces with advanced filtering and result ranking.
3

4
## Capabilities
5

6
### Search
7

8
Performs full-text search within a Notion workspace or specific page hierarchy with support for filtering and result limiting.
9

10
```typescript { .api }
11
/**
12
 * Performs search within Notion workspace
13
 * @param params - Search parameters including query and filters
14
 * @param kyOptions - HTTP client options
15
 * @returns Promise resolving to search results
16
 */
17
async search(params: SearchParams, kyOptions?: KyOptions): Promise<SearchResults>;
18

19
interface SearchParams {
20
  /** The ancestor page ID to search within */
21
  ancestorId: string;
22
  /** The search query string */
23
  query: string;
24
  /** Maximum number of results to return (default: 20) */
25
  limit?: number;
26
  /** Additional search filters */
27
  filters?: SearchFilters;
28
}
29

30
interface SearchFilters {
31
  /** Whether to include only deleted items (default: false) */
32
  isDeletedOnly?: boolean;
33
  /** Whether to include only navigable items (default: false) */
34
  isNavigableOnly?: boolean;
35
  /** Whether to exclude template pages (default: true) */
36
  excludeTemplates?: boolean;
37
  /** Whether to require edit permissions (default: false) */
38
  requireEditPermissions?: boolean;
39
  /** Whether to include public pages without explicit access (default: true) */
40
  includePublicPagesWithoutExplicitAccess?: boolean;
41
  /** Filter by ancestor page IDs */
42
  ancestors?: string[];
43
  /** Filter by creator user IDs */
44
  createdBy?: string[];
45
  /** Filter by editor user IDs */
46
  editedBy?: string[];
47
  /** Filter by last edited time range */
48
  lastEditedTime?: DateRange;
49
  /** Filter by creation time range */
50
  createdTime?: DateRange;
51
}
52

53
interface SearchResults {
54
  recordMap: RecordMap;
55
  results: SearchResult[];
56
  total: number;
57
}
58

59
interface SearchResult {
60
  id: string;
61
  isNavigable: boolean;
62
  score: number;
63
  highlight: {
64
    pathText: string;
65
    text: string;
66
  };
67
}
68
```
69

70
**Usage Examples:**
71

72
```typescript
73
import { NotionAPI } from "notion-client";
74

75
const api = new NotionAPI();
76

77
// Basic search within a workspace
78
const results = await api.search({
79
  ancestorId: "workspace-root-page-id",
80
  query: "project management",
81
  limit: 20
82
});
83

84
// Search with filters
85
const filteredResults = await api.search({
86
  ancestorId: "workspace-root-page-id",
87
  query: "meeting notes",
88
  limit: 10,
89
  filters: {
90
    excludeTemplates: true,
91
    isNavigableOnly: true,
92
    createdBy: ["user-id-1", "user-id-2"]
93
  }
94
});
95

96
// Search within specific time range
97
const recentResults = await api.search({
98
  ancestorId: "workspace-root-page-id", 
99
  query: "quarterly review",
100
  filters: {
101
    lastEditedTime: {
102
      start_date: "2024-01-01",
103
      end_date: "2024-03-31"
104
    }
105
  }
106
});
107

108
// Process search results
109
results.results.forEach(result => {
110
  console.log(`Found: ${result.id} (Score: ${result.score})`);
111
  console.log(`Navigable: ${result.isNavigable}`);
112
  if (result.highlight) {
113
    console.log(`Highlight: ${result.highlight.text}`);
114
    console.log(`Path: ${result.highlight.pathText}`);
115
  }
116
});
117

118
console.log(`Total results: ${results.total}`);
119
```
120

121
## Search Result Processing
122

123
Search results include relevance scoring and text highlighting:
124

125
**Usage Examples:**
126

127
```typescript
128
const results = await api.search({
129
  ancestorId: "workspace-id",
130
  query: "database design"
131
});
132

133
// Sort results by score
134
const sortedResults = results.results.sort((a, b) => b.score - a.score);
135

136
// Filter high-confidence results
137
const highConfidenceResults = results.results.filter(r => r.score > 0.8);
138

139
// Extract page IDs for further processing
140
const pageIds = results.results.map(r => r.id);
141

142
// Get full page data for top results
143
const topResult = results.results[0];
144
if (topResult) {
145
  const fullPage = await api.getPage(topResult.id);
146
  console.log("Full page data:", fullPage);
147
}
148
```
149

150
## Advanced Search Patterns
151

152
### Search within specific page hierarchies:
153

154
```typescript
155
// Search only within a specific project folder
156
const projectResults = await api.search({
157
  ancestorId: "project-folder-page-id",
158
  query: "task status",
159
  filters: {
160
    ancestors: ["project-folder-page-id"]
161
  }
162
});
163
```
164

165
### Search for recently modified content:
166

167
```typescript
168
const oneWeekAgo = new Date();
169
oneWeekAgo.setDate(oneWeekAgo.getDate() - 7);
170

171
const recentChanges = await api.search({
172
  ancestorId: "workspace-id",
173
  query: "", // Empty query to get all recent changes
174
  filters: {
175
    lastEditedTime: {
176
      start_date: oneWeekAgo.toISOString().split('T')[0],
177
      end_date: new Date().toISOString().split('T')[0]
178
    }
179
  }
180
});
181
```
182

183
### Search for content by specific authors:
184

185
```typescript  
186
const authorResults = await api.search({
187
  ancestorId: "workspace-id",
188
  query: "documentation",
189
  filters: {
190
    createdBy: ["author-user-id"],
191
    excludeTemplates: true
192
  }
193
});
194
```
195

196
## Search Types and Sorting
197

198
The search API uses different search types and sorting options:
199

200
```typescript { .api }
201
interface SearchConfiguration {
202
  /** Search type - typically 'BlocksInAncestor' for workspace search */
203
  type: string;
204
  /** Search source identifier */
205
  source: string;
206
  /** Sort configuration */
207
  sort: {
208
    /** Sort field - typically 'relevance' */
209
    field: string;
210
  };
211
}
212
```
213

214
## Error Handling
215

216
Search operations can fail for various reasons:
217

218
**Usage Examples:**
219

220
```typescript
221
try {
222
  const results = await api.search({
223
    ancestorId: "invalid-page-id",
224
    query: "test"
225
  });
226
} catch (error) {
227
  if (error.message.includes("not found")) {
228
    console.error("Page not found or not accessible");
229
  } else if (error.message.includes("permission")) {
230
    console.error("Insufficient permissions to search");
231
  } else {
232
    console.error("Search failed:", error.message);
233
  }
234
}
235
```
236

237
## Types
238

239
```typescript { .api }
240
interface DateRange {
241
  start_date?: string;
242
  end_date?: string;
243
}
244
```