# فصل ۰۴ — نسخه‌بندیِ داده

<div dir="rtl">

# فصل ۰۴ — نسخه‌بندیِ داده

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

ده خانه از ۱۲۴۰۰ خانهٔ جدول را عوض می‌کنیم — کمتر از یک‌دهمِ درصد. **انبارِ نسخه‌ها ۲٫۵ مگابایت بزرگ می‌شود: ۲۵۴ کیلوبایت برای هر خانه.**

همین یک عدد جوابِ سؤالی است که همه می‌پرسند: **چرا `git` را روی دادهٔ بزرگ نمی‌اندازیم.** بعد فهرستی می‌سازیم که همین ده نسخه را با ۱۶ کیلوبایت اداره می‌کند، و در آخر یک فایلِ دستکاری‌شده را **با اسمش** لو می‌دهیم.

![یک قفسهٔ بایگانی که هر جعبه‌اش با شکلِ محتوایش برچسب خورده](/lesson-assets/t2-s04-versioning-data/prompt/01-image-content-addressed-shelf.png)

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

- بینِ «اثرِ انگشتِ فایل» و «اثرِ انگشتِ محتوا» فرق بگذاری و بدانی کدام را کجا لازم داری
- انبارِ محتوا-نشانی بسازی که خودش تکراری‌ها را حذف می‌کند
- پنج دستورِ پایهٔ SQL را بخوانی و بنویسی: جدول، ستون، `INSERT`، `SELECT ... WHERE`، `UNIQUE`
- فهرستِ نسخه با `sqlite3` بنویسی که ثبتِ دوباره را نمی‌پذیرد
- بگویی هر مدل با کدام نسخه از داده ساخته شده — و ثابتش کنی

## قبل از شروع

**از فصل ۱:** `sha256` و اینکه راه‌انداز کهنگی را از محتوا می‌فهمد. اینجا همان ایده را از «چه چیزی دوباره اجرا شود» به «کدام داده بود» می‌بریم.

**از فصل ۳:** اسکیما یک فایل است. اثرِ انگشتی که اینجا می‌سازیم روی آن فایل هم کار می‌کند.

> 💡 **نکته:** `sqlite3` بخشی از خودِ پایتون است و به نصب نیاز ندارد. کلِ فهرستِ نسخه‌های ما یک فایل است که می‌شود کپی‌اش کرد یا در `git` گذاشتش.

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

</div>

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

<div dir="rtl">

## ۱. دو اثرِ انگشت، دو سؤالِ متفاوت

</div>

```python
import csv
import hashlib

RAW = WORK / "raw" / "tickets.csv"
VER = WORK / "versions"
STORE = VER / "store"
STORE.mkdir(parents=True, exist_ok=True)

with open(RAW, encoding="utf-8") as fh:
    reader = csv.DictReader(fh)
    FIELDS = reader.fieldnames
    rows = list(reader)


def write_csv(path, rows, fields=None):
    with open(path, "w", encoding="utf-8", newline="") as fh:
        w = csv.DictWriter(fh, fieldnames=fields or FIELDS)
        w.writeheader()
        w.writerows(rows)


def fingerprint_bytes(path):
    """اثرِ انگشتِ فایل: هر بایتی که عوض شود، عوض می‌شود."""
    h = hashlib.sha256()
    with open(path, "rb") as fh:
        for block in iter(lambda: fh.read(1 << 16), b""):
            h.update(block)
    return h.hexdigest()[:12]


def fingerprint_rows(rows, fields=None):
    """اثرِ انگشتِ محتوا: به ترتیبِ ردیف‌ها و به ترتیبِ ستون‌ها بی‌اعتناست."""
    lines = sorted(repr([r[k] for k in sorted(fields or FIELDS)]) for r in rows)
    return hashlib.sha256("\n".join(lines).encode("utf-8")).hexdigest()[:12]


a = VER / "a.csv"
b = VER / "b.csv"
write_csv(a, rows)
write_csv(b, list(reversed(rows)))          # همان داده، ترتیبِ برعکس
print("فایلِ اول  :", fingerprint_bytes(a), "· محتوا:", fingerprint_rows(rows))
print("فایلِ برعکس:", fingerprint_bytes(b), "· محتوا:", fingerprint_rows(list(reversed(rows))))
```

```text
فایلِ اول  : fa917db4b366 · محتوا: d971fc13a343
فایلِ برعکس: 58f0434e067d · محتوا: d971fc13a343
```

<div dir="rtl">

**دو فایلِ کاملاً متفاوت روی دیسک، با محتوای کاملاً یکسان.**

اثرِ انگشتِ فایل عوض شد چون بایت‌ها جابه‌جا شده‌اند. اثرِ انگشتِ محتوا عوض نشد چون **مجموعهٔ ردیف‌ها همان است**، و ما قبل از `hash` گرفتن ردیف‌ها را مرتب کردیم و مقدارهای هر ردیف را همیشه با یک ترتیبِ ثابتِ ستونی کنارِ هم چیدیم.

**هر دو لازم‌اند و هیچ‌کدام جای دیگری را نمی‌گیرد:**

- **اثرِ انگشتِ فایل** به سؤالِ «آیا این دقیقاً همان فایل است؟» جواب می‌دهد — برای تشخیصِ خرابی در انتقال و ذخیره‌سازی.
- **اثرِ انگشتِ محتوا** به سؤالِ «آیا این همان داده است؟» جواب می‌دهد — برای اینکه یک `sort` یا یک `export` با ترتیبِ ستونِ متفاوت، ده نسخهٔ تقلبی نسازد.

**در نسخه‌بندیِ داده، دومی است که کار می‌کند.** اگر با اولی نسخه بدهی، هر بار که کسی همان جدول را با یک ابزارِ دیگر بیرون بدهد، یک «نسخهٔ جدید» می‌بینی که هیچ چیزِ جدیدی ندارد.

> ⚠️ **مواظب باش:** `fingerprint_rows` ما مرتب می‌کند، پس اگر **خودِ ترتیبِ ردیف‌ها** بخشی از داده باشد — مثلِ یک سیاههٔ رویداد — این تابع دو دادهٔ واقعاً متفاوت را یکی می‌بیند. **هر اثرِ انگشتی یک تعریف از «یکسان بودن» است، و آن تعریف را تو انتخاب می‌کنی.**

## ۲. انبارِ محتوا-نشانی و فهرستِ نسخه‌ها

ایده در یک جمله: **اسمِ فایل، اثرِ انگشتِ محتوایش باشد.** آن‌وقت دو دادهٔ یکسان به‌طورِ خودکار یک فایل می‌شوند و هیچ نسخه‌ای هیچ نسخه‌ای را بازنویسی نمی‌کند.

**فهرستِ نسخه‌ها را در `sqlite3` می‌نویسیم، و از اینجا به بعدِ دوره SQL کم‌کم برمی‌گردد.** پس اول پنج چیزی که این فصل لازم دارد، روی یک جدولِ دوردیفیِ اسباب‌بازی — **هیچ‌کدام از دوره‌های قبلی SQL تدریس نکرده‌اند، پس این‌ها را فرض نمی‌گیریم.**

</div>

| این را ببینی | یعنی |
|---|---|
| `CREATE TABLE files (name TEXT, n_rows INTEGER)` | یک **جدول** بساز به نامِ `files` با دو **ستون**؛ هر ستون یک نوع دارد |
| `NOT NULL` | این ستون حق ندارد خالی بماند |
| `UNIQUE` | هیچ دو ردیفی حق ندارند در این ستون مقدارِ یکسان داشته باشند |
| `INSERT INTO files VALUES (?, ?)` | یک **ردیف** اضافه کن؛ هر `?` جای یک مقدار است که جدا فرستاده می‌شود |
| `SELECT name FROM files WHERE n_rows > 100` | ستونِ `name` را از ردیف‌هایی بده که شرطِ `WHERE` را دارند |

```python
import sqlite3

demo = sqlite3.connect(":memory:")                    # پایگاه دادهٔ موقت، فقط در حافظه
demo.execute("CREATE TABLE files (name TEXT NOT NULL UNIQUE, n_rows INTEGER)")
demo.execute("INSERT INTO files VALUES (?, ?)", ("tickets.csv", 1240))
demo.execute("INSERT INTO files VALUES (?, ?)", ("labels.csv", 90))
print("همهٔ ردیف‌ها:", demo.execute("SELECT name, n_rows FROM files").fetchall())
print("فقط بزرگ‌ها:", demo.execute(
    "SELECT name FROM files WHERE n_rows > 100").fetchall())
try:
    demo.execute("INSERT INTO files VALUES (?, ?)", ("tickets.csv", 7))
except sqlite3.IntegrityError as error:
    print("sqlite3.IntegrityError:", error)
```

```text
همهٔ ردیف‌ها: [('tickets.csv', 1240), ('labels.csv', 90)]
فقط بزرگ‌ها: [('tickets.csv',)]
sqlite3.IntegrityError: UNIQUE constraint failed: files.name
```

<div dir="rtl">

**سه نکته که همین‌جا باید بدانی و بعداً تکرار نمی‌شوند:**

- **`SELECT` همیشه فهرستی از چندتایی برمی‌گرداند** — حتی وقتی یک ستون خواسته‌ای، جواب `('tickets.csv',)` است نه `'tickets.csv'`.
- **`?` را هرگز با چسباندنِ رشته جایگزین نکن.** اگر مقدار را داخلِ خودِ متنِ SQL بنویسی، یک نقلِ قول در داده کلِ دستور را عوض می‌کند. `?` مقدار را **جدا از دستور** می‌فرستد.
- **`UNIQUE` را خودِ پایگاه داده اجرا می‌کند، نه کدِ تو.** خطِ آخر همین را نشان داد: ثبتِ دوباره یک `exception` شد، نه یک ردیفِ اضافه. **بخشِ بعد کلِ درسش همین یک کلمه است.**

حالا جدولِ واقعیِ فصل — همان پنج چیز، با ستون‌های بیشتر:

</div>

```python
DB = VER / "registry.db"
if DB.exists():
    DB.unlink()
db = sqlite3.connect(DB)
db.executescript("""
CREATE TABLE versions (
  version_id  INTEGER PRIMARY KEY AUTOINCREMENT,
  fingerprint TEXT NOT NULL UNIQUE,
  path        TEXT NOT NULL,
  n_rows      INTEGER NOT NULL,
  n_bytes     INTEGER NOT NULL,
  note        TEXT NOT NULL,
  parent      TEXT,
  created_at  TEXT NOT NULL
);
""")

TICK = [0]
def now():
    """ساعتِ مجازی: بازتولیدپذیری با ساعتِ واقعی نمی‌سازد."""
    TICK[0] += 1
    return f"2031-06-0{TICK[0] // 24 + 1}T{TICK[0] % 24:02d}:00:00"


def put(rows, note, parent=None, fields=None):
    """ذخیرهٔ یک نسخه در انبارِ محتوا-نشانی و ثبتش در فهرست."""
    fp = fingerprint_rows(rows, fields)
    dest = STORE / f"{fp}.csv"
    if not dest.exists():                       # تغییرناپذیری: فایلِ موجود بازنویسی نمی‌شود
        write_csv(dest, rows, fields)
    db.execute("INSERT INTO versions (fingerprint, path, n_rows, n_bytes, note,"
               " parent, created_at) VALUES (?,?,?,?,?,?,?)",
               (fp, dest.name, len(rows), dest.stat().st_size, note, parent, now()))
    db.commit()
    return fp


v1 = put(rows, "خامِ اولیه")
print("نسخهٔ ۱:", v1, "·", (STORE / f"{v1}.csv").stat().st_size, "بایت")
```

```text
نسخهٔ ۱: d971fc13a343 · 260608 بایت
```

<div dir="rtl">

**به `UNIQUE` در تعریفِ جدول دقت کن؛ کلِ بحثِ بخشِ بعد همان یک کلمه است.**

و به آن تابعِ `now` هم دقت کن. اگر `datetime.now()` بگذاری، هر اجرای نوت‌بوک یک فهرستِ متفاوت می‌سازد و **دیگر نمی‌توانی دو اجرا را مقایسه کنی**. در کارِ واقعی البته زمانِ واقعی می‌خواهی — ولی آن ستون هرگز نباید داخلِ چیزی برود که با آن یکسانی را می‌سنجی.

**اسمِ این ترفند «ساعتِ مجازی» است و فعلاً همین‌قدر بدان: به‌جای خواندنِ زمان از سیستم، خودت یک شمارنده نگه می‌داری و جلو می‌بری.** ترمِ ۴ فصلِ ۴ آن را کامل می‌سازد و از آنجا به بعد ابزارِ ثابتِ دوره می‌شود — هر جا مهلت، عمرِ `cache`، یا پنجرهٔ زمانی در کار باشد.

## ۳. و حالا همان داده را دوباره ثبت کن

</div>

```python
try:
    put(rows, "همان داده، دوباره")
except sqlite3.IntegrityError as e:
    print("sqlite3.IntegrityError:", e)
```

```text
sqlite3.IntegrityError: UNIQUE constraint failed: versions.fingerprint
```

<div dir="rtl">

> 🔧 **اگر کار نکرد:** این خطا **دقیقاً همان چیزی است که خواستیم**: پایگاه داده جلوی ثبتِ دوبارهٔ یک داده را گرفت. ولی به‌شکلِ فعلی‌اش کدِ فراخوان را می‌شکند، و بدتر از آن، **`put` اول فایل را می‌نویسد و بعد ثبت می‌کند.** اینجا چیزی گم نشد چون همان نسخه از قبل در فهرست است، ولی اگر ثبت به هر دلیلِ دیگری بیفتد، فایلی بی‌ثبت در انبار می‌ماند. **قاعده: قیدِ پایگاه داده آخرین خطِ دفاع است، نه منطقِ برنامه.** اگر خواستی خودت هم `UNIQUE` را ببینی، `CREATE TABLE` را عوض کن و اجرا کن؛ آن‌وقت نسخه‌های تکراری بی‌صدا در فهرست جمع می‌شوند و همان‌جاست که فهرست بی‌ارزش می‌شود.

## ۴. تکراری، یک خطا نیست

</div>

```python
def register(rows, note, parent=None, fields=None):
    """نسخهٔ دوم: نسخهٔ تکراری خطا نیست، فقط تازه هم نیست."""
    fp = fingerprint_rows(rows, fields)
    seen = db.execute("SELECT version_id FROM versions WHERE fingerprint=?",
                      (fp,)).fetchone()
    if seen:
        return fp, False
    put(rows, note, parent, fields)
    return fp, True


print(register(rows, "همان داده، دوباره")[1], "→ چیزی اضافه نشد")
tweaked = [dict(r) for r in rows]
tweaked[0]["rating"] = "3" if tweaked[0]["rating"] != "3" else "4"
fp2, added = register(tweaked, "یک خانه عوض شد", parent=v1)
print(added, "→", fp2)
```

```text
False → چیزی اضافه نشد
True → b06218c7615c
```

<div dir="rtl">

**یک خانه عوض شد و اثرِ انگشت کاملاً عوض شد.**

این ویژگیِ `hash` است، نه عیبش: **هیچ رابطه‌ای بینِ «چقدر داده عوض شده» و «چقدر اثرِ انگشت عوض شده» وجود ندارد.** پس نمی‌شود از روی دو اثرِ انگشت فهمید چقدر شبیه‌اند — فقط می‌شود فهمید یکی‌اند یا نه. **و برای نسخه‌بندی همین کافی است.**

> ✅ **چک کن:** `register` هیچ‌وقت به داده دست نمی‌زند و هیچ‌وقت فایلی را بازنویسی نمی‌کند. اگر می‌خواهی مطمئن شوی، بعد از هر ثبت `len(list(STORE.iterdir()))` را بشمار: **فقط وقتی زیاد می‌شود که داده واقعاً تازه باشد.**

## ۵. حالا هزینه‌اش را بشمار

</div>

```python
def dir_size(path):
    return sum(p.stat().st_size for p in path.iterdir())


start_files = len(list(STORE.iterdir()))
start_bytes = dir_size(STORE)
parent = fp2
current = tweaked
for i in range(10):
    current = [dict(r) for r in current]
    current[i + 1]["handling_minutes"] = str(int(current[i + 1]["handling_minutes"]) + 1)
    parent, _ = register(current, f"اصلاحِ دستیِ ردیفِ {i + 2}", parent=parent)

print("فایل‌های انبار :", start_files, "→", len(list(STORE.iterdir())))
print("حجمِ انبار     :", f"{start_bytes / 1024:.0f}", "→",
      f"{dir_size(STORE) / 1024:.0f}", "کیلوبایت")
print("تغییرِ واقعی   : 10 خانه از", len(rows) * len(FIELDS))
print("هزینهٔ هر تغییر:", f"{(dir_size(STORE) - start_bytes) / 10 / 1024:.0f}", "کیلوبایت")
print("حجمِ فهرست     :", f"{DB.stat().st_size / 1024:.0f}", "کیلوبایت")
```

```text
فایل‌های انبار : 2 → 12
حجمِ انبار     : 509 → 3054 کیلوبایت
تغییرِ واقعی   : 10 خانه از 12400
هزینهٔ هر تغییر: 254 کیلوبایت
حجمِ فهرست     : 16 کیلوبایت
```

<div dir="rtl">

**۲۵۴ کیلوبایت برای عوض کردنِ یک خانه. نسبتِ هزینه به تغییر حدودِ صد هزار برابر است.**

و **دقیقاً همین اتفاق در `git` می‌افتد.** هر `commit` روی یک فایلِ متنی، **کلِ فایل را** به‌شکلِ یک شیءِ تازه ذخیره می‌کند، نه فقط خط‌های عوض‌شده را. (`git` بعداً می‌تواند اشیای شبیهِ هم را فشرده کند، ولی **شرطش دقیق است**: این کار فقط هنگامِ `git gc` یا `git push` انجام می‌شود، و فقط بینِ اشیایی که در **یک بستهٔ واحد** بیفتند — پس دو نسخه‌ای که یکی امروز و یکی سه ماهِ بعد `commit` شده‌اند، ممکن است هیچ‌وقت کنارِ هم فشرده نشوند.) روی کدِ منبع این ارزان است: فایل‌ها کوچک‌اند و تغییرها زیاد. **روی دادهٔ چندگیگابایتی همان طراحی یعنی هر `clone` باید کلِ تاریخچه را بیاورد.**

**پس قاعده این است: داده در انبار می‌ماند و در `git` فقط اشاره‌گرش می‌رود.** فهرستِ ما ۱۶ کیلوبایت است و همان چیزی است که کنارِ کد نگه می‌داری. ابزارهایی مثلِ DVC و LakeFS و Git-LFS دقیقاً همین کار را می‌کنند، فقط با انبارِ بزرگ‌تر و همگام‌سازیِ آماده.

> 📏 **اندازه بگیر:** **با چه چیزی مقایسه شد؟** حجمِ انبار در برابرِ حجمِ تغییرِ واقعی — و در برابرِ حجمِ فهرست، که همان چیزی است که در `git` می‌گذاری. **روی کدام داده؟** همان جدولِ ۲۵۵ کیلوبایتی؛ روی جدولِ بزرگ‌تر نسبت بدتر می‌شود، نه بهتر. **با چند `seed`؟** هیچ تصادفی در کار نیست؛ عددها با اجرای دوباره **دقیقاً** همین‌اند، و همین آزمونِ سلامتِ کلِ این فصل است.

## ۶. تغییرناپذیری، و فایلی که دستکاری شده

</div>

```python
victim = STORE / f"{v1}.csv"
tampered = victim.read_text(encoding="utf-8").replace("TK-01155", "TK-99999", 1)
victim.write_text(tampered, encoding="utf-8", newline="")
with open(victim, encoding="utf-8") as fh:
    again = list(csv.DictReader(fh))
print("نامِ فایل روی دیسک :", victim.name[:12])
print("اثرِ انگشتِ محتوایش:", fingerprint_rows(again))
print("سالم است؟", victim.name[:12] == fingerprint_rows(again))
write_csv(victim, rows)                      # انبار را به حالتِ سالمش برگردان
print("بعد از بازگرداندن:", victim.name[:12] == fingerprint_bytes(victim) or
      victim.name[:12] == fingerprint_rows(rows))
```

```text
نامِ فایل روی دیسک : d971fc13a343
اثرِ انگشتِ محتوایش: 55a8a7143c29
سالم است؟ False
بعد از بازگرداندن: True
```

<div dir="rtl">

**یک شناسه را عوض کردیم و انبار خودش لو داد.**

این مزیتِ رایگانِ محتوا-نشانی است: **اسمِ فایل یک ادعا دربارهٔ محتوایش است**، پس هر لحظه می‌شود ادعا را سنجید. یک حلقهٔ ساده روی کلِ انبار، هر فایلِ خراب یا دستکاری‌شده را پیدا می‌کند — بدونِ اینکه لازم باشد جایی نسخهٔ دومی نگه داری.

**و «تغییرناپذیری» یعنی همین:** نسخه‌ای که ثبت شد، دیگر عوض نمی‌شود. اگر داده اصلاح شد، **نسخهٔ تازه** ثبت می‌شود. این تنها راهی است که نتیجهٔ سه ماهِ پیش قابلِ بازتولید بماند.

## ۷. تبار: این نسخه از کجا آمد

</div>

```python
def lineage(fp):
    chain = []
    while fp:
        row = db.execute("SELECT fingerprint, note, parent, n_rows FROM versions"
                         " WHERE fingerprint=?", (fp,)).fetchone()
        if not row:
            break
        chain.append(row)
        fp = row[2]
    return chain


chain = lineage(parent)
print("طولِ زنجیره:", len(chain), "نسخه")
for fp, note, _p, n in chain[:2]:
    print(f"  {fp}  {n:>5} ردیف   {note}")
print(f"  {'…':<14}{len(chain) - 3:>5} نسخهٔ میانی")
fp, note, _p, n = chain[-1]
print(f"  {fp}  {n:>5} ردیف   {note}")
```

```text
طولِ زنجیره: 12 نسخه
  54867518536e   1240 ردیف   اصلاحِ دستیِ ردیفِ 11
  f3d0a0d16660   1240 ردیف   اصلاحِ دستیِ ردیفِ 10
  …                 9 نسخهٔ میانی
  d971fc13a343   1240 ردیف   خامِ اولیه
```

<div dir="rtl">

ستونِ `parent` همان چیزی است که یک فهرستِ ساده را به یک **تبار** تبدیل می‌کند. حالا از هر نسخه‌ای می‌شود تا خامِ اولیه عقب رفت و دید در راه چه شده.

**و توجه کن که این با سیاههٔ منشأِ فصلِ ۱ یکی نیست و مکملش است.** آن سیاهه می‌گوید **کدام مرحله** داده را ساخت؛ این تبار می‌گوید **کدام داده** بود. سؤالِ «این عدد از کجا آمد؟» به هر دو نیاز دارد.

## ۸. و آخرین حلقه: مدل به داده

</div>

```python
KEYS = ["شکایت", "پاسخگو", "سومین بار", "پیگیری کردم"]


def guess(text):
    t = text.replace("ي", "ی").replace("ك", "ک").replace("‌", " ")
    t = " ".join(t.split())
    return int(any(k in t for k in KEYS))


def score(rows):
    right = sum(guess(r["text"]) == int(r["escalated"]) for r in rows)
    caught = sum(guess(r["text"]) and int(r["escalated"]) for r in rows)
    real = sum(int(r["escalated"]) for r in rows)
    return right / len(rows), caught / real


CLEAN = [r for r in {tuple(r.values()): r for r in rows}.values()
         if r["text"].strip() and 0 <= int(r["handling_minutes"]) <= 1440
         and "2031-01-01" <= r["created_at"] <= "2031-12-31"]
fp_clean, _ = register(CLEAN, "پس از اعتبارسنجیِ فصل ۳", parent=v1)

db.execute("CREATE TABLE models (name TEXT PRIMARY KEY, data_fp TEXT NOT NULL,"
           " accuracy REAL NOT NULL, recall REAL NOT NULL)")
for name, fp_used, data in (("keyword-v1", v1, rows), ("keyword-v2", fp_clean, CLEAN)):
    acc, rec = score(data)
    db.execute("INSERT INTO models VALUES (?,?,?,?)", (name, fp_used, acc, rec))
db.commit()

for name, data_fp, acc, rec in db.execute("SELECT * FROM models"):
    note, n = db.execute("SELECT note, n_rows FROM versions WHERE fingerprint=?",
                         (data_fp,)).fetchone()
    print(f"  {name:<11} داده={data_fp} {n:>5} ردیف  دقت={acc:.4f} "
          f"بازیافت={rec:.4f}  «{note}»")
```

```text
  keyword-v1  داده=d971fc13a343  1240 ردیف  دقت=0.8685 بازیافت=0.4609  «خامِ اولیه»
  keyword-v2  داده=5c59a32bc917  1160 ردیف  دقت=0.8672 بازیافت=0.4673  «پس از اعتبارسنجیِ فصل ۳»
```

<div dir="rtl">

**دقت ۰٫۰۰۱ پایین آمد و بازیافت ۰٫۰۰۶ بالا. و صادقانه: این دو عدد هیچ چیزی دربارهٔ بهتر شدن نمی‌گویند.**

نه فقط چون اختلاف کوچک است — چون **دو مدل روی دو مجموعهٔ متفاوت سنجیده شده‌اند.** یکی روی ۱۲۴۰ ردیف و دیگری روی ۱۱۶۰ ردیف. مقایسه‌شان از پایه بی‌معناست، و اگر ستونِ `داده` در این جدول نبود، **هیچ‌کس این را نمی‌فهمید.**

**و همین کلِ حرفِ این فصل است.** فهرستِ نسخه به‌ت نمی‌گوید کدام مدل بهتر است؛ به‌ت می‌گوید **چه چیزی را با چه چیزی مقایسه کرده‌ای** — و بدونِ آن، هر مقایسه‌ای یک حدس است. ترمِ ۳ کاملاً روی همین ساخته می‌شود.

> 🤖 **از دستیارت بپرس:** «تفاوتِ ذخیره‌سازیِ محتوا-نشانی با ذخیره‌سازیِ مبتنی بر مسیر چیست و چرا اولی به `cache` و همتاسازی بهتر جواب می‌دهد؟» بعد این را هم بپرس: **«اگر داده‌ام روزی ده گیگابایت رشد کند، نگه‌داشتنِ هر نسخه به‌شکلِ کامل چه زمانی از صرفه می‌افتد و جایگزینش چیست؟»** — و جوابش را با عددهای همین فصل بسنج، نه با کلی‌گویی.

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| fingerprint | فینگرپرینت | رشتهٔ کوتاهی که از محتوا ساخته می‌شود و یکتاست |
| content-addressed storage | کانتنت-اَدرسد استوریج | انباری که اسمِ هر فایل، اثرِ انگشتِ محتوایش است |
| immutability | ایمیوتبیلیتی | چیزی که ثبت شد دیگر عوض نمی‌شود؛ اصلاح یعنی نسخهٔ تازه |
| registry | رجیستری | فهرستِ نسخه‌ها با فرادادهٔ هرکدام |
| lineage | لینیج | زنجیرهٔ «این نسخه از کدام نسخه آمد» |
| pointer file | پوینتر فایل | فایلِ کوچکی که به‌جای داده، اثرِ انگشتش را نگه می‌دارد |
| tamper detection | تمپر دیتکشن | فهمیدنِ اینکه محتوای ذخیره‌شده دستکاری شده |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا اثرِ انگشتِ فایل برای نسخه‌بندیِ داده انتخابِ بدی است؟

**تمرینِ اجباری:** تابعی به نامِ `verify_store()` بنویس که کلِ انبار را بگردد و برای هر فایل چک کند اثرِ انگشتِ محتوایش با اسمش می‌خواند. **آن را روی انبارِ سالم اجرا کن، بعد یک فایل را دستکاری کن و دوباره اجرا کن.** بعد یک سؤالِ سخت‌تر: اگر انبار ده هزار فایل داشته باشد، این تابع چقدر طول می‌کشد؟ **چه چیزی را می‌شود ذخیره کرد تا هر بار همه‌چیز دوباره خوانده نشود، و آن ذخیره خودش چه ریسکی می‌آورد؟**

**تمرینِ ستاره‌دار ⭐:** انبارت را به **دلتا** ببر: به‌جای ذخیرهٔ کاملِ هر نسخه، فقط ردیف‌های عوض‌شده نسبت به `parent` را ذخیره کن، به‌علاوهٔ یک بازسازیِ کامل هر پنج نسخه. **حجمِ انبار را برای همان ده نسخهٔ این فصل با هر دو روش گزارش کن.** بعد چیزی را که ارزان‌تر شد در برابرِ چیزی که گران‌تر شد بگذار: **زمانِ بازیابیِ یک نسخهٔ قدیمی چقدر شد، و اگر یک دلتای وسطِ زنجیره خراب شود چه از دست می‌رود؟** جوابت توضیح می‌دهد چرا بیشترِ انبارهای دادهٔ واقعی این معامله را **نمی‌کنند**.

## در فصل بعد

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

</div>

---
Source: https://yaadestan.com/courses/darbast/lessons/t2/s04-versioning-data (یادستان, Yaadestan)
