0
# Records and Data Handling
1

2
Record handling with change tracking, type conversion, and data manipulation capabilities. Supports both generated record types and generic record operations.
3

4
## Capabilities
5

6
### Record Interface
7

8
Base interface for all database records providing data access and manipulation methods.
9

10
```java { .api }
11
public interface Record extends Attachable {
12
    /**
13
     * Get the number of fields in this record
14
     * @return Number of fields
15
     */
16
    int size();
17
    
18
    /**
19
     * Get a field value by field reference
20
     * @param field Field to get value for
21
     * @return Value of the specified field
22
     */
23
    <T> T get(Field<T> field);
24
    
25
    /**
26
     * Get a field value by field name
27
     * @param fieldName Name of the field
28
     * @return Value of the named field
29
     */
30
    Object get(String fieldName);
31
    
32
    /**
33
     * Get a field value by field index
34
     * @param index Zero-based field index
35
     * @return Value at the specified index
36
     */
37
    Object get(int index);
38
    
39
    /**
40
     * Get a typed field value by field name
41
     * @param fieldName Name of the field
42
     * @param type Expected type class
43
     * @return Typed value of the named field
44
     */
45
    <T> T get(String fieldName, Class<T> type);
46
    
47
    /**
48
     * Get a typed field value by field index
49
     * @param index Zero-based field index
50
     * @param type Expected type class
51
     * @return Typed value at the specified index
52
     */
53
    <T> T get(int index, Class<T> type);
54
    
55
    /**
56
     * Set a field value
57
     * @param field Field to set
58
     * @param value New value
59
     */
60
    <T> void set(Field<T> field, T value);
61
    
62
    /**
63
     * Set a field value by name
64
     * @param fieldName Name of the field
65
     * @param value New value
66
     */
67
    void set(String fieldName, Object value);
68
    
69
    /**
70
     * Set a field value by index
71
     * @param index Zero-based field index
72
     * @param value New value
73
     */
74
    void set(int index, Object value);
75
    
76
    /**
77
     * Create a copy of this record with a field value changed
78
     * @param field Field to set
79
     * @param value New value
80
     * @return New record with the field value changed
81
     */
82
    <T> Record with(Field<T> field, T value);
83
    
84
    /**
85
     * Check if this record has been modified
86
     * @return true if any field has been changed
87
     */
88
    boolean changed();
89
    
90
    /**
91
     * Check if a specific field has been modified
92
     * @param field Field to check
93
     * @return true if the field has been changed
94
     */
95
    boolean changed(Field<?> field);
96
    
97
    /**
98
     * Check if a field by name has been modified
99
     * @param fieldName Name of the field to check
100
     * @return true if the field has been changed
101
     */
102
    boolean changed(String fieldName);
103
    
104
    /**
105
     * Get the original record values before changes
106
     * @return Record with original values
107
     */
108
    Record original();
109
    
110
    /**
111
     * Reset all changes, reverting to original values
112
     */
113
    void reset();
114
    
115
    /**
116
     * Reset changes for a specific field
117
     * @param field Field to reset
118
     */
119
    void reset(Field<?> field);
120
    
121
    /**
122
     * Convert record values to an array
123
     * @return Array containing all field values
124
     */
125
    Object[] intoArray();
126
    
127
    /**
128
     * Convert record to a Map
129
     * @return Map with field names as keys and values
130
     */
131
    Map<String, Object> intoMap();
132
    
133
    /**
134
     * Convert record to a custom type
135
     * @param type Target type class
136
     * @return Instance of the target type populated with record data
137
     */
138
    <E> E into(Class<? extends E> type);
139
    
140
    /**
141
     * Get the record's values as a Row
142
     * @return Row containing the record values
143
     */
144
    Row valuesRow();
145
    
146
    /**
147
     * Get the record's field structure as a Row
148
     * @return Row describing the record structure
149
     */
150
    Row fieldsRow();
151
}
152
```
153

154
**Usage Examples:**
155

156
```java
157
// Generic record access
158
Record record = create.select().from(AUTHOR).where(AUTHOR.ID.eq(1)).fetchOne();
159

160
// Type-safe field access
161
String firstName = record.get(AUTHOR.FIRST_NAME);
162
Integer id = record.get(AUTHOR.ID);
163

164
// Access by field name or index
165
String lastName = record.get("LAST_NAME", String.class);
166
Object firstValue = record.get(0);
167

168
// Modify record values
169
record.set(AUTHOR.FIRST_NAME, "Johnny");
170
record.set("ACTIVE", true);
171

172
// Check for changes
173
if (record.changed()) {
174
    System.out.println("Record has been modified");
175
    if (record.changed(AUTHOR.FIRST_NAME)) {
176
        System.out.println("First name was changed");
177
    }
178
}
179

180
// Convert to different formats
181
Object[] values = record.intoArray();
182
Map<String, Object> map = record.intoMap();
183
AuthorPojo pojo = record.into(AuthorPojo.class);
184
```
185

186
### UpdatableRecord Interface
187

188
Extended record interface for records that can be persisted to the database.
189

190
```java { .api }
191
public interface UpdatableRecord<R extends UpdatableRecord<R>> extends Record {
192
    /**
193
     * Store this record (INSERT or UPDATE based on primary key)
194
     * @return Number of affected rows (0 or 1)
195
     */
196
    int store();
197
    
198
    /**
199
     * Insert this record into the database
200
     * @return Number of affected rows (0 or 1)
201
     */
202
    int insert();
203
    
204
    /**
205
     * Update this record in the database
206
     * @return Number of affected rows (0 or 1)
207
     */
208
    int update();
209
    
210
    /**
211
     * Delete this record from the database
212
     * @return Number of affected rows (0 or 1)
213
     */
214
    int delete();
215
    
216
    /**
217
     * Refresh this record from the database
218
     * Reloads all field values from the database
219
     */
220
    void refresh();
221
    
222
    /**
223
     * Refresh specific fields from the database
224
     * @param fields Fields to refresh
225
     */
226
    void refresh(Field<?>... fields);
227
    
228
    /**
229
     * Get the table this record belongs to
230
     * @return Table instance
231
     */
232
    Table<R> getTable();
233
    
234
    /**
235
     * Create a copy of this record
236
     * @return New record instance with same values
237
     */
238
    R copy();
239
}
240
```
241

242
**Usage Examples:**
243

244
```java
245
// Create new record
246
AuthorRecord author = create.newRecord(AUTHOR);
247
author.setFirstName("Jane");
248
author.setLastName("Doe");
249
author.setDateOfBirth(LocalDate.of(1985, 3, 20));
250

251
// Store (INSERT since it's new)
252
int result = author.store();
253
Integer newId = author.getId(); // Auto-generated ID
254

255
// Modify and update
256
author.setFirstName("Janet");
257
int updated = author.update();
258

259
// Refresh from database
260
author.refresh();
261

262
// Delete record
263
int deleted = author.delete();
264

265
// Work with existing record
266
AuthorRecord existing = create.selectFrom(AUTHOR)
267
    .where(AUTHOR.ID.eq(5))
268
    .fetchOne();
269

270
if (existing != null) {
271
    existing.setActive(false);
272
    existing.store(); // UPDATE since it exists
273
}
274
```
275

276
### Result Interface
277

278
Container for multiple records returned from queries.
279

280
```java { .api }
281
public interface Result<R extends Record> extends List<R>, Attachable {
282
    /**
283
     * Check if this result is empty
284
     * @return true if no records
285
     */
286
    boolean isEmpty();
287
    
288
    /**
289
     * Get the fields in this result
290
     * @return Array of fields
291
     */
292
    Field<?>[] fields();
293
    
294
    /**
295
     * Get field by index
296
     * @param index Zero-based field index
297
     * @return Field at the specified index
298
     */
299
    Field<?> field(int index);
300
    
301
    /**
302
     * Get field by name
303
     * @param name Field name
304
     * @return Field with the specified name
305
     */
306
    Field<?> field(String name);
307
    
308
    /**
309
     * Get all values for a specific field
310
     * @param field Field to get values for
311
     * @return List of values for the field
312
     */
313
    <T> List<T> getValues(Field<T> field);
314
    
315
    /**
316
     * Get all values for a field by name
317
     * @param fieldName Name of the field
318
     * @return List of values for the named field
319
     */
320
    List<?> getValues(String fieldName);
321
    
322
    /**
323
     * Get all values for a field by index
324
     * @param index Zero-based field index
325
     * @return List of values at the specified index
326
     */
327
    List<?> getValues(int index);
328
    
329
    /**
330
     * Convert all records to arrays
331
     * @return List of Object arrays
332
     */
333
    List<Object[]> intoArrays();
334
    
335
    /**
336
     * Convert all records to Maps
337
     * @return List of Maps with field names as keys
338
     */
339
    List<Map<String, Object>> intoMaps();
340
    
341
    /**
342
     * Convert all records to custom type instances
343
     * @param type Target type class
344
     * @return List of instances of the target type
345
     */
346
    <E> List<E> into(Class<? extends E> type);
347
    
348
    /**
349
     * Group records by a field value
350
     * @param field Field to group by
351
     * @return Map with field values as keys and record lists as values
352
     */
353
    <K> Map<K, Result<R>> intoGroups(Field<K> field);
354
    
355
    /**
356
     * Convert to a Map using a field as key
357
     * @param keyField Field to use as map key
358
     * @return Map with field values as keys and records as values
359
     */
360
    <K> Map<K, R> intoMap(Field<K> keyField);
361
    
362
    /**
363
     * Format result as a table string
364
     * @return String representation of the result as a table
365
     */
366
    String format();
367
    
368
    /**
369
     * Format result with specific number of records
370
     * @param maxRecords Maximum records to include in format
371
     * @return String representation with limited records
372
     */
373
    String format(int maxRecords);
374
}
375
```
376

377
**Usage Examples:**
378

379
```java
380
// Fetch multiple records
381
Result<AuthorRecord> authors = create.selectFrom(AUTHOR)
382
    .where(AUTHOR.ACTIVE.eq(true))
383
    .fetch();
384

385
// Work with result metadata
386
Field<?>[] fields = authors.fields();
387
int recordCount = authors.size();
388
boolean hasData = !authors.isEmpty();
389

390
// Extract field values
391
List<String> firstNames = authors.getValues(AUTHOR.FIRST_NAME);
392
List<Integer> ids = authors.getValues(AUTHOR.ID);
393

394
// Convert to different formats
395
List<Object[]> arrays = authors.intoArrays();
396
List<Map<String, Object>> maps = authors.intoMaps();
397
List<AuthorPojo> pojos = authors.into(AuthorPojo.class);
398

399
// Group and organize data
400
Map<Boolean, Result<AuthorRecord>> byActive = authors.intoGroups(AUTHOR.ACTIVE);
401
Map<Integer, AuthorRecord> byId = authors.intoMap(AUTHOR.ID);
402

403
// Display results
404
System.out.println(authors.format(10)); // Show first 10 records as table
405
```
406

407
### Record Creation and Manipulation
408

409
Methods for creating new records and manipulating record data.
410

411
```java { .api }
412
public interface DSLContext {
413
    /**
414
     * Create a new record for a table
415
     * @param table Table to create record for
416
     * @return New record instance
417
     */
418
    <R extends Record> R newRecord(Table<R> table);
419
    
420
    /**
421
     * Create a new record with field values
422
     * @param table Table to create record for
423
     * @param source Source record or object to copy values from
424
     * @return New record with copied values
425
     */
426
    <R extends Record> R newRecord(Table<R> table, Object source);
427
    
428
    /**
429
     * Execute a batch of records
430
     * @param records Records to execute in batch
431
     * @return Array of affected row counts
432
     */
433
    int[] batchStore(UpdatableRecord<?>... records);
434
    
435
    /**
436
     * Execute a batch insert
437
     * @param records Records to insert in batch
438
     * @return Array of affected row counts
439
     */
440
    int[] batchInsert(UpdatableRecord<?>... records);
441
    
442
    /**
443
     * Execute a batch update
444
     * @param records Records to update in batch
445
     * @return Array of affected row counts
446
     */
447
    int[] batchUpdate(UpdatableRecord<?>... records);
448
    
449
    /**
450
     * Execute a batch delete
451
     * @param records Records to delete in batch
452
     * @return Array of affected row counts
453
     */
454
    int[] batchDelete(UpdatableRecord<?>... records);
455
}
456
```
457

458
**Usage Examples:**
459

460
```java
461
// Create new records
462
AuthorRecord author1 = create.newRecord(AUTHOR);
463
author1.setFirstName("Alice");
464
author1.setLastName("Smith");
465

466
AuthorRecord author2 = create.newRecord(AUTHOR);
467
author2.setFirstName("Bob");
468
author2.setLastName("Jones");
469

470
// Batch operations
471
int[] insertResults = create.batchInsert(author1, author2);
472

473
// Create record from existing data
474
AuthorPojo pojo = new AuthorPojo("Charlie", "Brown", LocalDate.of(1990, 1, 1));
475
AuthorRecord author3 = create.newRecord(AUTHOR, pojo);
476
author3.store();
477

478
// Bulk operations with collections
479
List<AuthorRecord> authors = Arrays.asList(author1, author2, author3);
480
authors.forEach(author -> {
481
    author.setActive(true);
482
});
483

484
int[] updateResults = create.batchUpdate(authors.toArray(new AuthorRecord[0]));
485
```
486

487
## Record Type Information
488

489
```java { .api }
490
public interface RecordType<R extends Record> {
491
    /**
492
     * Get all fields in this record type
493
     * @return Array of fields
494
     */
495
    Field<?>[] fields();
496
    
497
    /**
498
     * Get field by index
499
     * @param index Zero-based field index
500
     * @return Field at the specified index
501
     */
502
    Field<?> field(int index);
503
    
504
    /**
505
     * Get field by name
506
     * @param name Field name
507
     * @return Field with the specified name
508
     */
509
    Field<?> field(String name);
510
    
511
    /**
512
     * Get the number of fields
513
     * @return Field count
514
     */
515
    int size();
516
}
517
```