Using DuckDB for fast data analysis in Python in 2023: A tutorial and overview

Explore the power of DuckDB for Python data analysis in 2023 with our tutorial, covering installation, querying, and optimization tips.

Cartesian Mathematics Foundation


November 2, 2023

Introduction to DuckDB

DuckDB is an in-memory analytical data management system designed to execute analytical SQL queries fast, efficiently, and reliably. It is an open-source project that aims to be the SQLite for analytics, providing a lightweight, easy-to-use database solution optimized for analytical workloads.

What is DuckDB?

DuckDB is a database management system that focuses on analytical data processing and query execution. It is designed to handle complex analytical queries on large datasets with high performance. Unlike traditional databases that are optimized for transactional workloads, DuckDB is built from the ground up to support the needs of data analysts and scientists. One of the key features of DuckDB is its columnar storage format, which allows for efficient querying and data compression. This storage format is particularly beneficial for analytical queries that typically scan large volumes of data and perform aggregations.

Benefits of using DuckDB for data analysis

DuckDB offers several advantages for data analysis, including:

  • Performance: DuckDB’s columnar storage and vectorized query execution make it extremely fast for analytical queries.

  • Ease of Use: With no external dependencies and a simple installation process, DuckDB is easy to set up and use.

  • Concurrency: DuckDB supports concurrent read and write operations, making it suitable for multi-user environments.

  • Integration: DuckDB can be easily integrated with popular data analysis tools like Pandas and R, streamlining the data analysis workflow.

  • Portability: DuckDB is a single-file database, similar to SQLite, which means it is easy to share and requires no server setup.

Comparison with other databases (e.g., SQLite, PostgreSQL)

When compared to other databases, DuckDB stands out in several ways:

  • SQLite: While SQLite is also a single-file, serverless database, it is optimized for transactional workloads and not for analytical queries. DuckDB, on the other hand, is designed specifically for analytics.

  • PostgreSQL: PostgreSQL is a powerful, full-featured database system that can handle analytical workloads. However, it requires more setup and maintenance than DuckDB and may not be as performant for certain analytical queries.

Installing DuckDB in Python (using pip)

Installing DuckDB in Python is straightforward and can be done using the pip package manager. Here’s how you can install DuckDB:

pip install duckdb

Once the installation is complete, you can import DuckDB in your Python script or interactive environment like Jupyter Notebook.

Establishing a Connection to DuckDB using Python

To interact with DuckDB, we first need to establish a connection. DuckDB makes this process straightforward:

import duckdb
# Establish a connection to an in-memory database
conn = duckdb.connect(database=':memory:', read_only=False)

This creates a new in-memory database that we can use for our session. If you want to persist data, you can specify a file path instead of ':memory:'.

Basic DuckDB Operations

Now that we have a connection, let’s go through some basic operations.

Creating a Table

To create a new table in DuckDB, use the execute method:

    id INTEGER,
    name VARCHAR,
    email VARCHAR,
    join_date DATE

Inserting Data

Insert data into the table using the execute method:

INSERT INTO users (id, name, email, join_date) VALUES
(1, 'Alice', '', '2021-01-01'),
(2, 'Bob', '', '2021-02-01')

Selecting Data

Retrieve data from the table with a SELECT statement:

result = conn.execute("SELECT * FROM users").fetchall()

Updating Data

Update existing data using the UPDATE statement:

UPDATE users
SET email = ''
WHERE name = 'Alice'

Deleting Data

Remove data from the table with the DELETE statement:

conn.execute("DELETE FROM users WHERE name = 'Bob'")

Understanding DuckDB Data Types and Schema Design

DuckDB supports a variety of data types, including integers, floating-point numbers, strings, dates, and more. When designing your schema, it’s important to choose the appropriate data type for each column to ensure data integrity and optimize performance.

Here’s a brief overview of some common DuckDB data types: - INTEGER: A whole number without a fractional component. - VARCHAR: A variable-length string. - DATE: A calendar date (year, month, day).

When designing your schema, consider the nature of the data you’ll be storing and choose the most appropriate data types.

Advanced Querying and Data Manipulation

In this section, we delve into the more sophisticated aspects of querying and data manipulation using DuckDB. We will explore analytical functions, aggregate functions, window functions, join operations, set operations, and how to handle complex data types like date, time, arrays, and nested records. Each topic will be accompanied by code examples and explanations to provide a comprehensive understanding of these advanced features.

Using DuckDB’s Analytical Functions

Analytical functions in DuckDB allow you to perform complex calculations over a set of rows that are related to the current row. These functions are often used in conjunction with the OVER() clause, which defines the window or set of rows the function operates on.

# Example of using an analytical function
  AVG(salary) OVER (PARTITION BY department) AS avg_department_salary
FROM employees;

In the above query, the AVG() function calculates the average salary within each department, allowing you to compare individual salaries to their department average. ### Working with Aggregate Functions Aggregate functions compute a single result from a set of input values. DuckDB provides a variety of aggregate functions such as SUM(), COUNT(), MAX(), and MIN().

# Example of using aggregate functions
  COUNT(*) AS employee_count,
  MAX(salary) AS max_salary
FROM employees
GROUP BY department;

This query returns the number of employees and the maximum salary within each department.

Window Functions and Their Use Cases

Window functions perform calculations across a set of rows related to the current row, similar to analytical functions. However, window functions do not cause rows to become grouped into a single output row — the rows retain their separate identities.

# Example of using a window function
  RANK() OVER (ORDER BY salary DESC) AS salary_rank
FROM employees;

Here, the RANK() function assigns a rank to each employee based on their salary, with the highest salary receiving rank 1. ### Join Operations and Set Operations Joins and set operations are fundamental for combining data from multiple tables or queries.

# Example of a join operation
FROM employees e
JOIN departments d ON e.department_id = d.department_id;

This join operation links employees with their respective departments based on a common department ID. Set operations like UNION, INTERSECT, and EXCEPT allow you to combine results from multiple queries.

# Example of a set operation
SELECT employee_id FROM employees
SELECT manager_id FROM departments;

The UNION operation returns a list of unique employee IDs and manager IDs. ### Handling Date and Time Data DuckDB provides functions to handle date and time data effectively.

# Example of working with date and time
  DATE_PART('year', order_date) AS order_year
FROM orders;

The DATE_PART() function extracts the year from the order_date column. ### Working with Arrays and Nested Records DuckDB supports arrays and nested records, which can be useful for storing and querying multi-dimensional data.

# Example of working with arrays
FROM products
WHERE ARRAY_LENGTH(product_features) > 3;

This query selects products with more than three features.

Advanced querying and data manipulation in DuckDB enable you to perform sophisticated data analysis with ease. By mastering these concepts, you can unlock the full potential of DuckDB for your data analysis tasks.

Performance Optimization and Best Practices

Optimizing performance and adhering to best practices are crucial for getting the most out of DuckDB, especially when dealing with large datasets. This section will guide you through various strategies to enhance the speed and efficiency of your DuckDB operations.

Indexing Strategies in DuckDB

Unlike traditional databases, DuckDB does not support the creation of secondary indexes. DuckDB is designed to be a columnar database, which inherently provides efficient querying without the need for additional indexing structures. However, you can still optimize query performance by considering the following:

  • Column Order: Place frequently filtered columns earlier in your table schema. DuckDB stores data in a columnar format, so queries that filter or aggregate on these columns can be more efficient.

  • Partitioning: For very large tables, consider partitioning your data by a key column. This can be done by creating separate tables for each partition and using a UNION ALL view to combine them for querying.

  • Clustering: While DuckDB does not have explicit clustering keys, you can sort your data on disk by certain columns to improve the performance of range scans.

Query Optimization Tips

To optimize your queries in DuckDB, consider the following tips:

  • Use WHERE Clauses Wisely: Apply filters as early as possible in your queries to reduce the amount of data processed.

  • Select Only Necessary Columns: Avoid using SELECT * and instead specify only the columns you need.

  • Take Advantage of Columnar Storage: DuckDB performs best with operations that can be vectorized, such as column-wise computations and aggregates.

  • Batch Inserts: When inserting data, batch multiple rows together to minimize the overhead of transaction processing.

Understanding and Using Execution Plans

Understanding the execution plan of a query can help you identify potential bottlenecks. In DuckDB, you can use the EXPLAIN statement to get a detailed execution plan:

EXPLAIN SELECT * FROM my_table WHERE my_column > 10;

The output will show you the steps DuckDB takes to execute the query, including scans, joins, and filters. Analyze the plan to ensure that the database is processing the query as expected.

Best Practices for Data Import/Export

When importing or exporting data, consider the following best practices:

  • Use Efficient Formats: For importing data, DuckDB works well with Parquet and CSV files. Parquet is especially efficient as it is a columnar storage format.

  • Copy Command: Use the COPY command to import or export data, as it is optimized for bulk operations.

  • Compress Data: When exporting data, consider using compression to reduce file size and improve I/O performance.

Integrating DuckDB with Data Analysis Libraries

DuckDB can be seamlessly integrated with popular data analysis libraries like Pandas. Here’s how you can work with DuckDB and Pandas together:

import duckdb
import pandas as pd
# Create a DuckDB connection
con = duckdb.connect()
# Create a DataFrame
df = pd.DataFrame({'a': [1, 2, 3], 'b': [4, 5, 6]})
# Write DataFrame to DuckDB
con.execute("CREATE TABLE my_table AS SELECT * FROM df")
# Read from DuckDB into a DataFrame
result_df = con.execute("SELECT * FROM my_table").fetchdf()
# Perform operations using Pandas
result_df['a_times_b'] = result_df['a'] * result_df['b']

By leveraging the power of DuckDB and Pandas together, you can perform complex data analysis tasks with ease.


Optimizing your use of DuckDB can lead to significant performance gains. By understanding how DuckDB processes data and applying the strategies outlined in this section, you can ensure that your data analysis workflows are both efficient and scalable. Remember to always test and measure the performance impact of any changes you make, and consult the DuckDB documentation for the latest features and best practices.

Appendix A: Additional Resources

Appendix B: Glossary of Terms

  • Columnar Storage: A data storage format that stores each column of data separately, which can improve performance for certain types of queries.

  • Vectorization: The process of processing multiple data points in a single operation, which can lead to significant performance improvements.

Appendix C: Troubleshooting Common Issues with DuckDB

  • Memory Limit Errors: If you encounter memory limit errors, consider increasing the memory limit using the PRAGMA memory_limit command.

  • Slow Queries: For queries that are running slower than expected, use the EXPLAIN command to analyze the execution plan and identify potential optimizations.

Appendix D: Additional Resources

  • DuckDB Official Website: The main landing page for DuckDB, which includes an overview of the project and links to various resources.
  • DuckDB Documentation: Comprehensive documentation that covers all aspects of using DuckDB, including installation, SQL syntax, functions, and configuration options.
  • DuckDB GitHub Repository: The source code repository for DuckDB, where you can find the latest code, report issues, and contribute to the project.
  • DuckDB Python API Reference: Detailed information about the DuckDB Python package, including installation instructions and usage examples.
  • DuckDB Blog: The official DuckDB blog, where you can find articles on new features, performance benchmarks, and use cases.
  • DuckDB Community: Links to community resources such as the DuckDB Slack channel, where you can ask questions and interact with other DuckDB users and developers.
  • Data Engineering Podcasts and Talks: Look for podcasts or talks featuring DuckDB to gain insights from the creators and users of DuckDB.
    • Search for “DuckDB” on podcast platforms or tech talk aggregators.
  • Stack Overflow: A popular Q&A site where you can search for DuckDB-related questions or ask your own.
  • DB-Engines Ranking: An overview of DuckDB’s ranking and popularity compared to other database management systems.
  • DuckDB Articles and Tutorials: Additional tutorials and articles written by the community that can provide different perspectives and use cases.
    • Search for “DuckDB tutorial” or “DuckDB use case” on your preferred search engine.

Including these resources in your appendix will give readers a well-rounded set of references to support their learning and application of DuckDB in their projects.