notion_query_database
Query and retrieve data from a Notion database with custom filters, sorting, and pagination. Choose response formats like JSON or Markdown for optimal readability or further processing.
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 | |
| 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 |
| page_size | No | Number of results per page (max 100) | |
| sorts | No | Sort conditions | |
| start_cursor | No | Pagination cursor for next page of results |
Implementation Reference
- src/client/index.ts:173-200 (handler)Core handler implementing the Notion API POST /databases/{database_id}/query call with filter, sorts, pagination.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)Tool schema defining name, description, and input schema for notion_query_database.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:163-177 (registration)Dispatches CallToolRequest for notion_query_database to the NotionClientWrapper handler, with argument validation.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/server/index.ts:303-322 (registration)Registers the tool schema in the allTools array for ListToolsRequest response.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, ];
- src/types/args.ts:80-91 (helper)TypeScript interface defining the arguments for the notion_query_database tool.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"; }