Query Notion Database

Search and filter the Beam Nexus Skills database to discover skills created by teammates.

Purpose

Browse the company skills library in Notion. Filter by team, integration, or skill name to find relevant skills. Returns skill metadata for display or import.

Use cases:

• Discover skills created by teammates
• Find skills for specific integrations (Beam AI, Linear, etc.)
• Check if a skill already exists before creating
• Browse skills by team (General, Solutions, Engineering, Sales)

Time Estimate: 1-2 minutes

---

Workflow

Step 1: Validate Configuration

ALWAYS run configuration check first:

python ../../notion-master/scripts/check_notion_config.py

If configuration missing:

• Option A: Run setup wizard: python ../../notion-master/scripts/setup_notion.py
• Option B: See ../../notion-master/references/setup-guide.md

Expected output if configured:

✅ ALL CHECKS PASSED
You're ready to use Notion skills

---

Step 2: Query Database

Use the query_db.py script with filters:

Basic query (all skills):

python ../../notion-master/scripts/query_db.py

Filter by team:

python ../../notion-master/scripts/query_db.py --team General
python ../../notion-master/scripts/query_db.py --team Solutions

Filter by integration:

python ../../notion-master/scripts/query_db.py --integration "Beam AI"
python ../../notion-master/scripts/query_db.py --integration "Linear"

Search by name:

python ../../notion-master/scripts/query_db.py --name notion
python ../../notion-master/scripts/query_db.py --name agent

Combined filters:

python ../../notion-master/scripts/query_db.py --team Solutions --integration "Beam AI"

Sort and limit:

python ../../notion-master/scripts/query_db.py --sort name --limit 10

---

Step 3: Display Results

Human-readable output:

The script automatically displays results in readable format:

[RESULTS] Found 5 skills

1. beam-list-agents
   Team: Solutions
   Description: List all agents in Beam AI workspace...
   Integrations: Beam AI
   Created: 2025-12-01
   URL: https://notion.so/...

2. query-notion-db
   Team: General
   Description: Query Notion databases with filters...
   Integrations: Notion
   Created: 2025-11-15
   URL: https://notion.so/...

JSON output (for programmatic use):

python ../../notion-master/scripts/query_db.py --json

Returns JSON array of skill objects with full metadata.

---

Step 4: User Selection (Optional)

After displaying results, ask user which skill to import (if applicable):

Which skill would you like to import? (1-5, or 'none')

If user selects a skill:

1. Get the page ID from results
2. Trigger import-skill-to-nexus skill with page ID

---

Available Filters

Filter	Flag	Example	Description
Team	--team	--team General	General, Solutions, Engineering, Sales
Integration	--integration	--integration "Beam AI"	Tool the skill integrates with
Name	--name	--name notion	Partial match on skill name
Owner	--owner	--owner user-id	Filter by creator (user ID)
Sort	--sort	--sort name	created (default) or name
Limit	--limit	--limit 10	Max results to return

---

Error Handling

Common errors:

Error	Cause	Solution
401 Unauthorized	Invalid API key	Check NOTION_API_KEY in .env
404 Not Found	Database ID incorrect	Verify NOTION_SKILLS_DB_ID in .env
No results found	Filter too restrictive	Try broader filters
Network timeout	Connection issue	Check internet, retry

For detailed troubleshooting:

• See ../../notion-master/references/error-handling.md

---

Integration with Other Skills

Typical workflow:

1. query-notion-db (find skills)
2. import-skill-to-nexus (download selected skill)

Example:

User: "Find Beam AI skills in Notion"

AI: [Runs query_db.py --integration "Beam AI"]
    [Displays 3 results]

    Which would you like to import?

User: "Number 2"

AI: [Triggers import-skill-to-nexus with page ID]
    [Downloads and installs skill]

---

Advanced Usage

Custom database query:

For queries beyond the script's filters, use the Notion API directly or see:

• ../../notion-master/references/api-reference.md - API patterns and examples

Database schema reference:

• ../../notion-master/references/database-schema.md - Field definitions and filter examples

---

Notes

• Pagination: Script automatically handles pagination (fetches all results)
• Rate limits: Notion allows 3 requests/second (script handles this)
• Database ID: Default is Beam Nexus Skills (2bc2cadf-bbbc-80be-af8a-d45dfc8dfa2e)
• Team filter: Matches exact team name (case-sensitive)
• Name filter: Partial match, case-insensitive

---

Version: 2.0
Created: 2025-11-04
Updated: 2025-12-10
Status: Production Ready