E-Commerce Platform¶

A practical example building a complete e-commerce knowledge system with multiple interconnected collections.

What you'll learn:

Multiple compound types working together
Hierarchy traversal for category trees
Network graphs for recommendations
Cross-collection queries

Architecture¶

flowchart LR
    P["Products<br/>(Document)"] --> C["Categories<br/>(Hierarchy)"]
    P --> PU["Purchases<br/>(Document)"]
    P <--> R["Recommendations<br/>(Network)"]

Four collections, each optimized for its data shape:

Collection	Compound	Purpose
Products	Document	Catalog with semantic descriptions
Categories	Hierarchy	Category tree with parent-child
Purchases	Document	User purchase history
Recommendations	Network	Product relationships

The Data¶

Products¶

products = pd.DataFrame([
    {"product_id": "LAP001", "name": "ProBook 15",
     "description": "15-inch professional laptop with Intel i7, 16GB RAM",
     "category": "Laptops", "price": 1299.99, "stock": 45},
    {"product_id": "LAP002", "name": "UltraSlim Air",
     "description": "Ultra-thin 13-inch laptop, all-day battery",
     "category": "Laptops", "price": 1499.99, "stock": 30},
    {"product_id": "PHN001", "name": "Galaxy Ultra",
     "description": "Flagship smartphone with 200MP camera",
     "category": "Phones", "price": 1199.99, "stock": 100},
    {"product_id": "ACC001", "name": "Wireless Earbuds Pro",
     "description": "Active noise cancellation, premium sound",
     "category": "Accessories", "price": 249.99, "stock": 200},
    # ... more products
])

Category Hierarchy¶

categories = pd.DataFrame([
    {"category": "Electronics", "parent": None, "level": 0},
    {"category": "Computers", "parent": "Electronics", "level": 1},
    {"category": "Mobile", "parent": "Electronics", "level": 1},
    {"category": "Laptops", "parent": "Computers", "level": 2},
    {"category": "Tablets", "parent": "Computers", "level": 2},
    {"category": "Phones", "parent": "Mobile", "level": 2},
    {"category": "Wearables", "parent": "Mobile", "level": 2},
    {"category": "Accessories", "parent": "Electronics", "level": 1},
])

Recommendations Network¶

recommendations = pd.DataFrame([
    ("LAP001", "bought_together", "ACC002"),  # Laptop + USB Hub
    ("LAP001", "bought_together", "ACC003"),  # Laptop + Stand
    ("PHN001", "bought_together", "ACC004"),  # Phone + Charger
    ("LAP001", "also_viewed", "LAP002"),      # Similar laptops
    ("LAP003", "upgrade_from", "LAP001"),     # Upgrade path
], columns=["source", "relation", "target"])

Schema Definitions¶

from hybi.compose import Document, Hierarchy, Network, Field, Encoding

# Products: semantic search on descriptions
product_schema = Document(
    content_field="description",
    content_encoding=Encoding.SEMANTIC,
    content_weight=2.0,
    metadata_fields={
        "product_id": Field(encoding=Encoding.EXACT),
        "name": Field(encoding=Encoding.SEMANTIC, weight=1.5),
        "category": Field(encoding=Encoding.EXACT),
        "price": Field(encoding=Encoding.NUMERIC),
        "stock": Field(encoding=Encoding.NUMERIC),
    },
)

# Categories: tree structure
category_schema = Hierarchy(
    node_field="category",
    parent_field="parent",
    level_field="level",
    node_encoding=Encoding.EXACT,
)

# Recommendations: product graph
recommendation_schema = Network(
    node_field="source",
    edge_field="relation",
    source_field="source",
    target_field="target",
    node_encoding=Encoding.EXACT,
    edge_encoding=Encoding.EXACT,
)

Ingesting the Data¶

from hybi import HyperBinder

hb = HyperBinder("http://localhost:8000")

hb.ingest(products, collection="ecom_products", schema=product_schema)
hb.ingest(categories, collection="ecom_categories", schema=category_schema)
hb.ingest(recommendations, collection="ecom_recommendations", schema=recommendation_schema)

Cross-Collection Queries¶

1. Products in a Category and Subcategories¶

Find all products in "Computers" including Laptops and Tablets:

products_coll = hb.collection("ecom_products")
categories_coll = hb.collection("ecom_categories")

# Get all descendant categories
descendants = categories_coll.query(category_schema).descendants(
    node="Computers", top_k=20
)
subcategories = ["Computers"] + [r["category"] for r in descendants]
# → ["Computers", "Laptops", "Tablets"]

# Find products in those categories
for cat in subcategories:
    cat_products = products_coll.query(product_schema).filter(
        where=[("category", "==", cat)], top_k=10
    )
    for p in cat_products:
        print(f"[{cat}] {p['name']}: ${p['price']}")

Output:

[Laptops] ProBook 15: $1299.99
[Laptops] UltraSlim Air: $1499.99
[Laptops] GamerX Pro: $1899.99
[Tablets] iPad Pro 12.9: $1099.99
[Tablets] Galaxy Tab S9: $849.99

2. Product Recommendations¶

Get "frequently bought together" recommendations:

recommendations_coll = hb.collection("ecom_recommendations")

# What do people buy with ProBook 15?
bought_together = recommendations_coll.query(recommendation_schema).find(
    source="LAP001", edge="bought_together", top_k=10
)

for rec in bought_together:
    target_id = rec["target"]

    # Look up product details
    product = products_coll.query(product_schema).filter(
        where=[("product_id", "==", target_id)], top_k=1
    )
    for p in product:
        print(f"+ {p['name']} (${p['price']})")

Output:

+ USB-C Hub ($79.99)
+ Laptop Stand ($49.99)

3. Upgrade Paths¶

Find upgrade recommendations:

upgrades = recommendations_coll.query(recommendation_schema).find(
    edge="upgrade_from", top_k=10
)

for rec in upgrades:
    # Get both products
    source = list(products_coll.query(product_schema).filter(
        where=[("product_id", "==", rec["source"])], top_k=1
    ))[0]
    target = list(products_coll.query(product_schema).filter(
        where=[("product_id", "==", rec["target"])], top_k=1
    ))[0]

    price_diff = float(source["price"]) - float(target["price"])
    print(f"{target['name']} → {source['name']} (+${price_diff:.2f})")

Output:

ProBook 15 → GamerX Pro (+$600.00)
Pixel 8 → iPhone Pro Max (+$600.00)

Navigate the category tree:

# Get path to root
ancestors = categories_coll.query(category_schema).ancestors(
    node="Phones", top_k=10
)
path = [a["category"] for a in ancestors]
print(f"Path: {' → '.join(reversed(path))}")
# → Electronics → Mobile → Phones

# Get sibling categories
siblings = categories_coll.query(category_schema).siblings(
    node="Phones", top_k=10
)
sibling_names = [s["category"] for s in siblings]
print(f"Siblings: {sibling_names}")
# → ["Wearables"]

5. Low Stock Alert¶

Find low-stock items in the Mobile category:

# Get Mobile subcategories
mobile_descendants = categories_coll.query(category_schema).descendants(
    node="Mobile", top_k=10
)
mobile_cats = ["Mobile"] + [r["category"] for r in mobile_descendants]

for cat in mobile_cats:
    low_stock = products_coll.query(product_schema).filter(
        where=[("category", "==", cat), ("stock", "<", 50)],
        top_k=10
    )
    for p in low_stock:
        print(f"⚠️ {p['name']}: {p['stock']} units left")

Semantic Product Search¶

The Document compound enables semantic search on descriptions:

# Find products matching a natural language query
results = products_coll.query(product_schema).search(
    "lightweight laptop for travel with long battery",
    top_k=5
)

for r in results:
    print(f"{r['name']} (score: {r.score:.2f})")
    print(f"  {r['description'][:60]}...")

Output:

UltraSlim Air (score: 0.87)
  Ultra-thin 13-inch laptop, weighs only 2.5lbs. All-day batt...
ProBook 15 (score: 0.72)
  15-inch professional laptop with Intel i7, 16GB RAM, 512GB...

Complete Code¶

#!/usr/bin/env python3
"""E-Commerce Platform Demo"""

import pandas as pd
from hybi import HyperBinder
from hybi.compose import Document, Hierarchy, Network, Field, Encoding


def main():
    # Create data
    products = pd.DataFrame([
        {"product_id": "LAP001", "name": "ProBook 15",
         "description": "15-inch professional laptop, Intel i7, 16GB RAM",
         "category": "Laptops", "price": 1299.99, "stock": 45},
        {"product_id": "LAP002", "name": "UltraSlim Air",
         "description": "Ultra-thin 13-inch, all-day battery, M2 chip",
         "category": "Laptops", "price": 1499.99, "stock": 30},
        {"product_id": "PHN001", "name": "Galaxy Ultra",
         "description": "Flagship smartphone, 200MP camera",
         "category": "Phones", "price": 1199.99, "stock": 100},
        {"product_id": "ACC001", "name": "USB-C Hub",
         "description": "7-in-1 hub with HDMI, USB-A, SD card",
         "category": "Accessories", "price": 79.99, "stock": 150},
    ])

    categories = pd.DataFrame([
        {"category": "Electronics", "parent": None, "level": 0},
        {"category": "Computers", "parent": "Electronics", "level": 1},
        {"category": "Laptops", "parent": "Computers", "level": 2},
        {"category": "Mobile", "parent": "Electronics", "level": 1},
        {"category": "Phones", "parent": "Mobile", "level": 2},
        {"category": "Accessories", "parent": "Electronics", "level": 1},
    ])

    recommendations = pd.DataFrame([
        ("LAP001", "bought_together", "ACC001"),
        ("LAP001", "also_viewed", "LAP002"),
    ], columns=["source", "relation", "target"])

    # Schemas
    product_schema = Document(
        content_field="description",
        content_encoding=Encoding.SEMANTIC,
        metadata_fields={
            "product_id": Field(encoding=Encoding.EXACT),
            "name": Field(encoding=Encoding.SEMANTIC),
            "category": Field(encoding=Encoding.EXACT),
            "price": Field(encoding=Encoding.NUMERIC),
        },
    )

    category_schema = Hierarchy(
        node_field="category",
        parent_field="parent",
        level_field="level",
    )

    rec_schema = Network(
        source_field="source",
        edge_field="relation",
        target_field="target",
    )

    # Ingest
    hb = HyperBinder("http://localhost:8000")
    hb.ingest(products, collection="ecom_products", schema=product_schema)
    hb.ingest(categories, collection="ecom_categories", schema=category_schema)
    hb.ingest(recommendations, collection="ecom_recs", schema=rec_schema)

    # Query: Semantic search
    print("Semantic search: 'lightweight laptop'")
    for r in hb.collection("ecom_products").query(product_schema).search(
        "lightweight laptop for travel", top_k=3
    ):
        print(f"  {r['name']}: ${r['price']}")

    # Query: Category descendants
    print("\nProducts in Computers category:")
    descendants = hb.collection("ecom_categories").query(category_schema).descendants(
        node="Computers", top_k=10
    )
    for cat in ["Computers"] + [d["category"] for d in descendants]:
        for p in hb.collection("ecom_products").query(product_schema).filter(
            where=[("category", "==", cat)], top_k=5
        ):
            print(f"  [{cat}] {p['name']}")


if __name__ == "__main__":
    main()

Key Takeaways¶

Right compound for the job - Document for semantic, Hierarchy for trees, Network for graphs
Cross-collection queries - Navigate categories, then find products
Semantic search - Natural language queries on product descriptions
Graph traversal - Recommendations, upgrades, frequently bought together
Tree operations - Ancestors, descendants, siblings for category navigation

E-Commerce Platform¶

Architecture¶

The Data¶

Products¶

Category Hierarchy¶

Recommendations Network¶

Schema Definitions¶

Ingesting the Data¶

Cross-Collection Queries¶

1. Products in a Category and Subcategories¶

2. Product Recommendations¶

3. Upgrade Paths¶

4. Category Navigation¶

5. Low Stock Alert¶

Semantic Product Search¶

Complete Code¶

Key Takeaways¶