elasticsearch dsl py

البحث المرن DSL

Elasticsearch DSL هي مكتبة عالية المستوى تهدف إلى المساعدة في كتابة الاستعلامات وتشغيلها ضد Elasticsearch. إنه مبني على العميل الرسمي منخفض المستوى (elasticsearch-py).

فهو يوفر طريقة أكثر ملاءمة واصطلاحية لكتابة الاستعلامات ومعالجتها. ويظل قريبًا من Elasticsearch JSON DSL، مما يعكس مصطلحاته وبنيته. إنه يعرض النطاق الكامل لـ DSL من Python إما مباشرة باستخدام فئات محددة أو تعبيرات تشبه مجموعة الاستعلام.

كما يوفر أيضًا غلافًا اختياريًا للعمل مع المستندات ككائنات Python: تحديد التعيينات، واسترجاع المستندات وحفظها، وتغليف بيانات المستند في فئات محددة من قبل المستخدم.

لاستخدام واجهات برمجة تطبيقات Elasticsearch الأخرى (على سبيل المثال، صحة المجموعة)، ما عليك سوى استخدام العميل الأساسي.

تثبيت

 نقطة تثبيت elasticsearch-dsl

أمثلة

يرجى الاطلاع على دليل الأمثلة لرؤية بعض الأمثلة المعقدة باستخدام elasticsearch-dsl .

التوافق

المكتبة متوافقة مع جميع إصدارات Elasticsearch منذ 2.x ولكن يتعين عليك استخدام إصدار رئيسي مطابق :

بالنسبة إلى Elasticsearch 8.0 والإصدارات الأحدث، استخدم الإصدار الرئيسي 8 ( 8.xy ) من المكتبة.

بالنسبة إلى Elasticsearch 7.0 والإصدارات الأحدث، استخدم الإصدار الرئيسي 7 ( 7.xy ) من المكتبة.

بالنسبة إلى Elasticsearch 6.0 والإصدارات الأحدث، استخدم الإصدار الرئيسي 6 ( 6.xy ) من المكتبة.

بالنسبة إلى Elasticsearch 5.0 والإصدارات الأحدث، استخدم الإصدار الرئيسي 5 ( 5.xy ) من المكتبة.

بالنسبة إلى Elasticsearch 2.0 والإصدارات الأحدث، استخدم الإصدار الرئيسي 2 ( 2.xy ) من المكتبة.

الطريقة الموصى بها لتعيين متطلباتك في ملف setup.py أو require.txt هي:

 # البحث المرن 8.x
elasticsearch-dsl>=8.0.0,<9.0.0

# البحث المرن 7.x
elasticsearch-dsl>=7.0.0,<8.0.0

# البحث المرن 6.x
elasticsearch-dsl>=6.0.0,<7.0.0

# البحث المرن 5.x
elasticsearch-dsl>=5.0.0,<6.0.0

# البحث المرن 2.x
elasticsearch-dsl>=2.0.0,<3.0.0

يتم التطوير على الفروع main والأقدم، ولا تحصل إلا على إصدارات إصلاح الأخطاء

مثال البحث

لنحصل على طلب بحث نموذجي مكتوب مباشرةً على شكل dict :

 from elasticsearch import Elasticsearch
client = Elasticsearch ( "https://localhost:9200" )

response = client . search (
    index = "my-index" ,
    body = {
      "query" : {
        "bool" : {
          "must" : [{ "match" : { "title" : "python" }}],
          "must_not" : [{ "match" : { "description" : "beta" }}],
          "filter" : [{ "term" : { "category" : "search" }}]
        }
      },
      "aggs" : {
        "per_tag" : {
          "terms" : { "field" : "tags" },
          "aggs" : {
            "max_lines" : { "max" : { "field" : "lines" }}
          }
        }
      }
    }
)

for hit in response [ 'hits' ][ 'hits' ]:
    print ( hit [ '_score' ], hit [ '_source' ][ 'title' ])

for tag in response [ 'aggregations' ][ 'per_tag' ][ 'buckets' ]:
    print ( tag [ 'key' ], tag [ 'max_lines' ][ 'value' ])

تكمن المشكلة في هذا الأسلوب في أنه مطول جدًا، وعرضة لأخطاء نحوية مثل التداخل غير الصحيح، ويصعب تعديله (على سبيل المثال، إضافة مرشح آخر)، وبالتأكيد ليس ممتعًا في الكتابة.

لنعد كتابة المثال باستخدام Python DSL:

 from elasticsearch import Elasticsearch
from elasticsearch_dsl import Search

client = Elasticsearch ( "https://localhost:9200" )

s = Search ( using = client , index = "my-index" ) 
    . filter ( "term" , category = "search" ) 
    . query ( "match" , title = "python" )   
    . exclude ( "match" , description = "beta" )

s . aggs . bucket ( 'per_tag' , 'terms' , field = 'tags' ) 
    . metric ( 'max_lines' , 'max' , field = 'lines' )

response = s . execute ()

for hit in response :
    print ( hit . meta . score , hit . title )

for tag in response . aggregations . per_tag . buckets :
    print ( tag . key , tag . max_lines . value )

وكما ترى فإن المكتبة اهتمت بما يلي:

• إنشاء كائنات Query مناسبة بالاسم (على سبيل المثال "مطابقة")
• إنشاء استعلامات في استعلام bool مركب
• وضع استعلام term في سياق عامل التصفية للاستعلام bool
• توفير سهولة الوصول إلى بيانات الاستجابة
• لا توجد أقواس مجعدة أو مربعة في كل مكان

مثال الثبات

لنحصل على فئة بايثون بسيطة تمثل مقالة في نظام التدوين:

 from datetime import datetime
from elasticsearch_dsl import Document , Date , Integer , Keyword , Text , connections

# Define a default Elasticsearch client
connections . create_connection ( hosts = "https://localhost:9200" )

class Article ( Document ):
    title = Text ( analyzer = 'snowball' , fields = { 'raw' : Keyword ()})
    body = Text ( analyzer = 'snowball' )
    tags = Keyword ()
    published_from = Date ()
    lines = Integer ()

    class Index :
        name = 'blog'
        settings = {
          "number_of_shards" : 2 ,
        }

    def save ( self , ** kwargs ):
        self . lines = len ( self . body . split ())
        return super ( Article , self ). save ( ** kwargs )

    def is_published ( self ):
        return datetime . now () > self . published_from

# create the mappings in elasticsearch
Article . init ()

# create and save and article
article = Article ( meta = { 'id' : 42 }, title = 'Hello world!' , tags = [ 'test' ])
article . body = ''' looong text '''
article . published_from = datetime . now ()
article . save ()

article = Article . get ( id = 42 )
print ( article . is_published ())

# Display cluster health
print ( connections . get_connection (). cluster . health ())

في هذا المثال يمكنك أن ترى:

• توفير اتصال افتراضي
• تحديد الحقول مع تكوين التعيين
• إعداد اسم الفهرس
• تحديد الأساليب المخصصة
• تجاوز طريقة .save() المضمنة للربط بدورة حياة الثبات
• استرداد وحفظ الكائن في Elasticsearch
• الوصول إلى العميل الأساسي لواجهات برمجة التطبيقات الأخرى

يمكنك رؤية المزيد في فصل الثبات من الوثائق.

الهجرة من elasticsearch-py

لا يتعين عليك نقل تطبيقك بالكامل للحصول على فوائد Python DSL، يمكنك البدء تدريجيًا عن طريق إنشاء كائن Search من dict الموجود لديك، وتعديله باستخدام واجهة برمجة التطبيقات (API) وإجراء تسلسل له مرة أخرى إلى dict :

 body = {...} # insert complicated query here

# Convert to Search object
s = Search . from_dict ( body )

# Add some filters, aggregations, queries, ...
s . filter ( "term" , tags = "python" )

# Convert back to dict to plug back into existing code
body = s . to_dict ()

تطوير

تفعيل البيئة الافتراضية (virtualenvs):

$ virtualenv venv
$ source venv/bin/activate

لتثبيت كافة التبعيات اللازمة للتطوير، قم بتشغيل:

$ pip install -e ' .[develop] '

لتشغيل جميع اختبارات elasticsearch-dsl-py ، قم بتشغيل:

$ python setup.py test

وبدلاً من ذلك، من الممكن استخدام البرنامج النصي run_tests.py في test_elasticsearch_dsl ، الذي يغلف pytest، لتشغيل مجموعات فرعية من مجموعة الاختبار. يمكن رؤية بعض الأمثلة أدناه:

 # Run all of the tests in `test_elasticsearch_dsl/test_analysis.py`
$ ./run_tests.py test_analysis.py

# Run only the `test_analyzer_serializes_as_name` test.
$ ./run_tests.py test_analysis.py::test_analyzer_serializes_as_name

سوف يتخطى pytest الاختبارات من test_elasticsearch_dsl/test_integration ما لم يكن هناك مثيل لـ Elasticsearch يمكن أن يحدث فيه الاتصال. افتراضيًا، تتم محاولة الاتصال الاختباري على localhost:9200 ، استنادًا إلى الإعدادات الافتراضية المحددة في فئة elasticsearch-py Connection. لأن تشغيل اختبارات التكامل سيؤدي إلى تغييرات مدمرة في مجموعة Elasticsearch، قم بتشغيلها فقط عندما تكون المجموعة المرتبطة فارغة. على هذا النحو، إذا كان مثيل Elasticsearch الموجود على localhost:9200 لا يلبي هذه المتطلبات، فمن الممكن تحديد خادم Elasticsearch اختباري مختلف من خلال متغير البيئة TEST_ES_SERVER .

$ TEST_ES_SERVER=my-test-server:9201 ./run_tests

التوثيق

الوثائق متاحة على https://elasticsearch-dsl.readthedocs.io.

دليل المساهمة

هل تريد اختراق Elasticsearch DSL؟ مذهل! لدينا دليل المساهمة.

رخصة

حقوق الطبع والنشر 2013 Elasticsearch

مرخص بموجب ترخيص Apache، الإصدار 2.0 ("الترخيص")؛ لا يجوز لك استخدام هذا الملف إلا وفقًا للترخيص. يمكنك الحصول على نسخة من الترخيص على

http://www.apache.org/licenses/LICENSE-2.0

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