How to Use PRQL: The Beginner's Guide (First Query, the Pipeline Lesson, First Compile, and the dbt Arc)

CodexFuse Team · 2026-11-02T12:23:33.070Z · 14 min read min read

Learn how to use PRQL: install prqlc, write your first pipeline query, compile to SQL, use the Python bindings, and run PRQL inside dbt — a beginner’s guide.

If you write SQL every day, learning how to use PRQL feels like someone finally turned the query the right way round. PRQL — the Pipelined Relational Query Language, pronounced "Prequel" — is an open-source language that lets you write data transformations as a pipeline, one transformation per line, and then compiles that pipeline to plain SQL that any SQL database runs. This PRQL tutorial is the beginner guide the field has been missing: your first query, the pipeline lesson that makes the syntax click, your first compile to readable SQL, and the dbt arc for people whose transformations live in models. It is a language, not a database — PRQL compiles to SQL, so it runs wherever SQL runs. If you come from the semantic-modeling side of SQL alternatives, our Malloy beginner guide covers that world; PRQL is different — it is a pipelined syntax replacement for SQL itself, not a modeling language.

This guide is written for beginners who already read SQL: analysts, data engineers, and developers who keep tripping over SQL's backwards syntax. Everything below was checked against the PRQL project's own language book and compiler on 2026-11-02, including live runs of the actual compiler — the SQL outputs in this article were produced by the real prqlc, not transcribed from memory. Version numbers move over time: the compiler was at version 0.13.14 when this guide was written.

What Is PRQL, Exactly?

PRQL is a pipelined SQL replacement that compiles to SQL for any SQL database. That single sentence is the whole product: you write a pipeline of transformations — from, then filter, then derive, then aggregate — and the PRQL compiler turns it into the equivalent SQL for Postgres, BigQuery, DuckDB, Snowflake, and eleven other dialects. In the project's own words: "Pipelined Relational Query Language, pronounced 'Prequel'. PRQL is a modern language for transforming data — a simple, powerful, pipelined SQL replacement. Like SQL, it's readable, explicit and declarative. Unlike SQL, it forms a logical pipeline of transformations, and supports abstractions such as variables and functions."

The project is open source under the Apache License 2.0 (GitHub repository PRQL/prql), and its own status page describes it as "ready to use by the intrepid, either with our supported integrations, or within your own tools, using one of our supported language bindings" — noting it still has some bugs and missing features and is not yet aimed at rolling out to non-technical teams. One clarification before we start, because this trips up real beginners: a page ranking for "PRQL" defines it as "Pattern Recognition Query Language," an invented pattern-matching syntax. That is a different thing with a colliding name. Everywhere in this guide, PRQL means the Pipelined Relational Query Language from prql-lang.org.

How to Install prqlc (PRQL Install in 4 Steps)

Installing the PRQL compiler takes about a minute, and there are four official routes — pick exactly one. The CLI is "a single, dependency-free binary that compiles PRQL into SQL," written in Rust. No database server is needed to start — the compiler is the only prerequisite, which is why the prql for beginners path is measured in minutes, not hours.

1. macOS: brew install prqlc
2. Windows: winget install prqlc
3. Any platform with Rust: cargo install prqlc (installs from crates.io)
4. Python (compiler bindings): pip install prqlc — this gives you the Python bindings with prqlc.compile(), which is how most beginners run it.

Two traps to avoid. First, pip install prql installs an unrelated, long-abandoned "Preql" project from 2020 — the correct package is prqlc, never prql. Second, Linux users can also grab precompiled binaries from the project's GitHub release page. To confirm your install worked, check the version the same way this guide did on 2026-11-02: a fresh pip install prqlc installed version 0.13.14, which matched the project's changelog for that date. If you are more comfortable cloning than installing, the source lives in the PRQL/prql GitHub repository — and if Git is not second nature yet, our Git beginner guide covers the commands you will need.

How Do You Write Your First PRQL Query? A PRQL Tutorial in 5 Steps

Your first PRQL query is the canonical five-line example from the project's own language book, and it teaches the only mental model PRQL has: each line takes the previous line's result and transforms it. Here it is, verbatim:

from tracks
filter artist == "Bob Marley"     # Each line transforms the previous result
aggregate {                       # `aggregate` reduces each column to a value
  plays    = sum plays,
  longest  = max length,
  shortest = min length,          # Trailing commas are allowed
}

Read it the way PRQL reads it. Step 1: from tracks starts the pipeline with the tracks table. Step 2: filter artist == "Bob Marley" keeps only matching rows. Step 3: aggregate { ... } collapses the remaining rows into one row with three computed columns. Step 4: compile it to SQL (next section). Step 5: run that SQL on any database.

Compiling this query on 2026-11-02 with the real compiler (prqlc 0.13.14) produced exactly the SQL the book promises:

SELECT
  COALESCE(SUM(plays), 0) AS plays,
  MAX(length) AS longest,
  MIN(length) AS shortest
FROM
  tracks
WHERE
  artist = 'Bob Marley'

The compiler even appends a signature comment — -- Generated by PRQL compiler version:0.13.14 — so you can always trace generated SQL back to its source. That is the whole pitch of this PRQL tutorial in miniature: you never debug SQL to write PRQL; you write the pipeline, and PRQL writes the SQL.

The Pipeline Lesson: How Does Each PRQL Verb Map to SQL?

The pipeline lesson is the single idea that makes PRQL click: every PRQL verb is one transformation of the table flowing through the pipeline, and every verb has an exact SQL counterpart. Learn the nine verbs below and you can read any PRQL query.

The filter row deserves attention because it is the verb that breaks SQL habits fastest: the language book states that "filter replaces both of SQL's WHERE & HAVING" — where the filter sits in the pipeline decides which one it becomes. Here is a second example, computed with the real compiler for this guide, showing derive, sort, and take in one pipeline:

from employees
filter salary > 80000
derive bonus = salary * 0.10
select {name, salary, bonus}
sort {-salary}
take 5

And the SQL the compiler generated for it, byte for byte:

SELECT
  name,
  salary,
  salary * 0.1 AS bonus
FROM
  employees
WHERE
  salary > 80000
ORDER BY
  salary DESC
LIMIT
  5

Notice what happened: the pipeline order became the SQL clause order, derive turned into a computed column, sort {-salary} became ORDER BY salary DESC, and take 5 became LIMIT 5. Nothing is hidden — the generated SQL is readable enough to commit to a repository, which is exactly how PRQL is meant to be used.

How Do You Compile PRQL to SQL?

You compile PRQL with the prqlc command line, which reads a PRQL query and prints the equivalent SQL. The book documents the pattern as piping a query into the compiler: echo '...' | prqlc compile. The compiler targets fourteen SQL dialects — the full list, confirmed against the live compiler on 2026-11-02, is sql.any, sql.ansi, sql.bigquery, sql.clickhouse, sql.duckdb, sql.generic, sql.glaredb, sql.mssql, sql.mysql, sql.oracle, sql.postgres, sql.redshift, sql.sqlite, and sql.snowflake.

That dialect list answers the most common beginner question — "does PRQL work with my database?" — with a yes for essentially every mainstream SQL database. The compiler also has a notable real-world adoption: ClickHouse natively supports PRQL, quoted on the project's homepage. If ClickHouse is your database, our ClickHouse beginner guide is the natural next read after this one.

How to Try PRQL Without Installing Anything: The Playground

The fastest way to try PRQL is the official playground at prql-lang.org/playground, which lets you type PRQL in the browser and watch the compiled SQL appear beside it. It is the same compiler, just hosted — ideal for following along with this guide before you install anything. The project's README links it as the place to "experiment with PRQL in the browser," and for a beginner it removes every excuse: no install, no database, just the pipeline lesson in front of you.

How to Use PRQL with Python (prql python)

The Python bindings are the main way developers actually use PRQL: pip install prqlc gives you a prqlc.compile() function that takes a PRQL string and returns SQL. The call this guide verified live on 2026-11-02 is simply:

import prqlc

prql_query = """
from tracks
filter artist == "Bob Marley"
aggregate { plays = sum plays }
"""

sql = prqlc.compile(prql_query)
print(sql)

The bindings also accept compile options, including a target such as target="sql.postgres" to pin the SQL dialect, plus formatting and signature-comment flags. The PRQL ecosystem around Python includes a Jupyter magic and the pyprql project for notebook use — if notebooks are your working environment, our Jupyter beginner guide pairs naturally with PRQL's interactive style. The wider tooling ecosystem, documented with the language, includes a VS Code extension, the QStudio IDE integration, and plprql, a Postgres extension that runs PRQL inside PostgreSQL v12 through v16.

How to Use PRQL with dbt (The dbt Arc)

PRQL reaches dbt models through the dbt-prql adapter, installed with pip install dbt-prql — and it works differently from what most beginners expect. Any text between {% prql %} and {% endprql %} tags inside an ordinary dbt model is compiled from PRQL to SQL; anything inside {{...}} passes through to the dbt parser untouched:

{% prql %}
from orders
filter status == "paid"
select {order_id, total}
{% endprql %}

Two cautions, straight from the adapter's own documentation. First, it does not use .prql model files today — that is on the project's roadmap ("We'd love to have this work on .prql files without the {% prql %} tags"), not the current behavior. Second, it works by monkeypatching dbt's Jinja environment — its own authors call this "dark magic" — which "isn't stable between dbt versions, since it relies on internal dbt APIs." The project publishes no dbt-version compatibility matrix, only an open invitation to report problems. You can disable the patching with the DBT_PRQL_DISABLE=1 environment variable and remove it with pip uninstall dbt-prql. If dbt itself is new to you, start with our dbt beginner guide before adding PRQL to the mix.

PRQL vs SQL vs Malloy: When Is PRQL the Right Tool?

PRQL vs SQL is not a fair fight — PRQL compiles to SQL, so you are choosing a writing style, not a platform. Choose PRQL when SQL's backwards clause order slows you down: the pipeline reads top-to-bottom the way you think about the data, and the compiled SQL is still yours to inspect, commit, and run anywhere. Choose raw SQL when you are writing a one-off query that the whole team must read without learning anything new. The real comparison beginners need is PRQL vs Malloy, because both are billed as SQL alternatives: PRQL is a pipelined SQL-syntax replacement that compiles to SQL for any SQL database, while Malloy is an open-source semantic modeling and query language built on top of SQL engines — it models reusable data relationships (sources, measures, dimensions) as well as querying them.

None of these are rivals — they stack. A team can model its business logic in Malloy, write its transformations as PRQL pipelines, and run both against the same warehouse, because both compile down to the same SQL.

7 Beginner Mistakes with PRQL

Sources

PRQL GitHub README (github.com/PRQL/prql) — official definition of PRQL, "ready to use by the intrepid" status (July 2026), Apache License 2.0, repository created 2022-01-18, 10,937-star snapshot; PRQL language book Introduction (prql-lang.org/book/) — canonical Bob Marley first-query example, verbatim compiled SQL, "filter replaces both of SQL's WHERE & HAVING"; PRQL book prqlc CLI page (prql-lang.org/book/project/integrations/prqlc-cli.html) — brew/winget/cargo install commands, single dependency-free Rust binary; PRQL book Python bindings page (prql-lang.org/book/project/bindings/python.html) — pip install prqlc, prqlc.compile() options including target="sql.postgres", dialect targets; PRQL book changelog (prql-lang.org/book/project/changelog.html) — version 0.13.14; PyPI prqlc (pypi.org/project/prqlc/) — 0.13.14 release uploaded July 2026; PRQL playground (prql-lang.org/playground) — browser-based try-it; dbt-prql on PyPI (pypi.org/project/dbt-prql/0.1.0/) — {% prql %} tag mechanics, Jinja monkeypatching ("dark magic"), DBT_PRQL_DISABLE=1; libraries.io dbt-prql — version 0.2.3, roadmap note on .prql files; Malloy GitHub README (github.com/malloydata/malloy) — "A semantic modeling and query language built on top of SQL"; docs.rs plprql — ecosystem listing: VS Code extension, Jupyter magic/pyprql, QStudio IDE integration, plprql Postgres extension; prql-lang.org homepage — ClickHouse native PRQL support. Author's own live verification, 2026-11-02: pip install prqlc installed 0.13.14; the Bob Marley example and the employees derive/sort/take pipeline were compiled with the real prqlc.compile() and produced the SQL shown in this article byte for byte; prqlc.get_targets() returned all 14 dialects. Version and star counts move over time — figures above are snapshots.

Frequently Asked Questions

Is PRQL a database or a language?

PRQL is a language, not a database. It compiles your pipeline into SQL, and the SQL runs on your existing database — Postgres, BigQuery, DuckDB, Snowflake, or any of the other eleven supported dialects. PRQL never stores data and never replaces your database.

How do you pronounce PRQL?

"Prequel." The name stands for Pipelined Relational Query Language, and the project's own definition spells out the pronunciation. If someone says they use "PRQL" for pattern recognition, they are talking about an unrelated name collision, not this language.

Can PRQL replace SQL completely?

For writing transformations, yes — that is its stated purpose as "a simple, powerful, pipelined SQL replacement." But it compiles to SQL, so SQL remains the substrate: your database executes SQL, and every PRQL query becomes SQL before it runs. Teams usually adopt PRQL for authoring and keep reading the generated SQL for review and debugging.

Does PRQL work with my database?

Almost certainly. The compiler targets fourteen SQL dialects, including Postgres, MySQL, SQLite, BigQuery, Snowflake, Redshift, ClickHouse, DuckDB, MSSQL, and Oracle, plus generic ANSI and "any" SQL fallbacks. ClickHouse goes further and natively supports PRQL syntax.

Is PRQL ready for production?

For the intrepid, yes; for everyone, not quite yet. The project's own status page (July 2026) says PRQL is "ready to use by the intrepid" with "some bugs and some missing features," and that it is "probably only ready to be rolled out to non-technical teams for fairly simple queries." Try it on real work, pin your compiler version, and inspect the generated SQL before it matters.