Composite Database Concepts, Constituents, Querying Across Graphs, and Location Transparency

AtlasMart’s application-side federation works, but every service must know three Bolt addresses and orchestrate the same lookup sequence. Enterprise architects propose a composite database named atlasmart so callers can query logical constituents atlasmart.orders, atlasmart.customers, and atlasmart.catalog. The important question is not “how do I create it?” but “what semantics change, and what stays owned by the constituents?”

Learning outcomes

Reproducible Chapter 19 lab baseline

1. Composite anatomy

2. Optional licensed Enterprise setup

These commands are intentionally separated from the mandatory Community lab. They require self-managed Enterprise. Administration commands are routed to the system database over Bolt; the actual AtlasMart fixture would then be loaded into the three target standard databases just as it was into the three Community instances.

// OPTIONAL: self-managed Neo4j Enterprise 2026.07.1; run administration against system.
CYPHER 25
CREATE DATABASE `atlasmart-catalog` IF NOT EXISTS;
CREATE DATABASE `atlasmart-orders` IF NOT EXISTS;
CREATE DATABASE `atlasmart-customers` IF NOT EXISTS;
CREATE COMPOSITE DATABASE atlasmart IF NOT EXISTS DEFAULT LANGUAGE CYPHER 25;
CREATE ALIAS atlasmart.catalog IF NOT EXISTS FOR DATABASE `atlasmart-catalog`;
CREATE ALIAS atlasmart.orders IF NOT EXISTS FOR DATABASE `atlasmart-orders`;
CREATE ALIAS atlasmart.customers IF NOT EXISTS FOR DATABASE `atlasmart-customers`;

SHOW DATABASE atlasmart YIELD name, type, currentStatus, constituents, defaultLanguage;
SHOW ALIASES FOR DATABASE
YIELD name, composite, database, location, url, credentials, user
WHERE composite = 'atlasmart'
RETURN * ORDER BY name;

3. Location transparency is naming transparency, not latency transparency

A constituent alias can target a local standard database in the same DBMS or a remote standard database over a Neo4j driver connection. Callers can keep the logical alias stable while the target changes, but the physical location still determines network latency, TLS/authentication, remote capacity, failure modes and billing/egress.

// OPTIONAL remote constituent example. Use a secret-management process; do not commit passwords.
CYPHER 25
CREATE ALIAS atlasmart.catalogRemote
FOR DATABASE neo4j
AT 'neo4j+s://catalog.example.invalid:7687'
USER atlasmart_federation
PASSWORD 'example_secret';

SHOW ALIAS atlasmart.catalogRemote FOR DATABASE
YIELD name, composite, database, location, url, credentials, user;

4. Query graph scopes with USE and CALL

A composite query can keep the root scope non-graph-accessing while child CALL {} scopes select constituents with USE. Variables crossing a subquery boundary are scalar/map/list values—not magic edges between graphs. The example joins through customerId and productId.

CYPHER 25
CALL {
  USE atlasmart.orders
  MATCH (o:Order {orderId:$orderId})-[:PLACED_BY]->(cr:CustomerRef)
  MATCH (o)-[li:CONTAINS]->(pr:ProductRef)
  RETURN o.orderId AS orderId, o.status AS status,
         cr.customerId AS customerId, pr.productId AS productId,
         li.quantity AS quantity, li.unitPrice AS unitPrice
}
CALL {
  USE atlasmart.customers
  WITH customerId
  MATCH (c:Customer {customerId:customerId})
  RETURN c.name AS customerName, c.tier AS tier
}
CALL {
  USE atlasmart.catalog
  WITH productId
  MATCH (p:Product {productId:productId})
  RETURN p.name AS productName, p.price AS currentPrice
}
RETURN orderId, status, customerId, customerName, tier,
       productId, productName, quantity, unitPrice, currentPrice
ORDER BY productId;

5. Graph-selection limitations matter

6. Cypher/version compatibility is an intersection

The current composite can have a default language such as Cypher 25. However, a remote constituent may run another compatible Neo4j release. Neo4j does not guarantee arbitrary mixed-version composite compatibility: newly added behavior can only be used when supported by the composite DBMS and the constituents involved. Treat a version matrix as deployment evidence, not an assumption.

7. Security and backup stay constituent-aware

// OPTIONAL Enterprise example; exact role naming is an AtlasMart design choice.
CYPHER 25
CREATE ROLE atlasmart_reader IF NOT EXISTS;
GRANT ACCESS ON DATABASE atlasmart TO atlasmart_reader;
GRANT ACCESS ON DATABASE `atlasmart-catalog` TO atlasmart_reader;
GRANT ACCESS ON DATABASE `atlasmart-orders` TO atlasmart_reader;
GRANT ACCESS ON DATABASE `atlasmart-customers` TO atlasmart_reader;
GRANT MATCH {*} ON GRAPH `atlasmart-catalog` TO atlasmart_reader;
GRANT MATCH {*} ON GRAPH `atlasmart-orders` TO atlasmart_reader;
GRANT MATCH {*} ON GRAPH `atlasmart-customers` TO atlasmart_reader;
SHOW ROLE atlasmart_reader PRIVILEGES;

8. Wrong model: “the composite contains the data”

If AtlasMart only exports or backs up the composite namespace and ignores target databases, recovery will have metadata pointing at missing/unrecovered data. Repair the mental model by producing a constituent inventory: owner, target, location, version, backup policy, RPO/RTO, security owner, and dependency SLO for every alias.

Production judgment

Summary and next step

A composite makes graph location selectable inside one Cypher request, but domain data, security, schema, version and recovery remain constituent responsibilities. Lesson 3 examines the performance and query-shape consequences once federated reads cross those boundaries.

Authoritative references

• Current Neo4j versions — Current self-managed release 2026.07.1 and 5.26.30 LTS snapshot.
• Database administration — Current database/transaction-domain model and the one-standard-database Community versus multi-database Enterprise boundary.
• Create standard databases — Enterprise-only self-managed CREATE DATABASE semantics and system-database administration.
• Show databases — SHOW DATABASES fields including type, role, writer, status, aliases and constituents.
• Composite database concepts — Enterprise-only, unavailable-on-Aura composite semantics, local/remote constituents, compatibility, transactions and proxy-node federation.
• Create composite databases — CREATE COMPOSITE DATABASE and current default Cypher language behavior.
• Query composite databases — USE/CALL graph selection, graph functions, update restrictions, root-scope limits and runtime behavior.
• Composite aliases — Local and remote constituent aliases, SHOW ALIASES evidence, namespace rules and alias limitations.
• Standard aliases — Local/remote alias behavior, credentials, access visibility and current OIDC-forwarding option for remote aliases.
• Composite RBAC — Access must be granted to the composite and constituents; remote constituents enforce remote-user RBAC.
• Composite tutorial — Official federation/sharding example and proxy-node model.
• Database alias command syntax — Current SHOW/CREATE/ALTER alias command forms.
• Cypher USE clause — Current graph-selection clause semantics for composite/federated queries.
• Python driver manual — Official driver lifecycle, sessions, parameters, database selection and application-side orchestration.
• Backup and restore — Operational reminder that constituent data stores—not a composite alias layer—are the recovery units.