Cypher Query Tool

The Cypher Query tool (noodlbox_raw_cypher_query) allows you to execute powerful graph queries using the Cypher language. This tool provides direct access to your code knowledge graph while maintaining strict security protections.

Parameters

Parameter	Type	Required	Description
`repository`	string	Yes	Repository name (e.g., "my-project" or "owner/repo")
`cypher`	string	Yes	Cypher query to execute (read-only operations only)
`max_results`	number	No	Maximum results to return (default: 10000, 0 for unlimited)

Basic Usage

Find Functions by Name

MATCH (s:CODE_SYMBOL)
WHERE s.symbol_type = "Function"
  AND s.name CONTAINS "user"
RETURN s.name, s.file_path
LIMIT 10

Explore Function Calls

MATCH (caller:CODE_SYMBOL)-[r:CALLS]->(callee:CODE_SYMBOL)
WHERE caller.name = "handleLogin"
RETURN callee.name, callee.file_path, type(r)
LIMIT 20

Find Files in a Directory

MATCH (f:File)
WHERE f.path STARTS WITH "src/components"
RETURN f.path, f.extension
ORDER BY f.path

Advanced Queries

Multi-Hop Relationships

MATCH path = (start:CODE_SYMBOL)-[:CALLS*1..3]->(end:CODE_SYMBOL)
WHERE start.name = "main"
  AND end.symbol_type = "Function"
RETURN path
LIMIT 5

Community Analysis

MATCH (c:Community)
WHERE c.cohesion > 0.8
RETURN c.label, c.cohesion, c.symbol_count
ORDER BY c.cohesion DESC
LIMIT 10

Process Discovery

MATCH (p:Process)
WHERE p.process_type = "cross_community"
RETURN p.label, p.step_count
ORDER BY p.step_count DESC
LIMIT 15

Security Features

Write Protection

All write operations (CREATE, DELETE, SET, MERGE, DROP, ALTER) are automatically blocked. This tool can only read data from the knowledge graph.

The Cypher Query tool implements multiple security layers:

1. Comment Stripping

Comments are removed before query analysis to prevent bypass attempts:

// This won't work:
/* CREATE */ MATCH (n) RETURN n

2. Write Operation Detection

The following operations are blocked:

CREATE
DELETE
SET
MERGE
DROP
ALTER
REMOVE

3. Query Length Limits

Maximum query size is 10KB to prevent resource exhaustion.

4. Prepared Statements

All queries use Kuzu's prepared statements for additional protection.

Response Format

interface CypherQueryResult {
  results: any[];           // Query results as JSON
  row_count: number;        // Number of rows returned
  warning?: string;         // Present if results truncated
}

Example Response

{
  "results": [
    {
      "s.name": "getUserById",
      "s.file_path": "src/users/repository.ts"
    },
    {
      "s.name": "updateUser",
      "s.file_path": "src/users/service.ts"
    }
  ],
  "row_count": 2
}

Best Practices

1. Use LIMIT Clauses

Always limit results to avoid overwhelming responses:

MATCH (n:CODE_SYMBOL)
RETURN n
LIMIT 100  // Good practice

2. Filter Early

Apply WHERE clauses early in the query:

// Good: Filter first
MATCH (s:CODE_SYMBOL)
WHERE s.symbol_type = "Function"
MATCH (s)-[:CALLS]->(t)
RETURN s, t

// Less efficient: Filter last
MATCH (s:CODE_SYMBOL)-[:CALLS]->(t)
WHERE s.symbol_type = "Function"
RETURN s, t

3. Use Specific Labels

Specify node labels to improve query performance:

// Good
MATCH (s:CODE_SYMBOL)
WHERE s.name = "main"

// Less efficient
MATCH (s)
WHERE s.name = "main"

4. Test with Small Limits

Start with small limits and increase as needed:

MATCH (n)
RETURN n
LIMIT 5  // Start small

Common Patterns

Pattern 1: Find Dependencies

MATCH (source:CODE_SYMBOL {name: "MyComponent"})-[:CALLS*1..2]->(dep:CODE_SYMBOL)
WHERE dep.symbol_type IN ["Function", "Class"]
RETURN DISTINCT dep.name, dep.file_path
LIMIT 50

Pattern 2: Explore File Structure

MATCH (f:File)
WHERE f.path CONTAINS "authentication"
MATCH (f)-[:CONTAINS]->(s:CODE_SYMBOL)
RETURN f.path, collect(s.name) as symbols

Pattern 3: Community Connections

MATCH (c1:Community)-[r]->(c2:Community)
WHERE c1.label = "Authentication"
RETURN c2.label, type(r), count(*) as connection_count
ORDER BY connection_count DESC

Troubleshooting

Query Returns No Results

Check node labels are correct (CODE_SYMBOL, File, Community, Process, Repository)
Verify property names match schema (use Database Schema resource)
Test with simpler queries first

Query is Slow

Add LIMIT clauses
Use more specific WHERE filters
Avoid unbounded variable-length paths (*)

Write Operation Blocked

Ensure you're only using read operations (MATCH, RETURN, WHERE, WITH, ORDER BY, LIMIT, SKIP)
Check for accidentally included write keywords
Remove any CREATE, DELETE, SET, MERGE operations

Database Schema Resource - Understand available node types and properties
Debugging - Debug with Cypher queries
Refactoring - Find dependencies before refactoring

On this page