# فصل ۰۳ — اعتبارسنجیِ داده و قراردادِ اسکیما

<div dir="rtl">

# فصل ۰۳ — اعتبارسنجیِ داده و قراردادِ اسکیما

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

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

و بعد هزینه‌اش را حساب می‌کنیم: میانگینِ رضایتِ مشتری با دادهٔ نادیده **۳٫۶۷** است و با دادهٔ معتبر **۳٫۴۱**. **یک‌چهارمِ نمره اختلاف، فقط از خانه‌هایی که کسی نگاهشان نکرده بود.**

![یک ابزارِ اندازه‌گیری که قطعه‌های نامناسب را از خطِ تولید کنار می‌گذارد](/lesson-assets/t2-s03-data-validation/prompt/01-image-gauge-and-tally.png)

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

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

## قبل از شروع

**از فصل ۱:** مرحله‌ها و سیاههٔ منشأ. اعتبارسنجی یک مرحلهٔ دیگرِ همان مسیر است — و معمولاً اولینشان.

**از فصل ۲:** فایلِ خام را **کاملاً به‌صورتِ رشته** می‌خوانیم. اعتبارسنجی باید **قبل از** هر تبدیلی اتفاق بیفتد، وگرنه داری چیزی را می‌سنجی که یک نفر قبلاً حدس زده است.

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

</div>

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

<div dir="rtl">

## ۱. نگاه کردن کافی نیست

</div>

```python
import csv

RAW = WORK / "raw" / "tickets.csv"
with open(RAW, encoding="utf-8") as fh:
    rows = list(csv.DictReader(fh))

print("ردیف:", len(rows))
for r in rows[:2]:
    print({k: r[k] for k in ("ticket_id", "channel", "rating", "handling_minutes")})
```

```text
ردیف: 1240
{'ticket_id': 'TK-01155', 'channel': 'حضوری', 'rating': '4', 'handling_minutes': '209'}
{'ticket_id': 'TK-00868', 'channel': 'حضوری', 'rating': '9', 'handling_minutes': '168'}
```

<div dir="rtl">

**در همین دو ردیفِ اول یک خطا هست و احتمالاً از رویش رد شدی: `rating` برابرِ `9` است، در حالی که این ستون از ۱ تا ۵ است.**

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

**راهِ حل این است که انتظارت را یک بار بنویسی و ماشین هر بار بسنجدش.**

**و برای نوشتنِ آن انتظار، یک زبانِ کوچک لازم داریم: عبارتِ باقاعده.** سرنخ فقط `re.split` را در حدِ «متن را از روی فاصله ببُر» نشان داد. **از همین‌جا تا آخرِ دوره پنج نشانه به‌کار می‌آید و بیشتر از پنج‌تا نه** — پس همه‌شان را یک بار، همین‌جا:

</div>

| نشانه | یعنی | نمونه |
|---|---|---|
| `\d` | **یک** رقم | `\d` با `7` جور است، با `77` نه |
| `[...]` | **یکی** از نویسه‌های داخلِ کروشه؛ `-` بازه می‌سازد | `[۰-۹]` یعنی یک رقمِ فارسی |
| `+` | نشانهٔ قبلی، **یک بار یا بیشتر** | `\d+` یعنی «حداقل یک رقم» |
| `{n}` | نشانهٔ قبلی، **دقیقاً `n` بار** | `\d{5}` یعنی دقیقاً پنج رقم |
| `?` | نشانهٔ قبلی، **صفر یا یک بار** (یعنی اختیاری) | `-?\d+` یعنی عددی با علامتِ منفیِ اختیاری |

<div dir="rtl">

هر نویسهٔ دیگری خودش را می‌سازد: در `TK-\d{5}`، حرف‌های `T` و `K` و `-` عیناً همان‌اند.

</div>

```python
import re

PATTERNS = [
    (r"\d",         ["7", "77", "x"]),
    (r"\d+",        ["7", "77", ""]),
    (r"\d{5}",      ["12345", "1234", "123456"]),
    (r"TK-\d{5}",   ["TK-01234", "TK-1234", "tk-01234"]),
    (r"[۰-۹]+",     ["۱۲", "12", "۱x"]),
    (r"-?\d+",      ["-7", "7", "--7"]),
]
for pattern, samples in PATTERNS:
    verdict = " · ".join(f"{sample or '(خالی)'} {'✓' if re.fullmatch(pattern, sample) else '✗'}"
                         for sample in samples)
    print(f"  {pattern:<12}{verdict}")
print()
print("search در برابرِ fullmatch، روی همان الگو:")
for finder in (re.search, re.fullmatch):
    hit = finder(r"TK-\d{5}", "قبلاً TK-01234 بود")
    print(f"  {finder.__name__:<10}{'پیدا کرد' if hit else 'پیدا نکرد'}")
```

```text
  \d          7 ✓ · 77 ✗ · x ✗
  \d+         7 ✓ · 77 ✓ · (خالی) ✗
  \d{5}       12345 ✓ · 1234 ✗ · 123456 ✗
  TK-\d{5}    TK-01234 ✓ · TK-1234 ✗ · tk-01234 ✗
  [۰-۹]+      ۱۲ ✓ · 12 ✗ · ۱x ✗
  -?\d+       -7 ✓ · 7 ✓ · --7 ✗

search در برابرِ fullmatch، روی همان الگو:
  search    پیدا کرد
  fullmatch پیدا نکرد
```

<div dir="rtl">

**دو ردیف را دوباره بخوان.** `[۰-۹]+` رقمِ **فارسی** می‌خواهد و `12` انگلیسی را رد می‌کند — همان تفاوتی که در دادهٔ فارسی مرتب دردسر می‌سازد. و `r"..."` جلوی رشته لازم است تا `\d` را خودِ پایتون تفسیر نکند.

**و خطِ آخر مهم‌ترین انتخابِ این فصل است:** `search` دنبالِ الگو **جایی داخلِ** متن می‌گردد؛ `fullmatch` می‌خواهد **کلِ** مقدار الگو باشد. برای اعتبارسنجیِ یک ستون همیشه `fullmatch` درست است — **وگرنه `TK-999999999` هم قبول می‌شود، چون پنج رقمِ اولش جور درمی‌آید.**

## ۲. اسکیما، به‌شکلِ داده

</div>

```python
CHANNELS = ["تلفن", "ایمیل", "چت", "حضوری"]
CATEGORIES = ["پرداخت", "ارسال", "حساب کاربری", "اپلیکیشن"]

SCHEMA = {
    "ticket_id":        [("required", None, "error"),
                         ("pattern", r"TK-\d{5}", "error"),
                         ("unique", None, "error")],
    "customer_id":      [("required", None, "error"),
                         ("pattern", r"C-\d{4}", "error")],
    "created_at":       [("required", None, "error"),
                         ("pattern", r"\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}", "error"),
                         ("between", ("2031-01-01", "2031-12-31"), "warn")],
    "channel":          [("required", None, "error"),
                         ("allowed", CHANNELS, "warn")],
    "branch_code":      [("required", None, "error"),
                         ("pattern", r"\d{3}", "error")],
    "text":             [("required", None, "warn")],
    "category":         [("required", None, "error"),
                         ("allowed", CATEGORIES, "error")],
    "escalated":        [("required", None, "error"),
                         ("allowed", ["0", "1"], "error")],
    "rating":           [("integer", None, "warn"),
                         ("range", (1, 5), "warn")],
    "handling_minutes": [("required", None, "error"),
                         ("integer", None, "error"),
                         ("range", (0, 1440), "warn")],
}
print("ستون‌های زیرِ قرارداد:", len(SCHEMA),
      "· قاعده‌ها:", sum(len(v) for v in SCHEMA.values()))
```

```text
ستون‌های زیرِ قرارداد: 10 · قاعده‌ها: 22
```

<div dir="rtl">

**این اسکیما کد نیست، داده است** — یک `dict` که می‌شود در فایل ذخیره‌اش کرد، `diff` گرفت، و نسخه داد. اگر همین قاعده‌ها را به‌شکلِ `if` در جای‌جای مسیر می‌نوشتی، **هیچ‌کس نمی‌توانست بپرسد «قراردادِ ما با این جدول چیست؟» و یک جواب بگیرد.**

هر قاعده سه چیز دارد: **نوعش، آرگومانش، و شدتش.** ستونِ سوم مهم‌ترینِ آن‌هاست و بخشِ ۶ کاملاً دربارهٔ همان است.

**و به یک انتخابِ عمدی دقت کن:** `created_at` هم قاعدهٔ `error` دارد (شکلش باید تاریخ باشد) و هم قاعدهٔ `warn` (باید در بازهٔ منطقی باشد). **رشته‌ای که اصلاً تاریخ نیست، کدِ پایین‌دستی را می‌شکند؛ تاریخی که در آینده است فقط داده‌ای است که باید دربارهٔ آن تصمیم بگیری.**

## ۳. اعتبارسنج، از اجزای اولیه

</div>

```python
import re


def check_value(kind, arg, value):
    if kind == "required":
        return value.strip() != ""
    if value.strip() == "":
        return True                       # خانهٔ خالی فقط با required سنجیده می‌شود
    if kind == "pattern":
        return re.fullmatch(arg, value) is not None
    if kind == "allowed":
        return value in arg
    if kind == "integer":
        return re.fullmatch(r"-?\d+", value) is not None
    if kind == "range":
        return value.lstrip("-").isdigit() and arg[0] <= int(value) <= arg[1]
    if kind == "between":
        return arg[0] <= value <= arg[1]
    raise ValueError("قاعدهٔ ناشناخته: " + kind)


def validate(rows, schema):
    findings = []
    for column, checks in schema.items():
        for kind, arg, severity in checks:
            if kind == "unique":
                seen, bad = set(), []
                for r in rows:
                    if r[column] in seen:
                        bad.append(r[column])
                    seen.add(r[column])
            else:
                bad = [r[column] for r in rows if not check_value(kind, arg, r[column])]
            if bad:
                findings.append({"column": column, "rule": kind, "severity": severity,
                                 "count": len(bad), "sample": bad[0]})
    return findings


findings = validate(rows, SCHEMA)
print("قاعده‌هایی که شکستند:", len(findings))
```

```text
قاعده‌هایی که شکستند: 5
```

<div dir="rtl">

**دو تصمیمِ طراحی در این سی خط هست که ارزشِ دیدن دارند.**

**اول، اعتبارسنج در اولین تخلف نمی‌ایستد.** هر قاعده را روی **همهٔ** ردیف‌ها می‌سنجد و همه را جمع می‌کند. اگر با اولین خطا `raise` می‌کرد، هر بار فقط یک عیب می‌دیدی و بیست بار اجرا لازم بود. **گزارش، نه استثنا.**

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

## ۴. گزارشِ کیفیتِ داده

</div>

```python
def report(findings, total):
    print(f"{'ستون':<20}{'قاعده':<10}{'شدت':<8}{'تعداد':>7}{'سهم':>8}   نمونه")
    for f in sorted(findings, key=lambda f: -f["count"]):
        share = 100 * f["count"] / total
        sample = f["sample"] if f["sample"] else "«خالی»"
        print(f"{f['column']:<20}{f['rule']:<10}{f['severity']:<8}"
              f"{f['count']:>7}{share:>7.1f}٪   {sample[:22]}")


report(findings, len(rows))
```

```text
ستون                قاعده     شدت       تعداد     سهم   نمونه
rating              range     warn        241   19.4٪   9
ticket_id           unique    error        40    3.2٪   TK-00001
handling_minutes    range     warn         35    2.8٪   -16
text                required  warn          5    0.4٪   «خالی»
created_at          between   warn          3    0.2٪   2033-07-19 10:15:00
```

<div dir="rtl">

**۳۲۴ خانهٔ متخلف در پنج قاعده — و هیچ‌کدام از این‌ها با چشم پیدا نمی‌شد.**

- **۲۴۱ تیکت امتیازِ ناممکن دارند** (`0` یا `9`). این تقریباً یک‌پنجمِ کلِ داده است.
- **۴۰ تیکت شناسهٔ تکراری دارند** — همان ردیف‌های دوباره‌واردشدهٔ فصلِ ۱.
- **۳۵ تیکت زمانِ رسیدگیِ منفی دارند.** منفی، نه صفر.
- **سه تیکت تاریخِ آینده دارند.** یک عیبِ کلاسیکِ سامانه‌های واقعی است: ساعتِ یک سرور اشتباه تنظیم شده.

> ✅ **چک کن:** ستونِ «نمونه» را جدی بگیر. یک عدد به تنهایی («۲۴۱ تخلف») به‌ت نمی‌گوید چه اتفاقی افتاده؛ **دیدنِ `9` فوراً می‌گوید مشکل چیست: جایی کسی «بدونِ نظر» را با ۹ کد کرده است.** گزارشی که نمونه ندارد، فقط اضطراب تولید می‌کند.

## ۵. هزینهٔ ندیدن

اینجا معمولاً کسی می‌پرسد «خب، دویست‌وچهل‌تا از هزارودویست‌تا، چقدر مهم است؟» جوابش عدد دارد.

</div>

```python
def mean(values):
    return sum(values) / len(values)


all_rating = [int(r["rating"]) for r in rows if r["rating"].strip()]
ok_rating = [v for v in all_rating if 1 <= v <= 5]
all_min = [int(r["handling_minutes"]) for r in rows]
ok_min = [v for v in all_min if 0 <= v <= 1440]
print(f"میانگینِ rating — با هر چه در فایل هست: {mean(all_rating):.2f}"
      f" · فقط مقادیرِ مجاز: {mean(ok_rating):.2f}")
print(f"میانگینِ دقیقه  — با هر چه در فایل هست: {mean(all_min):.1f}"
      f" · فقط مقادیرِ مجاز: {mean(ok_min):.1f}")
```

```text
میانگینِ rating — با هر چه در فایل هست: 3.67 · فقط مقادیرِ مجاز: 3.41
میانگینِ دقیقه  — با هر چه در فایل هست: 111.7 · فقط مقادیرِ مجاز: 118.4
```

<div dir="rtl">

**۳٫۶۷ در برابرِ ۳٫۴۱، و ۱۱۱٫۷ در برابرِ ۱۱۸٫۴.**

و دقت کن دو خطا در دو **جهتِ مخالف**اند: `9`های ناممکن میانگینِ رضایت را **بالا** برده‌اند و دقیقه‌های منفی میانگینِ زمان را **پایین**. **پس نمی‌شود گفت «خطاها همدیگر را خنثی می‌کنند»؛ هر ستون رفتارِ خودش را دارد.**

**و این عددها همان چیزی‌اند که در جلسه روی اسلاید می‌رود.** کسی که یک‌چهارمِ نمرهٔ رضایت اختلاف را ببیند، تصمیم می‌گیرد. اعتبارسنجی برای گرفتنِ `traceback` نیست؛ برای این است که تصمیم‌ها روی عددِ درست گرفته شوند.

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

## ۶. کدام تخلف باید مسیر را متوقف کند

</div>

```python
fatal = [f for f in findings if f["severity"] == "error"]
soft = [f for f in findings if f["severity"] == "warn"]
print("بازدارنده :", sum(f["count"] for f in fatal), "خانه در", len(fatal), "قاعده")
print("ثبت‌شونده :", sum(f["count"] for f in soft), "خانه در", len(soft), "قاعده")
```

```text
بازدارنده : 40 خانه در 1 قاعده
ثبت‌شونده : 284 خانه در 4 قاعده
```

<div dir="rtl">

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

معیارِ ما این است: **تخلفی که کدِ پایین‌دستی را غلط می‌کند، بازدارنده است؛ تخلفی که فقط یک واقعیتِ ناخوشایند دربارهٔ داده است، ثبت می‌شود.**

- شناسهٔ تکراری **بازدارنده** است، چون هر `join` ای که با آن بزنی ردیف تکثیر می‌کند و هیچ خطایی هم نمی‌دهد. **یک باگِ بی‌صدا در همهٔ پایین‌دست.**
- امتیازِ `9` **ثبت‌شونده** است، چون کدِ پایین‌دستی درست کار می‌کند؛ فقط جوابش بی‌معنا می‌شود. این را با یک فیلترِ آگاهانه حل می‌کنی، نه با متوقف کردنِ مسیر.

**و یک هشدارِ عملی: وسوسه می‌شوی همه‌چیز را `error` کنی. نکن.** مسیری که هر روز به‌خاطرِ سه تاریخِ عجیب متوقف شود، ظرفِ دو هفته کسی «موقتاً» خاموشش می‌کند — و آن موقت هیچ‌وقت تمام نمی‌شود. **دروازه‌ای که همیشه قرمز است، دروازه نیست.**

## ۷. ستونی که در اسکیما هست ولی در فایل نیست

فرض کن قرار است ستونِ تازه‌ای به نامِ `priority` اضافه شود و تو زودتر از سامانهٔ بالادستی قرارداد را نوشته‌ای.

</div>

```python
SCHEMA["priority"] = [("required", None, "error"),
                      ("allowed", ["کم", "متوسط", "زیاد"], "error")]
try:
    validate(rows, SCHEMA)
except KeyError as e:
    print("KeyError:", e)
```

```text
KeyError: 'priority'
```

<div dir="rtl">

> 🔧 **اگر کار نکرد:** `KeyError: 'priority'` یعنی `r[column]` روی ستونی صدا زده شده که در ردیف نیست. **این خطا درست است ولی جایش غلط است**: از عمقِ حلقه بیرون آمده، بعد از اینکه اعتبارسنج ده ستونِ دیگر را هم سنجیده، و به کسی که گزارش را می‌خواند هیچ نمی‌گوید. **قاعده: قبل از لمسِ اولین ردیف، سرستون‌ها را بسنج.**

</div>

```python
def validate(rows, schema):
    """نسخهٔ دوم: اول سرستون‌ها، بعد خانه‌ها."""
    present = set(rows[0])
    missing = [c for c in schema if c not in present]
    extra = [c for c in present if c not in schema]
    if missing:
        raise ValueError("ستونِ اعلام‌شده در فایل نیست: " + ", ".join(missing))
    findings = [{"column": c, "rule": "unknown", "severity": "warn",
                 "count": len(rows), "sample": ""} for c in extra]
    for column, checks in schema.items():
        for kind, arg, severity in checks:
            if kind == "unique":
                seen, bad = set(), []
                for r in rows:
                    if r[column] in seen:
                        bad.append(r[column])
                    seen.add(r[column])
            else:
                bad = [r[column] for r in rows if not check_value(kind, arg, r[column])]
            if bad:
                findings.append({"column": column, "rule": kind, "severity": severity,
                                 "count": len(bad), "sample": bad[0]})
    return findings


try:
    validate(rows, SCHEMA)
except ValueError as e:
    print("ValueError:", e)
del SCHEMA["priority"]
```

```text
ValueError: ستونِ اعلام‌شده در فایل نیست: priority
```

<div dir="rtl">

**همان خرابی، این بار با پیامی که می‌شود بر اساسش کار کرد** — و بدونِ هدر دادنِ یک پیمایشِ کاملِ داده.

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

## ۸. قرارداد یک فایل است

</div>

```python
import json

SCHEMA_PATH = WORK / "schema.json"
SCHEMA_PATH.write_text(json.dumps(SCHEMA, ensure_ascii=False, indent=1), encoding="utf-8")
loaded = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
print("همان نتیجه از اسکیمای خوانده‌شده:", validate(rows, loaded) == findings)
print("حجمِ فایلِ اسکیما:", SCHEMA_PATH.stat().st_size, "بایت")
```

```text
همان نتیجه از اسکیمای خوانده‌شده: True
حجمِ فایلِ اسکیما: 1592 بایت
```

<div dir="rtl">

**۱۵۹۲ بایت — و همین یک‌ونیم کیلوبایت کلِ انتظارِ تو از جدولی است که فصلِ ۲ حجمش را حدودِ ۲۴۶ کیلوبایت اندازه گرفت.**

حالا که قرارداد یک فایل است، سه چیزِ تازه ممکن می‌شود:

- می‌شود در `git` گذاشتش و دید **کِی و چرا** عوض شده.
- می‌شود همان فایل را به سامانهٔ بالادستی داد تا **قبل از فرستادن** خودش بسنجد.
- می‌شود کنارِ هر نسخه از داده، نسخهٔ قراردادی را هم نگه داشت که آن داده با آن اعتبارسنجی شده است.

**فصلِ بعد برای سومی زمینه را می‌سازد:** فهرستِ نسخه و اثرِ انگشت. ثبتِ اثرِ انگشتِ خودِ فایلِ اسکیما کنارِ هر نسخه یک ستونِ اضافه در همان فهرست است.

## ۹. و بعد از پاک‌سازی

</div>

```python
def clean(rows):
    seen, out = set(), []
    for r in rows:
        key = tuple(r.values())
        if key in seen:                                   # unique · error
            continue
        seen.add(key)
        if not r["text"].strip():                         # text required · warn
            continue
        if not (0 <= int(r["handling_minutes"]) <= 1440):  # range · warn
            continue
        if not ("2031-01-01" <= r["created_at"] <= "2031-12-31"):   # between · warn
            continue
        if r["rating"] and not (1 <= int(r["rating"]) <= 5):
            r = {**r, "rating": ""}                       # امتیازِ ناممکن = «نداریم»
        out.append(r)
    return out


cleaned = clean(rows)
after = validate(cleaned, SCHEMA)
print("قبل:", len(rows), "ردیف ·", sum(f["count"] for f in findings), "خانهٔ متخلف در",
      len(findings), "قاعده")
print("بعد:", len(cleaned), "ردیف ·", sum(f["count"] for f in after), "خانهٔ متخلف در",
      len(after), "قاعده")
print("افت:", len(rows) - len(cleaned), "ردیف ·",
      f"{100 * (len(rows) - len(cleaned)) / len(rows):.1f}٪")
```

```text
قبل: 1240 ردیف · 324 خانهٔ متخلف در 5 قاعده
بعد: 1160 ردیف · 0 خانهٔ متخلف در 0 قاعده
افت: 80 ردیف · 6.5٪
```

<div dir="rtl">

**صفر تخلف — ولی حواست باشد این عدد چه چیزی را ثابت می‌کند و چه چیزی را نه.**

ثابت می‌کند که `clean` دقیقاً همان پنج تخلفی را برداشته که اعتبارسنج پیدا کرده بود. **ثابت نمی‌کند که داده «تمیز» است.** اعتبارسنج فقط چیزهایی را می‌بیند که به او گفته‌ای ببیند؛ هر عیبی که قاعده‌ای برایش ننوشته‌ای، همچنان آنجاست و همچنان نامرئی است.

**و حالا به آن ۲۴۱ امتیازِ ناممکن برگرد: با وجودشان، افتِ ردیف فقط ۶٫۵ درصد شد.** چون آن ۲۴۱ ردیف حذف نشدند؛ **فقط خانهٔ `rating` شان خالی شد.** تفاوت مهم است: ردیفی که یک خانهٔ بدش را خالی کرده‌ای هنوز نُه ستونِ سالمِ دیگر دارد. **دور ریختنِ کلِ ردیف به‌خاطرِ یک خانه، ارزان‌ترین کار است و معمولاً غلط‌ترین.**

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

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| schema contract | اسکیما کانترکت | انتظارِ نوشته‌شده از ستون‌ها، به‌شکلِ داده |
| validation | ولیدیشن | سنجیدنِ داده در برابرِ آن انتظار |
| fail fast | فیل فست | ایستادن در اولین جای ممکن، با پیامی که کار می‌بندد |
| severity | سِویریتی | اینکه یک تخلف باید متوقف کند یا فقط ثبت شود |
| data quality report | دیتا کوالیتی ریپورت | گزارشِ شمارشیِ تخلف‌ها با نمونه |
| unexpected column | آن‌اکسپکتد کالمن | ستونی که در داده هست ولی در قرارداد نیست |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا «شناسهٔ تکراری» بازدارنده است ولی «امتیازِ ۹» نه؟

**تمرینِ اجباری:** دو قاعدهٔ تازه به اسکیما اضافه کن: **(الف)** `text` نباید بیشتر از ۶۰۰ نویسه باشد، و **(ب)** `customer_id` باید در بیشتر از یک ردیف دیده شود یا فقط یک بار — هرکدام را که فکر می‌کنی درست است انتخاب کن و **دلیلش را بنویس**. بعد گزارش را دوباره بساز. **کدام قاعدهٔ تازه تخلف پیدا کرد و کدام هیچ؟** قاعده‌ای که هیچ‌وقت تخلف پیدا نمی‌کند هم ارزش دارد — ولی باید بدانی چرا نگهش داشته‌ای.

**تمرینِ ستاره‌دار ⭐:** سه راهِ برخورد با ۲۴۱ امتیازِ ناممکن را **اندازه بگیر**، نه اینکه انتخاب کنی: ردیف را حذف کن، خانه را خالی کن، یا با میانهٔ مقادیرِ مجاز پرش کن. برای هر سه، **میانگینِ `rating` به‌تفکیکِ `category`** را حساب کن و در یک جدول کنارِ هم بگذار. **کدام راه ترتیبِ دسته‌ها را عوض می‌کند؟** جوابت نشان می‌دهد که «پاک‌سازی» یک تصمیمِ تحلیلی است، نه یک کارِ فنیِ خنثی — و باید مثلِ هر تصمیمِ دیگری ثبت شود.

## در فصل بعد

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

</div>

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