{"record":{"id":"eba2cf48cc3a6041","repo":"apache/beam","slug":"approximateunique-needs-a-samplesize-16-for-an-estimation","errorCode":null,"errorMessage":"ApproximateUnique needs a sampleSize >= 16 for an estimation error <= 50%.  In general, the estimation error is about 2 / sqrt(sampleSize).","messagePattern":"ApproximateUnique needs a sampleSize >= 16 for an estimation error <= 50%\\.  In general, the estimation error is about 2 / sqrt\\(sampleSize\\)\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/ApproximateUnique.java","lineNumber":179,"sourceCode":"   * @param <T> the type of the elements in the input {@code PCollection}\n   */\n  public static final class Globally<T> extends PTransform<PCollection<T>, PCollection<Long>> {\n\n    /**\n     * The number of entries in the statistical sample; the higher this number, the more accurate\n     * the estimate will be.\n     */\n    private final long sampleSize;\n\n    /** The desired maximum estimation error or null if not specified. */\n    private final @Nullable Double maximumEstimationError;\n\n    /**\n     * @see ApproximateUnique#globally(int)\n     */\n    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      }","sourceCodeStart":161,"sourceCodeEnd":197,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/ApproximateUnique.java#L161-L197","documentation":"ApproximateUnique.Globally requires sampleSize >= 16 because the HyperLogLog-based estimator's error grows as ~2/sqrt(sampleSize); below 16 the promised error bound is meaningless, so the constructor throws IllegalArgumentException.","triggerScenarios":"Constructing ApproximateUnique.Globally with a sample size of 15 or less, e.g. via new ApproximateUnique.Globally(8) or ApproximateUnique.globally(n) with n < 16.","commonSituations":"Developers tune sampleSize down for performance without realizing the minimum, or pass a placeholder 0/1 value while scaffolding a pipeline.","solutions":["Set sampleSize to at least 16 (choose based on 2/sqrt(sampleSize) error tolerance)","Use the ApproximateUnique.globally(double error) overload to derive sampleSize from a desired error","Clamp user-provided sample sizes: Math.max(16, sampleSize)"],"exampleFix":"// before\nApproximateUnique.globally(10)\n// after\nApproximateUnique.globally(16)  // or ApproximateUnique.globally(0.05)","handlingStrategy":"validation","validationCode":"if (sampleSize < 16) throw new IllegalArgumentException(\"sampleSize must be >= 16 for ApproximateUnique\");","typeGuard":null,"tryCatchPattern":"try { ApproximateUnique.globally(n); }\ncatch (IllegalArgumentException e) { /* clamp and retry: */ p = p.apply(ApproximateUnique.globally(16)); }","preventionTips":["Never pass sampleSize below 16; document the floor in pipeline config","Prefer the double-error overload globally(error) which derives a valid sampleSize","Clamp external/config-driven sample sizes with Math.max(16, value)"],"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"}