When to Use
- Generating embeddings inside Cypher without external Python (
ai.text.embed())
- Batch-embedding nodes/chunks during ingestion (
ai.text.embedBatch())
- Calling LLMs directly in Cypher for completions or GraphRAG (
ai.text.completion())
- Extracting structured JSON maps from LLM inside Cypher (
ai.text.structuredCompletion())
- Aggregating LLM summaries over grouped rows (
ai.text.aggregateCompletion())
- Stateful chat sessions in Cypher (
ai.text.chat())
- Counting tokens or chunking text by token limit (
ai.text.tokenCount(), ai.text.chunkByTokenLimit())
When NOT to Use
- Python-based GraphRAG pipelines (VectorCypherRetriever, HybridCypherRetriever) →
neo4j-graphrag-skill
- Vector index CREATE / kNN search / SEARCH clause →
neo4j-vector-index-skill
- GDS embeddings (FastRP, Node2Vec) →
neo4j-gds-skill
- Fulltext / keyword search →
neo4j-cypher-skill
Prerequisites
CYPHER 25 required for all ai.* functions. Two ways to enable:
// Per-query prefix (self-managed, no admin rights needed):
CYPHER 25 MATCH (n:Chunk) ...
// Per-database default (admin; applies to all sessions):
ALTER DATABASE neo4j SET DEFAULT LANGUAGE CYPHER 25
Installation:
- Aura: GenAI plugin enabled by default — no action needed
- Self-managed JAR: copy plugin JAR to
plugins/ directory
- Docker:
--env NEO4J_PLUGINS='["genai"]'
Provider Config Quick Reference
All ai.text.* functions accept a configuration :: MAP as last argument.
| Provider string | Required keys | Notes |
|---|
'openai' | token, model | token = OpenAI API key |
'azure-openai' | token, resource, model | token = OAuth2 bearer; resource = Azure resource name |
'vertexai' | model, project, region, token or apiKey | publisher defaults to 'google' |
'bedrock-titan' | model, region, accessKeyId, secretAccessKey | Embedding only |
'bedrock-nova' | model, region, accessKeyId, secretAccessKey | Completion only |
Optional for all: vendorOptions :: MAP passes provider-specific extras (e.g. { dimensions: 1024 } for OpenAI).
❌ Never hardcode API key literals. ✅ Always use $param passed via driver parameters dict.
Full provider config table → references/providers.md
Embedding
Single embed [2025.11]
CYPHER 25
MATCH (c:Chunk)
WHERE c.embedding IS NULL
WITH c
CALL {
WITH c
SET c.embedding = ai.text.embed(c.text, 'openai', {
token: $openaiKey,
model: 'text-embedding-3-small'
})
} IN TRANSACTIONS OF 500 ROWS
ai.text.embed() returns VECTOR — directly storable and queryable in a vector index.
Batch embed procedure [2025.11]
CYPHER 25
MATCH (c:Chunk) WHERE c.embedding IS NULL
WITH collect(c) AS chunks
UNWIND chunks AS c
WITH c.text AS text, c AS node
CALL ai.text.embedBatch(text, 'openai', { token: $openaiKey, model: 'text-embedding-3-small' })
YIELD index, resource, vector
MATCH (c:Chunk {text: resource})
SET c.embedding = vector
Procedure signature: CALL ai.text.embedBatch(resource, provider, config) YIELD index, resource, vector
List configured embed providers
CYPHER 25
CALL ai.text.embed.providers()
YIELD name, requiredConfigType, optionalConfigType, defaultConfig
RETURN name, requiredConfigType
Text Completion [2025.11]
CYPHER 25
RETURN ai.text.completion(
'Summarize: ' + $text,
'openai',
{ token: $openaiKey, model: 'gpt-4o-mini' }
) AS summary
Returns STRING.
Aggregate completion — summarize across rows [2026.03]
CYPHER 25
MATCH (c:Chunk)-[:PART_OF]->(a:Article {id: $articleId})
RETURN ai.text.aggregateCompletion(
c.text,
'Summarize the following article chunks in 3 sentences',
'openai',
{ token: $openaiKey, model: 'gpt-4o-mini' }
) AS summary
value parameter = each row's STRING fed to the LLM. Uses toString() for non-string values.
Pure-Cypher GraphRAG Pattern
Embed question → vector search → graph traverse → LLM completion — all in one Cypher query:
CYPHER 25
WITH ai.text.embed($question, 'openai', { token: $openaiKey, model: 'text-embedding-3-small' }) AS qEmbedding
MATCH (chunk:Chunk)
SEARCH chunk IN (VECTOR INDEX chunk_embedding FOR qEmbedding LIMIT 10) SCORE AS score
// SEARCH preferred on 2026.x; db.index.vector.queryNodes() deprecated 2026.04 — SEARCH syntax → neo4j-vector-index-skill
MATCH (chunk)<-[:HAS_CHUNK]-(article:Article)
OPTIONAL MATCH path = shortestPath((article)-[*..3]-(other:Article))
WITH chunk, article, collect(DISTINCT other.title) AS related, score
ORDER BY score DESC LIMIT 5
WITH collect(chunk.text + '\n[Source: ' + article.title + ']') AS context, $question AS question
RETURN ai.text.completion(
'Answer based on context:\n' + reduce(s='', c IN context | s + c + '\n') + '\nQuestion: ' + question,
'openai',
{ token: $openaiKey, model: 'gpt-4o-mini' }
) AS answer
Key insight (Bergman): shortest path between seed nodes surfaces relationships not visible from direct neighbors alone.
Structured Output [2026.02]
Returns MAP — directly storable as node properties or used downstream in Cypher.
CYPHER 25
MATCH (p:Product {id: $productId})
WITH p,
ai.text.structuredCompletion(
'Extract key attributes from: ' + p.description,
{
type: 'object',
properties: {
category: { type: 'string' },
tags: { type: 'array', items: { type: 'string' } },
priceRange: { type: 'string', enum: ['budget', 'mid', 'premium'] }
},
required: ['category', 'tags', 'priceRange'],
additionalProperties: false
},
'openai',
{ token: $openaiKey, model: 'gpt-4o-mini' }
) AS extracted
SET p.category = extracted.category,
p.priceRange = extracted.priceRange
WITH p, extracted.tags AS tags
UNWIND tags AS tag
MERGE (t:Tag {name: tag})
MERGE (p)-[:TAGGED]->(t)
Aggregate structured completion — extract across multiple rows [2026.03]
CYPHER 25
MATCH (:User {id: $userId})-[:ORDERED]->(o:Order)-[:CONTAINS]->(p:Product)
RETURN ai.text.aggregateStructuredCompletion(
p.name + ': ' + p.category,
'Build a shopping profile for this user',
{
type: 'object',
properties: {
preferredCategories: { type: 'array', items: { type: 'string' } },
spendingTier: { type: 'string', enum: ['economy', 'standard', 'premium'] }
},
required: ['preferredCategories', 'spendingTier']
},
'openai',
{ token: $openaiKey, model: 'gpt-4o-mini' }
) AS profile
Chat [2025.12]
Supported providers: openai and azure-openai only.
// Start new conversation (chatId = null → new session)
CYPHER 25
WITH ai.text.chat(
'Hello, who are you?',
null,
'openai',
{ token: $openaiKey, model: 'gpt-4o-mini' }
) AS result
RETURN result.message AS reply, result.chatId AS sessionId
// Continue conversation (pass returned chatId)
CYPHER 25
WITH ai.text.chat(
'What did I just ask you?',
$chatId,
'openai',
{ token: $openaiKey, model: 'gpt-4o-mini' }
) AS result
RETURN result.message AS reply, result.chatId AS sessionId
Returns MAP { message: STRING, chatId: STRING }. Store chatId to continue session.
Tokenization & Chunking [2026.04]
// Count tokens before sending to LLM
CYPHER 25
RETURN ai.text.tokenCount($text, 'openai', { token: $openaiKey, model: 'gpt-4o-mini' }) AS tokenCount
// Chunk text by token limit (no external dependencies)
CYPHER 25
UNWIND ai.text.chunkByTokenLimit($longText, 512, 'gpt-4', 50) AS chunk
MERGE (c:Chunk { text: chunk })
// List providers supporting tokenCount
CYPHER 25
CALL ai.text.tokenCount.providers() YIELD name, requiredConfigType
RETURN name, requiredConfigType
Signatures:
ai.text.tokenCount(input, provider, configuration = {}) :: INTEGER — provider-driven tokenizer; uses provider config (token/model). Local tokenizer for 'openai' (no API call); free API call for 'Bedrock' and 'VertexAI'.ai.text.chunkByTokenLimit(input, limit, model = 'gpt-4', overlap = 0) :: LIST<STRING> — local OpenAI tokenizer keyed off model; no provider call, no token required. Chunks by newlines, then spaces, then token count. Set limit below provider max to leave room for prompt overhead.
ai.text.embedBatch [2026.04] supports maxBatchSize (config key) to cap data per API request — defaults to 8192 for 'openai' and 'azure-openai'; no default for 'vertexai' (set if hitting token-limit errors).
Write Gate
SET node.embedding = ai.text.embed(...) and SET node.* = ai.text.structuredCompletion(...) write to the graph.
Before bulk writes:
- Count nodes first:
MATCH (c:Chunk) WHERE c.embedding IS NULL RETURN count(c)
- Verify config with one test node before batch
- Use
CALL { ... } IN TRANSACTIONS OF 500 ROWS for batches > 1000 nodes
- Require explicit confirmation before executing
Deprecated — Do NOT Use
| Old function | Replacement |
|---|
genai.vector.encode() [deprecated] | ai.text.embed() |
genai.vector.encodeBatch() [deprecated] | CALL ai.text.embedBatch() |
genai.vector.listEncodingProviders() [deprecated] | CALL ai.text.embed.providers() |
Common Errors
| Error | Cause | Fix |
|---|
Unknown function 'ai.text.embed' | Missing CYPHER 25 prefix OR plugin not installed | Add CYPHER 25 prefix; verify plugin installed |
Cypher version not supported | Using CYPHER 25 on Neo4j < 5.20 or missing plugin | Upgrade Neo4j; ensure GenAI plugin loaded |
Configuration key 'token' missing | Provider config map incomplete | Check required keys for provider (see table above) |
null returned from embed | Wrong model name or provider auth failed | Test with RETURN ai.text.embed('test', 'openai', {token:$k, model:'text-embedding-3-small'}) standalone |
Unsupported provider | Provider string typo (case-sensitive, lowercase) | Use 'openai' not 'OpenAI'; run CALL ai.text.embed.providers() |
ai.text.chat fails on VertexAI | Chat only supported on openai/azure-openai | Switch to openai/azure-openai for chat |
Checklist
References