{"record":{"id":"f29407e20fc20c11","repo":"apache/beam","slug":"value-counts-sort-true-is-not-supported-because-it-imposes","errorCode":null,"errorMessage":"value_counts(sort=True) is not supported because it imposes an ordering on the dataset which likely will not be preserved.","messagePattern":"value_counts\\(sort=True\\) is not supported because it imposes an ordering on the dataset which likely will not be preserved\\.","errorType":"exception","errorClass":"WontImplementError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/dataframe/frames.py","lineNumber":2338,"sourceCode":"\n  @frame_base.with_docs_from(pd.Series)\n  def value_counts(\n      self,\n      sort=False,\n      normalize=False,\n      ascending=False,\n      bins=None,\n      dropna=True):\n    \"\"\"``sort`` is ``False`` by default, and ``sort=True`` is not supported\n    because it imposes an ordering on the dataset which likely will not be\n    preserved.\n\n    When ``bin`` is specified this operation is not parallelizable. See\n    [Issue 20903](https://github.com/apache/beam/issues/20903) tracking the\n    possible addition of a distributed implementation.\"\"\"\n\n    if sort:\n      raise frame_base.WontImplementError(\n          \"value_counts(sort=True) is not supported because it imposes an \"\n          \"ordering on the dataset which likely will not be preserved.\",\n          reason=\"order-sensitive\")\n\n    if bins is not None:\n      return frame_base.DeferredFrame.wrap(\n          expressions.ComputedExpression(\n              'value_counts',\n              lambda s: s.value_counts(\n                  normalize=normalize, bins=bins, dropna=dropna)[self._expr],\n              requires_partition_by=partitionings.Singleton(\n                  reason=(\n                      \"value_counts with bin specified requires collecting \"\n                      \"the entire dataset to identify the range.\")),\n              preserves_partition_by=partitionings.Singleton(),\n          ))\n\n    if dropna:","sourceCodeStart":2320,"sourceCodeEnd":2356,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/dataframe/frames.py#L2320-L2356","documentation":"DeferredSeries.value_counts(sort=True) (pandas' default) sorts counts descending, imposing a global ordering that a distributed pipeline cannot preserve deterministically. The Beam dataframe API rejects sort=True with WontImplementError (reason 'order-sensitive'); only sort=False is allowed.","triggerScenarios":"Calling series.value_counts() with default arguments (sort defaults to True in pandas) or explicitly value_counts(sort=True); also value_counts with bins relies on a non-parallelizable path.","commonSituations":"Porting pandas value_counts() calls verbatim; building frequency tables expecting sorted output; using the result to pick top-K categories.","solutions":["Pass sort=False: series.value_counts(sort=False)","Sort explicitly afterwards with sort_values() if a deferred sort is acceptable at that point","Compute top-K via a different mechanism (e.g. nlargest on the counts series with keep='all')"],"exampleFix":"// before\ncounts = s.value_counts()\n// after\ncounts = s.value_counts(sort=False)","handlingStrategy":"validation","validationCode":"counts = s.value_counts(sort=False)  # sort=True is unsupported on DeferredSeries","typeGuard":"def beam_safe_value_counts(kwargs):\n    return not kwargs.get('sort', True)","tryCatchPattern":"from apache_beam.dataframe import frame_base\ntry:\n    counts = s.value_counts(sort=False)\nexcept frame_base.WontImplementError:\n    counts = s.value_counts(sort=False)","preventionTips":["Never call value_counts() without sort=False on deferred frames","If sorted output is required, sort explicitly afterwards via sort_values()","Add code review checks for pandas default arguments in Beam ports"],"tags":["pandas","apache-beam","dataframe","order-sensitive"],"backgroundTag":"unsupported-operation","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"}