ditto · did the data survive?

The batch job copies products to products_backup, then upserts products and deletes stale documents. Run the comparison as a separate step afterwards, and react to the verdict:

ComparisonReport report = comparator.compare(
        ComparisonRequest.builder("products_backup", "products")
                .ignoredPaths("meta.syncedAt")
                .build(),
        progress -> log.info("{} docs read", progress.processedDocs()));

switch (report.verdict()) {
    case GREEN  -> log.info("products verified");
    case YELLOW -> alerts.warn("products", report.id());     // usable; have someone look
    case RED    -> rollback.restoreFromBackup("products");   // your code, e.g. renameCollection
}

• A RED verdict is a value, not an exception. Exceptions mean the comparison couldn't run meaningfully: ComparisonException for a missing collection or unusable keys, DataAccessException for database errors.
• Run it from any scheduler (JobRunr, Spring Batch, @Scheduled, Quartz). It's blocking, and stops when its thread is interrupted. The ProgressListener can drive a dashboard progress bar.
• Label the comparison with the job's id, .label("batchJobId", jobId), and the stored report can be found from the job later: reportRepository.findByLabels(Map.of("batchJobId", jobId), 10) or GET /actuator/comparisons?label=batchJobId:4711.
• Don't let the next sync overwrite the backup before verification and rollback are done.

FULL mode reads both collections once. When that takes too long, sample instead: ditto draws random keys from both sides ($sample), looks up their counterparts in batches, and reports every rate as a 95% Wilson confidence interval.

ComparisonRequest.builder("events_backup", "events").sample(20_000).build();

# CLI
java -jar ditto-cli.jar ... --sample-size=20000

By default (verdict-basis: CONSERVATIVE) each rule evaluates the worse end of the interval, so GREEN means "GREEN with 95% confidence". A value right at a threshold may therefore come out YELLOW. Use a larger sample, or POINT, if you prefer point estimates.

A common pattern: a quick SAMPLE verdict right after the sync, then a FULL comparison later.

On a test environment one side often has just a few hundred documents, while the other is a full copy. A normal comparison is RED then, because most keys are missing. Matched-only compares just the documents whose key exists on both sides:

comparator.compare(comparator.backupRequest("products").matchedOnly().build());

# CLI
java -jar ditto-cli.jar --collection=products --matched-only

• ditto reads the smaller collection and looks up its keys in the other, so a small test collection is quick to check against a large one.
• Content, changed paths and structure cover the matched documents only. The key counts are still reported, but key similarity isn't judged, unless no key matches at all.
• A normal comparison that looks like this situation suggests the option in its hints.

Compare the output of a rewritten pipeline with the old one, or a migrated database with its source. The two sides can live in different databases of the same cluster, and can be matched by any unique top-level field:

comparator.compare(ComparisonRequest.builder(
                CollectionRef.of("legacy", "customers"),
                CollectionRef.of("crm", "customers"))
        .keyField("customerNo")              // unique on both sides; index it
        .ignoredPaths("_id", "migratedAt")
        .nullEqualsMissing(true)             // new pipeline omits nulls
        .build());

Look at topChangedPaths for systematic differences: a path changed in close to 100% of documents points to a format or mapping difference rather than data churn.

Some changes keep every value intact but still break consumers. For example, an upstream system starts writing qty as a double. Content-wise 42 == 42.0, so the documents count as unchanged, but the structure check reports a type shift and the verdict is RED:

"typeShifts": [ {
  "path": "qty",
  "baseline":  [ { "type": "INT32",  "docs": 20000, "share": 1.0 } ],
  "candidate": [ { "type": "DOUBLE", "docs": 20000, "share": 1.0 } ]
} ]

The same check reports fields that disappeared from every document (missingPaths, RED), new fields (YELLOW) and fields that became much rarer or more common (presenceDeltas, YELLOW).

The CLI maps the verdict to the exit code and prints nothing but JSON on stdout, so it fits into shell scripts and CI pipelines:

java -jar ditto-cli.jar --uri="$MONGO_URI" --db=shop \
  --baseline=products_backup --candidate=products --ignore=meta.syncedAt \
  --out=report.json > /dev/null
case $? in
  0) echo "GREEN" ;;
  1) echo "YELLOW, continuing"; jq '.rules[] | select(.level != "GREEN") | .reason' report.json ;;
  2) echo "RED, aborting"; exit 1 ;;
  *) echo "comparison failed"; exit 1 ;;
esac

Prices, stock levels and counters change in most documents on every run. Left as they are, they would make the verdict RED. Declare them as expected-change paths. They stay in the report, flagged "expected": true, but don't count for maxPathChangeRate. Documents changed only there count as unchanged for the unchangedRate rule.

ditto:
  expected-change-paths: [price, stock]    # stock also covers stock.qty, stock.updatedAt …
  redacted-paths: [customer]               # values shown as *** in reports
  max-value-examples: 3                    # 0 keeps values out of reports

Every changed path comes with a few before/after values, so a surprise is easy to judge:

{ "path": "name", "changedDocs": 1204, "expected": false,
  "valueExamples": [
    { "key": { "type": "INT32", "value": "4711" },
      "baseline": [ "\"Oak desk\"" ], "candidate": [ "\"OAK DESK\"" ] } ] }

Fixed thresholds fit some collections badly: one where 8% of documents change every day is permanently YELLOW. Store every report, and let ditto derive the thresholds from the last runs of the same comparison:

ditto:
  persistence:
    enabled: true                     # stores reports in comparison_reports
  adaptive-thresholds:
    enabled: true                     # after 5 runs: GREEN within 2σ, YELLOW within 3σ of the mean

ditto uses the last 20 non-RED runs, so a broken run doesn't lower the bar for the next one. The report says where its thresholds came from:

"thresholdSource": {
  "kind": "HISTORY", "historyRuns": 14,
  "notes": [ "unchangedRate: mean 0.9120, standard deviation 0.0071 over 14 runs -> GREEN >= 0.8978, YELLOW >= 0.8907", ... ]
}

Every comparison publishes a Spring event, whoever triggered it. Alerting is one listener:

@EventListener
void onComparison(ComparisonCompletedEvent event) {
    if (event.report().verdict() == Level.RED) {
        alerts.critical(event.report());
    }
}
// ComparisonFailedEvent for comparisons that could not run

If the application has Micrometer, ditto records ditto.comparison (timer, tagged with verdict), ditto.comparison.errors, and gauges with the latest verdict, key similarity, unchanged rate and max path change rate per collection pair. That's enough for a dashboard and an alert rule.

With Actuator and persistence, the read-only comparisons endpoint lists stored reports (/actuator/comparisons, /actuator/comparisons/{id}) once exposed via management.endpoints.web.exposure.include. Both integrations are optional: ditto doesn't bring Micrometer or Actuator into an application that doesn't use them.

Paths and keys

Mode and detection

Thresholds and history

Report, persistence and resources