Software Engineer Encyclopedia
0%
Domain 04 · Database Engineering & Data Management · Pillar

Elasticsearch وOpenSearch: inverted index وanalyzers وBM25 والـ hybrid search

Elasticsearch and OpenSearch for Engineers

إزاي search engine بيلاقي مستند في مليارات في milliseconds: الـ inverted index، الـ analyzers (وتحديات العربي)، BM25 بالحساب، الـ mappings والـ shards، الـ relevance tuning، الـ aggregations، وإزاي ده بيتجمع مع الـ vectors في hybrid search للـ RAG — مع .NET client ومقارنة بـ PostgreSQL full-text.

  • Intermediate
  • ~10 min read
  • 14 sections
  • 7 code examples
  • 2 diagrams
  • 6 questions
  • Priority L2 · Essential
  • Elasticsearch 8.x/9.x · OpenSearch 2.x/3.x (Apache-2.0 fork) · Elastic.Clients.Elasticsearch / OpenSearch.Client for .NET — APIs evolve between majors, reviewed 2026-11-18

بعد الدرس ده هتقدر

  • تشرح الـ inverted index وليه البحث بالكلمة O(عدد المستندات اللي فيها الكلمة) مش O(كل المستندات)
  • تصمم analyzer مناسب للعربي والإنجليزي (normalization، stemming، synonyms)
  • تحسب BM25 لمثال صغير وتفهم k1 وb وIDF
  • تصمم mapping صح (text مقابل keyword، multi-fields) وتختار عدد الـ shards
  • تبني hybrid search (BM25 + kNN vectors) مع RRF أو weighted scoring
  • تقرر بين Elasticsearch/OpenSearch وPostgreSQL full-text + pgvector وAzure AI Search

المتطلبات قبل ما تبدأ

01

ليه search engine منفصل؟ وإمتى لأ؟

When you need a search engine
Basics

WHERE Title LIKE '%فاتورة%' بيعمل scan لكل الصفوف، ما بيفهمش إن «فواتير» و«الفاتورة» نفس الكلمة، وما بيرتبش النتايج حسب الأهمية. الـ search engines (Elasticsearch، OpenSearch، وكلهم مبنيين على Apache Lucene) بتحل التلاتة: index مخصص للنص، تحليل لغوي، وترتيب بالـ relevance.

الاحتياجPostgreSQL FTS + pgvectorElasticsearch / OpenSearch
بحث بسيط في كام مليون مستند جوه نفس الـ DBكافي غالبًا، transactions و ACL في نفس الـ queryزيادة تشغيلية
Relevance tuning متقدم، synonyms، typo tolerance، highlighting، facetsمحدودقوي جدًا
Logs/observability ضخمةمش مناسبالاستخدام الأصلي (ELK)
Hybrid search على ملايين chunks مع filtersممكن لحد حجم معينمدمج (kNN + BM25 + RRF)
Consistency مع البياناتفوري (نفس الـ transaction)near-real-time (refresh ~1s) + محتاج sync pipeline

OpenSearch مقابل Elasticsearch: OpenSearch fork من Elasticsearch 7.10 (2021) تحت Apache-2.0 وبقى مشروع مستقل؛ الـ APIs الأساسية متشابهة جدًا لكن اتباعدوا في features (خصوصًا الـ vector/AI). Elasticsearch رجّع خيار AGPL مع licenses تانية. القرار غالبًا: الـ cloud اللي انت عليه (AWS OpenSearch Service، Elastic Cloud)، الـ license، والـ features المحتاجها.

02

الـ inverted index من جوه

The inverted index
Deep dive
doc1: "إلغاء الفاتورة الشهرية"doc2: "Monthly invoice cancelled"doc3: "فواتير شهر مارس"Analyzernormalize · stemInverted indexالغاء → [doc1]فاتور → [doc1, doc3]شهر → [doc1, doc3]invoic → [doc2]month → [doc2]cancel → [doc2]query "فواتير" → analyzed to "فاتور" → posting list [doc1, doc3] → score with BM25
Analysis turns text into terms; the inverted index maps each term to a posting list of documents (and positions)
  • Posting list لكل term: ids المستندات (مضغوطة ومرتبة)، وعدد مرات الظهور (term frequency)، والمواقع (لـ phrase queries و highlighting).
  • AND/OR = تقاطع/اتحاد posting lists مرتبة — سريع جدًا حتى مع ملايين المستندات.
  • Segments: Lucene بيكتب الـ index في segments مش بتتغير (immutable)، والحذف بيعلّم bit، والـ merges بتدمج segments — نفس فكر الـ LSM من Storage Internals. الـ refresh (افتراضيًا كل ثانية) بيفتح segment جديد للبحث ← «near real-time».
  • Doc values: تخزين عمودي جنب الـ inverted index للـ sorting والـ aggregations على keyword/number fields.
03

الـ analyzers: الجزء اللي بيحدد جودة البحث (خصوصًا العربي)

Text analysis
Deep dive

Analyzer = character filters ← tokenizer ← token filters. نفس الـ analyzer لازم يتطبق وقت الـ indexing ووقت الـ query (أو analyzers متوافقة)، وإلا «فواتير» في البحث مش هتلاقي «الفاتورة» في المستند.

Consoleindex settings: Arabic + English analysis with a shared normalizer (Dev Tools console format)
PUT /docs-v1
{
  "settings": {
    "analysis": {
      "filter": {
        "ar_stop": { "type": "stop", "stopwords": "_arabic_" },
        "ar_stem": { "type": "stemmer", "language": "arabic" },
        "en_stem": { "type": "stemmer", "language": "light_english" },
        "domain_synonyms": { "type": "synonym_graph", "synonyms": ["فاتورة, invoice", "اشتراك, subscription, plan"] }
      },
      "analyzer": {
        "ar_custom": {
          "tokenizer": "standard",
          "filter": ["lowercase", "decimal_digit", "arabic_normalization", "ar_stop", "ar_stem"]
        },
        "ar_search": {
          "tokenizer": "standard",
          "filter": ["lowercase", "decimal_digit", "arabic_normalization", "domain_synonyms", "ar_stop", "ar_stem"]
        },
        "en_custom": { "tokenizer": "standard", "filter": ["lowercase", "stop", "en_stem"] }
      }
    }
  },
  "mappings": {
    "properties": {
      "tenant_id": { "type": "keyword" },
      "title":     { "type": "text", "analyzer": "ar_custom", "search_analyzer": "ar_search",
                     "fields": { "en": { "type": "text", "analyzer": "en_custom" }, "raw": { "type": "keyword" } } },
      "body":      { "type": "text", "analyzer": "ar_custom", "search_analyzer": "ar_search", "fields": { "en": { "type": "text", "analyzer": "en_custom" } } },
      "updated_at":{ "type": "date" },
      "embedding": { "type": "dense_vector", "dims": 1024, "index": true, "similarity": "cosine" }
    }
  }
}
Filterبيعمل إيه للعربيخطره
arabic_normalizationتوحيد أشكال الألف والهمزات والياء/الألف المقصورة والتاء المربوطة وشيل التشكيل والتطويلقليل — شبه إجباري
decimal_digit٣ ← 3قليل
Stemmer عربي (light)«الفواتير» و«فاتورة» تقرب لنفس الجذرover-stemming: كلمات مختلفة المعنى بتتجمع؛ اختبره على استعلاماتك
Synonymsربط المصطلحات العربي بالإنجليزي في المجالsynonyms غلط بتبوّظ الـ precision؛ خليها في search time بس عشان تعدلها من غير reindex
Consoledebug what the analyzer produces (Dev Tools console format)
POST /docs-v1/_analyze
{ "analyzer": "ar_search", "text": "إلغاء الفواتير الشهريّة" }
// inspect the tokens: if the output surprises you, the search results will too

العامية المصرية والـ code-switching (فرانكو، «الانفويس») بيحتاجوا synonyms ومراقبة لاستعلامات المستخدمين الفعلية (zero-result queries). وده بالظبط ليه الـ hybrid search مفيد: الـ embeddings بتلقط المعنى اللي الـ analyzer بيفوته.

04

BM25 بالحساب

BM25 by hand
Deep dive

BM25 بيدّي score لكل (query term، مستند) ويجمعهم:

TextBM25 for one term t in document d
score(t, d) = IDF(t) × tf × (k1 + 1) / ( tf + k1 × (1 − b + b × |d| / avgdl) )

IDF(t) = ln( 1 + (N − n_t + 0.5) / (n_t + 0.5) )     N = docs in index, n_t = docs containing t
tf     = occurrences of t in d,  |d| = length of d,  avgdl = average document length
k1 ≈ 1.2  (term-frequency saturation),  b ≈ 0.75  (length normalisation)
Pythonbm25_toy.py — tiny worked example
import math
docs = {"d1": "invoice cancel invoice".split(), "d2": "invoice due date reminder".split(), "d3": "cancel subscription plan".split()}
N, avgdl, k1, b = len(docs), sum(len(d) for d in docs.values()) / len(docs), 1.2, 0.75

def idf(term):
    n = sum(term in d for d in docs.values())
    return math.log(1 + (N - n + 0.5) / (n + 0.5))

def bm25(query, d):
    s = 0.0
    for t in query.split():
        tf = d.count(t)
        s += idf(t) * tf * (k1 + 1) / (tf + k1 * (1 - b + b * len(d) / avgdl)) if tf else 0.0
    return round(s, 3)

for name, d in docs.items():
    print(name, bm25("cancel invoice", d))
# d1 scores highest: both terms, "invoice" twice, short document
  • IDF: كلمة نادرة (موجودة في مستندات قليلة) بتساهم أكتر. «الفاتورة» في نظام فواتير IDF واطي؛ رقم فاتورة محدد IDF عالي.
  • Saturation (k1): الكلمة 10 مرات مش أهم 10 مرات من مرة — المساهمة بتتشبع.
  • Length normalisation (b): مستند طويل فيه الكلمة مرة أقل صلة من مستند قصير فيه نفس المرة.

ده نفس BM25 اللي في SQLite FTS5 وفي الـ keyword half بتاع الـ RAG. وعشان BM25 بيعتمد على إحصائيات الـ index (N، n_t، avgdl)، scores من indexes أو shards مختلفة مش قابلة للمقارنة المباشرة — سبب إضافي إن الـ hybrid بيستخدم RRF على الترتيب مش على الـ scores.

05

Mappings والـ shards والـ replicas

Modelling and scaling an index
Practical
القرارالقاعدة
text مقابل keywordtext = بيتحلل للبحث؛ keyword = قيمة كاملة للـ filters والـ sorting والـ aggregations (tenant_id، status، email). multi-field لو محتاج الاتنين.
Dynamic mappingاقفله أو خليه strict في الإنتاج؛ حقل JSON غريب ممكن يعمل «mapping explosion».
تغيير mappingأغلب التغييرات محتاجة reindex: اعمل index جديد (docs-v2)، reindex، وبدّل alias (docs ← v2) — التطبيق دايمًا بيكلم الـ alias.
Shardsالـ index بيتقسم primary shards (توزيع البيانات والـ query parallelism). shards صغيرة كتير = overhead؛ القاعدة العملية: shard بعشرات الـ GB، وما تبدأش بـ 50 shard لـ 2 GB بيانات.
Replicasنسخ للقراءة والـ availability؛ 1 replica على الأقل في الإنتاج.
Multi-tenancyindex مشترك + filter على tenant_id (keyword) + routing بالـ tenant للعملاء الكبار، أو index لكل tenant enterprise. الـ filter لازم يتحط في الكود server-side دايمًا.
06

الـ queries اللي هتستخدمها فعلًا

Query DSL essentials
Practical
Consolebool query: must (scored) vs filter (cached, not scored) (Dev Tools console format)
GET /docs/_search
{
  "query": {
    "bool": {
      "must": [
        { "multi_match": { "query": "إلغاء الاشتراك", "fields": ["title^3", "body", "title.en^2", "body.en"], "type": "best_fields" } }
      ],
      "filter": [
        { "term": { "tenant_id": "6f1c…" } },                       // isolation: always a filter, added by the server
        { "range": { "updated_at": { "gte": "now-1y" } } }
      ],
      "should": [ { "match_phrase": { "title": { "query": "إلغاء الاشتراك", "boost": 2 } } } ]
    }
  },
  "highlight": { "fields": { "body": {} } },
  "aggs": { "by_type": { "terms": { "field": "doc_type" } } },
  "size": 10
}
  • must مقابل filter: الـ filter ما بيأثرش على الـ score ونتيجته بتتعمل cache — حط فيه كل الشروط الـ yes/no (tenant، تاريخ، صلاحيات).
  • Boosting: العنوان أهم من المتن (title^3)، والـ phrase match بيرفع النتيجة.
  • Fuzziness: "fuzziness": "AUTO" للأخطاء الإملائية (edit distance — نفس درس DP)، بحذر مع العربي القصير.
  • Aggregations = facets («كام نتيجة في كل نوع مستند») على keyword fields.
07

Hybrid search: BM25 + vectors

Hybrid retrieval for RAG
Deep dive
Query+ tenant filterBM25 (top 50)codes, names, numberskNN vectors (top 50)meaning, paraphraseRRF fusionΣ 1/(60 + rank)Rerank top 30→ top 8 to LLM
Run lexical and vector retrieval in parallel, fuse by rank, then rerank the short list
ConsoleElasticsearch: retriever with RRF (8.x+ syntax; check your version) (Dev Tools console format)
GET /docs/_search
{
  "retriever": {
    "rrf": {
      "retrievers": [
        { "standard": { "query": { "bool": {
            "must": { "multi_match": { "query": "مدة الإجازة المرضية", "fields": ["title^2", "body"] } },
            "filter": { "term": { "tenant_id": "6f1c…" } } } } } },
        { "knn": { "field": "embedding", "query_vector": [0.012, -0.08, "…"], "k": 50, "num_candidates": 200,
                   "filter": { "term": { "tenant_id": "6f1c…" } } } }
      ],
      "rank_window_size": 50,
      "rank_constant": 60
    }
  },
  "size": 30
}

في OpenSearch نفس الفكرة بـ hybrid query + search pipeline بيعمل normalization (min-max) ودمج weighted، أو RRF في النسخ الأحدث. الفلتر جوه الـ kNN مهم: لو فلترت بعد الـ kNN، ممكن الـ top-50 كلهم من tenants تانيين وتطلع بنتايج قليلة أو صفر (post-filtering problem). التقييم: recall@k و MRR على الـ golden set لكل من BM25 لوحده، vectors لوحدها، والـ hybrid — والـ hybrid غالبًا بيكسب في الأسئلة اللي فيها أرقام وأسماء.

08

من ‎.NET: indexing pipeline والبحث

Using it from ASP.NET Core
Practical
C#SearchIndexer + SearchService (Elastic.Clients.Elasticsearch; shapes vary by client version)
public sealed record SearchDoc(string Id, string TenantId, string Title, string Body, DateTimeOffset UpdatedAt, float[] Embedding);

public sealed class SearchIndexer(ElasticsearchClient es, ILogger<SearchIndexer> log)
{
    public async Task IndexBatchAsync(IReadOnlyList<SearchDoc> docs, CancellationToken ct)
    {
        var resp = await es.BulkAsync(b => b.Index("docs").IndexMany(docs, (d, doc) => d.Id(doc.Id).Routing(doc.TenantId)), ct);
        if (resp.Errors)
            foreach (var item in resp.ItemsWithErrors)
                log.LogWarning("Index failed for {Id}: {Reason}", item.Id, item.Error?.Reason);   // retry or dead-letter
    }
}

public sealed class SearchService(ElasticsearchClient es, ITenantContext tenant)
{
    public async Task<IReadOnlyList<SearchDoc>> SearchAsync(string q, CancellationToken ct)
    {
        var resp = await es.SearchAsync<SearchDoc>(s => s
            .Indices("docs")
            .Routing(tenant.TenantId)
            .Query(qd => qd.Bool(bq => bq
                .Must(m => m.MultiMatch(mm => mm.Query(q).Fields(new[] { "title^3", "body", "title.en^2", "body.en" })))
                .Filter(f => f.Term(t => t.Field("tenant_id").Value(tenant.TenantId)))))      // isolation in code, never from the client
            .Size(10), ct);
        return resp.Documents.ToList();
    }
}

الـ sync مع الـ database: الـ search index مش مصدر الحقيقة. التغييرات بتتبعت عبر outbox/CDC لـ indexer (نفس الـ ingestion pipeline في Document Ingestion)، مع reindex كامل ممكن في أي وقت من الـ DB، و reconciliation دوري (عدد المستندات لكل tenant). والحذف لازم يوصل للـ index (right to erasure).

09

التشغيل: الحاجات اللي بتصحيك الساعة 3 الفجر

Operating a search cluster
Practical
العرضالسبب الشائعالعلاج
Cluster status yellowreplicas مش متوزعة (node واحد، أو node واقع)nodes كفاية، أو replicas=0 في dev فقط
Cluster redprimary shard مش متاحاسترجاع من snapshot؛ ده سبب الـ snapshots المنتظمة
Heap pressure / GC طويلaggregations على fields عالية الـ cardinality، fielddata على textkeyword/doc_values، حدود للـ aggregations، تقليل الـ shards
Indexing بطيءrefresh كل ثانية مع bulk ضخم، replicas أثناء الـ reindexrefresh_interval أطول أثناء الـ bulk، replicas=0 مؤقتًا في reindex ثم رجّعها
Disk watermarkالقرص قرب يتملي فبيوقف الكتابةretention (ILM/ISM)، rollover للـ indices الزمنية

لو مش عايز تشغّل cluster: الخدمات المُدارة (Elastic Cloud، Amazon OpenSearch Service، أو Azure AI Search كبديل مختلف) بتشيل جزء كبير من ده — بس الـ mapping والـ analyzers والـ relevance لسه شغلك.

10

قياس جودة البحث

Measuring search relevance
Deep dive
  • Judgment list: 100–300 query حقيقية مع المستندات الصح (بنفس فكرة الـ golden set)، وقيس nDCG@10 و recall@k مع كل تغيير analyzer/boost/synonym. Elasticsearch فيه _rank_eval API للغرض ده.
  • Online signals: zero-result rate، click-through على أول 3 نتايج، إعادة صياغة الـ query (refinement)، والوقت لحد أول click.
  • Zero-result queries أسبوعيًا: أغنى مصدر لـ synonyms ومشاكل الـ analyzer (العامية، الإملاء، الإنجليزي بحروف عربي).
11

أخطاء شائعة

Common mistakes
Basics
  • tenant_id كـ text بدل keyword ← الـ filter بيتحلل وبيطابق غلط.
  • الـ filters في must ← scores ملخبطة و cache أقل.
  • تغيير analyzer من غير reindex، أو analyzer مختلف وقت البحث عن وقت الـ indexing.
  • Shards كتير جدًا من البداية.
  • Post-filtering للـ kNN في multi-tenant.
  • اعتبار الـ search index مصدر حقيقة، أو نسيان الحذف منه.
  • Deep pagination بـ from/size (from=10000) بدل search_after.
12

اختبر فهمك

Knowledge check
Basics

المستخدم بيدور «فواتير» والمستند فيه «الفاتورة» وما ظهرش. أول حاجة تفحصها؟

ليه BM25 بيدّي وزن أقل لكلمة موجودة في 90% من المستندات؟

Hybrid search في نظام multi-tenant رجّع نتيجتين بس رغم إن الـ tenant عنده مستندات كتير. السبب الأرجح؟

13

تمارين محلولة

Worked exercises
Practical
1: صمّم بحث منتجات لمتجر عربي/إنجليزي فيه أكواد SKU

الحل: name: text بـ analyzer عربي + subfield إنجليزي + subfield keyword. sku: keyword (و ngram subfield لو محتاج بحث جزئي). category/brand: keyword للـ facets. price: scaled_float/number للـ range والـ sort. synonyms للمصطلحات (موبايل، جوال، phone). الـ query: bool بـ multi_match على الاسم + term على الـ sku (boost عالي لو مطابق بالظبط)، filters للسعر والفئة، aggregations للـ facets. قيس zero-result rate و click-through.

2: محتاجين نغير الـ analyzer العربي في الإنتاج من غير downtime

الحل: index جديد docs-v2 بالـ analyzer الجديد ← reindex من الـ DB (أو _reindex API) مع dual-write للتغييرات أثناء العملية ← eval على الـ golden queries للنسختين ← تبديل الـ alias ذريًا ← الاحتفاظ بـ v1 فترة للـ rollback ← حذفه.

14

أسئلة إنترفيو

Interview questions
Basics
(Junior) إيه الـ inverted index؟
خريطة من كل term للمستندات اللي فيها (posting list)، فالبحث بالكلمة بيقرأ قائمة المستندات اللي فيها مباشرة بدل ما يفحص كل المستندات.
(Mid) text مقابل keyword في Elasticsearch؟
text بيتحلل لـ terms للبحث النصي؛ keyword بيتخزن كقيمة واحدة كاملة للمطابقة الدقيقة والـ filters والـ sorting والـ aggregations.
(Senior) PostgreSQL ولا Elasticsearch للـ RAG بتاع SaaS عندنا؟
بالأرقام والمتطلبات: لو مليون–عشرة ملايين chunk والـ ACL معقد ومحتاجين consistency، PostgreSQL FTS + pgvector أبسط تشغيليًا. لو relevance tuning متقدم، synonyms، facets، حجم أكبر، أو فريق بحث مخصص، Elasticsearch/OpenSearch. القرار بـ eval على نفس الـ golden set (recall@k، latency p95، تكلفة التشغيل) مش بالتفضيل.
↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

محتويات الدرس