DuckDB

DuckDB هو نظام إدارة قواعد بيانات OLAP يعمل داخل العملية. يمكنك استخدام مسارات Hugging Face (hf://) للوصول إلى البيانات على Hub:

DuckDB CLI (واجهة سطر الأوامر) هو ملف تنفيذي واحد لا يعتمد على أي مكتبات خارجية. تتوفر أيضًا واجهات برمجة تطبيقات أخرى لتشغيل DuckDB، بما في ذلك Python وC++ وGo وJava وRust وغيرها. لمزيد من التفاصيل، قم بزيارة صفحة العملاء الخاصة بهم.

لتفاصيل التثبيت، قم بزيارة صفحة التثبيت.

إذا كنت تستخدم سطر الأوامر hf، يمكنك تنفيذ استعلامات DuckDB مباشرةً باستخدام hf datasets sql، على سبيل المثال hf datasets sql "FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3". يتم تكوين المصادقة للمجموعات البيانات المقيدة والخاصة تلقائيًا من رمز الدخول الخاص بك، ويعيد --format json إخراجًا قابلًا للقراءة آليًا.

بدءًا من الإصدار v0.10.3، تتضمن واجهة سطر الأوامر الخاصة بـ DuckDB دعمًا أصليًا للوصول إلى مجموعات البيانات على Hugging Face Hub عبر عناوين URL تستخدم مخطط hf://. فيما يلي بعض الميزات التي يمكنك الاستفادة منها باستخدام هذه الأداة القوية:

• استعلام مجموعات البيانات العامة ومجموعات البيانات الخاصة والمقيّدة التي تملكها
• تحليل مجموعات البيانات وتنفيذ عمليات SQL
• دمج مجموعات البيانات وتصديرها إلى صيغ مختلفة
• إجراء بحث تشابه متجهات على مجموعات بيانات التضمين
• تنفيذ البحث النصي الكامل على مجموعات البيانات

للاطلاع على قائمة كاملة بميزات DuckDB، قم بزيارة التوثيق الخاص بـ DuckDB.

لبدء سطر الأوامر، نفّذ الأمر التالي في مجلد التثبيت:

./duckdb

بناء رابط Hugging Face

للوصول إلى مجموعات بيانات Hugging Face، استخدم تنسيق الرابط التالي:

hf://datasets/{my-username}/{my-dataset}/{path_to_file} 

• my-username، اسم المستخدم أو المنظمة الخاصة بالبيانات، مثل ibm
• my-dataset، اسم مجموعة البيانات، على سبيل المثال: duorc
• path_to_parquet_file، مسار ملف parquet الذي يدعم أنماط glob، مثل **/*.parquet، للاستعلام عن جميع ملفات parquet

يمكنك الاستعلام عن ملفات Parquet المحوّلة تلقائيًا باستخدام فرع @~parquet، الذي يتوافق مع المراجعة refs/convert/parquet. لمزيد من التفاصيل، راجع التوثيق في https://huggingface.co/docs/datasets-server/en/parquet#conversion-to-parquet.

لإشارة إلى المراجعة refs/convert/parquet لمجموعة بيانات، استخدم الصياغة التالية:

تم النسخ

hf://datasets/{my-username}/{my-dataset}@~parquet/{path_to_file} 

إليك مثالًا على عنوان URL يتبع الصياغة المذكورة أعلاه:

تم النسخ

hf://datasets/ibm/duorc@~parquet/ParaphraseRC/test/0000.parquet

استعلام عن مجموعة بيانات

لنبدأ بعرض سريع لاستعلام جميع صفوف مجموعة البيانات:

FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3;

أو باستخدام صياغة SQL التقليدية:

SELECT * FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3;

في الأقسام التالية، سنغطي عمليات أكثر تعقيدًا يمكنك تنفيذها باستخدام DuckDB على مجموعات بيانات Hugging Face.

استعلام دلاء التخزين: تقرأ DuckDB 2.0 وما بعدها دلاء التخزين بشكل أصلي، من سطر الأوامر وكل عميل:

تم النسخ

SELECT * FROM 'hf://buckets/username/my-bucket/data.parquet' LIMIT 10;

لا تخضع الدلاء (Buckets) لإدارة الإصدارات، لذا لا ينطبق صياغة @revision على مسارات الدلاء. في DuckDB 1.x، قم بتسجيل نظام ملفات Hugging Face من Python بدلاً من ذلك: duckdb.register_filesystem(HfFileSystem()). راجع الاستعلام باستخدام DuckDB للتفاصيل.

حفظ مجموعة بيانات

استخدم صيغة COPY ... TO لحفظ مجموعة بيانات على Hugging Face.

1. قم بتثبيت الإضافة لـ DuckDB >=2.0:

SET allow_extension_repositories = 'allowed';
CREATE OR REPLACE EXTENSION REPOSITORY hf_repo
  WITH PREFIX 'https://hf.co/buckets/duckdb-extensions/builds/resolve';
INSTALL hf FROM hf_repo;
LOAD hf FROM hf_repo;

2. قم بالمصادقة باستخدام hf CLI أو مباشرةً في DuckDB:

• في سطر الأوامر:

  تم النسخ

  hf auth login

• في DuckDB:

  تم النسخ

  CREATE SECRET (TYPE HUGGINGFACE, TOKEN 'hf_...');

3. أنشئ مستودع مجموعة البيانات الخاصة بك إذا لم يكن موجودًا بالفعل:

• في سطر الأوامر:

  تم النسخ

  hf repos create username/my-dataset --repo-type dataset --private

• في DuckDB:

  تم النسخ

  FROM hf_create_repo('hf://datasets/username/my-dataset', private := true);

4. صدّر جدولك إلى Hugging Face، على سبيل المثال بتنسيق Parquet:

COPY tbl TO 'hf://datasets/username/my-dataset/out.parquet';

استخدم PARTITION_BY لتقسيم الجدول إلى ملفات متعددة بناءً على مفتاح التقسيم: COPY tbl TO 'hf://datasets/username/my-dataset/out-directory' (FORMAT parquet, PARTITION_BY (year, month));. تُوضع الملفات في الدليل الفرعي الصحيح بناءً على قيم مفتاح التقسيم، على سبيل المثال 'hf://datasets/username/my-dataset/out-directory/year=2026/month=1/data_1.parquet'.

بما أن مجموعات البيانات هي مستودعات git، فإن كل ملف جديد يُعدّ التزامًا في سجل مجموعة البيانات.