AI Completion

AI completion functions use a large language model to generate or execute GQL queries from natural language. Use ai.setCompletionProvider() to set the active completion AI provider.

Example Graph

GQL
INSERT (p1:Paper {_id:'P1', title:'Efficient Graph Search', score:6, author:'Alex'}),
       (p2:Paper {_id:'P2', title:'Optimizing Queries', score:9, author:'Alex'}),
       (p3:Paper {_id:'P3', title:'Path Patterns', score:7, author:'Zack'}),
       (p1)-[:Cites {weight:2}]->(p2),
       (p2)-[:Cites {weight:1}]->(p3)

Streaming Procedures

ai.gql() and ai.read() are streaming procedures, not scalar functions. They produce multiple rows of output (one per pipeline stage) as the NL-to-GQL pipeline executes. Because scalar functions used with RETURN must produce a single value, these are invoked with CALL ... YIELD instead.

ai.gql()

Converts a natural language question into a GQL query using the configured completion provider via a streaming procedure. The pipeline automatically includes the current graph's schema (labels, properties, edge patterns) as context for the LLM. Streams one row per pipeline stage.

GQL
CALL ai.gql("Find all papers written by Alex")
YIELD stage, detail, elapsed_ms, tokens_input, tokens_output, tokens_cached, data

Result columns:

Result:

JSON
[
  {"stage": "start", "detail": "Find all papers written by Alex", "elapsed_ms": 0, "tokens_input": 0, "tokens_output": 0, "tokens_cached": 0, "data": {"require_read": false}},
  {"stage": "routing", "detail": "MATCH intent — using LLM path", "elapsed_ms": 0, "tokens_input": 0, "tokens_output": 0, "tokens_cached": 0, "data": {}},
  {"stage": "grounding", "detail": "2 labels, 1 patterns selected", "elapsed_ms": 1888, "tokens_input": 0, "tokens_output": 0, "tokens_cached": 0, "data": {"node_labels": ["Paper"], "edge_labels": ["Cites"], "pattern_count": 1}},
  {"stage": "generation", "detail": "requested 1 tool call(s)", "elapsed_ms": 3308, "tokens_input": 2842, "tokens_output": 29, "tokens_cached": 1920, "data": {"step": 0, "tool_calls": 1}},
  {"stage": "tool", "detail": "validate_gql → {\"valid\":true}", "elapsed_ms": 3308, "tokens_input": 2842, "tokens_output": 29, "tokens_cached": 1920, "data": {"name": "validate_gql", "args": "{\"query\":\"MATCH (p:Paper) WHERE p.author = 'Alex' RETURN p\"}", "result": "{\"class\":\"read\",\"valid\":true}"}},
  {"stage": "generation", "detail": "MATCH (p:Paper) WHERE p.author = 'Alex' RETURN p", "elapsed_ms": 4130, "tokens_input": 5723, "tokens_output": 45, "tokens_cached": 4736, "data": {"step": 1, "has_text": true}},
  {"stage": "generation", "detail": "final candidate: MATCH (p:Paper) WHERE p.author = 'Alex' RETURN p", "elapsed_ms": 4130, "tokens_input": 5723, "tokens_output": 45, "tokens_cached": 4736, "data": {"candidate": "MATCH (p:Paper) WHERE p.author = 'Alex' RETURN p", "steps": 2, "termination": "final"}},
  {"stage": "validation", "detail": "passed", "elapsed_ms": 4130, "tokens_input": 5723, "tokens_output": 45, "tokens_cached": 4736, "data": {"passed": true, "class": "read"}},
  {"stage": "final", "detail": "MATCH (p:Paper) WHERE p.author = 'Alex' RETURN p", "elapsed_ms": 4130, "tokens_input": 5723, "tokens_output": 45, "tokens_cached": 4736, "data": {"gql": "MATCH (p:Paper) WHERE p.author = 'Alex' RETURN p"}}
]

To output the generated query directly:

GQL
CALL ai.gql("Find all papers written by Alex")
YIELD stage, data
FILTER stage = "final"
RETURN data.gql

Result:

ai.read()

Converts a natural language question into a read-only GQL query, executes it, and streams pipeline progress. Write/DDL queries are rejected. Returns the same columns as CALL ai.gql(), with an additional execution stage that runs the generated query.

GQL
CALL ai.read("How many papers did Alex write in total?")
YIELD stage, detail, elapsed_ms, tokens_input, tokens_output, tokens_cached, data

Result columns same with ai.gql().

Scalar Functions

These functions return a single value and are used with RETURN.

ai.explain()

Runs the NL-to-GQL pipeline and returns the generated query alongside a reasoning trace (schema used, tool calls, refinements). Does not execute the query.

The returned map contains:

GQL
RETURN ai.explain("Find ALL papers written by Alex")

Result:

JSON
{
  "gql": "MATCH (p:Paper) WHERE p.author = 'Alex' RETURN p",
  "trace": {
    "nl": "Find ALL papers written by Alex",
    "total_duration_ms": 4753,
    "termination": "success",
    "schema": {
      "label_count": 2,
      "pattern_count": 1,
      "node_labels": ["Paper"],
      "edge_labels": ["Cites"]
    },
    "generation": {
      "used_tool_use": true,
      "termination": "final",
      "steps": [
        {"assistant_text": "", "duration_ms": 1517, "tool_calls": [{"name": "validate_gql", "args": "{\"query\":\"MATCH (p:Paper) WHERE p.author = 'Alex' RETURN p\"}", "result": "{\"class\":\"read\",\"valid\":true}"}]},
        {"assistant_text": "MATCH (p:Paper) WHERE p.author = 'Alex' RETURN p", "duration_ms": 1837, "tool_calls": []}
      ]
    },
    "validation": {"passed": true, "class": "read"},
    "token_usage": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "input_tokens": 6325,
      "output_tokens": 45,
      "total_tokens": 6370,
      "calls": 2
    }
  }
}

ai.trace()

Returns the most recent NL-to-GQL pipeline trace recorded by ai.gql(), ai.read(), or ai.explain(). Returns NULL if no pipeline call has run in the current session. Useful for debugging when a generated query is incorrect — you can inspect which labels were selected, what tool calls were made, and where the pipeline went wrong.

GQL
RETURN ai.trace()

JSON
{
  "nl": "Find ALL papers written by Alex",
  "total_duration_ms": 4753,
  "termination": "success",
  "schema": {
    "label_count": 2,
    "pattern_count": 1,
    "node_labels": ["Paper"],
    "edge_labels": ["Cites"]
  },
  "generation": {
    "used_tool_use": true,
    "termination": "final",
    "steps": [
      {"assistant_text": "", "duration_ms": 1517, "tool_calls": [{"name": "validate_gql", "args": "{\"query\":\"MATCH (p:Paper) WHERE p.author = 'Alex' RETURN p\"}", "result": "{\"class\":\"read\",\"valid\":true}"}]},
      {"assistant_text": "MATCH (p:Paper) WHERE p.author = 'Alex' RETURN p", "duration_ms": 1837, "tool_calls": []}
    ]
  },
  "validation": {"passed": true, "class": "read"},
  "token_usage": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "input_tokens": 6325,
    "output_tokens": 45,
    "total_tokens": 6370,
    "calls": 2
  }
}

Pipeline Configuration

ai.aiConfig()

Returns the current NL-to-GQL pipeline configuration.

GQL
RETURN ai.aiConfig()

Result:

JSON
{
  "max_steps": 4,
  "max_refinements": 2,
  "schema_top_k": 8,
  "patterns_top_k": 8,
  "examples_top_k": 3,
  "query_memory_enabled": false,
  "query_memory_size": 256,
  "pipeline": "agentic"
}

ai.setAIConfig()

Sets a configuration parameter for the NL-to-GQL pipeline.

Available configuration keys:

GQL
RETURN ai.setAIConfig("max_refinements", 3)