การแก้ปัญหา

ทุกรายการด้านล่างเป็นความล้มเหลวจริง: สิบเอ็ดรายการที่บันทึกไว้ใน README ของแต่ละส่วนใน แล็บเอง บวกกับอีกห้ารายการที่จับได้ระหว่างสร้างและทดสอบเวิร์กช็อปนี้ หาอาการของคุณ, อ่านสาเหตุ, ทำตามวิธีแก้ หากไม่มีอะไรที่นี่ตรงเลย ส่วน ## Common failures ในแทร็ก Instructor ครอบคลุมฝั่งผู้ดำเนินการของแต่ละโมดูลอย่างลึกกว่า และ Solutions Architect ของคุณเป็นจุดถัดไป

ชุดเครื่องมือและการตั้งค่า

dbt ล้มเหลวด้วย error การ import ของ mashumaro หรือติดตั้งไม่ได้

• อาการ - การติดตั้ง dbt-snowflake หรือ dbt-clickhouse ล้มเหลว หรือ dbt โผล่ error การ import ที่พูดถึง mashumaro ซึ่งดูไม่มีอะไรเกี่ยวกับเวอร์ชัน Python ของคุณ
• สาเหตุ - dbt-snowflake และ dbt-clickhouse ต้องใช้ Python 3.11, 3.12 หรือ 3.13 ทั้งคู่ Python 3.14+ ทำให้ dependency mashumaro ที่ใช้ร่วมกันพัง และความล้มเหลวมักโผล่ ขึ้นในโมดูลที่ไม่เกี่ยวข้องกันหลังจากที่ทำผิดไปแล้ว
• วิธีแก้ - ติดตั้ง 3.13 ไว้ข้าง Python ของระบบคุณ (ตัวอย่างเช่น brew install python@3.13) และสร้าง virtualenv ใหม่โดยระบุตัวแปลภาษานั้นอย่างชัดเจน: python3.13 -m venv .venv

สภาพแวดล้อมต้นทาง Snowflake

terraform init ล้มเหลวด้วย error ของ provider

• อาการ - terraform init ใน workshop_public/snowflake_migration_lab/01-setup-snowflake/ ล้มเหลวขณะแก้ปัญหา provider
• สาเหตุ - ไบนารี Terraform เก่า หรือไม่มีการเข้าถึงเครือข่ายไปยัง Terraform registry
• วิธีแก้ - ใช้ Terraform >= 1.6 และยืนยันว่าเข้าถึงอินเทอร์เน็ตไปยัง registry ได้

snowsql ปฏิเสธการเชื่อมต่อ

• อาการ - snowsql -a ${SNOWFLAKE_ORG}-${SNOWFLAKE_ACCOUNT} -u ${SNOWFLAKE_USER} ปฏิเสธการเชื่อมต่อ
• สาเหตุ - SNOWFLAKE_ORG หรือ SNOWFLAKE_ACCOUNT ผิด
• วิธีแก้ - ตรวจทานทั้งสองค่ากับบัญชีที่คุณสร้าง แล้วลองคำสั่ง snowsql เดิมอีกครั้ง

dbt run ล้มเหลวด้วย relation not found

• อาการ - dbt run ในโปรเจกต์ dbt ของส่วนที่ 1 รายงาน relation ที่ไม่มีอยู่
• สาเหตุ - โครงสร้างฐานข้อมูลไม่เคยถูกสร้าง
• วิธีแก้ - รัน ./setup.sh --skip-seed ก่อน และยืนยันว่า profiles.yml ชี้ไปที่ NYC_TAXI_DB

Superset แสดง connection refused

• อาการ - UI ของ Superset ในส่วนที่ 1 ปฏิเสธการเชื่อมต่อทันทีหลัง docker-compose up
• สาเหตุ - Superset ใช้เวลาราว 60 วินาทีในการเริ่มต้นระบบ
• วิธีแก้ - รอ 60 วินาทีแล้วลองใหม่ หากยังล้มเหลว ให้ตรวจ docker logs nyc_taxi_superset

การใส่ข้อมูลตั้งต้นใช้เวลานานกว่าที่คาด

• อาการ - ขั้นตอนใส่ข้อมูลตั้งต้นใน workshop_public/snowflake_migration_lab/01-setup-snowflake/ ดูเหมือนค้าง
• สาเหตุ - นี่เป็นพฤติกรรมปกติของ Snowflake ที่สเกลนี้ ไม่ใช่การค้าง คำสั่ง INSERT แบบ TABLE(GENERATOR) ที่ผลิต 50 ล้านแถวใช้เวลาราว 10-12 นาที และคำสั่ง UPDATE ที่ตามมาซึ่งใส่ค่าคอลัมน์ VARIANT TRIP_METADATA ให้ทั้ง 50 ล้านแถวใช้เวลาอีก 15-20 นาทีบน warehouse ขนาด SMALL
• วิธีแก้ - ปล่อยให้มันรัน ทั้งสองขั้นตอนไม่ต้องมีการโต้ตอบ ไม่มีอะไรให้ลองใหม่

การจัดเตรียม ClickHouse Cloud และการย้ายข้อมูล

การยืนยันตัวตนของ Terraform ล้มเหลวด้วย 401 Unauthorized

• อาการ - Terraform apply ใน workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ ล้มเหลวด้วย 401 Unauthorized
• สาเหตุ - CLICKHOUSE_TOKEN_KEY หรือ CLICKHOUSE_TOKEN_SECRET ผิด หรือคีย์ไม่มี scope ที่จำเป็น
• วิธีแก้ - สร้างคู่คีย์ใหม่จาก UI ของ ClickHouse Cloud ภายใต้ Settings -> API keys และตรวจให้แน่ใจว่ามี scope Admin

สคริปต์ย้ายข้อมูลล้มเหลวกลางการรัน

• อาการ - scripts/02_migrate_trips.py ตายกลางทางของการคัดลอก 50 ล้านแถว

• สาเหตุ - เครือข่ายหรือ warehouse สะดุดชั่วคราวระหว่างการถ่ายโอนที่ใช้เวลานาน

• วิธีแก้ - รันใหม่ด้วย --resume สคริปต์ทำ watermark บน max(pickup_at) ที่มีอยู่ ใน ClickHouse แล้ว และข้ามแถวที่มันโหลดไปแล้ว:

  python scripts/02_migrate_trips.py --resume

สคริปต์ย้ายข้อมูลมี error การเชื่อมต่อ

• อาการ - สคริปต์ย้ายข้อมูลเข้าถึง Snowflake หรือ ClickHouse ไม่ได้

• สาเหตุ - ตัวแปรสภาพแวดล้อมของ Snowflake หรือ ClickHouse หนึ่งตัวหรือมากกว่า ไม่ได้ถูกตั้งค่าใน shell ปัจจุบัน

• วิธีแก้ - ตรวจดูมัน แล้ว source ไฟล์สถานะใหม่ก่อนลองอีกครั้ง:

  echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD
  echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD

  รัน source .env && source .clickhouse_state ก่อน แล้วลองอีกครั้ง

dbt run ล้มเหลวด้วย Connection refused หรือ Unknown host

• อาการ - dbt run กับโปรเจกต์ ClickHouse แปลงชื่อโฮสต์หรือเชื่อมต่อไม่ได้
• สาเหตุ - CLICKHOUSE_HOST ไม่ได้ถูกตั้งค่าใน shell ปัจจุบัน
• วิธีแก้ - source .clickhouse_state จากไดเรกทอรีของโมดูล แล้วลอง dbt run อีกครั้ง

dbt ล้มเหลวด้วย Could not find profile named 'nyc_taxi_ch'

• อาการ - dbt debug หรือ dbt run ใน workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch ล้มเหลวทันทีด้วย error ว่าไม่พบโปรไฟล์
• สาเหตุ - โปรไฟล์ dbt ของ ClickHouse ไม่เคยถูกเพิ่มเข้า ~/.dbt/profiles.yml
• วิธีแก้ - เปิด workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch/profiles.yml.example และผสานบล็อก nyc_taxi_ch: ของมันเข้าไปใน ~/.dbt/profiles.yml ที่คุณมีอยู่เป็น โปรไฟล์ระดับบนสุดตัวที่สอง อย่าเขียนทับไฟล์ - การทำเช่นนั้นลบโปรไฟล์ nyc_taxi: จากโมดูล 01 และทำให้ลูปรีเฟรชในขั้นที่ 4 ของมันพัง ดู 03 จัดเตรียมและย้ายข้อมูล ซึ่งครอบคลุมขั้นตอนการผสานนี้อย่างครบถ้วน

dbt บน ClickHouse

analytics.agg_hourly_zone_trips ว่างเปล่าหลังการรัน dbt

• อาการ - หลัง dbt run ของโมดูล 04 analytics.agg_hourly_zone_trips มีศูนย์แถว และชาร์ตแดชบอร์ดใดที่หนุนด้วยมันแสดงว่าไม่มีข้อมูล
• สาเหตุ - นี่เป็นสิ่งที่คาดไว้ ไม่ใช่ความล้มเหลว ฟิลเตอร์ incremental ของโมเดลคือ WHERE pickup_at >= now() - INTERVAL 2 HOUR ซึ่งตรงกับแถวที่ producer การเดินทางสด เขียนเท่านั้น ทุกแถวที่สคริปต์ย้ายข้อมูลย้ายมาเป็นข้อมูลย้อนหลัง จึงไม่มีแถวใดตกอยู่ใน หน้าต่าง 2 ชั่วโมงนั้น
• วิธีแก้ - ไม่มีอะไรต้องแก้ ศูนย์เป็นค่าที่ถูกต้องในที่นี้ ตารางจะมีข้อมูลเมื่อ producer เขียนลง ClickHouse โดยตรงหลังขั้นตอนตัดสวิตช์ของ 05 เบนช์มาร์กและตัดสวิตช์

แดชบอร์ดและเบนช์มาร์ก

Superset แสดง 403 Forbidden

• อาการ - UI ของ Superset คืนค่า 403 Forbidden กลางทางของโมดูล
• สาเหตุ - คุกกี้ของเซสชันหมดอายุ
• วิธีแก้ - ออกจากระบบ, เข้าระบบใหม่ที่ http://localhost:8088 แล้วรัน bash superset/add_clickhouse_connection.sh อีกครั้ง

เบนช์มาร์กแสดง N/A สำหรับ Q7

• อาการ - CSV ที่ run_benchmark.sh ส่งออกมามี N/A แทนค่าความเร็วที่เพิ่มขึ้นของ คิวรีที่ 7
• สาเหตุ - สคริปต์เบนช์มาร์กเชื่อมต่อกับ ClickHouse ไม่ได้
• วิธีแก้ - ยืนยันว่า CLICKHOUSE_HOST ถูกตั้งค่าแล้ว (source .clickhouse_state) และเซอร์วิสทำงานอยู่ แล้วรันเบนช์มาร์กอีกครั้ง

แดชบอร์ด Superset ที่นำเข้ามาเชื่อมต่อกับ ClickHouse ไม่ได้

• อาการ - แดชบอร์ดที่นำเข้ามาใน Superset โหลดได้ แต่ชาร์ตของมันเข้าถึง ClickHouse ไม่ได้
• สาเหตุ - ไฟล์ ZIP ที่ export และ commit ไว้มีโฮสต์ถูกลบข้อมูลออกเป็น your-instance.clickhouse.cloud add_clickhouse_connection.sh แก้ URI จริงเข้าไป จาก .env ก่อนนำเข้า; การนำเข้าด้วยมือผ่าน UI ของ Superset ไม่ทำ
• วิธีแก้ - ใช้ bash superset/add_clickhouse_connection.sh แทนการนำเข้าด้วยมือ หรือแก้การเชื่อมต่อภายหลังให้ใช้ CLICKHOUSE_HOST และ credential จริงของคุณ

การตัดสวิตช์และความเท่าเทียม

การตรวจสอบความเท่าเทียมล้มเหลว หรือการตัดสวิตช์ดูเหมือนทำแถวหาย

• อาการ - การตรวจสอบความเท่าเทียมของจำนวนแถวในโมดูล 05 ล้มเหลว หรือการตัดสวิตช์ ดูเหมือนทำข้อมูลหาย

• สาเหตุ - รอบไล่ตามด้วย --resume ถูกข้าม producer ของ Snowflake เขียนอย่างต่อเนื่อง ตลอดโมดูล 01-05 ดังนั้นการย้ายข้อมูลในโมดูล 03 จับได้เพียงส่วนต้นของข้อมูล; ส่วนหาง มีอยู่แต่ใน Snowflake จนกว่าจะถูกไล่ตาม การหยุด producer ของ Snowflake เร็วเกินไป (ตัวอย่างเช่น หลังโมดูล 01 ทันที) ทำลายการสาธิตการตัดสวิตช์ของโมดูลนี้อย่างเงียบ ๆ เพราะจะไม่มีส่วนหางเหลือให้ไล่ตาม

• วิธีแก้ - รันรอบไล่ตามก่อนตรวจสอบความเท่าเทียม มันย้ายเฉพาะแถวในช่องว่างและใช้เวลา ระดับวินาทีถึงนาที ไม่ใช่ 40-50 นาทีอย่างเดิม:

  python scripts/02_migrate_trips.py --resume
  bash scripts/01_verify_migration.sh