{"record":{"id":"0df560876dcfe441","repo":"pola-rs/polars","slug":"cannot-use-partition-by-with-maintain-order-fal","errorCode":null,"errorMessage":"cannot use `partition_by` with `maintain_order=False, include_key=False, as_dict=True`","messagePattern":"cannot use `partition_by` with `maintain_order=False, include_key=False, as_dict=True`","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/dataframe/frame.py","lineNumber":10214,"sourceCode":"        │ str ┆ i64 ┆ i64 │\n        ╞═════╪═════╪═════╡\n        │ c   ┆ 3   ┆ 1   │\n        └─────┴─────┴─────┘}\n        \"\"\"\n        by_parsed = _expand_selectors(self, by, *more_by)\n\n        partitions = [\n            self._from_pydf(_df)\n            for _df in self._df.partition_by(by_parsed, maintain_order, include_key)\n        ]\n\n        if as_dict:\n            if include_key:\n                names = [p.select(by_parsed).row(0) for p in partitions]\n            else:\n                if not maintain_order:  # Group keys cannot be matched to partitions\n                    msg = \"cannot use `partition_by` with `maintain_order=False, include_key=False, as_dict=True`\"\n                    raise ValueError(msg)\n                names = self.select(by_parsed).unique(maintain_order=True).rows()\n\n            return dict(zip(names, partitions, strict=True))\n\n        return partitions\n\n    def shift(self, n: int = 1, *, fill_value: IntoExpr | None = None) -> DataFrame:\n        \"\"\"\n        Shift values by the given number of indices.\n\n        Parameters\n        ----------\n        n\n            Number of indices to shift forward. If a negative value is passed, values\n            are shifted in the opposite direction instead.\n        fill_value\n            Fill the resulting null values with this value. Accepts scalar expression\n            input. Non-expression inputs are parsed as literals.","sourceCodeStart":10196,"sourceCodeEnd":10232,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/dataframe/frame.py#L10196-L10232","documentation":"DataFrame.partition_by(as_dict=True) builds a dict mapping group keys to partition frames by pairing each partition with a key. When include_key=False the key columns are stripped from the partitions, so the keys must be recovered separately from self.select(by).unique(maintain_order=True) and zipped positionally — which is only sound if partitions come back in a deterministic order. With maintain_order=False the Rust-side partition order is not guaranteed to match, so polars rejects the exact combination (maintain_order=False, include_key=False, as_dict=True) up front.","triggerScenarios":"df.partition_by('a', maintain_order=False, include_key=False, as_dict=True) — all three flags together; performance tuning that disabled maintain_order on an existing as_dict=True, include_key=False call site.","commonSituations":"Building {key: sub-frame} lookup tables for per-group export/sharding while optimizing partition_by speed; dropping key columns to save memory and then relying on dict keys for identification.","solutions":["Re-enable order: partition_by('a', maintain_order=True, include_key=False, as_dict=True)","Keep key columns and strip them afterwards: partition_by('a', maintain_order=False, include_key=True, as_dict=True), then pop/drop the key cols per partition","Return a list and derive keys yourself with deterministic ordering on both sides (select(by).unique(maintain_order=True) plus partition_by(..., maintain_order=True))"],"exampleFix":"# before\nparts = df.partition_by('a', maintain_order=False, include_key=False, as_dict=True)\n\n# after\nparts = df.partition_by('a', maintain_order=True, include_key=False, as_dict=True)\n# or keep keys and strip them per partition:\n# parts = {k: p.drop('a'): ...}","handlingStrategy":"validation","validationCode":"if as_dict and not include_key and not maintain_order:\n    raise ValueError('partition_by: set maintain_order=True or include_key=True when as_dict=True')\nparts = df.partition_by(by, maintain_order=maintain_order, include_key=include_key, as_dict=as_dict)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat (as_dict=True, include_key=False) as requiring maintain_order=True by contract","If order must stay off, keep include_key=True and drop key columns per partition","Document why order matters when dict keys identify partitions — future readers will re-disable it otherwise"],"tags":["polars","dataframe","partition-by","flag-conflict","valueerror","ordering"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}