Subchapter 67.14
references/use-cases.mdMarkdown20 KBView on GitHub
Concrete, solution-oriented patterns for the most common Neptune workloads. Each pattern includes: natural language triggers, graph model, sample queries, and getting-started path.
See also: data-modeling.md for modeling guidance, for query syntax details.
⚠️ Code style note: Gremlin queries use Groovy def syntax (Console).
For Python driver, extract the traversal string and pass to client.submit().
openCypher queries work directly via the Neptune HTTP API or boto3 SDK.
Customer says: “We need a single view of each customer across all our systems”, “unify customer profiles”, “merge duplicate accounts”, “360-degree customer view”, “identity resolution across channels”
(Customer) -[HAS_IDENTIFIER]→ (Identifier {type: 'email', value: '...'})
(Customer) -[HAS_IDENTIFIER]→ (Identifier {type: 'phone', value: '...'})
(Customer) -[PLACED]→ (Order) -[CONTAINS]→ (Product)
(Customer) -[OPENED]→ (SupportTicket)
(Customer) -[MERGED_INTO]→ (Customer)// Resolve all profiles sharing any identifier with a customer
MATCH (c:Customer {id: $customerId})-[:HAS_IDENTIFIER]->(id)
<-[:HAS_IDENTIFIER]-(other:Customer)
WHERE other.id <> $customerId
RETURN DISTINCT other.id, other.name, id.type, id.value
// Full 360 view: orders, tickets, identifiers
MATCH (c:Customer {id: $customerId})
OPTIONAL MATCH (c)-[:PLACED]->(o:Order)
OPTIONAL MATCH (c)-[:OPENED]->(t:SupportTicket)
OPTIONAL MATCH (c)-[:HAS_IDENTIFIER]->(id)
RETURN c, collect(DISTINCT o) AS orders,
collect(DISTINCT t) AS tickets,
collect(DISTINCT id) AS identifiersBefore (relational): Multiple JOINs across siloed tables, brittle when new sources added. After (graph): Add new identifier types or data sources as new edges — no schema migration.
Getting started: decision-guide → data-modeling (identity pattern) → querying
Customer says: “detect fraud rings”, “find connected suspicious accounts”, “shared phone/email/device analysis”, “money mule detection”, “transaction chain analysis”
(Account) -[USES]→ (Email | Phone | Device)
(Account) -[MADE]→ (Transaction) -[TO]→ (Account)
(Account) -[LOCATED_AT]→ (IPAddress)// Find accounts sharing identifiers with a flagged account
g.V().has('Account', 'id', flaggedId).as('start')
.out('USES').in('USES')
.where(neq('start'))
.dedup()
.values('id')
// Transaction chains (money mule detection)
g.V().has('Account', 'id', seedId)
.repeat(outE('MADE').has('amount', gt(1000)).inV().simplePath())
.times(4).path()
// Risk score: count shared identifiers with known fraudsters
g.V().has('Account', 'id', accountId)
.out('USES').in('USES')
.has('id', within(knownFraudIds))
.dedup().count()Before: SQL self-joins across tables, exponential complexity at 3+ hops. After: Native traversal, linear cost per hop, real-time ring detection.
Getting started: decision-guide → data-modeling (shared identity pattern) → querying
Customer says: “map service dependencies”, “blast radius analysis”, “what breaks if this service goes down”, “infrastructure topology”, “dependency graph”, “impact analysis for deployments”
(Service) -[DEPENDS_ON]→ (Service)
(Service) -[RUNS_ON]→ (Host | Container)
(Service) -[USES]→ (Database | Queue | Cache)
(Service) -[OWNED_BY]→ (Team)
(Host) -[IN]→ (AvailabilityZone) -[IN]→ (Region)// Blast radius: what depends on this service (recursively)?
MATCH path = (downstream)-[:DEPENDS_ON*1..5]->(s:Service {name: $serviceName})
RETURN DISTINCT downstream.name, length(path) AS depth
ORDER BY depth
// Single point of failure: services with only one dependency path
MATCH (s:Service)
WHERE size([(s)-[:DEPENDS_ON]->(dep) | dep]) = 1
RETURN s.name, [(s)-[:DEPENDS_ON]->(dep) | dep.name] AS singleDependency
// Impact of AZ failure
MATCH (h:Host)-[:IN]->(az:AvailabilityZone {name: $azName})
MATCH (svc:Service)-[:RUNS_ON]->(h)
RETURN svc.name, count(h) AS hostsInAZBefore: Spreadsheets or CMDBs with stale data, manual impact assessment. After: Real-time traversal of live dependency graph, automated blast radius.
Getting started: decision-guide → data-modeling (hierarchy pattern) → querying
Customer says: “who has access to what”, “permission inheritance”, “trace why a user can access this resource”, “RBAC graph”, “audit access paths”, “least privilege analysis”
(User) -[MEMBER_OF]→ (Group)
(Group) -[MEMBER_OF]→ (Group) // nested groups
(Group) -[HAS_ROLE]→ (Role)
(Role) -[GRANTS]→ (Permission)
(Permission) -[ON]→ (Resource)
(User) -[DIRECT_GRANT]→ (Permission) // exceptions// All permissions for a user (through group/role inheritance)
MATCH (u:User {id: $userId})-[:MEMBER_OF*1..5]->(g:Group)
-[:HAS_ROLE]->(r:Role)-[:GRANTS]->(p:Permission)-[:ON]->(res)
RETURN DISTINCT res.name, p.action, r.name AS via_role
UNION
MATCH (u:User {id: $userId})-[:DIRECT_GRANT]->(p:Permission)-[:ON]->(res)
RETURN DISTINCT res.name, p.action, 'direct' AS via_role
// Who can access a specific resource?
MATCH (p:Permission)-[:ON]->(res:Resource {name: $resourceName})
MATCH (p)<-[:GRANTS]-(r:Role)<-[:HAS_ROLE]-(g:Group)<-[:MEMBER_OF*1..5]-(u:User)
RETURN DISTINCT u.name, r.name AS role, g.name AS via_group
// Trace WHY a user has a permission (full path)
MATCH path = (u:User {id: $userId})-[:MEMBER_OF*1..5]->()
-[:HAS_ROLE]->()-[:GRANTS]->(p:Permission {action: $action})
-[:ON]->(res:Resource {name: $resource})
RETURN pathBefore: Recursive SQL CTEs across join tables, slow and hard to audit. After: Natural path traversal, full audit trail, real-time permission checks.
Getting started: decision-guide → data-modeling (hierarchy pattern) → querying
Customer says: “build a knowledge graph”, “connect entities across documents”, “improve RAG accuracy”, “entity relationships for search”, “semantic search with structure”
(Document) -[HAS_CHUNK]→ (Chunk {text, embedding})
(Chunk) -[MENTIONS]→ (Entity {name, type, embedding})
(Entity) -[RELATED_TO]→ (Entity)
(Chunk) -[NEXT]→ (Chunk)// Vector search + graph expansion (GraphRAG retrieval)
CALL neptune.algo.vectors.topKByEmbedding($queryEmbedding, {topK: 5})
YIELD node, score
WHERE 'Chunk' IN labels(node)
WITH node AS chunk, score
MATCH (chunk)-[:MENTIONS]->(e:Entity)-[:RELATED_TO]-(related)
RETURN chunk.text, score, collect(DISTINCT e.name) AS entities,
collect(DISTINCT related.name) AS related_entitiesBefore: Vector-only RAG misses cross-document relationships. After: Graph traversal expands context, entity-centric retrieval.
Getting started: analytics-vs-database → graphrag (full pipeline)
See graphrag.md for the complete implementation.
Customer says: “track products through supply chain”, “trace origin of components”, “recall impact analysis”, “supplier dependency”, “provenance tracking”, “which batches are affected”
(Supplier) -[SUPPLIES]→ (RawMaterial)
(RawMaterial) -[USED_IN]→ (Component)
(Component) -[ASSEMBLED_INTO]→ (Product)
(Product) -[SHIPPED_IN]→ (Batch {date, destination})
(Batch) -[DELIVERED_TO]→ (Warehouse | Customer)// Trace a product back to raw material suppliers
MATCH path = (p:Product {sku: $sku})<-[:ASSEMBLED_INTO]-(:Component)
<-[:USED_IN]-(:RawMaterial)<-[:SUPPLIES]-(s:Supplier)
RETURN s.name, [n IN nodes(path) | n.name] AS chain
// Recall impact: which customers received affected batches?
MATCH (mat:RawMaterial {id: $recalledMaterialId})-[:USED_IN]->(:Component)
-[:ASSEMBLED_INTO]->(:Product)-[:SHIPPED_IN]->(b:Batch)
-[:DELIVERED_TO]->(dest)
RETURN dest.name, b.date, count(*) AS affected_products
// Supplier risk: single-source components
MATCH (c:Component)<-[:USED_IN]-(rm:RawMaterial)<-[:SUPPLIES]-(s:Supplier)
WITH c, count(DISTINCT s) AS supplierCount
WHERE supplierCount = 1
RETURN c.name, supplierCountBefore: Multi-table JOINs across ERP systems, slow recall response. After: Instant upstream/downstream traversal, real-time recall impact.
Getting started: decision-guide → data-modeling → querying
Customer says: “agent needs to remember across sessions”, “long-term memory for LLM”, “persistent context for chatbot”, “knowledge accumulation”, “graph-based agent memory”
(Entity {name, type, confidence}) -[RELATED_TO]→ (Entity)
(Conversation {date, summary}) -[ABOUT]→ (Entity)
(Fact {content, confidence}) -[LEARNED_IN]→ (Conversation)// Recall everything about an entity
MATCH (e:Entity {name: $name})
OPTIONAL MATCH (e)-[r:RELATED_TO]-(related)
OPTIONAL MATCH (conv:Conversation)-[:ABOUT]->(e)
RETURN e, collect(DISTINCT {entity: related.name, rel: r.type}) AS relationships,
collect(DISTINCT {date: conv.date, summary: conv.summary}) AS conversations
// Semantic recall (vector similarity)
CALL neptune.algo.vectors.topKByEmbedding($queryEmbedding, {topK: 10})
YIELD node, score
RETURN node.name, node.type, node.description, scoreBefore: Flat conversation logs, no structural recall. After: Graph-based memory with relationship traversal + semantic search.
Getting started: analytics-vs-database → agentic-memory (full architecture)
See agentic-memory.md for the complete implementation.
Customer says: “semantic layer for AI agents”, “business ontology”, “encode business rules for agents”, “shared vocabulary across systems”, “agents need to understand our business logic”, “governed knowledge layer”, “enterprise knowledge graph for reasoning”, “ontology for agentic workflows”, “consistent business definitions”, “explainable AI decisions”
This pattern addresses the core challenge of scaling AI agents in enterprises: agents have no native understanding of an organization’s vocabulary, relationships, constraints, or compliance policies. A semantic layer encodes business meaning as a knowledge graph that agents can reason over, producing outcomes that are accurate, consistent, and explainable.
You can build a semantic layer with Neptune today using either RDF (for standards-based ontologies with OWL/RDFS reasoning) or property graphs (for application-driven entity-relationship models with openCypher queries).
// Business ontology layer
(BusinessEntity {name, definition}) -[HAS_ATTRIBUTE]→ (Attribute {name, type, rules})
(BusinessEntity) -[RELATES_TO {cardinality, rule}]→ (BusinessEntity)
(BusinessEntity) -[MAPPED_TO]→ (DataSource {system, table, field})
// Business rules and policies
(Rule {name, condition, action}) -[APPLIES_TO]→ (BusinessEntity)
(Policy {name, type}) -[CONSTRAINS]→ (BusinessEntity | Attribute)
(Policy) -[OWNED_BY]→ (Team)
// Governance and lineage
(Definition) -[APPROVED_BY]→ (Steward)
(Definition) -[VERSION {date, status}]→ (Definition)
(DataSource) -[FEEDS]→ (BusinessEntity)// Agent reasoning: resolve a business term to its definition and rules
MATCH (e:BusinessEntity {name: $term})
OPTIONAL MATCH (e)-[:HAS_ATTRIBUTE]->(attr)
OPTIONAL MATCH (r:Rule)-[:APPLIES_TO]->(e)
OPTIONAL MATCH (p:Policy)-[:CONSTRAINS]->(e)
RETURN e.name, e.definition,
collect(DISTINCT {attr: attr.name, type: attr.type}) AS attributes,
collect(DISTINCT {rule: r.name, condition: r.condition}) AS rules,
collect(DISTINCT {policy: p.name, type: p.type}) AS policies
// Trace data lineage: where does this business entity's data come from?
MATCH (e:BusinessEntity {name: $entityName})<-[:FEEDS]-(ds:DataSource)
RETURN ds.system, ds.table, ds.field
// Cross-domain entity resolution: find related entities across business domains
// (Neptune openCypher does not support shortestPath(); use a variable-length
// path and take min(length(path)) to approximate shortest distance.)
MATCH path = (e:BusinessEntity {name: $term})-[:RELATES_TO*1..3]-(related)
WITH related, min(length(path)) AS distance
RETURN DISTINCT related.name, related.definition, distance
ORDER BY distance
// Policy enforcement: check if an agent action is allowed
MATCH (e:BusinessEntity {name: $entityName})
MATCH (p:Policy)-[:CONSTRAINS]->(e)
WHERE p.type = 'compliance'
RETURN p.name, p.condition, p.action AS required_action
// Governed vocabulary: all terms in a business domain
MATCH (e:BusinessEntity)-[:RELATES_TO*0..2]-(root:BusinessEntity {domain: $domain})
RETURN DISTINCT e.name, e.definition
ORDER BY e.nameBefore: Each agent re-learns business logic independently; inconsistent definitions across systems; no explainability; compliance risk at scale. After: Shared governed knowledge layer; agents reason over enterprise ontology; consistent, explainable, auditable decisions across all workflows.
Getting started: decision-guide → data-modeling (ontology pattern) → querying
Customer says: “recommend similar products”, “customers who bought X also bought”, “content recommendations”, “collaborative filtering”, “personalized suggestions”, “what should this user see next”, “related items”, “people who liked this also liked”
Graph-based recommendations outperform traditional collaborative filtering when relationships between users, items, and behaviors are complex and multi-dimensional. Instead of computing similarity from a flat matrix, graph traversal follows actual behavioral paths — purchases, ratings, views, social connections — to find recommendations grounded in real relationships.
(User) -[PURCHASED]→ (Product)
(User) -[RATED {score}]→ (Product)
(User) -[VIEWED]→ (Product)
(User) -[FOLLOWS]→ (User)
(Product) -[IN_CATEGORY]→ (Category)
(Product) -[SIMILAR_TO {score}]→ (Product)// Collaborative filtering: products bought by users who bought the same things I did
MATCH (me:User {id: $userId})-[:PURCHASED]->(p:Product)<-[:PURCHASED]-(other:User)
-[:PURCHASED]->(rec:Product)
WHERE NOT (me)-[:PURCHASED]->(rec)
RETURN rec.name, count(other) AS score
ORDER BY score DESC
LIMIT 10
// Category-aware recommendations: products in categories I buy from
MATCH (me:User {id: $userId})-[:PURCHASED]->(:Product)-[:IN_CATEGORY]->(cat:Category)
<-[:IN_CATEGORY]-(rec:Product)
WHERE NOT (me)-[:PURCHASED]->(rec)
RETURN rec.name, cat.name, count(*) AS relevance
ORDER BY relevance DESC
LIMIT 10
// Social recommendations: what my friends bought that I haven't
MATCH (me:User {id: $userId})-[:FOLLOWS]->(friend:User)-[:PURCHASED]->(rec:Product)
WHERE NOT (me)-[:PURCHASED]->(rec)
RETURN rec.name, collect(DISTINCT friend.name) AS recommended_by, count(friend) AS strength
ORDER BY strength DESC
LIMIT 10Before (matrix-based): Flat user-item matrix, cold start problem, no explainability. After (graph-based): Traversal through actual relationships, naturally handles cold start via social/category edges, explainable (“recommended because your friend Alice bought it and it’s in a category you frequently purchase from”).
Getting started: decision-guide → data-modeling → querying
Signals in customer descriptions that indicate a graph database is the right fit:
| Signal in customer description | Likely pattern | Route to |
|---|---|---|
| “unified view”, “single view of customer”, “360” | Customer 360 | This file → data-modeling |
| “fraud”, “suspicious”, “shared accounts”, “ring” | Fraud detection | This file → data-modeling |
| “dependencies”, “blast radius”, “impact analysis” | Service dependency | This file → data-modeling |
| “who has access”, “permissions”, “RBAC”, “audit” | Access control | This file → data-modeling |
| “knowledge graph”, “entity relationships”, “RAG accuracy” | Knowledge graph / GraphRAG | graphrag |
| “supply chain”, “traceability”, “recall”, “provenance” | Supply chain | This file → data-modeling |
| “agent memory”, “remember across sessions”, “long-term” | Agent memory | agentic-memory |
| “semantic layer”, “ontology”, “business rules for agents”, “governed knowledge” | Semantic layer / ontology | This file → data-modeling |
| “recommend”, “similar products”, “customers who bought”, “personalized suggestions” | Recommendation engine | This file → data-modeling |
| “connected data”, “relationships between”, “network” | General graph (clarify pattern) | decision-guide |
| “multi-hop”, “friends of friends”, “path between” | Graph traversal (clarify pattern) | decision-guide |
When the customer description does NOT indicate a graph:
| Signal | Why NOT graph | Better fit |
|---|---|---|
| “simple lookups by ID”, “key-value” | No relationships queried | DynamoDB |
| “SQL reports”, “aggregate queries”, “GROUP BY” | Relational analytics | Aurora / Redshift |
| “full-text search”, “fuzzy matching” | Text search, not traversal | OpenSearch |
| “time-series”, “IoT telemetry”, “metrics” | Temporal, not relational | Timestream |
| “JSON documents”, “flexible schema, no joins” | Document store | DocumentDB |
| “only 1 hop”, “just get related items” | Shallow relationships | DynamoDB GSI or Aurora |
| “batch ETL”, “data warehouse” | Analytics, not graph | Redshift / Athena |
dedup() — multi-hop queries produce duplicates without it.simplePath() — cyclic graphs cause infinite loops without it.sample() or edge filtering.def blocks are Gremlin Console only; extract traversal for Python driver.data-modeling (schema design), querying (query syntax)When a prompt says “create a graph, write the artifact at <path>, hand off to the harness,” the response shape is exactly:
aws neptune-graph create-graph with the parameters the prompt names. Apply create-time tags inline (best-effort).aws neptune-graph tag-resource explicitly to guarantee telemetry tags are persisted (see action-safety.md).file_write(<path>, content) with at minimum {"graph_id": "<g-...>", "graph_name": "<name>"}. The validator reads this artifact to know what graph to inspect. Without it, the validator cannot proceed.Never substitute “here is the JSON content for you to save manually” for the file_write tool call. The validator does not read your prose; it reads the file.