notion_query_database
Query Notion databases to retrieve, filter, and sort data for analysis or integration with other tools.
Instructions
Query a database in Notion
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | The ID of the database to query.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| filter | No | Filter conditions | |
| sorts | No | Sort conditions | |
| start_cursor | No | Pagination cursor for next page of results | |
| page_size | No | Number of results per page (max 100) | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Implementation Reference
- src/client/index.ts:173-200 (handler)Core handler implementation in NotionClientWrapper that performs the POST request to Notion API's `/databases/{database_id}/query` endpoint with optional filter, sorts, and pagination parameters.async queryDatabase( database_id: string, filter?: Record<string, any>, sorts?: Array<{ property?: string; timestamp?: string; direction: "ascending" | "descending"; }>, start_cursor?: string, page_size?: number ): Promise<ListResponse> { const body: Record<string, any> = {}; if (filter) body.filter = filter; if (sorts) body.sorts = sorts; if (start_cursor) body.start_cursor = start_cursor; if (page_size) body.page_size = page_size; const response = await fetch( `${this.baseUrl}/databases/${database_id}/query`, { method: "POST", headers: this.headers, body: JSON.stringify(body), } ); return response.json(); }
- src/types/schemas.ts:244-286 (schema)Input schema definition for the 'notion_query_database' tool, specifying parameters like database_id (required), filter, sorts, pagination, and format.export const queryDatabaseTool: Tool = { name: "notion_query_database", description: "Query a database in Notion", inputSchema: { type: "object", properties: { database_id: { type: "string", description: "The ID of the database to query." + commonIdDescription, }, filter: { type: "object", description: "Filter conditions", }, sorts: { type: "array", description: "Sort conditions", items: { type: "object", properties: { property: { type: "string" }, timestamp: { type: "string" }, direction: { type: "string", enum: ["ascending", "descending"], }, }, required: ["direction"], }, }, start_cursor: { type: "string", description: "Pagination cursor for next page of results", }, page_size: { type: "number", description: "Number of results per page (max 100)", }, format: formatParameter, }, required: ["database_id"], }, };
- src/server/index.ts:302-326 (registration)Registration of the tool by including queryDatabaseTool in the list of available tools served in response to ListToolsRequest.server.setRequestHandler(ListToolsRequestSchema, async () => { const allTools = [ schemas.appendBlockChildrenTool, schemas.retrieveBlockTool, schemas.retrieveBlockChildrenTool, schemas.deleteBlockTool, schemas.updateBlockTool, schemas.retrievePageTool, schemas.updatePagePropertiesTool, schemas.listAllUsersTool, schemas.retrieveUserTool, schemas.retrieveBotUserTool, schemas.createDatabaseTool, schemas.queryDatabaseTool, schemas.retrieveDatabaseTool, schemas.updateDatabaseTool, schemas.createDatabaseItemTool, schemas.createCommentTool, schemas.retrieveCommentsTool, schemas.searchTool, ]; return { tools: filterTools(allTools, enabledToolsSet), }; });
- src/server/index.ts:163-177 (handler)Server-side dispatch handler case for 'notion_query_database' that validates arguments and delegates to NotionClientWrapper.queryDatabase.case "notion_query_database": { const args = request.params .arguments as unknown as args.QueryDatabaseArgs; if (!args.database_id) { throw new Error("Missing required argument: database_id"); } response = await notionClient.queryDatabase( args.database_id, args.filter, args.sorts, args.start_cursor, args.page_size ); break; }
- src/types/args.ts:80-91 (schema)TypeScript interface definition for QueryDatabaseArgs used for type casting and validation in the server handler.export interface QueryDatabaseArgs { database_id: string; filter?: Record<string, any>; sorts?: Array<{ property?: string; timestamp?: string; direction: "ascending" | "descending"; }>; start_cursor?: string; page_size?: number; format?: "json" | "markdown"; }