Validate, Estimate, and Preview

Before saving or deploying an audience segment to production marketing campaigns, DriveMetaData provides a verification loop to confirm rule integrity, calculate accurate reach figures, and inspect real customer records.

---

1. Module Overview & Business Outcomes

The verification subsystem consists of three interdependent stages:

1. Rule Validation: Verifies that rule logic, catalog attributes, operators, and date intervals conform to backend analytical contracts.
2. Size Estimation: Scans ClickHouse columnar data to calculate matching customer counts and rule impact waterfalls without transferring row payloads.
3. Record Preview: Renders paginated sample customer rows to visually confirm that the targeted population aligns with marketing intent.

---

2. Prerequisites, Entitlements & RBAC

Operation	Required Role	Security / Context Requirements
Validate	Viewer, Editor, Admin	Valid Client-ID and Workspace-ID tenant headers.
Estimate	Viewer, Editor, Admin	Valid rule structure with no blocking syntax errors.
Preview (Standard)	Viewer, Editor, Admin	At least one returnable preview attribute selected. Non-PII fields only.
Preview (Raw PII)	Editor, Admin with pii_read	Requires X-Audience-PII-Access: true header clearance to view unmasked emails or phones.

---

3. Canonical Step-by-Step Walkthrough

Step 1: Run Rule Validation

1. After configuring conditions, click Validate in the top header.
2. If syntax errors exist, the status updates to Needs fixes. Review the error list in Audience Summary and click any issue to focus the offending condition card.
3. Once all conditions are complete and valid, the status badge transitions to Valid.

Step 2: Compute Reach Estimation

1. Click Estimate in the top header (or within the summary card).
2. The engine executes a vectorized count across ClickHouse and populates the Audience Summary panel:
   • Estimated Audience Size: The net unique qualifying customers.
   • Included Users: Raw positive matches before exclusions.
   • Excluded Users: Volume removed by negative (NOT) groups.
   • Total Workspace Users: The baseline customer population for percentage calculations.
   • Impact Waterfall: Condition-by-condition funnel displaying the incremental drop-off caused by each filter rule.

Step 3: Inspect Matching Preview Records

1. Open the Audience Attributes drawer on the right and check the columns you wish to inspect (e.g., Customer.name, Customer.country, Orders.purchaseCount).
2. The Preview Users grid at the bottom loads live customer rows matching the rule definition.
3. Use the page-size selector to view 10, 20, 50, or 100 records per page.
4. Verify that the displayed users match your target profile (e.g., confirming country values or order histories).

---

4. Operational Guardrails & Limits

• 365-Day Time Limit: Global evaluation dates and individual lookback windows cannot exceed 365 days.
• Preview Pagination Capping: Sample preview rows are restricted to a maximum of 100 rows per request to avoid memory exhaustion and browser latency.
• Stale State Management: If you alter any condition, operator, value, or date range after running an estimate, the UI flags the reach metric as Estimate stale, requiring a re-run before saving.
• PII Redaction Policy: Direct PII fields (Customer.email, Customer.mobile) are automatically masked (e.g., a***@example.com) unless explicit administrative PII access clearance is enabled.

---

5. Interpreting the Audience Summary Panel

The Audience Summary sidebar provides real-time health metrics for your segment:

Use the Rule Impact Waterfall to diagnose rules that shrink the audience too aggressively. If step 3 drops the reach to zero, review that condition's operator or time window.

---

6. Troubleshooting & Error Playbook

Symptom	Probable Root Cause	Actionable Resolution
Validation fails with missing_filters	An empty rule container was left in the tree.	Delete the empty rule block or add at least one condition.
Validation fails with invalid_date_range	Start date is later than end date, or window exceeds 365 days.	Normalize the date range in the page date filter.
Estimation returns 0 records	Overlapping exclusion rule removes the entire population.	Temporarily remove the exclusion group and re-estimate to isolate the conflict.
Query times out after 30 seconds	High-cardinality multi-join condition without an index or lookback window.	Add a time window (e.g., last 30 days) to restrict the scan range on behavioral events.
Preview table says "No attributes selected"	Output columns have not been chosen in the attributes panel.	Open the Audience Attributes drawer and select at least one returnable column.

---

7. Downstream Handoff & Next Steps

• Manage Preview Attributes: Customize, reorder, and persist preview table columns.
• Save, Export, and AI Generation: Save validated definitions or export sample CSV files.
• Audience Query Payload Schema: Review the backend /validate and /preview payload contracts.