Package io.ebean

Class FetchConfig

  • All Implemented Interfaces:
    Serializable
    public class FetchConfig
extends Object
implements Serializable
    Defines the configuration options for a "query fetch" or a "lazy loading fetch". This gives you the ability to use multiple smaller queries to populate an object graph as opposed to a single large query.

    The primary goal is to provide efficient ways of loading complex object graphs avoiding SQL Cartesian product and issues around populating object graphs that have multiple *ToMany relationships.

    It also provides the ability to control the lazy loading queries (batch size, selected properties and fetches) to avoid N+1 queries etc.

    There can also be cases loading across a single OneToMany where 2 SQL queries using Ebean FetchConfig.query() can be more efficient than one SQL query. When the "One" side is wide (lots of columns) and the cardinality difference is high (a lot of "Many" beans per "One" bean) then this can be more efficient loaded as 2 SQL queries. 

    
 // Normal fetch join results in a single SQL query
 List<Order> list = DB.find(Order.class).fetch("details").findList();

 // Find Orders join details using a single SQL query

    Example: Using a "query join" instead of a "fetch join" we instead use 2 SQL queries 

    

 // This will use 2 SQL queries to build this object graph
 List<Order> list =
     DB.find(Order.class)
         .fetch("details", new FetchConfig().query())
         .findList();

 // query 1) find order
 // query 2) find orderDetails where order.id in (?,?...) // first 100 order id's

    Example: Using 2 "query joins" 

    

 // This will use 3 SQL queries to build this object graph
 List<Order> list =
     DB.find(Order.class)
         .fetch("details", new FetchConfig().query())
         .fetch("customer", new FetchConfig().queryFirst(5))
         .findList();

 // query 1) find order
 // query 2) find orderDetails where order.id in (?,?...) // first 100 order id's
 // query 3) find customer where id in (?,?,?,?,?) // first 5 customers

    Example: Using "query joins" and partial objects 

    
 // This will use 3 SQL queries to build this object graph
 List<Order> list =
     DB.find(Order.class)
         .select("status, shipDate")
         .fetch("details", "quantity, price", new FetchConfig().query())
         .fetch("details.product", "sku, name")
         .fetch("customer", "name", new FetchConfig().queryFirst(5))
         .fetch("customer.contacts")
         .fetch("customer.shippingAddress")
         .findList();

 // query 1) find order (status, shipDate)
 // query 2) find orderDetail (quantity, price) fetch product (sku, name) where
 // order.id in (?,? ...)
 // query 3) find customer (name) fetch contacts (*) fetch shippingAddress (*)
 // where id in (?,?,?,?,?)

 // Note: the fetch of "details.product" is automatically included into the
 // fetch of "details"
 //
 // Note: the fetch of "customer.contacts" and "customer.shippingAddress"
 // are automatically included in the fetch of "customer"

    You can use query() and lazy together on a single join. The query is executed immediately and the lazy defines the batch size to use for further lazy loading (if lazy loading is invoked). 

    

 List<Order> list =
     DB.find(Order.class)
         .fetch("customer", new FetchConfig().query(10).lazy(5))
         .findList();

 // query 1) find order
 // query 2) find customer where id in (?,?,?,?,?,?,?,?,?,?) // first 10 customers
 // .. then if lazy loading of customers is invoked
 // .. use a batch size of 5 to load the customers

    Example of controlling the lazy loading query:

    This gives us the ability to optimise the lazy loading query for a given use case. 

    

 List<Order> list = DB.find(Order.class)
   .fetch("customer","name", new FetchConfig().lazy(5))
   .fetch("customer.contacts","contactName, phone, email")
   .fetch("customer.shippingAddress")
   .where().eq("status",Order.Status.NEW)
   .findList();

 // query 1) find order where status = Order.Status.NEW
 //
 // .. if lazy loading of customers is invoked
 // .. use a batch size of 5 to load the customers
    Author:
    mario, rbygrave
    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      FetchConfig()
      Construct the fetch configuration object.

    • Constructor Detail

      • FetchConfig

        public FetchConfig()
        Construct the fetch configuration object.

    • Method Detail

      • lazy

        public FetchConfig lazy()
        Specify that this path should be lazy loaded using the default batch load size.

      • lazy

        public FetchConfig lazy​(int lazyBatchSize)
        Specify that this path should be lazy loaded with a specified batch size.
        Parameters:
        lazyBatchSize - the batch size for lazy loading

      • query

        public FetchConfig query()
        Eagerly fetch the beans in this path as a separate query (rather than as part of the main query).

        This will use the default batch size for separate query which is 100.

      • cache

        public FetchConfig cache()
        Eagerly fetch the beans fetching the beans from the L2 bean cache and using the DB for beans not in the cache.

      • query

        public FetchConfig query​(int queryBatchSize)
        Eagerly fetch the beans in this path as a separate query (rather than as part of the main query).

        The queryBatchSize is the number of parent id's that this separate query will load per batch.

        This will load all beans on this path eagerly unless a lazy(int) is also used.

        Parameters:
        queryBatchSize - the batch size used to load beans on this path

      • queryFirst

        public FetchConfig queryFirst​(int queryBatchSize)
        Eagerly fetch the first batch of beans on this path. This is similar to query(int) but only fetches the first batch.

        If there are more parent beans than the batch size then they will not be loaded eagerly but instead use lazy loading.

        Parameters:
        queryBatchSize - the number of parent beans this path is populated for

      • getLazyBatchSize

        public int getLazyBatchSize()
        Return the batch size for lazy loading.

      • getQueryBatchSize

        public int getQueryBatchSize()
        Return the batch size for separate query load.

      • isQueryAll

        public boolean isQueryAll()
        Return true if the query fetch should fetch 'all' rather than just the 'first' batch.

      • isCache

        public boolean isCache()
        Return true if this uses L2 bean cache.