# Polars

[Polars](https://pola.rs/) 是一个基于 [OLAP](https://en.wikipedia.org/wiki/Online_analytical_processing) 查询引擎的内存 DataFrame 库。它速度快、易于使用，并且是 [开源](https://github.com/pola-rs/polars/) 的。

从 `1.2.0` 版本开始，Polars 提供对 Hugging Face 文件系统的_原生_支持。这意味着 Polars 查询优化器的所有优势（例如谓词下推和投影下推）都会生效，Polars 仅会加载完成查询所需的数据。这显著加快了读取速度，尤其适用于大型数据集（参见[优化](./datasets-polars-optimizations)）

您可以使用 Hugging Face 路径（`hf://`）来访问 Hub 上的数据：

## 入门

要开始使用，只需将 Polars `pip install` 到你的环境中即可：

```bash
pip install polars
```

安装 Polars 后，您可以直接基于 Hugging Face URL 查询数据集。此操作无需其他依赖项。

```python
import polars as pl

pl.read_parquet("hf://datasets/roneneldan/TinyStories/data/train-00000-of-00004-2d5a1467fff1081b.parquet")
```

> [!TIP]
> Polars 提供了两种 API：惰性 API（`scan_parquet`）和急切 API（`read_parquet`）。我们建议将急切 API 用于交互式工作负载，将惰性 API 用于性能敏感的场景，因为它能实现更好的查询优化。有关此主题的更多信息，请参阅 [Polars 用户指南](https://docs.pola.rs/user-guide/concepts/lazy-api/#when-to-use-which)。

Polars 支持使用通配符一次性将多个文件下载到单个 DataFrame 中。

```python
pl.read_parquet("hf://datasets/roneneldan/TinyStories/data/train-*.parquet")
```

### Hugging Face 网址

Hugging Face URL 可以由 `username` 和 `dataset` 名称按以下方式构建：

- `hf://datasets/{username}/{dataset}/{path_to_file}`

路径可以包含通配符模式，例如 `**/*.parquet`，以查询所有匹配该模式的文件。此外，对于任何不受支持的 [文件格式](./datasets-polars-file-formats)，您可以使用 Hugging Face 提供的自动转换的 parquet 文件，方法是使用 `@~parquet branch`：

- `hf://datasets/{my-username}/{my-dataset}@~parquet/{path_to_file}`

