# فصل ۰۲ — قالبِ ذخیره، با عدد

<div dir="rtl">

# فصل ۰۲ — قالبِ ذخیره، با عدد

## در این فصل چه یاد می‌گیری

یک جدولِ ثابت را در پنج قالب می‌نویسیم و حجم و زمانِ خواندنش را اندازه می‌گیریم. `parquet` حدودِ **یک‌چهارمِ** `csv` جا می‌گیرد و `jsonl` **بزرگ‌تر** از `csv` درمی‌آید.

ولی نتیجهٔ اصلیِ فصل عدد نیست: **`csv` سه ستون از چهار ستونی که می‌سنجیم را بی‌صدا خراب می‌کند.** کدِ شعبهٔ `099` برمی‌گردد `99`، ستونِ زمان برمی‌گردد رشته، و امتیازِ صحیح برمی‌گردد اعشاری. **هیچ خطایی داده نمی‌شود** — و همان کد دفعهٔ بعد روی همان فایل نتیجهٔ دیگری می‌دهد.

![دو بایگانی: یکی پرونده‌های کامل، یکی کشوهایی که هرکدام فقط یک فیلد را نگه می‌دارند](/lesson-assets/t2-s02-storage-formats/prompt/01-image-row-vs-column.png)

آخر این فصل می‌توانی:

- حجم و زمانِ خواندنِ یک جدول را در قالب‌های مختلف اندازه بگیری
- تفاوتِ ذخیرهٔ سطری و ستونی را با یک آزمایش نشان بدهی
- بگویی هر قالب چه چیزی از تایپ‌ها را نگه می‌دارد و چه چیزی را دور می‌ریزد
- برای هر جای مسیر قالبِ درست را انتخاب کنی و دلیلش را با عدد بگویی

## قبل از شروع

**از فصل ۱:** پیکرهٔ خام و اینکه هر مرحله فایلی می‌سازد که مرحلهٔ بعد می‌خوانَد. **قالبِ آن فایل یک تصمیمِ مهندسی است، نه یک عادت.**

**از سرنخ ترمِ ۲:** `pandas`، `read_csv` و `dtype`.

> 💡 **نکته:** `pyarrow` در Colab از قبل نصب است، پس `to_parquet` بدونِ نصبِ چیزی کار می‌کند. اگر روی ماشینِ خودت اجرا می‌کنی و نبود، `pip install pyarrow` لازم می‌شود.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/darbast/term-2-data-as-infrastructure/session-02-storage-formats.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

</div>

| اجرا | زمانِ تقریبی |
|---|---|
| کلِ نوت‌بوک روی CPU | کمتر از یک دقیقه |
| GPU | لازم نیست |

<div dir="rtl">

## ۱. اول جدولی با تایپِ درست بساز

هر مقایسه‌ای بی‌معناست اگر خودِ جدول از اول خراب باشد. پس `csv` خام را **کاملاً به‌صورتِ رشته** می‌خوانیم و بعد هر ستون را دستی به تایپِ درستش می‌بریم.

</div>

```python
import pandas as pd

RAW = WORK / "raw" / "tickets.csv"
FMT = WORK / "formats"
FMT.mkdir(exist_ok=True)

raw = pd.read_csv(RAW, dtype=str, keep_default_na=False)   # هیچ حدسی نزن
df = raw.drop_duplicates().reset_index(drop=True)
df["created_at"] = pd.to_datetime(df["created_at"])
df["escalated"] = df["escalated"].astype("int8")
df["handling_minutes"] = df["handling_minutes"].astype("int32")
df["rating"] = pd.to_numeric(df["rating"], errors="coerce").astype("Int8")
# branch_code عمداً رشته می‌ماند: «007» با «7» یکی نیست
print("ردیف:", len(df), "· ستون:", len(df.columns))
print("branch_code ردیفِ اول:", df["branch_code"].iloc[0],
      "· نوعِ مقدار:", type(df["branch_code"].iloc[0]).__name__)
```

```text
ردیف: 1200 · ستون: 10
branch_code ردیفِ اول: 099 · نوعِ مقدار: str
```

<div dir="rtl">

`dtype=str` یعنی «حدس نزن»، و `keep_default_na=False` یعنی «رشتهٔ خالی را با `NaN` عوض نکن». **این دو با هم تنها راهِ خواندنِ یک `csv` بدونِ از دست دادنِ اطلاعات‌اند.** بعدش هر تبدیل را خودمان و آگاهانه انجام می‌دهیم.

`Int8` با `I` بزرگ یک تایپِ عددیِ **خالی‌پذیر** است: هم عددِ صحیح نگه می‌دارد و هم «مقدار ندارد». `int8` معمولی نمی‌تواند، و به همین دلیل `pandas` وقتی خودش حدس می‌زند ستونی با خانهٔ خالی را اعشاری می‌کند.

## ۲. یک جدول، پنج فایل

</div>

```python
PATHS = {
    "csv": FMT / "t.csv",
    "csv.gz": FMT / "t.csv.gz",
    "jsonl": FMT / "t.jsonl",
    "parquet": FMT / "t.parquet",
    "parquet+zstd": FMT / "t.zstd.parquet",
}
df.to_csv(PATHS["csv"], index=False, encoding="utf-8")
df.to_csv(PATHS["csv.gz"], index=False, encoding="utf-8", compression="gzip")
df.to_json(PATHS["jsonl"], orient="records", lines=True,
           force_ascii=False, date_format="iso")
df.to_parquet(PATHS["parquet"], index=False, compression="snappy")
df.to_parquet(PATHS["parquet+zstd"], index=False, compression="zstd")

base = PATHS["csv"].stat().st_size
print(f"{'قالب':<14}{'کیلوبایت':>10}{'نسبت به csv':>14}")
for name, p in PATHS.items():
    size = p.stat().st_size
    print(f"{name:<14}{size / 1024:>10.1f}{base / size:>14.2f}")
```

```text-approx
قالب            کیلوبایت   نسبت به csv
csv                246.3          1.00
csv.gz              33.9          7.26
jsonl              410.7          0.60
parquet             65.9          3.74
parquet+zstd        45.3          5.44
```

<div dir="rtl">

**سه چیز در این جدول هست و هر سه ارزشِ توضیح دارند.**

**اول، `jsonl` از `csv` بزرگ‌تر است.** چون نامِ هر ستون در **هر ردیف** دوباره نوشته می‌شود. با ۱۲۰۰ ردیف و ده ستون، دوازده هزار بار نامِ ستون‌ها روی دیسک تکرار شده است.

**دوم، `csv.gz` از `parquet` هم کوچک‌تر شد.** فشرده‌سازیِ عمومی روی متنِ تکراری خیلی خوب کار می‌کند و متنِ تیکت‌های ما پر از عبارت‌های تکراری است. **پس «`parquet` همیشه کوچک‌تر است» غلط است** — و اگر فقط دنبالِ حجم باشی، `csv.gz` گزینهٔ کاملاً معقولی است.

**سوم، `zstd` روی همان `parquet` حجم را باز هم کم کرد.** الگوریتمِ فشرده‌سازی یک انتخابِ جداست، نه بخشی از قالب.

> ⚠️ **مواظب باش:** حجمِ `parquet` به نسخهٔ کتابخانه‌ای که آن را می‌نویسد وابسته است، پس عددهای تو با کتاب کمی فرق می‌کنند. **نتیجه‌گیریِ فصل به اختلافِ نسبی تکیه دارد، نه به عددِ مطلق** — و آن اختلاف روی هر نسخه‌ای همین شکلی است.

## ۳. زمانِ خواندن

</div>

```python
import time


def fastest(fn, n=5):
    """کمترین زمان از چند اجرا — کمتر از میانگین تحتِ تأثیرِ نویزِ سیستم است."""
    best = None
    for _ in range(n):
        t0 = time.perf_counter()
        fn()
        dt = time.perf_counter() - t0
        best = dt if best is None else min(best, dt)
    return best


READERS = {
    "csv": lambda: pd.read_csv(PATHS["csv"]),
    "csv.gz": lambda: pd.read_csv(PATHS["csv.gz"]),
    "jsonl": lambda: pd.read_json(PATHS["jsonl"], lines=True),
    "parquet": lambda: pd.read_parquet(PATHS["parquet"]),
}
print(f"{'قالب':<10}{'خواندنِ کلِ جدول':>22}")
for name, fn in READERS.items():
    print(f"{name:<10}{fastest(fn) * 1000:>18.1f} ms")
```

```text-approx
قالب            خواندنِ کلِ جدول
csv                      8.6 ms
csv.gz                   8.9 ms
jsonl                   15.2 ms
parquet                  3.1 ms
```

<div dir="rtl">

**`parquet` حدودِ سه برابر سریع‌تر خوانده شد، و `csv.gz` با اینکه هفت برابر کوچک‌تر است، سریع‌تر از `csv` نبود.**

دلیلش این است که خواندنِ `csv` کارِ سنگینی است: هر عدد به‌صورتِ متن روی دیسک است و باید **تجزیه** شود. باز کردنِ فشرده‌سازی کارِ ارزانی است در مقایسه با همان تجزیه، پس فایلِ کوچک‌ترْ زمانِ کمتری نمی‌آورد. **`parquet` اعداد را به‌شکلِ دودویی نگه می‌دارد و تجزیه‌ای در کار نیست.**

## ۴. ستونی یعنی چه

فرقِ اصلیِ `parquet` این است که داده را **ستون‌به‌ستون** روی دیسک می‌چیند، نه ردیف‌به‌ردیف. حالا فقط یک ستون بخواه.

</div>

```python
def one_col_csv():
    return pd.read_csv(PATHS["csv"], usecols=["escalated"])


def one_col_parquet():
    return pd.read_parquet(PATHS["parquet"], columns=["escalated"])


t_csv = fastest(one_col_csv)
t_pq = fastest(one_col_parquet)
print(f"یک ستون از csv     : {t_csv * 1000:>6.1f} ms")
print(f"یک ستون از parquet : {t_pq * 1000:>6.1f} ms")
print("نسبت               :", round(t_csv / t_pq, 1))
```

```text-approx
یک ستون از csv     :    5.9 ms
یک ستون از parquet :    2.3 ms
نسبت               :    2.6
```

<div dir="rtl">

**`usecols` در `csv` هم کمک کرد — از ۸٫۶ به ۵٫۹ — ولی نتوانست به `parquet` برسد.**

چرا؟ چون در یک فایلِ سطری، مقادیرِ یک ستون **در کلِ فایل پخش‌اند**. برای برداشتنِ ستونِ دهم باید نُه ستونِ دیگر را هم از دیسک بخوانی و رد کنی؛ فقط از تبدیلشان به مقدارِ پایتون فرار کرده‌ای. در فایلِ ستونی، آن ستون یک قطعهٔ پیوسته است و بقیه اصلاً لمس نمی‌شوند.

**روی ۱۲۰۰ ردیف این تفاوت ناچیز است. روی جدولی با صد ستون که فقط سه‌تایش را می‌خواهی، همین تفاوت مرزِ بینِ ثانیه و دقیقه است.**

## ۵. حالا چیزی که `csv` بی‌صدا خراب می‌کند

</div>

```python
back = {
    "csv": pd.read_csv(PATHS["csv"]),
    "jsonl": pd.read_json(PATHS["jsonl"], lines=True),
    "parquet": pd.read_parquet(PATHS["parquet"]),
}


def kind(frame, col):
    return type(frame[col].iloc[0]).__name__


print(f"{'ستون':<16}{'قبل':>12}{'csv':>12}{'jsonl':>12}{'parquet':>12}")
for col in ("branch_code", "created_at", "rating", "escalated"):
    line = f"{col:<16}{kind(df, col):>12}"
    for name in ("csv", "jsonl", "parquet"):
        line += f"{kind(back[name], col):>12}"
    print(line)
print("branch_code ردیفِ اول — خام:", df["branch_code"].iloc[0],
      "· بعد از csv:", back["csv"]["branch_code"].iloc[0])
```

```text
ستون                     قبل         csv       jsonl     parquet
branch_code              str       int64       int64         str
created_at         Timestamp         str   Timestamp   Timestamp
rating                  int8     float64     float64        int8
escalated               int8       int64       int64        int8
branch_code ردیفِ اول — خام: 099 · بعد از csv: 99
```

<div dir="rtl">

**از این چهار ستون، سه‌تا از `csv` سالم بیرون نیامدند، و هیچ‌کدام خطا ندادند.** `escalated` فقط عرضِ نوعش عوض شد و مقدارش همان ماند. این چهارتا نمونه‌اند: بقیهٔ ستون‌های جدول را اینجا نسنجیده‌ایم.

- **`branch_code`** رشته بود و عدد برگشت. **کدِ شعبهٔ `099` شد `99`** و صفرِ ابتدایی برای همیشه رفت. اگر این کد را با جدولِ دیگری `join` کنی، هیچ ردیفی نمی‌خورد و ساعت‌ها دنبالِ باگ می‌گردی.
- **`created_at`** زمان بود و رشته برگشت. تا وقتی `to_datetime` را دوباره صدا نزنی، مرتب‌سازی‌ات **الفبایی** است نه زمانی.
- **`rating`** عددِ صحیحِ خالی‌پذیر بود و اعشاری برگشت، چون `csv` جای «خالی» فقط رشتهٔ خالی دارد و `pandas` برای نگه‌داشتنِ آن مجبور است به `float` برود.

**علتِ ریشه‌ای یکی است: `csv` تایپ ندارد.** هر چیزی که در آن می‌نویسی متن است، و هر بار که می‌خوانی، یک نفر باید حدس بزند. اینجا آن یک نفرْ `pandas` است و حدسش معقول ولی غلط است.

**`parquet` هر چهار ستون را دست‌نخورده پس داد**، چون تایپ را کنارِ داده نگه می‌دارد. `jsonl` وسطِ این دو ایستاد: زمان را نگه داشت (چون به‌شکلِ متنِ استاندارد نوشته شد) ولی `099` را باز هم عدد خواند.

> ✅ **چک کن:** ستونِ `created_at` را در فایلِ `t.csv` با یک ویرایشگر باز کن. مقدارها آنجا هستند و کاملاً خوانا. **مسئله این نیست که داده گم شده؛ مسئله این است که «این ستون زمان است» گم شده.** فرقِ داده و فراداده دقیقاً همین‌جاست.

## ۶. و چیزی که `parquet` قبول نمی‌کند

`parquet` سخت‌گیر است: هر ستون یک تایپ دارد و تمام. حالا عمداً ستونی می‌سازیم که نصفه تمیز شده — بعضی خانه‌هایش عدد است و بعضی متن.

</div>

```python
half_clean = df.copy()
half_clean["rating_raw"] = [int(v) if pd.notna(v) else "نامشخص" for v in df["rating"]]
try:
    half_clean.to_parquet(FMT / "broken.parquet", index=False)
except Exception as e:
    print(type(e).__name__)
    print(str(e).split("\n")[0][1:69])
```

```text
ArrowInvalid
"Could not convert 'نامشخص' with type str: tried to convert to int64
```

<div dir="rtl">

> 🔧 **اگر کار نکرد:** این خطا **درست است و باید بیفتد.** `parquet` دارد می‌گوید ستونت دو تایپ دارد و او فقط یکی را می‌تواند بنویسد. راهِ حل، آرام کردنِ `parquet` نیست؛ **تصمیم گرفتن دربارهٔ ستون است**: یا «نامشخص» را به «مقدار ندارد» تبدیل کن و ستون را `Int8` بگذار، یا کلِ ستون را رشته کن و بپذیر که دیگر عدد نیست. **همین سخت‌گیری بزرگ‌ترین مزیتِ `parquet` است**: ستونِ دوتایپه در `csv` بی‌صدا ذخیره می‌شود و سه مرحله بعد به‌شکلِ یک خطای عجیب بیرون می‌زند.

## ۷. پس چرا هنوز `jsonl` لازم داری

</div>

```python
row = df.iloc[[0]]
before_j = PATHS["jsonl"].stat().st_size
with open(PATHS["jsonl"], "a", encoding="utf-8") as fh:
    fh.write(row.to_json(orient="records", lines=True,
                         force_ascii=False, date_format="iso"))
after_j = PATHS["jsonl"].stat().st_size

pd.concat([df, row], ignore_index=True).to_parquet(PATHS["parquet"], index=False)
after_p = PATHS["parquet"].stat().st_size

print("یک ردیف به jsonl   : نوشتنِ", after_j - before_j, "بایت")
print("یک ردیف به parquet : بازنویسیِ", after_p, "بایت")
print("نسبت               :", round(after_p / (after_j - before_j)))
```

```text-approx
یک ردیف به jsonl   : نوشتنِ 290 بایت
یک ردیف به parquet : بازنویسیِ 67530 بایت
نسبت               : 233
```

<div dir="rtl">

**برای افزودنِ یک ردیف، `jsonl` ۲۹۰ بایت نوشت و `parquet` کلِ فایل را از نو ساخت.**

`parquet` ستونی است، پس هر ردیفِ تازه به **همهٔ** قطعه‌های ستونی دست می‌زند. عملاً «افزودن» ندارد؛ فقط «نوشتنِ دوباره» دارد. `jsonl` در عوض یک خط است پشتِ خطِ قبلی، و همین‌طور هم خوانده می‌شود — خط‌به‌خط، بدونِ اینکه لازم باشد کلِ فایل در حافظه جا شود.

**پس این‌ها رقیبِ هم نیستند؛ برای دو جای مسیرند.** `jsonl` قالبِ **ورودِ داده** است: چیزی که همین الان می‌رسد. `parquet` قالبِ **دادهٔ تثبیت‌شده** است: چیزی که بارها خوانده می‌شود و کم عوض می‌شود. **الگوی رایج همین است: با `jsonl` جمع کن، دوره‌ای به `parquet` تبدیل کن.**

> 📏 **اندازه بگیر:** **با چه چیزی مقایسه شد؟** پنج قالب روی **یک** جدولِ کاملاً یکسان — بدونِ این، مقایسهٔ حجم بی‌معنا بود. **روی کدام داده؟** همان ۱۲۰۰ ردیفِ ترم، که متنِ فارسیِ تکراری دارد؛ روی دادهٔ عددیِ محض نسبت‌ها فرق می‌کنند. **با چند `seed`؟** زمان‌ها **بهترین از پنج اجرا**اند نه یک اجرا، چون یک اندازه‌گیریِ تکیِ زمان تقریباً همیشه نویز است.

## ۸. انتخاب

</div>

| قالب | کِی | چه چیزی را از دست می‌دهی |
|---|---|---|
| `csv` | تبادل با آدم‌ها و ابزارهایی که فقط همین را می‌خوانند | تایپ، به‌کل |
| `csv.gz` | آرشیوِ ارزان وقتی خواندنش نادر است | تایپ، و امکانِ خواندنِ تکه‌ای |
| `jsonl` | دادهٔ در حالِ ورود، سیاهه، رویداد | ستونی نیست؛ حجمِ زیاد |
| `parquet` | دادهٔ تثبیت‌شده‌ای که بارها خوانده می‌شود | افزودنِ ارزان؛ خوانا نبودن با چشم |
| `sqlite` | وقتی به پرس‌وجو و شرط و `join` نیاز داری | یک فایلِ واحد با قفل، برای موازی‌سازیِ سنگین مناسب نیست |

<div dir="rtl">

**و یک قاعدهٔ ساده که بیشترِ تصمیم‌ها را می‌گیرد: هر جا داده از مسیرِ تو خارج می‌شود و به دستِ آدم می‌رسد، `csv`؛ هر جا داده داخلِ مسیرِ تو از مرحله‌ای به مرحله‌ای می‌رود، `parquet`.**

> 🤖 **از دستیارت بپرس:** «در `parquet` مفهومِ `row group` چیست و چطور باعث می‌شود بشود بخشی از فایل را بدونِ خواندنِ کلِ آن فیلتر کرد؟» بعد این را هم بپرس: **«اگر جدولِ من ۱۰ گیگابایت باشد و فقط ردیف‌های یک ماهِ خاص را بخواهم، `partition` چه کمکی می‌کند و چه هزینه‌ای دارد؟»** — جوابش توضیح می‌دهد چرا مسیرهای دادهٔ بزرگ فایل‌ها را در پوشه‌هایی به نامِ تاریخ می‌چینند.

## واژه‌های تازهٔ این فصل

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| row-oriented | رو-اورینتد | چیدنِ داده ردیف‌به‌ردیف روی دیسک |
| column-oriented | کالمن-اورینتد | چیدنِ داده ستون‌به‌ستون روی دیسک |
| parquet | پارکِت | قالبِ ستونیِ دودویی با تایپِ ذخیره‌شده |
| jsonl | جیسون-اِل | هر خط یک شیءِ JSON کامل |
| schema | اسکیما | تعریفِ ستون‌ها و تایپشان، جدا از خودِ داده |
| nullable type | نال‌اِیبل تایپ | تایپی که «مقدار ندارد» را هم نگه می‌دارد |
| round-trip | راند-تریپ | نوشتن و دوباره خواندن، برای دیدنِ اینکه چه چیزی گم می‌شود |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا `csv.gz` با اینکه هفت برابر کوچک‌تر است، سریع‌تر خوانده نشد؟

**تمرینِ اجباری:** ستونِ `text` را از جدول حذف کن و هر پنج فایل را دوباره بساز. **نسبت‌های حجم چطور عوض می‌شوند و چرا؟** بعد همین را برعکس کن: جدولی بساز که **فقط** `ticket_id` و `text` را دارد. **جوابت باید این جمله را توضیح بدهد: برتریِ `parquet` در حجم به جنسِ ستون‌ها وابسته است، نه به تعدادِ ردیف‌ها.**

**تمرینِ ستاره‌دار ⭐:** یک آزمونِ `round-trip` بنویس که برای هر قالب چک کند جدولِ برگشته با جدولِ اصلی **یکی** است — هم مقدارها و هم تایپِ هر ستون. بعد آن را روی هر سه قالب اجرا کن و **نتیجه را به‌شکلِ یک جدولِ صادقانه گزارش کن: چند ستون سالم برگشت، چند ستون خراب.** بعد سؤالِ سخت: **اگر مجبور باشی `csv` استفاده کنی، چطور می‌شود تایپ‌ها را کنارش نگه داشت؟** (راهنمایی: یک فایلِ دوم لازم داری — و همان فایلِ دوم موضوعِ فصلِ بعد است.)

## در فصل بعد

تا اینجا فرض کردیم داده «همان چیزی است که انتظار داریم». نیست. فصلِ بعد یک اسکیمای واقعی می‌نویسد — انتظار از هر ستون، بازه، یکتایی — و آن را روی همین ۱۲۰۰ ردیف اجرا می‌کند. **تعدادِ تخلف‌هایی که پیدا می‌شود از چیزی که حدس می‌زنی بیشتر است**، و مهم‌تر از عددش این است که یاد بگیری کدامشان باید مسیر را متوقف کند و کدام فقط باید ثبت شود.

</div>

---
Source: https://yaadestan.com/courses/darbast/lessons/t2/s02-storage-formats (یادستان, Yaadestan)
