AI & Vector Functions

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)

AI Completion Functions

AI completion functions use a large language model to generate or execute GQL queries from natural language. Using ai.setapikey() to configure both the embedding and completion provider at once, no extra setup is needed. To use a different provider for completion (e.g., Anthropic for completion, OpenAI for embeddings), use ai.setapikey() with false to set the key without activating, then ai.setCompletionProvider() to switch.

ai.gql()

Converts a natural language question into a GQL query using the configured completion provider. The function automatically includes the current graph's schema (labels, properties, edge patterns) as context for the LLM.

GQL
RETURN ai.gql("Find all papers written by Alex")

Result:

ai.read()

Converts a natural language question into a read-only GQL query, executes it, and returns the results. Only read operations are allowed, any generated query containing write operations (INSERT, DELETE, SET, etc.) is rejected.

The returned record contains:

GQL
RETURN ai.read("How many papers did Alex write?")

Result:

JSON
{
  "query": "MATCH (p:Paper) WHERE p.author = 'Alex' RETURN COUNT(p) AS count",
  "results": [
    {
      "count": 2
    }
  ],
  "count": 1
}

ai.setCompletionProvider()

Sets the active completion provider. The provider's API key must have been set first via ai.setapikey().

GQL
RETURN ai.setCompletionProvider("openai")

ai.completionProvider()

Returns the name of the current completion provider.

GQL
RETURN ai.completionProvider()

Vector Creation

ai.vector()

Converts a list of numbers to a VECTOR type. Values are stored as 32-bit floats, so minor precision differences may occur (e.g., 0.1 becomes 0.10000000149011612). This is useful when you need to explicitly create a VECTOR value for storing in a VECTOR property or passing to similarity functions.

GQL
RETURN ai.vector([0.1, 0.2, 0.3])

Result:

JSON
{
  "values": [
    0.10000000149011612,
    0.20000000298023224,
    0.30000001192092896
  ]
}

ai.embed()

Generates an embedding vector from text using the configured AI provider.

An AI provider must be configured with ai.setapikey() before using this function.

GQL
LET embedding = ai.embed("Introduction to graph databases")
RETURN embedding, ai.dimension(embedding) AS dimensions

Result:

JSON
{
  "embedding": {
    "values": [
      -0.0258026123046875,
      -0.0126800537109375,
      …
      0.0162200927734375,
      -0.017486572265625
    ]
  },
  "dimensions": 1536
}

Similarity Functions

ai.cosine()

Computes cosine similarity between two vectors. Returns a value between -1 and 1, where 1 means identical direction.

GQL
LET v1 = ai.vector([1.0, 0.0, 0.0])
LET v2 = ai.vector([1.0, 1.0, 0.0])
RETURN ai.cosine(v1, v2)

Result: 0.7071067690849304

ai.euclidean()

Computes Euclidean distance between two vectors. Lower values indicate more similarity.

GQL
LET v1 = ai.vector([1.0, 0.0])
LET v2 = ai.vector([0.0, 1.0])
RETURN ai.euclidean(v1, v2)

Result: 1.4142135381698608

ai.dot()

Computes the dot product of two vectors.

GQL
LET v1 = ai.vector([1.0, 2.0, 3.0])
LET v2 = ai.vector([4.0, 5.0, 6.0])
RETURN ai.dot(v1, v2)

Result: 32

ai.distance()

Computes the cosine distance between two vectors (1 - cosine similarity). Lower values indicate more similarity.

GQL
LET v1 = ai.vector([1.0, 0.0, 0.0])
LET v2 = ai.vector([1.0, 1.0, 0.0])
RETURN ai.distance(v1, v2)

Result: 0.2928932309150696

Vector Utilities

ai.dimension()

Returns the number of dimensions in a vector.

GQL
LET v = ai.vector([3.0, 4.0])
RETURN ai.dimension(v)

Result: 2

ai.magnitude()

Returns the magnitude (L2 norm) of a vector.

GQL
LET v = ai.vector([3.0, 4.0])
RETURN ai.magnitude(v)

Result: 5

ai.normalize()

Normalizes a vector to a unit vector (magnitude of 1).

GQL
LET v = ai.vector([3.0, 4.0])
RETURN ai.normalize(v)

Result:

JSON
{
  "values": [
    0.6000000238418579,
    0.800000011920929
  ]
}

ai.toList()

Converts a vector to a list of numbers.

GQL
LET embedding = ai.embed("Introduction to graph databases")
RETURN ai.toList(embedding)

Result: [-0.0258026123046875, -0.0126800537109375, …, 0.0162200927734375, -0.017486572265625]

Vector Arithmetic

ai.add()

Adds two vectors element-wise.

GQL
LET v1 = ai.vector([1.0, 2.0])
LET v2 = ai.vector([3.0, 4.0])
RETURN ai.toList(ai.add(v1, v2))

Result: [4, 6]

ai.subtract()

Subtracts the second vector from the first element-wise.

GQL
LET v1 = ai.vector([5.0, 3.0])
LET v2 = ai.vector([1.0, 2.0])
RETURN ai.toList(ai.subtract(v1, v2))

Result: [4, 1]

ai.scale()

Multiplies a vector by a scalar value.

GQL
LET v = ai.vector([1.0, 2.0, 3.0])
RETURN ai.toList(ai.scale(v, 2))

Result: [2, 4, 6]

Provider Configuration

ai.setapikey()

Sets the API key for an AI provider. Optionally activates it as the current provider.

By default, calling ai.setapikey() both sets the key and activates the provider:

GQL
RETURN ai.setapikey("openai", "sk-...")

Each provider stores one API key. Calling ai.setapikey() again for the same provider overwrites the previous key. To set keys for multiple providers without activating them, pass false as the third argument, then use ai.setprovider() to switch:

GQL
RETURN ai.setapikey("gemini", "AQ.za...", false)

NOTE

"anthropic" supports completion only (ai.gql(), ai.read()), it has no embedding model. Use ai.setapikey("anthropic", "sk-ant-...", false) followed by ai.setCompletionProvider("anthropic") to configure it for completion.

ai.setprovider()

Switches the active embedding provider. The provider's API key must have been set first via ai.setapikey().

GQL
RETURN ai.setprovider("openai")

ai.provider()

Returns the name of the current AI provider.

GQL
RETURN ai.provider()

ai.embeddim()

Returns the embedding dimension of the current provider.

GQL
RETURN ai.embeddim()