عميل Elasticsearch لـ TypeScript: @elastic/elasticsearch

عميل Elasticsearch لـ TypeScript (@elastic/elasticsearch)

\n\n

في تطوير الويب الحديث، أصبح البحث النصي الكامل وتحليل البيانات جزءًا لا يتجزأ من العديد من التطبيقات. Elasticsearch هو نظام بحث موزع قوي مبني على Apache Lucene. للعمل معه من تطبيقات TypeScript (سواء على خادم Node.js أو في المتصفح)، يُستخدم العميل الرسمي @elastic/elasticsearch. في هذه المقالة، سنشرح بالتفصيل كيفية تثبيته وإعداده وإمكانياته الرئيسية.

\n\n

ما هو @elastic/elasticsearch؟

\n\n

@elastic/elasticsearch هو العميل الرسمي عالي الأداء لـ Elasticsearch، والمكتوب بلغة TypeScript. يوفر مجموعة كاملة من واجهات برمجة التطبيقات (API) للتفاعل مع مجموعة Elasticsearch، بما في ذلك:

\n\n

\n
• فهرسة وحذف المستندات
\n
• البحث النصي الكامل مع دعم الاستعلامات المعقدة
\n
• التجميعات لتحليل البيانات (التجميع، الإحصائيات)
\n
• إدارة الفهارس والتعيين (Mapping)
\n
• دعم تجمع الاتصالات، إعادة المحاولة، وتوزيع الحمل
\n

\n\n

بفضل الدعم الكامل لـ TypeScript، تحصل على الإكمال التلقائي، التحقق من الأنواع، والتوثيق مباشرة في بيئة التطوير المتكاملة (IDE).

\n\n

التثبيت

\n\n

للبدء، قم بتثبيت الحزمة عبر npm أو yarn:

\n\n

npm install @elastic/elasticsearch\n# أو\nyarn add @elastic/elasticsearch

\n\n

إذا كنت تستخدم TypeScript، فلا حاجة لتثبيت أنواع إضافية - فهي مدمجة بالفعل في الحزمة.

\n\n

الاتصال وإعداد العميل

\n\n

قم بإنشاء نسخة من العميل، مع تحديد عنوان URL لمجموعة Elasticsearch الخاصة بك:

\n\n

import { Client } from '@elastic/elasticsearch';\n\nconst client = new Client({\n  node: 'http://localhost:9200', // أو نقطة نهاية سحابية\n  auth: {\n    username: 'elastic',\n    password: 'changeme'\n  },\n  // للإنتاج، يُوصى باستخدام TLS\n  tls: {\n    rejectUnauthorized: false // للتطوير فقط!\n  }\n});

\n\n

للنشر السحابي (Elastic Cloud)، استخدم cloud.id و auth.apiKey:

\n\n

const client = new Client({\n  cloud: {\n    id: 'my-cluster:dXMtZWFzdD...'\n  },\n  auth: {\n    apiKey: 'base64EncodedApiKey'\n  }\n});

\n\n

العمليات الأساسية

\n\n

1. فهرسة مستند

\n\n

إضافة مستند جديد إلى الفهرس:

\n\n

interface Product {\n  id: number;\n  name: string;\n  description: string;\n  price: number;\n  tags: string[];\n}\n\nasync function indexProduct(product: Product) {\n  const response = await client.index({\n    index: 'products',\n    id: String(product.id),\n    body: product,\n    refresh: 'wait_for' // انتظار تحديث الفهرس\n  });\n  console.log('Document indexed:', response.result);\n}\n\nindexProduct({\n  id: 1,\n  name: 'لابتوب Lenovo ThinkPad',\n  description: 'لابتوب قوي للتطوير',\n  price: 1200,\n  tags: ['إلكترونيات', 'لابتوبات']\n});

\n\n

2. البحث عن المستندات

\n\n

بحث نصي كامل بسيط في حقل description:

\n\n

async function searchProducts(query: string) {\n  const response = await client.search({\n    index: 'products',\n    body: {\n      query: {\n        match: {\n          description: query\n        }\n      },\n      // التقسيم إلى صفحات\n      from: 0,\n      size: 10\n    }\n  });\n\n  const hits = response.hits.hits.map(hit => hit._source);\n  console.log('Found products:', hits);\n  return hits;\n}\n\nsearchProducts('لابتوب تطوير');

\n\n

3. التجميعات

\n\n

تجميع المنتجات حسب العلامات:

\n\n

async function aggregateByTags() {\n  const response = await client.search({\n    index: 'products',\n    body: {\n      size: 0, // لا نعيد المستندات نفسها\n      aggs: {\n        by_tag: {\n          terms: {\n            field: 'tags.keyword',\n            size: 20\n          }\n        }\n