{"record":{"id":"802c8b77aa709c4d","repo":"apache/beam","slug":"sort-index-axis-index-is-not-supported-because-it-imposes-an","errorCode":null,"errorMessage":"sort_index(axis=index) is not supported because it imposes an ordering on the dataset which we cannot guarantee will be preserved.","messagePattern":"sort_index\\(axis=index\\) is not supported because it imposes an ordering on the dataset which we cannot guarantee will be preserved\\.","errorType":"exception","errorClass":"WontImplementError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/dataframe/frames.py","lineNumber":877,"sourceCode":"    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\n    ``axis=columns`` is allowed.\"\"\"\n    if axis in (0, 'index'):\n      # axis=rows imposes an ordering on the DataFrame which we do not support\n      raise frame_base.WontImplementError(\n          \"sort_index(axis=index) is not supported because it imposes an \"\n          \"ordering on the dataset which we cannot guarantee will be \"\n          \"preserved.\",\n          reason=\"order-sensitive\")\n\n    # axis=columns reorders the columns by name\n    return frame_base.DeferredFrame.wrap(\n        expressions.ComputedExpression(\n            'sort_index',\n            lambda df: df.sort_index(axis=axis, **kwargs),\n            [self._expr],\n            requires_partition_by=partitionings.Arbitrary(),\n            preserves_partition_by=partitionings.Arbitrary(),\n        ))\n\n  @frame_base.with_docs_from(pd.DataFrame)\n  @frame_base.args_to_kwargs(\n      pd.DataFrame, removed_args=[\"errors\"] if PD_VERSION >= (2, 0) else None)","sourceCodeStart":859,"sourceCodeEnd":895,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/dataframe/frames.py#L859-L895","documentation":"sort_index(axis=index) is rejected because sorting a distributed dataset's rows imposes an ordering that Beam cannot guarantee will be preserved through the pipeline (see the Beam order-sensitive operations doc). Beam DataFrames deliberately refuse any operation whose result depends on row order. Only axis=columns is allowed for sort_index, since that reorders columns by name deterministically.","triggerScenarios":"Calling df.sort_index() (default axis=0), df.sort_index(axis=0), or df.sort_index(axis='index') on a DeferredDataFrame or DeferredSeries.","commonSituations":"Migrating pandas code that sorts by index before joins or output; assuming index order matters downstream; forgetting that Beam partitions data arbitrarily.","solutions":["Call sort_index(axis='columns') if you only need column ordering by name.","If row ordering matters, collect with to_pandas() and sort_index locally, or sort in the sink (e.g. WriteToText doesn't guarantee order either — use a single-partition step).","Redesign the pipeline so correctness does not depend on index order."],"exampleFix":"// before\ndf.sort_index()  # WontImplementError\n// after\ndf = df.to_pandas().sort_index()","handlingStrategy":"validation","validationCode":"def check_sort_index(axis=0):\n    if axis in (0, 'index'):\n        raise ValueError(\"sort_index(axis=index) is order-sensitive and unsupported in Beam\")\n    return True","typeGuard":"def is_column_axis(axis):\n    return axis in (1, 'columns')","tryCatchPattern":"from apache_beam.dataframe import frame_base\ntry:\n    df = df.sort_index()\nexcept frame_base.WontImplementError:\n    df = df.to_pandas().sort_index()","preventionTips":["Design pipelines so correctness never depends on row/index order.","If ordering is needed for output, sort in the sink or after collection.","Only use axis='columns' with sort_index in deferred code."],"tags":["apache-beam","dataframe","pandas","order-sensitivity"],"backgroundTag":"order-sensitive-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"}