AI Completion

AI completion functions use a large language model to generate or execute GQL queries from natural language.

NOTE

Use ai.set_completion_provider() to set the active completion AI provider.

Example Graph

GQL
INSERT (alice:Person {_id: 'U1', name: 'Alice', age: 28, city: 'New York'}),
       (bob:Person {_id: 'U2', name: 'Bob', age: 32, city: 'New York'}),
       (carol:Person {_id: 'U3', name: 'Carol', age: 25, city: 'Boston'}),
       (david:Person {_id: 'U4', name: 'David', age: 30, city: 'Boston'}),
       (eve:Person {_id: 'U5', name: 'Eve', age: 27, city: 'Seattle'}),
       (alice)-[:FRIEND]->(bob), (alice)-[:FRIEND]->(carol),
       (bob)-[:FRIEND]->(david), (carol)-[:FRIEND]->(david),
       (david)-[:FRIEND]->(eve)

NL-to-GQL: ai.gql()

ai.gql() converts a natural language question into a GQL query using the configured completion provider. It is registered in two forms:

Function Form

The function form supports four positional arguments:

Simplest: NL in, GQL string out.

GQL
RETURN ai.gql("Names of Alice's friends")

Result:

Generate and execute:

GQL
RETURN ai.gql("Names of Alice's friends", "", 0, true)

Result:

JSON
{
  "gql": "MATCH (a:Person)-[:FRIEND]->(b:Person) WHERE a.name = 'Alice' RETURN b.name",
  "rows": [
    { "b.name": "Bob" },
    { "b.name": "Carol" }
  ],
  "count": 2
}

Procedure Form

Parameters are passed as a single map literal. The procedure form is a superset of the function form, it accepts the same nl / instruction / timeout_ms / execute arguments, plus three procedure-only parameters:

GQL
CALL ai.gql({nl: "Names of Alice's friends"})
YIELD stage, detail, elapsed_ms, tokens_input, tokens_output, tokens_cached, data

Result (one row per pipeline stage):

With extra guidance and a 15-second cap, filtering down to the final GQL string:

GQL
CALL ai.gql({
  nl: "Friends of friends of David",
  instruction: "FRIEND edges are bidirectional even though stored directed; consider both directions",
  timeout_ms: 15000
})
YIELD stage, data
FILTER stage = "final"
RETURN data.gql

Result:

ai.gql() produces multiple rows of output as the NL-to-GQL pipeline executes. The pipeline automatically includes the current graph's schema (labels, properties, edge patterns) as context for the LLM.

Pipeline Stages

The happy path is start → routing → grounding → generation → (tool ↔ generation)* → validation → final. On failure at any step the stream emits an error row and ends; if a refinement budget remains, the pipeline first tries refinement → generation before giving up.

Each returned row carries the stage plus six telemetry columns:

• detail (one-line human summary)
• elapsed_ms (wall time since CALL began)
• tokens_input / tokens_output / tokens_cached (cumulative LLM token counters)
• data (stage-specific payload — e.g. the generated GQL on final, tool args + result on tool).

You can omit any column you don't care about. Common patterns:

GQL
-- Just the final query
CALL ai.gql({nl: "Names of Alice's friends"}) YIELD stage, data
FILTER stage = "final"
RETURN data.gql

-- Stage trace only, no payload
CALL ai.gql({nl: "Names of Alice's friends"}) 
YIELD stage, detail, elapsed_ms

-- Just token accounting
CALL ai.gql({nl: "..."}) YIELD stage, tokens_input, tokens_output, tokens_cached
FILTER stage = "final"
RETURN tokens_input, tokens_output, tokens_cached

Agent Tools

During the generation stage the LLM can call any of the following tools. Each call surfaces as a tool row in the stream with data.name, data.args, and data.result:

Common Intents

The system prompt steers algorithm-shaped questions to CALL algo.<name>(...) YIELD ... rather than a naive MATCH ... RETURN. Common mappings:

Example — asking for "the most influential people" emits:

GQL
CALL algo.pagerank() YIELD nodeId, score
ORDER BY score DESC LIMIT 10

Pipeline Inspection

These functions let you re-run, replay, or audit the NL-to-GQL pipeline.

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 of Alice's friends")

Result:

JSON
{
  "gql": "MATCH (a:Person {name: 'Alice'})-[:FRIEND]->(f:Person) RETURN f",
  "trace": {
    "total_duration_ms": 4753,
    "schema": {
      "label_count": 1,
      "pattern_count": 1,
      "node_labels": ["Person"],
      "edge_labels": ["FRIEND"]
    },
    "generation": {
      "used_tool_use": true,
      "termination": "final",
      "steps": [
        {
          "assistant_text": "",
          "duration_ms": 1517,
          "tool_calls": [
            {
              "name": "validate_gql",
              "args": {"query": "MATCH (a:Person {name: 'Alice'})-[:FRIEND]->(f:Person) RETURN f"},
              "result": {
                "class": "read",
                "construct": "",
                "valid": true
              },
              "is_error": false,
              "duration_ms": 1
            }
          ]
        },
        {
          "assistant_text": "MATCH (a:Person {name: 'Alice'})-[:FRIEND]->(f:Person) RETURN f",
          "duration_ms": 1837,
          "tool_calls": []
        }
      ]
    },
    "validation": {
      "passed": true,
      "class": "read",
      "construct": "",
      "parse_err": ""
    },
    "token_usage": {
      "cached_input_tokens": 6144,
      "total_tokens": 12674,
      "calls": 2,
      "by_model": {
        "openai/gpt-4o-mini": {
          "provider": "openai",
          "model": "gpt-4o-mini",
          "input_tokens": 12629,
          "output_tokens": 45
        }
      }
    },
    "nl": "Find ALL of Alice's friends",
    "termination": "success",
    "examples": [],
    "refinements": []
  }
}

ai.trace()

Returns the most recent NL-to-GQL pipeline trace recorded by ai.gql() 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()

ai.traces()

Returns the most recent n pipeline traces as a list of maps (newest first). When n is 0 or omitted, returns the full retained history (capped at 32). Use this to compare runs side-by-side rather than only seeing the latest trace.

GQL
RETURN ai.traces(3)

Feedback

ai.rate()

ai.rate() is the feedback hook into per-graph query memory. It acts on the most recent pipeline trace (the one ai.trace() would return) and does three things:

1. Stamps the trace: attaches your 1–5 rating and optional comment, so future ai.trace() / ai.traces() calls show which runs were judged good or bad.
2. Auto-purges bad examples: if rating ≤ 2 and the run was a success and query memory is enabled, the (NL, GQL) pair is removed from memory. A wrong answer never gets recalled as a few-shot example for similar future prompts. Ratings of 3, 4, 5 don't change memory, they're decoration only.
3. Returns a BOOL: true when a trace was found and rated, false when no trace exists yet or the rating is out of range.

Without query memory enabled (ai.set_ai_config('query_memory_enabled', true)), step 2 is a no-op and ai.rate() only stamps the trace. The function earns its keep when query memory is on.

Typical loop:

GQL
-- 1. Generate a query and inspect the result
CALL ai.gql({nl: "How many friends does Alice have?"}) YIELD stage, data
FILTER stage = "final"
RETURN data.gql

-- 2. Rate it — a low rating purges this NL/GQL pair from memory
RETURN ai.rate(2, "model returned the friend list instead of a count")

Now any future "how many ..." prompt won't recall this bad answer. If you'd rated it 5, the pair would stick around and be surfaced as a positive example.

Skills

A skill is a named natural-language template that you can recall later and pipe into ai.gql(). Useful for capturing prompts that worked well so you (or other sessions) can reuse them by name.

ai.save_skill()

Registers a named NL template. Passing an empty NL deletes the skill (idempotent). Returns true.

GQL
RETURN ai.save_skill("top_authors", "Who are the top 5 most-cited authors?")

ai.list_skills()

Returns every saved skill as a list of {name, nl, created_at} records.

GQL
RETURN ai.list_skills()

Result:

JSON
[
  {
    "name": "top_authors", 
    "nl": "Who are the top 5 most-cited authors?", 
    "created_at": "2026-05-28T11:42:03Z"
  }
]

ai.drop_skill()

Removes a saved skill by name. Returns true when a skill was deleted, false when the name was unknown.

GQL
RETURN ai.drop_skill("top_authors")

ai.skill_nl()

Returns the NL template of a saved skill so it can be piped into ai.gql(). Returns NULL when the name is unknown.

GQL
CALL ai.gql({nl: ai.skill_nl("top_authors")})
YIELD stage, data
FILTER stage = "final"
RETURN data.gql

Pipeline Configuration

ai.ai_config()

Returns the current NL-to-GQL pipeline configuration.

GQL
RETURN ai.ai_config()

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.set_ai_config()

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

Available configuration keys:

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

Enable per-graph query memory:

GQL
RETURN ai.set_ai_config("query_memory_enabled", true)