Use Neo4j GenAI Plugin ai.text.* functions and procedures for in-Cypher embedding generation, text completion, structured output, chat, tokenization, and batch ingestion. Covers ai.text.embed(), ai.text.embedBatch(), ai.text.completion(), ai.text.structuredCompletion(), ai.text.aggregateCompletion()

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: 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](references/providers.md) Embedding Single embed [2025.11] ai.text.embed() returns VECTOR — directly storable and queryable in a vector index. Batch embed procedure [2025.11] Procedure signature: CALL ai.text.embedBatch(resource, provider, config) YIELD index, resource, vector List configured embed providers Text Completion [2025.11] Returns STRING . Aggregate completion — summarize across rows [2026.03] 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: 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. Aggregate structured completion — extract across multiple rows [2026.03] Chat [2025.12] Supported providers: openai and azure openai only. Returns MAP { message: STRING, chatId: STRING } . Store chatId to continue session. Tokenization & Chunking [2026.04] 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: 1. Count nodes first: MATCH (c:Chunk) WHERE c.embedding IS NULL RETURN count(c) 2. Verify config with one test node before batch 3. Use CALL { ... } IN TRANSACTIONS OF 500 ROWS for batches 1000 nodes 4. 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 [ ] CYPHER 25 prefix present on every ai.text. query [ ] GenAI plugin installed (Aura: automatic; self managed: JAR in plugins/) [ ] API key passed as $param , never as literal string [ ] model key explicit in config (no silent defaults) [ ] Provider string lowercase ( 'openai' , 'vertexai' , 'bedrock titan' ) [ ] Bulk writes use IN TRANSACTIONS OF 500 ROWS ; count target nodes first [ ] genai.vector.encode() replaced with ai.text.embed() [2025.11+] [ ] Chat sessions: store returned chatId for continuation; only openai/azure openai supported [ ] Structured output schema uses additionalProperties: false to prevent hallucination keys References [Full provider config](references/providers.md) — all required/optional keys per provider [Official docs](https://neo4j.com/docs/genai/plugin/current/) [API reference](https://neo4j.com/docs/genai/plugin/current/reference/functions procedures/)

neo4j-genai-plugin-skill