Converting result objects to lists, arrays, collections, and sets

You can convert the query result objects of entity queries to lists, arrays, collections, and sets by using the conversion methods:

  • toCollection
  • toSet
  • toList
  • toTypedArray
Important: Do not use the where method on lists, arrays, collections, or sets returned by conversion methods on result objects. Instead, apply all selection criteria to query objects by using predicate methods before calling the select method.

Converting a query result to these types executes the database query and iterates across the entire set. The application pulls all entities into local memory. Because of limitations of memory, database performance, and CPU performance, never do this conversion for queries of unknown size. Only do this conversion if you are absolutely certain that the result set size and the size of the object graphs are within acceptable limits. Be sure to test your assumptions under production conditions.

Warning: Converting a query result to a list or array pulls all the entities into local memory. Do this conversion only if you are absolutely certain that the result set size and the size of the objects are small. Otherwise, you risk memory and performance problems.

If you need the results as an array, you can convert to a list and then convert that to an array using Gosu enhancement methods.

The following example converts queries to different collection-related types, including arrays:

uses gw.api.database.Query

// Query for addresses in the city of Chicago
var query = Query.make(Address)
query.compare(Address#City, Equals, "Chicago")
var result = query.select()

// Specify the threshold for too many items in the result
var threshold = 101  // -- 101 or higher is too many
result.getCountLimitedBy(threshold)

// Test whether the result count crosses the threshold
if (result.getCountLimitedBy(threshold ) < threshold ) {
  // Iterate the results
  for (address in result) {
    print (address.AddressLine1 + ", " + address.City + ", " + address.PostalCode)
  }
} else {
  // Prompt for more criteria
  print ("The search will return too many items!") 
}
var query = Query.make(User)

// In production code, converting to lists or arrays can be dangerous due
//   to memory and performance issues. Never use this approach unless you are certain
//   the result size is small. In this demonstration, we check the count first.
//   In real-world code, you would not use this approach with the User table, which
//   can be larger than 100 rows.
if (query.select().Count < 100) {
  var resultCollection = query.select().toCollection() 
  var resultSet = query.select().toSet() 
  var resultList = query.select().toList() 
  var resultArray = query.select().toTypedArray() 

  print("Collection: typeof " + typeof resultCollection + "/ size " + resultCollection.Count)
  print("Set: typeof " + typeof resultSet + "/ size " + resultSet.Count)
  print("List: typeof " + typeof resultList + "/ size " + resultList.Count)
  print("Array: typeof " + typeof resultArray + "/ size " + resultArray.Count)
} else {
  throw("Too many query results to convert to in-memory collections")
}

This example prints something like the following:

Collection: typeof java.util.ArrayList/ size 34
Set: typeof java.util.HashSet/ size 34
List: typeof java.util.ArrayList/ size 34
Array: typeof entity.User[]/ size 34

See also