For decades, developers have faced a frustrating trade-off: choose the flexibility and scalability of a document database, or choose the rich relationship modeling of a graph database. To build applications that required both – like fraud detection systems, recommendation engines, or complex supply chain trackers – you often had to manage two separate systems, dealing with the inevitable headaches of data synchronization, latency, and operational complexity.
But agentic applications demand more. They need to traverse complex relationships and manage rich, hierarchical data at speed.
We are excited to introduce a graph model in Couchbase to eliminate this dichotomy. By layering a graph model directly on top of our document store, we enable you to query your existing JSON data as a graph without moving it, duplicating it, or managing a separate database. This is not a “bolted-on” sidecar; it is a native integration that allows you to keep your existing SQL++, but use graph clauses for pattern matching and relationship traversal – all within a single, high-performance platform.
In this post, we present the architecture of this new model, explore how it leverages the SQL++ language you already know, and show you how to build relationship-heavy applications with unprecedented simplicity and scale.
The Couchbase Graph Model extends SQL++ by introducing 1) a “CREATE GRAPH” statement that defines a virtual property graph over your existing dataset and 2) a “MATCH” term in SQL++’s existing FromClause. “MATCH” enables query authors to specify navigational query patterns using the same syntax found in popular graph query languages like Cypher (Neo4j) and SQL/PGQ 2023. What separates the Couchbase Graph Model from the “bolted-on sidecar” graph extensions of other competitors is our synergistic interplay between documents, vertices, and edges. For example, Couchbase Graph Model queries can explicitly JOIN query pattern vertices and Couchbase collections/subqueries. Consequently, a Couchbase user can express powerful concepts (e.g., hypergraphs, hypernode graphs, etc.) that will more accurately model an organization’s data model.
Behind the scenes, Couchbase rewrites the graph query patterns into a series of JOINs and recursive CTEs that operate over the vertex and edge queries of the “CREATE GRAPH” definition. Once rewritten, the query is optimized and executed in partitioned-parallel using the same services (Query Service, Index Service, Search Service, etc.) your existing SQL++ queries use. Due to the virtual nature of this graph, users do not need to wait for their graph to be built – and can get to their insights faster. By combining MATCH with existing SQL++ clauses, Couchbase users can “keep” their JSON and graph it too.
Below are the use cases enabled by graph model support in Couchbase:
- 360-degree patient care: Healthcare data is notoriously messy. A patient’s record is a “document” (name, DOB, address), but their medical history is a complex web of relationships: doctors visited, prescriptions filled, lab results, insurance claims, and family history. A doctor can now ask, “Show me all patients diagnosed with Type 2 Diabetes who have been prescribed Metformin by Dr. Smith but haven’t visited the clinic in 6 months,” as a graph pattern.
- Fraud detection: Fraudsters operate in networks. They share addresses, phone numbers, or devices to create synthetic identities. Detecting this requires spotting the connections between seemingly unrelated accounts. An analyst can now detect a fraud ring with a simply query: “Find all users who logged in from the same IP address within 10 minutes of each other and initiated transactions to the same destination account.”
- Recommendation engines: “People who bought X also bought Y” is simple. But “People like you (same demographics) who bought X and reviewed it positively also bought Y” is a complex graph problem. An e-commerce site can now serve hyper-personalized recommendations: “Recommend products purchased by other users who also bought the same ‘Hiking Boots’ as the current user, but filter for products in the ‘Camping Gear’ category.”
- Supply chain visibility: A modern supply chain is a deep hierarchy. A car contains an engine, which includes a piston, which contains a specific alloy. If a batch of alloy is defective, you need to know exactly which cars to recall. A manufacturer can trace a defect instantly: “Find every finished ‘Model X’ car that contains a ‘Piston Ring’ supplied by ‘Acme Corp’ in ‘Batch #99’.” This traversal (CONTAINS -> CONTAINS -> CONTAINS) is more intuitive to express as a path in a graph model as opposed to a query using recursive CTEs.
The Graph Model delivers a significant step forward in making relationship-rich data accessible directly within Couchbase. By bridging the gap between JSON documents and graph structures, you can now uncover hidden patterns and answer complex questions without the overhead of a separate graph database.
Ready to try it out? We’ve prepared a complete, hands-on notebook that walks you through creating the dog_research_graph, populating it with sample data, and running powerful graph queries to answer questions such as, “Find all dog food products that contain ingredients that trigger allergies in Golden Retrievers.” Download the Colab notebook and start exploring the potential of your data today.
Looking ahead, we are actively working on integrating this model with GraphRAG and Agent Memory. This will allow you to combine the structural precision of graph queries with the semantic power of vector search, enabling LLMs to provide even more accurate, context-aware answers. Stay tuned for future updates as we continue to expand the boundaries of what’s possible with your data.
