Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
Enterprise only

Explain a Specific Cluster

Run the explain phase for a specific Zingg ID to see exactly how that cluster was formed.

Enterprise only. Requires a completed match or runIncremental phase before running.

The explain phase takes a Zingg ID as input and returns the pair-level evidence for how that cluster formed. You can see which record pairs were compared, what their similarity scores were, and how transitive matching connected records through intermediate pairs.

Step 1: Import

from zingg.client import *
from zingg.pipes import *
from zinggEC.enterprise.common.EArguments import *
from zinggEC.enterprise.common.epipes import *
from zinggEC.enterprise.common.EFieldDefinition import EFieldDefinition
from zinggEC.enterprise.common.ExplainArguments import *
from zinggEC.enterprise.common.EClientOptions import *
from zinggES.enterprise.spark.ESparkClient import *

Step 2: Set up the base arguments

Use the same arguments setup. All field definitions, pipes, modelId, and zinggDir must match the original match run exactly.

args = EArguments()
args.setModelId("your-model-id")
args.setZinggDir("/tmp/models")
# ... same field definitions and pipes as your original match run

Step 3: Wrap the arguments and set where the explain output goes

explain needs a pipe telling it where to write the result.

Step 4: Set the phase and the Zingg ID to explain

Find Zingg IDs in the ZINGG_ID column of your match output. The Zingg ID is passed as a client option alongside the phase.

Step 5: Run the explain phase

Step 6: Read the explain output

Read from wherever you pointed explainOutput in Step 3 — a CSV path here, but it can be any pipe format (parquet, Snowflake table, etc.).

The output shows pair-level evidence for how the cluster formed. Each row is a record pair.

Using the CLI instead of Python API

Create an explainConfig.json and run with the --zinggid flag:

explainConfig.json

CLI command

Same requirements apply: a completed match or runIncremental phase, and results cover probabilistic matches only.

Run explain on Snowflake the same way as other phases — via the local CLI script, pointing at a Snowflake-flavored explainConfig.json and your Snowflake connection properties.

explainConfig.json

CLI command

The explainOutput result is written to the Snowflake table configured in props.table (EXPLAIN_CUSTOMERS above).

Last updated

Was this helpful?