{"record":{"id":"f2a5d985557e6e92","repo":"apache/beam","slug":"sort-values-axis-index-is-not-supported-because-it-imposes","errorCode":null,"errorMessage":"sort_values(axis=index) is not supported because it imposes an ordering on the dataset which likely will not be preserved.","messagePattern":"sort_values\\(axis=index\\) 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":855,"sourceCode":"              requires_partition_by=partitionings.Singleton(),\n              preserves_partition_by=partitionings.Singleton()))\n\n  @frame_base.args_to_kwargs(pd.DataFrame)\n  @frame_base.populate_defaults(pd.DataFrame)\n  def sort_values(self, axis, **kwargs):\n    \"\"\"``sort_values`` is not implemented.\n\n    It is not implemented for ``axis=index`` because it imposes an ordering on\n    the dataset, and it likely will not be maintained (see\n    https://s.apache.org/dataframe-order-sensitive-operations).\n\n    It is not implemented for ``axis=columns`` because it makes the order of\n    the columns depend on the data (see\n    https://s.apache.org/dataframe-non-deferred-columns).\"\"\"\n    if axis in (0, 'index'):\n      # axis=index imposes an ordering on the DataFrame rows which we do not\n      # support\n      raise frame_base.WontImplementError(\n          \"sort_values(axis=index) is not supported because it imposes an \"\n          \"ordering on the dataset which likely will not be preserved.\",\n          reason=\"order-sensitive\")\n    else:\n      # axis=columns will reorder the columns based on the data\n      raise frame_base.WontImplementError(\n          \"sort_values(axis=columns) is not supported because the order of the \"\n          \"columns in the result depends on the data.\",\n          reason=\"non-deferred-columns\")\n\n  @frame_base.with_docs_from(pd.DataFrame)\n  @frame_base.args_to_kwargs(pd.DataFrame)\n  @frame_base.populate_defaults(pd.DataFrame)\n  @frame_base.maybe_inplace\n  def sort_index(self, axis, **kwargs):\n    \"\"\"``axis=index`` is not allowed because it imposes an ordering on the\n    dataset, and we cannot guarantee it will be maintained (see\n    https://s.apache.org/dataframe-order-sensitive-operations). Only","sourceCodeStart":837,"sourceCodeEnd":873,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/dataframe/frames.py#L837-L873","documentation":"sort_values with axis=0/'index' orders the rows of the dataset — an ordering Beam's distributed, unordered PCollections cannot preserve — so the API raises WontImplementError. axis=1/'columns' is also rejected, but for a different reason: it would reorder columns based on the data (a non-deferred-column violation).","triggerScenarios":"df.sort_values(by='col') (axis defaults to 0/'index') or explicitly df.sort_values(by='col', axis=0); also df.sort_values(by=..., axis=1) hits the companion axis=columns error.","commonSituations":"Porting pandas reporting/Top-N code that relies on sorted output; preparing data for ordered display or rolling-window logic; rank-based feature engineering moved into Beam pipelines.","solutions":["Use df.nlargest(n, by) / df.nsmallest(n, by) if you only need top-k rows.","Use df.rank(...) or df.sort_index alternatives that are order-independent where possible.","Sort after collection: convert with to_pandas() and sort there (accepting a non-distributed stage).","If ordering only matters within groups, use groupby-based aggregations instead of a global sort."],"exampleFix":"// before\ndf = df.sort_values('score', ascending=False)\n// after\ndf = df.nlargest(10, 'score')  # or sort after to_pandas()","handlingStrategy":"fallback","validationCode":"if kwargs.get('axis', 0) in (0, 'index'):\n    raise ValueError('Global row sorting is unsupported in Beam; use nlargest/rank or sort after collection')","typeGuard":"def sort_values_supported(axis=0) -> bool:\n    return False  # both axis choices raise; route to alternatives","tryCatchPattern":"try:\n    df = df.sort_values('score')\nexcept frame_base.WontImplementError:\n    df = df.nlargest(10, 'score')","preventionTips":["Do not attempt row sorting on deferred frames","Prefer nlargest/nsmallest/rank for top-k and ordering needs","Perform display-oriented sorting after to_pandas() at pipeline boundaries"],"tags":["apache-beam","dataframe","pandas","sort","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-14T21:17:11.552Z"}