التنفيذ المؤجّل والمتدفق في Polars: متى تستخدم collect أو sink_parquet؟

لنتصور مطوّرًا يعمل على جدول مصدر واحد. يحتاج محلّل إلى ملخص صغير للفئات في Python، بينما يحتاج مسار تجهيز مجموعة بيانات إلى حفظ سجلات مختارة على القرص. المدخلات واحدة، لكن المهمتين مختلفتان. ينبغي أن تحدد الوجهة اختيار طريقة التنفيذ.

عند استخدام التنفيذ المؤجّل والمتدفق في Polars، ابدأ بمسح يستند إلى ملف وافحص الاستعلام. استخدم collect عندما يحتاج المستهلك إلى DataFrame ذي حجم محدود عمدًا، أو sink_parquet عندما تكون وجهة النتيجة هي القرص. يوضح دليل المصادر ووجهات الإخراج كيف ترتبط القراءة والمعالجة بالكتابة. لا يضمن التنفيذ المتدفق حدًا أقصى لاستخدام الذاكرة.

يعتمد هذا الدليل على الوثائق. مثال الملف المحلي افتراضي ولم يُنفَّذ، ولا توجد نتائج لاختبارات أداء.

ابدأ بمسح، لا بإطار بيانات محمّل بالفعل

ما الذي يتيح scan_parquet وscan_csv للمُحسِّن رؤيته؟

يصف LazyFrame المستند إلى ملف العمل قبل تجسيد النتيجة في الذاكرة. باستخدام scan_parquet أو scan_csv، يستطيع المُحسِّن نقل المرشحات واختيارات الأعمدة المؤهلة باتجاه قارئ البيانات. يوضح دليل الواجهة البرمجية للتنفيذ المؤجّل دفع شروط الترشيح واختيار الأعمدة إلى المصدر من خلال عملية تجميع مرشّحة.

يُبقي اختيار الأعمدة على الأعمدة التي يحتاجها الاستعلام. وينقل دفع شروط الترشيح شروط الصفوف المناسبة إلى موضع أقرب إلى المصدر. لا يتيح أيٌّ منهما تغيير ما يتلقاه المستهلك. إذا كانت عملية لاحقة تحتاج إلى معرّف، فإن إزالته تغيّر عقد البيانات. وينطبق الأمر نفسه على إسقاط القيم المفقودة التي تحمل معنى.

لا يمكن نقل كل تعبير إلى قارئ البيانات. وقد لا تحقق صيغتا CSV وParquet الوفر نفسه في عمليات الإدخال والإخراج. افحص الخطة، ثم قِس عمليات الإدخال والإخراج قبل الادعاء بتحقيق وفر.

لماذا لا يستطيع read().lazy() التراجع عن قراءة فورية؟

عندما يصل read_parquet(...).lazy() إلى .lazy()، يكون التحميل الفوري قد حدث بالفعل. يمكن أن تكون التحويلات اللاحقة مؤجّلة، لكن لا يمكن التراجع عن القراءة الأولية. توصي وثائق المصادر ووجهات الإخراج باستخدام scan_* بدلًا من read_* لمسارات العمل التي يُراد فيها تنفيذ العمليات على الملفات بصورة مؤجّلة.

لا يعني ذلك أن استخدام DataFrame محمّل فورًا خطأ. يصف دليل الواجهة البرمجية للتنفيذ المؤجّل فائدته أثناء الاستكشاف، حيث تساعد النتائج الوسيطة على فهم البيانات. اختره لهذا السبب، بدلًا من إعادة كتابة عمل استكشافي مفيد لمجرد تسميته تنفيذًا متدفقًا.

يفترض المثال هنا وجود ملف محلي افتراضي اسمه events.parquet. نوع العمودين record_id وcategory هو String، ونوع value هو Float64. لم يُفحص أي مخطط للبيانات. يحتاج المستهلكان المحتملان إما إلى سجلات مختارة على مستوى الصفوف، أو إلى ملخص للفئات مشتق منها.

اقرأ الخطة المنطقية والخطة المادية للتنفيذ المتدفق كلًّا على حدة

استخدم explain لفحص التحسين

قارن query.explain(optimized=False) مع query.explain(optimized=True). يوضح دليل خطة الاستعلام انتقال مرشح إلى عملية المسح بعد التحسين. تصف هذه العروض العمل المخطط له. وهي لا تقيس زمن التنفيذ أو ذروة استخدام الذاكرة، ولا تثبت صحة النتائج.

تحقق من ظهور اختيار الأعمدة وترشيح الصفوف المتوقعين. إذا غاب أيٌّ منهما، فابحث في السبب قبل تفسير قياسات الموارد. ثم تحقق من المرشح نفسه وفقًا لقاعدة العمل: قد يختار المرشح الصفوف الخطأ حتى عندما يكون في الموضع الصحيح.

استخدم الرسم المادي لاستقصاء العمليات الحساسة لاستخدام الذاكرة

يوثّق دليل التنفيذ المتدفق الاستدعاء query.show_graph(plan_stage="physical", engine="streaming") ومفتاحًا للعمليات التي قد تستهلك قدرًا كبيرًا من الذاكرة. يتطلب عرض الرسم إتاحة Graphviz ضمن PATH، كما يشرح دليل خطة الاستعلام. في غيابه، يظل العرض النصي باستخدام explain مفيدًا، لكنه لا يوفّر العرض المادي نفسه.

يعمل التنفيذ المتدفق على دفعات. بعض العمليات غير قابلة بطبيعتها للتنفيذ المتدفق، وبعضها الآخر لا يملك بعد تطبيقًا يدعم ذلك، فيعود إلى التنفيذ داخل الذاكرة. استخدم الرسم المادي لتحديد مواضع هذه المخاوف. فهو لا يضمن حدًا لذروة الذاكرة المقيمة للعملية، أو RSS.

تحقق أيضًا من الإعدادات الافتراضية الخاصة بالإصدار. ينص مرجع collect المستقر الحالي على أن engine="auto" يتبع Config.set_engine_affinity أو POLARS_ENGINE_AFFINITY، ويستخدم التنفيذ المتدفق افتراضيًا في غير ذلك. قد تختلف الإصدارات الأقدم المثبتة. يعبّر تحديد engine="streaming" صراحةً عن قصدك، لكنه لا يثبت أن كل عملية تُنفَّذ بصورة متدفقة. سجّل الإصدار المثبت وإعداداته قبل الاعتماد على الوثائق الحالية.

اختر collect أو sink_parquet وفقًا للمخرجات التي تحتاجها

اسأل عمّا يحتاجه المستهلك التالي. لا يكفي حجم الملف المصدر وحده للإجابة.

نتيجة محدودة في الذاكرة

تقوم collect بتجسيد LazyFrame في DataFrame. يحتاج الكائن المُعاد إلى ذاكرة حتى إن كان العمل السابق يُنفَّذ بصورة متدفقة. لا يجعل التجميع وحده النتيجة صغيرة: عدد الفئات هو ما يحدد عدد صفوف الملخص المتبقية.

نتيجة محفوظة دون جمع المخرجات كاملةً

يصف مرجع sink_parquet التقييم المتدفق والكتابة بصيغة Parquet دون اشتراط حصول المستدعي أولًا على DataFrame النهائي كاملًا. ينفّذ الإعداد الافتراضي lazy=False عملية الإخراج. مع lazy=True، ينتظر التنفيذ استدعاء الجمع؛ ولا تنطبق وسيطتا engine وoptimizations الخاصتان بعملية الإخراج عند بناء تلك الخطة المؤجّلة. اختر إعدادات التنفيذ عند جمعها. خيار التأجيل موسوم بأنه غير مستقر.

افصل بين قواعد الرجوع الاحتياطي لنقطتي التنفيذ. يتبع مرجع الإخراج الحالي تفضيل المحرك عند الاختيار التلقائي، ويستخدم التنفيذ المتدفق في غير ذلك، ويصف الرجوع الاحتياطي من المحرك المختار إلى التنفيذ المتدفق. أما مرجع collect فيصف الرجوع الاحتياطي من المحرك المختار إلى التنفيذ داخل الذاكرة. تظل القيود على مستوى العمليات قائمة. ولا تضع إعدادات الضغط ومجموعات الصفوف ميزانية ثابتة للذاكرة.

يطرح سؤال المجتمع السابق عن DuckDB وPolars موضوع التقاط تغيّرات البيانات في PostgreSQL. اقرأه بوصفه سؤالًا عن المصطلحات، لا نصيحة معمارية متحقَّقًا منها. لا يوفّر التنفيذ المتدفق على دفعات هنا خدمة دائمة التشغيل لها مواضع متابعة ومعالجة لوقت الحدث وضمانات تسليم.

دليل Polars الذي يبدأ بالنتيجة

حدّد عقد النتيجة قبل اختيار التنفيذ

دليل Polars الذي يبدأ بالنتيجة هو قائمة تحقق تحريرية أصلية، وليس مكتبة أو تطبيقًا منشورًا جرى التحقق منه. ابدأ بتسمية المستهلك. اتفق على الأعمدة والأنواع المطلوبة، ثم احسم المرشحات ومعالجة القيم الخالية وأي متطلبات للترتيب. تمنحك هذه القرارات عناصر ملموسة للتحقق منها بعد التنفيذ.

يوضح الرسم اختيار الوجهة بصورة مفاهيمية. وهو ليس خطة مادية مرصودة من Polars.

امسح البيانات وقلّص نطاقها وافحصها

يفترض هذا المثال التوضيحي أن Polars متاح بالفعل، ويستخدم الواجهة البرمجية الموثقة في الإصدار المستقر الحالي. لم يُنفَّذ هذا المثال. لم تُفحص بيئة الإعداد أو محتويات مجموعة البيانات، ولا يُدَّعى وجود أي مخرجات مطبوعة. يُسقط المرشح الصفوف ذات القيم الخالية في value فقط لتوضيح سياسة معينة؛ وقد تحتاج مجموعة بياناتك إلى سياسة مختلفة.

import polars as pl

rows = (
    pl.scan_parquet("events.parquet")
    .select("record_id", "category", "value")
    .filter(pl.col("value").is_not_null())
)

planned_schema = rows.collect_schema()
unoptimized_plan = rows.explain(optimized=False)
optimized_plan = rows.explain(optimized=True)

يحدّد collect_schema المخطط المخطط له. قد يتطلب ذلك قراءة البيانات الوصفية من القرص أو إرسال طلبات بعيدة، لذا لا يكون تحديد المخطط بلا تكلفة بالضرورة. كما أنه لا يتحقق من كل صف وفقًا لقواعد مجال البيانات. قارن الأسماء والأنواع بالعقد، ثم افحص الخطة المنطقية، والرسم المادي حيث تسمح الأدوات بذلك. يوضح دليل مخططات البيانات سبب أهمية المخططات المعروفة أثناء التخطيط للتنفيذ المؤجّل.

اختر إحدى نقطتي التنفيذ التاليتين للمخرجات المطلوبة. إنهما بديلان لم يُنفَّذا، وليسا تسلسلًا من الخطوات. يفترض فرع الملخص أنك أثبتَّ بصورة مستقلة أن عدد الفئات يمكن التعامل معه. وعليك أيضًا أن تقرر معنى وجود قيمة خالية في الفئة.

ينتج البديل A ملخص الفئات المطلوب في Python.

summary = rows.group_by("category").agg(
    pl.col("value").mean().alias("mean_value")
)
result = summary.collect(engine="streaming")

يكتب البديل B السجلات المختارة المطلوبة على القرص.

rows.sink_parquet("events-selected-candidate.parquet", engine="streaming")

تدعم الواجهة البرمجية لـ collect والواجهة البرمجية للإخراج هذين الوصفين لنقطتي التنفيذ. ستقارن مقارنة أزمنتهما بين مهمتين مختلفتين: إحداهما تعيد ملخصًا للفئات، بينما تصدّر الأخرى سجلات على مستوى الصفوف. وهذا ليس اختبارًا لأداء المحرك.

اقترح فحصًا قابلًا للمقارنة، ثم تحقق من الوجهة

تحافظ المقارنة المفيدة على ثبات المخرجات. استخدم لقطة المدخلات نفسها وإصدار Polars نفسه، مع إعدادات وظروف جهاز وتخزين قابلة للمقارنة. يناقش دليل Optijara حول إبقاء بروتوكولات اختبارات الأداء مرتبطة بالنتائج هذا الانضباط في مجال آخر. أبقِ البروتوكول المقترح منفصلًا عن النتائج التي تسجلها لاحقًا.

لم يُجرَ أيٌّ من هذه القياسات هنا. بالنسبة إلى مخرجات مرشحة محفوظة، تحقق من مخطط البيانات وأعداد الصفوف دون تحميل المخرجات كاملةً لمجرد التحقق منها. قارن القيم وفقًا لهوامش التسامح المتفق عليها، ولا تقارن الترتيب إلا حيث يتطلبه العقد.

إذا فشل التنفيذ، فتعامل مع الملفات الجزئية على أنها غير متحقَّق منها. ابحث في الخطأ والعمليات المعنية. استخدم وجهة جديدة للمخرجات المرشحة في المحاولة التالية، وتحقق منها قبل أي تسليم معتمد. وجود الملف ليس فحصًا لقبول النتيجة.

ما الذي تُخطئ الفرق في فهمه عن التنفيذ المؤجّل والمتدفق؟

الاختصار المغري هو التعامل مع التخطيط المؤجّل والتنفيذ المتدفق بوصفهما قرارًا واحدًا. إنهما منفصلان. لا تستطيع إضافة .lazy() بعد القراءة تغيير ذلك التحميل الذي اكتمل. ولا يلغي اختيار التنفيذ المتدفق DataFrame النهائي الذي تعيده collect.

قد يبدو الفحص أيضًا أكثر حسمًا مما هو عليه. تشرح الخطة العمل المقصود، ويقدّم مخطط البيانات المحدَّد أسماءً وأنواعًا. لا يجيب أيٌّ منهما عمّا إذا كان استخدام الذاكرة مقبولًا أو ما إذا كانت الصفوف تحتفظ بمعناها المقصود. أبقِ تلك الفحوص منفصلة عن الفحص الاستطلاعي.

تصبح مقارنة الأداء صعبة التفسير إذا غيّرت المرشحات أو اختيار الأعمدة بين التجارب. ويخلق تغيير لقطة البيانات أو الوجهة المشكلة نفسها. سجّل تغيّر المهمة بدلًا من إرجاع كل اختلاف إلى المحرك. وأبقِ متطلبات الاستيعاب المستمر خارج قرار اختيار نقطة تنفيذ للدفعات.

بالنسبة إلى الصفوف المستخرجة من ملفات PDF، تحقق من بقاء العناوين والوحدات مرتبطة بالقيم الصحيحة، واحتفظ بمراجع المصادر قبل التحويل الجدولي. يغطي دليل Optijara حول الحفاظ على معنى جداول PDF المستخرجة ومراجع مصادرها ذلك العمل السابق في المسار. وهو لا يثبت وجود تكامل مع Polars. لا تستطيع وجهة إخراج مختلفة استعادة معنى فُقد أثناء الاستخراج.

قيود ينبغي فحصها قبل تغيير مسار معالجة البيانات

المفاضلات المتعلقة بالذاكرة والإصدار والتخزين

حجم المدخلات ليس إلا جزءًا من مسألة الذاكرة. احتسب الحالة الوسيطة والنتيجة النهائية، وتحقق من العمليات التي يمكن تنفيذها بصورة متدفقة. تشرح وثائق التنفيذ المتدفق ونقاط التنفيذ هذه القيود. كما يتطلب التبنّي جهدًا في التطبيق، ويضيف عمليات إدخال وإخراج للتخزين أو تعقيدًا تشغيليًا. لا يُوعَد هنا بأي تحسن في زمن التنفيذ أو التكلفة.

يمثل استقصاء PythonSpeed لاستخدام الذاكرة مثالًا سابقًا ملموسًا على تحليل يختص بعبء عمل معين. تنطبق قياساته على مجموعة بياناته وإصداراته ومنصته. وهي ليست نتائج حالية عامة، ولا اختبارات أجرتها Optijara.

قبل استخدام الإعدادات الافتراضية أو المعلمات الاختيارية، تحقق من وثائق الإصدار المثبت لديك. يوسم مرجع الإخراج عدة خيارات بأنها غير مستقرة أو تجريبية. إذا أردت فهم أثر تغيير ما، فتجنب ضبط الضغط والترتيب في الوقت نفسه الذي تضبط فيه إعدادات التنفيذ.

لا يزال معنى البيانات وخصوصيتها بحاجة إلى مراجعة

أثناء الإعداد، حافظ على المعرّفات وحدود تقسيم البيانات. اجعل معالجة القيم الخالية صريحة، واحتفظ بالترتيب حيث يتطلبه المستهلك. لا يثبت ملف Parquet صالح أن الأمثلة المقصودة قد بقيت سليمة. يشرح الدليل ذي الصلة حول الحفاظ على اختيار مجموعة البيانات وهويتها الزمنية تلك الفحوص لمجموعات البيانات التي تعتمد على الزمن؛ ولا يدّعي وجود تكامل مع Polars.

استخدم لقطات مدخلات مأذونًا بها. حدّد من يمكنه الوصول إلى المخرجات المرشحة ومدة الاحتفاظ بها. لا تحسم الوجهة المحلية التزامات الخصوصية، حتى إن نُفِّذ الاستعلام بنجاح.

اختر الوجهة قبل استدعاء collect

ابدأ بالنتيجة التي يحتاجها المستهلك. استخدم المسح للعمل المستند إلى الملفات الذي يُراد تنفيذه بصورة مؤجّلة، ثم افحص الخطط المنطقية والمادية وفقًا للغرض المختلف لكل منها. تحقق من نقطة التنفيذ المختارة واحتفظ بأدلة القياسات الفعلية قبل تغيير مسار معالجة تشغيلي. للمساعدة في تخطيط سير عمل للذكاء الاصطناعي، تقدم Optijara استشارات في الذكاء الاصطناعي.