عرض مصدر Rails/active record querying

<noinclude>{{DISPLAYTITLE:واجهة استعلامات Active Record في ريلز}}</noinclude>
[[تصنيف:Rails]]
[[تصنيف:Rails Models]]
يغطي هذا الدليل مختلف الطرائق المستعملة لجلب واستعادة البيانات من قاعدة البيانات باستعمال [[Rails/active record|Active Record]]. بعد قراءة هذا الدليل، ستتعلم:
* كيفية البحث عن السجلات باستعمال توابع وشروط متعددة.
* كيفية تحديد الترتيب، والتجميع، والخاصيات المعادة، والخاصيات الأخرى للسجلات التي عُثِر عليها.
* كيفية استعمال التحميل الحثيث (eager loading) للتقليل من عدد استعلامات قاعدة البيانات الضرورية لجلب البيانات.
* كيفية استعمال توابع البحث الديناميكية.
* كيفية استعمال تسلسل التوابع (method chaining) لاستعمال توابع متعددة [[Rails/active record|Active Record]] سويةً.
* كيفية التحقق من تواجد سجلات محددة.
* كيفية تنفيذ حسابات مختلفة على نماذج [[Rails/active record|Active Record]].
* كيفية تشغيل EXPLAIN على العلاقات.
في حال كنت معتادًا على تنفيذ استعلامات [[SQL]] لإيجاد السجلات في قاعدة البيانات، فستجد أنَّ هناك طرقًا أفضل لتنفيذ هذه الاستعلامات في ريلز. يغنيك [[Rails/active record|Active Record]] عن الحاجة لتنفيذ تعليمات [[SQL]] في معظم الحالات.

إن الأمثلة الموجودة في هذا التوثيق ستستخدم النماذج التالية:

'''ملاحظة''': جميع النماذج التالية تستخدم الحقل id مفتاحًا رئيسيًا لها، إلّا عند تحديد عكس ذلك.<syntaxhighlight lang="rails">
class Client < ApplicationRecord
  has_one :address
  has_many :orders
  has_and_belongs_to_many :roles
end
</syntaxhighlight><syntaxhighlight lang="rails">
class Address < ApplicationRecord
  belongs_to :client
end
</syntaxhighlight><syntaxhighlight lang="rails">
class Order < ApplicationRecord
  belongs_to :client, counter_cache: true
end
</syntaxhighlight><syntaxhighlight lang="rails">
class Role < ApplicationRecord
  has_and_belongs_to_many :clients
end
</syntaxhighlight>سينفذ [[Rails/active record|Active Record]] استعلامات [[SQL]] من أجلك، وجميع هذه الاستعلامات مطابقة مع معظم أنظمة قواعد البيانات، بما فيها MySQL، و MariaDB، و PostgreSQL، و SQLite. بغض النظر عن نمط قاعدة البيانات المستخدمة، تكون توابع [[Rails/active record|Active Record]] المستخدمة في الاستعلامات ذاتها لجميع الأنظمة السابقة الذكر.

== جلب الكائنات من قاعدة البيانات ==
لقراءة الكائنات من قاعدة البيانات، يزوّدك [[Rails/active record|Active Record]] بمجموعة من توابع البحث. يسمح كل تابع بحث بتمرير وسائط له لتنفيذ استعلامات محددة على قاعدة البيانات دون كتابة استعلامات [[SQL]] خام.

هذه التوابع هي:
* <code>find</code>

* <code>create_with</code>
* <code>distinct</code>
* <code>eager_load</code>
* <code>extending</code>
* <code>from</code>
* <code>group</code>
* <code>having</code>
* <code>includes</code>
* <code>joins</code>
* <code>left_outer_joins</code>
* <code>limit</code>
* <code>lock</code>
* <code>none</code>
* <code>offset</code>
* <code>order</code>
* <code>preload</code>
* <code>readonly</code>
* <code>references</code>
* <code>reorder</code>
* <code>reverse_order</code>
* <code>select</code>
* <code>where</code>
إن توابع البحث التي تعيد مجموعات، مثل التابع <code>where</code> والتابع <code>group</code>، تعيد نسخةً من <code>ActiveRecord::Relation</code>. والتوابع التي تبحث عن كائن وحيد، مثل التابع <code>find</code> والتابع <code>first</code>، تعيد نسخةً وحيدةً من نوع النموذج المطلوب.

يمكن تلخيص العمليات الأساسية للتابع <code>(Model.find(options</code> كالتالي:
* تحويل الخيارات المعطاة إلى استعلام [[SQL]] خام.
* تنفيذ الاستعلام وقراءة النتائج الموافقة من قاعدة البيانات.
* تهيئة كائنات [[Ruby|روبي]] الموافقة للنموذج المطلوب تنفيذ الاستعلام عليه، وذلك من أجل كل حقل من الحقول الناتجة.
* تشغيل توابع رد النداء مثل <code>after_find</code> ثم <code>after_initialize</code>، في حال وجودهما.

=== جلب كائن وحيد ===
يزوّد [[Rails/active record|Active Record]] مجموعة من الطرق المختلفة لجلب كائن وحيد.

==== التابع <code>find</code> ====
باستخدام التابع <code>find</code>، يمكنك جلب الكائن المقابل لقيمة المفتاح الرئيسي الممرر له. مثلًا:<syntaxhighlight lang="rails">
# 10 (id) ابحث عن الزبون بالمفتاح الرئيسي
client = Client.find(10)
# => #<Client id: 10, first_name: "Ryan">


</syntaxhighlight>استعلام [[SQL]] الموافق للتعليمة السابقة هو:<syntaxhighlight lang="sql">
SELECT * FROM clients WHERE (clients.id = 10) LIMIT 1
</syntaxhighlight>يرمي التابع <code>find</code> استثناءً من النوع <code>ActiveRecord::RecordNotFound</code> في حال لم يتم العثور على أي سجل مطابق.

يمكنك أيضًا استخدام هذا التابع للاستعلام عن مجموعة من الكائنات، عن طريق تمرير مصفوفة من قيم المفتاح الرئيسي للتابع. تكون القيمة المعادة مصفوفة تحتوي على جميع السجلات المطابقة لقيم المفتاح الرئيسي الممررة. مثلًا:<syntaxhighlight lang="rails">
# ابحث عن الزبائن بقيم المفتاح الرئيسي 1 و 10.
clients = Client.find([1, 10]) # Client.find(1, 10) أو يمكن استعمال
# => [#<Client id: 1, first_name: "Lifo">, #<Client id: 10, first_name: "Ryan">]


</syntaxhighlight>استعلام [[SQL]] الموافق للتعليمة السابقة هو:<syntaxhighlight lang="sql">
SELECT * FROM clients WHERE (clients.id IN (1,10))
</syntaxhighlight>'''تحذير''': يرمي التابع <code>find</code> استثناءً من النوع <code>ActiveRecord::RecordNotFound</code> إلّا إذا تم العثور على سجل واحد على الأقل من أجل جميع قيم المفتاح الرئيسي الممررة.

==== التابع <code>take</code> ====
يعيد التابع <code>take</code> سجلًا بدون أي ترتيب واضح. مثلًا:<syntaxhighlight lang="rails">
client = Client.take
# => #<Client id: 1, first_name: "Lifo">

</syntaxhighlight>استعلام [[SQL]] الموافق للتعليمة السابقة هو:<syntaxhighlight lang="sql">
SELECT * FROM clients LIMIT 1
</syntaxhighlight>يعيد التابع <code>take</code> القيمة <code>nil</code> في حال لم يتم العثور على أي سجل، ولن يتم رمي استثناء.

يمكنك تمرير وسيط رقمي للتابع <code>take</code> لإعادة مجموعة السجلات التي عددها يوافق الوسيط الممرر. مثلًا:<syntaxhighlight lang="rails">
clients = Client.take(2)
# => [
#   #<Client id: 1, first_name: "Lifo">,
#   #<Client id: 220, first_name: "Sara">
# ]
</syntaxhighlight>استعلام [[SQL]] الموافق للتعليمة السابقة هو:<syntaxhighlight lang="sql">
SELECT * FROM clients LIMIT 2
</syntaxhighlight>إن التابع <code>!take</code> يعمل تمامًا مثل التابع <code>take</code>، إلا أنّه يرمي استثناء من النوع <code>ActiveRecord::RecordNotFound</code> في حال عدم العثور على أي سجل.

'''ملاحظة''': قد يختلف السجل المعاد بناءً على محرك قاعدة البيانات المستخدم.

==== التابع <code>first</code> ====
يبحث التابع <code>first</code> عن أول سجل، مرتّب حسب ترتيب المفتاح الرئيسي (بشكل افتراضي). مثلًا:<syntaxhighlight lang="rails">
client = Client.first
# => #<Client id: 1, first_name: "Lifo">

</syntaxhighlight>استعلام [[SQL]] الموافق للتعليمة السابقة هو:<syntaxhighlight lang="sql">
SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1
</syntaxhighlight>يعيد التابع <code>first</code> القيمة <code>nil</code> في حال لم يتم العثور على أي سجل، ولن يتم رمي استثناء.

في حال احتوى النطاق الافتراضي على تابع ترتيب، سيعيد التابع <code>first</code> السجل الأول بناءً على الترتيب المحدد في النطاق.

يمكنك تمرير وسيط عددي للتابع <code>first</code> لإعادة مجموعة السجلات التي عددها يوافق الوسيط الممرر. مثلًا:<syntaxhighlight lang="rails">
clients = Client.first(3)
# => [
#   #<Client id: 1, first_name: "Lifo">,
#   #<Client id: 2, first_name: "Fifo">,
#   #<Client id: 3, first_name: "Filo">
# ]
</syntaxhighlight>استعلام [[SQL]] الموافق للتعليمة السابقة هو:<syntaxhighlight lang="sql">
SELECT * FROM clients ORDER BY clients.id ASC LIMIT 3
</syntaxhighlight>عند استخدام التابع <code>first</code> على مجموعة مرتبة باستخدام التابع <code>order</code>، سيعيد التابع <code>first</code> أول سجل بناءً على الترتيب المحدد في التابع <code>order</code>.<syntaxhighlight lang="rails">
client = Client.order(:first_name).first
# => #<Client id: 2, first_name: "Fifo">
</syntaxhighlight>استعلام [[SQL]] الموافق للتعليمة السابقة هو:<syntaxhighlight lang="sql">
SELECT * FROM clients ORDER BY clients.first_name ASC LIMIT 1
</syntaxhighlight>إن التابع <code>!first</code> يعمل تمامًا مثل التابع <code>first</code> إلا أنّه يرمي استثناء من النوع <code>ActiveRecord::RecordNotFound</code> في حال عدم العثور على أي سجل.

==== التابع <code>last</code> ====
يبحث التابع <code>last</code> عن آخر سجل، مرتّب حسب المفتاح الرئيسي (بشكل افتراضي). مثلًا:<syntaxhighlight lang="rails">
client = Client.last
# => #<Client id: 221, first_name: "Russel">
</syntaxhighlight>استعلام [[SQL]] الموافق للتعليمة السابقة هو:<syntaxhighlight lang="sql">
SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1
</syntaxhighlight>يعيد التابع <code>last</code> القيمة <code>nil</code> في حال لم يتم العثور على أي سجل، ولن يتم رمي استثناء.

في حال احتوى النطاق الافتراضي على تابع ترتيب، سيعيد التابع <code>last</code> السجل الأول بناءً على الترتيب المحدد في النطاق.

يمكنك تمرير وسيط رقمي للتابع <code>last</code> لإعادة مجموعة السجلات التي عددها يوافق الوسيط الممرر. مثلًا:<syntaxhighlight lang="rails">
clients = Client.last(3)
# => [
#   #<Client id: 219, first_name: "James">,
#   #<Client id: 220, first_name: "Sara">,
#   #<Client id: 221, first_name: "Russel">
# ]
</syntaxhighlight>استعلام [[SQL]] الموافق للتعليمة السابقة هو:<syntaxhighlight lang="sql">
SELECT * FROM clients ORDER BY clients.id DESC LIMIT 3
</syntaxhighlight>عند استخدام التابع <code>last</code> على مجموعة مرتبة باستخدام التابع <code>order</code>، سيعيد التابع <code>last</code> آخر سجل بناءً على الترتيب المحدد في التابع <code>order</code>.<syntaxhighlight lang="rails">
client = Client.order(:first_name).last
# => #<Client id: 220, first_name: "Sara">
</syntaxhighlight>استعلام [[SQL]] الموافق للتعليمة السابقة هو:<syntaxhighlight lang="sql">
SELECT * FROM clients ORDER BY clients.first_name DESC LIMIT 1
</syntaxhighlight>إن التابع <code>!last</code> يعمل تمامًا مثل التابع <code>last</code> إلا أنّه يرمي استثناء من النوع <code>ActiveRecord::RecordNotFound</code> في حال عدم العثور على أي سجل.

==== التابع <code>find_by</code> ====
يبحث التابع <code>find_by</code> عن أول سجل يطابق الشروط المعطاة. مثلًا:<syntaxhighlight lang="rails">
Client.find_by first_name: 'Lifo'
# => #<Client id: 1, first_name: "Lifo">
 
Client.find_by first_name: 'Jon'
# => nil
</syntaxhighlight>يماثل كتابة:<syntaxhighlight lang="rails">
Client.where(first_name: 'Lifo').take
</syntaxhighlight>استعلام [[SQL]] الموافق للتعليمة السابقة هو:<syntaxhighlight lang="sql">
SELECT * FROM clients WHERE (clients.first_name = 'Lifo') LIMIT 1
</syntaxhighlight>إن التابع <code>!find_by</code> يعمل تمامًا مثل التابع <code>find_by</code> إلا أنّه يرمي استثناء من النوع <code>ActiveRecord::RecordNotFound</code> في حال عدم العثور على أي سجل. مثلًا:<syntaxhighlight lang="rails">
Client.find_by! first_name: 'does not exist'
# => ActiveRecord::RecordNotFound
</syntaxhighlight>هذا يماثل كتابة:<syntaxhighlight lang="rails">
Client.where(first_name: 'does not exist').take!
</syntaxhighlight>

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

قد تبدو هذه القضية سهلة:<syntaxhighlight lang="rails">
# سيأخذ هذا حيّزًا كبيرًا من الذاكرة في حال كان الجدول كبيرًا جدًا
User.all.each do |user|
 NewsMailer.weekly(user).deliver_now
end


</syntaxhighlight>لكن هذا الحل يصبح غير عملي عند ازدياد حجم الجدول، بما أن التابع <code>User.all.each</code> يخبر [[Rails/active record|Active Record]] بضرورة تحميل كل الجدول في مرور واحد، وبناء كائن لكل سجل، ومن ثم الحفاظ على كامل مصفوفة كائنات النموذج في الذاكرة. بالطبع، عندما نملك كمًا كبيرًا من السجلات، قد يزيد حجم المجموعة عن الحجم المسموح حجزه في الذاكرة أساسًا.

يزوّد ريلز بتابعين لحل هذه المشكلة وتقسيم السجلات على دفعات مناسبة للذاكرة من أجل معالجتها. التابع الأول هو <code>find_each</code> الذي يسترد دفعة من السجلات ومن ثم يدفع كل سجل إلى الكتلة المعطاة بشكل إفرادي ككائن من النموذج. أمَّا التابع الثاني فهو <code>find_in_batches</code>  الذي يسترد دفعة من السجلات ومن ثم يدفع كامل الدفعة إلى الكتلة المعطاة كمصفوفة من كائنات النموذج.

'''ملاحظة''': يراد استعمال التوابع <code>find_each</code> و <code>find_in_batches</code> لمعالجة عدد كبير من السجلات التي لا تتسع في الذاكرة بآنٍ معًا. إذا احتجت فقط للمرور على ألف سجل مثلًا، يفضّل استخدام توابع البحث العادية.

==== التابع <code>find_each</code> ====
يجلب التابع <code>find_each</code> دفعة من السجلات ومن ثم يدفع كل سجل من هذه السجلات إلى الكلتة المعطاة. في المثال التالي، يسترد التابع <code>find_each</code> المستخدمين على دفعات من 1000 عنصر، ومن ثم يدفعها إلى الكتلة واحدة تلو الأخرى:<syntaxhighlight lang="rails">
User.find_each do |user|
  NewsMailer.weekly(user).deliver_now
end
</syntaxhighlight>تعاد هذه العملية، ويتم استرداد المزيد من الدفعات عند الحاجة، حتى تتم معالجة جميع السجلات.

يعمل التابع <code>find_each</code> على أصناف النماذج، كما هو مبين أعلاه، إضافةً إلى العلاقات:<syntaxhighlight lang="rails">
User.where(weekly_subscriber: true).find_each do |user|
  NewsMailer.weekly(user).deliver_now
end
</syntaxhighlight>طالما أنَّ العلاقات لا تملك ترتيبًا معينًا، التابع <code>find_each</code> سيحتاج إلى فرض ترتيب معين داخليًا للمرور على العناصر.

في حال وجود ترتيب معين في المستقبل، سيعتمد السلوك على الراية <code>config.active_record.error_on_ignored_order</code>. في حال كانت قيمتها <code>true</code>، سيتم رمي الاستثناء <code>ArgumentError</code>، وإلّا سيتم تجاهل الترتيب وتزويد تحذير، وهو السلوك الافتراضي. يمكن تجاوز هذا السلوك عن طريق الخيار <code>error_on_ignore:</code>، كما هو مشروح أدناه.

===== خيارات التابع <code>find_each</code> =====

====== <code>batch_size:</code> ======
يمكّنك هذا الخيار من تحديد عدد السجلات المراد جلبها في كل دفعة، قبل دفعها بشكل إفرادي إلى الكتلة. مثلًا، لقراءة السجلات على دفعات من 5000 عنصر:<syntaxhighlight lang="rails">
User.find_each(batch_size: 5000) do |user|
  NewsMailer.weekly(user).deliver_now
end
</syntaxhighlight>

====== <code>start:</code> ======
بشكل افتراضي، يتم استرداد السجلات بترتيب تصاعدي بناءً على المفتاح الرئيسي، الذي يجب أن يكون قيمة صحيحة. يمكّنك الخيار <code>start:</code> من تحديد أول معرّف من السلسلة عندما لا يكون أصغر معرّف هو المعرّف المطلوب. قد يكون هذا مفيدًا على سبيل المثال عندما تريد إعادة بدء معالجة دفعة محددة تمّت مقاطعتها، بفرّض أنّك تملك آخر معرّف تمّت معالجته كنقطة تحقق.

مثلًا، لإرسال رسائل بريدية لمستخدمي القائمة البريدية التي تبدأ معرّفاتهم بالقيمة 2000:<syntaxhighlight lang="rails">
User.find_each(start: 2000) do |user|
  NewsMailer.weekly(user).deliver_now
end
</syntaxhighlight>

====== <code>finish:</code> ======
يشبه هذا الخيار الخيار <code>start:</code>، إذ يمكنك من تهيئة آخر معرف من السلسلة عندما لا يكون أعلى معرّف هو المعرّف المطلوب. قد يكون هذا مفيدًا على سبيل المثال في حال أردت معالجة دفعة بيانات محددة بناءً على مجموعة جزئية من السجلات. يمكن تنفيذ هذ ا عبر الخيارين <code>start:</code> و <code>finish:</code>.

مثلًا، لإرسال رسائل بريدية لمستخدمي القائمة البريدية التي تكون معرّفاتهم بين 2000 و 10000:<syntaxhighlight lang="rails">
User.find_each(start: 2000, finish: 10000) do |user|
  NewsMailer.weekly(user).deliver_now
end
</syntaxhighlight>مثال آخر عن استخدام هذين الخيارين معًا هو في حال أردت من مجموعة من العمليات العاملة (workers) أن تعالج نفس رتل المعالجة. يمكنك تحديد 10000 سجل لكل عملية عاملة عن طريق تحديد الخيارين <code>start:</code> و <code>finish:</code> لكل عملية.

====== <code>error_on_ignore:</code> ======
يتجاوز تهيئة التطبيق الافتراضية ويحدّد فيما إذا وجب رمي استثناء عند وجود ترتيب معين على العلاقة.

==== التابع <code>find_in_batches</code> ====
إن التابع <code>find_in_batches</code> مماثل جدًا للتابع <code>find_each</code>، بما أن كليهما يجلبان دفعات من السجلات. يقع موقع الاختلاف في طريقة دفع الكائنات إلى الكتلة المعطاة، إذ يدفع التابع <code>find_in_batches</code> دفعات من الكائنات إلى الكتلة كمصفوفة كائنات النموذج، بدلًا من الطريقة الإفرادية. يبيّن المثال التالي طريقة استخدام التابع عند دفع مصفوفة من 1000 فاتورة على حدة إلى الكتلة المعطاة، مع احتواء الكتلة الأخيرة على الفواتير المتبقية:<syntaxhighlight lang="rails">
# بـ 1000 فاتورة بآن معًا add_invoices يزوّد التابع
Invoice.find_in_batches do |invoices|
 export.add_invoices(invoices)
end


</syntaxhighlight>يعمل التابع <code>find_in_batches</code> على أصناف النماذج، كما هو مبين أعلاه، إضافةً إلى العلاقات:<syntaxhighlight lang="rails">
Invoice.pending.find_in_batches do |invoices|
  pending_invoices_export.add_invoices(invoices)
end
</syntaxhighlight>طالما لا تحتاج العلاقات إلى ترتيب معين، سيحتاج التابع إلى فرض ترتيب معين داخليًا للمرور على العناصر.

===== خيارات التابع <code>find_in_batches</code> =====
يقبل التابع <code>find_in_batches</code> نفس الخيارات التي يقبلها التابع <code>find_each</code>.

== الشروط ==
يمكّنك التابع <code>where</code> من تحديد شروط معيّنة لحدّ عدد السجلات المعادة، والذي يمثل القسم <code>WHERE</code> في استعلام [[SQL]]. يمكن تحديد الشروط إمّا [[Ruby/String|كسلسلة نصية]]، أو [[Ruby/Array|مصفوفة]]، أو [[Ruby/Hash|جدول hash]].

=== شروط السلاسل النصية ===
في حال أردت إضافة شروط إلى بحثك، يمكنك تحديدها مباشرةً، مثل <code>("'Client.where("orders_count = '2</code>. سيبحث هذا عن جميع الزبائن الذين يملكون القيمة 2 للحقل <code>orders_count</code>.

'''تحذير''': إن بناء الشروط عن طريق السلاسل النصية قد يجعل تطبيقك عرضةً لهجمات حقن الاستعلامات (SQL Injection). مثلًا، الاستعلام التالي غير آمن:<syntaxhighlight lang="rails">
Client.where("first_name LIKE '%#{params[:first_name]}%'")
</syntaxhighlight>أكمل قراءة القسم التالي من أجل التعرف على الطريقة المفضلة لمعالجة الشروط باستخدام المصفوفات.

=== الشروط المصفوفية ===
ماذا لو احتجت إلى تغيير الرقم السابق مثلًا ليكون وسيطًا من مكان آخر؟ سيأخذ تابع البحث الشكل التالي:<syntaxhighlight lang="rails">
Client.where("orders_count = ?", params[:orders])
</syntaxhighlight>يأخذ [[Rails/active record|Active Record]] السلسلة النصية من الشروط المطلوبة وسيطًا أولًا له، وأيّة وسطاء إضافية ستحل مكان المحرف <code>?</code> في السلسلة المعطاة.

في حال أردت تحديد مجموعة من الشروط:<syntaxhighlight lang="rails">
Client.where("orders_count = ? AND locked = ?", params[:orders], false)
</syntaxhighlight>في هذا المثال، سيتم استبدال أول إشارة استفهام بالقيمة <code>[params[:orders</code>، والثانية بالقيمة <code>false</code>.

إن التعليمة التالية هي المفضلة بشدة:<syntaxhighlight lang="rails">
Client.where("orders_count = ?", params[:orders])
</syntaxhighlight>عن استعمال التعليمة التالية:<syntaxhighlight lang="rails">
Client.where("orders_count = #{params[:orders]}")
</syntaxhighlight>بسبب أمان الوسائط.

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

'''ملاحظة''': للمزيد من المعلومات حول مخاطر حقن الاستعلامات، اقرأ [[Rails/security|دليل الأمان]].

==== الشروط النائبة ====
بشكل مماثل لطريقة استبدال إشارة الاستفهام بالوسائط، يمكنك أيضًا تحديد مفاتيح في سلسلة الشروط النصية مع مفاتيح/قيم الكائن <code>[[Ruby/Hash|Hash]]</code> الممرر:<syntaxhighlight lang="rails">
Client.where("created_at >= :start_date AND created_at <= :end_date",
  {start_date: params[:start_date], end_date: params[:end_date]})
</syntaxhighlight>سيعزّز هذا سهولة قراءة التعليمات بوجود مجموعة كبيرة من الشروط المتغيرة.

=== شروط الكائن <code>[[Ruby/Hash|Hash]]</code> ===
يمكّنك [[Rails/active record|Active Record]] من تمرير شروط على شكل كائن <code>[[Ruby/Hash|Hash]]</code> والتي تزيد من قابلية قراءة نمط كتابة الشروط. باستخدام شروط <code>[[Ruby/Hash|Hash]]</code>، يمكنك تمرير <code>[[Ruby/Hash|Hash]]</code> بالمفاتيح التي تمثل الحقول التي تريد التحقق منها، والقيم التي تحدد القيم المطلوبة لهذه الحقول:

'''ملاحظة''': يمكن فقط استخدام تحقق المساواة، والمجال، والمجموعة الجزئية في شروط <code>[[Ruby/Hash|Hash]]</code>.

==== شروط المساواة ====
<syntaxhighlight lang="rails">
Client.where(locked: true)
</syntaxhighlight>سيولّد هذا استعلام [[SQL]] التالي:<syntaxhighlight lang="sql">
SELECT * FROM clients WHERE (clients.locked = 1)
</syntaxhighlight>يمكن أن يكون اسم الحقل أيضًا سلسلة نصية:<syntaxhighlight lang="rails">
Client.where('locked' => true)
</syntaxhighlight>في حالة ارتباط الانتماء (belongs_to)، يمكن استخدام مفتاح الارتباط لتحديد فيما إذا كان من المراد استخدام كائن [[Rails/active record|Active Record]] كالقيمة الممررة. يعمل هذا التابع مع العلاقات متعددة الأشكال أيضًا.<syntaxhighlight lang="rails">
Article.where(author: author)
Author.joins(:articles).where(articles: { author: author })
</syntaxhighlight>

==== شروط المجال ====
<syntaxhighlight lang="rails">
Client.where(created_at: (Time.now.midnight - 1.day)..Time.now.midnight)
</syntaxhighlight>سيبحث هذا عن الزبائن الذين تم إنشاؤهم البارحة باستخدام استعلام <code>BETWEEN</code>.<syntaxhighlight lang="sql">
SELECT * FROM clients WHERE (clients.created_at BETWEEN '2008-12-21 00:00:00' AND '2008-12-22 00:00:00')
</syntaxhighlight>يمثّل هذا استخدامًا أبسط من الشروط المصفوفية.

==== شروط المجموعات الجزئية ====
إذا أردت البحث عن السجلات باستخدام تعليمة <code>IN</code>، يمكنك تمرير مصفوفة للكائن <code>[[Ruby/Hash|Hash]]</code> الممثل للشرط:<syntaxhighlight lang="rails">
Client.where(orders_count: [1,3,5])
</syntaxhighlight>سيولّد هذا استعلام [[SQL]] التالي:<syntaxhighlight lang="sql">
SELECT * FROM clients WHERE (clients.orders_count IN (1,3,5))
</syntaxhighlight>

=== شروط النفي NOT ===
يمكن بناء شروط النفي باستخدام <code>where.not</code>:<syntaxhighlight lang="rails">
Client.where.not(locked: true)
</syntaxhighlight>كتعبير آخر، يمكن توليد هذا الاستعلام عن طريق استدعاء التابع <code>where</code> بدون وسائط، ومن ثم سلسلته مع التابع <code>not</code> وتمرير شروط <code>where</code>. سيولّد هذا استعلام [[SQL]] التالي:<syntaxhighlight lang="sql">
SELECT * FROM clients WHERE (clients.locked != 1)
</syntaxhighlight>

=== شروط OR ===
يمكن استخدام شروط OR بين علاقتين عن طريق استدعاء التابع Or على أول علاقة، ومن ثم تمرير الثانية كوسيط لهذا التابع.<syntaxhighlight lang="rails">
Client.where(locked: true).or(Client.where(orders_count: [1,3,5]))
</syntaxhighlight><syntaxhighlight lang="sql">
SELECT * FROM clients WHERE (clients.locked = 1 OR clients.orders_count IN (1,3,5))
</syntaxhighlight>

== الترتيب ==
لجلب السجلات من قاعدة البيانات بترتيب معين، يمكنك استخدام التابع <code>order</code>.

مثلًا، لاسترداد مجموعة من السجلات المرتّبة تصاعديًا حسب الحقل <code>created_at</code> في الجدول، جرب ما يلي:<syntaxhighlight lang="rails">
Client.order(:created_at)
# OR
Client.order("created_at")
</syntaxhighlight>يمكنك أيضًا تحديد فيما إذا كان التحديد تصاعدي (ASC) أو تنازلي (DESC):<syntaxhighlight lang="rails">
Client.order(created_at: :desc)
# OR
Client.order(created_at: :asc)
# OR
Client.order("created_at DESC")
# OR
Client.order("created_at ASC")
</syntaxhighlight>أو الترتيب عن طريق مجموعة من الحقول:<syntaxhighlight lang="rails">
Client.order(orders_count: :asc, created_at: :desc)
# OR
Client.order(:orders_count, created_at: :desc)
# OR
Client.order("orders_count ASC, created_at DESC")
# OR
Client.order("orders_count ASC", "created_at DESC")
</syntaxhighlight>في حال أردت استدعاء الترتيب عدة مرات، يمكنك سلسلة مجموعة الاستدعاءات كالتالي:<syntaxhighlight lang="rails">
Client.order("orders_count ASC").order("created_at DESC")
# SELECT * FROM clients ORDER BY orders_count ASC, created_at DESC
</syntaxhighlight>'''تحذير''': عند استخدامك الإصدار 5.7.5 وما فوقه من MySQL، فعند اختيارك للحقول باستخدام التوابع مثل <code>select</code> و <code>pluck</code> و <code>ids</code>، سيرمي التابع <code>order</code> استثناءً من النوع <code>ActiveRecord::StatementInvalid</code> إلّا إذا كانت الحقول المستخدمة للترتيب مضمّنة في قائمة الحقول المختارة. اطلع على القسم التالي من أجل اختيار الحقول في مجموعة النتائج.

== اختيار حقول محددة ==
افتراضيًا، يختار التابع <code>Model.find</code> جميع الحقول في مجموعة النتائج عن طريق استخدام <code>* select</code>. لاختيار مجموعة جزئية فقط من الحقول، يمكنك تحديدها باستخدام التابع <code>select</code>.

مثلًا، لاختيار الحقول <code>viewable_by</code> و <code>locked</code>:<syntaxhighlight lang="rails">
Client.select("viewable_by, locked")
</syntaxhighlight>استعلام [[SQL]] المستخدم من قبل تعليمة البحث هذه ستبدو كالتالي:<syntaxhighlight lang="sql">
SELECT viewable_by, locked FROM clients
</syntaxhighlight>كن حذرًا لأن هذا يعني أنّك ستهيّء كائنًا بالحقول المختارة فقط. في حال حاولت الوصول لحقول غير مختارة، فستحصل على الخطأ التالي:<syntaxhighlight lang="text">
ActiveModel::MissingAttributeError: missing attribute: <attribute>
</syntaxhighlight>حيث تكون <code><attribute></code> هو الخاصية المختارة. لن يرمِ التابع <code>id</code> أي استثناء، لذا من المفضل أن تكون حذرًا عند التعامل مع الارتباطات، لأنها تحتاج من التابع <code>id</code> أن يعمل بشكل صحيح.

في حال أردت التقاط سجل وحيد من أجل كل قيمة فريدة في حقل معين، يمكنك استخدام <code>distinct</code>:<syntaxhighlight lang="rails">
Client.select(:name).distinct
</syntaxhighlight>ستولّد التعليمة السابقة استعلام [[SQL]] التالي:<syntaxhighlight lang="sql">
SELECT DISTINCT name FROM clients
</syntaxhighlight>يمكنك أيضًا حذف قيد الفردية:<syntaxhighlight lang="rails">
query = Client.select(:name).distinct
# => يعيد الأسماء الفريدة

query.distinct(false)
# => يعيد جميع الأسماء، حتى في وجود التكرارات


</syntaxhighlight>

== الحد وتجاوز السجلات ==
لتطبيق تعليمة الحد <code>LIMIT</code> على استعلام [[SQL]] المنفذ من قبل التابع <code>Model.find</code>، يمكنك تحديده باستخدام التابعين <code>limit</code> و <code>offset</code> على العلاقة.

يمكنك استخدام التابع <code>limit</code> لتحديد عدد السجلات المراد جلبها، والتابع <code>offset</code> لتحديد عدد السجلات المراد تجاوزها قبل البدء بإعادة السجلات. مثلًا:<syntaxhighlight lang="rails">
Client.limit(5)
</syntaxhighlight>سيعيد 5 زبائن كحد أقصى. بنا أنه لا يتجاوز السجلات، فسيعيد أول 5 سجلات من الجدول. سيبدو استعلام [[SQL]] المنفذ كالتالي:<syntaxhighlight lang="sql">
SELECT * FROM clients LIMIT 5
</syntaxhighlight>وبإضافة التابع <code>offset</code>:<syntaxhighlight lang="rails">
Client.limit(5).offset(30)
</syntaxhighlight>سيعاد 5 زبائن بشكل أعظمي بدءًا من الزبون ذي الرقم 31. سيبدو استعلام [[SQL]] كالتالي:<syntaxhighlight lang="rails">
SELECT * FROM clients LIMIT 5 OFFSET 30
</syntaxhighlight>

== التجميع ==
لتطبيق تعليمة التجميع <code>[[SQL/group by|GROUP BY]]</code> على استعلام [[SQL]] المنفذ من توابع البحث، يمكنك استخدام التابع <code>group</code>.

مثلًا، إذا أردت البحث عن مجموعة التواريخ التي أُنشئت فيها الطلبات:<syntaxhighlight lang="rails">
Order.select("date(created_at) as ordered_date, sum(price) as total_price").group("date(created_at)")
</syntaxhighlight>وهذا سيعطيك كائنًا وحيدًا من النوع <code>Order</code> من أجل كل تاريخ أنشئت فيه طلبات في قاعدة البيانات.

سيبدو استعلام [[SQL]] كالتالي:<syntaxhighlight lang="rails">
SELECT date(created_at) as ordered_date, sum(price) as total_price
FROM orders
GROUP BY date(created_at)
</syntaxhighlight>

=== مجموع العناصر المجمعة ===
للحصول على مجموع العناصر المجمعة في استعلام وحيد، يمكنك استدعاء التابع <code>count</code> بعد التابع <code>group</code>.<syntaxhighlight lang="rails">
Order.group(:status).count
# => { 'awaiting_approval' => 7, 'paid' => 12 }
</syntaxhighlight>سيبدو استعلام SQL المنفذ كالتالي:<syntaxhighlight lang="sql">
SELECT COUNT (*) AS count_all, status AS status
FROM "orders"
GROUP BY status
</syntaxhighlight>

== تعليمة <code>Having</code> ==
تستخدم [[SQL]] التعليمة <code>[[SQL/having|HAVING]]</code> لوضع شروط على الحقول المجمعة باستخدام <code>[[SQL/group by|GROUP BY]]</code>. يمكنك إضافة هذه الشروط في بنية <code>[[SQL/having|HAVING]]</code> للتابع <code>Model.find</code> عن طريق إضافة التابع <code>having</code> إلى تابع البحث. إليك مثال عن ذلك:<syntaxhighlight lang="rails">
Order.select("date(created_at) as ordered_date, sum(price) as total_price").
  group("date(created_at)").having("sum(price) > ?", 100)
</syntaxhighlight>سيبدو استعلام [[SQL]] المنفذ كالتالي:<syntaxhighlight lang="sql">
SELECT date(created_at) as ordered_date, sum(price) as total_price
FROM orders
GROUP BY date(created_at)
HAVING sum(price) > 100
</syntaxhighlight>سيعيد هذا التاريخ ومجموع أسعار كل كائن طلب، بعد تجميعهم عن طريق تاريخ إنشاء الطلب، حيث يكون مجموع أسعار الطلبات أكثر من 100$.

== تجاوز الشروط ==

=== التابع <code>unscope</code> ===
يمكنك تحديد شروط معينة لتتم إزالتها باستخدام التابع <code>unscope</code>. مثلًا:<syntaxhighlight lang="rails">
Article.where('id > 10').limit(20).order('id asc').unscope(:order)
</syntaxhighlight>سيبدو استعلام [[SQL]] كالتالي:<syntaxhighlight lang="sql">
SELECT * FROM articles WHERE id > 10 LIMIT 20

# unscope الاستعلام الأساسي دون استدعاء
SELECT * FROM articles WHERE id > 10 ORDER BY id asc LIMIT 20


</syntaxhighlight>يمكنك أيضًا تجاوز بنى شروط <code>where</code> أيضًا. مثلًا:<syntaxhighlight lang="rails">
Article.where(id: 10, trashed: false).unscope(where: :id)
# SELECT "articles".* FROM "articles" WHERE trashed = 0
</syntaxhighlight>العلاقة التي تستخدم التابع <code>unscope</code> تأثر أيضًا على أي علاقة مدمجة معها:<syntaxhighlight lang="rails">
Article.order('id asc').merge(Article.unscope(:order))
# SELECT "articles".* FROM "articles"
</syntaxhighlight>

=== التابع <code>only</code> ===
يمكنك أيضًا تجاوز الشروط عن طريق التابع <code>only</code>. مثلًا:<syntaxhighlight lang="rails">
Article.where('id > 10').limit(20).order('id desc').only(:order, :where)
</syntaxhighlight>سيبدو استعلام [[SQL]] المنفذ كالتالي:<syntaxhighlight lang="sql">
SELECT * FROM articles WHERE id > 10 ORDER BY id DESC

# الاستعلام الأصلي دون التابع only
SELECT * FROM articles WHERE id > 10 ORDER BY id DESC LIMIT 20


</syntaxhighlight>

=== التابع <code>reorder</code> ===
يتجاوز التابع <code>reorder</code> الترتيب المجالي الافتراضي. مثلًا:<syntaxhighlight lang="rails">
class Article < ApplicationRecord
  has_many :comments, -> { order('posted_at DESC') }
end
 
Article.find(10).comments.reorder('name')
</syntaxhighlight>سيبدو استعلام [[SQL]] كالتالي:<syntaxhighlight lang="sql">
SELECT * FROM articles WHERE id = 10 LIMIT 1
SELECT * FROM comments WHERE article_id = 10 ORDER BY name
</syntaxhighlight>في حال عدم استخدام التابع <code>reorder</code>، سيبدو استعلام [[SQL]] المنفذ كالتالي:<syntaxhighlight lang="sql">
SELECT * FROM articles WHERE id = 10 LIMIT 1
SELECT * FROM comments WHERE article_id = 10 ORDER BY posted_at DESC
</syntaxhighlight>

=== التابع <code>reverse_order</code> ===
يعكس التابع <code>reverse_order</code> الترتيب المحدد سابقًا.<syntaxhighlight lang="rails">
Client.where("orders_count > 10").order(:name).reverse_order
</syntaxhighlight>سيبدو استعلام [[SQL]] المنفذ كالتالي:<syntaxhighlight lang="sql">
SELECT * FROM clients WHERE orders_count > 10 ORDER BY name DESC
</syntaxhighlight>في حال عدم تحديد ترتيب سابقًا، يعكس التابع <code>reverse_order</code> ترتيب السجلات حسب حقل المفتاح الرئيسي.<syntaxhighlight lang="rails">
Client.where("orders_count > 10").reverse_order
</syntaxhighlight>سيبدو استعلام [[SQL]] المنفذ كالتالي:<syntaxhighlight lang="sql">
SELECT * FROM clients WHERE orders_count > 10 ORDER BY clients.id DESC
</syntaxhighlight>لا يقبل هذا التابع أيّة وسائط.

=== التابع <code>rewhere</code> ===
يتجاوز التابع <code>rewhere</code> شروط <code>where</code> موجودة مسبقًا ومسمّاة. مثلًا:<syntaxhighlight lang="rails">
Article.where(trashed: true).rewhere(trashed: false)
</syntaxhighlight>سيبدو استعلام [[SQL]] المنفذ كالتالي:<syntaxhighlight lang="sql">
SELECT * FROM articles WHERE `trashed` = 0
</syntaxhighlight>في حال عدم استخدام التابع <code>rewhere</code>:<syntaxhighlight lang="rails">
Article.where(trashed: true).where(trashed: false)
</syntaxhighlight>سيبدو استعلام [[SQL]] المنفذ كالتالي:<syntaxhighlight lang="sql">
SELECT * FROM articles WHERE `trashed` = 1 AND `trashed` = 0
</syntaxhighlight>

== العلاقة الفارغة (Null Relation) ==
يعيد التابع <code>none</code> علاقة قابلة للسلسلة بدون سجلات، إذ عند سلسلة المزيد من الشروط للعلاقة المعادة، سيتم توليد المزيد من العلاقات الفارغة. يفيد هذا في الحالات التي تحتاج بها إلى رد قابل للسلسلة لتابع أو نطاق يمكن أن لا يعيد سجلات إطلاقًا.<syntaxhighlight lang="rails">
Article.none # يعيد علاقة فارغة ولا ينفذ أي استعلامات
</syntaxhighlight><syntaxhighlight lang="rails">
# أدناه من المتوقع أن يعيد علاقة visible_articles التابع
@articles = current_user.visible_articles.where(name: params[:name])
 
def visible_articles
  case role
  when 'Country Manager'
    Article.where(country: country)
  when 'Reviewer'
    Article.published
  when 'Bad User'
    Article.none # => returning [] or nil breaks the caller code in this case
  end
end
</syntaxhighlight>

== كائنات القراءة فقط ==
يزوّد Active Record بالتابع <code>readonly</code> في العلاقات لتحديد عدم إمكانية تعديل أي من الكائنات المعادة بشكل ظاهري. لن تنجح أي عملية لتعديل سجلات القراءة فقط، الأمر الذي يرمي استنثناءً من النوع <code>ActiveRecord::ReadOnlyRecord</code>.<syntaxhighlight lang="rails">
client = Client.readonly.first
client.visits += 1
client.save
</syntaxhighlight>بما أن الكائن <code>client</code> محدد ليكون قابلًا للقراءة فقط، سترمي التعليمات السابقة استثناءً من النوع <code>ActiveRecord::ReadOnlyRecord</code> عند استدعاء التابع <code>client.save</code> بالقيمة المحدثة للحقل <code>visits</code>.

== منع تعديل السجلات ==
إن عملية القفل هي عملية مفيدة لتجنب حالات التسابق (أو حالات التعارض - Race Conditions) عند تحديث السجلات في قاعدة البيانات.

يزوّد [[Rails/active record|Active Record]] بطريقتان للقفل:
* القفل المستبشر (Optimistic Locking).
* القفل المستطير (Pessimistic Locking).

=== القفل المستبشر ===
يمكّن القفل المستبشر مجموعة من المستخدمين الوصول إلى السجل ذاته من أجل التعديل، ويفرض أن عددًا أصغريًا من التعارضات تحصل في البيانات. يقوم بذلك عن طريق التحقق فيما إذا قامت عملية أخرى بتعديلات على السجل منذ فتحه. سيرمى الاستثناء <code>ActiveRecord::StaleObjectError</code> في حال حصل ذلك، وسيتم تجاهل التحديث.

==== حقل القفل المستبشر ====
لاستخدام القفل المستبشر، يجب على الجدول أن يحوي حقلًا يسمى <code>lock_version</code> من نوع القيمة الصحيحة (integer). عند تحديث سجل، يزيد [[Rails/active record|Active Record]] قيمة الحقل <code>lock_version</code>. في حال طلب تحديث بقيمة <code>lock_version</code> أصغر من القيمة الموجودة حاليًا في الحقل <code>lock_version</code> في قاعدة البيانات، سيفشل التعديل وسيرمى الاستثناء <code>ActiveRecord::StaleObjectError</code>. مثلًا:<syntaxhighlight lang="rails">
c1 = Client.find(1)
c2 = Client.find(1)
 
c1.first_name = "Michael"
c1.save
 
c2.name = "should fail"
c2.save # Raises an ActiveRecord::StaleObjectError
</syntaxhighlight>ستكون مسؤولًا بالتالي عن التحقق من التضاربات، سواءً عن طريق المرور التعاودي في الاستثناء أو عن طريق الاستعادة أو الدمج أو تطبيق منطق عمل مختلف لإصلاح التضارب.

يمكن تعطيل هذا السلوط عن طريق تعيين الخيار <code>ActiveRecord::Base.lock_optimistically</code> للقيمة <code>false</code>.

لتجاوز اسم الحقل <code>lcok_version</code>، يزوّد الصنف <code>ActiveRecord::Base</code> خاصية تدعى <code>locking_column</code>:<syntaxhighlight lang="rails">
class Client < ApplicationRecord
  self.locking_column = :lock_client_column
end
</syntaxhighlight>

=== القفل المستطير ===
يستخدم القفل غير الفعال طريقة قفل مزودة من قبل طبقة قاعدة البيانات. باستخدام التابع <code>lock</code> عند بناء علاقة، سيتم بناء قفل حصري (exclusive lock) على السجلات المحددة. إن العلاقات التي تستخدم التابع <code>lock</code> تكون محاطة بعملية (transaction) معظم الأوقات، وذلك لتجنب حالات القفل الميت (deadlock).

مثلًا:<syntaxhighlight lang="rails">
Item.transaction do
  i = Item.lock.first
  i.name = 'Jones'
  i.save!
end
</syntaxhighlight>الجلسة السابقة تولّد استعلام [[SQL]] التالي من أجل قاعدة بيانات MySQL:<syntaxhighlight lang="sql">
SQL (0.2ms)   BEGIN
Item Load (0.3ms)   SELECT * FROM `items` LIMIT 1 FOR UPDATE
Item Update (0.4ms)   UPDATE `items` SET `updated_at` = '2009-02-07 18:05:56', `name` = 'Jones' WHERE `id` = 1
SQL (0.8ms)   COMMIT
</syntaxhighlight>يمكنك أيضًا تمرير تعليمات [[SQL]] خام للتابع <code>lock</code> من أجل السماح بأنواع مختلفة من الأقفال. مثلًا، تملك MySQL تعبيرًا يسمّى <code>LOCK IN SHARE MODE</code>، حيث يمكنك فيه قفل سجل، والسماح بالاستعلامات الأخرى أن تقرأه. لتحديد هذا التعبير، مرّره كخيار للتابع <code>lock</code>:<syntaxhighlight lang="rails">
Item.transaction do
  i = Item.lock("LOCK IN SHARE MODE").find(1)
  i.increment!(:views)
end
</syntaxhighlight>في حال كان لديك كائنًا من النموذج، يمكنك بدء عملية (transaction) والحصول على القفل باستخدام تعليمة واحدة كالتالي:<syntaxhighlight lang="rails">
item = Item.first
item.with_lock do
 # ستتم استدعاء هذه الكتلة ضمن العملية
 # والعنصر يكون مقفولًا
 item.increment!(:views)
end


</syntaxhighlight>

== دمج الجداول ==
يزوّد [[Rails/active record|Active Record]] بتابعي بحث لتحديد تعليمات الدمج (التعليمة <code>[[SQL/join|JOIN]]</code>) على استعلام [[SQL]] المنفذ: التابع <code>joins</code> والتابع <code>left_outer_joins</code>. في حين أن التابع <code>joins</code> يجب استخدامه من أجل الدمج الداخلي ([[SQL/inner join|<code>INNER JOIN</code>]]) أو الاستعلامات المخصصة، يستخدم التابع <code>left_outer_joins</code> للاستعلامات التي تستخدم الدمج الخارجي (<code>[[SQL/left join|LEFT OUTER JOIN]]</code>).

=== التابع <code>joins</code> ===
هناك عدة طرائق لاستخدام التابع <code>joins</code>.

==== باستخدام قطعة SQL كسلسلة نصية ====
يمكنك تحديد تعليمة [[SQL]] خام لتحديد بنية الدمج <code>[[SQL/join|JOIN]]</code> كسلسلة نصية، وتمريرها للتابع <code>joins</code>:<syntaxhighlight lang="rails">
Author.joins("INNER JOIN posts ON posts.author_id = authors.id AND posts.published = 't'")
</syntaxhighlight>سيولّد هذا استعلام [[SQL]] التالي:<syntaxhighlight lang="sql">
SELECT authors.* FROM authors INNER JOIN posts ON posts.author_id = authors.id AND posts.published = 't'
</syntaxhighlight>

==== باستخدام مصفوفة/كائن Hash من الارتباطات المسماة ====
يمكّنك [[Rails/active record|Active Record]] من استخدام أسماء الارتباطات المعرّفة على النموذج كطريق قصير لتحديد بنية تعليمة الدمج لهذه الارتباطات باستخدام التابع <code>joins</code>.

مثلًا، لنفرض النماذج التالية:<syntaxhighlight lang="rails">
class Category < ApplicationRecord
  has_many :articles
end
 
class Article < ApplicationRecord
  belongs_to :category
  has_many :comments
  has_many :tags
end
 
class Comment < ApplicationRecord
  belongs_to :article
  has_one :guest
end
 
class Guest < ApplicationRecord
  belongs_to :comment
end
 
class Tag < ApplicationRecord
  belongs_to :article
end
</syntaxhighlight>والآن، ستولّد جميع الطرق التالية الدمج الداخلي المتوقع.

===== دمج ارتباط وحيد =====
<syntaxhighlight lang="rails">
Category.joins(:articles)
</syntaxhighlight>سيولّد ذلك:<syntaxhighlight lang="sql">
SELECT categories.* FROM categories
  INNER JOIN articles ON articles.category_id = categories.id

</syntaxhighlight>أو، باللغة الفصيحة: "أعد الكائن <code>Category</code> من أجل جميع الفئات (categories) التي تملك مقالات (articles)". والآن عند رؤيتك لقيم مكررة فهذا يعني أنها تملك أكثر من مقالة واحدة لنفس الفئة. في حال أردت الأصناف الفريدة فقط، يمكنك استخدام:<syntaxhighlight lang="rails">
Category.joins(:articles).distinct
</syntaxhighlight>

==== دمج مجموعة ارتباطات ====
<syntaxhighlight lang="rails">
Article.joins(:category, :comments)
</syntaxhighlight>سيولّد ذلك:<syntaxhighlight lang="sql">
SELECT articles.* FROM articles
  INNER JOIN categories ON categories.id = articles.category_id
  INNER JOIN comments ON comments.article_id = articles.id
</syntaxhighlight>أو، باللغة الفصيحة: "أعد جميع المقالات (articles) التي تملك فئةً (category)، وتعليقًا (comment) واحدًا على الأقل". لاحظ أنه قد تجد مقالات مكررة مجددًا.

===== دمج الارتباطات المتداخلة (مستوى واحد) =====
<syntaxhighlight lang="rails">
Article.joins(comments: :guest)
</syntaxhighlight>سيولّد ذلك:<syntaxhighlight lang="sql">
SELECT articles.* FROM articles
  INNER JOIN comments ON comments.article_id = articles.id
  INNER JOIN guests ON guests.comment_id = comments.id

</syntaxhighlight>أو، باللغة الفصيحة: "أعد جميع المقالات التي تملك تعليقًا مكتوبًا من قبل زائر (guest)".

===== دمج الارتباطات المتداخلة (مستويات متعددة) =====
<syntaxhighlight lang="rails">
Category.joins(articles: [{ comments: :guest }, :tags])
</syntaxhighlight>سيولّد ذلك:<syntaxhighlight lang="sql">
SELECT categories.* FROM categories
  INNER JOIN articles ON articles.category_id = categories.id
  INNER JOIN comments ON comments.article_id = articles.id
  INNER JOIN guests ON guests.comment_id = comments.id
  INNER JOIN tags ON tags.article_id = articles.id
</syntaxhighlight>أو، باللغة الفصيحة: "أعد جميع الأصناف التي تملك مقالات تحتوي بدورها على تعليق مكتوب من قبل زائر، وتحتوي أيضًا على وسم (tag)".

==== تحديد الشروط على الجداول المدمجة ====
يمكنك تحديد شروط على الجداول المدمجة باستخدام الشروط المصفوفية أو النصية المعتادة. يمكن الحصول على نمط خاص لكتابة الشروط للجداول المدمجة باستخدام كائنات <code>[[Ruby/Hash|Hash]]</code>:<syntaxhighlight lang="rails">
time_range = (Time.now.midnight - 1.day)..Time.now.midnight
Client.joins(:orders).where('orders.created_at' => time_range)
</syntaxhighlight>يمكن دمج شروط hash بطريقة أكثر سلاسة وأسهل للقراءة:<syntaxhighlight lang="rails">
time_range = (Time.now.midnight - 1.day)..Time.now.midnight
Client.joins(:orders).where(orders: { created_at: time_range })
</syntaxhighlight>سيبحث ذلك عن كل الزبائن الذين يملكون طلبات أنشئت البارحة، مجدًدا باستخدام تعليمة <code>BETWEEN</code> الخاصة بـ [[SQL]].

=== التابع <code>left_outer_joins</code> ===
في حال أردت اختيار مجموعة من السجلات بغض النظر عن امتلاكها لسجلات مرتبطة، يمكنك استخدام التابع <code>left_outer_joins</code>.<syntaxhighlight lang="rails">
Author.left_outer_joins(:posts).distinct.select('authors.*, COUNT(posts.*) AS posts_count').group('authors.id')
</syntaxhighlight>سيولّد ذلك:<syntaxhighlight lang="sql">
SELECT DISTINCT authors.*, COUNT(posts.*) AS posts_count FROM "authors"
LEFT OUTER JOIN posts ON posts.author_id = authors.id GROUP BY authors.id
</syntaxhighlight>الذي يعني: "أعد جميع الكتّاب (authors) مع عدد المنشورات (posts) الخاصة بهم، بغض النظر عن امتلاكهم أو عدم امتلاكهم للمنشورات".

== التحميل الحثيث للارتباطات ==
إن التحميل الحثيث (Eager loading) هو طريقة من طرائق تحميل ارتباطات السجلات المعادة من التابع <code>Model.find</code>، والتي تستخدم أقل عدد ممكن من الاستعلامات.

=== مشكلة الـ N + 1 استعلام ===
لنفرض التعليمات التالية التي تبحث عن 10 زبائن وتطبع عناوينهم البريدية:<syntaxhighlight lang="rails">
clients = Client.limit(10)
 
clients.each do |client|
  puts client.address.postcode
end
</syntaxhighlight>قد تبدو هذه التعليمات صحيحة من النظرة الأولى، لكن المشكلة تكمن بعدد الاستعلامات المنفذة. ستنفّذ التعليمات السابقة استعلامًا واحدًا من أجل تحميل 10 زبائن، و10 استعلامات من أجل كل زبون لتحميل عنوانه، مما ينفذ 11 استعلام ككل.

=== الحل لمشكلة الـ N + 1 استعلام ===
يمكّنك [[Rails/active record|Active Record]] من تحديد الارتباطات المراد تحميلها بشكل مسبق. يمكن هذا عن طريق تحديد التابع <code>includes</code> لاستدعاء <code>Model.find</code>. باستخدام <code>includes</code>، سيتأكد [[Rails/active record|Active Record]] من أن جميع الارتباطات قد تم تحميلها باستخدام أقل عدد من الاستعلامات.

بالعودة للتعليمات السابقة، يمكننا كتابة التالي لتحميل العناوين بشكل حثيث:<syntaxhighlight lang="rails">
clients = Client.includes(:address).limit(10)
 
clients.each do |client|
  puts client.address.postcode
end
</syntaxhighlight>ستولّد التعليمات السابقة استعلامين فقط، بدلًا من 11 استعلام في الحالة السابقة، وهذه الاستعلامات هي:<syntaxhighlight lang="sql">
SELECT * FROM clients LIMIT 10
SELECT addresses.* FROM addresses
  WHERE (addresses.client_id IN (1,2,3,4,5,6,7,8,9,10))

</syntaxhighlight>

=== التحميل الحثيث لمجموعة من الارتباطات ===
يمكّنك [[Rails/active record|Active Record]] من تحميل مجموعة من الارتباطات بشكل حثيث ضمن استدعاء <code>Model.find</code> وحيد، عن طريق استخدام مصفوفة، كائن <code>[[Ruby/Hash|Hash]]</code>، أو كائن <code>[[Ruby/Hash|Hash]]</code> متداخل مع مصفوفات باستخدام التابع <code>includes</code>.

==== مصفوفة ارتباطات ====
<syntaxhighlight lang="rails">
Article.includes(:category, :comments)
</syntaxhighlight>سيحمّل هذا جميع المقالات والفئات المرتبطة بها والتعليقات لكل مقال.

==== كائنات <code>[[Ruby/Hash|Hash]]</code> المتداخلة للارتباطات ====
<syntaxhighlight lang="rails">
Category.includes(articles: [{ comments: :guest }, :tags]).find(1)
</syntaxhighlight>سيبحث هذا عن الفئة ذات المعرف1 وسيقوم بتحميل حثيث لجميع المقالات المرتبطة، وجميع وسوم المقالات المرتبطة، وتعليقات الزوار المرتبطة أيضًا.

=== فرض شروط على التحميل الحثيث ===
في حين أن [[Rails/active record|Active Record]] يمكّنك من فرض شروط على الارتباطات المحملة بشكل حثيث كما هو الحال في التابع <code>joins</code>، إلّا أنّه من المفضّل استخدام التابع <code>joins</code> بدلًا من ذلك.

لكن إذا أردت استخدام هذه الطريقة، يمكنك استخدام التابع <code>where</code> كما هو الحال طبيعيًا.<syntaxhighlight lang="rails">
Article.includes(:comments).where(comments: { visible: true })
</syntaxhighlight>سيولّد هذا استعلامًا يحوي <code>[[SQL/left join|LEFT OUTER JOIN]]</code>، في حين أنّه يقوم التابع <code>joins</code> بتوليد استعلام يحوي <code>[[SQL/inner join|INNER JOIN]]</code> بدلًا من ذلك.<syntaxhighlight lang="sql">
SELECT "articles"."id" AS t0_r0, ... "comments"."updated_at" AS t1_r5 FROM "articles" LEFT OUTER JOIN "comments" ON "comments"."article_id" = "articles"."id" WHERE (comments.visible = 1)
If 
</syntaxhighlight>في حال عدم وجود شرط <code>where</code>، سيولّد هذا مجموعة عادية من استعلامين.

'''ملاحظة''': إن استخدام <code>where</code>، فسيعمل فقط عند تمريرك للكائن <code>[[Ruby/Hash|Hash]]</code>. من أجل قطع [[SQL]]، يجب أن تستخدم <code>references</code> لفرض دمج الجداول:<syntaxhighlight lang="rails">
Article.includes(:comments).where("comments.visible = true").references(:comments)
</syntaxhighlight>في حال استخدام هذه الطريقة من التحميل، وعند عدم وجود تعليقات لأي من المقالات، سيتم مع ذلك تحميل جميع المقالات. باستخدام <code>joins</code> (أي <code>[[SQL/inner join|INNER JOIN]]</code>)، '''تجب''' مطابقة شرط الدمج، وإلّا لن تعاد أيّة سجلات.

'''ملاحظة''': في حال تمّ تحميل ارتباط بشكل حثيث كجزء من عملية دمج، لن تجد أي حقول مستخدمة في بنية اختيار مخصصة على النماذج المحملة. هذا لتجنب تضارب الحقول بين السجلات الآباء والأبناء.

== النطاقات ==
تمكّنك النطاقات (Scopes) من تحديد استعلامات مستخدمة غالبًا والتي يمكن الرجوع لها كاستدعاءات توابع على الكائنات المرتبطة أو النماذج. مع هذه النطاقات، يمكنك استخدام جميع التوابع المذكورة مسبقًا مثل <code>where</code> و <code>joins</code> و <code>includes</code>. تعيد جميع توابع النطاقات الكائن <code>ActiveRecord::Relation</code> والذي يمكّن التوابع الأخرى (مثل النطاقات الأخرى) من أن يتم استدعاؤها على العلاقة نفسها.

لتعريف نطاق بسيط، يمكنك استخدام التابع <code>scope</code> داخل الصنف، وتمرير الاستعلام المستخدم عند استدعاء النطاق:<syntaxhighlight lang="rails">
class Article < ApplicationRecord
  scope :published, -> { where(published: true) }
end
</syntaxhighlight>يطابق هذا تعريف تابع في الصنف، والطريقة المستخدمة هي حسب تفضيلك الشخصي:<syntaxhighlight lang="rails">
class Article < ApplicationRecord
  def self.published
    where(published: true)
  end
end
</syntaxhighlight>يمكن أيضًا سلسلة النطاقات داخل النطاقات:<syntaxhighlight lang="rails">
class Article < ApplicationRecord
  scope :published,               -> { where(published: true) }
  scope :published_and_commented, -> { published.where("comments_count > 0") }
end
</syntaxhighlight>لاستدعاء النطاق <code>published</code>، يمكننا استدعاؤها إمّا على الصنف:<syntaxhighlight lang="rails">
Article.published # => [published articles]
</syntaxhighlight>أو على ارتباط يحوي على الكائن <code>Article</code>:<syntaxhighlight lang="rails">
category = Category.first
category.articles.published # => [published articles belonging to this category]
</syntaxhighlight>

=== تمرير الوسائط ===
يمكن للنطاقات أن تأخذ وسائطًا مثل:<syntaxhighlight lang="rails">
class Article < ApplicationRecord
  scope :created_before, ->(time) { where("created_at < ?", time) }
end
</syntaxhighlight>ومن ثم استدعاؤها كما لو كانت تابعًا في الصنف:<syntaxhighlight lang="rails">
Article.created_before(Time.zone.now)
</syntaxhighlight>لكن هذا قد يكرر الوظيفية المزودة من تعريف تابع الصنف.<syntaxhighlight lang="rails">
class Article < ApplicationRecord
  def self.created_before(time)
    where("created_at < ?", time)
  end
end
</syntaxhighlight>إن استخدام تابع الصنف هو الطريقة المفضلة لإنشاء النطاقات التي تقبل وسائط ممررة لها. لا يزال بالإمكان استدعاء هذه التوابع من الكائنات المرتبطة:<syntaxhighlight lang="rails">
category.articles.created_before(time)
</syntaxhighlight>

=== استخدام الشروط ===
يمكن لنطاقك أن يستخدم شروطًا معينة:<syntaxhighlight lang="rails">
class Article < ApplicationRecord
  scope :created_before, ->(time) { where("created_at < ?", time) if time.present? }
end
</syntaxhighlight>كما هو الحال في الأمثلة السابقة، سيعمل هذا بشكل مطابق لتوابع الصنف:<syntaxhighlight lang="rails">
class Article < ApplicationRecord
  def self.created_before(time)
    where("created_at < ?", time) if time.present?
  end
end
</syntaxhighlight>لكن هناك اختلاف وحيد: سيعيد النطاق كائنًا من النوع <code>ActiveRecord::Relation</code> بشكل دائم، حتى لو لم يحقّق الشرط الموجود، في حين أن تابع الصنف سيعيد <code>nil</code> عند عدم تحقيق الشرط. قد يسبب هذا بالخطأ <code>NoMethodError</code> عند سلسلة (chaining) توابع الصنف مع الشروط، وذلك عندما يكون أحد الشروط <code>false</code>.

=== تطبيق نطاق افتراضي ===
إذا أردنا تطبيق نطاق بشكل دائم على كل الاستعلامات المستخدمة في النموذج، يمكننا تحديد ذلك في التابع <code>default_scope</code> ضمن النموذج نفسه:<syntaxhighlight lang="rails">
class Client < ApplicationRecord
  default_scope { where("removed_at IS NULL") }
end
</syntaxhighlight>عند تنفيذ الاستعلامات على هذا النموذج، سيبدو استعلام [[SQL]] المنفذ الآن كالتالي:<syntaxhighlight lang="sql">
SELECT * FROM clients WHERE removed_at IS NULL
</syntaxhighlight>في حال أردنا فعل أشياء أكثر تعقيدًا ضمن النطاق الافتراضي، يمكننا تعريفه تابعًا في الصنف:<syntaxhighlight lang="rails">
class Client < ApplicationRecord
  def self.default_scope
    # ActiveRecord::Relation يجب أن يعيد
  end
end
</syntaxhighlight>'''ملاحظة''': يطبق النطاق الافتراضي <code>default_scope</code> أيضًا أثناء إنشاء أو بناء سجل عند تمرير وسائط النطاق ككائن <code>[[Ruby/Hash|Hash]]</code>. ولن يطبق عند تحديث السجل، مثلًا:<syntaxhighlight lang="rails">
class Client < ApplicationRecord
  default_scope { where(active: true) }
end
 
Client.new          # => #<Client id: nil, active: true>
Client.unscoped.new # => #<Client id: nil, active: nil>

</syntaxhighlight>لاحظ أنه عند استخدام الشكل المصفوفي، لن يكون من الممكن تحويل وسائط الاستعلامات إلى كائن <code>[[Ruby/Hash|Hash]]</code> من أجل الإسناد الافتراضي للحقول. مثلًا:<syntaxhighlight lang="rails">
class Client < ApplicationRecord
  default_scope { where("active = ?", true) }
end
 
Client.new # => #<Client id: nil, active: nil>
</syntaxhighlight>

=== دمج النطاقات ===
كما هو الحال في <code>where</code>، يمكن دمج النطاقات باستخدام شروط <code>AND</code>.<syntaxhighlight lang="rails">
class User < ApplicationRecord
  scope :active, -> { where state: 'active' }
  scope :inactive, -> { where state: 'inactive' }
end
 
User.active.inactive
# SELECT "users".* FROM "users" WHERE "users"."state" = 'active' AND "users"."state" = 'inactive'
</syntaxhighlight>يمكننا دمج ومطابقة التابع <code>scope</code> مع التابع <code>where</code>، وسيحوي الاستعلام الأخير على جميع الشروط المدموجة بواسطة <code>AND</code>.<syntaxhighlight lang="rails">
User.active.where(state: 'finished')
# SELECT "users".* FROM "users" WHERE "users"."state" = 'active' AND "users"."state" = 'finished'

</syntaxhighlight>في حال أردنا من آخر تعليمة <code>where</code> أن تتحقق وتُطبَّق، يمكن استخدام <code>Relation.merge</code>.<syntaxhighlight lang="rails">
User.active.merge(User.inactive)
# SELECT "users".* FROM "users" WHERE "users"."state" = 'inactive'
</syntaxhighlight>الاختلاف الوحيد المهم هو أن النطاق الافتراضي سيتم إلحاقه افتراضيًا في شروط <code>scope</code> و <code>where</code>.<syntaxhighlight lang="rails">
class User < ApplicationRecord
  default_scope { where state: 'pending' }
  scope :active, -> { where state: 'active' }
  scope :inactive, -> { where state: 'inactive' }
end
 
User.all
# SELECT "users".* FROM "users" WHERE "users"."state" = 'pending'
 
User.active
# SELECT "users".* FROM "users" WHERE "users"."state" = 'pending' AND "users"."state" = 'active'
 
User.where(state: 'inactive')
# SELECT "users".* FROM "users" WHERE "users"."state" = 'pending' AND "users"."state" = 'inactive'
</syntaxhighlight>كما ترى أعلاه، يتم دمج النطاق الافتراضي في شرطي <code>scope</code> و <code>where</code>.

=== إزالة جميع النطاقات ===
في حال أردنا إزالة جميع النطاقات لأي سبب كائن، يمكننا استخدام التابع <code>unscope</code>. يكون هذا مفيدًا عندما يتم تحديد نطاق افتراضي على نموذج ما، ولا نريد تطبيقه على استعلام ما.<syntaxhighlight lang="rails">
Client.unscoped.load
</syntaxhighlight>يقوم هذا بحذف جميع النطاقات وتنفيذ استعلام عادي على الجدول.<syntaxhighlight lang="rails">
Client.unscoped.all
# SELECT "clients".* FROM "clients"
 
Client.where(published: false).unscoped.all
# SELECT "clients".* FROM "clients"
</syntaxhighlight>يقبل للتابع <code>unscoped</code> هيكلًا من التعليمات.<syntaxhighlight lang="rails">
Client.unscoped {
  Client.created_before(Time.zone.now)
}
</syntaxhighlight>

== توابع البحث الديناميكية ==
من أجل كل حقل (أو خاصية) تعرّفه في جدولك، يزوّدك [[Rails/active record|Active Record]] بتابع بحث. إذا ملكت حقلًا مسمى <code>first_name</code> على النموذج <code>Client</code> مثلًا، ستحصل على التابع <code>find_by_first_name</code> بالمجان من [[Rails/active record|Active Record]]. وإذا ملكت حقلًا مسمى <code>locked</code> على النموذج <code>Client</code>، ستحصل أيضًا على التابع <code>find_by_locked</code>.

يمكنك أيضًا تحديد إشارة التعجب في نهاية توابع البحث الديناميكية لتجعلها ترمي الاستثناء <code>ActiveRecord::RecordNotFound</code> في حال لم تعد أيّة سجلات، مثلًا:<syntaxhighlight lang="rails">
Client.find_by_name!("Ryan")
</syntaxhighlight>وفي حال أردت البحث عن طريق الحقلين <code>name</code> و <code>locked</code> معًا، يمكنك إمّا سلسلة هذه التوابع معًا، أو كتابة "and" بين أسماء الحقلين. مثلًا:<syntaxhighlight lang="rails">
Client.find_by_first_name_and_locked("Ryan", true)
</syntaxhighlight>

== الماكرو <code>enums</code> ==
يعين الماكرو <code>enum</code> حقلًا عدديًّا صحيحًا لمجموعة من القيم الممكنة.<syntaxhighlight lang="rails">
class Book < ApplicationRecord
  enum availability: [:available, :unavailable]
end
</syntaxhighlight>سينشئ هذا النطاقات الموافقة على النموذج تلقائيًا. تضاف أيضًا التوابع للتنقل بين الحالات الممكنة والاستعلام عن الحالة الحالية للنموذج.<syntaxhighlight lang="rails">
# يبحث المثلان التاليان عن الكتب المتوافرة
Book.available
# أو
Book.where(availability: :available)
 
book = Book.new(availability: :available)
book.available?   # => true
book.unavailable! # => true
book.available?   # => false
</syntaxhighlight>اقرأ التوثيق الكامل حول [http://api.rubyonrails.org/v5.2.2/classes/ActiveRecord/Enum.html الماكرو enums] لمزيد من التفاصيل.

== فهم سَلسَلة التوابع ==
يطبّق نمط Active Record مفهوم سَلْسَلة (Chaining) التوابع، الذي يمكننا من استخدام مجموعة من توابع [[Rails/active record|Active Record]] معًا في طريقة سَلِسَلةٍ وبسيطةٍ.

يمكنك سَلسَلة التوابع في تعليمة واحدة عندما يعيد التابع السابق علاقة (كائنًا من نوع <code>ActiveRecord::Relation</code>)، مثل التوابع <code>all</code> و <code>where</code> و <code>joins</code>. التوابع التي تعيد كائنًا وحيدًا يجب أن تكون في نهاية التعليمة.

هناك بعض الأمثلة أدناه، ولكن لا يغطي هذا التوثيق جميع الحالات المحتملة بل يتطرق إلى كم صغير منها فقط. عند استدعاء تابع في [[Rails/active record|Active Record]]، لن يتم تنفيذ الاستعلام وإرساله إلى قاعدة البيانات، إذ سيحصل ذلك فقط عند الحاجة للبيانات. لذلك كل مثال من الأمثلة التالية سيولّد فقط استعلامًا واحدًا.

=== جلب بيانات مرشَّحة من مجموعة جداول ===
<syntaxhighlight lang="rails">
Person
  .select('people.id, people.name, comments.text')
  .joins(:comments)
  .where('comments.created_at > ?', 1.week.ago)
</syntaxhighlight>سيبدو الناتج كالتالي:<syntaxhighlight lang="sql">
SELECT people.id, people.name, comments.text
FROM people
INNER JOIN comments
  ON comments.person_id = people.id
WHERE comments.created_at > '2015-01-01'
</syntaxhighlight>

=== جلب بيانات محددة من مجموعة جداول ===
<syntaxhighlight lang="rails">
Person
  .select('people.id, people.name, companies.name')
  .joins(:company)
  .find_by('people.name' => 'John') # this should be the last
</syntaxhighlight>سيولّد ذلك الاستعلام التالي:<syntaxhighlight lang="sql">
SELECT people.id, people.name, companies.name
FROM people
INNER JOIN companies
  ON companies.person_id = people.id
WHERE people.name = 'John'
LIMIT 1
</syntaxhighlight>'''ملاحظة''': في حال عثر الاستعلام على مجموعة من السجلات، سيقرأ التابع <code>find_by</code> أول سجل فقط وسيتجاهل السجلات الأخرى.

== البحث عن كائن أو بناؤه ==
من الضروري أحيانًا البحث عن سجل أو بناؤه في حال عدم وجوده. يمكنك تحقيق ذلك باستخدام التوابع <code>find_or_create_by</code> أو <code>!find_or_create_by</code>.

=== التابع <code>find_or_create_by</code> ===
يتحقق التابع <code>find_or_create_by</code> من أن سجلًا ما موجود بالحقول المعطاة. وفي حال عدم وجوده، سيتم استدعاء التابع <code>create</code>.

مثلًا، في حال أردت البحث عن زبون يدعى <code>Sara</code>، وفي حال عدم وجوده يجب إنشاؤه. يمكنك تحقيق ذلك عن طريق تنفيذ التالي:<syntaxhighlight lang="rails">
Client.find_or_create_by(first_name: 'Sara')
# => #<Client id: 1, first_name: "Sara", orders_count: 0, locked: true, created_at: "2011-08-30 06:09:27", updated_at: "2011-08-30 06:09:27">
</syntaxhighlight>سيبدو استعلام [[SQL]] كالتالي:<syntaxhighlight lang="sql">
SELECT * FROM clients WHERE (clients.first_name = 'Sara') LIMIT 1
BEGIN
INSERT INTO clients (created_at, first_name, locked, orders_count, updated_at) VALUES ('2011-08-30 05:22:57', 'Sara', 1, NULL, '2011-08-30 05:22:57')
COMMIT
</syntaxhighlight>يعيد التابع <code>find_or_create_by</code> إما السجل الموجود مسبقًا، أو السجل الجديد. في حالتنا، كنا لا نملك زبونًا يدعى Sara، لذا تم إنشاء السجل وإعادته مباشرةً.

قد لا يتم حفظ السجل في قاعدة البيانات، إذ يعتمد ذلك على مرور السجل للتأكيدات الموجودة أو لا (كما هو الحال في <code>create</code>).

لنفرض أننا بحاجة لتعيين الحقل <code>locked</code> ليصبح <code>false</code> عند إنشائنا لسجل جديد، لكننا لا نحتاج لتضمينه في الاستعلام. لذا سنحتاج للبحث عن الزبون المسمى Sara، وفي حال عدم وجود هذا الزبون، إنشاء زبون باسم "Sara"، وتعيين الحقل <code>locked</code> إلى <code>false</code>.

يمكننا تحقيق ذلك بطريقتين، الأولى باستخدام <code>create_with</code>:<syntaxhighlight lang="rails">
Client.create_with(locked: false).find_or_create_by(first_name: 'Sara')

</syntaxhighlight>والثانية باستخدام كتلة معطاة:<syntaxhighlight lang="rails">
Client.find_or_create_by(first_name: 'Sara') do |c|
  c.locked = false
end
</syntaxhighlight>سيتم تنفيذ الكتلة فقط عند إنشاء الزبون، إذ أنه في المرة الثانية من تنفيذ هذه التعليمة، سيتم تجاهل الكتلة.

=== التابع <code>!find_or_create_by</code> ===
يمكنك أيضًا استخدام التابع <code>!find_or_create_by</code> لرمي استثناء في حال كان السجل الجديد خطأ. لن تتم تغطية [[Rails/active record validations|التحققات من الصحة]] في هذا التوثيق، لكننا لنفرض أنك قمت بإضافة التحقق التالي:<syntaxhighlight lang="rails">
validates :orders_count, presence: true
</syntaxhighlight>في نموذج الزبون <code>Client</code>. والآن عند محاولتك لإنشاء زبون دون تمرير الحقل <code>orders_count</code>، سيكون السجل خطأ وسيتم رمي استثناء:<syntaxhighlight lang="rails">
Client.find_or_create_by!(first_name: 'Andy')
# => ActiveRecord::RecordInvalid: Validation failed: Orders count can't be blank
</syntaxhighlight>

=== التابع <code>find_or_initialize_by</code> ===
يعمل التابع <code>find_or_initialize_by</code> تمامًا مثل التابع <code>find_or_create_by</code>، لكنه سيستدعي التابع <code>new</code> بدلًا من <code>create</code>. مما يعني أنه لن يتم حفظ الكائن في قاعدة البيانات، وإنما فقط في الذاكرة. باستكمال المثال الموضح أعلاه، نحتاج الآن إلى إنشاء الزبون المسمى Fadi:<syntaxhighlight lang="rails">
fadi = Client.find_or_initialize_by(first_name: 'Fadi')
# => #<Client id: nil, first_name: "Fadi", orders_count: 0, locked: true, created_at: "2011-08-30 06:09:27", updated_at: "2011-08-30 06:09:27">
 
fadi.persisted?
# => false
 
fadi.new_record?
# => true
</syntaxhighlight>لأن الكائن لم يتم حفظه بعد في قاعدة البيانات، سيبدو استعلام [[SQL]] المولّد كالتالي:<syntaxhighlight lang="sql">
SELECT * FROM clients WHERE (clients.first_name = 'Fadi') LIMIT 1
</syntaxhighlight>عندما تريد حفظه في قاعدة البيانات، استدعِ التابع save:<syntaxhighlight lang="rails">
fadi.save
# => true
</syntaxhighlight>

== البحث بواسطة SQL ==
في حال أردت استخدام تعليمات [[SQL]] الخاصة بك للبحث عن سجلات في جدول ما، يمكنك استخدام التابع <code>find_by_sql</code>. يعيد هذا التابع مصفوفة من الكائنات حتى لو كانت مجموعة النتائج تحوي كائنًا وحيدًا. مثلًا، يمكنك تنفيذ الاستعلام التالي:<syntaxhighlight lang="rails">
Client.find_by_sql("SELECT * FROM clients
  INNER JOIN orders ON clients.id = orders.client_id
  ORDER BY clients.created_at desc")
# =>  [
#   #<Client id: 1, first_name: "Lucas" >,
#   #<Client id: 2, first_name: "Jan" >,
#   ...
# ]
</syntaxhighlight>يزوّدك التابع <code>find_by_sql</code> بطريقة بسيطة لإنشاء استدعاءات مخصصة لقاعدة البيانات واسترداد الكائنات المهيّئة.

=== التابع <code>select_all</code> ===
يملك التابع <code>find_by_sql</code> تابعًا قريبًا منه يسمى <code>connection.select_all</code>. يسترد هذا التابع الكائنات من قاعدة البيانات بواسطة [[SQL]] مخصص كما هو الحال في التابع <code>find_by_sql</code>، لكنه لن يهيّء هذه الكائنات. إذ سيعيد كائنًا من نوع <code>ActiveRecord::Result</code>، وعند استدعاء <code>to_hash</code> على هذا الكائن، سيتم تحويله إلى مصفوفة من الكائنات <code>[[Ruby/Hash|Hash]]</code> حيث كل جدول <code>[[Ruby/Hash|Hash]]</code> يمثل سجلًا.<syntaxhighlight lang="rails">
Client.connection.select_all("SELECT first_name, created_at FROM clients WHERE id = '1'").to_hash
# => [
#   {"first_name"=>"Rafael", "created_at"=>"2012-11-10 23:23:45.281189"},
#   {"first_name"=>"Eileen", "created_at"=>"2013-12-09 11:22:35.221282"}
# ]
</syntaxhighlight>

=== التابع <code>pluck</code> ===
يمكن استخدام التابع <code>pluck</code> للاستعلام عن حقل وحيد أو مجموعة حقول من الجدول الموافق للنموذج. يقبل هذا التابع قائمة بأسماء الحقول كوسيط له، ويعيد مصفوفة القيم بالحقول المحددة وأنواع بياناتها.<syntaxhighlight lang="rails">
Client.where(active: true).pluck(:id)
# SELECT id FROM clients WHERE active = 1
# => [1, 2, 3]
 
Client.distinct.pluck(:role)
# SELECT DISTINCT role FROM clients
# => ['admin', 'member', 'guest']
 
Client.pluck(:id, :name)
# SELECT clients.id, clients.name FROM clients
# => [[1, 'David'], [2, 'Jeremy'], [3, 'Jose']]
</syntaxhighlight>يجعل التابع <code>pluck</code> من الممكن أن يستبدل بتعليمات مثل:<syntaxhighlight lang="rails">
Client.select(:id).map { |c| c.id }
# أو
Client.select(:id).map(&:id)
# أو
Client.select(:id, :name).map { |c| [c.id, c.name] }
</syntaxhighlight>التعليمات التالية:<syntaxhighlight lang="rails">
Client.pluck(:id)
# أو
Client.pluck(:id, :name)
</syntaxhighlight>على نقيض التابع <code>select</code>، سيحول التابع <code>pluck</code> نتيجة قاعدة البيانات مباشرةً إلى مصفوفة، دون الحاجة لتهيئة كائنات [[Rails/active record|Active Record]]. يؤدي ذلك إلى تحسين الأداء من أجل استعلام ضخم ومنفذ بشكل متردد. لكن، لن تكون التوابع المتجاوزة في النموذج متاحةً. مثلًا:<syntaxhighlight lang="rails">
class Client < ApplicationRecord
  def name
    "I am #{super}"
  end
end
 
Client.select(:name).map &:name
# => ["I am David", "I am Jeremy", "I am Jose"]
 
Client.pluck(:name)
# => ["David", "Jeremy", "Jose"]
</syntaxhighlight>أيضًا على نقيض <code>sleect</code> أو نطاقات العلاقة <code>Relation</code>، ينفذ التابع <code>pluck</code> استعلامًا مباشرًا، وبالتالي لا يمكن سَلسَلته بنطاقات لاحقة، لكنه يعمل بنطاقات مطبقة سابقًا:<syntaxhighlight lang="rails">
Client.pluck(:name).limit(1)
# => NoMethodError: undefined method `limit' for #<Array:0x007ff34d3ad6d8>
 
Client.limit(1).pluck(:name)
# => ["David"]
</syntaxhighlight>

=== التابع <code>ids</code> ===
يستخدم التابع <code>ids</code> لتحديد فقط المعرفات الخاصة بالعلاقات باستخدام المفتاح الرئيسي للجدول.<syntaxhighlight lang="rails">
Person.ids
# SELECT id FROM people
</syntaxhighlight><syntaxhighlight lang="rails">
class Person < ApplicationRecord
  self.primary_key = "person_id"
end
 
Person.ids
# SELECT person_id FROM people
</syntaxhighlight>

== وجود الكائنات ==
في حال أردت التحقق من وجود الكائنات، يوجد تابع يسمى <code>?exists</code>. يقوم هذا التابع بتنفيذ استعلام على قاعدة البيانات باستخدام نفس استعلام التابع <code>find</code>، لكن بدلًا من إعادة الكائن ككل، يعيد القيمة <code>true</code> أو <code>false</code>.<syntaxhighlight lang="rails">
Client.exists?(1)
</syntaxhighlight>يأخذ التابع <code>?exists</code> مجموعة قيم، لكن الاختلاف أنه سيعيد <code>true</code> في حال وجود أي من هذه السجلات.<syntaxhighlight lang="rails">
Client.exists?(id: [1,2,3])
# أو
Client.exists?(name: ['John', 'Sergei'])
</syntaxhighlight>يمكن أيضًا استخدام التابع <code>?exists</code> دون تمرير الوسائط على النموذج أو العلاقة.<syntaxhighlight lang="rails">
Client.where(first_name: 'Ryan').exists?
</syntaxhighlight>تعيد التعليمة السابقة القيمة <code>true</code> في حال كان هناك زبون واحد على الأقل بالاسم Ryan، والقيمة <code>false</code> فيما عدا ذلك.<syntaxhighlight lang="rails">
Client.exists?
</syntaxhighlight>تعيد التلعيمة السابقة القيمة <code>false</code> في حال كان الجدول <code>clients</code> فارغًا، والقيمة <code>true</code> فيما عدا ذلك.

يمكنك أيضًا استخدام التوابع <code>?any</code> و <code>?many</code> للتحقق من وجود نموذج أو علاقة.<syntaxhighlight lang="rails">
# عبر نموذج
Article.any?
Article.many?
 
# عبر مجال مسمى
Article.recent.any?
Article.recent.many?
 
# عبر علاقة
Article.where(published: true).any?
Article.where(published: true).many?
 
# عبر ارتباط
Article.first.categories.any?
Article.first.categories.many?
</syntaxhighlight>

== الحسابات ==
يستخدم هذا القسم التابع <code>count</code> كتابع مثال عن هذا المفهوم، لكن الخيارات المشروحة يمكن استخدامها لجميع الأقسام الفرعية.

تعمل جميع توابع الحساب على النموذج مباشرةً:<syntaxhighlight lang="rails">
Client.count
# SELECT COUNT(*) FROM clients
</syntaxhighlight>أو على علاقة:<syntaxhighlight lang="rails">
Client.where(first_name: 'Ryan').count
# SELECT COUNT(*) FROM clients WHERE (first_name = 'Ryan')

</syntaxhighlight>يمكنك أيضًا استخدام توابع البحث المتعددة على علاقة لتنفيذ عمليات حساب معقدة:<syntaxhighlight lang="rails">
Client.includes("orders").where(first_name: 'Ryan', orders: { status: 'received' }).count

</syntaxhighlight>والذي سينفذ:<syntaxhighlight lang="sql">
SELECT COUNT(DISTINCT clients.id) FROM clients
  LEFT OUTER JOIN orders ON orders.client_id = clients.id
  WHERE (clients.first_name = 'Ryan' AND orders.status = 'received')

</syntaxhighlight>

=== التابع <code>count</code> ===
في حال أردت معرفة عدد السجلات الموجودة في جدول النموذج، يمكنك استدعاء <code>Client.count</code>. في حال أردت أن تكون أكثر دقة، وأردت البحث عن الزبائن الذين يملكون أعمارًا في قاعدة البيانات، يمكنك استخدام <code>(Client.count(:age</code>.

=== التابع <code>average</code> ===
في حال أردت معرفة معدل رقم معين في جدول من جداولك، يمكنك استدعاء التابع <code>average</code> مع الصنف المتعلق بالجدول. يعمل الاستدعاء هذا كالتالي:<syntaxhighlight lang="rails">
Client.average("orders_count")
</syntaxhighlight>سيعيد ذلك عددًا (غالبًا عددًا عشريًا مثل 3.14159265) الذي يمثل معدل قيم هذا الحقل.

=== التابع <code>minimum</code> ===
في حال أردت معرفة أصغر قيمة موجودة في حقل من حقول جدولك، يمكنك استدعاء التابع <code>minumum</code> على الصنف المتعلق بالجدول. يعمل استدعاء التابع الكتالي:<syntaxhighlight lang="rails">
Client.minimum("age")
</syntaxhighlight>

=== التابع <code>maximum</code> ===
في حال أردت معرفة أكبر قيمة موجودة في حقل من حقول جدولك، يمكنك استدعاء التابع <code>maximum</code> على الصنف المتعلق بالجدول. يعمل استدعاء التابع الكتالي:<syntaxhighlight lang="rails">
Client.maximum("age")
</syntaxhighlight>

=== التابع <code>sum</code> ===
في حال أردت معرفة مجموع عناصر حقل مين في جدولك، يمكنك استدعاء التابع <code>sum</code> على الصنف المتعلق بالجدول. يعمل استدعاء التابع كالتالي:<syntaxhighlight lang="rails">
Client.sum("orders_count")
</syntaxhighlight>

== تنفيذ تعليمة <code>EXPLAIN</code> ==
يمكنك تنفيذ تعليمة <code>EXPLAIN</code> على الاستعلامات المولّدة من العلاقات، مثلًا:<syntaxhighlight lang="rails">
User.where(id: 1).joins(:articles).explain
</syntaxhighlight>قد يولّد:<syntaxhighlight lang="text">
EXPLAIN for: SELECT `users`.* FROM `users` INNER JOIN `articles` ON `articles`.`user_id` = `users`.`id` WHERE `users`.`id` = 1
+----+-------------+----------+-------+---------------+
| id | select_type | table    | type  | possible_keys |
+----+-------------+----------+-------+---------------+
|  1 | SIMPLE      | users    | const | PRIMARY       |
|  1 | SIMPLE      | articles | ALL   | NULL          |
+----+-------------+----------+-------+---------------+
+---------+---------+-------+------+-------------+
| key     | key_len | ref   | rows | Extra       |
+---------+---------+-------+------+-------------+
| PRIMARY | 4       | const |    1 |             |
| NULL    | NULL    | NULL  |    1 | Using where |
+---------+---------+-------+------+-------------+
 
2 rows in set (0.00 sec)
</syntaxhighlight>عند استخدام قواعد البيانات MySQL و MariaDB.

ينفّذ [[Rails/active record|Active Record]] طباعة جميلة لمحاكاة طباعة سطر أوامر قاعدة البيانات. لذا من أجل نفس الاستعلام وعند استخدام قاعدة بيانات PostgreSQL، ستولّد تعليمة <code>EXPLAIN</code> التالي:<syntaxhighlight lang="text">
EXPLAIN for: SELECT "users".* FROM "users" INNER JOIN "articles" ON "articles"."user_id" = "users"."id" WHERE "users"."id" = 1
                                  QUERY PLAN
------------------------------------------------------------------------------
 Nested Loop Left Join  (cost=0.00..37.24 rows=8 width=0)
   Join Filter: (articles.user_id = users.id)
   ->  Index Scan using users_pkey on users  (cost=0.00..8.27 rows=1 width=4)
         Index Cond: (id = 1)
   ->  Seq Scan on articles  (cost=0.00..28.88 rows=8 width=4)
         Filter: (articles.user_id = 1)
(6 rows)
</syntaxhighlight>قد يولّد التحميل الحثيث أكثر من استعلام في الخلفية، وقد تحتاج بعض الاستعلامات نتائج الاستعلامات السابقة. بسبب ذلك، ينفذ التابع <code>explain</code> الاستعلام أولًا، ومن ثم يطلب خطة الاستعلام. مثلًا:<syntaxhighlight lang="rails">
User.where(id: 1).includes(:articles).explain
</syntaxhighlight>يولّد:<syntaxhighlight lang="text">
EXPLAIN for: SELECT `users`.* FROM `users`  WHERE `users`.`id` = 1
+----+-------------+-------+-------+---------------+
| id | select_type | table | type  | possible_keys |
+----+-------------+-------+-------+---------------+
|  1 | SIMPLE      | users | const | PRIMARY       |
+----+-------------+-------+-------+---------------+
+---------+---------+-------+------+-------+
| key     | key_len | ref   | rows | Extra |
+---------+---------+-------+------+-------+
| PRIMARY | 4       | const |    1 |       |
+---------+---------+-------+------+-------+
 
1 row in set (0.00 sec)
 
EXPLAIN for: SELECT `articles`.* FROM `articles`  WHERE `articles`.`user_id` IN (1)
+----+-------------+----------+------+---------------+
| id | select_type | table    | type | possible_keys |
+----+-------------+----------+------+---------------+
|  1 | SIMPLE      | articles | ALL  | NULL          |
+----+-------------+----------+------+---------------+
+------+---------+------+------+-------------+
| key  | key_len | ref  | rows | Extra       |
+------+---------+------+------+-------------+
| NULL | NULL    | NULL |    1 | Using where |
+------+---------+------+------+-------------+
 
 
1 row in set (0.00 sec)
</syntaxhighlight>عند استخدام قواعد البيانات MySQL و MariaDB.

=== فهم خرج تعليمة <code>EXPLAIN</code> ===
إن فهم خرج تعليمة <code>EXPLAIN</code> هو خارج حدود هذا التوثيق. قد تفيدك مراجع أخرى في ذلك:
* [http://www.sqlite.org/eqp.html EXPLAIN QUERY PLAN في SQLite3]
* [http://dev.mysql.com/doc/refman/5.7/en/explain-output.html صيغة مخرجات EXPLAIN في MySQL]
* [https://mariadb.com/kb/en/mariadb/explain/ EXPLAIN في MariaDB]

* [https://www.postgresql.org/docs/current/static/using-explain.html استعمال EXPLAIN في PostgreSQL]

== مصادر ==
* [https://guides.rubyonrails.org/active_record_querying.html#readonly-objects صفحة Active Record Query Interface في توثيق Ruby On Rails الرسمي.]