Graph Schema Reference

This document describes the Neo4j graph database schema powering the Consumer Graph MCP.

Node Types

User

Represents a shopper with purchase history and preferences.

Properties:

user_id (string, unique) - User identifier
zip (string) - ZIP code for location context
created_at (datetime) - Account creation timestamp
profile_type (string) - Shopping profile (e.g., “Health-Conscious”, “Family-Bulk”)
latitude (float, optional) - Geographic coordinate
longitude (float, optional) - Geographic coordinate

Relationships:

PURCHASED → Product
ELIGIBLE_FOR → Offer
SHOPS_AT → Retailer
MEMBER_OF → Household
MEMBER_OF → Community

Product

Represents a purchasable product.

Properties:

product_id (string, unique) - Product identifier
upc (string) - Universal Product Code
name (string) - Product name
brand (string) - Brand name
category (string) - Product category
organic (boolean) - Organic status
vegan (boolean, optional) - Vegan status
trending (boolean) - Trending flag
tags (array of strings) - Descriptive tags

Relationships:

IN_CATEGORY → Category
SIMILAR_TO → Product (with similarity_score property)
HAS_OFFER ← Offer

Offer

Represents a promotional offer for points/rewards.

Properties:

offer_id (string, unique) - Offer identifier
points (integer) - Point value
description (string) - Offer description
start (date) - Start date
end (date) - End date
priority (string) - Priority level (“High”, “Medium”, “Low”)
offer_type (string) - Type of offer
venue_type (string) - Where offer applies

Relationships:

HAS_OFFER → Product (specific product offer)
HAS_OFFER → Brand (brand-level offer via Category node)
HAS_OFFER → Category (category-level offer)
ELIGIBLE_FOR ← User
AVAILABLE_AT → Retailer

Retailer

Represents a store or shopping venue.

Properties:

retailer_id (string, unique) - Retailer identifier
name (string) - Retailer name
venue_type (string) - Type of venue (“Grocery”, “Drugstore”, “Warehouse”, etc.)
tier (string) - Price tier (“Premium”, “Mid-Range”, “Discount”, etc.)

Relationships:

AVAILABLE_AT ← Offer
SHOPS_AT ← User

Demo Retailers:

RET_WHOLE_FOODS - Premium grocery
RET_ALDI - Discount grocery
RET_TARGET - Big box
RET_COSTCO - Warehouse club
RET_MARIANOS - Regional chain
RET_WALGREENS - Drugstore
RET_TRADER_JOES - Specialty
RET_AMAZON_FRESH - Online delivery

Community

Intermediary node representing a group of similar shoppers.

Properties:

community_id (string, unique) - Community identifier
name (string) - Community name
member_count (integer) - Number of members
primary_category (string) - Main category affinity
zip_code (string, optional) - Geographic location

Relationships:

MEMBER_OF ← User
POPULAR_IN ← Product

Purpose: Graph optimization pattern reducing edges by 70%. Groups similar shoppers to enable efficient collaborative filtering and trend analysis.

Benefits:

Faster recommendation queries
Better scalability
Enables community-based insights
Reduces graph memory footprint

Household

Represents a shared living/shopping unit.

Properties:

household_id (string, unique) - Household identifier
member_count (integer) - Number of household members
combined_monthly_budget (float) - Total household budget
household_type (string) - Type (“Couple”, “Family”, “Roommates”)

Relationships:

MEMBER_OF ← User

Purpose: Enables household-level shopping insights and recommendations considering shared context.

Relationship Types

PURCHASED

User purchased a product.

Properties:

quantity (integer) - Items purchased
timestamp (datetime) - Purchase time
price (float, optional) - Purchase price

Direction: User → Product

Usage: Purchase history, frequency analysis, preference modeling

ELIGIBLE_FOR

User is eligible to redeem an offer.

Properties: None

Direction: User → Offer

Usage: Personalized offer filtering, targeted promotions

HAS_OFFER

Offer applies to product, brand, or category.

Properties: None

Direction: Offer → Product/Category

Usage: Offer discovery, product-to-offer matching

SIMILAR_TO

Products are similar based on collaborative filtering.

Properties:

similarity_score (float) - Similarity strength (0.0 to 1.0)

Direction: Product ↔ Product (bidirectional)

Usage: Product recommendations, alternative suggestions, explainable AI

IN_CATEGORY

Product belongs to a category.

Properties: None

Direction: Product → Category

Usage: Category browsing, categorization

SHOPS_AT

User shops at a retailer.

Properties:

frequency (integer) - Visit count
last_visit (datetime) - Most recent visit

Direction: User → Retailer

Usage: Retailer preferences, location-based offers

MEMBER_OF

User belongs to household or community.

Properties: None

Direction: User → Household/Community

Usage: Household context, community insights, collaborative filtering

POPULAR_IN

Product is popular within a community.

Properties:

purchase_count (integer) - Community purchases

Direction: Product → Community

Usage: Community trending, social proof

SHOPS_IN

User shops in a category.

Properties:

purchase_count (integer) - Category purchases

Direction: User → Category

Usage: Category affinity, expansion prediction

Graph Patterns

User Shopping Profile

(User)-[:MEMBER_OF]->(Household)
(User)-[:MEMBER_OF]->(Community)
(User)-[:SHOPS_IN]->(Category)
(User)-[:SHOPS_AT]->(Retailer)
(User)-[:PURCHASED]->(Product)

Product Relationships

(Product)-[:IN_CATEGORY]->(Category)
(Product)-[:SIMILAR_TO]-(Product)
(Offer)-[:HAS_OFFER]->(Product)
(Product)<-[:POPULAR_IN]-(Community)

Offer Discovery

(User)-[:ELIGIBLE_FOR]->(Offer)
(Offer)-[:HAS_OFFER]->(Product/Category)
(Offer)-[:AVAILABLE_AT]->(Retailer)

Collaborative Filtering (Optimized)

(User)-[:MEMBER_OF]->(Community)<-[:MEMBER_OF]-(OtherUser)
(OtherUser)-[:PURCHASED]->(Product)

Old pattern (slow): (User)-[:SIMILAR_TO]-(OtherUser) New pattern (fast): Uses Community as intermediary

Optimization Strategy

Problem

Direct user-to-user and user-to-product relationships created 2,182 edges, causing:

Slow queries
High memory usage
Poor scalability

Solution: Intermediary Nodes

Community Nodes: Group similar users
Category Nodes: Group related products

Results

Edges reduced: 2,182 → 662 (70% reduction)
Query performance: ~3x faster
Scalability: Linear growth instead of quadratic
Memory: Reduced graph memory footprint

Pattern Transformation

Before: (User)-[:PURCHASED]->(Product) [2,182 edges]
After:  (User)-[:SHOPS_IN]->(Category)<-[:IN_CATEGORY]-(Product) [662 edges]

Indexes

The following indexes are created for query performance:

User:

user_id (unique constraint)

Product:

product_id (unique constraint)
name (text index for search)
brand (index)
category (index)

Offer:

offer_id (unique constraint)
start, end (composite index for date range queries)

Category:

category_id (unique constraint)
name (index)

Community:

community_id (unique constraint)

Query Examples

Find User’s Purchase History

MATCH (u:User {user_id: $userId})-[p:PURCHASED]->(prod:Product)
RETURN prod, p.quantity, p.timestamp
ORDER BY p.timestamp DESC
LIMIT 20

Get Active Offers for User

MATCH (u:User {user_id: $userId})-[:ELIGIBLE_FOR]->(o:Offer)
WHERE date() >= o.start AND date() <= o.end
RETURN o
ORDER BY o.points DESC

Find Similar Products

MATCH (p1:Product {product_id: $productId})-[s:SIMILAR_TO]-(p2:Product)
WHERE s.similarity_score >= $minSimilarity
RETURN p2, s.similarity_score
ORDER BY s.similarity_score DESC
LIMIT 10

Community Recommendations (Optimized)

MATCH (u:User {user_id: $userId})-[:MEMBER_OF]->(c:Community)
MATCH (c)<-[:MEMBER_OF]-(other:User)-[:PURCHASED]->(p:Product)
WHERE NOT (u)-[:PURCHASED]->(p)
RETURN p, count(*) as purchase_count
ORDER BY purchase_count DESC
LIMIT 10

Data Volumes

Demo Dataset

Users: 6 demo + 120+ similar users
Products: 135+ items across 10 categories
Offers: 120+ active offers
Retailers: 8 venues
Categories: 47 categories
Communities: 45 communities
Households: 3 households

Edges

Total edges: ~662 (after optimization)
User relationships: ~180
Product relationships: ~300
Offer relationships: ~150
Household/Community: ~32

Schema Evolution

Phase 1: Direct Relationships

User → Product (PURCHASED)
User → User (SIMILAR_TO)
Simple but slow at scale

Phase 2: Community & Category Nodes

User → Community → User (implicit similarity)
User → Category → Product (categorized shopping)
70% edge reduction, 3x faster queries

Phase 3 (Future):

Temporal nodes for time-based patterns
Brand nodes for brand-level analysis
Location nodes for geographic clustering

Best Practices

For Queries

Always use indexes (user_id, product_id, etc.)
Limit result sets with LIMIT clause
Use date filters on active offers
Leverage Community nodes for recommendations
Profile queries with PROFILE or EXPLAIN

For Data Modeling

Use intermediary nodes for many-to-many relationships
Store frequently accessed properties on nodes
Use relationship properties for metadata
Normalize data appropriately
Consider query patterns in schema design

For Performance

Create indexes on frequently queried properties
Use parameterized queries
Batch write operations
Monitor query execution time
Use APOC procedures for complex operations

Schema Visualization

Access Neo4j Browser at http://localhost:7474 to visualize the graph:

// Visualize demo user's shopping pattern
MATCH path = (u:User {user_id: 'DEMO_USER_HEALTH'})-[*1..2]-(n)
RETURN path
LIMIT 50

// Visualize product category structure
MATCH (p:Product)-[:IN_CATEGORY]->(c:Category)
RETURN p, c
LIMIT 100

// Visualize community structure
MATCH (u:User)-[:MEMBER_OF]->(c:Community)<-[:POPULAR_IN]-(p:Product)
WHERE c.community_id = 'COMM_001'
RETURN u, c, p