GH-39241: [Python][Parquet] Point out column order mismatch in ParquetWriter.write_table

python/pyarrow/parquet/core.py

@@ -1204,6 +1204,8 @@ def write_table(self, table, row_group_size=None):
         Parameters
         ----------
         table : Table
+            Its schema must match the writer schema, including the order
+            of the columns.
         row_group_size : int, default None
             Maximum number of rows in each written row group. If None,
             the row group size will be the minimum of the Table size (in rows)
@@ -1220,6 +1222,12 @@ def write_table(self, table, row_group_size=None):
                 "Table schema does not match schema used to create file: \n"
                 f"table:\n{table.schema!s} vs. \nfile:\n{self.schema!s}"
             )
+            if (table.schema.names != self.schema.names and
+                    sorted(table.schema.names) == sorted(self.schema.names)):
+                msg += (
+                    "\nThe columns are in a different order. Use "
+                    "table.select(schema.names) to reorder them."
+                )
             raise ValueError(msg)
 
         self.writer.write_table(table, row_group_size=row_group_size)

python/pyarrow/tests/parquet/test_parquet_writer.py

@@ -90,6 +90,17 @@ def test_validate_schema_write_table(tempdir):
             w.write_table(simple_table)
 
 
+def test_write_table_column_order_mismatch(tempdir):
+    # GH-39241
+    table = pa.table({'a': [1], 'b': ['x']})
+    schema = pa.schema([('b', pa.string()), ('a', pa.int64())])
+
+    with pq.ParquetWriter(tempdir / 'test.parquet', schema) as w:
+        with pytest.raises(ValueError, match="different order"):
+            w.write_table(table)
+        w.write_table(table.select(schema.names))
+
+
 def test_parquet_invalid_writer(tempdir):
     # avoid segfaults with invalid construction
     with pytest.raises(TypeError):