> For the complete documentation index, see [llms.txt](https://docs.zingg.ai/zingg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zingg.ai/zingg/reference/configuration-schema.md). # Configuration Schema Complete reference for all Zingg JSON configuration parameters and Python API arguments. This page is the reference. Every Zingg configuration parameter, JSON key and Python API method is documented here with type, valid values, and edition availability. {% hint style="success" icon="right-long" %} **Read more**: For the step-by-step task of setting up configuration - [Configure Zingg](/zingg/running-zingg/configure-zingg.md). {% endhint %} ### Top-level parameters

Parameter	Type	Edition	Description
`modelId`	string	All editions	Unique identifier for this model. Used as folder name under `zinggDir`. Use the same `modelId` across all phases for a given run.
`zinggDir`	string	All editions	Root directory where Zingg writes model files and training data. Can be a local path, DBFS path (`dbfs:/`), GCS path (`gs://`), S3 path (`s3a://`), or OneLake path (`abfss://`).
`numPartitions`	integer	All editions	Number of Spark partitions. Controls how data is distributed across cluster nodes. Rule of thumb: set to approximately 20–30× the number of worker vCPUs. Start with 4–8 for a standard development cluster. Increase proportionally for larger datasets.
`labelDataSampleSize`	float (0.0001–0.1)	All editions	Fraction of the dataset scanned when running `findTrainingData`. Valid range: 0.0001 to 0.1. For 100k records use 0.1–0.5. For 1M+ records use 0.01–0.05. Reduce to 0.05 or lower if `findTrainingData` is slow on large datasets.
`stopWordsCutoff`	float (0–1)	All editions, optional	Used with the `recommend` phase. Fraction of high-frequency words to extract as stopword candidates. Default is `0.1` (10%).
`collectMetrics`	boolean	All editions	Controls telemetry collection. Default `true`. Set to `false` to disable. When enabled, Zingg captures runtime metrics (record count, field count, running phase, execution time). No input data or user data is ever captured. See Security and Privacy for full details.
`passthroughExpr`	string	Enterprise only, optional	SQL expression defining records to exclude from matching. Records matching this expression are carried through to output with their own Zingg ID but do not influence cluster formation. Example: `"fname = 'matilda'"`.
`deterministicMatching`	array	Enterprise only, optional	Deterministic match conditions, where exact field matches always result in a match regardless of the probabilistic score. See Deterministic vs Probabilistic Matching for full configuration.
`setBlockingModel`	string	Enterprise only, optional	Blocking strategy. Valid values: `"DEFAULT"`, `"WIDER"`. If not set, the model uses `DEFAULT`.

### `fieldDefinition` Each entry in the `fieldDefinition` array defines one field in your input schema.

Parameter	Type	Edition	Description
`fieldName`	string	All editions	Name of the field in your input dataset. Must match exactly.
`matchType`	enum	All editions	How to compare this field. See Match Types for all values.
`fields`	string	All editions	The field to use for comparison. Keep the same as `fieldName` for standard use. Can reference a different column name if the field you want to compare appears under a different name in the input schema. For now, keep this the same as `fieldName` unless specifically advised otherwise.
`dataType`	string	All editions	Spark SQL data type - `string`, `integer`, `double`, `date`, `timestamp`.
`stopWords`	string (path)	All editions, optional	Path to a CSV file of stopwords for this field. One word per row. The file must have a header row. Generated by the `recommend` phase.
`primaryKey`	boolean	Enterprise only, optional	Marks this field as the primary key. Used by `runIncremental` to identify records uniquely across runs and by `reassignZinggId` for ID preservation. Set `true` on exactly one field per config.
`postProcessors`	string	Enterprise only, optional	Standardise postprocessor reference. Format: `STANDARDISE_<basename>` where `<basename>.json` is the mapping file. Normalises field values to canonical form after matching.

### `data/output` (pipe)

Parameter	Type	Edition	Description
`name`	string	All editions	Logical name for this pipe. Used in logging.
`format`	string	All editions	Connector format. See Connect Your Data for all supported formats.
`props`	object	All editions	Connector-specific properties. Keys depend on the format. See Connect Your Data for `props` per connector.
`schema`	string	All editions	Spark SQL schema string. Required for CSV. Format: `"field1 type1, field2 type2, ..."`.

### `outputStats` (statistics pipe) Uses the same `format`, `name`, and `props` pattern as `data` and `output`. The path must contain the `$ZINGG_DYNAMIC_STAT_NAME` placeholder, which is replaced at runtime with `SUMMARY`, `CLUSTER`, or `RECORD` depending on the statistics type written. If not configured, statistics are not written and the run proceeds normally.

Parameter	Type	Edition	Description
`name`	string	Enterprise only	Logical name for this stats pipe.
`format`	string	Enterprise only	Connector format. Usually `csv`.
`props.location`	string	Enterprise only	Path must contain `$ZINGG_DYNAMIC_STAT_NAME`. Example: `/tmp/zinggStats_$ZINGG_DYNAMIC_STAT_NAME`

### JSON Config A complete JSON config combines top-level parameters, `fieldDefinition`, `data`, and `output`, plus `outputStats` for Enterprise. #### **Using environment variables in JSON config** If you do not want to pass sensitive values (passwords, API keys, connection strings) through the config file directly, you can configure them through system environment variables. Wrap the variable name in dollar signs in your config: * **Strings:** `"$var$"` (with quotes) * **Booleans and numerics:** `$var$` (without quotes) At runtime, Zingg replaces the placeholder with the actual environment variable value. **Example JSON config with environment variables** ```json { "output": [ { "name": "unifiedCustomers", "format": "net.snowflake.spark.snowflake", "props": { "path": "$location$", "password": "$passwd$" } } ], "labelDataSampleSize": 0.5, "numPartitions": 4, "modelId": "$modelId$", "zinggDir": "models", "collectMetrics": "$collectMetrics$" } ``` {% hint style="success" icon="right-long" %} Environment variable substitution applies anywhere in the JSON config - top-level parameters, pipe `props`, field paths, output locations, and credentials. The substitution is purely textual at runtime, so any environment variable Zingg can read can be referenced this way. {% endhint %} ### Python API equivalents For every JSON parameter, there is an equivalent Python API method on the `Arguments` (Community) or `EArguments` (Enterprise) object.

JSON parameter	Python API method	Edition	Example
`modelId`	`args.setModelId()`	All editions	`args.setModelId("100")`
`zinggDir`	`args.setZinggDir()`	All editions	`args.setZinggDir("/tmp/models")`
`numPartitions`	`args.setNumPartitions()`	All editions	`args.setNumPartitions(4)`
`labelDataSampleSize`	`args.setLabelDataSampleSize()`	All editions	`args.setLabelDataSampleSize(0.5)`
`fieldDefinition`	`args.setFieldDefinition([])`	All editions	`args.setFieldDefinition(fieldDefs)`
`data`	`args.setData()`	All editions	`args.setData(inputPipe)`
`output`	`args.setOutput()`	All editions	`args.setOutput(outputPipe)`
`collectMetrics`	`args.setCollectMetrics()`	All editions	`args.setCollectMetrics(False)`
`outputStats`	`args.setOutputStats()`	Enterprise only	`args.setOutputStats(statsPipe)`
`passthroughExpr`	`args.setPassthroughExpr()`	Enterprise only	`args.setPassthroughExpr("fname = 'matilda'")`
`deterministicMatching`	`args.setDeterministicMatchingCondition()`	Enterprise only	`args.setDeterministicMatchingCondition(dm1, dm2)`
`setBlockingModel`	`args.setBlockingModel()`	Enterprise only	`args.setBlockingModel("DEFAULT")`
`primaryKey` (field-level)	`fieldDef.setPrimaryKey()`	Enterprise only	`recId.setPrimaryKey(True)`
`postProcessors` (field-level)	`fieldDef.setPostProcessors()`	Enterprise only	`job_title.setPostProcessors([StandardisePostprocessorType("STANDARDISE", "jobtitles")])`

{% hint style="success" icon="right-long" %} Sample config files: * `github.com/zinggAI/zingg/tree/main/ examples/febrl/config.json` * `github.com/zinggAI/zingg/tree/main/examples/febrl120k/config.json` {% endhint %} {% hint style="success" icon="right-long" %} **Related pages:** * [Configure Zingg](/zingg/running-zingg/configure-zingg.md) - step-by-step task of building your config * [Match Types](/zingg/zingg-concepts/zingg-configuration/field-definition/match-types.md) - full reference for all `matchType` values * [Connect Your Data](/zingg/connect-your-data/pipes-and-data-connections.md) - all `data` and `output` pipe formats and props * [Working With Python](/zingg/zingg-python-api/working-with-python.md) - Python API alternative to JSON config {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.zingg.ai/zingg/reference/configuration-schema.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.