Neo4j Graph Schema Design for LLM Applications

Executive Summary

This report surveys best practices for designing Neo4j graph schemas tailored to LLM applications. We cover core graph modeling principles (nodes, relationships, properties, labels, indexes, constraints), and show how to apply them in typical LLM-related patterns: knowledge graphs, retrieval-augmented generation (RAG/GraphRAG), conversation memory, prompt templates, and embedding storage. We discuss key trade-offs (query performance vs storage, write/read balance, scalability, consistency) and emphasize the importance of query-driven design. Indexing and constraint strategies are outlined, including vector indexes for similarity search. We compare modeling choices (when to use node vs relationship vs property) with examples. Special topics include temporal/versioned data (e.g. modeling events via intermediate nodes), multi-tenancy (separate DB vs label/role isolation), security (RBAC, access control) and data lineage/provenance (modeling ETL flows in a graph). We cover embedding storage and hybrid search, showing vector index creation and queries. Integration patterns with LLM pipelines (e.g. LangChain, Neo4j’s GraphCypherQA) are discussed, as well as caching/denormalization strategies, monitoring/benchmarking queries, and schema migration/versioning tactics. The report explicitly lists critical factors (query patterns, cardinality, update frequency, latency, dataset size, embedding dimensions, vector index technology) to guide design choices. Where helpful, tables summarize schema pattern trade-offs, and Mermaid diagrams illustrate entity-relationship schemas and data flow pipelines. Code blocks give concrete Cypher examples (indexes, constraints, queries) and configuration snippets. All guidance is grounded in Neo4j documentation, community posts, and GenAI graph literature.

Core Neo4j Data Modeling Principles

Neo4j uses a property graph model: data are stored as nodes (entities) connected by relationships (edges), each of which may have key-value properties. Nodes have one or more labels (analogous to types), and relationships have a type. By convention, node labels use PascalCase, relationship types use UPPER_SNAKE_CASE, and property keys use camelCase. A Neo4j database is schema-optional: you can create nodes/relationships freely, but you may add indexes and constraints to optimize queries and enforce data integrity. For example, apply uniqueness constraints on identifier properties (e.g. CREATE CONSTRAINT ON (p:Person) ASSERT p.userId IS UNIQUE;) and indexes on frequently matched properties to speed lookups. Write your queries before finalizing the model: knowing expected query patterns (e.g. range queries by date) helps decide when to use nodes vs relationships or separate “time” entities. In Neo4j, traversals are highly optimized – following relationships is extremely fast, often much faster than filtering by properties. Thus when data is inherently connected, prefer modeling it as nodes/relationships rather than embedding values in properties alone. However, use properties for intrinsic metadata (e.g. names, timestamps) that won’t be traversed.

Key rules include:

• Query-first design: Model around the most critical queries. Prioritize fast paths for high-value queries, even if some others slow down.
• Labels and constraints: Define labels for entity types (e.g. :Person, :Document) and enforce uniqueness (e.g. userId or docId) via constraints. Use property existence constraints to ensure required fields.
• Avoid property bloat: Don’t cram multi-valued or shared data into lists on one node if it needs relating. For example, if many entities share a value (like a location or tag), make it its own node to allow connecting multiple nodes.
• Name conventions: Use clear, consistent naming (PascalCase for labels, UPPER_CASE for relationship types, descriptive property names) to improve readability.
• Refactor with Cypher: Neo4j allows evolving the model over time. Use SET, MERGE, and Cypher script approaches to add/remove labels, move properties to new nodes, or batch update schema. For example:

// Add a new label and remove the old label for data migration
MATCH (n:OldLabel) 
SET n:NewLabel 
REMOVE n:OldLabel;

遵循 书写查询优先 的原则。根据预期查询模式设计模型，例如如果需要按时间范围查询，则不要将日期保存在大型节点集合的属性里，而应将其建模为独立的时间节点或关系。应用唯一性和存在性约束来保证数据质量，比如：

CREATE CONSTRAINT person_id_unique IF NOT EXISTS
  FOR (p:Person) REQUIRE p.userId IS UNIQUE;

此外，Neo4j 内置的图遍历性能极高——沿着关系搜索通常比过滤属性快得多。因此，若信息需要跨实体共享或查询，应尽量使用节点/关系建模；仅当信息仅为单节点元数据且无需遍历时，才用属性存储。

Schema Patterns for LLM Use Cases

知识图谱 (Knowledge Graph)

Knowledge Graphs connect entities (e.g. Person, Organization, Document, Topic) via semantic relationships. Model each real-world entity as a node with its properties; create relationships to capture interactions. For example, in a research domain:

erDiagram
PERSON {
  string personId
  string name
}
ARTICLE {
  string articleId
  string title
}
TOPIC {
  string topicId
  string name
}
PERSON ||--o{ ARTICLE : AUTHOR_OF
ARTICLE }o--|| TOPIC : COVERS

This simple ER diagram illustrates a :Person writing many :Articles, and each :Article linked to one or more :Topics. In practice you might also have :Institution, :Conference, etc. Include indexes on lookup fields (e.g. :Person(personId), :Article(articleId)). Unique constraints on IDs prevent duplicate nodes. Graph queries can then traverse this network (e.g. find co-authors by path patterns). The GraphRAG approach (combining graph and RAG) emphasizes such schemas: it extracts entities and relations from text to build a rich KG that RAG pipelines then use.

示例: 如果一个文档提到了多个概念，可做如下模型：Person -[:MENTIONS]-> (Entity:Topic)，并给 Person、Entity 等打标签。构造索引和约束，如 CREATE INDEX ON :Topic(name) 以加速基于属性的检索。GraphRAG 案例显示，通过将知识存储在图结构中，检索结果更加准确和可解释。

检索增强生成 (GraphRAG)

Retrieval-Augmented Generation augments an LLM’s prompt with retrieved knowledge. In Neo4j, this often means combining vector-based embedding search with structured graph queries. A common pattern (GraphRAG) is:

flowchart LR
    Q[User Query] --> VS[Vector Search]
    Q --> GS[Graph Search]
    VS --> Combine[Combine Results]
    GS --> Combine
    Combine --> LLM[Prompt to LLM]
    LLM --> A[LLM Answer]

The user query is embedded and searched via a Neo4j vector index (e.g. on document chunks) and/or via full-text indexes. The resulting high-relevance documents (or passages) provide entry points into the graph. Then a Cypher traversal (graph query) explores related nodes/edges to gather structured context (entities, facts, multi-hop paths). These pieces are combined (e.g. concatenated or structured) and fed as an augmented prompt to the LLM. Neo4j’s blog shows this yields richer context than vector-only retrieval.

For example, use LangChain’s GraphQA integration or the neo4j-graphrag library to issue both a Cypher query and a vector lookup. In Cypher one can do:

CALL db.index.vector.queryNodes('docEmbeddings', 5, $queryVector) 
YIELD node AS doc, score
WHERE score > 0.8
MATCH (doc)-[:HAS_ENTITY]->(e:Entity)
RETURN doc.id, doc.title, collect(e.name) AS entities, score;

This retrieves top-5 documents semantically similar to the query, then finds associated entities. The entities and doc text form context for the LLM. Choosing which layers to index (full-text, vector, spatial, etc.) depends on the use case.

Schema: Store unstructured text chunks as nodes (e.g. :Paragraph or :DocumentChunk) with a property embedding (a LIST or new VECTOR type). Create a vector index on that property for nearest-neighbor search (e.g. CREATE VECTOR INDEX chunkVec FOR (c:DocumentChunk) ON (c.embedding)). Also build the KG schema on top (entities, relations) to connect those chunks to structured data. The GraphRAG pattern then leverages both graph connectivity and vector similarity.

对话记忆 (Conversation Memory)

LLM-based chatbots and agents require storing dialogue history and extracted knowledge. A common graph schema (as in Neo4j Labs’ agent-memory) uses nodes for Conversation, Message, Entity, etc.. For example:

erDiagram
CONVERSATION {
  string sessionId
}
USER {
  string userId
  string name
}
MESSAGE {
  string text
  string role
  datetime timestamp
}
ENTITY {
  string name
}
CONVERSATION ||--o{ MESSAGE : contains
USER ||--o{ MESSAGE : sent_by
MESSAGE }o--|| ENTITY : mentions

Here, a :Conversation node groups a thread of messages, each :Message has properties (content, timestamp, speaker role), and :User nodes send messages. The :Message may mention :Entity nodes extracted via NLP (NER). Messages are chained (e.g. via a NEXT relationship) to preserve order, or use a timestamp property. Neo4j Labs’ agent-memory tool defines exactly this pattern: Conversation→Message (one-to-many), Message-[:NEXT_MESSAGE]→Message, and Message-[:MENTIONS]→Entity. This supports “short-term memory” (full chat history) and “long-term memory” (entities and facts). Index sessions by sessionId and messages by messageId.

For conversation search, one can query the graph by session or by entity mentions. Example Cypher:

MATCH (c:Conversation {sessionId:$id})-[:HAS_MESSAGE]->(m:Message)
RETURN m.timestamp, m.role, m.text ORDER BY m.timestamp;

This returns the entire chat history for a session. For entity-based queries:

MATCH (e:Entity {name:$entity})<-[:MENTIONS]-(m)-[:HAS_MESSAGE]->(c:Conversation)
RETURN c.sessionId, collect(m.text) AS context;

This finds all messages mentioning a given entity across conversations. The agent-memory docs also show automatic summarization and preference learning from this graph.

提示模板 (Prompt Templates)

Prompt templates (static question structures with blanks) can be stored as nodes or properties. One pattern is to create a :PromptTemplate node with a templateText property (e.g. "Translate {{sentence}} to French.") and metadata (like domains or topics). Link a template to relevant entities or context types via relationships. For instance:

CREATE (t:PromptTemplate {name:"SummarizeDoc", text:"Summarize the following document: {{docContent}}"});
MATCH (d:Document {id:$docId}), (t:PromptTemplate {name:"SummarizeDoc"})
CREATE (d)-[:USES_TEMPLATE]->(t);

LLM pipelines (e.g. LangChain prompts) can fetch templates by label or name, fill variables with data from the graph, and then call the model. This separates static prompt engineering from data. There are few official patterns, but we recommend treating templates as first-class graph data for flexibility and traceability of how prompts are constructed.

嵌入存储与相似度搜索 (Embedding Storage and Vector Search)

LLM applications often involve vector embeddings. In Neo4j, store an embedding as a property (either LIST<Float> or the native VECTOR type) on a node or relationship. For example, each document paragraph or node might have embedding: List<Float> of length 768 or 1536. Neo4j supports vector indexes (powered by Lucene’s HNSW algorithm) for fast nearest-neighbor search.

Example: suppose each :Paragraph node has embedding. Create a vector index:

CREATE VECTOR INDEX paraVec IF NOT EXISTS
  FOR (p:Paragraph) ON (p.embedding)
  OPTIONS {indexConfig:{vector.dimensions:768, vector.similarity_function:'COSINE'}};

This index uses cosine similarity (recommended for text embeddings) and HNSW parameters. To query similar vectors:

WITH [0.12, -0.34, ..., 0.56] AS queryVec
CALL db.index.vector.queryNodes('paraVec', 10, queryVec) 
YIELD node AS para, score
RETURN para.paragraphId AS id, score
ORDER BY score DESC;

This returns the 10 closest paragraphs by embedding. The score reflects vector similarity (higher is more similar by default cosine). Vector search can be combined with graph filters (e.g. restrict to certain labels or time ranges). For example:

CALL db.index.vector.queryNodes('paraVec', 10, queryVec)
YIELD node, score
MATCH (node)-[:BELONGS_TO]->(d:Document {project:"Alpha"})
RETURN node, score;

Using hybrid queries (vector plus graph filters) lets you incorporate domain constraints (e.g. only search within documents of a project). Neo4j also supports multi-modal indexes (index on multiple properties or relationship types). Key considerations: embedding dimension (256, 512, 768, 1536 etc), index memory (tune vector.hnsw.ef_construction, m), and similarity function (cosine vs Euclidean).

Trade-offs and Design Considerations

Graph modeling inevitably involves trade-offs. Key factors to consider:

• Query Patterns: Tailor the schema for expected queries. For heavy read/analytics, favor pre-linked nodes/denormalization; for write-heavy scenarios, avoid too many indexes/constraints to speed ingestion. As Neo4j docs note, no single model optimizes all queries. Focus on critical queries first.
• Cardinality & Degree: High-degree nodes (like a hub entity connected to millions) can slow traversals; sometimes invert modeling (e.g. use relationships differently or shard high-cardinality attributes into separate nodes). Conversely, low-cardinality shared values are good as nodes (to reuse) rather than repeated properties.
• Read/Write Patterns: If the graph is mostly read-optimized (e.g. a static KG for RAG), you can afford more indexes and denormalization. For high write/update rates (e.g. streaming chat logs), minimize heavy indexes/constraints and batch writes. Neo4j Community Edition only supports one active DB, so very large or multi-tenant workloads may need Enterprise.
• Scalability: Neo4j scales well on clusters, but ~billions of nodes/edges can require sharding (via Fabric) or multiple databases. Vector indexes with very high-dimensional embeddings (e.g. 3072 floats) require more memory and time to build.
• Consistency vs Performance: Neo4j is fully ACID, which is good for data integrity but means very large transactions (e.g. batch ingest) can hit limits. Consider batching or APOC periodic commits for big migrations.
• Index Overhead: Every index speeds reads but slows writes. Choose indexes for fields used in WHERE or MATCH. For LLM patterns, full-text indexes (for keyword search) and vector indexes (for semantic search) are common. Extra composite indexes (multiple fields) can speed certain queries at storage cost.

The table below summarizes some common schema options and their trade-offs:

Modeling Choice	Advantages	Disadvantages / Costs
Entity Nodes	Reusable across relationships; powerful traversals; rich analytics (e.g. graph algorithms).	More nodes means more storage and possibly more indexes; more hops in queries.
Properties on Node	Simple, fast access for single-entity data. Low overhead if the data is truly local.	Cannot be shared; expensive to scan many nodes for property values; loses relational context.
Relationship Properties	Attaches attributes to connections (e.g. timestamp on a :VISITED relationship) without extra nodes.	Cannot easily index relationship properties in Neo4j (only Node indexes are supported) and harder to query than linking through a node.
Intermediate Nodes (Reification)	Captures complex relationships and history (e.g. an “Event” node between Person and Location with time stamps).	Additional traversal steps; more complex queries; slight performance overhead per extra node/hop.
Denormalized Edges	Duplicate or cache paths for faster lookup (e.g. direct edge to “current_mentor” alongside a longer chain).	Extra storage and need to maintain consistency (every write might need multiple updates).

选择模型时需要考虑查询性能、存储成本和更新模式等权衡。例如，虽然用实体节点建模可以获得丰富的连通性和分析能力，但会增加节点数和关系遍历的深度；而将值直接作为属性则简化了图但限制了复用。Neo4j 官方提醒，没有一种模型能同时对所有查询都最优，需根据业务优先级取舍。

Indexing and Constraint Strategies

Proper indexes and constraints are crucial for performance and integrity:

• Unique constraints: For any label with a business key (e.g. :User(userId), :Document(docId)), create a uniqueness constraint so Neo4j can enforce it and index the field automatically:

  CREATE CONSTRAINT user_id_unique IF NOT EXISTS
    FOR (u:User) REQUIRE u.userId IS UNIQUE;
  

• Existence constraints: Neo4j (4.3+) allows requiring a property to exist on a label (e.g. requiring :Order(timestamp) for audit). This ensures no nodes lack critical fields.
• Indexes: Use b-tree indexes for exact-match lookups on high-selectivity properties (e.g. username, GUIDs). Composite indexes (multiple props) can speed multi-field searches. Full-text indexes support case-insensitive token search on text fields. Create indexes with names and IF NOT EXISTS:

  CREATE INDEX user_name_idx IF NOT EXISTS
    FOR (u:User) ON (u.name);
  CALL db.index.fulltext.createNodeIndex("docFullText", ["Document"], ["title","content"]);
  

• Vector indexes: As above, create VECTOR indexes on embedding properties. Specify dimensions and similarity: e.g.

  CREATE VECTOR INDEX docEmbeddings_idx IF NOT EXISTS
    FOR (d:Document) ON (d.embedding)
    OPTIONS { indexConfig: { `vector.dimensions`:1536, `vector.similarity_function`: 'COSINE' } };
  

• Index hints: In rare cases where the query planner misfires, use index hints (e.g. USING INDEX) to force usage of a specific index in a query. Monitor the db.querylog (slow query log) to see if expected indexes are used, and use EXPLAIN/PROFILE to analyze execution plans.

Constraint/index decisions should weigh query benefit vs write cost. For example, if you frequently query by a tag, index it; if a property is only used once, skip indexing. Neo4j schemas can and should evolve: adding new indexes/constraints later will gradually enforce and speed up queries.

Node vs Relationship vs Property Modeling

When to use properties vs relationships (or nodes for what might be a property) is a common design question:

• Shared Attributes: If multiple entities share a value or you want to traverse/filter by it, model it as a node. E.g. store country names as :Country nodes, connecting (:Person)-[:LIVES_IN]->(:Country) rather than repeating country strings. This allows fast traversals (“find all people in USA”) and avoids storing the same string many times.
• Edges vs separate nodes: While Neo4j relationships are first-class and very fast to traverse, they cannot have outgoing relationships or multiple groupings. If a relationship itself has multiple attributes or needs linking to other objects, create an intermediate node. For example, to model that a person stayed at a house for some time, Andrew Bowman suggests a :Residence node between Person and House, storing start/end dates on Residence. This way you don’t duplicate person nodes and keep temporal info easily accessible.
• One-to-many or many-to-many: By default, relationships handle these. If each entity “belongs to one category,” you could use either a property or a relationship. If categories are few and don’t need their own identity, a property might suffice. But if categories evolve or have attributes (and multiple entities share them), use nodes+relationships. For example, storing a user’s multiple email addresses: you could model (:User)-[:HAS_EMAIL]->(:Email). While storing them as a list property is possible, having separate Email nodes allows queries like “find all users at this email domain” more efficiently.

总之：关系数据库观念不完全适用图数据库。对于需要通过关系进行分析的信息，应使用节点/关系模型；对于仅作为元数据或不参与查询的内容，使用属性即可。上文例子中，使用独立节点存放可重用数据通常更灵活、性能更佳。

Temporal and Versioned Data

Time-varying information (logs, history, versions) is best modeled explicitly. Options include:

• Temporal properties: If you only need a simple timestamp (e.g. account creation date) and no range queries, a datetime property on a node is fine. But if you need to query date ranges or multiple time-stamped events, do not put the date on the entity itself.
• Event nodes: A robust pattern is to insert timestamped event nodes. For instance, instead of (Person)-[:LIVES_AT {from:..., to:...}]->(House), create (Person)-[:HAS_RESIDENCE]->(r:Residence {from:...,to:...})-[:AT_LOCATION]->(House). The Residence node captures one interval of living at a house, and you can link multiple such intervals. This avoids relationship property limitations and supports easy multi-hop queries. You could also add a boolean :CURRENT_RESIDENCE relationship to mark the active one for quick access (as Andrew suggested).
• Versioning: To version entities (e.g. documents, prompts), either maintain a timeline of nodes or use a validFrom/validTo property on nodes/relationships. For heavy versioned history, one can replicate a pattern like (Entity)-[:PREVIOUS_VERSION]->(OldEntity) linking revisions. Alternatively, use a surrogate node for each version with an effective date. The key is to enable queries like “find the latest version at time T” using timestamps or ordered relationships.

If using relationship time properties, Neo4j advises separate nodes instead for range queries. The event-node pattern (like :Residence) generalizes to auditing any state change. For example:

// Modeling status changes with events
MATCH (u:User {id:$id})
MERGE (e:StatusChange {userId:$id, from:"active", to:"suspended", at:datetime()})
CREATE (u)-[:HAS_STATUS_CHANGE]->(e);

This way you accumulate a history of StatusChange events as nodes linked to the user.

Multi-Tenancy

Multi-tenancy (isolating data of different customers) in Neo4j can be implemented several ways:

• Separate databases (Neo4j 4+ Enterprise): Neo4j Enterprise allows multiple active databases per cluster. Each tenant can have its own database, fully isolated (no cross-DB relationships). This is the strongest isolation but means global traversals across tenants aren’t possible.
• Role-based label filtering: In a single database, tag nodes/rels with tenant IDs (as a property or label). Use Neo4j’s Enterprise fine-grained security to restrict each user role to see only certain labels or properties. For example, all nodes for tenant A might have label :TenantA. Create roles that only grant read access to TenantA:*. The GraphAware OGM label plugin also offered dynamic label injection per tenant (legacy solution). This keeps common/shared data open but requires careful label management.
• Fabric (sharding): Neo4j Fabric can federate queries across multiple databases or even remote clusters. In a multi-tenant SaaS setup, Fabric could allow querying a user’s partition spread over shards. This is an advanced use-case for large-scale tenancy.

Multi-tenancy choices depend on consistency needs and volume. Separate databases offer transactional isolation (no risk of tenants seeing each other’s data), but require more maintenance. Shared-DB with RBAC is lighter but must manage permissions meticulously. For LLM use-cases, if tenants’ knowledge graphs are largely isolated, separate DBs (or AuraDB projects) may be simplest; if they share concepts, consider filtering by tenant property.

Security and Access Control

Secure by design: at minimum use Neo4j Enterprise’s role-based access control (RBAC). Key practices:

• User roles: Create roles for different job functions (admin, analyst, etc.). Grant/deny privileges at label/relationship level. For example, allow analyst role to read :Document and :Entity, but not write, while admin can do both.
• Fine-grained privileges: In Enterprise, you can restrict down to individual labels or types. For instance, only doctors can MATCH (p:Patient) but researchers can only read aggregated data. The healthcare tutorial shows granting read/write selectively.
• Authentication integration: Integrate LDAP/SSO in production to centralize identity, so that graph users align with corporate users.
• Encryptions: Enable TLS/SSL for all client-driver communication, and use disk encryption at rest if needed.
• Network security: Place Neo4j behind firewalls, use VPNs or VPCs. Avoid exposing Bolt endpoints publicly.
• Auditing and provenance: For sensitive or regulated data, log all write operations. The graph itself (conversation logs, RAG answers) becomes part of provenance; if a generated answer is used in production, you can trace back the chain in the KG. Keeping :Provenance or :AuditEvent nodes for significant actions can help (see next section).

While Community Edition lacks fine-grained roles, you can still isolate at application level. However, any serious multi-user or multi-tenant deployment should use Enterprise features to prevent data leakage.

Data Lineage and Provenance

In GenAI contexts, tracing the origin of information is crucial. Neo4j is well-suited to model data lineage/provenance as a graph. A typical lineage schema might include nodes for DataAsset (tables, files, documents), Process (ETL jobs, model runs), Person/Role (author of process), and Step (individual transformations). Edges capture “flow”: e.g., (SourceFile)-[:PROCESSED_BY]->(ETLJob)-[:CREATES]->(TargetTable). Metadata like timestamps or version IDs can be node properties. Because graph structure naturally represents flow networks, it’s ideal for answering questions like “which reports depend on this source field” or “trace this output back to original inputs”.

For LLM apps, provenance includes tracking which documents or knowledge nodes contributed to an answer. One can link each generated answer node to the source snippets used (via relationships :BASED_ON) and to the LLM parameters or model version (e.g. a :ModelRun node). Then Cypher queries can traverse backward: for a given LLM response, retrieve all (:Answer)-[:BASED_ON]->(:Snippet)-[:IN_DOC]->(:Document) etc.

Example lineage queries:

// Trace a lineage from an output back to sources
MATCH (ans:Answer {id:$ansId})-[:BASED_ON]->(s:Snippet)-[:IN_DOC]->(d:Document)
RETURN d.title, s.text;

// Find all processes that touched a particular dataset
MATCH (asset:DataAsset {name:$name})<-[:CREATES]-(p:Process)
RETURN p.name, p.runDate;

Such graph lineage aids debugging and compliance. Studies show graph databases are an effective way to store ETL lineage because they naturally model transformations as edges between nodes.

Embeddings Storage and Similarity Search Integration

As noted, embed LLM outputs (vectors) in the graph. Key steps:

1. Generation: Use an LLM (OpenAI, SentenceTransformers, etc.) to compute embeddings for texts (documents, chat messages, entities). Store each as a property, e.g. :Entity {embedding: [float,…]} or :Message {embedding: …}.
2. Indexing: Create a VECTOR index on that property. The HNSW algorithm in Lucene powers approximate nearest neighbors. Example: CREATE VECTOR INDEX entVec ON (e:Entity) ON (e.embedding) OPTIONS {indexConfig:{vector.dimensions:768}}.
3. Vector queries: As above, use CALL db.index.vector.queryNodes or relationships analog queryRels. Combine with graph filters when needed. For hybrid queries:

   // Find top-k similar entities in a subgraph
   CALL db.index.vector.queryNodes('entVec', 5, $queryVec) YIELD node AS e, score
   WHERE (e)-[:HAS_TAG]->(:Tag {name:"finance"})
   RETURN e.name, score ORDER BY score DESC;
   

4. Relevance scoring: Neo4j returns a score (float) from the index (higher means more similar for cosine). You can convert or threshold it as needed.
5. Embeddings dimension: Typical text models yield 256–3072 dims. Higher dims improve quality but increase index size and compute. Tune ef_construction and M (HNSW params) for balance between index build time and query accuracy.
6. Storage format: Using Neo4j 5+ you can store vectors in the native VECTOR type for memory efficiency. Otherwise use a list of floats.

Integration example: LangChain’s Neo4jVectorStore can automatically index embeddings on ingest. Neo4j’s Graph Data Science library also offers graph-embedding algorithms, but for pure retrieval we rely on Cypher-based vector indexes.

Integration with LLM Pipelines

Neo4j fits into LLM systems via connectors and query patterns:

• GraphQL / Cypher APIs: Expose Neo4j via GraphQL (Apollo or Neo4j GraphQL library) or use the Bolt driver from Python/Node. LLM agent frameworks (LangChain, LlamaIndex, OpenAI Agents, etc.) often have modules to call Cypher. For instance, LangChain’s Neo4jRetriever can take a question and return subgraph context by template Cypher queries.
• Chains and Pipelines: In a RAG pipeline, use a Retriever step to get graph context (could be a Cypher query chain) before calling LLMChain. For example, GraphCypherQAChain in LangChain first executes a Cypher query (provided or learned) to retrieve relevant triples, then feeds them into the LLM. Neo4j’s GraphRAG Python library illustrates this flow.
• Prompt filling: Pull data from Neo4j to fill LLM prompts (e.g. retrieve entity properties and inject into a template). This can use Cypher RETURN to fetch text snippets, then python string-format into a prompt.
• APIs & Plugins: For example, if using OpenAI’s neo4j plugin or building a custom API, ensure only allow safe queries (avoid writing uncontrolled Cypher via LLM).

Integration often requires orchestration: diagrammatically:

flowchart LR
    User --> Preprocess[Preprocess Query];
    Preprocess --> Neo4jQuery[Cypher/VectSearch];
    Neo4jQuery --> Context[Compose Context];
    Context --> LLM[LLM API];
    LLM --> Postprocess[Generate Answer];
    Postprocess --> User;

In practice, a tool like PydanticAI or Neo4j-AuraAgent can handle these steps, managing the Bolt session and query translations.

Caching and Denormalization Strategies

Graphs can be denormalized or cached to speed recurrent queries:

• Precomputed relationships: For common multi-hop patterns, maintain shortcut edges. E.g. if you often query “Who are these user’s mutual colleagues?”, you might cache a direct :MUTUAL_COLLEAGUES edge updated nightly.
• Flattened properties: If a node is deep in the graph but frequently queried, you might pull some of its key attributes up. For example, denormalize an organization’s industry code onto :Employee if often filtering by it, to avoid an extra hop.
• Materialized subgraphs: Regularly extract and store summary nodes. E.g., if weekly analytics uses aggregated counts of relationships, compute those and store in summary nodes to avoid runtime aggregation.
• Result caching: Use Neo4j’s query result cache (Enterprise) or external caches (Redis) for very hot read queries. For example, if a certain KG subquery is run often, cache its result JSON for 5 minutes.
• APOC triggers: Use APOC triggers to maintain derived data. For instance, automatically add/remove edges to a “CurrentStatus” node on write events.
  These strategies trade more storage and write complexity for faster read performance. They are particularly useful in LLM apps where response latency is critical.

Monitoring and Benchmarking

Monitor database health and query performance using Neo4j’s built-in tools and metrics:

• Built-in metrics: Configure Neo4j metrics (via JMX or Micrometer) for key stats: transactions per second, open connections, page cache hit ratio, memory pool usage, GC activity. Neo4j 5 logs essential metrics as JSON if enabled.
• Query monitoring: Use CALL dbms.listQueries() to see running queries, and CALL dbms.listTransactions() for open transactions. The debug.log records slow queries (threshold configurable). Regularly run EXPLAIN/PROFILE on your Cypher to check for unintended scans.
• Schema inspection: Periodically check CALL db.indexes() and CALL db.constraints() to verify all expected indexes exist and are online. Also use MATCH (n) RETURN labels(n), count(*) to gauge label cardinalities and detect imbalances.
• Benchmarking: For write-heavy scenarios, measure throughput with neo4j-admin bulk-insert or query loaders like YCSB. For read loads, test your most common Cyphers under realistic concurrency. Track 95th percentile latencies.
• Alerting: Set alerts on error logs, low pagecache hit ratio (<95%), or long GC pauses. On cloud, use managed metrics from Aura or integrations (Datadog, Prometheus).

No specific citation is used here, but these are standard practices. For example, Neo4j Ops Guide details metrics collection and slow query logs.

Schema Migration and Versioning

When evolving a graph schema, follow a careful approach:

1. Backward-compatible changes: If adding fields or labels, you can deploy migrations live. For example, to add a new property: MATCH (p:Person) SET p:newProp = defaultValue;. Adding a label: SET n:NewLabel.
2. Step-wise migrations: For major changes (e.g. splitting a label into two), use a transitional phase. Example:

   // Phase 1: copy data to new label
   MATCH (n:OldLabel) 
   CREATE (m:NewLabel) SET m = n;
   // establish relationships from old to new as needed
   MATCH (m:NewLabel) WHERE NOT EXISTS((:OldLabel)-[]->(m))
   CREATE (:OldLabel)-[:COPIED]->(m);
   // Phase 2: switch reads to NewLabel, update writes.
   // Phase 3: remove OldLabel nodes once safe.
   

3. Versioning keys: If node identity changes, maintain an “id” property and use MERGE to avoid duplicates. Utilize MERGE or uniqueness constraints to de-duplicate.
4. Schema version flags: Store a version property on global nodes or metadata node so the application knows which schema version is active.
5. Sample migration steps for LLM context: If you want to add vector search to existing documents: (a) write a script to compute embeddings for all existing docs; (b) add a new property embedding on nodes; (c) create the vector index; (d) switch queries to use the index.

Always test migrations on a staging copy of the database (using neo4j-admin dump/load or in Neo4j Sandbox) to validate before production. Keep backups at each step.

Key Attributes and Dimensions to Consider

When designing the schema, explicitly consider these factors:

• Query Patterns: Which Cypher patterns (depth of traversal, filters, joins) will be common?
• Data Cardinality: Number of nodes per label, expected relationship counts, fan-out.
• Update Frequency: Read-heavy vs write-heavy workloads; batch vs streaming ingestion.
• Latency Requirements: Real-time interactive (sub-second) vs asynchronous. LLM user queries often need low latency.
• Dataset Size: Total nodes/edges; will it fit on one cluster? Multi-petabyte graphs may need sharding/fabric.
• Embedding Dimensions: Typical LLM text embeddings are 256–3072 floats; higher dims give better accuracy but increase index memory and CPU cost.
• Vector Index Tech: The vector index uses HNSW. Configure M (neighbors per node) and ef_construction based on dim and recall needs (default is M=16, ef=100).
• Throughput vs Accuracy: For vector search, tuning these parameters trades off query speed vs retrieval recall. For example, higher ef improves recall but slows index building and increases memory.
• Consistency Needs: If using clusters, decide on causal consistency or relaxed replication.

列出关键设计属性：查询模式、节点度/基数、读写比、延迟要求、数据规模、嵌入维度、向量索引算法等。这些维度帮助选择恰当的模式。例如，如果查询多为深度遍历，就需要优化关系索引；如果数据量极大，则可能需要考虑分库或使用 Fabric；高维向量检索需要预留足够的内存并调整 HNSW 参数（vector.dimensions, ef_construction, M）来平衡精度和性能。

Checklist and Design Rules

• Plan from Queries: Start by listing the most important LLM use cases (e.g. “find relevant document by keyword + entity filtering”) and sketch Cypher queries. Design the graph to make those efficient.
• Label Uniqueness: Every node type representing real-world entities should have a unique identifier and constraint (e.g. :Customer(customerId) must be unique).
• Shared Concepts as Nodes: Data used by multiple entities (locations, categories, tags) should be nodes, not repeated properties.
• Don’t Over-Index: Only index properties used in queries. Each index/constraint adds write overhead.
• Balance Depth: Avoid excessively deep inheritance of labels or overly long relationship chains if possible; Neo4j queries become slower with very long paths. Denormalize where appropriate.
• Temporal Modeling: If time ranges or history queries are needed, use intermediate time/event nodes instead of flat properties. Use datetime() properties for current timestamps.
• Security by Label: Tag sensitive data with specific labels and restrict them via roles. Maintain a “System” or “Admin” role that can access everything.
• Versioning of Schema: Maintain backward-compatibility during migrations. Use “v2” labels or properties alongside old ones until clients switch.

示例检查表:

• Is each high-level entity a node label (with unique key)?
• Are many-to-many relationships explicit via relationships (not via property lists)?
• Have you indexed all filter/join properties?
• Are properties named consistently (camelCase)? Are labels clear?
• Do you foresee heavy writes that an index might slow down?
• Have you represented hierarchical or categorical data as nodes for easy traversal?
• Are TTL or prune strategies needed for old data in conversation logs?

Following these guidelines (and adjusting as metrics indicate) will yield a schema that balances Neo4j’s strengths for your LLM workload.

例: Schema 迁移
当需要替换或拆分标签时，可按以下步骤：首先保持旧结构，同时创建新结构：

// 复制旧节点到新节点(示例: Person->User)
MATCH (p:Person) 
CREATE (u:User)
SET u = p;  
// 后续调整关系和标签
MATCH (u:User) REMOVE u:Person;
// 使用 NewSchema 后，清理旧数据
MATCH (n:Person) DELETE n;

这个三阶段策略允许客户端按需切换到新模型，最后弃用旧模型。

Each section above is supported by official Neo4j documentation, community best-practices, and Neo4j Labs resources as cited.