# فصل ۰۸ — تحلیلی که فردا هم همان است

<div dir="rtl">

# فصل ۰۸ — تحلیلی که فردا هم همان است

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

گزارشِ فصلِ قبل تحویل شد. سه هفته بعد کسی می‌پرسد «همان عددِ اعضای فعال را دوباره بگیر». همان پرسش را اجرا می‌کنی و عدد فرق کرده.

سؤالِ بعدی‌اش سختِ واقعی است: **«خب کدامش درست است؟»**

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

![یک ظرفِ نمونهٔ آزمایشگاهی که مهر و برچسب خورده، کنارِ ظرفِ همانندی که بازمانده و محتویاتش تبخیر شده است](/lesson-assets/t6-s08-repeatable-analysis/prompt/01-image-sealed-specimen.png)

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

- بگویی یک عدد به کدام تاریخِ برش بند است و چرا فردا فرق می‌کند
- تاریخ و هر عددِ سیاستیِ دیگر را از متنِ پرسش بیرون بکشی
- پرسش‌هایت را نسخه‌دار ذخیره کنی، طوری که نسخهٔ قدیمی هرگز عوض نشود
- `VIEW` بسازی و بگویی کجا کافی است و کجا اصلاً کافی نیست
- هر عددی را که تحویل می‌دهی با یک فرمان بازتولید کنی
- نتیجه را از Colab بیرون ببری، طوری که فارسی‌اش در Excel هم درست باز شود

## قبل از شروع

**از فصلِ ۲:** تعریفِ عملیاتی و `metric_book`. **از فصلِ ۷:** سه برچسبِ اجباریِ هر عدد. **از ترمِ ۴:** `PRIMARY KEY` مرکب و `UNIQUE`، و قاعدهٔ فقط-افزودنیِ مهاجرت — که در بخشِ ۳ دقیقاً همان است.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/avand/term-6-number-to-decision/session-08-repeatable-analysis.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

</div>

| جدول | تعدادِ سطر | زمانِ ساخت |
|---|---|---|
| `members` | ۱٬۴۰۰ | آنی |
| `loans` | ۱۶٬۸۳۴ | کمتر از دو ثانیه |
| `saved_queries` و `analysis_runs` (همین فصل می‌سازدشان) | ۲ و ۴ | آنی |

<div dir="rtl">

## ۱. همان پرسش، سه جواب

یک پرسش، بدونِ حتی یک کاراکتر تغییر، با سه تاریخِ برشِ متفاوت:

</div>

```python
ACTIVE = """
    SELECT COUNT(DISTINCT member_id) AS active
    FROM loans
    WHERE borrowed_at > date(?, '-90 days') AND borrowed_at <= ?
"""
for cut in ("2025-03-31", "2025-05-12", AS_OF):
    print("تاریخ برش", cut, "→", int(q(ACTIVE, (cut, cut)).iloc[0, 0]))
```

```text
تاریخ برش 2025-03-31 → 829
تاریخ برش 2025-05-12 → 833
تاریخ برش 2025-06-12 → 851
```

<div dir="rtl">

**۸۲۹ و ۸۳۳ و ۸۵۱ — و پرسش عوض نشده.**

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

**پس اولین قاعدهٔ این فصل: هیچ عددی بدونِ تاریخِ برشش تحویل داده نمی‌شود.** دقیقاً مثلِ واحد و دوره در فصلِ ۷.

## ۲. تاریخِ برش را از متنِ پرسش بیرون بکش

راهِ آسان این است که تاریخ را همان‌جا در پرسش بنویسی. جواب می‌دهد — یک بار.

</div>

```python
BAKED = """
    SELECT COUNT(DISTINCT member_id) AS active
    FROM loans
    WHERE borrowed_at > '2025-03-14' AND borrowed_at <= '2025-06-12'
"""
print("پرسش با تاریخ چسبیده:", int(q(BAKED).iloc[0, 0]))
print("همان با پارامتر     :", int(q(ACTIVE, (AS_OF, AS_OF)).iloc[0, 0]))
print()
print("و همان پرسش پارامتری با برش سه‌ماه قبل‌تر:",
      int(q(ACTIVE, ("2025-03-12", "2025-03-12")).iloc[0, 0]))
print("در حالی که پرسش چسبیده هنوز می‌گوید      :", int(q(BAKED).iloc[0, 0]))
```

```text
پرسش با تاریخ چسبیده: 851
همان با پارامتر     : 851

و همان پرسش پارامتری با برش سه‌ماه قبل‌تر: 824
در حالی که پرسش چسبیده هنوز می‌گوید      : 851
```

<div dir="rtl">

**هر دو نسخه امروز ۸۵۱ می‌دهند و فردا فقط یکی‌شان قابلِ استفاده است.**

پرسشِ چسبیده به هر برشی که بدهی همان ۸۵۱ را می‌دهد، چون اصلاً برش نمی‌گیرد. **بدترین شکلِ خرابی هم همین است: هیچ خطایی نمی‌دهد و عددی برمی‌گرداند که شش ماهِ پیش درست بوده.**

و یادآوریِ قاعدهٔ ثابتِ دوره: تاریخ یک **مقدار** است، پس با `?` می‌رود. **رشته‌چسبانیِ تاریخ داخلِ متنِ پرسش، حتی برای «فقط همین یک بار»، همان چیزی است که ترمِ ۱ فصلِ ۷ ممنوع کرد.**

## ۳. پرسش را ذخیره کن، و نسخه‌اش را عوض نکن

پارامتر کافی نیست. فردا تعریف هم عوض می‌شود — مثلاً تصمیم می‌گیری اعضایی را که عضویتشان تمام شده نشماری. آن‌وقت دو تعریف داری و هر دو معتبرند، مثلِ فصلِ ۲.

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

</div>

```python
ACTIVE_V2 = """
    SELECT COUNT(DISTINCT l.member_id) AS active
    FROM loans AS l
    JOIN members AS m ON m.id = l.member_id
    WHERE l.borrowed_at > date(?, '-90 days') AND l.borrowed_at <= ?
      AND m.left_at IS NULL
"""
con.execute("DROP TABLE IF EXISTS saved_queries")
con.execute("""
    CREATE TABLE saved_queries (
        name     TEXT    NOT NULL,
        version  INTEGER NOT NULL,
        note     TEXT    NOT NULL,
        sql_text TEXT    NOT NULL,
        PRIMARY KEY (name, version)
    )
""")
con.executemany("INSERT INTO saved_queries VALUES (?, ?, ?, ?)", [
    ("active_borrower", 1, "هر عضوی که در ۹۰ روز منتهی به تاریخ برش امانت گرفته", ACTIVE),
    ("active_borrower", 2, "همان، ولی فقط اعضایی که هنوز عضو هستند", ACTIVE_V2),
])
con.commit()
print(q("SELECT name, version, note FROM saved_queries ORDER BY name, version").to_string(index=False))
```

```text
           name  version                                                note
active_borrower        1 هر عضوی که در ۹۰ روز منتهی به تاریخ برش امانت گرفته
active_borrower        2              همان، ولی فقط اعضایی که هنوز عضو هستند
```

<div dir="rtl">

**کلیدِ مرکبِ `(name, version)` کارِ اصلی را می‌کند: پایگاه داده خودش نمی‌گذارد یک نسخه دو بار نوشته شود.**

> 🔧 **اگر کار نکرد:** طبیعی‌ترین کاری که آدم بعد از یک تغییرِ کوچک می‌کند این است که همان نسخه را دوباره بنویسد. قید جلویش را می‌گیرد:

</div>

```python
try:
    con.execute("INSERT INTO saved_queries VALUES (?, ?, ?, ?)",
                ("active_borrower", 2, "یک تغییر کوچک", ACTIVE_V2))
except Exception as error:
    print(type(error).__module__ + "." + type(error).__name__)
    print(error)
con.rollback()
```

```text
sqlite3.IntegrityError
UNIQUE constraint failed: saved_queries.name, saved_queries.version
```

<div dir="rtl">

**این خطا دقیقاً همان چیزی است که می‌خواستیم.** اگر نسخهٔ ۲ عوض شود، هر عددی که قبلاً با نسخهٔ ۲ گزارش شده دیگر بازتولیدپذیر نیست — و بدتر، کسی متوجه نمی‌شود. **نسخهٔ سه بساز؛ نسخهٔ دو مالِ گذشته است.**

## ۴. `VIEW`: پرسشی که خودِ پایگاه داده اسمش را می‌داند

جدولِ `saved_queries` متنِ `SQL` را در یک ستونِ `TEXT` نگه می‌دارد. طبیعی است بپرسی چرا خودِ پایگاه داده جایی برای نگه داشتنِ یک پرسش ندارد. **دارد، و اسمش `VIEW` است: یک پرسشِ نام‌دار که مثلِ جدول از آن `SELECT` می‌گیری، ولی هیچ سطری ذخیره نمی‌کند و هر بار از نو اجرا می‌شود.**

</div>

```python
con.execute("DROP VIEW IF EXISTS current_members")
con.execute("""
    CREATE VIEW current_members AS
    SELECT id, name FROM members WHERE left_at IS NULL
""")
con.commit()

print(q("""
    SELECT type, name, tbl_name FROM sqlite_master
    WHERE name IN (?, ?) ORDER BY name
""", ("current_members", "saved_queries")).to_string(index=False))
print()
print("اعضای فعلی:", int(q("SELECT COUNT(*) AS n FROM current_members").iloc[0, 0]))
```

```text
 type            name        tbl_name
 view current_members current_members
table   saved_queries   saved_queries

اعضای فعلی: 1000
```

<div dir="rtl">

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

و از آن مثلِ جدول استفاده می‌شود:

</div>

```python
ACTIVE_V3 = """
    SELECT COUNT(DISTINCT l.member_id) AS active
    FROM loans AS l
    JOIN current_members AS m ON m.id = l.member_id
    WHERE l.borrowed_at > date(?, '-90 days') AND l.borrowed_at <= ?
"""
print("نسخه ۲، پرسش کامل:", int(q(ACTIVE_V2, (AS_OF, AS_OF)).iloc[0, 0]))
print("همان، با VIEW    :", int(q(ACTIVE_V3, (AS_OF, AS_OF)).iloc[0, 0]))
```

```text
نسخه ۲، پرسش کامل: 833
همان، با VIEW    : 833
```

<div dir="rtl">

همان عدد، و پرسش کوتاه‌تر و خواناتر شد. **پس چرا `saved_queries` را دور نمی‌اندازیم؟** به‌خاطرِ دو مرز که هیچ‌کدامشان قابلِ دور زدن نیستند.

**مرزِ اول: `VIEW` پارامتر نمی‌گیرد.** تاریخِ برش نمی‌تواند از بیرون بیاید، و همین کلِ درسِ بخشِ ۱ و ۲ را از دسترسش خارج می‌کند:

</div>

```python
try:
    con.execute("""
        CREATE VIEW active_90 AS
        SELECT COUNT(DISTINCT member_id) AS active
        FROM loans
        WHERE borrowed_at > date(?, '-90 days') AND borrowed_at <= ?
    """)
except Exception as error:
    print(type(error).__module__ + "." + type(error).__name__)
    print(error)
```

```text
sqlite3.OperationalError
parameters are not allowed in views
```

<div dir="rtl">

**پیام صریح است.** تنها راهی که می‌ماند چسباندنِ تاریخ به متنِ `VIEW` است — یعنی دقیقاً همان `BAKED` بخشِ ۲ که فردا عددِ دیروز را می‌دهد و خطایی هم نمی‌دهد.

**مرزِ دوم: `VIEW` نسخه ندارد.** یک نام دارد و بس، و عوض کردنِ تعریفش یعنی برداشتن و دوباره ساختن:

</div>

```python
before = int(q("SELECT COUNT(*) AS n FROM current_members").iloc[0, 0])
con.execute("DROP VIEW current_members")
con.execute("""
    CREATE VIEW current_members AS
    SELECT id, name FROM members
    WHERE left_at IS NULL AND home_branch_id IS NOT NULL
""")
con.commit()
after = int(q("SELECT COUNT(*) AS n FROM current_members").iloc[0, 0])

print("قبل از تغییر تعریف:", before)
print("بعد از تغییر تعریف:", after)
print("نام‌های current_members در sqlite_master:",
      int(q("SELECT COUNT(*) AS n FROM sqlite_master WHERE name = ?",
            ("current_members",)).iloc[0, 0]))
```

```text
قبل از تغییر تعریف: 1000
بعد از تغییر تعریف: 930
نام‌های current_members در sqlite_master: 1
```

<div dir="rtl">

**دو عدد از یک نام، و هیچ‌جا ننوشته که تعریف عوض شده.** هر گزارشی که دیروز با این `VIEW` ساخته شده، امروز بازتولیدپذیر نیست و هیچ‌کس هم خبردار نمی‌شود — همان چیزی که کلیدِ مرکبِ `(name, version)` در بخشِ ۳ جلویش را گرفت.

**پس هر دو را نگه می‌داریم و کارشان را تقسیم می‌کنیم:** `VIEW` برای تکه‌های ثابت و بی‌پارامترِ تعریف که می‌خواهی در خودِ اسکیما زندگی کنند، و `saved_queries` برای سنجه‌ای که پارامتر می‌گیرد و باید نسخه‌اش برای همیشه بماند.

## ۵. دفترِ تحلیل، و اجرای یک‌فرمانی

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

</div>

```python
con.execute("DROP TABLE IF EXISTS analysis_runs")
con.execute("""
    CREATE TABLE analysis_runs (
        id      INTEGER PRIMARY KEY,
        ran_at  TEXT    NOT NULL,
        name    TEXT    NOT NULL,
        version INTEGER NOT NULL,
        as_of   TEXT    NOT NULL,
        value   REAL    NOT NULL
    )
""")
con.commit()


def run_metric(name, as_of, version=None):
    """یک سنجه ذخیره‌شده را اجرا می‌کند، در دفتر ثبتش می‌کند، و مقدارش را برمی‌گرداند."""
    if version is None:
        version = con.execute(
            "SELECT MAX(version) FROM saved_queries WHERE name = ?", (name,)
        ).fetchone()[0]
    sql_text = con.execute(
        "SELECT sql_text FROM saved_queries WHERE name = ? AND version = ?",
        (name, version),
    ).fetchone()[0]
    value = float(q(sql_text, (as_of, as_of)).iloc[0, 0])
    con.execute(
        "INSERT INTO analysis_runs (ran_at, name, version, as_of, value)"
        " VALUES (datetime('now'), ?, ?, ?, ?)",
        (name, version, as_of, value),
    )
    con.commit()
    return value


print("نسخه ۲ با برش امروز :", run_metric("active_borrower", AS_OF))
print("نسخه ۲ دوباره       :", run_metric("active_borrower", AS_OF))
print("نسخه ۱ با همان برش  :", run_metric("active_borrower", AS_OF, version=1))
print("نسخه ۲ با برش قدیمی :", run_metric("active_borrower", "2025-03-31"))
```

```text
نسخه ۲ با برش امروز : 833.0
نسخه ۲ دوباره       : 833.0
نسخه ۱ با همان برش  : 851.0
نسخه ۲ با برش قدیمی : 799.0
```

<div dir="rtl">

**چهار اجرا، و هر عدد فقط به دو چیز بند است: نسخه و تاریخِ برش.**

- همان نسخه و همان برشِ دو بار → همان ۸۳۳. **بازتولیدپذیری یعنی همین و بس.**
- نسخهٔ ۱ در برابرِ نسخهٔ ۲ با یک برش → ۸۵۱ و ۸۳۳. اختلافشان دقیقاً همان ۱۸ عضوی است که در نود روزِ گذشته امانت گرفتند و بعد عضویتشان تمام شد.
- نسخهٔ ۲ با برشِ قدیمی‌تر → ۷۹۹.

**سه‌تا از این چهار عدد متفاوت‌اند و هیچ‌کدام غلط نیست** — چون هر کدام برچسبِ کاملِ خودش را دارد.

## ۶. دفتر چه چیزی را نگه می‌دارد

</div>

```python
print(q("""
    SELECT name, version, as_of, CAST(value AS INTEGER) AS value, COUNT(*) AS runs
    FROM analysis_runs
    GROUP BY name, version, as_of, value
    ORDER BY version, as_of
""").to_string(index=False))
print()
print("سطرهای دفتر:", int(q("SELECT COUNT(*) AS n FROM analysis_runs").iloc[0, 0]))
```

```text
           name  version      as_of  value  runs
active_borrower        1 2025-06-12    851     1
active_borrower        2 2025-03-31    799     1
active_borrower        2 2025-06-12    833     2

سطرهای دفتر: 4
```

<div dir="rtl">

**چهار اجرا، سه ترکیبِ متمایز — و ستونِ `runs` می‌گوید ترکیبِ تکراری همان مقدار را داده.**

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

**و ارزشِ واقعیِ این دفتر جایی معلوم می‌شود که کسی می‌پرسد «چرا عددِ ماهِ پیش با این نمی‌خواند؟»** جواب دیگر حافظه نیست، یک سطر است.

## ۷. رسید: پرسش را کنارِ عدد تحویل بده

آخرین تکه. هر عددی که بیرون می‌رود، با هر چیزی که برای بازساختنش لازم است بیرون می‌رود:

</div>

```python
receipt = con.execute("""
    SELECT r.name, r.version, r.as_of, r.value, s.note, s.sql_text
    FROM analysis_runs AS r
    JOIN saved_queries AS s ON s.name = r.name AND s.version = r.version
    ORDER BY r.id DESC
    LIMIT 1
""").fetchone()
print("سنجه   :", receipt[0], "| نسخه:", receipt[1])
print("تاریخ برش:", receipt[2])
print("مقدار  :", int(receipt[3]))
print("تعریف  :", receipt[4])
print("پرسش   :")
print(receipt[5].strip())
```

```text
سنجه   : active_borrower | نسخه: 2
تاریخ برش: 2025-03-31
مقدار  : 799
تعریف  : همان، ولی فقط اعضایی که هنوز عضو هستند
پرسش   :
SELECT COUNT(DISTINCT l.member_id) AS active
    FROM loans AS l
    JOIN members AS m ON m.id = l.member_id
    WHERE l.borrowed_at > date(?, '-90 days') AND l.borrowed_at <= ?
      AND m.left_at IS NULL
```

<div dir="rtl">

**عدد، تعریف، نسخه، تاریخِ برش، و متنِ دقیقِ پرسش — در یک تکه.**

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

## ۸. و حالا از Colab بیاورش بیرون

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

سه چیز را بیرون می‌بریم: **جدولِ نتیجه به‌شکلِ `CSV`، متنِ گزارش، و خودِ فایلِ `.db`.**

</div>

```python
import shutil

OUT = WORK / "delivery"
OUT.mkdir(exist_ok=True)

report = q("""
    SELECT r.name, r.version, r.as_of, CAST(r.value AS INTEGER) AS value, s.note
    FROM analysis_runs AS r
    JOIN saved_queries AS s ON s.name = r.name AND s.version = r.version
    ORDER BY r.id
""")
csv_path = OUT / "active_borrower.csv"
report.to_csv(csv_path, index=False, encoding="utf-8-sig")

(OUT / "report.txt").write_text(
    "سنجه: active_borrower | تاریخ برش: %s\nسطرهای دفتر: %d\n" % (AS_OF, len(report)),
    encoding="utf-8",
)

con.commit()
shutil.copy(DB_PATH, OUT / "analysis.db")
copy_con = sqlite3.connect(OUT / "analysis.db")
tables = copy_con.execute(
    "SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'"
).fetchone()[0]
copy_con.close()

print("فایل‌های تحویل:", [path.name for path in sorted(OUT.iterdir())])
print("سطرهای CSV      :", len(report))
print("جدول‌های نسخه کپی:", tables)
print("سه بایت اول CSV :", csv_path.read_bytes()[:3])
```

```text
فایل‌های تحویل: ['active_borrower.csv', 'analysis.db', 'report.txt']
سطرهای CSV      : 4
جدول‌های نسخه کپی: 7
سه بایت اول CSV : b'\xef\xbb\xbf'
```

<div dir="rtl">

**آن سه بایت مهم‌ترین جزئیاتِ این بخش‌اند.** `utf-8-sig` یعنی «`utf-8` به‌علاوهٔ یک علامتِ سه‌بایتی در ابتدای فایل». Excel بدونِ آن علامت، فایلِ `CSV` را با کدگذاریِ محلیِ ویندوز می‌خواند و **هر حرفِ فارسی به یک مشتِ نویسهٔ بی‌معنی تبدیل می‌شود** — همان چیزی که هر کسی یک بار دیده و فکر کرده داده خراب شده. داده سالم است؛ فقط سه بایت کم داشت.

`WORK` همان پوشهٔ موقتی است که سلولِ راه‌اندازی ساخت. **در Colab به‌جایش `Path("/content")` بگذار** تا فایل‌ها در نوارِ کناریِ Colab دیده شوند و بتوانی با یک کلیک برشان داری. و برای دانلودِ مستقیم:

</div>

```python
try:
    from google.colab import files
    files.download(str(csv_path))
except ImportError:
    print("این‌جا Colab نیست، پس فایل‌ها فقط روی دیسکِ همین اجرا ماندند.")
```

```text
این‌جا Colab نیست، پس فایل‌ها فقط روی دیسکِ همین اجرا ماندند.
```

<div dir="rtl">

**در Colab این خط چیزی چاپ نمی‌کند و به‌جایش پنجرهٔ دانلودِ مرورگر را باز می‌کند**؛ بیرون از Colab کتابخانهٔ `google.colab` وجود ندارد و همان پیامِ بالا را می‌بینی. راهِ سومی هم هست که برای فایل‌های بزرگ‌تر بهتر است: `drive.mount` که Google Drive تو را به runtime وصل می‌کند و بعد از آن هر فایلی که آنجا بنویسی می‌ماند — **ولی اجرایش یک بار اجازهٔ صریح می‌خواهد، پس در این فصل اجرایش نکردیم.**

> ⚠️ **مواظب باش:** فایلِ `.db` را همیشه **بعد از** `con.commit()` کپی کن. اگر تراکنشی باز مانده باشد، نسخه‌ای که برمی‌داری آخرین نوشته‌هایت را ندارد — و بدترین شکلش این است که فایل سالم باز می‌شود و فقط چند سطر کم دارد.

> ✅ **چک کن:** دو اجرای اولِ بخشِ ۵ باید دقیقاً یک عدد بدهند. اگر ندادند، یا پرسشت به چیزی بیرون از پارامترهایش نگاه می‌کند — مثلِ `date('now')` — یا داده بینِ دو اجرا عوض شده. **در هر دو حالت، هر عددی که تا حالا با آن پرسش گزارش کرده‌ای بی‌اعتبار است.**

> 💡 **نکته:** `date('now')` در یک پرسشِ تحلیلی تقریباً همیشه اشتباه است. همان عددِ چسبیدهٔ بخشِ ۲ است، فقط برعکس: **به‌جای اینکه هیچ‌وقت عوض نشود، هر بار عوض می‌شود و هیچ‌کس نمی‌داند کِی.** تاریخِ برش را از بیرون بده.

> 📏 **اندازه بگیر:** **یک سطر یعنی چه؟** در `saved_queries` یک سطر یک **نسخه از یک تعریف** است، و در `analysis_runs` یک سطر یک **اجرا** — نه یک عدد. دو اجرای یکسان دو سطر دارند و همین عمدی است. **با کدام شمارشِ دوم سنجیدی؟** با سه‌تا: اجرای دومِ نسخهٔ ۲ که باید عیناً ۸۳۳ بدهد، جمعِ ستونِ `runs` در بخشِ ۶ که باید همان ۴ سطرِ دفتر شود، و ۴ سطرِ فایلِ `CSV` بخشِ ۸ که باید همان چهارتا باشند. **چه کسی از قلم افتاد؟** در نسخهٔ ۲، همان ۱۸ نفری که امانت گرفتند و بعد عضویتشان تمام شد — و این حذف حالا **در تعریفِ نسخه نوشته شده**، نه پنهان در یک `JOIN`.

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

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| reproducibility | ری‌پروداسیبیلیتی | بازتولیدپذیری؛ اینکه همان ورودی همیشه همان خروجی را بدهد |
| as-of date | ازآو دیت | تاریخِ برش؛ روزی که داده تا آن لحظه دیده شده |
| hard-coded value | هاردکد ولیو | مقداری که داخلِ کد چسبیده و از بیرون قابلِ تغییر نیست |
| query versioning | کوئری ورژنینگ | نسخه‌دار کردنِ پرسش، طوری که نسخهٔ قدیمی دست نخورد |
| audit log | آدیت لاگ | دفترِ ثبت؛ سطری برای هر اجرا با همهٔ ورودی‌هایش |
| view | ویو | پرسشِ نام‌داری که در خودِ اسکیما ذخیره می‌شود و سطری نگه نمی‌دارد |
| byte order mark | بایت اوردر مارک | همان سه بایتِ ابتدای فایل که `utf-8-sig` اضافه می‌کند |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا نسخهٔ ۱ و نسخهٔ ۲ با همان تاریخِ برش دو عدد دادند؟

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

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

## در فصل بعد

ترمِ ۶ و کلِ آوند با یک پروژه تمام می‌شود که هر هشت فصلِ این ترم را با هم به کار می‌گیرد — و ترمِ ۵ را هم.

یک پرسشِ واقعی از مدیرِ کتابخانه می‌آید، و از آن تا یک توصیهٔ قابلِ اجرا می‌رویم: **اسکیما را می‌خوانیم، سنجه را تعریف می‌کنیم، پرسشِ کند را با `EXPLAIN QUERY PLAN` و یک `index` سریع می‌کنیم، عدد را با آزمونِ سه‌گانه می‌سنجیم، مقایسه را منصفانه می‌کنیم، و یک صفحه تحویل می‌دهیم که پایینش نوشته: چه چیزی نظرم را عوض می‌کند.**

</div>

---
Source: https://yaadestan.com/courses/avand/lessons/t6/s08-repeatable-analysis (یادستان, Yaadestan)
