Database Schema

The Database Schema resource provides complete metadata about the knowledge graph structure for a repository. Use this to understand available node types, relationships, and properties before writing Cypher queries.

URI Pattern

db://schema/{repository}

Parameters

{repository}: Repository name (e.g., "my-app")

Response Format

interface SchemaResult {
  node_tables: NodeTableInfo[];
  rel_tables: RelTableInfo[];
}

interface NodeTableInfo {
  id: string;
  name: string;
  comment?: string;
  properties: PropertyInfo[];
}

interface RelTableInfo {
  id: string;
  name: string;
  comment?: string;
  properties: PropertyInfo[];
  src: string;       // Source node type
  dst: string;       // Destination node type
}

interface PropertyInfo {
  name: string;
  type: string;      // e.g., "STRING", "INT64", "BOOLEAN"
}

Example Request

GET db://schema/my-app

Example Response

{
  "node_tables": [
    {
      "id": "0",
      "name": "CodeSymbol",
      "comment": "Code symbols (functions, classes, variables, etc.)",
      "properties": [
        { "name": "id", "type": "SERIAL" },
        { "name": "name", "type": "STRING" },
        { "name": "symbol_type", "type": "STRING" },
        { "name": "file_path", "type": "STRING" },
        { "name": "line_number", "type": "INT64" }
      ]
    },
    {
      "id": "1",
      "name": "File",
      "comment": "Source files in the repository",
      "properties": [
        { "name": "id", "type": "SERIAL" },
        { "name": "path", "type": "STRING" },
        { "name": "extension", "type": "STRING" }
      ]
    },
    {
      "id": "2",
      "name": "Community",
      "comment": "Code communities detected by modularity analysis",
      "properties": [
        { "name": "id", "type": "SERIAL" },
        { "name": "label", "type": "STRING" },
        { "name": "cohesion", "type": "DOUBLE" },
        { "name": "symbol_count", "type": "INT64" }
      ]
    },
    {
      "id": "3",
      "name": "Process",
      "comment": "Execution flows through the codebase",
      "properties": [
        { "name": "id", "type": "SERIAL" },
        { "name": "label", "type": "STRING" },
        { "name": "process_type", "type": "STRING" },
        { "name": "step_count", "type": "INT64" }
      ]
    }
  ],
  "rel_tables": [
    {
      "id": "0",
      "name": "CALLS",
      "comment": "Function/method call relationships",
      "properties": [],
      "src": "CodeSymbol",
      "dst": "CodeSymbol"
    },
    {
      "id": "1",
      "name": "CONTAINED_BY",
      "comment": "Symbol contained in file",
      "properties": [],
      "src": "CodeSymbol",
      "dst": "File"
    },
    {
      "id": "2",
      "name": "MEMBER_OF",
      "comment": "Symbol belongs to community",
      "properties": [],
      "src": "CodeSymbol",
      "dst": "Community"
    }
  ]
}

Node Types

CodeSymbol

Represents code symbols like functions, classes, variables, etc.

Key Properties:

name: Symbol name
symbol_type: Type of symbol (Function, Class, Variable, etc.)
file_path: Location in codebase
line_number: Starting line number

File

Source files in the repository.

Key Properties:

path: File path relative to repository root
extension: File extension

Community

Code communities detected by modularity analysis.

Key Properties:

label: Human-readable community name
cohesion: Cohesion score (0-1, higher is more cohesive)
symbol_count: Number of symbols in community

Process

Execution flows through the codebase.

Key Properties:

label: Process name
process_type: "intra_community" or "cross_community"
step_count: Number of steps in process

Repository

Repository metadata.

Key Properties:

name: Repository name
full_name: Full repository name (owner/repo)

Relationship Types

CALLS

Function/method call relationships between symbols.

(caller:CodeSymbol)-[:CALLS]->(callee:CodeSymbol)

CONTAINED_BY

Symbols contained in files.

(symbol:CodeSymbol)-[:CONTAINED_BY]->(file:File)

MEMBER_OF

Symbols belonging to communities.

(symbol:CodeSymbol)-[:MEMBER_OF]->(community:Community)

STEP_IN_PROCESS

Steps in execution processes.

(symbol:CodeSymbol)-[:STEP_IN_PROCESS]->(process:Process)

Use Cases

1. Before Writing Cypher Queries

Always check the schema first:

GET db://schema/my-app

Then write informed queries:

MATCH (s:CodeSymbol)
WHERE s.symbol_type = "Function"  // Correct property name
RETURN s.name, s.file_path         // Correct properties

2. Understanding Available Data

See what information is tracked:

GET db://schema/my-app

Check node types and their properties to know what you can query.

3. Building Dynamic Queries

Generate queries programmatically based on schema:

const schema = await getResource('db://schema/my-app');

// Find all node types
const nodeTypes = schema.node_tables.map(t => t.name);

// Build query for each type
for (const type of nodeTypes) {
  const query = `MATCH (n:${type}) RETURN count(n)`;
  await executeQuery(query);
}

4. Validation

Validate query syntax before execution:

const schema = await getResource('db://schema/my-app');

function validateProperty(nodeType: string, property: string): boolean {
  const node = schema.node_tables.find(n => n.name === nodeType);
  return node?.properties.some(p => p.name === property) ?? false;
}

// Valid
validateProperty('CodeSymbol', 'name');  // true

// Invalid
validateProperty('CodeSymbol', 'invalid_prop');  // false

Property Types

Type	Description	Example Values
`STRING`	Text data	"functionName", "/path/to/file.ts"
`INT64`	Integer numbers	42, 1337
`DOUBLE`	Floating point numbers	0.85, 3.14159
`BOOLEAN`	True/false values	true, false
`SERIAL`	Auto-incrementing ID	1, 2, 3, ...

Best Practices

1. Cache the Schema

The schema rarely changes, so cache it:

let cachedSchema: SchemaResult | null = null;

async function getSchema(repo: string): Promise<SchemaResult> {
  if (!cachedSchema) {
    cachedSchema = await getResource(`db://schema/${repo}`);
  }
  return cachedSchema;
}

2. Use for Query Validation

Validate queries before execution:

const schema = await getSchema('my-app');

function isValidNodeType(type: string): boolean {
  return schema.node_tables.some(t => t.name === type);
}

3. Document Your Queries

Reference schema properties in query comments:

// From schema: CodeSymbol has properties: name, symbol_type, file_path
MATCH (s:CodeSymbol)
WHERE s.symbol_type = "Function"
RETURN s.name, s.file_path

Troubleshooting

Property Not Found in Query

Check the schema for correct property names:

GET db://schema/my-app

Property names are case-sensitive.

Relationship Direction

Check src and dst fields in rel_tables to understand relationship direction:

{
  "name": "CALLS",
  "src": "CodeSymbol",  // Source
  "dst": "CodeSymbol"   // Destination
}

Query: (src:CodeSymbol)-[:CALLS]->(dst:CodeSymbol)

Cypher Query Tool - Use schema to write queries
Repositories List - Find available repositories
Codebase Map - Explore with schema knowledge

On this page