حلقه

نود Loop چیست؟

نود Loop (که قبلاً Split In Batches نام داشت) امکان پردازش آیتم‌ها به صورت دسته‌ای را فراهم می‌کند.

چرا Loop نیاز است؟

1. 1Rate Limiting: بسیاری از APIها محدودیت تعداد درخواست دارند
2. 2Memory Management: پردازش همزمان هزاران آیتم حافظه زیادی مصرف می‌کند
3. 3Sequential Processing: گاهی آیتم‌ها باید به ترتیب پردازش شوند
4. 4Error Recovery: اگر یک batch خطا بدهد، بقیه ادامه دارند

نحوه کار:

1. 1آیتم‌های ورودی به دسته‌هایی (batches) تقسیم می‌شوند
2. 2هر batch به ترتیب پردازش می‌شود
3. 3خروجی هر batch جمع‌آوری می‌شود
4. 4پس از اتمام همه batchها، نتیجه نهایی ارسال می‌شود

تفاوت با پردازش عادی:

• بدون Loop: همه آیتم‌ها همزمان پردازش (Parallel)
• با Loop: آیتم‌ها در دسته‌ها پردازش (Sequential Batches)

الگوی Loop + Wait:

ترکیب Loop با Wait node تأخیر بین batchها ایجاد می‌کند — ایده‌آل برای Rate Limiting.

موارد استفاده رایج نود Loop

۱. ارسال ایمیل‌های دسته‌ای

ارسال 1000 ایمیل بازاریابی: Loop با batch size 50 و Wait 10 ثانیه بین هر دسته. جلوگیری از Block شدن توسط SMTP.

۲. همگام‌سازی دیتابیس

بروزرسانی 10,000 رکورد در دیتابیس: دسته‌های 100 تایی. جلوگیری از timeout و مصرف حافظه.

۳. دریافت همه صفحات API (Pagination)

API که 100 آیتم در هر صفحه برمی‌گرداند: Loop تا page_info.has_next_page === false. جمع‌آوری همه نتایج.

۴. Rate Limiting

API با محدودیت 60 req/min: Loop با batch size 1 و Wait 1 ثانیه. یا batch size 10 و Wait 10 ثانیه.

۵. پردازش فایل‌های حجیم

خواندن CSV 50,000 ردیفی: پردازش 500 ردیف در هر batch. ذخیره در دیتابیس بدون مشکل حافظه.

۶. Retry خودکار

اتصال به API ناپایدار: Loop 3 بار + IF (موفق؟) + Wait 5 ثانیه. پس از 3 شکست، خطا ثبت شود.

۷. Bulk Create/Update

ایجاد 500 Contact در HubSpot: دسته‌های 10 تایی. HubSpot rate limit 100/10s. Wait 2 ثانیه بین دسته‌ها.

۸. Data Migration

انتقال داده از سیستم قدیمی به جدید: خواندن batch > Transform > نوشتن batch. لاگ هر batch.

۹. Image Processing

پردازش 200 تصویر: Resize/Compress هر batch 5 تایی. جلوگیری از مصرف حافظه بیش از حد.

۱۰. Polling Pattern

بررسی وضعیت هر 30 ثانیه تا تغییر وضعیت: Loop Until status === "completed" + Wait 30s. حداکثر 20 تکرار.

۱۱. Multi-API Sync

همگام‌سازی داده بین 3 سیستم: برای هر آیتم، 3 API call. Loop جلوی Rate Limit هر 3 سیستم را می‌گیرد.

نکات و ترفندهای نود Loop

انتخاب Batch Size بهینه

• API با Rate Limit: batch size = 1, delay = (60/rate_limit) ثانیه
• پردازش سبک: batch size = 100-500
• پردازش سنگین (تصویر، ویدیو): batch size = 5-10
• دیتابیس: batch size = 100-1000 (بسته به Query)
• ایمیل: batch size = 20-50 با delay 5-10 ثانیه

الگوی Rate Limiting

Loop + Wait ساده‌ترین الگو:

1. 1Loop: batch size = 1
2. 2HTTP Request: API call
3. 3Wait: delay بر اساس rate limit
4. 4بازگشت به Loop

Pagination Pattern

1. 1Loop Until: has_next === false
2. 2HTTP Request: URL = next_page_url
3. 3Set: ذخیره نتایج + next_page_url
4. 4IF: has_next? → بازگشت به Loop

Error Handling در Loop

• Continue on Fail: آیتم خراب Skip شود
• Retry pattern: 3 بار تلاش با delay
• لاگ errors: آیتم‌های ناموفق در آرایه جدا ذخیره شوند
• Alert: اگر error rate > 10%، اعلان بده

Performance Tips

• هرچه batch size بزرگ‌تر = سریع‌تر ولی مصرف حافظه بیشتر
• Wait node فقط وقتی Rate Limit لازم است
• داده‌های بزرگ (Binary) را قبل از Loop فیلتر کنید
• Parallel processing (بدون Loop) وقتی Rate Limit نیست

کِی از Loop استفاده نکنید

• وقتی همه آیتم‌ها می‌توانند همزمان پردازش شوند
• وقتی API rate limit ندارد
• وقتی تعداد آیتم‌ها کم است (< 50)
• n8n خودش Items را به صورت Parallel پردازش می‌کند

ترکیب با سایر نودها

• Wait: Rate limiting بین batches
• IF: شرط توقف Loop
• Merge: جمع‌آوری نتایج همه batches
• Error Trigger: اعلان خطا در batch
• Code: پردازش پیچیده روی هر batch
• Set: ذخیره شمارنده و وضعیت

Static Data برای State

از $workflow.staticData برای ذخیره:

• شمارنده کل پردازش‌شده
• آخرین cursor/page
• آیتم‌های ناموفق
• زمان آخرین اجرا

عیب‌یابی نود Loop

۱. حلقه بی‌نهایت (Infinite Loop)

مشکل: Loop هرگز متوقف نمی‌شود راه‌حل: حتماً Max Iterations تنظیم کنید (Safety limit). شرط توقف را بررسی کنید. از n8n execution timeout استفاده کنید.

۲. مصرف حافظه بالا

مشکل: Workflow با آیتم‌های زیاد Crash می‌کند راه‌حل: Batch size کوچک‌تر کنید. آیتم‌های پردازش‌شده را از حافظه حذف کنید. از Binary data حداقلی استفاده کنید.

۳. تعداد آیتم‌های خروجی اشتباه

مشکل: خروجی Loop فقط آخرین batch را دارد راه‌حل: خروجی Loop باید به نودهای داخل حلقه وصل شود نه بیرون. از Merge نود برای جمع‌آوری نتایج.

۴. Context از بین می‌رود

**مشکل:** متغیرها بین iterationها حفظ نمی‌شوند **راه‌حل:** از Static Data برای ذخیره وضعیت بین iterationها استفاده کنید. $workflow.staticData را ست کنید.

۵. Batch Size بهینه

مشکل: نمی‌دانم batch size چقدر باشد راه‌حل: برای API rate limiting: محاسبه limit/time. برای حافظه: 50-200 آیتم. برای دیتابیس: 100-500 آیتم.

۶. Error در یک Batch کل Loop را متوقف می‌کند

مشکل: یک آیتم خراب کل پردازش را Stop می‌کند راه‌حل: Error Handling با Continue on Fail فعال کنید. از Try/Catch pattern استفاده کنید.

۷. Loop داخل Loop (Nested)

مشکل: حلقه تودرتو پیچیده و کند راه‌حل: تا حد ممکن از Nested loops اجتناب کنید. داده‌ها را Flatten کنید. از Sub-workflow استفاده کنید.

۸. Execution Timeout

مشکل: Workflow به timeout می‌رسد راه‌حل: n8n execution timeout را افزایش دهید. تعداد آیتم‌ها یا تأخیر را بهینه کنید.