# Definition Builder Guide

> Step-by-step guide to creating DQS Definitions using the 5-step wizard. Configure objects, fields, thresholds, and dimension weights.

Source: https://dataqualitysense.com/resources/using-dqs/definition-builder/
Last updated: 2026-06-03

---

## What is a Definition?

A Definition is your configured data quality check in DQS. It specifies which Salesforce object to analyze, which fields to include, which capabilities to measure, and what thresholds to apply.

Think of a Definition as a recipe. You tell DQS what ingredients (fields) to examine and what standards (thresholds) to apply. DQS follows your recipe each time you run a scan.

## The 5-Step Wizard

The Definition Builder guides you through five steps:

1. **Select Capabilities** - Choose what to measure
2. **Define Scope** - Pick which object and fields
3. **Add Filters** - Narrow the record set (optional)
4. **Configure** - Set thresholds and options
5. **Review** - Validate and activate

Each step builds on the previous one. You can save progress at any step and return later.

## Step 1: Select Capabilities

In this step, you choose which data quality dimensions to measure.

### Available Capabilities

The wizard displays two panels:

**Data Quality (Operational Hygiene)**
- Completeness - Are fields populated?
- Validity - Do values match expected formats?
- Uniqueness - Are records distinct?
- Timeliness - Is data current?
- Consistency - Are values uniform?

**AI Readiness (Agentforce Prep)**
- PII Detection - Is sensitive data protected before AI exposure?

### Selecting Capabilities

1. Click a capability card to select it
2. The card highlights and a checkmark appears
3. Select multiple capabilities for a comprehensive analysis
4. Click again to deselect

> **Tip:** Start with 2-3 capabilities for your first Definition. You can add more later.

### Best Practice: Start Focused

Select capabilities based on your immediate goal:

| Goal | Recommended Capabilities |
|------|--------------------------|
| Improve data entry quality | Completeness, Validity |
| Find duplicates | Uniqueness |
| Clean stale records | Timeliness |
| Prepare for AI/Agentforce | All AI Readiness |
| Full data audit | All capabilities |

Click **Continue** when you've selected your capabilities.

## Step 2: Define Scope

In this step, you choose which Salesforce object and fields to analyze.

### Selecting an Object

1. Use the object picker dropdown
2. Search by object name or API name
3. Click to select the object

DQS supports standard and custom objects. The wizard displays the object label and API name to help you select the correct one.

> **Tip:** Start with a high-value object like Contact, Lead, or Account. These typically have the most data quality impact.

### Selecting Fields

After choosing an object, the wizard displays available fields.

1. Fields are grouped by type (text, number, date, etc.)
2. Click a field row to select it
3. Use the search box to find specific fields
4. Select multiple fields for analysis

The wizard shows which capabilities apply to each field based on field type:

| Capability | Compatible Field Types |
|------------|------------------------|
| Completeness | Most types (text, number, date, picklist, etc.) |
| Validity | Text, email, phone, URL, picklist |
| Uniqueness | All types |
| Timeliness | Date, DateTime only |
| Consistency | Text, picklist, email |

### Per-Field Configuration

You can set different thresholds for individual fields. This is useful when:

- Critical fields need stricter thresholds
- Some fields have unique format requirements
- Different fields have different freshness expectations

Click the gear icon next to a field to access per-field settings.

Click **Continue** when you've selected your fields.

## Step 3: Add Filters (Optional)

Filters narrow which records DQS analyzes. This step is optional but useful for large datasets or specific use cases.

### When to Use Filters

| Scenario | Filter Example |
|----------|----------------|
| Analyze only active accounts | Status = 'Active' |
| Focus on recent records | CreatedDate = LAST_90_DAYS |
| Exclude test data | Name does not contain 'Test' |
| Target specific regions | BillingCountry = 'United States' |

### Building a Filter

1. Click **Add Condition**
2. Select a field from the dropdown
3. Choose an operator (equals, contains, greater than, etc.)
4. Enter a value
5. Repeat for additional conditions

### Filter Logic

Use AND/OR logic to combine conditions:

- **AND** - All conditions must be true
- **OR** - Any condition can be true

Example: `(Status = 'Active') AND (Industry = 'Technology' OR Industry = 'Finance')`

### Record Count Preview

The wizard shows how many records match your filter. Use this to verify your filter works as expected.

- A count of 0 means no records match (check your filter)
- A very high count may need more filtering for large orgs

> **Tip:** Skip filters for your first Definition to get a full picture. Add filters later for targeted analysis.

Click **Continue** to proceed (or skip this step).

## Step 4: Configure

In this step, you set thresholds and options for each selected capability.

### Global vs Per-Field Settings

Settings apply at two levels:

1. **Global** - Default settings for all fields
2. **Per-Field** - Override settings for specific fields

Configure global settings first, then customize individual fields if needed.

### Completeness Configuration

| Option | Description | Default |
|--------|-------------|---------|
| Treat blanks as incomplete | Count whitespace-only values as missing | Yes |
| Treat placeholders as incomplete | Count N/A, TBD, Unknown as missing | Yes |
| Custom placeholder values | Add your own placeholder patterns | None |
| Threshold | Minimum acceptable completeness % | 95% |

**Example settings for Contact:**
- Threshold: 90% for optional fields
- Threshold: 99% for required fields like Email
- Placeholders: N/A, TBD, Unknown, -, .

### Validity Configuration

| Option | Description | Default |
|--------|-------------|---------|
| Pattern type | Email, URL, Fixed Length, Custom Regex | Email |
| Custom regex | Your own validation pattern | None |
| Case sensitive | Match exact case | No |
| Include blank values | Count blanks as invalid | No |

**Built-in patterns:**
- **Email** - RFC 5322 compliant format
- **URL** - HTTP/HTTPS format
- **Fixed Length** - Exact character count

### Uniqueness Configuration

| Option | Description | Default |
|--------|-------------|---------|
| Case sensitive | Treat "ABC" and "abc" as different | No |
| Threshold | Minimum acceptable uniqueness % | 95% |

### Timeliness Configuration

| Option | Description | Default |
|--------|-------------|---------|
| Freshness window (days) | Days before data is considered stale | 90 |
| Grace period (days) | Buffer before flagging as stale | 7 |
| Operational range | Min/max expected date boundaries | None |

**Example settings by field:**
- LastModifiedDate: 30-day freshness window
- LastActivityDate: 90-day window
- BirthDate: No freshness check needed

### Consistency Configuration

| Option | Description | Default |
|--------|-------------|---------|
| Expected values | List of valid values | None |
| Import from picklist | Auto-populate from field's picklist | No |
| Case sensitive | Match exact case | No |
| Top N dominant values | Show most frequent values | 5 |

### PII Detection Configuration

| Option | Description | Default |
|--------|-------------|---------|
| Pattern type | Which PII patterns to scan for | All patterns |
| Custom patterns | Add your own regex patterns for org-specific sensitive data | None |

### Processing Cost Indicator

Each capability shows a processing cost:

| Cost | Capabilities | Impact |
|------|--------------|--------|
| LOW | Completeness, Validity | Fast, minimal resources |
| MEDIUM | Timeliness, Consistency, PII Detection | Moderate processing time |
| HIGH | Uniqueness | Longer processing, more comparisons |

Consider cost when selecting capabilities for large datasets.

Click **Continue** when configuration is complete.

## Step 5: Review

The final step shows a summary of your Definition.

### Review Checklist

Verify the following before activating:

1. **Object** - Correct object selected
2. **Fields** - All important fields included
3. **Capabilities** - Appropriate checks selected
4. **Filters** - Record count looks right
5. **Thresholds** - Settings match your requirements

### Definition Summary

The summary displays:

- Definition name (editable)
- Target object and record count
- Selected capabilities with variants
- Field count by capability
- Estimated processing cost

### Naming Your Definition

Use descriptive names that indicate:
- Object being analyzed
- Purpose or scope
- Owner (optional)

**Good names:**
- "Contact Data Quality - Sales Team"
- "Lead AI Readiness Check"
- "Account Completeness - EMEA Region"

**Poor names:**
- "Definition 1"
- "Test"
- "My Definition"

### Saving and Activating

You have two options:

1. **Save as Draft** - Save without activating (editable later)
2. **Activate** - Save and make ready for scanning

Draft Definitions can be edited. Active Definitions are locked but ready to run.

## Example: Building a Contact Definition

Let's walk through creating a Contact Data Quality Definition.

### Step 1: Select Capabilities

Select:
- Completeness (check for missing data)
- Validity (verify email and phone formats)
- Timeliness (find stale contact records)

### Step 2: Define Scope

Object: Contact

Fields:
- Email (text, email)
- Phone (phone)
- MailingCity (text)
- MailingState (text)
- MailingCountry (text)
- Title (text)
- LastActivityDate (date)

### Step 3: Add Filters

Condition: `AccountId != null` (Contacts with Accounts only)

Record count preview: 15,234 records

### Step 4: Configure

**Completeness:**
- Threshold: 90%
- Treat blanks as incomplete: Yes
- Placeholders: N/A, Unknown, TBD

**Validity:**
- Email field: Email pattern
- Phone field: Phone pattern (if available)

**Timeliness:**
- LastActivityDate: 60-day freshness window
- Grace period: 14 days

### Step 5: Review

Name: "Contact Data Quality - Active Accounts"

Summary:
- 7 fields
- 3 capabilities
- 15,234 records
- Estimated cost: LOW

Click **Activate** to complete.

## Managing Definitions

### Viewing All Definitions

From the DQS home screen, you see:
- All your Definitions
- Status (Draft, Active, Archived)
- Last scan date
- Quick actions

### Editing Definitions

- **Draft** - Fully editable
- **Active** - Create a new version to edit
- **Archived** - View-only

### Archiving Definitions

Archive Definitions you no longer need:
1. Click the dropdown menu
2. Select **Archive**
3. Confirm

Archived Definitions remain viewable but cannot run.

## Troubleshooting

### "No fields available"

**Cause:** Selected capabilities don't match available field types.

**Solution:** Select different capabilities or choose an object with compatible field types.

### "0 records match filter"

**Cause:** Filter conditions are too restrictive.

**Solution:** Adjust filter values or remove conditions.

## Next Steps

- [Running Scans](/resources/using-dqs/running-scans/): Execute your Definition
- [Understanding Results](/resources/using-dqs/understanding-results/): Interpret scan outputs