zquery

Type Members

1. final class Cache extends AnyRef

   

   A Cache maintains an internal state with a mapping from requests to Refs that will contain the result of those requests when they are executed.

   A Cache maintains an internal state with a mapping from requests to Refs that will contain the result of those requests when they are executed. This is used internally by the library to provide deduplication and caching of requests.

2. final class CompletedRequestMap extends AnyRef

   

   A CompletedRequestMap is a universally quantified mapping from requests of type Request[E, A] to results of type Either[E, A[ for all types E and A.

   A CompletedRequestMap is a universally quantified mapping from requests of type Request[E, A] to results of type Either[E, A[ for all types E and A. The guarantee is that for any request of type Request[E, A], if there is a corresponding value in the map, that value is of type Either[E, A]. This is used by the library to support data sources that return different result types for different requests while guaranteeing that results will be of the type requested.

3. trait DataSource[-R, -A] extends AnyRef

   

   A DataSource[R, A] is capable of executing requests of type A that require an environment R.

   A DataSource[R, A] is capable of executing requests of type A that require an environment R.

   Data sources must implement the method run which takes a collection of requests and returns an effect with a CompletedRequestMap containing a mapping from requests to results. Because run is parameterized on a collection of requests rather than a single request, data sources have the ability to introspect on all the requests being executed in parallel and optimize the query.

   Data sources will typically be parameterized on a subtype of Request[A], though that is not strictly necessarily as long as the data source can map the request type to a Request[A]. Data sources can then pattern match on the collection of requests to determine the information requested, execute the query, and place the results into the CompletedRequestsMap using CompletedRequestMap.empty and CompletedRequestMap.insert. Data sources must provide results for all requests received. Failure to do so will cause a query to die with a QueryFailure when run.

4. trait DataSourceFunction[+R, -R1] extends AnyRef

   

   A DataSourceFunction[R, R1] is a universally quantified function from values of type DataSource[R, A] to values of type DataSource[R1, A] for all types A.

   A DataSourceFunction[R, R1] is a universally quantified function from values of type DataSource[R, A] to values of type DataSource[R1, A] for all types A. This is used internally by the library to describe functions for transforming data sources that do not change the type of requests that a data source is able to execute.

5. final case class Described[+A](value: A, description: String) extends Product with Serializable

   

   A Described[A] is a value of type A along with a string description of that value.

   A Described[A] is a value of type A along with a string description of that value. The description may be used to generate a hash associated with the value, so values that are equal should have the same description and values that are not equal should have different descriptions.

6. type Query[+E, +A] = ZQuery[Any, E, A]

   

7. final case class QueryFailure(dataSource: DataSource[Nothing, Nothing], request: Request[Any, Any]) extends Throwable with Product with Serializable

   

   QueryFailure keeps track of details relevant to query failures.

8. type RQuery[-R, +A] = ZQuery[R, Throwable, A]

   

9. trait Request[+E, +A] extends AnyRef

   

   A Request[E, A] is a request from a data source for a value of type A that may fail with an E.

   A Request[E, A] is a request from a data source for a value of type A that may fail with an E.

   sealed trait UserRequest[+A] extends Request[Nothing, A]
   
   case object GetAllIds                 extends UserRequest[List[Int]]
   final case class GetNameById(id: Int) extends UserRequest[String]

10. type TaskQuery[+A] = ZQuery[Any, Throwable, A]

    

11. type UQuery[+A] = ZQuery[Any, Nothing, A]

    

12. type URQuery[-R, +A] = ZQuery[R, Nothing, A]

    

13. final class ZQuery[-R, +E, +A] extends AnyRef

    

    A ZQuery[R, E, A] is a purely functional description of an effectual query that may contain requests from one or more data sources, requires an environment R, may fail with an E, and may succeed with an A.

    A ZQuery[R, E, A] is a purely functional description of an effectual query that may contain requests from one or more data sources, requires an environment R, may fail with an E, and may succeed with an A. All requests that do not need to be performed sequentially, as expressed by flatMap or combinators derived from it, will automatically be batched, allowing for aggressive data source specific optimizations. Requests will also automatically be deduplicated and cached.

    This allows for writing queries in a high level, compositional style, with confidence that they will automatically be optimized. For example, consider the following query from a user service.

    val getAllUserIds: ZQuery[Any, Nothing, List[Int]] = ???
    def getUserNameById(id: Int): ZQuery[Any, Nothing, String] = ???
    
    for {
      userIds   <- getAllUserIds
      userNames <- ZQuery.foreachPar(userIds)(getUserNameById)
    } yield userNames

    This would normally require N + 1 queries, one for getAllUserIds and one for each call to getUserNameById. In contrast, ZQuery will automatically optimize this to two queries, one for userIds and one for userNames, assuming an implementation of the user service that supports batching.

    Based on "There is no Fork: an Abstraction for Efficient, Concurrent, and Concise Data Access" by Simon Marlow, Louis Brandy, Jonathan Coens, and Jon Purdy. http://simonmar.github.io/bib/papers/haxl-icfp14.pdf