Business identification rules

Prerequisites

At least one entity type has been created in the current model. For more information, see Create an entity type.

Background information

The role of a business identification rule varies depending on the primary key mode.

Permissions

Workspace administrators and modelers can create and manage business identification rules.

Create a business identification rule

1. In the top menu bar of the Dataphin homepage, choose Knowledge Graph > Model Design.

2. In the top navigation bar, select a workspace. In the model configuration repository on the left, click an entity type name, and then in the Entity Type Configuration panel, click Configure Business Identification Rule at the top.

3. Below the list of business identification rules, click Create Identification Rule. The list displays all existing identification rules.

   Multiple rules are evaluated in parallel, and the highest score is used. If there is a tie, the rule that appears first in the list takes precedence. The list includes the rule name, identification attributes, matching threshold, auto-association threshold, and status. Click Rule Matching Preview to enter test data and validate the rule's matching results.

4. In the Create Business Identification Rule dialog box, configure the following parameters.

   Parameter	Description
   Rule Name	Enter a display name for the rule. The name can be up to 64 characters long and contain any character.
   Identification Attribute Configuration	Attribute Name: Select from all available attributes of the current entity type. Each attribute can only be selected once. Data Type: Displays the data type of the selected attribute. This field is read-only. Matching Policy: Includes Exact Match, Fuzzy Match (Edit Distance), Fuzzy Match (Containment), Equals, Numeric Range Match, Date Range Match, and Semantic Similarity Match. Exact Match: Attribute values must be identical (case-sensitive). This policy applies to String, RegexString, Enum, URL, and Email data types. Fuzzy Match (Edit Distance): Calculates similarity based on the Levenshtein edit distance. This policy applies to String and RegexString data types. When you select this policy, you must also configure the Policy Configuration (Similarity Threshold). Note You can use this policy only after you install the Neo4j Edit Distance plugin. Fuzzy Match (Containment): Checks if one value is contained within another. This policy applies to String and RegexString data types. Equals: Attribute values must be equal. This policy applies to Integer, Float, Boolean, Date, BigInteger, Enum, and Timestamp data types. Numeric Range Match: Values match if they fall within a specified tolerance. This policy applies to Integer, Float, BigInteger, and Decimal data types. When you select this policy, you must also configure the Policy Configuration (Tolerance Value). Date Range Match: Values match if they fall within a specified number of days. This policy applies to Date and Timestamp data types. When you select this policy, you must also configure the Tolerance in Days. Semantic Similarity Match: Calculates text semantic similarity (cosine similarity) based on Large Language Model (LLM) embeddings. This policy applies only to the String data type. When you select this policy, you must also configure the Policy Configuration (Similarity Threshold). Note This matching policy is available only if semantic detection is enabled for the selected identification attribute. The semantic similarity match policy uses the vector model configured for the entity's workspace. Policy Configuration: For Fuzzy Match (Edit Distance) and Semantic Similarity Match policies, you must enter a Similarity Threshold. The default value is 0.8. For the Numeric Range Match policy, you must enter a Tolerance Value. The default value is 0 for Integer types and 0.01 for Float types. For the Date Range Match policy, you must enter the Tolerance in Days. The default value is 0. Weight: You must configure a weight for each identification attribute. The sum of all attribute weights must be 1. Note You can add up to 5 identification attributes to a single rule.
   Global Threshold Settings	Overall Matching Threshold: Enter a threshold for the weighted composite score of all attributes (range [0.0, 1.0]). The default value is 0.8. When the composite score reaches this threshold, the result becomes a candidate match. Auto-association Threshold: After selecting Enable Auto-association, you can enter an auto-association threshold (range [0.0, 1.0]). The default value is 0.95. When the composite score reaches this threshold, the system automatically associates the new entity with the existing one.

5. Click OK to finish configuring the rule.

Multi-rule evaluation and priority

When multiple business identification rules are configured for the same entity type, the disambiguation engine operates in two phases: candidate recall and score aggregation.

1. Candidate recall and candidate pool construction

   Each enabled rule independently performs a recall query, returning a set of candidates rather than a single candidate.

   For example, when using a rule based on name and birth year to query for Zhang San 1990, if multiple duplicate entities already exist in the knowledge graph, the query may match several entity IDs simultaneously.

   Candidate set from Rule 1 = [ (ID=1001, score=0.92), (ID=1002, score=0.88), … ]
   Candidate set from Rule 2 = [ (ID=1001, score=0.75), (ID=1003, score=0.82), … ]
   Candidate set from Rule 3 = [ (ID=1002, score=0.90), … ]

   The engine takes the union of candidates from all rules and deduplicates by entity ID to form the candidate pool. If a candidate is matched by multiple rules, the engine retains the score from each rule independently for the subsequent aggregation step.

   Candidate Pool = {
     ID=1001: { Rule 1: 0.92, Rule 2: 0.75, Rule 3: no hit },
     ID=1002: { Rule 1: 0.88, Rule 2: no hit, Rule 3: 0.90 },
     ID=1003: { Rule 1: no hit, Rule 2: 0.82, Rule 3: no hit },
     …
   }

   Note

   Each rule recall returns the top-K candidates (default: 50, adjustable at the workspace level). After deduplication, the candidate pool has a maximum size of 200. If this limit is exceeded, candidates are truncated in descending order of their recall score.

2. Parallel evaluation for each candidate in the pool

   After the candidate pool is constructed, the engine runs all enabled rules to evaluate each candidate entity in the pool in parallel. For any rule that did not initially match a candidate, the system backfills the score to ensure that every candidate has a score from every rule.

   Score set for candidate entity X = { Rule 1: 0.92, Rule 2: 0.75, Rule 3: 0.88 }

3. Independent rating based on rules

   Each rule independently determines a rating for a candidate based on its own thresholds, not by comparing scores across different rules.

   Rule rating	Condition
   Auto-association	Rule score ≥ the rule's Auto-association Threshold
   Candidate Match	the rule's Overall Matching Threshold ≤ Rule score < the rule's Auto-association Threshold
   No Match	Rule score < the rule's Overall Matching Threshold

4. Rating aggregation

   The engine determines a final rating for each candidate entity, which can be Auto-association, Candidate Match, or No Match.

5. Final sorting and handling of ties in the candidate pool

   Steps 1-4 explain how to aggregate multiple rules for a single candidate. However, when multiple entities in the candidate pool share the highest rating (often due to historical duplicate data or overly broad rules), the system does not arbitrarily pick one. Instead, it strictly follows the rules below:

   Sorting keys for candidates (compared in descending order of priority):

   1. Final rating (descending): Auto-association > Candidate Match > No Match

   2. Display score (the raw score of the winning rule), in descending order.

   3. Winning rule priority, in ascending order (rules appearing earlier in the list have higher priority).

   4. Entity ID, in ascending lexicographical order (used only as a stability fallback to ensure identical results for identical inputs, not for business semantic decisions).

   The system handles the outcome based on the number of candidates that are truly tied at the highest rating (that is, their first three sorting keys are identical, and only the ID differs):

   Highest rating	True tie count	Action	Final state
   Auto-association	1 (unique)	Automatically associate with this candidate.	Auto-association
   Auto-association	≥ 2	Auto-association is prohibited. The system downgrades the overall status to Candidate Match. The system displays all tied candidates for the user to choose from.	Candidate Match
   Candidate Match	1 to N	Enter the candidate matching flow. The system displays the top-K candidates (default: 5) in sorted order.	Candidate Match
   No Match	-	If the pool contains no valid candidates, the system creates a new entity based on the primary key mode.	No Match

6. Handling of disabled rules

   Disabled rules do not participate in candidate recall or evaluation, and do not affect the candidate pool construction or the final decision. Disabling all rules is equivalent to having no rules configured.

   Note

   You can still select a disabled rule in the disambiguation settings of the Offline Integration-Knowledge Graph Output component.