README.Rmd

---
output:
  github_document:
    html_preview: false
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r}
#| include: false

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# prqlr <img src="man/figures/logo.png" align="right" width="150"/>

<!-- badges: start -->
[![prqlr status badge](https://prql.r-universe.dev/badges/prqlr)](https://prql.r-universe.dev)
[![CRAN status](https://www.r-pkg.org/badges/version/prqlr)](https://CRAN.R-project.org/package=prqlr)
<!-- badges: end -->

R bindings for [the `prqlc` Rust library](https://github.com/prql/prql),
powered by [`savvy`](https://github.com/yutannihilation/savvy).

This version supports PRQL `r prqlr::prql_version()`.

## Installation

Requires R 4.2.0 or later.

This package can be installed from CRAN or [R-universe](https://prql.r-universe.dev/prqlr).
If available, a binary package will be installed.

```r
# Install from CRAN
install.packages("prqlr")
```

```r
# Install from R-universe
install.packages("prqlr", repos = "https://prql.r-universe.dev")
```

For source installation, pre-built Rust libraries may be available
if the environment variable `NOT_CRAN` is set to `"true"`. (Or, set `LIBPRQLR_BUILD` to `"false"`)

```r
Sys.setenv(NOT_CRAN = "true")
install.packages("prqlr")
```

Or, the Rust toolchain (Rust `r RcppTOML::parseTOML("src/rust/Cargo.toml")$package$"rust-version"` or later)
must be configured to build the Rust library.

Please check the <https://github.com/r-rust/hellorust> repository for about Rust code in R packages.

## Examples

```{r}
library(prqlr)

"from mtcars | filter cyl > 6 | select {cyl, mpg}" |>
  prql_compile() |>
  cat()
```

PRQL's pipelines can be joined by the newline character (`\n`), or actual newlines in addition to `|`.

```{r}
"from mtcars \n filter cyl > 6 \n select {cyl, mpg}" |>
  prql_compile() |>
  cat()
```

```{r}
"from mtcars
filter cyl > 6
select {cyl, mpg}" |>
  prql_compile() |>
  cat()
```

Thanks to the `{tidyquery}` package,
we can even convert a PRQL query to a SQL query and then to a `{dplyr}` query!

```{r}
"from mtcars
filter cyl > 6
select {cyl, mpg}" |>
  prql_compile() |>
  tidyquery::show_dplyr()
```

## `{knitr}` integration

Using `{prqlr}` with `{knitr}` makes it easy to create documents that lists PRQL queries and a translated SQL queries,
or documents that lists PRQL queries and tables of data retrieved by PRQL queries.

Please check the vignette `vignette("knitr", "prqlr")` for details.