Step 3: Query

Step 7: Monitor Execution Progress

Watch the execution in real time:

akili run status customer-orders --follow

Expected output:

Run: 2026-03-14T10:30:00Z
  [10:30:01] Inputs resolved: cleaned-customers (cached), cleaned-orders (fresh)
  [10:30:02] Engine selected: DuckDB (input size: 2.3 GB)
  [10:30:03] Executing logic/transform.sql...
  [10:30:15] Transform complete. 847,231 rows produced.
  [10:30:16] Quality checks running...
  [10:30:17]   customer_id_complete     PASS
  [10:30:17]   unique_customer_day      PASS
  [10:30:17]   data_freshness           PASS
  [10:30:17]   revenue_non_negative     PASS
  [10:30:17]   orders_non_negative      PASS
  [10:30:18]   valid_customer_ref       PASS
  [10:30:18]   row_volume               PASS
  [10:30:18]   avg_matches_total        PASS
  [10:30:18]   revenue_consistent       PASS
  [10:30:18] Quality: 9/9 passed
  [10:30:19] Writing to serving stores...
  [10:30:19]   Lakehouse       written (source of truth)
  [10:30:20]   Lookup store    847,231 rows upserted
  [10:30:20]   Analytics       catalog registered (no data movement)
  [10:30:21]   Real-time cache 847,231 keys written (TTL: 24h)
  [10:30:21] Materialization complete.
Status: SUCCESS  Duration: 21s

---

Step 8: Query Results via Serving Endpoints

With the product materialized and quality checks passed, data is available through all three serving endpoints.

Lookup (single record)

# Fetch a specific customer's orders for today
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.akili.example.com/api/v1/products/customer-orders/latest?filter=customer_id:CUST-123"

Response:

{
  "data": {
    "customer_id": "CUST-123",
    "customer_name": "Jane Mwangi",
    "email": "jane@example.com",
    "order_date": "2026-03-14",
    "total_orders": 3,
    "total_revenue": 4520.00,
    "avg_order_value": 1506.67,
    "first_order_at": "2026-03-14T08:15:00Z",
    "last_order_at": "2026-03-14T14:30:00Z",
    "updated_at": "2026-03-14T10:30:19Z"
  }
}

Analytics (aggregation)

-- In Superset SQL Lab or any SQL client connected to the analytics engine
SELECT
    order_date,
    COUNT(DISTINCT customer_id) AS active_customers,
    SUM(total_orders) AS total_orders,
    SUM(total_revenue) AS total_revenue,
    AVG(avg_order_value) AS avg_order_value
FROM lakehouse_myorg.commerce.customer_orders
WHERE order_date >= '2026-03-01'
GROUP BY order_date
ORDER BY order_date;

Realtime (cache)

# Fetch live data for a specific customer
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.akili.example.com/api/v1/products/customer-orders/realtime?key=customer:CUST-123:orders:2026-03-14"

Response:

{
  "customer_id": "CUST-123",
  "order_date": "2026-03-14",
  "total_orders": 3,
  "total_revenue": 4520.00
}

---

Step 9: Check Quality Scores

View the quality history for your product:

akili product quality customer-orders

Expected output:

Quality Report: customer-orders
  Score: 100% (9/9 checks passing)
  Last checked: 2026-03-14T10:30:18Z

  Check                    Status  Severity  Last Result
  customer_id_complete     PASS    error     1.0 (threshold: 1.0)
  unique_customer_day      PASS    error     0 duplicates
  data_freshness           PASS    error     age: 18s (max: 6h)
  revenue_non_negative     PASS    error     min: 0.00
  orders_non_negative      PASS    error     min: 0
  valid_customer_ref       PASS    error     100% referenced
  row_volume               PASS    warn      847,231 rows
  avg_matches_total        PASS    error     100% consistent
  revenue_consistent       PASS    error     0 inconsistent

---

Step 10: View in the Discovery Catalog

The product is now discoverable in the data catalog and the Portal:

# Search for the product
akili search "customer orders"

The Portal displays:

• Product metadata (owner, domain, classification, tags)
• Output schema with column descriptions and roles
• Lineage graph showing upstream dependencies and downstream consumers
• Quality score trend chart
• Serving endpoint status
• Recent materialization history

---

What Happens Next

With the product deployed:

• Automatic execution: The product materializes automatically whenever cleaned-customers and cleaned-orders are both available for the current partition
• Quality enforcement: Every materialization runs all 9 quality checks. Failures on error-severity checks block downstream products.
• Lineage tracking: The catalog maintains full provenance from source systems through transformations to serving endpoints
• Version management: Update the product by bumping the version in product.yaml and redeploying. Minor changes (add nullable column) are non-breaking. Major changes (remove column) require downstream consumers to update.

---

Troubleshooting

Problem	Likely Cause	Fix
Validation fails on classification	Output classification lower than max input	Set classification in product.yaml to at least the highest input classification
Execution stuck in WAITING	One or more inputs not yet materialized	Check upstream product status with akili product status cleaned-orders
Quality check fails	Data does not meet threshold	Check the specific check output, adjust thresholds or fix source data
Serving endpoint empty	Materialization succeeded but quality blocked serving writes	Check quality results — a blocking check may have failed
Deploy fails with 409	Product name+version already exists	Bump the version or use akili product update

---

Next Steps

• Manifest Authoring — Deep dive into each manifest file
• Ingestion Patterns — Build source-aligned products with connectors
• Quality Rules — Advanced quality patterns
• Serving Configuration — Tune endpoints for your access patterns
• Governance — Classification, retention, and compliance