Skip to main content

Build Audience Rules

Audience rules define the exact criteria customer records must satisfy to qualify for an audience segment. DriveMetaData provides a visual, drag-and-drop rule builder that translates complex nested Boolean logic into high-performance ClickHouse filter queries.

1. Module Overview & Business Outcomes​

The Visual Rule Builder allows operators to combine customer profile attributes, behavioral events, and predictive indicators using:

  • Root Match Modes (ALL vs. ANY): Define whether users must meet every top-level criterion or at least one.
  • Nested Rule Groups: Structure multi-condition clusters with independent evaluation logic.
  • Exclusion Logic (NOT): Suppress recent converters, churned accounts, or ineligible cohorts.
  • Granular Time Windows: Restrict behavioral actions to exact historical or rolling timeframes.

2. Prerequisites, Entitlements & RBAC​

  • Role: Requires Editor or Admin permissions to add, edit, duplicate, or delete audience conditions.
  • Catalog Access: Available catalog fields must be loaded from analytics-query-engine.
  • Lookback Limit: Time windows must not exceed the system maximum of 365 days.

3. Core Rule Architecture​

Every audience rule set is structured as a hierarchical tree:

Root Match Mode​

At the very top of the canvas, select the root evaluation mode:

  • ALL (AND): Users must qualify under every top-level condition and group. Recommended for targeted conversion campaigns.
  • ANY (OR): Users qualify if they meet any single condition or group. Recommended for broad awareness or multi-channel acquisition pools.

4. Canonical Step-by-Step Walkthrough​

Step 1: Add Conditions​

  1. Click + Add condition within the target group.
  2. Select the Source Category (e.g., Events).
  3. Select the Attribute (e.g., Event Type).
  4. Select the Operator (e.g., equals).
  5. Enter or select the Value (e.g., add_to_cart).

Step 2: Configure Lookback Time Windows​

For behavioral events, commerce actions, or touchpoints, specify the evaluation window:

  • Preset Durations: Select in last 7 days, in last 30 days, in last 90 days, or in last 365 days.
  • Rolling Ranges: Configure dynamic spans like from 7 days ago to now or now to 2 weeks from now for forward-looking event triggers.

Step 3: Add Nested Groups​

When requirements require mixed logic (e.g., (In India AND purchased) AND (Came from Google OR Facebook)):

  1. Click + Add group.
  2. Set the group match mode to Match all (ALL) or Match any (ANY).
  3. Add the individual conditions inside the nested container.

Step 4: Add Exclusion Logic (NOT)​

To remove ineligible customers:

  1. Click + Add group and toggle the container mode to Exclude matches.
  2. Add the conditions that define disqualified users (e.g., Event Type equals purchase in last 30 days).
  3. Any user matching these criteria is subtracted from the final audience population.

Step 5: Duplicate or Reorder Conditions​

  • Click the Copy icon on any condition card to duplicate its settings for fast variant creation.
  • Click the Trash icon to delete obsolete rules.
  • Use Clear all to wipe the canvas and restart from scratch.

5. Supported Operators by Data Type​

Data TypeSupported OperatorsUsage Example
Stringequals, notEquals, in, notIn, isSet, isNotSetCustomer.country in ['India', 'UAE']
Number & Moneyequals, notEquals, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, between, isSet, isNotSetOrders.purchaseCount greaterThanOrEqual 2
Date & Timeequals, before, after, between, isSet, isNotSetCustomer.createdAt after '2026-01-01'
Booleanequals, notEqualsCustomer.isSubscribed equals true

6. Canonical Business Recipes​

Recipe 1: High-Intent Cart Abandoners (30 Days)​

  • Goal: Recover potential buyers who added items to their shopping cart but failed to complete checkout.
  • Root Match Mode: ALL (AND)
  • Condition 1 (Inclusion): Events.eventType equals add_to_cart with time window in last 30 days.
  • Group 2 (Exclusion / NOT): Events.eventType equals purchase with time window in last 30 days.

Recipe 2: Churn-Risk VIP Customers​

  • Goal: Retarget high-value accounts showing declining activity.
  • Root Match Mode: ALL (AND)
  • Condition 1: Orders.totalRevenue greater than 500.
  • Condition 2: Prediction.churnRisk equals High.
  • Group 3 (Exclusion / NOT): Events.eventType equals session_start with time window in last 14 days.

7. Troubleshooting & Error Playbook​

SymptomProbable Root CauseActionable Resolution
Validation error: missing_filtersAn empty group card exists on the canvas without any configured conditions.Add at least one condition to the group or delete the empty group card.
Validation error: invalid_date_rangeA condition time window exceeds the maximum allowed 365 days.Reduce the time window to 365 days or fewer.
Zero matching users returnedConflicting inclusion conditions in an ALL (AND) group (e.g., Country = India AND Country = UAE).Change the group mode to ANY (OR) or check that conditions do not contradict one another.
JSON does not match visual canvasChanges were made in the raw JSON editor without submitting or validating.Switch back to Visual Builder and use the interactive controls to update rules safely.

8. Downstream Handoff & Next Steps​