Implement the query language

Oct 13, 2025 by pinkandtrash.com 49 views

Overview

The Ummon query system enables users to explore a knowledge graph by selecting entities, filtering them with conditions, and traversing relationships. It features a lightweight, graph-oriented query language and supports natural language input via an LLM (Large Language Model) for translation. The system must integrate with the existing KnowledgeGraph structure, handle errors gracefully, and provide flexible output formatting.

Query Language Syntax

The query language is designed to be simple, readable, and directly mappable to graph operations. It supports two primary query types: select queries and traversal queries, with conditions for filtering.

Select Queries

Syntax: select [entity_type] [where condition]
Description: Retrieves entities of a specified type, optionally filtered by conditions.
Examples:
- select functions — Retrieves all entities of type functions.
- select functions where name like 'auth%' — Retrieves functions with names starting with "auth".

Traversal Queries

Syntax: [entity_type] [relationship] [entity_type] [where condition]
Description: Finds entities of one type connected to entities of another type via a specified relationship, with optional filtering.
Examples:
- functions calling auth — Finds functions that call an entity named "auth".
- classes containing methods where name = 'get' — Finds classes containing methods named "get".

Conditions

Syntax: [attribute] [operator] [value]
Description: Filters entities based on their attributes.
Operators:
- Comparison: =, !=, >, <, >=, <=
- String Matching: like (uses % as a wildcard, e.g., auth% matches strings starting with "auth")
- Logical: and, or, not
Examples:
- name = 'auth' — Matches entities with the exact name "auth".
- file_path like 'src/%' — Matches entities with file paths starting with "src/".
- confidence > 0.8 — Matches entities with a confidence score greater than 0.8.

Supported Entity Types

The query language must support the following entity types from the knowledge graph:

functions
methods
classes
modules
variables
constants
domain_concepts

Supported Relationships

The query language must support the following relationships between entities:

calls — Function/method calls another entity.
contains — Entity contains another (e.g., class contains methods).
imports — Entity imports another (e.g., module imports).
inherits — Class inherits from another class.
implements — Class implements an interface.
references — Entity references another (e.g., variable reference).
uses — Entity uses another entity.
depends_on — Entity depends on another.
represented_by — Entity is represented by another (e.g., domain concept representation).
relates_to — General relationship between entities.

Full Query Examples

select functions where name like 'auth%' and file_path like 'src/%' — Functions with names starting with "auth" in the "src/" directory.
classes containing methods where name = 'get' — Classes with methods named "get".
select domain_concepts where confidence > 0.8 — Domain concepts with confidence above 0.8.

Implementation Details

The query system must be implemented in Rust, leveraging the existing KnowledgeGraph structure. Below are the steps and requirements for parsing, execution, and integration.

Parsing the Query

Tool: Use the pest crate for parsing the query language.

Grammar Definition:

Create a query.pest file with the following rules (simplified):

select_query = { "select" ~ entity_type ~ ("where" ~ condition)? }
traversal_query = { entity_type ~ relationship ~ entity_type ~ ("where" ~ condition)? }
entity_type = { "functions" | "methods" | "classes" | "modules" | "variables" | "constants" | "domain_concepts" }
relationship = { "calls" | "contains" | "imports" | "inherits" | "implements" | "references" | "uses" | "depends_on" | "represented_by" | "relates_to" }
condition = { attribute ~ operator ~ value ~ (logical_op ~ condition)? }
attribute = { "name" | "file_path" | "confidence" | "documentation" }
operator = { "=" | "!=" | ">" | "<" | ">=" | "<=" | "like" }
logical_op = { "and" | "or" | "not" }
value = { quoted_string | number }
quoted_string = { "'" ~ ASCII_ALPHANUMERIC+ ~ "'" }
number = { ASCII_DIGIT+ ("." ~ ASCII_DIGIT+)? }
WHITESPACE = _{ " " }

Ensure the grammar supports whitespace between tokens.

Parse Output:

Convert the parse tree into a structured query object. Define structs like:

enum Query {
    Select(SelectQuery),
    Traversal(TraversalQuery),
}

struct SelectQuery {
    entity_type: EntityType,
    conditions: Option<Vec<Condition>>,
}

struct TraversalQuery {
    source_type: EntityType,
    relationship: RelationshipType,
    target_type: EntityType,
    conditions: Option<Vec<Condition>>,
}

struct Condition {
    attribute: String,
    operator: Operator,
    value: Value,
    logical_op: Option<LogicalOperator>,
}

Map parsed tokens to these structs (e.g., "functions" → EntityType::Function).

Mapping to the Knowledge Graph

Select Queries:
- Use KnowledgeGraph::get_entities_by_type(EntityType) to fetch entities of the specified type.
- Apply conditions by filtering entities based on their attributes.
- Example: select functions where name like 'auth%'
  - Rust: kg.get_entities_by_type(EntityType::Function).filter(|e| e.name().starts_with("auth"))
Traversal Queries:
- Use a method like KnowledgeGraph::get_related_entities_by_type(source_type, relationship, target_type) to traverse relationships.
- Apply conditions to the source or target entities.
- Example: functions calling auth
  - Rust: kg.get_related_entities_by_type(EntityType::Function, RelationshipType::Calls, "auth")
Condition Handling:
- Map attribute names to entity fields (e.g., name → entity.name()).
- Implement operator logic:
  - = → equality check.
  - like → string pattern matching with % wildcard.
  - > → numeric comparison (cast values as needed).
- Combine conditions with and, or, not using recursive evaluation.

Error Handling

Invalid Syntax: If pest parsing fails, return an error like "Syntax error: Expected 'select' keyword at position 0".
Unknown Entity Types: Return "Unknown entity type: 'foo'" for unrecognized types.
Unknown Relationships: Return "Unknown relationship: 'bar'".
Missing Attributes: If an attribute doesn’t exist, return "Attribute 'baz' not found on entity type 'functions'".
No Results: Return an empty result set with a message like "No entities matched your query".

Natural Language Translation

For users who prefer natural language input, integrate an LLM to translate requests into the query language.

Workflow

Command: Support a --natural flag (e.g., ummon query "show me all functions related to authentication" --natural).

LLM Prompt:

Send the input to the LLM with a prompt:

Translate this request into Ummon’s query language: '[user_input]'
Examples:
- "show all functions" → `select functions`
- "functions that call auth" → `functions calling auth`
- "classes with methods named get" → `classes containing methods where name = 'get'`

Use a model like GPT-3.5 or a local equivalent (e.g., LLaMA).

Execution:
- Parse the LLM-generated query using the pest parser.
- Execute it as a standard query.
Feedback:
- Display the translated query to the user (e.g., "Translated to: select functions where name like 'auth%'").

Error Handling

Invalid Translation: If the LLM produces an unparsable query, return "Failed to translate query. Please rephrase or use the query language directly".
Fallback: Optionally, perform a full-text search on the knowledge graph using the original input as keywords.
Confidence: If the LLM provides a confidence score, reject translations below 0.9 and ask the user to rephrase.

Additional Features

Advanced Filtering

Nested Conditions: Support parentheses for grouping (e.g., (name like 'auth%' or name like 'login%') and file_path like 'src/%').
- Update the pest grammar: condition = { "(" ~ condition ~ ")" | attribute ~ operator ~ value }.
Attribute Existence: Support has [attribute] (e.g., has documentation checks if the attribute

Overview

The Ummon query system enables users to explore a knowledge graph by selecting entities, filtering them with conditions, and traversing relationships. It features a lightweight, graph-oriented query language and supports natural language input via an LLM (Large Language Model) for translation. In this Q&A article, we'll address common questions and provide additional insights into the query system.

Q: What is the purpose of the query language?

A: The query language is designed to be simple, readable, and directly mappable to graph operations. It supports two primary query types: select queries and traversal queries, with conditions for filtering.

Q: What are the supported entity types in the query language?

A: The query language must support the following entity types from the knowledge graph:

functions
methods
classes
modules
variables
constants
domain_concepts

Q: What are the supported relationships between entities in the query language?

A: The query language must support the following relationships between entities:

calls — Function/method calls another entity.
contains — Entity contains another (e.g., class contains methods).
imports — Entity imports another (e.g., module imports).
inherits — Class inherits from another class.
implements — Class implements an interface.
references — Entity references another (e.g., variable reference).
uses — Entity uses another entity.
depends_on — Entity depends on another.
represented_by — Entity is represented by another (e.g., domain concept representation).
relates_to — General relationship between entities.

Q: How does the query system handle errors?

A: The query system handles errors by:

Invalid Syntax: If pest parsing fails, return an error like "Syntax error: Expected 'select' keyword at position 0".
Unknown Entity Types: Return "Unknown entity type: 'foo'" for unrecognized types.
Unknown Relationships: Return "Unknown relationship: 'bar'".
Missing Attributes: If an attribute doesn’t exist, return "Attribute 'baz' not found on entity type 'functions'".
No Results: Return an empty result set with a message like "No entities matched your query".

Q: How does the query system support natural language translation?

A: The query system supports natural language translation by:

LLM Prompt: Send the input to the LLM with a prompt:

Translate this request into Ummon’s query language: '[user_input]'
Examples:
- "show all functions" → `select functions`
- "functions that call auth" → `functions calling auth`
- "classes with methods named get" → `classes containing methods where name = 'get'`

Execution: Parse the LLM-generated query using the pest parser and execute it as a standard query.
Feedback: Display the translated query to the user (e.g., "Translated to: select functions where name like 'auth%'").

Q: What are the additional features of the query system?

A: The query system includes the following additional features:

Advanced Filtering: Support nested conditions and attribute existence.
Result Formatting: Provide flexible output formatting options (e.g., JSON, text, tree, CSV).
Performance Optimizations: Implement indexing, caching, and pagination to improve query performance.

Q: How can I get started with the query system?

A: To get started with the query system, follow these steps:

Install the dependencies: Install the required dependencies, including the pest crate and the KnowledgeGraph structure.
Implement the query language: Implement the query language using the pest parser and the KnowledgeGraph structure.
Integrate the natural language translation: Integrate the natural language translation using an LLM (e.g., GPT-3.5 or LLaMA).
Test and refine: Test the query system and refine it as needed to ensure accurate and efficient results.

Q: What are the benefits of using the query system?

A: The query system provides several benefits, including:

Improved query performance: The query system uses indexing, caching, and pagination to improve query performance.
Flexible output formatting: The query system provides flexible output formatting options (e.g., JSON, text, tree, CSV).
Natural language translation: The query system supports natural language translation using an LLM.
Advanced filtering: The query system supports advanced filtering options, including nested conditions and attribute existence.

By following these steps and understanding the benefits of the query system, you can effectively use the query system to explore and analyze your knowledge graph.