0
# Active Record Operations
1

2
Core functionality for entities using the Active Record pattern through PanacheEntity and PanacheEntityBase. This pattern allows entities to inherit query and persistence methods directly as static methods on the entity class.
3

4
## Capabilities
5

6
### Entity Base Classes
7

8
Foundation classes for the Active Record pattern.
9

10
```java { .api }
11
public abstract class PanacheEntity extends PanacheEntityBase {
12
    @Id
13
    @GeneratedValue
14
    public Long id;
15
    
16
    @Override
17
    public String toString();
18
}
19

20
public abstract class PanacheEntityBase {
21
    // Inherits all static query and persistence methods
22
    
23
    // Instance methods
24
    public void persist();
25
    public void persistAndFlush();
26
    public void delete();
27
    public boolean isPersistent();
28
}
29
```
30

31
**Usage:**
32
```java
33
@Entity
34
public class Person extends PanacheEntity {
35
    public String name;
36
    public LocalDate birth;
37
    public PersonStatus status;
38
}
39
```
40

41
### Finding Entities
42

43
Static methods for finding entities by ID or query.
44

45
```java { .api }
46
public static <T extends PanacheEntityBase> T findById(Object id);
47

48
public static <T extends PanacheEntityBase> T findById(Object id, LockModeType lockModeType);
49

50
public static <T extends PanacheEntityBase> Optional<T> findByIdOptional(Object id);
51

52
public static <T extends PanacheEntityBase> Optional<T> findByIdOptional(Object id, LockModeType lockModeType);
53

54
public static <T extends PanacheEntityBase> PanacheQuery<T> find(String query, Object... params);
55

56
public static <T extends PanacheEntityBase> PanacheQuery<T> find(String query, Sort sort, Object... params);
57

58
public static <T extends PanacheEntityBase> PanacheQuery<T> find(String query, Map<String, Object> params);
59

60
public static <T extends PanacheEntityBase> PanacheQuery<T> find(String query, Sort sort, Map<String, Object> params);
61

62
public static <T extends PanacheEntityBase> PanacheQuery<T> find(String query, Parameters params);
63

64
public static <T extends PanacheEntityBase> PanacheQuery<T> find(String query, Sort sort, Parameters params);
65

66
public static <T extends PanacheEntityBase> PanacheQuery<T> findAll();
67

68
public static <T extends PanacheEntityBase> PanacheQuery<T> findAll(Sort sort);
69
```
70

71
**Usage:**
72
```java
73
// Find by ID
74
Person person = Person.findById(1L);
75
Optional<Person> maybePerson = Person.findByIdOptional(1L);
76

77
// Find with queries
78
List<Person> activeUsers = Person.find("status", PersonStatus.Active).list();
79
List<Person> namedUsers = Person.find("name = ?1", "John").list();
80
List<Person> sortedUsers = Person.find("status", PersonStatus.Active)
81
    .page(0, 10).list();
82

83
// Find all
84
List<Person> allPeople = Person.findAll().list();
85
List<Person> sortedPeople = Person.findAll(Sort.by("name")).list();
86
```
87

88
### Listing Entities
89

90
Convenience methods that directly return Lists (shortcuts for find().list()).
91

92
```java { .api }
93
public static <T extends PanacheEntityBase> List<T> list(String query, Object... params);
94

95
public static <T extends PanacheEntityBase> List<T> list(String query, Sort sort, Object... params);
96

97
public static <T extends PanacheEntityBase> List<T> list(String query, Map<String, Object> params);
98

99
public static <T extends PanacheEntityBase> List<T> list(String query, Sort sort, Map<String, Object> params);
100

101
public static <T extends PanacheEntityBase> List<T> list(String query, Parameters params);
102

103
public static <T extends PanacheEntityBase> List<T> list(String query, Sort sort, Parameters params);
104

105
public static <T extends PanacheEntityBase> List<T> listAll();
106

107
public static <T extends PanacheEntityBase> List<T> listAll(Sort sort);
108
```
109

110
**Usage:**
111
```java
112
// Direct list results
113
List<Person> activeUsers = Person.list("status", PersonStatus.Active);
114
List<Person> sortedUsers = Person.list("name like ?1", "J%", Sort.by("name"));
115
List<Person> allPeople = Person.listAll();
116

117
// With named parameters
118
Map<String, Object> params = Map.of("status", PersonStatus.Active, "city", "NYC");
119
List<Person> nycActive = Person.list("status = :status AND city = :city", params);
120

121
// With Parameters helper
122
List<Person> filtered = Person.list("status = :status AND age > :age", 
123
    Parameters.with("status", PersonStatus.Active).and("age", 18));
124
```
125

126
### Streaming Entities
127

128
Methods that return Streams for memory-efficient processing (require active transaction).
129

130
```java { .api }
131
public static <T extends PanacheEntityBase> Stream<T> stream(String query, Object... params);
132

133
public static <T extends PanacheEntityBase> Stream<T> stream(String query, Sort sort, Object... params);
134

135
public static <T extends PanacheEntityBase> Stream<T> stream(String query, Map<String, Object> params);
136

137
public static <T extends PanacheEntityBase> Stream<T> stream(String query, Sort sort, Map<String, Object> params);
138

139
public static <T extends PanacheEntityBase> Stream<T> stream(String query, Parameters params);
140

141
public static <T extends PanacheEntityBase> Stream<T> stream(String query, Sort sort, Parameters params);
142

143
public static <T extends PanacheEntityBase> Stream<T> streamAll();
144

145
public static <T extends PanacheEntityBase> Stream<T> streamAll(Sort sort);
146
```
147

148
**Usage:**
149
```java
150
@Transactional
151
public void processAllUsers() {
152
    Person.streamAll()
153
        .filter(person -> person.status == PersonStatus.Active)
154
        .forEach(this::processActivePerson);
155
}
156

157
@Transactional  
158
public List<String> getActiveUserNames() {
159
    return Person.stream("status", PersonStatus.Active)
160
        .map(person -> person.name)
161
        .collect(Collectors.toList());
162
}
163
```
164

165
### Counting Entities
166

167
Methods for counting entities without loading them.
168

169
```java { .api }
170
public static long count();
171

172
public static long count(String query, Object... params);
173

174
public static long count(String query, Map<String, Object> params);
175

176
public static long count(String query, Parameters params);
177
```
178

179
**Usage:**
180
```java
181
// Count all entities
182
long totalUsers = Person.count();
183

184
// Count with conditions
185
long activeUsers = Person.count("status", PersonStatus.Active);
186
long adultUsers = Person.count("age >= :age", Parameters.with("age", 18));
187
```
188

189
### Persisting Entities
190

191
Methods for saving entities to the database.
192

193
```java { .api }
194
// Instance methods
195
public void persist();
196
public void persistAndFlush();
197

198
// Static batch methods  
199
public static void persist(Iterable<?> entities);
200
public static void persist(Stream<?> entities);
201
public static void persist(Object firstEntity, Object... entities);
202
```
203

204
**Usage:**
205
```java
206
// Single entity persistence
207
Person person = new Person();
208
person.name = "John Doe";
209
person.persist(); // or person.persistAndFlush()
210

211
// Batch persistence
212
List<Person> people = Arrays.asList(person1, person2, person3);
213
Person.persist(people);
214

215
// Multiple entities
216
Person.persist(person1, person2, person3);
217
```
218

219
### Deleting Entities
220

221
Methods for removing entities from the database.
222

223
```java { .api }
224
// Instance method
225
public void delete();
226

227
// Static methods
228
public static long deleteAll();
229
public static boolean deleteById(Object id);
230
public static long delete(String query, Object... params);
231
public static long delete(String query, Map<String, Object> params);
232
public static long delete(String query, Parameters params);
233
```
234

235
**Usage:**
236
```java
237
// Delete single entity
238
Person person = Person.findById(1L);
239
person.delete();
240

241
// Delete by ID
242
boolean deleted = Person.deleteById(1L);
243

244
// Bulk delete
245
long deletedCount = Person.delete("status", PersonStatus.Inactive);
246
Person.deleteAll(); // Delete all entities
247

248
// Delete with conditions
249
long deleted = Person.delete("age < :age AND status = :status",
250
    Parameters.with("age", 18).and("status", PersonStatus.Inactive));
251
```
252

253
### Updating Entities
254

255
Bulk update operations using HQL.
256

257
```java { .api }
258
public static int update(String query, Object... params);
259
public static int update(String query, Map<String, Object> params);
260
public static int update(String query, Parameters params);
261
```
262

263
**Usage:**
264
```java
265
// Bulk updates
266
int updated = Person.update("status = ?1 where age >= ?2", PersonStatus.Adult, 18);
267

268
// With named parameters
269
int updated = Person.update("status = :newStatus where city = :city",
270
    Parameters.with("newStatus", PersonStatus.Verified).and("city", "NYC"));
271
```
272

273
### Entity Manager Access
274

275
Direct access to EntityManager and Session for advanced operations.
276

277
```java { .api }
278
public static EntityManager getEntityManager();
279
public static Session getSession();
280
public static void flush();
281
```
282

283
**Usage:**
284
```java
285
// Direct EntityManager access
286
EntityManager em = Person.getEntityManager();
287
CriteriaBuilder cb = em.getCriteriaBuilder();
288
CriteriaQuery<Person> cq = cb.createQuery(Person.class);
289

290
// Hibernate Session access
291
Session session = Person.getSession();
292
Query<?> nativeQuery = session.createNativeQuery("SELECT * FROM person WHERE...");
293

294
// Manual flush
295
Person.flush();
296
```
297

298
## Simplified Query Syntax
299

300
Panache supports simplified query syntax that automatically expands:
301

302
### Select Query Expansions
303
- `"order by name"` → `"from Person order by name"`
304
- `"name"` (with single param) → `"from Person where name = ?"`
305
- `"where age > 18"` → `"from Person where age > 18"`
306
- `"age > 18 AND status = 'ACTIVE'"` → `"from Person where age > 18 AND status = 'ACTIVE'"`
307

308
### Update Query Expansions
309
- `"set status = ?1"` → `"update from Person set status = ?1"`
310
- `"status = ?1 where age > ?2"` → `"update from Person set status = ?1 where age > ?2"`
311

312
### Delete Query Expansions  
313
- `"status"` (with single param) → `"delete from Person where status = ?"`
314
- `"age < 18"` → `"delete from Person where age < 18"`
315

316
### Named Queries
317
Reference named queries with `#` prefix:
318
```java
319
List<Person> active = Person.list("#Person.findActive");
320
```