اگر تا امروز برای هر تحلیل ساده مجبور بودید یک سرور پایگاه داده بالا بیاورید، DuckDB کل کار را به یک pip install تبدیل می‌کند. DuckDB یک پایگاه داده تحلیلی درون‌حافظه‌ای و متن‌باز است که مستقیم داخل پروسه پایتون اجرا می‌شود و روی فایل‌های CSV، Parquet، JSON و حتی DataFrame پانداز کوئری SQL می‌زند. نصبش چند ثانیه طول می‌کشد، به سرور و رمز عبور نیاز ندارد و برای فایل‌های چندگیگابایتی خیلی کمتر از Pandas رم مصرف می‌کند. در ادامه از نصب تا اولین گزارش واقعی، همه چیز را قدم‌به‌قدم می‌بینید.

DuckDB چیست و چرا برای تحلیل داده در پایتون مناسب است؟

DuckDB یک موتور پایگاه داده کارا با تمرکز بر پرس‌وجوی تحلیلی (OLAP) است که به‌جای اجرا روی سرور جدا، داخل همان برنامه پایتون شما اجرا می‌شود. یعنی بدون نصب سرویس و بدون تنظیم دسترسی، همان SQL استاندارد را روی فایل خام یا داده درون‌حافظه‌ای اجرا می‌کنید. اگر داده شما CSV، Parquet، JSON یا خروجی یک کتابخانه پایتون است، این ابزار معمولاً سریع‌ترین راه رسیدن به نتیجه است. در ادامه نصب، اولین کوئری، کار با پانداز و مقایسه با گزینه‌های رقیب را می‌بینید.

فهرست مطالب

پیش‌نیازها و نصب DuckDB در چند ثانیه
اولین کوئری: تحلیل فایل CSV بدون خواندن دستی
اجرای SQL مستقیم روی پانداز و Polars
Parquet؛ مسیر سریع برای داده‌های بزرگ
DuckDB یا SQLite یا PostgreSQL؟ جدول تصمیم
ابزارهای تحلیلی آماده که کار را کوتاه می‌کنند
خطاهای رایج در DuckDB و راه‌حل آن‌ها
امنیت و نکات استقرار که باید بدانید
سوالات متداول
جمع‌بندی و مسیر ادامه یادگیری

پیش‌نیازها و نصب DuckDB در چند ثانیه

DuckDB کلاینت رسمی پایتون دارد و فقط کافی است بسته duckdb را نصب کنید. نسخه پایدار فعلی کلاینت پایتون ۱.۵.۶ است و برای اجرا به پایتون ۳.۹ یا بالاتر نیاز دارد. اگر مثل بیشتر پروژه‌های امروزی با uv یا pip کار می‌کنید، هر دو مسیر در ادامه آمده است.

# با pip
pip install duckdb

# یا با uv در پروژه
uv add duckdb

برای اطمینان از نصب، نسخه را چاپ کنید و یک کوئری بی‌ضرر بزنید:

import duckdb

print(duckdb.__version__)
duckdb.sql("SELECT 42 AS answer").show()

خروجی این کد یک جدول کوچک با یک ستون به نام answer و مقدار ۴۲ است. اگر همین را دیدید، همه چیز آماده است. در محیط‌هایی که اینترنت ندارید، نصب از طریق پکیج‌های داخلی یا ساخت یک venv جدید ساده‌ترین راه است.

اولین کوئری: تحلیل فایل CSV بدون خواندن دستی

بزرگ‌ترین مزیت DuckDB این است که لازم نیست فایل را با pd.read_csv() کامل در حافظه بریزید. موتور فقط ستون‌ها و سطرهای لازم را می‌خواند و بقیه را روی دیسک رد می‌کند. برای شروع، یک فایل orders.csv فرض کنید که ستون‌های city، status و total را دارد.

import duckdb

rel = duckdb.sql("""
    SELECT
        city,
        COUNT(*) AS orders,
        ROUND(SUM(total), 0) AS revenue
    FROM 'orders.csv'
    WHERE status = 'done'
    GROUP BY city
    ORDER BY revenue DESC
    LIMIT 10
""")

print(rel)          # چاپ مستقیم جدول در ترمینال
df = rel.df()       # تبدیل نتیجه به DataFrame پانداز
df.to_csv("top_cities.csv", index=False)

نکته ظریف این کد همین خط FROM 'orders.csv' است: نام فایل باید داخل تک‌کوتیشن باشد. DuckDB آن را به‌عنوان یک جدول مجازی می‌بیند، نوع ستون‌ها را خودش حدس می‌زند و فقط همان بخش از فایل را می‌خواند. اگر ترجیح می‌دهید صریح‌تر باشید، از توابع ورودی استفاده کنید:

# خواندن با تنظیمات صریح
tbl = duckdb.read_csv(
    "orders.csv",
    header=True,
    all_varchar=False,
    sample_size=-1,          # تشخیص نوع ستون با کل فایل
)

# یا همان جایگزینی مستقیم
duckdb.sql("SELECT COUNT(*) FROM read_csv('orders.csv')").show()

برای شناخت سریع ساختار یک فایل ناشناخته، دستور SUMMARIZE کار را برایتان انجام می‌دهد و تعداد سطر، مقادیر خالی، کمینه و بیشینه هر ستون را نشان می‌دهد.

اجرای SQL مستقیم روی پانداز و Polars

اگر همین حالا در پروژه‌تان DataFrame دارید، لازم نیست آن را به دیسک بریزید. DuckDB می‌تواند مستقیم روی داده درون‌حافظه‌ای کوئری بزند؛ فقط نام متغیر را داخل SQL بنویسید. این یعنی همان گروه‌بندی و Join که در Pandas با زنجیره متدهای طولانی می‌شد، در چند خط SQL تمام می‌شود.

import duckdb
import pandas as pd

orders = pd.read_csv("orders.csv")
customers = pd.read_parquet("customers.parquet")

report = duckdb.sql("""
    SELECT
        c.segment,
        COUNT(*) AS orders,
        ROUND(SUM(o.total), 0) AS revenue
    FROM orders o
    JOIN customers c ON c.id = o.customer_id
    WHERE o.status = 'done'
    GROUP BY c.segment
    ORDER BY revenue DESC
""").df()

print(report)

خروجی دوباره یک DataFrame است و می‌توانید بلافاصله آن را ذخیره یا نمودار کنید. همین الگو با Polars یا جدول‌های PyArrow هم کار می‌کند. یک محدودیت را جدی بگیرید: DataFrameهای پایتونی در DuckDB فقط خواندنی هستند و نمی‌توانید با INSERT یا UPDATE آن‌ها را تغییر دهید. اگر نتیجه را می‌خواهید ذخیره کنید، آن را با rel.df() یا rel.write_parquet() بیرون بیاورید.

برای کار با دیتابیس‌های واقعی هم افزونه‌های آماده وجود دارد؛ مثلاً با افزونه SQLite می‌توانید یک فایل موجود را بدون مهاجرت کامل به DuckDB کوئری بزنید:

con = duckdb.connect("analytics.duckdb")
con.execute("INSTALL sqlite; LOAD sqlite;")
con.execute("ATTACH 'app.db' AS sqlite_db (TYPE sqlite)")

con.sql("SELECT COUNT(*) FROM sqlite_db.users").show()

Parquet؛ مسیر سریع برای داده‌های بزرگ

اگر فایل‌های شما هر بار خوانده و پردازش می‌شوند، تبدیل یک‌باره آن‌ها به Parquet معمولاً بهترین سرمایه‌گذاری است. Parquet فشرده‌سازی ستونی دارد و DuckDB می‌تواند بدون باز کردن کل فایل، فقط ستون‌های لازم را بخواند. ذخیره‌سازی ستونی دقیقاً همان چیزی است که باعث سرعت این مسیر می‌شود.

import duckdb

# تبدیل دسته‌ای چند فایل به یک Parquet فشرده
duckdb.sql("""
    COPY (SELECT * FROM 'raw_logs/*.csv' WHERE country = 'IR')
    TO 'logs_ir.parquet'
    (FORMAT PARQUET, COMPRESSION ZSTD)
""").show()

# خواندن با فیلتر و ستون‌های مشخص
duckdb.sql("""
    SELECT event_date, count(*) AS hits
    FROM 'logs_ir.parquet'
    WHERE event_date >= DATE '2025-01-01'
    GROUP BY event_date
    ORDER BY event_date
""").show()

با الگوی ستاره‌ای (مثل 'logs/2025-*.parquet') می‌توانید چند فایل را هم‌زمان کوئری بگیرید، بدون اینکه اول آن‌ها را به یک فایل بچسبانید. اگر خروجی نهایی را می‌خواهید، rel.write_parquet("out.parquet") همان کار را از سمت پایتون انجام می‌دهد.

DuckDB یا SQLite یا PostgreSQL؟ جدول تصمیم

پرتکرارترین اشتباه این است که DuckDB را با گزینه‌های موجود جایگزین کنیم. این جدول تفاوت‌ها را روشن می‌کند:

معیار	DuckDB	SQLite	PostgreSQL / MySQL
مدل اجرا	داخل پروسه (embedded)	داخل پروسه (embedded)	سرویس شبکه‌ای جدا
تمرکز طراحی	تحلیل و گزارش (OLAP)	ذخیره‌سازی سبک و تراکنش (OLTP)	سیستم عملیاتی چندکاربره
نصب	یک خط pip	یک فایل یا کتابخانه	نصب سرویس و تنظیم دسترسی
کاربران هم‌زمان	یک نویسنده در هر فایل	محدود	چند کاربره با قفل‌گذاری
خواندن مستقیم Parquet و CSV	بله و بسیار سریع	ندارد	ندارد
بهترین کاربرد	لاگ، CSV، گزارش دوره‌ای، تحلیل آفلاین	اپلیکیشن محلی و موبایل	سایت و اپ چندکاربره
محدودیت اصلی	سرویس شبکه‌ای و نوشتن هم‌زمان ندارد	تحلیل حجیم روی آن کند است	راه‌اندازی و نگهداری سنگین‌تر

خلاصه تصمیم: اگر داده روی فایل است و می‌خواهید سریع تحلیل کنید، DuckDB. اگر داده تراکنشی و نیازمند چند کاربر است، پایگاه داده سمت سرور را نگه دارید. این دو رقیب هم نیستند و در معماری واقعی کنار هم استفاده می‌شوند. اگر داده‌های شما اسنادی و تراکنشی است و می‌خواهید از صفر یک دیتابیس واقعی راه بیندازید، راهنمای آموزش MongoDB در پایتون با PyMongo نقطه شروع خوبی است.

ابزارهای تحلیلی آماده که کار را کوتاه می‌کنند

چند قابلیت که در ابزارهای رایج کمتر دیده می‌شود و کار روزمره را ساده می‌کند:

PIVOT تبدیل سطرها به ستون بدون نوشتن Join و شرط‌های تودرتو؛ برای گزارش ماهانه فروش عالی است.
ASOF JOIN برای وصل کردن دو سری زمانی به نزدیک‌ترین رکورد قبلی؛ همان کاری که در گزارش نرخ ارز و قیمت لحظه‌ای لازم می‌شود.
QUALIFY فیلتر کردن نتیجه توابع پنجره‌ای بدون نوشتن زیرپرس‌وجوی تودرتو.
DESCRIBE و EXPLAIN ANALYZE برای دیدن ساختار داده و ریشه کندی کوئری، همان کاری که EXPLAIN در دیتابیس‌های سروری انجام می‌دهد.
خروجی مستقیم به DataFrame، Arrow و Parquet با یک متد، بدون حلقه‌های تبدیل دستی.

برای متن فارسی هم یک نکته مهم وجود دارد. ذخیره‌سازی رشته‌ها UTF-8 است، اما اگر می‌خواهید مقایسه و مرتب‌سازی به بزرگی و کوچکی حروف حساس نباشد، افزونه ICU را نصب و بارگذاری کنید:

import duckdb

con = duckdb.connect("shop.duckdb")
con.execute("INSTALL icu; LOAD icu;")

con.sql("""
    SELECT count(*)
    FROM products
    WHERE lower(name) = lower('کتلگ')
""").show()

خطاهای رایج در DuckDB و راه‌حل آن‌ها

استفاده از اتصال سراسری داخل نخ‌ها: تابع duckdb.sql() و duckdb.connect(':default:') از یک اتصال مشترک استفاده می‌کنند و برای اجرای هم‌زمان نخ‌ها مناسب نیستند. راه‌حل: برای هر نخ یک duckdb.connect() جدا بسازید.
خطای Catalog: Table does not exist وقتی نام فایل را بدون تک‌کوتیشن داخل SQL نوشته‌اید. نام فایل باید داخل تک‌کوتیشن باشد یا از read_csv() و read_parquet() استفاده کنید.
تشخیص اشتباه نوع ستون در CSV: اگر ستونی ترکیب عدد و متن داشته باشد، مقدار به VARCHAR تبدیل و کوئری شکست می‌خورد. با sample_size=-1 کل فایل را نمونه‌برداری کنید یا با all_varchar=true همه چیز را متنی بخوانید و در صورت نیاز CAST کنید.
شکست نصب یا بارگذاری افزونه در محیط آفلاین: بارگذاری افزونه‌های community به اینترنت و اعتماد به منبع نیاز دارد. در محیط بدون اینترنت، افزونه‌های اصلی را از پیش نصب کنید و فقط از منابع مورد اعتماد استفاده کنید.
کمبود حافظه روی فایل حجیم: به جای SELECT * فقط ستون‌های لازم را بخوانید، فیلترها را داخل SQL بنویسید تا پیش از خواندن داده اعمال شوند، و نتیجه را Parquet کنید.
انتظار نوشتن هم‌زمان از چند پروسه: DuckDB برای یک نویسنده در هر فایل طراحی شده است. اگر چند سرویس هم‌زمان روی یک فایل بنویسند، به پایگاه داده سمت سرور نیاز دارید.

امنیت و نکات استقرار که باید بدانید

فایل DuckDB مثل یک دیتابیس واقعی است: آن را در مخزن گیت کامیت نکنید و در .gitignore بگذارید.
روی درایو شبکه‌ای اشتراکی با نوشتن هم‌زمان چند ماشین کار نکنید؛ فایل را محلی نگه دارید و در صورت نیاز خروجی را همگام کنید.
اطلاعات حساس را در نوت‌بوک یا داخل کد ننویسید؛ برای کلیدها و توکن‌ها از CREATE SECRET و مدیریت Secret استفاده کنید.
افزونه‌ها را فقط از منبع مورد اعتماد بارگذاری کنید؛ فعال کردن افزونه‌های امضانشده گزینه ریسکی است.
در وب‌اپلیکیشن، DuckDB را در مسیر هر درخواست نسازید؛ یک اتصال را در استارتاپ بسازید و همان را نگه دارید.

سوالات متداول

آیا DuckDB جایگزین PostgreSQL است؟

نه. این دو مسئولیت متفاوت دارند. اگر چند کاربر هم‌زمان دارید، داده تراکنشی می‌نویسید و به دسترسی شبکه‌ای نیاز دارید، PostgreSQL یا MySQL انتخاب درست است. DuckDB برای تحلیل سریع فایل و داده درون‌حافظه‌ای ساخته شده است. در عمل بسیاری از پروژه‌ها هر دو را دارند: سیستم عملیاتی روی دیتابیس سرور و گزارش‌های تحلیلی روی DuckDB.

برای فایلی بزرگ‌تر از حافظه رم چه کار کنم؟

چند کار ساده انجام دهید: به جای SELECT * فقط ستون‌های لازم را بخوانید، فیلترها را داخل SQL بنویسید تا پیش از خواندن داده اعمال شوند، و داده را در چند فایل Parquet نگه دارید تا پردازش موازی شود. اگر یک عملیات به کل یک ستون نیاز داشته باشد، فشار حافظه جدی می‌شود؛ در آن حالت پیش از تحلیل، ستون‌های اضافه را در مرحله تبدیل حذف کنید.

DuckDB با Pandas و Polars چه تفاوتی دارد؟

پانداز و Polars کتابخانه پردازش داده در حافظه‌اند و روی DataFrame کار می‌کنند. DuckDB یک موتور پایگاه داده است که می‌تواند مستقیم روی فایل و روی DataFrame شما SQL اجرا کند. این سه با هم رقیب نیستند و در یک پروژه واقعی کنار هم استفاده می‌شوند: کتابخانه برای تبدیل و مدل‌سازی، DuckDB برای پرس‌وجو و گروه‌بندی.

آیا DuckDB برای متن فارسی مناسب است؟

بله، چون رشته‌ها به‌صورت UTF-8 ذخیره می‌شوند. برای مقایسه و مرتب‌سازی حساس به بزرگی و کوچکی حروف، افزونه ICU را نصب و بارگذاری کنید و از توابع متنی مثل lower() استفاده کنید. برای جست‌وجوی کامل متن هم افزونه FTS در دسترس است.

چطور DuckDB را به پروژه FastAPI یا Django وصل کنم؟

سه راه عملی دارید: اتصال مستقیم با duckdb.connect() و بستن آن در پایان کار، استفاده از درایور SQLAlchemy به نام duckdb-engine اگر با لایه ORM کار می‌کنید، یا اجرای DuckDB در مرحله پردازش داده و ذخیره نتیجه در فایل Parquet که سرویس شما بعداً آن را می‌خواند. گزینه آخر معمولاً تمیزترین معماری برای سرویس‌های چندworker است.

جمع‌بندی و مسیر ادامه یادگیری

چک‌لیست عملی این مقاله:

با pip install duckdb نصب کنید و نسخه را با duckdb.__version__ بررسی کنید.
اولین کوئری را روی فایل واقعی خودتان با duckdb.sql("SELECT ... FROM 'file.csv'") اجرا کنید.
برای فایل‌هایی که مدام پردازش می‌شوند، یک‌بار به Parquet با فشرده‌سازی ZSTD تبدیل کنید.
قبل از انتخاب ابزار، جدول تصمیم بالا را بخوانید؛ DuckDB جایگزین دیتابیس عملیاتی نیست.
برای هر نخ یک اتصال جدا بسازید و از اتصال سراسری در حالت چندنخی استفاده نکنید.
برای ادامه، مستندات رسمی Python API و راهنمای عملکرد DuckDB را دنبال کنید.

DuckDB کوچک، رایگان و سریع است و دقیقاً جایی می‌نشیند که بیشتر پروژه‌های تحلیلی پایتون دردسر دارند: همان چند خط SQL روی فایلی که همین حالا روی دیسک دارید. اگر تحلیل داده در پروژه شما امروز با کوپی‌پیست‌های طولانی Pandas انجام می‌شود، همین امروز اولین کوئری را روی فایل واقعی خودتان اجرا کنید و زمان اجرا را مقایسه کنید؛ معمولاً همان یک تجربه، ادامه مسیر را روشن می‌کند.

آموزش DuckDB در پایتون؛ تحلیل داده بدون سرور