✅ Short Answer
- Positional parameters use index-based placeholders like
?1,?2, etc., which are set by their numeric position in the query. - Named parameters use named placeholders like
:name,:status, which are set by their explicit names.
🔎 Detailed Explanation
🔹 Positional Parameters
- Syntax:
?1,?2, … - Binding: set by order → first parameter is
?1, second is?2, etc. - Example:
String hql = "FROM MyEntity e WHERE e.name = ?1 AND e.status = ?2";
Query<MyEntity> query = session.createQuery(hql, MyEntity.class);
query.setParameter(1, "Alice");
query.setParameter(2, "ACTIVE");
List<MyEntity> results = query.getResultList();
- Downsides:
- Harder to read/maintain — position must match exactly.
- Mistakes happen easily if you reorder parameters.
🔹 Named Parameters
- Syntax:
:name,:status, … - Binding: set by name → clear, descriptive, easier to read.
- Example:
String hql = "FROM MyEntity e WHERE e.name = :name AND e.status = :status";
Query<MyEntity> query = session.createQuery(hql, MyEntity.class);
query.setParameter("name", "Alice");
query.setParameter("status", "ACTIVE");
List<MyEntity> results = query.getResultList();
Benefits:
✅ More readable and maintainable, especially in queries with many parameters.
✅ Changing query structure doesn’t affect parameter binding order.
📊 Quick Comparison Table
| Feature | Positional | Named |
|---|---|---|
| Syntax | ?1, ?2, etc. | :paramName |
| Binding | By index | By descriptive name |
| Readability | Lower | Higher |
| Maintainability | Fragile to query reordering | Safer when query changes |
💡 Best Practices
✅ Always prefer named parameters → they make queries more self-documenting, especially with many or optional parameters.
✅ Positional parameters are mostly kept for legacy compatibility or very simple cases.
📌 Key Takeaways
✅ Positional parameters → indexed placeholders like ?1; prone to maintenance issues.
✅ Named parameters → named placeholders like :name; more readable, recommended for most use cases.
✅ Both methods allow safe binding → preventing SQL injection compared to string concatenation.