0
# Querying and Views
1

2
Configurable iteration and querying system with index-based filtering, sorting, and pagination. The view system provides flexible ways to retrieve and iterate over stored data without loading everything into memory.
3

4
## Capabilities
5

6
### Creating Views
7

8
Create a configurable view for iterating over entities of a specific type.
9

10
```java { .api }
11
/**
12
 * Returns a configurable view for iterating over entities of the given type.
13
 * @param type - The class type to create a view for
14
 * @return A KVStoreView instance for configuring iteration
15
 * @throws Exception If type introspection or store access fails
16
 */
17
<T> KVStoreView<T> view(Class<T> type) throws Exception;
18
```
19

20
**Usage Examples:**
21

22
```java
23
// Create a basic view for all persons
24
KVStoreView<Person> allPersons = store.view(Person.class);
25

26
// Iterate over all persons
27
for (Person person : allPersons) {
28
    System.out.println(person.name);
29
}
30
```
31

32
### Index-Based Querying
33

34
Configure views to iterate based on specific indices for efficient data access.
35

36
```java { .api }
37
/**
38
 * Iterates according to the given index.
39
 * @param name - The index name to use for iteration
40
 * @return This view instance for method chaining
41
 */
42
public KVStoreView<T> index(String name);
43
```
44

45
**Usage Examples:**
46

47
```java
48
// Query persons by age index
49
KVStoreView<Person> byAge = store.view(Person.class).index("age");
50

51
// Query persons by name index
52
KVStoreView<Person> byName = store.view(Person.class).index("name");
53

54
// Iterate in natural key order (default)
55
KVStoreView<Person> byNaturalKey = store.view(Person.class).index(KVIndex.NATURAL_INDEX_NAME);
56
```
57

58
### Range Queries
59

60
Set start and end boundaries for iteration over indexed values.
61

62
```java { .api }
63
/**
64
 * Iterates starting at the given value of the chosen index (inclusive).
65
 * @param value - The starting value for iteration
66
 * @return This view instance for method chaining
67
 */
68
public KVStoreView<T> first(Object value);
69

70
/**
71
 * Stops iteration at the given value of the chosen index (inclusive).
72
 * @param value - The ending value for iteration
73
 * @return This view instance for method chaining
74
 */
75
public KVStoreView<T> last(Object value);
76
```
77

78
**Usage Examples:**
79

80
```java
81
// Get persons aged 25 to 65
82
KVStoreView<Person> workingAge = store.view(Person.class)
83
    .index("age")
84
    .first(25)
85
    .last(65);
86

87
// Get persons with names from "A" to "M"
88
KVStoreView<Person> firstHalf = store.view(Person.class)
89
    .index("name")
90
    .first("A")
91
    .last("M");
92

93
// Get all persons aged 30 exactly
94
KVStoreView<Person> thirtyYearOlds = store.view(Person.class)
95
    .index("age")
96
    .first(30)
97
    .last(30);
98
```
99

100
### Iteration Direction
101

102
Control the sort order of iteration results.
103

104
```java { .api }
105
/**
106
 * Reverses the order of iteration. By default, iterates in ascending order.
107
 * @return This view instance for method chaining
108
 */
109
public KVStoreView<T> reverse();
110
```
111

112
**Usage Examples:**
113

114
```java
115
// Get persons in descending age order
116
KVStoreView<Person> oldestFirst = store.view(Person.class)
117
    .index("age")
118
    .reverse();
119

120
// Get persons in reverse alphabetical order
121
KVStoreView<Person> reverseAlpha = store.view(Person.class)
122
    .index("name")
123
    .reverse();
124
```
125

126
### Pagination
127

128
Control how many results to retrieve and skip for pagination scenarios.
129

130
```java { .api }
131
/**
132
 * Stops iteration after a number of elements has been retrieved.
133
 * @param max - Maximum number of elements to retrieve (must be positive)
134
 * @return This view instance for method chaining
135
 */
136
public KVStoreView<T> max(long max);
137

138
/**
139
 * Skips a number of elements at the start of iteration. Skipped elements are not accounted
140
 * when using max(long).
141
 * @param n - Number of elements to skip
142
 * @return This view instance for method chaining
143
 */
144
public KVStoreView<T> skip(long n);
145
```
146

147
**Usage Examples:**
148

149
```java
150
// Get first 10 persons
151
KVStoreView<Person> firstTen = store.view(Person.class).max(10);
152

153
// Get persons 11-20 (pagination)
154
KVStoreView<Person> secondPage = store.view(Person.class)
155
    .skip(10)
156
    .max(10);
157

158
// Get top 5 oldest persons
159
KVStoreView<Person> oldestFive = store.view(Person.class)
160
    .index("age")
161
    .reverse()
162
    .max(5);
163
```
164

165
### Hierarchical Queries (Parent-Child Indices)
166

167
Query data using parent-child index relationships for hierarchical data structures.
168

169
```java { .api }
170
/**
171
 * Defines the value of the parent index when iterating over a child index. Only elements that
172
 * match the parent index's value will be included in the iteration.
173
 * 
174
 * Required for iterating over child indices, will generate an error if iterating over a
175
 * parent-less index.
176
 * @param value - The parent index value to filter by
177
 * @return This view instance for method chaining
178
 */
179
public KVStoreView<T> parent(Object value);
180
```
181

182
**Usage Examples:**
183

184
```java
185
// Assuming Task has a parent index "projectId" and child index "priority"
186
// Get all high-priority tasks for project "proj123"
187
KVStoreView<Task> highPriorityTasks = store.view(Task.class)
188
    .index("priority")
189
    .parent("proj123")  // Filter by parent project ID
190
    .first("high")
191
    .last("high");
192

193
// Get all tasks for a specific project, ordered by status
194
KVStoreView<Task> projectTasks = store.view(Task.class)
195
    .index("status")
196
    .parent("proj123");
197
```
198

199
### Advanced Iteration
200

201
Get closeable iterators for fine-grained control over resource management and batch processing.
202

203
```java { .api }
204
/**
205
 * Returns an iterator for the current configuration.
206
 * @return A closeable iterator that should be explicitly closed
207
 * @throws Exception If iteration setup fails
208
 */
209
public KVStoreIterator<T> closeableIterator() throws Exception;
210

211
public interface KVStoreIterator<T> extends Iterator<T>, Closeable {
212
    /**
213
     * Retrieve multiple elements from the store.
214
     * @param max - Maximum number of elements to retrieve
215
     * @return List containing up to max elements
216
     */
217
    List<T> next(int max);
218
    
219
    /**
220
     * Skip in the iterator.
221
     * @param n - Number of elements to skip
222
     * @return Whether there are items left after skipping
223
     */
224
    boolean skip(long n);
225
}
226
```
227

228
**Usage Examples:**
229

230
```java
231
// Manual iterator management with try-with-resources
232
try (KVStoreIterator<Person> iterator = store.view(Person.class)
233
        .index("age")
234
        .first(25)
235
        .closeableIterator()) {
236
    
237
    // Process in batches of 100
238
    List<Person> batch;
239
    while (!(batch = iterator.next(100)).isEmpty()) {
240
        processBatch(batch);
241
    }
242
}
243

244
// Skip and retrieve pattern
245
try (KVStoreIterator<Person> iterator = store.view(Person.class)
246
        .index("name")
247
        .closeableIterator()) {
248
    
249
    // Skip first 50 entries
250
    iterator.skip(50);
251
    
252
    // Get next 20 entries
253
    List<Person> next20 = iterator.next(20);
254
    
255
    // Check if more entries exist
256
    boolean hasMore = iterator.hasNext();
257
}
258
```
259

260
### Complex Query Examples
261

262
Combining multiple view configuration methods for sophisticated queries.
263

264
**Usage Examples:**
265

266
```java
267
// Get the 10 oldest active users, starting from age 21
268
KVStoreView<User> query1 = store.view(User.class)
269
    .index("age")           // Order by age
270
    .first(21)              // Start from age 21
271
    .reverse()              // Oldest first
272
    .max(10);               // Limit to 10 results
273

274
// Get users with names between "John" and "Mary", skip first 5
275
KVStoreView<User> query2 = store.view(User.class)
276
    .index("name")          // Order by name
277
    .first("John")          // Start from "John"
278
    .last("Mary")           // End at "Mary"
279
    .skip(5)                // Skip first 5 matches
280
    .max(20);               // Limit to 20 results
281

282
// Get tasks for specific project, ordered by priority, highest first
283
KVStoreView<Task> query3 = store.view(Task.class)
284
    .index("priority")      // Order by priority
285
    .parent("project123")   // Only tasks from project123
286
    .reverse();             // Highest priority first
287

288
// Pagination: get page 3 (entries 21-30) of users ordered by registration date
289
int page = 3;
290
int pageSize = 10;
291
KVStoreView<User> page3 = store.view(User.class)
292
    .index("registrationDate")
293
    .skip((page - 1) * pageSize)  // Skip 20 entries
294
    .max(pageSize);               // Get 10 entries
295
```