Lazy Query Tutorial

Onyx Database supports lazy retrieval of entities using the executeLazyQuery method. This method returns a list of record references rather than the entire entity. The references are used to hydrate the results when accessed through the get method. This is helpful when implementing infinite scrolling or reducing the packet size and memory footprint when displaying a list of results or retrieving a parent entity with an enormous child collection that hasFetchPolicy.LAZY. This tutorial demonstrates how to lazily query for data in Onyx Database.

Steps to Perform a Lazy Query (Onyx Cloud Database)

1

Create a Simple Query to Include All Records

Use the query builder syntax to create a query that includes all records of the Player entity type, ordered by firstName in ascending order.
1const query = db.from(Player).orderBy("firstName", "ASC");
  • The query builder allows for fluent query construction, making queries more readable and easier to maintain.
  • You can chain methods like where, orderBy, limit, etc., to build complex queries.
2

Invoke the executeLazyQuery Method

This will retrieve a LazyQueryCollection which extends the List interface.
1const allPlayers = await query.lazy(); // returns LazyQueryCollection

Notice that we have passed the criteria and a QueryOrder to sort by firstName in ascending order.

  • The Query constructors support the following arguments:
    • entityType: The class type of the entities you are requesting
    • criteria: The QueryCriteria you constructed in the last step
    • queryOrder: Allows you to order by field and direction (direction is set to ASC by default)
    • selections: A list of attributes you want to reduce the result rows down to
    • updates: List of AttributeUpdates. This enables you to perform bulk update queries
  • The Query also has the following properties that can be set after construction:
    • maxResults: The max number of rows returned
    • firstRow: The starting index of the first record returned (using zero-based counting)
    • partition: Specifies the partition to query the data from. If not specified, the query will span over all partitions.
    • resultCount: After executing a query you can call getResultCount() to get the total number of results that meet the query's criteria.
3

Iterate Over the LazyQueryCollection

Now, let's get and print out all entities in the LazyQueryCollection.
1for (let i = 0; i < allPlayers.size; i++) {
2    const player = allPlayers[i]; // retrieves the Player when invoked
3    console.log(`${player.firstName} ${player.lastName}`);
4}
  • Because the list that is returned is not fully hydrated, you cannot use the iterator or forEach methods or use the for-each loop construct. You must use a for loop using the count and call the get method on the list to retrieve the record when you want to hydrate the reference.
Next Tutorial: Group By and Query Functions

Important Notes

  • The lazy query returns references to the entities rather than fully hydrated entities. Accessing an entity via the get method will hydrate it.
  • Using lazy queries can significantly reduce memory usage and improve performance when dealing with large datasets.
  • Be cautious when iterating over the lazy collection; avoid methods that require full hydration of the collection.

Troubleshooting

  • Null Pointer Exceptions: Ensure that you are correctly accessing the entities using the get method on the lazy collection.
  • Performance Issues: If you experience performance issues, verify that you are not unintentionally hydrating the entire collection.
  • Unsupported Operations: Remember that certain collection methods are not supported on the lazy collection. Stick to using indexed access with get.

Next Steps

Now that you have learned how to perform a lazy query, you can explore more advanced querying techniques: