Run breakers abort a connector run if a specified condition is met. Each run breaker evaluates a mathematical statement against the results of the run before any changes are applied, meaning if a run breaker triggers, zero entities will be created, updated, deleted, or otherwise processed.
Up to three run breaker conditions can be configured per connector. If any condition is met, the run is aborted. An aborted run means that the connector run will not execute and the connector will not process any changes.
Changes to be made during each connector run are calculated before they are executed, meaning that the run breaker conditions are evaluated against the connector run before any changes are made. If any run breaker conditions are met, all counts for that run (entities updated, deleted, created, failed, and unchanged) will be 0.
Configuration
Each run breaker condition is made up of four components:
1. Comparator
How the threshold value should be compared to the run result:
- Exactly
- Greater than
- Greater than or equal to
- Less than
- Less than or equal to
2. Absolute or Relative Count
The threshold can be expressed as an absolute number (e.g., 10 entities) or a relative percentage (e.g., 50% of entities).
3. Entity Set
The set of entities the run breaker evaluates against:
- The run: all entities present in the current connector run (those that would be created, updated, unchanged, or failed if the run completed)
- Saved filter: all entities within a chosen saved filter
- Comprehensive set: all entities ever created by this connector. This option only applies to Comprehensive Mode runs. When using Comprehensive Mode, entities missing from the set are deleted from the Knowledge Graph.
When using a relative value in a run breaker condition, the chosen entity set represents 100%, or the total value of the entities available to evaluate.
4. Update Type
The state or condition of entities to check within the chosen set. Options vary by entity set:
The Run
- New — entities that will be newly created in the Knowledge Graph
- Exist — entities that already exist in the Knowledge Graph
- Present in the source — the total number of entities in the run (new and existing)
- Have mapped field — entities with a certain value for a specified mapped field, using: is blank, is not blank, equals, contains, starts with, or ends with
Saved Filter
- Present in the source — entities in the run that are also in the saved filter
- Have mapped field — entities in the run that are in the saved filter and have a certain value for a specified mapped field, using the same comparators as above
Comprehensive Set
- Missing — entities absent from the comprehensive set that may be deleted in Comprehensive Mode runs
Examples Run Breaker Configurations
- Exactly 25% of entities in the run are new
- Greater than 10 entities in the comprehensive set are missing
- Less than 10 entities in "New York Locations" are new
Details & Limitations
Dropped Rows
A dropped row is a row that encounters an error during the Transform stage and is excluded before the Mapping stage. Rows with missing entity IDs can also be dropped. Dropped rows do not count toward the entity set total used in run breaker calculations, which can affect whether a condition is triggered.
Dropped rows do not count toward the total number of entities considered in the entity set on a run breaker. As a result, this can impact whether a run breaker condition is triggered.
Below is an example of two runs on a connector with a run breaker configured, where five rows were dropped during each run.
Example — Run breaker: Greater than 10 entities in the run are new
| Total Entities in Run | Total New Entities | Dropped Rows | New Entities Processed | Run Breaker Triggered | Run Status |
|---|---|---|---|---|---|
| 50 | 14 | 5 | 9 | No | Completed |
| 50 | 25 | 5 | 20 | Yes | Aborted |
In the first run above, a user might expect the breaker to trigger (14 new entities total), but because 5 rows were dropped, only 9 were processed, falling below the threshold. It is recommended to build in some leeway in your thresholds to account for occasional dropped rows.
Mapped Field Limitations
The following fields are not supported in "mapped field" update type conditions:
- Categories
- Keywords
- Folders
Other limitations include:
- Any list fields or complex fields that include a list-type are not supported.
- When comparing values, only the values of primitive types (and subfields of primitive types) can be compared. Structs or any non-primitive types as an entire field value cannot be compared.
Run Modes
Run breakers using the comprehensive entity set only apply to Comprehensive Mode runs. All other run breaker configurations are not tied to a specific run mode.