![\"grafeo-ogm](\"./assets/logo.jpg\"){kind=logo}
\n\n \n
A type-safe Object-Graph Mapper for Neo4j, driven by GraphQL SDL.
\n\n[](https://www.npmjs.com/package/grafeo-ogm)\n[](LICENSE)\n[](https://www.typescriptlang.org/)\n[](https://nodejs.org/)\n[](https://neo4j.com/)\n\nDefine your graph model once in `.graphql` and get fully typed CRUD operations, optimized Cypher compilation, and TypeScript code generation -- no boilerplate, no Cartesian products, no injection vulnerabilities.\n\n> **grafeo** (*/ˈɡra.fe.o/*) -- from Greek *grapho* (write, draw), the root behind \"graph.\" Because your data model should be written once and understood everywhere.\n\n---\n\n## Table of Contents\n\n- [Why grafeo-ogm?](#why-grafeo-ogm)\n- [Common Use Cases](#common-use-cases)\n- [Quick Start](#quick-start)\n- [CLI](#cli)\n- [Features Overview](#features-overview)\n- [Schema Definition](#schema-definition)\n- [Query API](#query-api)\n- [Mutation API](#mutation-api)\n- [Advanced Features](#advanced-features)\n- [Vector Search](#vector-search)\n- [Type Generation](#type-generation)\n- [Testing Utilities](#testing-utilities)\n- [Security](#security)\n- [Migration from @neo4j/graphql-ogm](#migration-from-neo4jgraphql-ogm)\n- [Comparisons](#comparisons)\n- [FAQ](#faq)\n- [API Reference](#api-reference)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Why grafeo-ogm?\n\nThe official [`@neo4j/graphql-ogm`](https://github.com/neo4j/graphql/tree/changeset-release/lts/packages/ogm/) was deprecated with no development path beyond v5. grafeo-ogm is a community continuation that maintains **full backward compatibility** while addressing five fundamental problems the original library could never patch:\n\n| Problem | @neo4j/graphql-ogm | grafeo-ogm |\n|---|---|---|\n| **Deprecation** | Abandoned by Neo4j; no path beyond v5 | Actively maintained; evolves with your schema |\n| **Query efficiency** | `OPTIONAL MATCH` chains that create Cartesian products across relationships | Pattern comprehensions scoped to matched nodes -- O(1) rows per node regardless of relationship count |\n| **Security** | No identifier validation, no injection prevention, no parameterization enforcement | 7 security controls: parameterization, identifier regex, label validation, prototype pollution prevention, Lucene escaping, depth limiting, sort direction validation |\n| **Type generation** | Monolithic multi-MB output; required a running Neo4j driver at build time | Modular emitter pipeline; no driver needed at build time; output sized proportionally to schema |\n| **Customization** | No union type support, no subquery isolation, no edge property queries | Full union/interface support, `CALL` subquery isolation for mutations, connection fields with edge properties |\n\n### Pattern Comprehensions vs. OPTIONAL MATCH\n\nThe most impactful difference is how relationships are queried. The old OGM chains `OPTIONAL MATCH` clauses that multiply intermediate rows:\n\n```\n10 variants x 5 categories x 3 tags = 150 intermediate rows per node\nQuery 200 nodes = 30,000 rows processed\n```\n\ngrafeo-ogm uses pattern comprehensions that evaluate each relationship independently inside the RETURN projection:\n\n```cypher\nRETURN n {\n .id, .name,\n variants: [(n)-[:HAS_VARIANT]->(n0:Variant) | n0 { .id, .value }],\n status: head([(n)-[:HAS_STATUS]->(n0:Status) | n0 { .id, .name }])\n}\n-- Always 1 row per node. Adding relationships adds list expressions, never rows.\n```\n\n| Query | Old OGM (rows) | grafeo-ogm (rows) | Reduction |\n|---|---|---|---|\n| 1 node, 10+5+3 rels | 150 | 1 | 150x |\n| 50 nodes, same rels | 7,500 | 50 | 150x |\n| 200 nodes, same rels | 30,000 | 200 | 150x |\n\n### CALL Subquery Isolation\n\nMutations with multiple connect/disconnect operations are wrapped in `CALL { ... }` subqueries. Each operation runs in isolation -- no Cartesian products, no duplicate relationships, no silently dropped operations when a disconnect target doesn't exist.\n\n---\n\n## Common Use Cases\n\ngrafeo-ogm fits any TypeScript application backed by Neo4j. Common patterns it solves cleanly:\n\n**Knowledge graphs & semantic search**\nModel entities, properties, and relationships in GraphQL SDL. Combine relationship traversal with `@fulltext` indexes for hybrid keyword + structural queries (e.g. \"find all `Document` nodes mentioning *X* that are linked to active `Project` nodes owned by team *Y*\").\n\n**Social graphs & follower networks**\nMulti-hop traversals with relationship properties (e.g. `since`, `weight`) become typed `*Connection` queries with sortable edges. No raw Cypher needed for \"mutual followers\", \"friends of friends\", or \"shortest path between users\".\n\n**Recommendation engines**\nExpress collaborative filtering as relationship queries: \"users who bought *X* also bought *Y*\" becomes a typed `connect`/`*Connection` selection sorted by edge frequency or recency. Use `@cypher` directives for custom scoring algorithms in pure Cypher.\n\n**Permission & policy graphs (RBAC / ReBAC)**\nModel `User → ROLE → Permission` chains as native relationships. Filter queries with relationship existence (`Connection_SOME`) instead of joining tables. Multi-label nodes (`@node(labels: [...])`) handle hierarchical roles cleanly.\n\n**Master data management & data lineage**\nTrack provenance, transformations, and dependencies between datasets. Interface types (`InterfaceModel`) let you query polymorphic entities (any `Asset`, any `Pipeline`) without losing type safety.\n\n**Fraud detection & anti-money laundering**\nExpress patterns like \"transaction chains > 3 hops between sanctioned accounts\" using relationship quantifiers (`_SOME`, `_NONE`, `_ALL`). The mutation compiler's `CALL` subquery isolation prevents pipeline pollution when batching graph updates.\n\n**Content management with rich relationships**\nArticles, authors, tags, categories, and comments — all with edge metadata (timestamps, ordering, visibility). Connection edges with `orderBy: { edge: { ... } }` give you Prisma-style sortable joins on relationship properties.\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# npm\nnpm install grafeo-ogm neo4j-driver graphql\n\n# pnpm\npnpm add grafeo-ogm neo4j-driver graphql\n\n# yarn\nyarn add grafeo-ogm neo4j-driver graphql\n```\n\n### 1. Define your schema\n\n> **Fastest start:** `npx grafeo init` scaffolds a starter `schema.graphql` + `grafeo.config.ts` for you — and auto-detects an existing setup. See [CLI → `grafeo init`](#cli). Prefer to do it by hand? Define a `schema.graphql`:\n\n```graphql\n# schema.graphql\ntype Book @node\n @fulltext(indexes: [{ name: \"BookSearch\", fields: [\"title\"] }]) {\n id: ID! @id @unique\n title: String!\n isbn: String @unique\n published: DateTime\n author: Author! @relationship(type: \"WRITTEN_BY\", direction: OUT)\n categories: [Category!]! @relationship(type: \"IN_CATEGORY\", direction: OUT)\n}\n\ntype Author @node {\n id: ID! @id @unique\n name: String!\n books: [Book!]! @relationship(type: \"WRITTEN_BY\", direction: IN)\n}\n\ntype Category @node {\n id: ID! @id @unique\n name: String!\n}\n```\n\n### 2. Generate types (recommended)\n\n```bash\nnpx grafeo generate\n```\n\nThis wraps `generateTypes()` to emit typed models from your SDL — wire them in with `new OGM