@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-04-data-enrichment.md

@@ -1,546 +1,546 @@
-# Module 4: Data Enrichment
-
-**Level:** Intermediate
-**Estimated Time:** 20 minutes
-
-## Overview
-
-This module covers advanced GraphQL techniques for enriching extracted data with related entities, including batch queries, nested relations, and efficient enrichment patterns.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Enrich data with related entities using GraphQL
-- ✅ Use batch queries to avoid N+1 query problems
-- ✅ Extract nested relations in a single query
-- ✅ Implement efficient enrichment for large datasets
-- ✅ Handle missing or null relations gracefully
-
-## Why Enrichment Matters
-
-**Without enrichment** (flat data):
-```json
-{
-  "ref": "INV-001",
-  "productRef": "SKU-123",
-  "locationRef": "WH-001",
-  "qty": 100
-}
-```
-
-**With enrichment** (complete context):
-```json
-{
-  "ref": "INV-001",
-  "productRef": "SKU-123",
-  "locationRef": "WH-001",
-  "qty": 100,
-  "product": {
-    "ref": "SKU-123",
-    "name": "Wireless Mouse",
-    "gtin": "0123456789012"
-  },
-  "location": {
-    "ref": "WH-001",
-    "name": "Main Warehouse",
-    "type": "PHYSICAL"
-  }
-}
-```
-
-## Single Query Enrichment
-
-### Nested GraphQL Relations
-
-Extract parent and child entities in one query:
-
-```typescript
-const query = `
-  query ExtractInventoryEnriched($first: Int!, $after: String) {
-    inventoryPositions(first: $first, after: $after) {
-      edges {
-        node {
-          id
-          ref
-          productRef
-          locationRef
-          qty
-          status
-
-          # Product relation
-          product {
-            ref
-            name
-            gtin
-            description
-            catalogue {
-              ref
-              name
-            }
-          }
-
-          # Location relation
-          location {
-            ref
-            name
-            type
-            address {
-              city
-              state
-              country
-            }
-          }
-        }
-        cursor
-      }
-      pageInfo { hasNextPage }
-    }
-  }
-`;
-
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: { maxRecords: 10000 }
-});
-
-const enriched = result.data.inventoryPositions.edges.map(e => e.node);
-```
-
-**Benefits:**
-- Single API call per page
-- Consistent data snapshot
-- Reduced network overhead
-
-### Orders with Items Example
-
-```typescript
-const query = `
-  query ExtractOrdersFull($first: Int!, $after: String) {
-    orders(first: $first, after: $after) {
-      edges {
-        node {
-          id
-          ref
-          type
-          status
-          totalPrice
-          currency
-
-          customer {
-            ref
-            email
-            firstName
-            lastName
-          }
-
-          billingAddress {
-            street
-            city
-            state
-            postcode
-            country
-          }
-
-          items {
-            edges {
-              node {
-                ref
-                productRef
-                quantity
-                price
-                totalPrice
-                currency
-              }
-            }
-          }
-        }
-        cursor
-      }
-      pageInfo { hasNextPage }
-    }
-  }
-`;
-
-const result = await client.graphql({
-  query,
-  variables: { first: 50 },  // Smaller pages for complex queries
-  pagination: { maxRecords: 5000 }
-});
-```
-
-## Batch Enrichment Pattern
-
-When you can't get all data in one query, use batch enrichment to avoid N+1 queries.
-
-### The N+1 Problem
-
-**❌ BAD: N+1 queries**
-```typescript
-// 1 query to get inventory
-const inventory = await getInventoryPositions();
-
-// N queries to get each product (if we have 1000 items = 1000 queries!)
-for (const item of inventory) {
-  const product = await client.graphql({
-    query: `query { product(ref: "${item.productRef}") { name } }`
-  });
-  item.product = product.data.product;
-}
-```
-
-### ✅ GOOD: Batch Query Solution
-
-```typescript
-async function enrichInventoryWithProducts(inventory: any[]) {
-  const batchSize = 50;
-  const enriched = [];
-
-  for (let i = 0; i < inventory.length; i += batchSize) {
-    const batch = inventory.slice(i, i + batchSize);
-    const productRefs = batch.map(item => item.productRef);
-
-    // Single query for 50 products
-    const result = await client.graphql({
-      query: `
-        query GetProducts($refs: [String!]!) {
-          products(filter: { ref: { in: $refs } }, first: ${batchSize}) {
-            edges {
-              node {
-                ref
-                name
-                gtin
-                catalogue { ref name }
-              }
-            }
-          }
-        }
-      `,
-      variables: { refs: productRefs }
-    });
-
-    // Map products back to inventory items
-    const productMap = new Map(
-      result.data.products.edges.map(e => [e.node.ref, e.node])
-    );
-
-    for (const item of batch) {
-      enriched.push({
-        ...item,
-        product: productMap.get(item.productRef) || null
-      });
-    }
-  }
-
-  return enriched;
-}
-```
-
-### Multi-Entity Batch Enrichment
-
-Enrich with multiple entity types:
-
-```typescript
-async function enrichInventoryFull(inventory: any[]) {
-  const batchSize = 50;
-  const enriched = [];
-
-  for (let i = 0; i < inventory.length; i += batchSize) {
-    const batch = inventory.slice(i, i + batchSize);
-
-    // Get unique refs
-    const productRefs = [...new Set(batch.map(item => item.productRef))];
-    const locationRefs = [...new Set(batch.map(item => item.locationRef))];
-
-    // Parallel batch queries
-    const [productsResult, locationsResult] = await Promise.all([
-      client.graphql({
-        query: `
-          query GetProducts($refs: [String!]!) {
-            products(filter: { ref: { in: $refs } }, first: 100) {
-              edges { node { ref name gtin } }
-            }
-          }
-        `,
-        variables: { refs: productRefs }
-      }),
-      client.graphql({
-        query: `
-          query GetLocations($refs: [String!]!) {
-            locations(filter: { ref: { in: $refs } }, first: 100) {
-              edges { node { ref name type } }
-            }
-          }
-        `,
-        variables: { refs: locationRefs }
-      })
-    ]);
-
-    // Create lookup maps
-    const productMap = new Map(
-      productsResult.data.products.edges.map(e => [e.node.ref, e.node])
-    );
-    const locationMap = new Map(
-      locationsResult.data.locations.edges.map(e => [e.node.ref, e.node])
-    );
-
-    // Enrich batch
-    for (const item of batch) {
-      enriched.push({
-        ...item,
-        product: productMap.get(item.productRef) || null,
-        location: locationMap.get(item.locationRef) || null
-      });
-    }
-  }
-
-  return enriched;
-}
-```
-
-## Advanced Enrichment Patterns
-
-### Conditional Enrichment
-
-Only enrich items that meet certain criteria:
-
-```typescript
-async function conditionalEnrichment(inventory: any[]) {
-  // Filter items that need enrichment
-  const itemsNeedingEnrichment = inventory.filter(item =>
-    item.qty > 0 && item.status === 'AVAILABLE'
-  );
-
-  // Enrich only those items
-  const enriched = await enrichInventoryWithProducts(itemsNeedingEnrichment);
-
-  // Merge back with original data
-  const enrichedMap = new Map(enriched.map(item => [item.ref, item]));
-
-  return inventory.map(item =>
-    enrichedMap.get(item.ref) || item
-  );
-}
-```
-
-### Cached Enrichment
-
-Cache frequently accessed reference data:
-
-```typescript
-class CachedEnrichment {
-  private productCache = new Map<string, any>();
-  private locationCache = new Map<string, any>();
-
-  async enrichWithCache(inventory: any[]) {
-    // Find uncached products
-    const uncachedProductRefs = inventory
-      .map(item => item.productRef)
-      .filter(ref => !this.productCache.has(ref));
-
-    // Fetch uncached products
-    if (uncachedProductRefs.length > 0) {
-      const products = await this.fetchProducts(uncachedProductRefs);
-      products.forEach(p => this.productCache.set(p.ref, p));
-    }
-
-    // Enrich from cache
-    return inventory.map(item => ({
-      ...item,
-      product: this.productCache.get(item.productRef) || null
-    }));
-  }
-
-  private async fetchProducts(refs: string[]) {
-    const result = await client.graphql({
-      query: `
-        query GetProducts($refs: [String!]!) {
-          products(filter: { ref: { in: $refs } }, first: 1000) {
-            edges { node { ref name gtin } }
-          }
-        }
-      `,
-      variables: { refs }
-    });
-    return result.data.products.edges.map(e => e.node);
-  }
-}
-```
-
-### Deep Nesting
-
-Extract multiple levels of relations:
-
-```typescript
-const query = `
-  query ExtractProductsDeep($first: Int!, $after: String) {
-    products(first: $first, after: $after) {
-      edges {
-        node {
-          ref
-          name
-
-          catalogue {
-            ref
-            name
-            retailer {
-              id
-              name
-            }
-          }
-
-          categories {
-            edges {
-              node {
-                name
-                path
-                parent {
-                  name
-                  path
-                }
-              }
-            }
-          }
-
-          inventoryPositions {
-            edges {
-              node {
-                ref
-                qty
-                location {
-                  ref
-                  name
-                  type
-                }
-              }
-            }
-          }
-        }
-        cursor
-      }
-      pageInfo { hasNextPage }
-    }
-  }
-`;
-```
-
-## Handling Missing Relations
-
-### Graceful Null Handling
-
-```typescript
-function transformEnrichedRecord(record: any) {
-  return {
-    sku: record.productRef,
-    productName: record.product?.name || 'Unknown Product',
-    productGtin: record.product?.gtin || '',
-    warehouse: record.locationRef,
-    warehouseName: record.location?.name || 'Unknown Location',
-    warehouseType: record.location?.type || 'UNKNOWN',
-    quantity: parseInt(record.qty) || 0
-  };
-}
-```
-
-### Validation and Error Reporting
-
-```typescript
-function validateEnrichment(enriched: any[]) {
-  const issues = [];
-
-  for (const record of enriched) {
-    if (!record.product) {
-      issues.push({
-        type: 'MISSING_PRODUCT',
-        ref: record.ref,
-        productRef: record.productRef
-      });
-    }
-
-    if (!record.location) {
-      issues.push({
-        type: 'MISSING_LOCATION',
-        ref: record.ref,
-        locationRef: record.locationRef
-      });
-    }
-  }
-
-  if (issues.length > 0) {
-    console.warn(`Found ${issues.length} enrichment issues`);
-    console.warn(issues.slice(0, 10)); // Show first 10
-  }
-
-  return issues;
-}
-```
-
-## Practice Exercise
-
-**Goal**: Extract inventory positions and enrich with product and location details using batch queries
-
-**Requirements:**
-1. Extract inventory positions with basic fields
-2. Batch enrich with products (name, gtin, catalogue)
-3. Batch enrich with locations (name, type)
-4. Handle missing relations gracefully
-5. Report enrichment statistics
-
-**Solution:**
-
-```typescript
-async function extractAndEnrichInventory() {
-  // Step 1: Extract basic inventory
-  const result = await client.graphql({
-    query: `
-      query ExtractInventory($first: Int!, $after: String) {
-        inventoryPositions(first: $first, after: $after) {
-          edges {
-            node { id ref productRef locationRef qty status }
-            cursor
-          }
-          pageInfo { hasNextPage }
-        }
-      }
-    `,
-    variables: { first: 100 },
-    pagination: { maxRecords: 10000 }
-  });
-
-  const inventory = result.data.inventoryPositions.edges.map(e => e.node);
-  console.log(`Extracted ${inventory.length} inventory positions`);
-
-  // Step 2: Batch enrich
-  const enriched = await enrichInventoryFull(inventory);
-
-  // Step 3: Validate enrichment
-  const issues = validateEnrichment(enriched);
-
-  // Step 4: Report statistics
-  const stats = {
-    total: enriched.length,
-    withProduct: enriched.filter(r => r.product).length,
-    withLocation: enriched.filter(r => r.location).length,
-    fullyEnriched: enriched.filter(r => r.product && r.location).length,
-    issues: issues.length
-  };
-
-  console.log('Enrichment statistics:', stats);
-
-  return enriched;
-}
-```
-
-## Key Takeaways
-
-- 🎯 Use nested GraphQL relations when possible (single query)
-- 🎯 Batch enrichment avoids N+1 query problem
-- 🎯 Parallel queries for multiple entity types
-- 🎯 Cache frequently accessed reference data
-- 🎯 Handle missing relations gracefully with null checks
-- 🎯 Validate enrichment and report issues
-- 🎯 Choose appropriate batch sizes (50-100 typically optimal)
-
-## Next Steps
-
-Continue to [Module 5: Data Transformation](./02-core-guides-extraction-05-transformation.md) to learn how to transform enriched data using UniversalMapper and custom transformers.
+# Module 4: Data Enrichment
+
+**Level:** Intermediate
+**Estimated Time:** 20 minutes
+
+## Overview
+
+This module covers advanced GraphQL techniques for enriching extracted data with related entities, including batch queries, nested relations, and efficient enrichment patterns.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Enrich data with related entities using GraphQL
+- ✅ Use batch queries to avoid N+1 query problems
+- ✅ Extract nested relations in a single query
+- ✅ Implement efficient enrichment for large datasets
+- ✅ Handle missing or null relations gracefully
+
+## Why Enrichment Matters
+
+**Without enrichment** (flat data):
+```json
+{
+  "ref": "INV-001",
+  "productRef": "SKU-123",
+  "locationRef": "WH-001",
+  "qty": 100
+}
+```
+
+**With enrichment** (complete context):
+```json
+{
+  "ref": "INV-001",
+  "productRef": "SKU-123",
+  "locationRef": "WH-001",
+  "qty": 100,
+  "product": {
+    "ref": "SKU-123",
+    "name": "Wireless Mouse",
+    "gtin": "0123456789012"
+  },
+  "location": {
+    "ref": "WH-001",
+    "name": "Main Warehouse",
+    "type": "PHYSICAL"
+  }
+}
+```
+
+## Single Query Enrichment
+
+### Nested GraphQL Relations
+
+Extract parent and child entities in one query:
+
+```typescript
+const query = `
+  query ExtractInventoryEnriched($first: Int!, $after: String) {
+    inventoryPositions(first: $first, after: $after) {
+      edges {
+        node {
+          id
+          ref
+          productRef
+          locationRef
+          qty
+          status
+
+          # Product relation
+          product {
+            ref
+            name
+            gtin
+            description
+            catalogue {
+              ref
+              name
+            }
+          }
+
+          # Location relation
+          location {
+            ref
+            name
+            type
+            address {
+              city
+              state
+              country
+            }
+          }
+        }
+        cursor
+      }
+      pageInfo { hasNextPage }
+    }
+  }
+`;
+
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: { maxRecords: 10000 }
+});
+
+const enriched = result.data.inventoryPositions.edges.map(e => e.node);
+```
+
+**Benefits:**
+- Single API call per page
+- Consistent data snapshot
+- Reduced network overhead
+
+### Orders with Items Example
+
+```typescript
+const query = `
+  query ExtractOrdersFull($first: Int!, $after: String) {
+    orders(first: $first, after: $after) {
+      edges {
+        node {
+          id
+          ref
+          type
+          status
+          totalPrice
+          currency
+
+          customer {
+            ref
+            email
+            firstName
+            lastName
+          }
+
+          billingAddress {
+            street
+            city
+            state
+            postcode
+            country
+          }
+
+          items {
+            edges {
+              node {
+                ref
+                productRef
+                quantity
+                price
+                totalPrice
+                currency
+              }
+            }
+          }
+        }
+        cursor
+      }
+      pageInfo { hasNextPage }
+    }
+  }
+`;
+
+const result = await client.graphql({
+  query,
+  variables: { first: 50 },  // Smaller pages for complex queries
+  pagination: { maxRecords: 5000 }
+});
+```
+
+## Batch Enrichment Pattern
+
+When you can't get all data in one query, use batch enrichment to avoid N+1 queries.
+
+### The N+1 Problem
+
+**❌ BAD: N+1 queries**
+```typescript
+// 1 query to get inventory
+const inventory = await getInventoryPositions();
+
+// N queries to get each product (if we have 1000 items = 1000 queries!)
+for (const item of inventory) {
+  const product = await client.graphql({
+    query: `query { product(ref: "${item.productRef}") { name } }`
+  });
+  item.product = product.data.product;
+}
+```
+
+### ✅ GOOD: Batch Query Solution
+
+```typescript
+async function enrichInventoryWithProducts(inventory: any[]) {
+  const batchSize = 50;
+  const enriched = [];
+
+  for (let i = 0; i < inventory.length; i += batchSize) {
+    const batch = inventory.slice(i, i + batchSize);
+    const productRefs = batch.map(item => item.productRef);
+
+    // Single query for 50 products
+    const result = await client.graphql({
+      query: `
+        query GetProducts($refs: [String!]!) {
+          products(filter: { ref: { in: $refs } }, first: ${batchSize}) {
+            edges {
+              node {
+                ref
+                name
+                gtin
+                catalogue { ref name }
+              }
+            }
+          }
+        }
+      `,
+      variables: { refs: productRefs }
+    });
+
+    // Map products back to inventory items
+    const productMap = new Map(
+      result.data.products.edges.map(e => [e.node.ref, e.node])
+    );
+
+    for (const item of batch) {
+      enriched.push({
+        ...item,
+        product: productMap.get(item.productRef) || null
+      });
+    }
+  }
+
+  return enriched;
+}
+```
+
+### Multi-Entity Batch Enrichment
+
+Enrich with multiple entity types:
+
+```typescript
+async function enrichInventoryFull(inventory: any[]) {
+  const batchSize = 50;
+  const enriched = [];
+
+  for (let i = 0; i < inventory.length; i += batchSize) {
+    const batch = inventory.slice(i, i + batchSize);
+
+    // Get unique refs
+    const productRefs = [...new Set(batch.map(item => item.productRef))];
+    const locationRefs = [...new Set(batch.map(item => item.locationRef))];
+
+    // Parallel batch queries
+    const [productsResult, locationsResult] = await Promise.all([
+      client.graphql({
+        query: `
+          query GetProducts($refs: [String!]!) {
+            products(filter: { ref: { in: $refs } }, first: 100) {
+              edges { node { ref name gtin } }
+            }
+          }
+        `,
+        variables: { refs: productRefs }
+      }),
+      client.graphql({
+        query: `
+          query GetLocations($refs: [String!]!) {
+            locations(filter: { ref: { in: $refs } }, first: 100) {
+              edges { node { ref name type } }
+            }
+          }
+        `,
+        variables: { refs: locationRefs }
+      })
+    ]);
+
+    // Create lookup maps
+    const productMap = new Map(
+      productsResult.data.products.edges.map(e => [e.node.ref, e.node])
+    );
+    const locationMap = new Map(
+      locationsResult.data.locations.edges.map(e => [e.node.ref, e.node])
+    );
+
+    // Enrich batch
+    for (const item of batch) {
+      enriched.push({
+        ...item,
+        product: productMap.get(item.productRef) || null,
+        location: locationMap.get(item.locationRef) || null
+      });
+    }
+  }
+
+  return enriched;
+}
+```
+
+## Advanced Enrichment Patterns
+
+### Conditional Enrichment
+
+Only enrich items that meet certain criteria:
+
+```typescript
+async function conditionalEnrichment(inventory: any[]) {
+  // Filter items that need enrichment
+  const itemsNeedingEnrichment = inventory.filter(item =>
+    item.qty > 0 && item.status === 'AVAILABLE'
+  );
+
+  // Enrich only those items
+  const enriched = await enrichInventoryWithProducts(itemsNeedingEnrichment);
+
+  // Merge back with original data
+  const enrichedMap = new Map(enriched.map(item => [item.ref, item]));
+
+  return inventory.map(item =>
+    enrichedMap.get(item.ref) || item
+  );
+}
+```
+
+### Cached Enrichment
+
+Cache frequently accessed reference data:
+
+```typescript
+class CachedEnrichment {
+  private productCache = new Map<string, any>();
+  private locationCache = new Map<string, any>();
+
+  async enrichWithCache(inventory: any[]) {
+    // Find uncached products
+    const uncachedProductRefs = inventory
+      .map(item => item.productRef)
+      .filter(ref => !this.productCache.has(ref));
+
+    // Fetch uncached products
+    if (uncachedProductRefs.length > 0) {
+      const products = await this.fetchProducts(uncachedProductRefs);
+      products.forEach(p => this.productCache.set(p.ref, p));
+    }
+
+    // Enrich from cache
+    return inventory.map(item => ({
+      ...item,
+      product: this.productCache.get(item.productRef) || null
+    }));
+  }
+
+  private async fetchProducts(refs: string[]) {
+    const result = await client.graphql({
+      query: `
+        query GetProducts($refs: [String!]!) {
+          products(filter: { ref: { in: $refs } }, first: 1000) {
+            edges { node { ref name gtin } }
+          }
+        }
+      `,
+      variables: { refs }
+    });
+    return result.data.products.edges.map(e => e.node);
+  }
+}
+```
+
+### Deep Nesting
+
+Extract multiple levels of relations:
+
+```typescript
+const query = `
+  query ExtractProductsDeep($first: Int!, $after: String) {
+    products(first: $first, after: $after) {
+      edges {
+        node {
+          ref
+          name
+
+          catalogue {
+            ref
+            name
+            retailer {
+              id
+              name
+            }
+          }
+
+          categories {
+            edges {
+              node {
+                name
+                path
+                parent {
+                  name
+                  path
+                }
+              }
+            }
+          }
+
+          inventoryPositions {
+            edges {
+              node {
+                ref
+                qty
+                location {
+                  ref
+                  name
+                  type
+                }
+              }
+            }
+          }
+        }
+        cursor
+      }
+      pageInfo { hasNextPage }
+    }
+  }
+`;
+```
+
+## Handling Missing Relations
+
+### Graceful Null Handling
+
+```typescript
+function transformEnrichedRecord(record: any) {
+  return {
+    sku: record.productRef,
+    productName: record.product?.name || 'Unknown Product',
+    productGtin: record.product?.gtin || '',
+    warehouse: record.locationRef,
+    warehouseName: record.location?.name || 'Unknown Location',
+    warehouseType: record.location?.type || 'UNKNOWN',
+    quantity: parseInt(record.qty) || 0
+  };
+}
+```
+
+### Validation and Error Reporting
+
+```typescript
+function validateEnrichment(enriched: any[]) {
+  const issues = [];
+
+  for (const record of enriched) {
+    if (!record.product) {
+      issues.push({
+        type: 'MISSING_PRODUCT',
+        ref: record.ref,
+        productRef: record.productRef
+      });
+    }
+
+    if (!record.location) {
+      issues.push({
+        type: 'MISSING_LOCATION',
+        ref: record.ref,
+        locationRef: record.locationRef
+      });
+    }
+  }
+
+  if (issues.length > 0) {
+    console.warn(`Found ${issues.length} enrichment issues`);
+    console.warn(issues.slice(0, 10)); // Show first 10
+  }
+
+  return issues;
+}
+```
+
+## Practice Exercise
+
+**Goal**: Extract inventory positions and enrich with product and location details using batch queries
+
+**Requirements:**
+1. Extract inventory positions with basic fields
+2. Batch enrich with products (name, gtin, catalogue)
+3. Batch enrich with locations (name, type)
+4. Handle missing relations gracefully
+5. Report enrichment statistics
+
+**Solution:**
+
+```typescript
+async function extractAndEnrichInventory() {
+  // Step 1: Extract basic inventory
+  const result = await client.graphql({
+    query: `
+      query ExtractInventory($first: Int!, $after: String) {
+        inventoryPositions(first: $first, after: $after) {
+          edges {
+            node { id ref productRef locationRef qty status }
+            cursor
+          }
+          pageInfo { hasNextPage }
+        }
+      }
+    `,
+    variables: { first: 100 },
+    pagination: { maxRecords: 10000 }
+  });
+
+  const inventory = result.data.inventoryPositions.edges.map(e => e.node);
+  console.log(`Extracted ${inventory.length} inventory positions`);
+
+  // Step 2: Batch enrich
+  const enriched = await enrichInventoryFull(inventory);
+
+  // Step 3: Validate enrichment
+  const issues = validateEnrichment(enriched);
+
+  // Step 4: Report statistics
+  const stats = {
+    total: enriched.length,
+    withProduct: enriched.filter(r => r.product).length,
+    withLocation: enriched.filter(r => r.location).length,
+    fullyEnriched: enriched.filter(r => r.product && r.location).length,
+    issues: issues.length
+  };
+
+  console.log('Enrichment statistics:', stats);
+
+  return enriched;
+}
+```
+
+## Key Takeaways
+
+- 🎯 Use nested GraphQL relations when possible (single query)
+- 🎯 Batch enrichment avoids N+1 query problem
+- 🎯 Parallel queries for multiple entity types
+- 🎯 Cache frequently accessed reference data
+- 🎯 Handle missing relations gracefully with null checks
+- 🎯 Validate enrichment and report issues
+- 🎯 Choose appropriate batch sizes (50-100 typically optimal)
+
+## Next Steps
+
+Continue to [Module 5: Data Transformation](./02-core-guides-extraction-05-transformation.md) to learn how to transform enriched data using UniversalMapper and custom transformers.