JPQL وواجهة Criteria والاستعلامات

الربط وجلب البيانات دفعةً واحدة في JPQL

18 دقيقة الدرس 2 من 13

الربط وجلب البيانات دفعةً واحدة في JPQL

في SQL تربط الجداول، وفي JPQL تربط علاقات الكيانات. التحوّل دقيق لكنه عميق الأثر: بدلًا من تسمية الأعمدة والمفاتيح الأجنبية تتنقّل عبر رسم الكائنات التي تعرفها JPA بالفعل، ويترجم Hibernate هذا التنقّل إلى SQL ملائمة لقاعدة البيانات الأساسية. يتناول هذا الدرس المفردات الكاملة للربط في JPQL — الداخلي والخارجي والضمني والصريح، وأهمّها جميعًا ربط الجلب (fetch join) — مع شرح مقايضات الأداء التي يجب على كل مطوّر في بيئة الإنتاج أن يفهمها.

نموذج المجال

تستخدم جميع الأمثلة في هذا الدرس نموذج تجارة إلكترونية مصغّرًا. الكيان Order يحتوي على عدة كيانات OrderItem، وكل منها مرتبط بكيان Product؛ كما ينتمي الكيان Order إلى كيان Customer واحد.

// Order.java
@Entity
@Table(name = "orders")
public class Order {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "customer_id")
    private Customer customer;

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<OrderItem> items = new ArrayList<>();

    private LocalDateTime createdAt;
    // الدوال الجالبة والضابطة محذوفة
}

// OrderItem.java
@Entity
@Table(name = "order_items")
public class OrderItem {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "order_id")
    private Order order;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "product_id")
    private Product product;

    private int quantity;
    private BigDecimal unitPrice;
}

لاحظ أن كل @ManyToOne و@OneToMany يستخدم FetchType.LAZY. هذا هو الإعداد الصحيح للإنتاج — تُحمَّل الكائنات المترابطة فقط عند الوصول إليها صراحةً. وهو أيضًا ما يجعل فهم الربط أمرًا بالغ الأهمية: فالتحميل الكسول بدون ربط مناسب يؤدي مباشرةً إلى مشكلة N+1.

الربط الضمني مقابل الربط الصريح

يدعم JPQL أسلوبَين نحويَّين لربط الكيانات ذات الصلة.

الربط الضمني — التنقّل عبر نقطة المسار. يُولّد Hibernate ربط SQL المطلوب تلقائيًا:

// "أعطني كل الطلبات التي قدّمها عملاء من برلين"
TypedQuery<Order> q = em.createQuery(
    "SELECT o FROM Order o WHERE o.customer.city = :city",
    Order.class);
q.setParameter("city", "Berlin");
List<Order> orders = q.getResultList();

الربط الصريح — الكلمة المفتاحية JOIN مع اسم مستعار، تمامًا كما في SQL:

TypedQuery<Order> q = em.createQuery(
    "SELECT o FROM Order o JOIN o.customer c WHERE c.city = :city",
    Order.class);
q.setParameter("city", "Berlin");

كلاهما ينتج نفس INNER JOIN في SQL. يُفضَّل الربط الصريح متى احتجت إلى الإشارة إلى الكيان المرتبط أكثر من مرة في الاستعلام — فهو يتجنّب التنقّلات المتكررة في المسار ويوضّح القصد.

الربط الداخلي والخارجي والضربي

يحاكي JPQL أنواع الربط القياسية في SQL، لكنه يستهدف العلاقات بدلًا من الجداول:

JOIN / INNER JOIN — يعيد فقط الصفوف التي تتحقق فيها العلاقة (مفتاح أجنبي غير فارغ، مجموعة غير فارغة).
LEFT JOIN / LEFT OUTER JOIN — يعيد الكيان المالك حتى عندما تكون الكيان المرتبط غائبًا (NULL على الجانب الأيمن).
CROSS JOIN (نادر الاستخدام) — الضرب الديكارتي لنطاقَي كيانَين.

// LEFT JOIN: أعد أيضًا العملاء الذين لا طلبات لهم بعد
TypedQuery<Customer> q = em.createQuery(
    "SELECT DISTINCT c FROM Customer c LEFT JOIN c.orders o WHERE o IS NULL",
    Customer.class);
List<Customer> noOrders = q.getResultList();

DISTINCT في JPQL تؤدي مهمتَين: تضيف DISTINCT إلى SQL، وتزيل التكرارات من قائمة Java. بدونها سيظهر كيان Customer لديه ثلاثة طلبات ثلاث مرات في القائمة لأن SQL تنتج ثلاثة صفوف.

مشكلة N+1 — لماذا وُجد ربط الجلب

تخيّل أنك تحمّل 50 طلبًا ثم تطبع اسم عميل كل طلب:

List<Order> orders = em.createQuery("SELECT o FROM Order o", Order.class)
                        .getResultList();

for (Order o : orders) {
    // كل استدعاء لـ o.getCustomer().getName() يُطلق SELECT منفصلة
    System.out.println(o.getCustomer().getName());
}

هذا يُطلق استعلامًا واحدًا لجلب الطلبات بالإضافة إلى 50 استعلامًا إضافيًا لجلب كل عميل على حدة — 51 رحلة إجمالًا. مع مئات الصفوف يصبح هذا عنق زجاجة خطير. هذه هي المشكلة الكلاسيكية المعروفة بـ مشكلة N+1 في الاختيار.

FETCH JOIN — تحميل الرسم البياني في استعلام واحد

يخبر ربط الجلب Hibernate بتحميل الكيان المرتبط بنشاط في نفس جملة SQL، متجاوزًا الإعداد الكسول لهذا الاستعلام تحديدًا:

// تحميل الطلبات وعملائها في JOIN SQL واحدة — لا استعلامات كسولة
List<Order> orders = em.createQuery(
    "SELECT o FROM Order o JOIN FETCH o.customer",
    Order.class).getResultList();

for (Order o : orders) {
    // o.getCustomer() مُهيَّأ بالفعل — صفر استعلامات إضافية
    System.out.println(o.getCustomer().getName());
}

SQL المولَّدة تكون تقريبًا:

SELECT o.*, c.*
FROM orders o
INNER JOIN customers c ON c.id = o.customer_id

استعلام واحد بدلًا من 51. المقايضة هي مجموعة نتائج أوسع — أعمدة أكثر لكل صف — لكن ذلك دائمًا تقريبًا أفضل من عشرات الرحلات الإضافية.

LEFT JOIN FETCH للارتباطات القابلة للقيم الفارغة

إذا كانت الارتباط قد يكون فارغًا (مثلًا طلب بدون عميل في نموذجك)، استخدم LEFT JOIN FETCH حتى تُعاد الطلبات التي بلا عميل أيضًا:

List<Order> orders = em.createQuery(
    "SELECT o FROM Order o LEFT JOIN FETCH o.customer",
    Order.class).getResultList();

ربط جلب المجموعة — مصيدة الصفوف المكررة

جلب مجموعة من نوع @OneToMany يُضخّم النتيجة على المستوى SQL. طلب واحد يحتوي على أربعة عناصر يُنتج أربعة صفوف SQL جميعها تشير إلى نفس كائن Order. بدون DISTINCT ستحتوي قائمة Java على أربع نسخ من هذا الطلب:

// خاطئ: تكرارات في القائمة
List<Order> bad = em.createQuery(
    "SELECT o FROM Order o JOIN FETCH o.items",
    Order.class).getResultList();

// صحيح: إزالة التكرارات على مستوى Hibernate
List<Order> good = em.createQuery(
    "SELECT DISTINCT o FROM Order o JOIN FETCH o.items",
    Order.class).getResultList();

تحذير HibernateJpaDialect — "HHH90003004: firstResult/maxResults specified with collection fetch; applying in memory!" لا يستطيع Hibernate تطبيق الترقيم الصفحي على مستوى SQL (LIMIT/OFFSET) على استعلام يجلب مجموعة بـ fetch join، لأن عدد الصفوف في قاعدة البيانات لا يساوي عدد الكيانات. يعود Hibernate إلى جلب جميع الصفوف في الذاكرة ثم يُرقّمها صفحيًا هناك. للنقاط الطرفية ذات الترقيم الصفحي، اجلب المعرّفات أولًا باستعلام عادي مع ترقيم صفحي، ثم حمّل الرسم البياني الكامل في استعلام ثانٍ باستخدام WHERE o.id IN :ids.

ربط الجلب المتسلسل

يمكنك جلب ارتباطات متعددة في استعلام واحد. هنا نحمّل الطلبات مع عناصرها، ونُهيّئ منتج كل عنصر أيضًا:

List<Order> orders = em.createQuery(
    "SELECT DISTINCT o FROM Order o " +
    "JOIN FETCH o.customer " +
    "JOIN FETCH o.items i " +
    "JOIN FETCH i.product",
    Order.class).getResultList();

لا تجلب أكثر من مجموعة واحدة في كل استعلام. ربط مجموعتَين في آنٍ واحد (مثلًا o.items وo.tags) يُنشئ ضربًا ديكارتيًا لكلتيهما. استخدم @BatchSize أو استعلامات منفصلة للمجموعة الثانية.

استخدام ربط الجلب في مستودع Spring Data

يتيح لك Spring Data JPA وضع استعلامات JPQL مباشرةً على أساليب المستودع باستخدام @Query:

@Repository
public interface OrderRepository extends JpaRepository<Order, Long> {

    // جلب الطلبات مع عملائها في استعلام واحد
    @Query("SELECT o FROM Order o JOIN FETCH o.customer WHERE o.createdAt >= :since")
    List<Order> findRecentWithCustomer(@Param("since") LocalDateTime since);

    // طلبات مرقّمة صفحيًا بدون جلب مجموعة (آمن للترقيم الصفحي)
    @Query(
        value = "SELECT o FROM Order o JOIN FETCH o.customer WHERE o.customer.id = :customerId",
        countQuery = "SELECT COUNT(o) FROM Order o WHERE o.customer.id = :customerId"
    )
    Page<Order> findByCustomerId(@Param("customerId") Long customerId, Pageable pageable);
}

استعلام countQuery المنفصل مطلوب عندما يحتوي الاستعلام الرئيسي على ربط جلب — لا يستطيع Spring Data اشتقاق استعلام العدّ تلقائيًا من استعلام يحتوي على fetch join.

الخلاصة

تتبع روابط JPQL القواعد الدلالية ذاتها لـ SQL لكنها تعمل على رسم الكائنات. استخدم JOIN / LEFT JOIN الصريح عندما تحتاج إلى التصفية أو الفرز حسب كيان مرتبط. استخدم JOIN FETCH / LEFT JOIN FETCH عندما تحتاج إلى تهيئة ارتباط وتجنّب مشكلة N+1. أضف دائمًا DISTINCT عند جلب مجموعة بربط جلب، وتجنّب دمج الترقيم الصفحي مع جلب روابط المجموعات. الدرس القادم يتناول دوال التجميع والتجميع في JPQL.