Federated Queries, Data Locality, Cross-Graph Joins/Traversal Constraints, and Latency Tradeoffs

An AtlasMart order-details endpoint now needs the Order graph plus Customer and Catalog facts. In a single graph this is one traversal; in a federated design it is a sequence of constituent reads and value joins. The danger is to celebrate a single logical Cypher query while hiding three physical execution sites, network round trips, result transfer and failure dependencies. This lesson makes those costs explicit.

Learning outcomes

Reproducible Chapter 19 lab baseline

1. Compare three query shapes

2. Data locality starts with selectivity

The Orders constituent should find one order and return only its customer/product keys and commercial line facts. Customer should fetch one customer by constrained ID. Catalog should batch the product IDs. Returning every product to the root scope and filtering there would convert an index-selective local operation into a network/result-volume problem.

from neo4j import GraphDatabase
from time import perf_counter

AUTH = ("neo4j", "atlasmart-course-2026")
drivers = {
    "orders": GraphDatabase.driver("bolt://127.0.0.1:7768", auth=AUTH),
    "customers": GraphDatabase.driver("bolt://127.0.0.1:7769", auth=AUTH),
    "catalog": GraphDatabase.driver("bolt://127.0.0.1:7767", auth=AUTH),
}

def run(domain, query, **params):
    t0 = perf_counter()
    with drivers[domain].session(database="neo4j") as s:
        rows = [r.data() for r in s.run(query, **params)]
    return rows, perf_counter() - t0

order_rows, t_orders = run("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
ORDER BY productId
""", orderId="O-1901")

customer_id = order_rows[0]["customerId"]
product_ids = [r["productId"] for r in order_rows]
customer_rows, t_customers = run("customers", """
MATCH (c:Customer {customerId:$id})
RETURN c.customerId AS customerId, c.name AS customerName, c.tier AS tier
""", id=customer_id)
product_rows, t_catalog = run("catalog", """
MATCH (p:Product) WHERE p.productId IN $ids
RETURN p.productId AS productId, p.name AS productName, p.price AS currentPrice
""", ids=product_ids)

products = {p["productId"]: p for p in product_rows}
result = {
    "orderId": order_rows[0]["orderId"],
    "status": order_rows[0]["status"],
    "customer": customer_rows[0],
    "lines": [{**r, **products[r["productId"]]} for r in order_rows],
}
print(result)
print({"orders_s": t_orders, "customers_s": t_customers, "catalog_s": t_catalog})
for d in drivers.values(): d.close()

3. Proxy identity replaces impossible cross-graph relationships

4. One logical query still has physical boundaries

In the optional composite query, each CALL scope executes against a selected graph. Root-level scalar/value operations combine returned data. If a constituent is remote, those operations incur remote connectivity and can fail independently. Location transparency should make topology evolvable, not make operators blind to topology.

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. Edge case: multi-graph writes are not distributed ACID

CYPHER 25
// OPTIONAL Enterprise composite example: this must fail because one transaction writes two constituents.
CALL {
  USE atlasmart.orders
  CREATE (:AuditMarker {id:'two-write-test-orders'})
  RETURN 1 AS x
}
CALL {
  USE atlasmart.catalog
  WITH x
  CREATE (:AuditMarker {id:'two-write-test-catalog'})
  RETURN 1 AS y
}
RETURN x, y;
// Expected mechanism: writing to more than one database per transaction is not allowed.

6. Failure injection: one domain unavailable

# Keep Orders and Customers running; stop only Catalog.
docker stop atlasmart-ch19-catalog
# Run the free federation script: Orders/Customer may succeed; Catalog lookup must fail/timeout per driver settings.
# Record error class and elapsed time. Then restore Catalog.
docker start atlasmart-ch19-catalog
# Re-run and verify the O-1901 result is complete again.

7. When not to federate at request time

Production judgment

Summary and next step

Federation is now a measurable execution plan across data domains, not a magical graph traversal. Lesson 4 turns from mechanics to governance: who owns identity, reference data, schema changes, access, backups and compatibility as those graphs evolve independently.

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.