Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update README #31

Merged
merged 5 commits into from
Oct 13, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 0 additions & 12 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,3 @@ updates:
commit-message:
prefix: ci
labels: ['skip changelog']

# Rust
- package-ecosystem: cargo
directory: '/'
schedule:
interval: monthly
ignore:
- dependency-name: '*'
update-types: ['version-update:semver-patch']
commit-message:
prefix: 'build!:'
prefix-development: chore
4 changes: 2 additions & 2 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

33 changes: 20 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,37 @@
# Polars CLI

[![Crates.io](https://img.shields.io/crates/v/polars-cli)](https://crates.io/crates/polars-cli)
[![PyPI](https://img.shields.io/pypi/v/polars-cli)](https://pypi.org/project/polars-cli/)

The Polars command line interface provides a convenient way to execute SQL commands using Polars as a backend.

## Installation

Until binaries are available, the only way to install the Polars CLI is by building it from source:
The recommended way to install the Polars CLI is by using [pip](https://pip.pypa.io/):

```bash
cargo +nightly install --locked polars-cli
pip install polars-cli
```

Alternatively, clone the repository and install the latest version on the main branch:
This will install a pre-compiled binary and make it available on your path under `polars`.
If you do not have Python available, you can download a suitable binary from the most recent [GitHub release](https://github.com/pola-rs/polars-cli/releases/latest/).

Alternatively, you can install the Polars CLI using [cargo](https://doc.rust-lang.org/cargo/), which will compile the code from scratch:

```bash
cargo install --locked --path .
cargo install --locked polars-cli
```

#### Prerequisites

1. `rustup`: which provides the `cargo` executable. You can get it from the [official website](https://rustup.rs/).
2. `rustup install nightly` - The `nightly` version of rust, since some of our dependencies use unstable features.

## Usage

Running `polars` without any arguments will start an interactive shell in which you can run SQL commands.

```shell
$ polars
Polars CLI version 0.3.0
Polars CLI version 0.4.0
Type .help for help.

>> select * FROM read_csv('examples/datasets/foods1.csv');
>> select * FROM read_csv('examples/datasets/foods.csv');
┌────────────┬──────────┬────────┬──────────┐
│ category ┆ calories ┆ fats_g ┆ sugars_g │
│ --- ┆ --- ┆ --- ┆ --- │
Expand All @@ -44,10 +49,10 @@ Type .help for help.
└────────────┴──────────┴────────┴──────────┘
```

Or pipe your SQL command directly inline:
Alternatively, SQL commands can be piped directly into the Polars CLI.

```bash
$ echo "SELECT category FROM read_csv('examples/datasets/foods1.csv')" | polars
$ echo "SELECT category FROM read_csv('examples/datasets/foods.csv')" | polars
┌────────────┐
│ category │
│ --- │
Expand All @@ -67,6 +72,8 @@ $ echo "SELECT category FROM read_csv('examples/datasets/foods1.csv')" | polars

## Features

When compiling the Polars CLI from source, the following features can be enabled:

| Feature | Description |
| --------- | --------------------------------------------------------- |
| default | The default feature set that includes all other features. |
Expand Down
File renamed without changes.