Building Foreign Key Validation Rules
Foreign key validation rules ensure that relationships between entities remain valid by verifying that referenced records exist.
By default, a foreign key rule validates all foreign key fields on an entity. You can now optionally limit validation to a subset of foreign keys, allowing more targeted and efficient validation.
Foreign Key Validation Scope
Foreign key rules can operate in two modes:
Validate all foreign keys (default)
- Applies validation across every foreign key field on the entity.
- Includes any new foreign key fields added to the entity automatically.
- If a foreign key is removed from the model, validation continues without requiring updates.
- Requires no additional configuration.
- Maintains backward compatibility with existing rules.
Validate selected foreign keys
- Limits validation to only the chosen foreign key fields.
- Newly added foreign key fields are not included automatically and must be explicitly selected.
- If a foreign key is removed from the model but still exists in the selected scope, validation may fail until the rule is updated.
- Useful when only certain relationships are relevant.
- Reduces unnecessary validation overhead.
Benefits of Scoped Validation
Scoping foreign key validation provides:
- Useful when many FKs exist — Avoid validating irrelevant relationships.
- Clearer intent — Rules focus only on critical dependencies.
- Better scalability — Particularly useful for entities with many foreign key fields.
What Remains Unchanged
- The meaning of foreign key validation itself.
- Existing rules continue to validate all foreign keys unless modified.
- Custom (non-foreign key) validation rules are unaffected.
When to Use Scoped Validation
Use subset selection when:
- Only specific relationships impact data quality.
- Validation runtime needs to be optimized.
Create and Configure a Foreign Key Validation Rule
Foreign key validation rules ensure that relationships between entities remain valid by verifying that referenced records exist. You can create and configure these rules using a single modal and optionally limit validation to specific foreign key fields.
Before you begin
- Ensure you have permission to create validation rules.
- Confirm your environment includes the updated foreign key rule experience.
Create a foreign key rule
- Navigate to Data Validation for your pipeline or entity.
- Select Add rule.
- Choose the rule type:
- Foreign key rule — opens the configuration modal.
- Custom rule — follows the existing workflow.
Configure the rule
All configuration is completed within a single modal. Complete the following sections in the modal.
Select the target entity
- Choose the entity (type) to which the rule applies.
- The available foreign key fields are loaded based on the selected entity.
If the selected entity has no foreign key fields, foreign key validation cannot be configured and the rule cannot be saved.
Define foreign key validation scope
Use the foreign key selection section to control which relationships are validated.
- By default, Validate selected foreign keys only is turned off.
- All foreign keys on the entity are validated.
- Any foreign keys added in the future are automatically included.
- Turn on Validate selected foreign keys only to limit validation.
- Select the foreign key fields to include using the Include in validation checkboxes.
- Only the selected fields are validated.
- Foreign keys added in the future are not included automatically.
You must select at least one foreign key when selective validation is enabled.
Configure additional settings
Provide any additional rule configuration as needed, such as:
- Validation scope
- Optional schedule
- Rule name
- Notifications
- Advanced configuration
Save the rule
- Select Save to create the rule.
- Select Cancel to exit without saving.
Edit an existing rule
- Open the rule from the Data Validation interface.
- Update foreign key validation (toggle and Include in validation), and any other settings such as name, schedule, notifications, or advanced configuration.
- Save your changes.
If Validate selected foreign keys only is turned off, the rule validates all foreign keys on the entity.
Results
After creating or updating the rule:
- Validation runs as part of your standard workflow.
- If selective validation is enabled, only the chosen foreign keys are evaluated.
- Otherwise, all foreign keys are evaluated.
- Results appear in the same validation views as before.
Tips
- Use Validate selected foreign keys only when you need to focus on specific relationships.
- Leaving selective validation off ensures all current and future foreign keys are validated.
- If the foreign key rule option is not visible, verify your permissions and environment version.