Skip to main content

Fields and Saved Audiences

The Fields & Audiences panel provides the data foundation for all audience segmentation in DriveMetaData. Located on the left side of the workspace, it enables marketers and analysts to explore the real-time field catalog, search available column values, define custom dimensions, and load previously saved audiences.

1. Module Overview & Business Outcomes​

The panel is divided into two primary tabs:

  • Fields Tab: Catalogs all customer traits, behavioral events, commerce metrics, and machine learning predictions ingested into the tenant's data layer.
  • Audiences Tab: Houses the repository of saved audience definitions, allowing rapid reuse, template cloning, and variant creation without rebuilding rules from scratch.

2. Prerequisites, Entitlements & RBAC​

Role / EntitlementCapability in Catalog
ViewerSearch and browse fields; inspect saved audience definitions.
EditorAdd fields to rule builder; search dynamic field values; create custom fields; save and update audiences.
AdminDelete saved audiences; configure underlying source mappings and tenant-wide field schemas.

3. Field Catalog Architecture & Categories​

The backend dynamically exposes attributes organized into six business entities:

CategorySource EntityExample AttributesCharacteristics
CustomerCustomer.*Country, City, Lifecycle Stage, Gender, AgeStatic or slowly changing customer profile traits. Do not require time windows.
OrdersOrders.*Purchase Count, Total Revenue, Average Order ValueAggregated transaction statistics.
Commerce DetailscommerceDetails.*Product Category, SKU, Cart ValueGranular item-level commerce data. Requires time window.
Eventsevents.*Event Type, URL, Device Type, Screen ViewReal-time digital event telemetry. Requires time window.
Touchpointstouchpoint.*UTM Source, Campaign, Medium, Ad IDInbound marketing attribution channels. Requires time window.
PredictionsPrediction.*Churn Risk Score, LTV Band, Propensity to BuyMachine-learning generated scores and risk indicators.

Field Metadata Attributes​

Each field in the catalog contains critical metadata determining how it behaves in the builder:

  • member: The programmatic path used in JSON payloads (e.g., Customer.country, Orders.purchaseCount).
  • title: The human-readable label displayed in the UI (e.g., "Country", "Purchase Count").
  • type: Data type (string, number, money, time, boolean), dictating which input controls and operators appear.
  • requiresTimeWindow: When true, forces the condition to specify an evaluation lookback window (e.g., "in last 30 days").
  • returnable: Indicates whether this field can be selected as a visible column in the preview table.
  • piiClass: Privacy level (none vs. direct_pii).

4. Canonical Workflows​

Workflow A: Adding a Catalog Field to the Builder​

  1. Click the Fields tab in the left drawer.
  2. Use the search box or filter buttons (Customer, Events, Orders, Predictions) to locate the desired attribute.
  3. Click on the field card. The system automatically inserts a new condition card into the active rule group on the canvas, pre-populating the source and attribute name.

When selecting a string attribute (such as Customer.country or touchpoint.source), you can search real values stored in ClickHouse:

  1. Open the Value dropdown on the condition card.
  2. Type at least 2 characters (e.g., ind).
  3. The UI queries and renders matching options with estimated customer frequencies.
  4. Select the matching item to populate the filter.

Workflow C: Creating a Custom Field​

If a specific calculated attribute or composite dimension is not available in the default catalog:

  1. Click + Create Custom Field at the top of the catalog.
  2. Enter a Field Name and select the Base Entity (Customer, Orders, or Events).
  3. Specify the data type and computation logic.
  4. Click Create Field. The new field immediately becomes available in your tenant catalog under the Custom filter.

Workflow D: Loading or Deleting Saved Audiences​

  1. Switch to the Audiences tab in the left drawer.
  2. Search by audience name or filter by creation date.
  3. Click any audience item to load its saved rules, date filters, and attribute configurations onto the canvas.
  4. To delete an obsolete audience, hover over the item, click the Trash icon, and confirm deletion.
warning

Deleting a saved audience permanently removes its definition from PostgreSQL. Before deleting, verify that no active ad syncs or automated campaigns depend on this audience ID.

5. Validation Rules & Operational Guardrails​

  • PII Search Restriction: Direct PII fields (such as Customer.email or Customer.mobile) intentionally disable dynamic value dropdown lookups. Users must enter exact text or regex values to prevent bulk discovery of sensitive contact data.
  • Debounce & Query Limits: Dynamic value search triggers a 300ms debounce to protect database performance. Results are capped at a maximum of 20 options (with a system hard ceiling of 100).
  • Behavior Time Requirement: If an attribute has requiresTimeWindow = true, you must configure a lookback duration before the rule can pass validation.

6. Troubleshooting & Error Playbook​

SymptomProbable Root CauseActionable Resolution
Value dropdown displays "No values found"Search string does not match any records in the lookback window, or data has not synced.Verify spelling; broaden the global evaluation date range or type the value manually.
Catalog fails to load with error messageBackend network failure or missing tenant authentication headers.Verify network connectivity; click Retry Catalog or re-authenticate your workspace session.
Field is disabled for selectionField is marked as non-returnable or requires upstream data source configuration.Consult the data engineering team to map the source table in the query engine catalog.
Cannot delete saved audienceUser role lacks Admin privileges or audience is currently locked by an active campaign.Request deletion permission from a workspace administrator.

7. Downstream Handoff & Next Steps​