{"record":{"id":"f9f77531bf60d490","repo":"apache/beam","slug":"approximateunique-needs-an-estimation-error-between-1-0-01","errorCode":null,"errorMessage":"ApproximateUnique needs an estimation error between 1% (0.01) and 50% (0.5).","messagePattern":"ApproximateUnique needs an estimation error between 1% \\(0\\.01\\) and 50% \\(0\\.5\\)\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/ApproximateUnique.java","lineNumber":195,"sourceCode":"    public Globally(int sampleSize) {\n      if (sampleSize < 16) {\n        throw new IllegalArgumentException(\n            \"ApproximateUnique needs a sampleSize \"\n                + \">= 16 for an estimation error <= 50%.  \"\n                + \"In general, the estimation \"\n                + \"error is about 2 / sqrt(sampleSize).\");\n      }\n\n      this.sampleSize = sampleSize;\n      this.maximumEstimationError = null;\n    }\n\n    /**\n     * @see ApproximateUnique#globally(double)\n     */\n    public Globally(double maximumEstimationError) {\n      if (maximumEstimationError < 0.01 || maximumEstimationError > 0.5) {\n        throw new IllegalArgumentException(\n            \"ApproximateUnique needs an \" + \"estimation error between 1% (0.01) and 50% (0.5).\");\n      }\n\n      this.sampleSize = sampleSizeFromEstimationError(maximumEstimationError);\n      this.maximumEstimationError = maximumEstimationError;\n    }\n\n    @Override\n    public PCollection<Long> expand(PCollection<T> input) {\n      Coder<T> coder = input.getCoder();\n      return input.apply(Combine.globally(new ApproximateUniqueCombineFn<>(sampleSize, coder)));\n    }\n\n    @Override\n    public void populateDisplayData(DisplayData.Builder builder) {\n      super.populateDisplayData(builder);\n      ApproximateUnique.populateDisplayData(builder, sampleSize, maximumEstimationError);\n    }","sourceCodeStart":177,"sourceCodeEnd":213,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/ApproximateUnique.java#L177-L213","documentation":"ApproximateUnique.Globally requires maximumEstimationError in [0.01, 0.5]; the estimator cannot honor tighter than 1% error nor values above 50%, so out-of-range values throw IllegalArgumentException.","triggerScenarios":"Constructing Globally (or calling ApproximateUnique.globally(error)) with error < 0.01 or > 0.5, e.g. 0.001 for 'very accurate' counting or 0.9/1.0 by confusion with a confidence level.","commonSituations":"Confusing estimation error with confidence, passing a percentage (5 for 5%) instead of a fraction, or asking for unreasonably high precision.","solutions":["Pass the error as a fraction between 0.01 and 0.5, e.g. 0.05 for 5%","If higher precision is needed, use a different transform (e.g. Distinct) that is exact","Normalize percent inputs: error = percent / 100.0 and validate range"],"exampleFix":"// before\nApproximateUnique.globally(5) // percent, and > 0.5\n// after\nApproximateUnique.globally(0.05)","handlingStrategy":"validation","validationCode":"if (error < 0.01 || error > 0.5) throw new IllegalArgumentException(\"maximumEstimationError must be in [0.01, 0.5]\");","typeGuard":null,"tryCatchPattern":"try { ApproximateUnique.globally(err); }\ncatch (IllegalArgumentException e) { /* use 0.05 default or exact Distinct */ }","preventionTips":["Always express error as a fraction (0.05 for 5%), never a percentage","If error < 1% is required, switch to an exact transform like Distinct","Validate config-driven error values before building the pipeline"],"tags":["java","transforms","approximate-unique","argument-validation"],"backgroundTag":"value-out-of-range","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}