I want to make a claim about this documentation that goes beyond the usual. Most library documentation teaches you an API. This one teaches you a way of thinking about data transformation, and the way of thinking is better than the one most analysts currently have. That is rare enough to be worth the read regardless of which library you end up using.
The core idea is the expression. Rather than reaching into a DataFrame, extracting a column, doing something to it and putting it back, you describe transformations as composable expressions that are then applied. It sounds like a stylistic preference and it is not. Expressions can be optimised, parallelised and reordered by the engine because they describe intent rather than steps.
They compose cleanly, so a complex transformation is built from small readable pieces rather than a chain of mutations. And critically, they eliminate a whole category of bugs around modifying data while iterating over it, which anyone who has fought a chained assignment warning in another library will recognise as a real gift. The user guide teaches this properly. It does not just show the syntax, it explains why the model is shaped this way and what it buys you.
By the end you are thinking in terms of describing the transformation you want rather than the operations to perform, and that is a genuine upgrade in how you approach data work. The lazy evaluation material is the second thing done well. You build a query, nothing executes, the engine looks at the whole plan and works out that it can skip reading three columns you never use, push a filter down to the file scan so most rows are never loaded, and reorder joins sensibly. The documentation shows you the query plans and how to read them, which means this is not magic you have to trust but a mechanism you can inspect.
Anyone who has worked with databases will find this familiar and welcome, and anyone who has not is learning something genuinely valuable about how query engines work. Streaming for larger than memory data is a practical capability that gets undersold. There is a large class of jobs that are too big for a laptop's memory and far too small to justify a distributed cluster, and historically those jobs meant either painful chunking code or an unnecessary Spark deployment. Being able to process them on one machine, in one process, is a meaningful simplification of a lot of data engineering.
The migration guidance for people arriving from the incumbent library is unusually honest. It does not simply map old methods to new ones. It explains where the mental model genuinely differs and where a habit needs unlearning rather than translating, which is the more useful and less flattering thing to write. The performance is real and I deliberately have not led with it, because the documentation slightly over-indexes on benchmarks and the design is more interesting than the speed.
Now the limitations, and the ecosystem is the important one. The incumbent library has fifteen years of accumulated integration. Every plotting library, every machine learning library, every obscure file format reader, every tutorial and every answer on every forum assumes it. Interoperability here is decent, there is a well-supported conversion path, and you will still regularly hit a library that wants the other type and a search result that solves your problem in the other API.
That friction is the actual cost of switching and it is much larger than any benchmark difference. The documentation cannot fix this and it could acknowledge it more plainly. API churn is a real annoyance. The library has moved fast, methods have been renamed and deprecated, and there was a major version transition with breaking changes.
Code you find online may be a year old and may not run. The documentation is current, and the wider ecosystem of blog posts and answers is a minefield of version mismatches, which is disproportionately painful for beginners who cannot tell an API change from their own mistake. Coverage is uneven in the corners. The common path is documented beautifully.
Push into complex nested data types, unusual joins, custom aggregations or the plugin system and you increasingly find bare API reference with no example, and the reference alone is not enough to work out the intended usage. And the error messages, while improving, are still frequently unhelpful, particularly when an expression is invalid for reasons involving type inference. The documentation offers little help in decoding them, and a troubleshooting page mapping common errors to causes would save a lot of frustration. My four point zero is for documentation that teaches a better mental model rather than an API, explains its optimiser transparently, unlocks a genuinely useful middle ground of data size, and is honest with people migrating.
Marked down for an ecosystem gap that no documentation can close, for version churn that makes external examples unreliable, and for thin coverage of the harder corners. Read the user guide. It is one of the better technical documents in this catalogue.