Working with the Relational API

DuckDB’s Relational API provides a convenient and effective Python interface for composing and working with DuckDB queries. It provides a flexible and efficient way to interact with DuckDB in Python and is especially well suited to interactive data analysis workflows.

The Relational API revolves around DuckDBPyRelation objects, which are more generally referred to as relations. You can think of a DuckDB relation as a representation of a DuckDB query. Relations do not contain data themselves but rather contain all the information about a query required for execution. Relations are lazily evaluated, which means that when you are working with them, nothing is run against the database until the result set for a query is needed, such as when you want to display their results interactively or when the full result set is materialized for loading into a table or exporting to a specific data format.

The laziness of DuckDB’s relations provides...