{"record":{"id":"d9fd1e2413ad7a83","repo":"pola-rs/polars","slug":"write-parquet-with-use-pyarrow-true-allows-only","errorCode":null,"errorMessage":"write_parquet with `use_pyarrow=True` allows only boolean values for `statistics`","messagePattern":"write_parquet with `use_pyarrow=True` allows only boolean values for `statistics`","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/dataframe/frame.py","lineNumber":4309,"sourceCode":"        >>> df.write_parquet(\n        ...     path,\n        ...     partition_by=[\"watermark\"],\n        ... )\n        \"\"\"\n        if compression is None:\n            compression = \"uncompressed\"\n        if isinstance(file, (str, Path)):\n            if partition_by is not None or (\n                pyarrow_options is not None and pyarrow_options.get(\"partition_cols\")\n            ):\n                file = normalize_filepath(file, check_not_directory=False)\n            else:\n                file = normalize_filepath(file)\n\n        if use_pyarrow:\n            if statistics == \"full\" or isinstance(statistics, dict):\n                msg = \"write_parquet with `use_pyarrow=True` allows only boolean values for `statistics`\"\n                raise ValueError(msg)\n            if metadata is not None:\n                msg = \"write_parquet with `use_pyarrow=True` cannot be combined with `metadata`\"\n                raise ValueError(msg)\n            if mkdir:\n                msg = \"write_parquet with `use_pyarrow=True` cannot be combined with `mkdir`\"\n                raise ValueError(msg)\n\n            tbl = self.to_arrow()\n            data = {}\n\n            for i, column in enumerate(tbl):\n                # extract the name before casting\n                name = f\"column_{i}\" if column._name is None else column._name\n\n                data[name] = column\n\n            tbl = pa.table(data)\n","sourceCodeStart":4291,"sourceCodeEnd":4327,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/dataframe/frame.py#L4291-L4327","documentation":"Raised by DataFrame.write_parquet(use_pyarrow=True) when `statistics` is 'full' or a dict. The pyarrow writer path delegates to pq.write_table and only accepts a boolean statistics flag; the richer native-writer statistics modes (named/dict per-column and 'full') are polars-engine features. The validation fires before any IO, so no partial file is produced.","triggerScenarios":"`df.write_parquet('f.parquet', use_pyarrow=True, statistics='full')`, or `statistics={'a': True}` combined with `use_pyarrow=True`. Also triggered indirectly by pyarrow_options/partition_by flows that force use_pyarrow while a dict statistics config is passed through shared kwargs.","commonSituations":"Config-driven writers that always set rich statistics but toggle use_pyarrow=True for partitioned output; enabling pyarrow to use options like row_group_size and forgetting the statistics incompatibility; copying parameter sets between native and pyarrow write paths.","solutions":["Use the native writer for rich statistics: drop `use_pyarrow=True` (statistics='full'/dict are polars-side features)","Or keep use_pyarrow=True and pass a boolean: `statistics=True` / `statistics=False`","Set desired statistics on the pyarrow path via pyarrow_options if supported (e.g. version-specific settings), not the polars statistics argument"],"exampleFix":"# before\ndf.write_parquet('f.parquet', use_pyarrow=True, statistics='full')\n\n# after\ndf.write_parquet('f.parquet', statistics='full')  # native writer supports it","handlingStrategy":"validation","validationCode":"if use_pyarrow and (statistics == 'full' or isinstance(statistics, dict)):\n    raise ValueError('pyarrow writer accepts only boolean statistics; use the native writer')\ndf.write_parquet(path, use_pyarrow=use_pyarrow, statistics=statistics)","typeGuard":null,"tryCatchPattern":"try:\n    df.write_parquet(path, use_pyarrow=True, statistics=statistics)\nexcept ValueError as e:\n    if 'allows only boolean values' in str(e):\n        df.write_parquet(path, statistics=statistics)  # native writer\n    else:\n        raise","preventionTips":["Keep two explicit writer profiles: native (rich statistics, metadata) vs pyarrow (pyarrow_options)","Validate the statistics argument shape against the chosen writer path","Document that 'full'/dict statistics are polars-native features"],"tags":["parquet","write","argument-mismatch","pyarrow"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}