ورشة عمل أساسيّة 1 — Elasticsearch : فهرس واحد ، مستند واحد ، طلب GET واحد

المدة

20 دقيقة

الوحدة

1/7

المتطلّبات

المختبر يعمل (etat يعرض (healthy) في كلّ مكان) ، Kibana Dev Tools مفتوح

ستبني

فهرسًا لك ، pratique-mini، بمستندين ستقرأهما ، تُكمّلهما ، تبحث فيهما ثم تحذفهما

التسليمة

استجابة GET pratique-mini/_doc/1 بعد الخطوة 5 ، بحقولها الثلاثة

كيف تقرأ هذه الصفحة. ثماني خطوات ، استعلام واحد في كلّ مرّة. لكلّ خطوة : الاستعلام الذي تكتبه ، الاستجابة الدقيقة للمختبر ، وما يجب النظر إليه فيها. اكتب كلّ استعلام بنفسك (بلا نسخ ولصق) : بكتابة PUT و GET و _doc تدخل الكلمات في ذهنك. فقرات « لفهم أعمق » اختياريّة ؛ افتحها إذا تركتك خطوة في شكّ. إذا لم يكن المختبر مُشغَّلًا ، ارجع إلى التطبيق الموجّه : قسم بإيجاز يعطي الأوامر ، بما فيها الحزمة (https://github.com/hrhouma2/aiopsatlas-recherche-graphes-labo-fr).

الهدف

جعلك التطبيق الموجّه تُحمّل 504 دورة و609 رأي و12000 سطر سجلّ دفعة واحدة ، بنصّ برمجيّ. رأيت الأرقام ، لكنّك لم تكتب شيئًا بنفسك بعد. هنا ، تبدأ من الصفر : فهرس فارغ تُنشئه ، بطاقة أولى تضعها فيه ، تُعيد قراءتها ، تُكمّلها ، ثم ثانية ، بحث ، حذف. في النهاية ، تعرف ما هو الفهرس والمستند لأنّك صنعت واحدًا ، لا لأنّهم قالوا لك ذلك.

المصطلحات في صورة واحدة

الفهرس هو خزانة. المستند هو بطاقة مرتَّبة في الخزانة : نصّ JSON صغير بحقول. لكلّ بطاقة رقم ، _id الخاصّ بها ، يسمح باستعادتها مباشرة دون البحث. لا حاجة لتعريف الأعمدة مسبقًا : البطاقة الأولى المُرتَّبة تُنشئ الربط (mapping، مخطّط الخزانة) بمفردها.

أين تكتب ، وكيف تقرأ استعلامًا

افتح http://localhost:5601، القائمة ☰ → Management → Dev Tools. اللوحة اليسرى تستقبل الاستعلامات ، اليمنى تعرض الاستجابة. تُرسل بـ Ctrl + Enter (Cmd + Enter على macOS) أو الزرّ ▶ إلى يمين السطر.

كلّ استعلام له الصيغة نفسها : فعل ، مسار ، وأحيانًا متن JSON تحته.

المسار يقول على ماذا نتصرّف : pratique-mini (الخزانة) ، pratique-mini/_doc/1 (البطاقة رقم 1 من الخزانة) ، pratique-mini/_search (البحث في الخزانة). الكلمات التي تبدأ بـ _ هي أوامر خاصّة بـ Elasticsearch ، ليست أسماء تخصّك.

الخطوة 1 — إنشاء الخزانة ، فارغة

PUT pratique-mini

ما يطلبه الاستعلام : أنشئ فهرسًا اسمه pratique-mini. لا شيء آخر : لا أعمدة ، لا محتوى.

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "pratique-mini"
}

انظر إلى : "acknowledged": true، « تمّ الأمر » ، والاسم في الصدى. الشارة في أعلى يمين الاستجابة تقول 200 - OK.

الخطوة 2 — رؤيتها ، وتصحيح لونها

GET _cat/indices/pratique-mini?v

ما يطلبه الاستعلام : سطر ملخّص عن هذا الفهرس ، مع سطر العنوان (?v، verbose).

health status index         uuid                   pri rep docs.count docs.deleted store.size pri.store.size dataset.size
yellow open   pratique-mini YHjAfGXBTwSZcl7CLcc2jw   1   1          0            0       227b           227b         227b

انظر إلى : docs.count 0، الخزانة فارغة. و health yellow مع rep 1 : خطّط Elasticsearch نسخة احتياطيّة (réplica) لفهرسك على آلة ثانية ، ولا يمتلك المختبر إلّا آلة واحدة. لا يمكن وضع النسخة في أيّ مكان ، من هنا الأصفر. الفهارس الثلاثة للحزمة خضراء لأنّ ربطها يضبط number_of_replicas: 0. فعِل الشيء نفسه ، باستعلام واحد :

PUT pratique-mini/_settings
{
  "index": { "number_of_replicas": 0 }
}

{
  "acknowledged": true
}

أعد كتابة GET _cat/indices/pratique-mini?v :

health status index         uuid                   pri rep docs.count docs.deleted store.size pri.store.size dataset.size
green  open   pratique-mini YHjAfGXBTwSZcl7CLcc2jw   1   0          0            0       227b           227b         227b

انظر إلى : green، rep 0. سيكون uuid لديك مختلفًا : إنّه المعرّف الداخليّ للفهرس ، يُسحَب عشوائيًّا عند الإنشاء.

الخطوة 3 — ترتيب بطاقة أولى

PUT pratique-mini/_doc/1
{
  "titre": "Mon premier document"
}

ما يطلبه الاستعلام : في الخزانة pratique-mini، رتّب بطاقة (_doc) رقم 1 تحتوي على حقل titre.

{
  "_index": "pratique-mini",
  "_id": "1",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}

انظر إلى : "result": "created" و "_version": 1 : أوّل إصدار من البطاقة 1. معادل SQL : INSERT INTO pratique_mini (id, titre) VALUES (1, 'Mon premier document')، إلّا أنّه لم يكن هناك حاجة لأيّ CREATE TABLE.

الخطوة 4 — إعادة قراءة البطاقة

GET pratique-mini/_doc/1

ما يطلبه الاستعلام : أعطني البطاقة رقم 1 من pratique-mini، مباشرة ، بدون بحث.

{
  "_index": "pratique-mini",
  "_id": "1",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "titre": "Mon premier document"
  }
}

انظر إلى : "found": true، و _source، بطاقتك كما كتبتها ، بالحرف الواحد. معادل SQL : SELECT * FROM pratique_mini WHERE id = 1.

جرّب بطاقة غير موجودة : GET pratique-mini/_doc/3.

{
  "_index": "pratique-mini",
  "_id": "3",
  "found": false
}

لا خطأ ، لا _source : "found": false، شارة 404 - Not Found. فهم Elasticsearch السؤال ؛ الجواب هو « لا يوجد شيء بهذا الرقم ».

الخطوة 5 — إضافة قيم إلى البطاقة

POST pratique-mini/_update/1
{
  "doc": {
    "auteur": "Alice",
    "note": 5
  }
}

ما يطلبه الاستعلام : حدّث (_update) البطاقة 1 بـ إضافة هذين الحقلين. ما لم يُذكَر (titre) يبقى كما هو.

{
  "_index": "pratique-mini",
  "_id": "1",
  "_version": 2,
  "result": "updated",
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 1,
  "_primary_term": 1
}

انظر إلى : "result": "updated"، "_version": 2. أعد قراءة البطاقة بـ GET pratique-mini/_doc/1 :

{
  "_index": "pratique-mini",
  "_id": "1",
  "_version": 2,
  "_seq_no": 1,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "titre": "Mon premier document",
    "note": 5,
    "auteur": "Alice"
  }
}

ثلاثة حقول. العنوان لا يزال موجودًا. معادل SQL : UPDATE pratique_mini SET auteur = 'Alice', note = 5 WHERE id = 1، بفرق أنّه في SQL يجب أن تكون الأعمدة auteur و note موجودة مسبقًا. هذه استجابتك-تسليمتك : احتفظ بها.

الخطوة 6 — الفخّ : PUT يستبدل كلّ شيء

أعد إرسال استعلام الخطوة 3 بالضبط :

PUT pratique-mini/_doc/1
{
  "titre": "Mon premier document"
}

{
  "_index": "pratique-mini",
  "_id": "1",
  "_version": 3,
  "result": "updated",
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 3,
  "_primary_term": 1
}

انظر إلى : "result": "updated" (ليس created : البطاقة 1 كانت موجودة) و "_version": 3. ثم أعد قراءتها :

{
  "_index": "pratique-mini",
  "_id": "1",
  "_version": 3,
  "_seq_no": 3,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "titre": "Mon premier document"
  }
}

اختفى auteur و note. PUT _doc/1 لا يُعدّل البطاقة 1 : يستبدلها بما ترسله. لإكمالها دون خسارة ، الطريقة هي POST _update/1 مع doc. احتفظ بالقاعدة مع الفعلين : PUT يستبدل ، _update يُكمّل. أعِد الحقلين بطلب الخطوة 5 قبل الاستمرار (تحصل على _version: 4).

الخطوة 7 — بطاقة ثانية ، العدّ ، البحث

PUT pratique-mini/_doc/2
{
  "titre": "Deuxième document, écrit par Bob",
  "auteur": "Bob",
  "note": 3
}

الاستجابة : "_id": "2"، "result": "created"، "_version": 1. ثم عدّ :

GET pratique-mini/_count

{
  "count": 2,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  }
}

معادل SQL : SELECT COUNT(*) FROM pratique_mini. الآن ، انظر إلى كلّ ما يحتويه :

GET pratique-mini/_search

ما يطلبه الاستعلام : بحث في pratique-mini، بدون معيار ، إذن كلّ شيء.

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 1.0,
    "hits": [
      {
        "_index": "pratique-mini",
        "_id": "2",
        "_score": 1.0,
        "_source": {
          "titre": "Deuxième document, écrit par Bob",
          "auteur": "Bob",
          "note": 3
        }
      },
      {
        "_index": "pratique-mini",
        "_id": "1",
        "_score": 1.0,
        "_source": {
          "titre": "Mon premier document",
          "note": 5,
          "auteur": "Alice"
        }
      }
    ]
  }
}

انظر إلى : hits.total.value: 2 (كم بطاقة تُجيب) ثم hits.hits، قائمة البطاقات ، كلّ واحدة بـ _id و _source خاصّتها. يمكن أن يتغيّر ترتيب الاثنتين : بدون معيار ، كلّها بنفس _score يساوي 1.0. معادل SQL : SELECT * FROM pratique_mini.

وأخيرًا ، ابحث عن كلمة :

GET pratique-mini/_search
{
  "query": {
    "match": {
      "titre": "premier"
    }
  }
}

ما يطلبه الاستعلام : البطاقات التي يحتوي حقل titre فيها على كلمة premier.

{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.3788134,
    "hits": [
      {
        "_index": "pratique-mini",
        "_id": "1",
        "_score": 0.3788134,
        "_source": {
          "titre": "Mon premier document",
          "note": 5,
          "auteur": "Alice"
        }
      }
    ]
  }
}

انظر إلى : بطاقة واحدة فقط ، الـ 1 ، و _score ليست 1.0 بعد الآن : إنّها الصلة ، « إلى أيّ حدّ تُجيب هذه البطاقة على السؤال ». الوحدة 3 مخصّصة لهذا الرقم. معادل SQL تقريبيّ : SELECT * FROM pratique_mini WHERE titre LIKE '%premier%'، إلّا أنّ match ستجد أيضًا Premier بحرف كبير ، وستُفسّر لك الوحدة 2 السبب.

الخطوة 8 — حذف بطاقة ، ثم الخزانة

DELETE pratique-mini/_doc/2

{
  "_index": "pratique-mini",
  "_id": "2",
  "_version": 2,
  "result": "deleted",
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 4,
  "_primary_term": 1
}

انظر إلى : "result": "deleted". GET pratique-mini/_count يُعيد 1 (بعد ثانية). معادل SQL : DELETE FROM pratique_mini WHERE id = 2.

ثم احذف الخزانة كاملة ، بما فيها البطاقات :

DELETE pratique-mini

{
  "acknowledged": true
}

الدليل على أنّها لم تعد موجودة ، GET pratique-mini/_doc/1 :

{
  "error": {
    "root_cause": [
      {
        "type": "index_not_found_exception",
        "reason": "no such index [pratique-mini]",
        "resource.type": "index_or_alias",
        "resource.id": "pratique-mini",
        "index_uuid": "_na_",
        "index": "pratique-mini"
      }
    ],
    "type": "index_not_found_exception",
    "reason": "no such index [pratique-mini]",
    "resource.type": "index_or_alias",
    "resource.id": "pratique-mini",
    "index_uuid": "_na_",
    "index": "pratique-mini"
  },
  "status": 404
}

انظر إلى : الفرق مع الخطوة 4. بطاقة غائبة في خزانة موجودة : "found": false، بلا خطأ. خزانة غائبة : index_not_found_exception، 404. الاثنان استجابتان طبيعيّتان لخدمة تعمل. معادل SQL : DROP TABLE pratique_mini.

التحقّق النهائيّ

GET _cat/indices/pratique-*?v

الاستجابة المتوقَّعة : سطر العنوان وحده. لا شيء لك مُتبقٍّ في المجموعة ، و GET _cat/indices/cours,avis,acces?v يعرض دائمًا 504، 609، 12000.

• أنشأت pratique-mini وتعرف لماذا كان أصفر ، ثم أخضر.
• رتّبت البطاقة 1 بـ PUT _doc/1 وأعدت قراءتها بـ GET _doc/1.
• أضفت auteur و note بـ POST _update/1 دون فقدان titre.
• رأيت PUT _doc/1 يحذف الحقلين ، وتعرف قول القاعدة : PUT يستبدل ، _update يُكمّل.
• قال _count 2، سرد _search البطاقتين ، احتفظ match بواحدة فقط.
• حذفت البطاقة 2 ثم الفهرس ، و pratique-* فارغ.
• احتفظت باستجابة GET pratique-mini/_doc/1 بثلاثة حقول (الخطوة 5) كتسليمة.

إذا عطّلت