v6: Pagination

[bevzzz]

This PR adds Pagination API for sync and async clients. Owing to a different asynchronous programming model that we have in Java, the APIs are not identical.

Sync

Synchronous pagination is instantly familiar. CursorSpliterator powers 2 patterns for iterating over objects:

• the default Paginator object returned by collection.paginate() implements Iterable that can be used in a traditional for-loop
• stream() presents the internal Spliterator via an idiomatic Stream API

var things = client.collections.use("Things");
var allThings = things.paginate();

for (WeaviateObject object : allThings) {
    // Traditional for-loop
}

// Stream API
var listOfThings = allThings.stream().map(/* some transformations */).toList();

Async

We cannot do the exact same thing in asynchronous part of the client; Streams and Iterator APIs are inherently synchronous and resist being bent into asynchronicity.

Our API ends up looking only slightly differently:

var things = client.collections.use("Things");

things.paginate().forEach(thing -> System.out.println(thing));

In case other components of the application are also doing async-batching type of work, it is possible to process complete pages at once too:

things.paginate().forPage(manyThings -> otherApi.sendAsync(manyThings));

AsyncPaginator supports prefetching, so that work can begin before the main thread starts to process results:

// The first request is sent immediately;
var allThings = things.paginate(p -> p.prefetch(true));

// We can do something else right away
animals.query.fetchObjects(...);

// Start processing Things
allThings.forEach(thing -> System.out.print(thing));

// Do something else:
things.data.insert(...);

// Block until pagination completes
allThings.get();

For example, it is possible to write an async for loop in Python, where each await cedes control to the event loop. Java's concurrency is built on threads and we end up working at a slightly lower level.

E.g.: asynchronously iterating over a loop requires manually scheduling recursive callbacks. Some pseudo-code to illustrate:

iter = db.iterator()
iter.nextPage().then(processAll)

fn processAll(page) {
  if page is empty { return }
  
  for obj in page { ... }
  page.nextPage().then(processAll)

The example snippet above demonstrates the helper forEach which reduces the boilerplate necessary.

Passing query options

// Create a paginator
var allThings = things.paginate(
  p -> p
    .pageSize(10)
    .resumeFrom("uuid-3")
    .returnProperties("name", "height")
    .returnMetadata(Metadata.VECTOR));

// Process data (sync: stream or for-loop, async: forEach / forPage)
allThings.stream().toList();

I purposefully omitted passing arguments to .stream() method, because normally this method does not take any parameters.

[orca-security-eu]

Orca Security Scan Summary

Status	Check	Issues by priority
Passed	Secrets	0   0   0   0	View in Orca