algoliasearch rails

نقطة البداية المثالية لدمج Algolia في مشروع Rails الخاص بك

الوثائق • منتدى المجتمع • Stack Overflow • الإبلاغ عن خطأ • الأسئلة الشائعة • الدعم

تتيح لك هذه الجوهرة دمج واجهة برمجة تطبيقات Algolia Search بسهولة مع ORM المفضل لديك. إنه يعتمد على جوهرة روبي algoliasearch-client-ruby. يتم دعم الإصدارين 6.x و7.x من القضبان.

قد تكون مهتمًا بنموذج تطبيق Ruby on Rails الذي يوفر الإكمال التلقائي المستند إلى autocomplete.js وصفحة نتائج البحث الفوري المستندة إلى InstantSearch.js : algoliasearch-rails-example.

وثائق واجهة برمجة التطبيقات

يمكنك العثور على المرجع الكامل على موقع Algolia الإلكتروني.

1. يثبت

   • ثَبَّتَ
   • إعدادات
   • المهلات
   • ملحوظات

2. الاستخدام

   • مخطط الفهرس
   • الملاءمة
   • الفهرسة
   • بحث الواجهة الأمامية (تجربة الوقت الحقيقي)
   • بحث الخلفية
   • ترقيم الصفحات الخلفية
   • العلامات
   • مواجهة
   • بحث الأوجه
   • تجميع حسب
   • البحث الجغرافي

3. خيارات

   • الفهرسة التلقائية وعدم التزامن
   • اسم الفهرس المخصص
   • مؤشرات لكل بيئة
   • تعريف السمة المخصصة
   • الكائنات/العلاقات المتداخلة
   • objectID المخصص
   • تقييد الفهرسة على مجموعة فرعية من بياناتك
   • المطهر
   • ترميز UTF-8
   • الاستثناءات
   • مثال التكوين

4. المؤشرات

   • الفهرسة اليدوية
   • الإزالة اليدوية
   • إعادة الفهرسة
   • مسح الفهرس
   • باستخدام المؤشر الأساسي
   • الابتدائي/النسخة المتماثلة
   • مشاركة فهرس واحد
   • استهداف مؤشرات متعددة

5. اختبار

   • ملحوظات

6. استكشاف الأخطاء وإصلاحها

   • الأسئلة المتداولة

يثبت

ثَبَّتَ

gem install algoliasearch-rails

أضف الجوهرة إلى Gemfile الخاص بك:

 gem "algoliasearch-rails"

وتشغيل:

bundle install

إعدادات

أنشئ ملفًا جديدًا config/initializers/algoliasearch.rb لإعداد APPLICATION_ID و API_KEY .

 AlgoliaSearch . configuration = { application_id : 'YourApplicationID' , api_key : 'YourAPIKey' }

الجوهرة متوافقة مع ActiveRecord وMongoid وSequel.

المهلات

يمكنك تكوين حدود مختلفة للمهلة عن طريق تعيين الخيارات التالية في وقت التهيئة:

 AlgoliaSearch . configuration = {
  application_id : 'YourApplicationID' ,
  api_key : 'YourAPIKey' ,
} 

ملحوظات

تستخدم هذه الجوهرة بشكل مكثف عمليات الاسترجاعات الخاصة بـ Rails لتشغيل مهام الفهرسة. إذا كنت تستخدم طرقًا لتجاوز عمليات رد الاتصال after_validation أو before_save أو after_commit ، فلن يتم فهرسة تغييراتك. على سبيل المثال: لا يقوم update_attribute بإجراء عمليات التحقق من الصحة، لإجراء عمليات التحقق من الصحة عند التحديث، استخدم update_attributes .

جميع الطرق التي يتم إدخالها بواسطة وحدة AlgoliaSearch تكون مسبوقة بـ algolia_ وتكون مستعارة للأسماء القصيرة المرتبطة بها إذا لم تكن محددة بالفعل.

 Contact . algolia_reindex! # <=> Contact.reindex!

Contact . algolia_search ( "jon doe" ) # <=> Contact.search("jon doe")

الاستخدام

مخطط الفهرس

سيقوم التعليمة البرمجية التالية بإنشاء فهرس Contact وإضافة إمكانيات البحث إلى نموذج Contact الخاص بك:

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch do
    attributes :first_name , :last_name , :email
  end
end

يمكنك إما تحديد السمات المراد إرسالها (هنا يقتصر الأمر على :first_name, :last_name, :email ) أو لا (في هذه الحالة، يتم إرسال جميع السمات).

 class Product < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch do
    # all attributes will be sent
  end
end

يمكنك أيضًا استخدام التابع add_attribute لإرسال جميع سمات النموذج + السمات الإضافية:

 class Product < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch do
    # all attributes + extra_attr will be sent
    add_attribute :extra_attr
  end

  def extra_attr
    "extra_val"
  end
end 

الملاءمة

نحن نقدم العديد من الطرق لتكوين الفهرس الخاص بك مما يسمح لك بضبط ملاءمة الفهرس بشكل عام. وأهمها السمات القابلة للبحث والسمات التي تعكس الشعبية القياسية .

 class Product < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch do
    # list of attribute used to build an Algolia record
    attributes :title , :subtitle , :description , :likes_count , :seller_name

    # the `searchableAttributes` (formerly known as attributesToIndex) setting defines the attributes
    # you want to search in: here `title`, `subtitle` & `description`.
    # You need to list them by order of importance. `description` is tagged as
    # `unordered` to avoid taking the position of a match into account in that attribute.
    searchableAttributes [ 'title' , 'subtitle' , 'unordered(description)' ]

    # the `customRanking` setting defines the ranking criteria use to compare two matching
    # records in case their text-relevance is equal. It should reflect your record popularity.
    customRanking [ 'desc(likes_count)' ]
  end

end 

الفهرسة

لفهرسة نموذج، قم باستدعاء بسيط reindex في الفصل:

 Product . reindex

لفهرسة كافة النماذج الخاصة بك، يمكنك القيام بشيء من هذا القبيل:

 Rails . application . eager_load! # Ensure all models are loaded (required in development).

algolia_models = ActiveRecord :: Base . descendants . select { | model | model . respond_to? ( :reindex ) }

algolia_models . each ( & :reindex ) 

بحث الواجهة الأمامية (تجربة الوقت الحقيقي)

تميل تطبيقات البحث التقليدية إلى أن يكون لديها منطق بحث ووظيفة في الواجهة الخلفية. كان هذا منطقيًا عندما كانت تجربة البحث تتألف من قيام المستخدم بإدخال استعلام بحث، وتنفيذ هذا البحث، ثم إعادة توجيهه إلى صفحة نتائج البحث.

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

يعد عميل JS API جزءًا من الجوهرة، ما عليك سوى طلب algolia/v3/algoliasearch.min في مكان ما في بيان JavaScript الخاص بك، على سبيل المثال في application.js إذا كنت تستخدم Rails 3.1+:

 //= require algolia/v3/algoliasearch.min

ثم في كود JavaScript الخاص بك يمكنك القيام بما يلي:

 var client = algoliasearch ( ApplicationID , Search - Only - API - Key ) ;
var index = client . initIndex ( 'YourIndexName' ) ;
index . search ( 'something' , { hitsPerPage : 10 , page : 0 } )
  . then ( function searchDone ( content ) {
    console . log ( content )
  } )
  . catch ( function searchFailure ( err ) {
    console . error ( err ) ;
  } ) ;

لقد قمنا مؤخرًا (مارس 2015) بإصدار إصدار جديد (V3) من عميل JavaScript الخاص بنا، إذا كنت تستخدم الإصدار السابق (V2)، فاقرأ دليل الترحيل

بحث الخلفية

ملاحظات: نوصي باستخدام عميل JavaScript API الخاص بنا لإجراء الاستعلامات مباشرة من متصفح المستخدم النهائي دون المرور عبر الخادم الخاص بك.

يقوم البحث بإرجاع كائنات متوافقة مع ORM ويعيد تحميلها من قاعدة البيانات الخاصة بك. نوصي باستخدام عميل JavaScript API الخاص بنا لإجراء استعلامات لتقليل زمن الوصول الإجمالي وتفريغ خوادمك.

 hits =  Contact . search ( "jon doe" )
p hits
p hits . raw_answer # to get the original JSON raw answer

تتم إضافة سمة highlight_result إلى كل كائن ORM:

 hits [ 0 ] . highlight_result [ 'first_name' ] [ 'value' ]

إذا كنت تريد استرداد إجابة JSON الأولية من واجهة برمجة التطبيقات (API)، دون إعادة تحميل الكائنات من قاعدة البيانات، فيمكنك استخدام:

 json_answer = Contact . raw_search ( "jon doe" )
p json_answer
p json_answer [ 'hits' ]
p json_answer [ 'facets' ]

يمكن تحديد معلمات البحث إما من خلال إعدادات الفهرس بشكل ثابت في النموذج الخاص بك أو ديناميكيًا في وقت البحث مع تحديد معلمات البحث كوسيطة ثانية لطريقة search :

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch do
    attribute :first_name , :last_name , :email

    # default search parameters stored in the index settings
    minWordSizefor1Typo 4
    minWordSizefor2Typos 8
    hitsPerPage 42
  end
end 

 # dynamical search parameters
p Contact . raw_search ( 'jon doe' , { hitsPerPage : 5 , page : 2 } ) 

ترقيم الصفحات الخلفية

حتى لو نوصي بشدة بإجراء جميع عمليات البحث (وبالتالي ترقيم الصفحات) من الواجهة الأمامية لديك باستخدام JavaScript ، فإننا ندعم كلاً من will_paginate وkaminari كواجهة خلفية لترقيم الصفحات.

لاستخدام :will_paginate ، حدد :pagination_backend كما يلي:

 AlgoliaSearch . configuration = { application_id : 'YourApplicationID' , api_key : 'YourAPIKey' , pagination_backend : :will_paginate }

بعد ذلك، بمجرد استخدام طريقة search ، ستكون النتائج المرتجعة عبارة عن مجموعة مرقّمة:

 # in your controller
@results = MyModel . search ( 'foo' , hitsPerPage : 10 )

# in your views
# if using will_paginate
<%= will_paginate @results %>

# if using kaminari
<%= paginate @results %> 

العلامات

استخدم طريقة tags لإضافة علامات إلى السجل الخاص بك:

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch do
    tags [ 'trusted' ]
  end
end

أو باستخدام القيم الديناميكية:

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch do
    tags do
      [ first_name . blank? || last_name . blank? ? 'partial' : 'full' , has_valid_email? ? 'valid_email' : 'invalid_email' ]
    end
  end
end

في وقت الاستعلام، حدد { tagFilters: 'tagvalue' } أو { tagFilters: ['tagvalue1', 'tagvalue2'] } كمعلمات بحث لتقييد مجموعة النتائج بعلامات محددة.

مواجهة

يمكن استرجاع الأوجه باستدعاء طريقة facets الإضافية لإجابة البحث.

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch do
    # [...]

    # specify the list of attributes available for faceting
    attributesForFaceting [ :company , :zip_code ]
  end
end 

 hits = Contact . search ( 'jon doe' , { facets : '*' } )
p hits                    # ORM-compliant array of objects
p hits . facets             # extra method added to retrieve facets
p hits . facets [ 'company' ]  # facet values+count of facet 'company'
p hits . facets [ 'zip_code' ] # facet values+count of facet 'zip_code' 

 raw_json = Contact . raw_search ( 'jon doe' , { facets : '*' } )
p raw_json [ 'facets' ] 

بحث الأوجه

يمكنك أيضًا البحث عن قيم الجوانب.

 Product . search_for_facet_values ( 'category' , 'Headphones' ) # Array of {value, highlighted, count}

يمكن لهذه الطريقة أيضًا أن تأخذ أي معلمة يمكن أن يأخذها الاستعلام. سيؤدي هذا إلى ضبط البحث على النتائج التي قد تطابق الاستعلام فقط.

 # Only sends back the categories containing red Apple products (and only counts those)
Product . search_for_facet_values ( 'category' , 'phone' , {
  query : 'red' ,
  filters : 'brand:Apple'
} ) # Array of phone categories linked to red Apple products 

تجميع حسب

يمكن العثور على مزيد من المعلومات حول التجميع المتميز هنا.

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch do
    # [...]

    # specify the attribute to be used for distinguishing the records
    # in this case the records will be grouped by company
    attributeForDistinct "company"
  end
end 

البحث الجغرافي

استخدم طريقة geoloc لتوطين السجل الخاص بك:

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch do
    geoloc :lat_attr , :lng_attr
  end
end

في وقت الاستعلام، حدد { aroundLatLng: "37.33, -121.89", aroundRadius: 50000 } كمعلمات بحث لتقييد مجموعة النتائج بـ 50 كيلومترًا حول سان خوسيه.

خيارات

الفهرسة التلقائية وعدم التزامن

في كل مرة يتم فيها حفظ سجل، سيتم فهرسته بشكل غير متزامن . من ناحية أخرى، في كل مرة يتم فيها تدمير السجل، سيتم إزالته - بشكل غير متزامن - من الفهرس. وهذا يعني أنه يتم إرسال مكالمة شبكة مع عملية ADD/DELETE بشكل متزامن إلى Algolia API ولكن بعد ذلك سيقوم المحرك بمعالجة العملية بشكل غير متزامن (لذلك إذا قمت بإجراء بحث بعد ذلك مباشرة، فقد لا تعكس النتائج ذلك بعد).

يمكنك تعطيل إعداد الفهرسة التلقائية والإزالة التلقائية بالخيارات التالية:

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch auto_index : false , auto_remove : false do
    attribute :first_name , :last_name , :email
  end
end

تعطيل الفهرسة التلقائية بشكل مؤقت

يمكنك تعطيل الفهرسة التلقائية مؤقتًا باستخدام نطاق without_auto_index . غالبًا ما يستخدم هذا لسبب الأداء.

 Contact . delete_all
Contact . without_auto_index do
  1 . upto ( 10000 ) { Contact . create! attributes } # inside this block, auto indexing task will not run.
end
Contact . reindex! # will use batch operations

قوائم الانتظار والوظائف الخلفية

يمكنك تكوين عملية الفهرسة التلقائية والإزالة التلقائية لاستخدام قائمة انتظار لتنفيذ تلك العمليات في الخلفية. يتم استخدام قوائم انتظار ActiveJob (Rails >=4.2) بشكل افتراضي ولكن يمكنك تحديد آلية الانتظار الخاصة بك:

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch enqueue : true do # ActiveJob will be triggered using a `algoliasearch` queue
    attribute :first_name , :last_name , :email
  end
end

أشياء يجب مراعاتها

إذا كنت تقوم بإجراء التحديثات والحذف في الخلفية، فيمكن الالتزام بحذف السجل في قاعدة البيانات الخاصة بك قبل تنفيذ المهمة فعليًا. وبالتالي، إذا كنت تريد تحميل السجل لإزالته من قاعدة البيانات، فسوف يفشل ActiveRecord#find مع RecordNotFound.

في هذه الحالة يمكنك تجاوز تحميل السجل من ActiveRecord والتواصل مع الفهرس مباشرة:

 class MySidekiqWorker
  def perform ( id , remove )
    if remove
      # the record has likely already been removed from your database so we cannot
      # use ActiveRecord#find to load it
      index = AlgoliaSearch . client . init_index ( "index_name" )
      index . delete_object ( id )
    else
      # the record should be present
      c = Contact . find ( id )
      c . index!
    end
  end
end

مع الصاحب

إذا كنت تستخدم Sidekiq:

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch enqueue : :trigger_sidekiq_worker do
    attribute :first_name , :last_name , :email
  end

  def self . trigger_sidekiq_worker ( record , remove )
    MySidekiqWorker . perform_async ( record . id , remove )
  end
end

class MySidekiqWorker
  def perform ( id , remove )
    if remove
      # the record has likely already been removed from your database so we cannot
      # use ActiveRecord#find to load it
      index = AlgoliaSearch . client . init_index ( "index_name" )
      index . delete_object ( id )
    else
      # the record should be present
      c = Contact . find ( id )
      c . index!
    end
  end
end

مع وظيفة مؤجلة

إذا كنت تستخدم late_job:

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch enqueue : :trigger_delayed_job do
    attribute :first_name , :last_name , :email
  end

  def self . trigger_delayed_job ( record , remove )
    if remove
      record . delay . remove_from_index!
    else
      record . delay . index!
    end
  end
end

التزامن والاختبار

يمكنك فرض الفهرسة والإزالة لتكون متزامنة (في هذه الحالة، ستستدعي الجوهرة طريقة wait_task للتأكد من أن العملية قد تم أخذها في الاعتبار بمجرد عودة الطريقة) عن طريق تعيين الخيار التالي: ( لا ينصح بهذا، باستثناء غرض الاختبار )

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch synchronous : true do
    attribute :first_name , :last_name , :email
  end
end 

اسم الفهرس المخصص

افتراضيًا، سيكون اسم الفهرس هو اسم الفئة، على سبيل المثال "جهة الاتصال". يمكنك تخصيص اسم الفهرس باستخدام خيار index_name :

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch index_name : "MyCustomName" do
    attribute :first_name , :last_name , :email
  end
end 

مؤشرات لكل بيئة

يمكنك إضافة اسم الفهرس إلى بيئة Rails الحالية باستخدام الخيار التالي:

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch per_environment : true do # index name will be "Contact_#{Rails.env}"
    attribute :first_name , :last_name , :email
  end
end 

تعريف السمة المخصصة

يمكنك استخدام كتلة لتحديد قيمة سمة معقدة

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch do
    attribute :email
    attribute :full_name do
      " #{ first_name } #{ last_name } "
    end
    add_attribute :full_name2
  end

  def full_name2
    " #{ first_name } #{ last_name } "
  end
end

ملاحظات: بمجرد استخدام مثل هذا الكود لتحديد سمات إضافية، لن تتمكن الجوهرة بعد الآن من اكتشاف ما إذا كانت السمة قد تغيرت (يستخدم الكود طريقة ريلز #{attribute}_changed? لاكتشاف ذلك). ونتيجة لذلك، سيتم دفع السجل الخاص بك إلى واجهة برمجة التطبيقات (API) حتى لو لم تتغير سماته. يمكنك التغلب على هذا السلوك بإنشاء _changed? طريقة:

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch do
    attribute :email
    attribute :full_name do
      " #{ first_name } #{ last_name } "
    end
  end

  def full_name_changed?
    first_name_changed? || last_name_changed?
  end
end 

الكائنات/العلاقات المتداخلة

تحديد العلاقة

يمكنك بسهولة تضمين كائنات متداخلة تحدد سمة إضافية ترجع أي كائن متوافق مع JSON (صفيف أو تجزئة أو مزيج من الاثنين معًا).

 class Profile < ActiveRecord :: Base
  include AlgoliaSearch

  belongs_to :user
  has_many :specializations

  algoliasearch do
    attribute :user do
      # restrict the nested "user" object to its `name` + `email`
      { name : user . name , email : user . email }
    end
    attribute :public_specializations do
      # build an array of public specialization (include only `title` and `another_attr`)
      specializations . select { | s | s . public? } . map do | s |
        { title : s . title , another_attr : s . another_attr }
      end
    end
  end

end

نشر التغيير من طفل متداخل

مع أكتيف ريكورد

باستخدام ActiveRecord، سنستخدم touch و after_touch لتحقيق ذلك.

 # app/models/app.rb
class App < ApplicationRecord
  include AlgoliaSearch

  belongs_to :author , class_name : :User
  after_touch :index!

  algoliasearch do
    attribute :title
    attribute :author do
      author . as_json
    end
  end
end

# app/models/user.rb
class User < ApplicationRecord
  # If your association uses belongs_to
  # - use `touch: true`
  # - do not define an `after_save` hook
  has_many :apps , foreign_key : :author_id

  after_save { apps . each ( & :touch ) }
end 

مع تتمة

باستخدام Sequel، يمكنك استخدام مكون touch لنشر التغييرات:

 # app/models/app.rb
class App < Sequel :: Model
  include AlgoliaSearch

  many_to_one :author , class : :User

  plugin :timestamps
  plugin :touch

  algoliasearch do
    attribute :title
    attribute :author do
      author . to_hash
    end
  end
end

# app/models/user.rb
class User < Sequel :: Model
  one_to_many :apps , key : :author_id

  plugin :timestamps
  # Can't use the associations since it won't trigger the after_save
  plugin :touch

  # Define the associations that need to be touched here
  # Less performant, but allows for the after_save hook to trigger
  def touch_associations
    apps . map ( & :touch )
  end

  def touch
    super
    touch_associations
  end
end 

objectID المخصص

افتراضيًا، يعتمد objectID على id السجل الخاص بك. يمكنك تغيير هذا السلوك من خلال تحديد خيار :id (تأكد من استخدام حقل uniq).

 class UniqUser < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch id : :uniq_name do
  end
end 

تقييد الفهرسة على مجموعة فرعية من بياناتك

يمكنك إضافة قيود تتحكم في ما إذا كان يجب فهرسة السجل باستخدام الخيارات :if أو :unless options.

يسمح لك بإجراء الفهرسة المشروطة على أساس كل مستند.

 class Post < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch if : :published? , unless : :deleted? do
  end

  def published?
    # [...]
  end

  def deleted?
    # [...]
  end
end

ملاحظات: بمجرد استخدام هذه القيود، سيتم تنفيذ استدعاءات addObjects و deleteObjects من أجل الحفاظ على مزامنة الفهرس مع قاعدة البيانات (لا تعرف الجوهرة عديمة الحالة ما إذا كان الكائن لا يطابق قيودك بعد الآن أو لم يتطابق أبدًا ، لذلك نفرض إرسال عمليات ADD/DELETE). يمكنك التغلب على هذا السلوك بإنشاء _changed? طريقة:

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch if : :published do
  end

  def published
    # true or false
  end

  def published_changed?
    # return true only if you know that the 'published' state changed
  end
end

يمكنك فهرسة مجموعة فرعية من سجلاتك باستخدام إما:

 # will generate batch API calls (recommended)
MyModel . where ( 'updated_at > ?' , 10 . minutes . ago ) . reindex!

أو

 MyModel . index_objects MyModel . limit ( 5 ) 

المطهر

يمكنك تعقيم جميع سماتك باستخدام خيار sanitize . سيؤدي ذلك إلى تجريد جميع علامات HTML من سماتك.

 class User < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch per_environment : true , sanitize : true do
    attributes :name , :email , :company
  end
end

إذا كنت تستخدم الإصدار 4.2+ من Rails، فستحتاج أيضًا إلى الاعتماد على rails-html-sanitizer :

 gem 'rails-html-sanitizer' 

ترميز UTF-8

يمكنك فرض تشفير UTF-8 لجميع سماتك باستخدام خيار force_utf8_encoding :

 class User < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch force_utf8_encoding : true do
    attributes :name , :email , :company
  end
end

ملاحظات: هذا الخيار غير متوافق مع Ruby 1.8

الاستثناءات

يمكنك تعطيل الاستثناءات التي قد تظهر أثناء محاولة الوصول إلى واجهة برمجة تطبيقات Algolia باستخدام خيار raise_on_failure :

 class Contact < ActiveRecord :: Base
  include AlgoliaSearch

  # only raise exceptions in development env
  algoliasearch raise_on_failure : Rails . env . development? do
    attribute :first_name , :last_name , :email
  end
end 

مثال التكوين

فيما يلي مثال لتكوين الكلمة الحقيقية (من بحث HN):

 class Item < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch per_environment : true do
    # the list of attributes sent to Algolia's API
    attribute :created_at , :title , :url , :author , :points , :story_text , :comment_text , :author , :num_comments , :story_id , :story_title

    # integer version of the created_at datetime field, to use numerical filtering
    attribute :created_at_i do
      created_at . to_i
    end

    # `title` is more important than `{story,comment}_text`, `{story,comment}_text` more than `url`, `url` more than `author`
    # btw, do not take into account position in most fields to avoid first word match boost
    searchableAttributes [ 'unordered(title)' , 'unordered(story_text)' , 'unordered(comment_text)' , 'unordered(url)' , 'author' ]

    # tags used for filtering
    tags do
      [ item_type , "author_ #{ author } " , "story_ #{ story_id } " ]
    end

    # use associated number of HN points to sort results (last sort criteria)
    customRanking [ 'desc(points)' , 'desc(num_comments)' ]

    # google+, $1.5M raises, C#: we love you
    separatorsToIndex '+#$'
  end

  def story_text
    item_type_cd != Item . comment ? text : nil
  end

  def story_title
    comment? && story ? story . title : nil
  end

  def story_url
    comment? && story ? story . url : nil
  end

  def comment_text
    comment? ? text : nil
  end

  def comment?
    item_type_cd == Item . comment
  end

  # [...]
end

المؤشرات

الفهرسة اليدوية

يمكنك تشغيل الفهرسة باستخدام index! طريقة المثيل.

 c = Contact . create! ( params [ :contact ] )
c . index! 

الإزالة اليدوية

وقم بإزالة الفهرس باستخدام remove_from_index! طريقة المثيل.

 c . remove_from_index!
c . destroy 

إعادة الفهرسة

توفر الجوهرة طريقتين لإعادة فهرسة جميع العناصر الخاصة بك:

إعادة الفهرسة الذرية

لإعادة فهرسة جميع سجلاتك (مع الأخذ في الاعتبار الكائنات المحذوفة)، تقوم طريقة فئة reindex بفهرسة جميع كائناتك إلى فهرس مؤقت يسمى <INDEX_NAME>.tmp وتنقل الفهرس المؤقت إلى الفهرس النهائي بمجرد فهرسة كل شيء (ذريًا). هذه هي الطريقة الأكثر أمانًا لإعادة فهرسة كل المحتوى الخاص بك.

 Contact . reindex

ملاحظات : إذا كنت تستخدم مفتاح API خاصًا بالفهرس، فتأكد من السماح لكل من <INDEX_NAME> و <INDEX_NAME>.tmp .

تحذير: يجب ألا تستخدم عملية إعادة الفهرسة الذرية هذه أثناء تحديد نطاق/تصفية النموذج لأن هذه العملية تحل محل الفهرس بأكمله ، مع الاحتفاظ بالكائنات التي تمت تصفيتها فقط. على سبيل المثال: لا تفعل MyModel.where(...).reindex لكن افعل MyModel.where(...).reindex! (مع زائدة ! )!!!

إعادة الفهرسة العادية

لإعادة فهرسة جميع الكائنات الموجودة في مكانها (بدون فهرس مؤقت وبالتالي دون حذف الكائنات المحذوفة)، استخدم reindex! طريقة الطبقة:

 Contact . reindex! 

مسح الفهرس

لمسح فهرس، استخدم clear_index! طريقة الطبقة:

 Contact . clear_index! 

باستخدام المؤشر الأساسي

يمكنك الوصول إلى كائن index الأساسي عن طريق استدعاء طريقة فئة index :

 index = Contact . index
# index.get_settings, index.partial_update_object, ... 

الابتدائي/النسخة المتماثلة

يمكنك تحديد فهارس النسخ المتماثلة باستخدام طريقة add_replica . استخدم inherit: true على كتلة النسخة المتماثلة إذا كنت تريد أن ترث من الإعدادات الأساسية.

 class Book < ActiveRecord :: Base
  attr_protected

  include AlgoliaSearch

  algoliasearch per_environment : true do
    searchableAttributes [ :name , :author , :editor ]

    # define a replica index to search by `author` only
    add_replica 'Book_by_author' , per_environment : true do
      searchableAttributes [ :author ]
    end

    # define a replica index with custom ordering but same settings than the main block
    add_replica 'Book_custom_order' , inherit : true , per_environment : true do
      customRanking [ 'asc(rank)' ]
    end
  end

end

للبحث باستخدام نسخة طبق الأصل، استخدم الكود التالي:

 Book . raw_search 'foo bar' , replica : 'Book_by_editor'
# or
Book . search 'foo bar' , replica : 'Book_by_editor' 

مشاركة فهرس واحد

قد يكون من المنطقي مشاركة فهرس بين عدة نماذج. من أجل تنفيذ ذلك، ستحتاج إلى التأكد من عدم وجود أي تعارض مع objectID للنماذج الأساسية.

 class Student < ActiveRecord :: Base
  attr_protected

  include AlgoliaSearch

  algoliasearch index_name : 'people' , id : :algolia_id do
    # [...]
  end

  private
  def algolia_id
    "student_ #{ id } " # ensure the teacher & student IDs are not conflicting
  end
end

class Teacher < ActiveRecord :: Base
  attr_protected

  include AlgoliaSearch

  algoliasearch index_name : 'people' , id : :algolia_id do
    # [...]
  end

  private
  def algolia_id
    "teacher_ #{ id } " # ensure the teacher & student IDs are not conflicting
  end
end

ملاحظات: إذا كنت تستهدف فهرسًا واحدًا من عدة نماذج، فيجب عليك عدم استخدام MyModel.reindex مطلقًا واستخدام MyModel.reindex! . تستخدم طريقة reindex فهرسًا مؤقتًا لإجراء إعادة فهرسة ذرية: إذا استخدمتها، فسيحتوي الفهرس الناتج فقط على سجلات النموذج الحالي لأنه لن يعيد فهرسة النماذج الأخرى.

استهداف مؤشرات متعددة

يمكنك فهرسة سجل في عدة فهارس باستخدام طريقة add_index :

 class Book < ActiveRecord :: Base
  attr_protected

  include AlgoliaSearch

  PUBLIC_INDEX_NAME  = "Book_ #{ Rails . env } "
  SECURED_INDEX_NAME = "SecuredBook_ #{ Rails . env } "

  # store all books in index 'SECURED_INDEX_NAME'
  algoliasearch index_name : SECURED_INDEX_NAME do
    searchableAttributes [ :name , :author ]
    # convert security to tags
    tags do
      [ released ? 'public' : 'private' , premium ? 'premium' : 'standard' ]
    end

    # store all 'public' (released and not premium) books in index 'PUBLIC_INDEX_NAME'
    add_index PUBLIC_INDEX_NAME , if : :public? do
      searchableAttributes [ :name , :author ]
    end
  end

  private
  def public?
    released && ! premium
  end

end

للبحث باستخدام فهرس إضافي استخدم الكود التالي:

 Book . raw_search 'foo bar' , index : 'Book_by_editor'
# or
Book . search 'foo bar' , index : 'Book_by_editor'

اختبار

ملحوظات

لتشغيل المواصفات، يرجى تعيين متغيرات البيئة ALGOLIA_APPLICATION_ID و ALGOLIA_API_KEY . نظرًا لأن الاختبارات تقوم بإنشاء المؤشرات وإزالتها، فلا تستخدم حساب الإنتاج الخاص بك.

قد ترغب في تعطيل كافة استدعاءات واجهة برمجة التطبيقات (عمليات الإضافة والتحديث والحذف) للفهرسة، ويمكنك ضبط خيار disable_indexing :

 class User < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch per_environment : true , disable_indexing : Rails . env . test? do
  end
end

class User < ActiveRecord :: Base
  include AlgoliaSearch

  algoliasearch per_environment : true , disable_indexing : Proc . new { Rails . env . test? || more_complex_condition } do
  end
end 

❓ استكشاف الأخطاء وإصلاحها

تواجه مشكلة؟ قبل التواصل مع الدعم، نوصي بالتوجه إلى الأسئلة الشائعة حيث ستجد إجابات للمشكلات والمشاكل الأكثر شيوعًا مع العميل.

استخدم ملف Docker

إذا كنت ترغب في المساهمة في هذا المشروع دون تثبيت جميع تبعياته، فيمكنك استخدام صورة Docker الخاصة بنا. يرجى مراجعة دليلنا المخصص لمعرفة المزيد.