Implementation:Neuml Txtai Graph Query
| Knowledge Sources | |
|---|---|
| Domains | Graph Querying, OpenCypher, Similarity Search |
| Last Updated | 2026-02-10 01:00 GMT |
Overview
Concrete tool for executing openCypher graph queries with similarity search integration provided by txtai.
Description
The Query class executes openCypher graph queries using the GrandCypher library. It extends standard openCypher functionality with a custom similar() function that integrates vector similarity search results into graph queries. The class handles parsing queries to extract similar() clauses, replacing them with attribute-based filters, and filtering the graph to include only nodes matching similarity search results. Query validation checks that queries conform to openCypher format (requiring MATCH and RETURN clauses). The class supports both raw query strings and pre-parsed query dictionaries, enabling a two-phase workflow where queries are first parsed (extracting similarity parameters), similarity searches are executed externally, and then results are injected back for final query execution.
Usage
Use Query when executing structured graph queries against txtai graph backends. It is called internally by the NetworkX graph's search, isquery, and parse methods. The class is particularly useful when combining graph traversal with vector similarity search through the similar() function, enabling hybrid queries that leverage both graph structure and semantic similarity.
Code Reference
Source Location
- Repository: Neuml_Txtai
- File:
src/python/txtai/graph/query.py
Signature
class Query:
SIMILAR = "__SIMILAR__"
def __init__(self)
def __call__(self, graph, query, limit)
def isquery(self, queries)
def parse(self, query)
def build(self, parse)
def filter(self, graph, attributes, uids)
Import
from txtai.graph.query import Query
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| graph | Graph | Yes (for __call__) | A graph instance with a backend attribute (NetworkX graph) and a filter method.
|
| query | str or dict | Yes | An openCypher query string, or a parsed query dictionary (output of parse() with optional results key added).
|
| limit | int | No | Maximum number of results. Defaults to 3 if not provided. |
| queries | list of str | Yes (for isquery) | List of query strings to validate as openCypher queries. |
| attributes | dict | Yes (for filter) | Dictionary mapping attribute names to lists of (uid, score) tuples from similarity search results. |
| uids | iterable of (uid, score) | Yes (for filter) | Combined set of all matching node ids with scores for graph filtering. |
Outputs
| Name | Type | Description |
|---|---|---|
| __call__() | dict | Columnar result dictionary from GrandCypher execution, mapping return variable names to lists of values. |
| isquery() | bool | True if all input queries are valid openCypher queries (start with MATCH and contain RETURN).
|
| parse() | dict | Parsed query dictionary with keys: query (modified query string with similar() replaced by placeholders), where (WHERE clause content), limit (LIMIT value), nodes (list of node variables from similar() calls), similar (list of similarity search parameters).
|
| build() | tuple | A 3-tuple of (query_string, attributes_dict, uids_items) ready for execution. |
| filter() | Graph | A filtered subgraph containing only nodes matching the similarity search results, with match score attributes added. |
Usage Examples
from txtai.graph.query import Query
# Create a query instance
query = Query()
# Check if a query is a valid openCypher query
is_valid = query.isquery(["MATCH (n) RETURN n"])
# Parse a query with similarity function
parsed = query.parse(
"MATCH (n) WHERE similar(n, 'machine learning') RETURN n LIMIT 10"
)
# parsed = {
# "query": "MATCH (n) WHERE __SIMILAR__0 RETURN n LIMIT 10",
# "where": "similar(n, 'machine learning')",
# "limit": "10",
# "nodes": ["n"],
# "similar": [["machine learning"]]
# }
# After performing external similarity search, inject results
parsed["results"] = [[(0, 0.95), (1, 0.87), (2, 0.72)]]
# Execute the query against a graph
results = query(graph, parsed, limit=10)