{"record":{"id":"55ee77eeaa0434f4","repo":"apache/beam","slug":"sort-values-axis-columns-is-not-supported-because-the-order","errorCode":null,"errorMessage":"sort_values(axis=columns) is not supported because the order of the columns in the result depends on the data.","messagePattern":"sort_values\\(axis=columns\\) is not supported because the order of the columns in the result depends on the data\\.","errorType":"exception","errorClass":"WontImplementError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/dataframe/frames.py","lineNumber":861,"sourceCode":"    \"\"\"``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\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 \"","sourceCodeStart":843,"sourceCodeEnd":879,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/dataframe/frames.py#L843-L879","documentation":"apache_beam.dataframe raises this WontImplementError when sort_values is called with axis=columns. Reordering columns based on cell data cannot be done in Beam's deferred distributed execution, because the resulting column order would depend on the data flowing through the pipeline rather than being fixed at graph-construction time. Only axis=index (or the default 0) would be possible, and even that is separately rejected as order-sensitive.","triggerScenarios":"Calling df.sort_values(axis=1) or df.sort_values(axis='columns') on a DeferredDataFrame, or a deferred frame where with_docs_from/args_to_kwargs maps a positional axis argument to 1.","commonSituations":"Porting an existing pandas script to Beam DataFrames unchanged; sorting columns by their values (e.g. ranking columns per row) in a pipeline; confusion between Beam's two axis restrictions on sort_values.","solutions":["Avoid sorting columns in the pipeline: perform sort_values(axis=columns) on the final collected pandas DataFrame after to_pandas().","Use sort_values(axis='index') is also unsupported; if you only need sorted row output for sinks, write to a sink that guarantees ordering or collect first.","Restructure the transform to not depend on column order (e.g. operate on columns by name)."],"exampleFix":"// before\ndf.sort_values(axis='columns')  # WontImplementError in Beam\n// after\npdf = df.to_pandas()\npdf = pdf.sort_values(axis='columns')","handlingStrategy":"validation","validationCode":"import inspect\nif kwargs.get('axis', 0) in (1, 'columns'):\n    raise ValueError(\"sort_values(axis=columns) is unsupported in Beam; sort after to_pandas()\")","typeGuard":"def can_sort_values(df, axis=0):\n    return axis in (0, 'index')","tryCatchPattern":"from apache_beam.dataframe import frame_base\ntry:\n    df = df.sort_values(axis='columns')\nexcept frame_base.WontImplementError:\n    df = df.to_pandas().sort_values(axis='columns')","preventionTips":["Never pass axis=1/'columns' to sort_values in Beam pipelines.","Reserve column-ordering transformations for the final eager pandas stage.","Operate on columns by name, not by data-derived position."],"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"}