DataLoader is a generic utility to be used as part of your application's data fetching layer to provide a simplified and consistent API over various remote data sources such as databases or web services via batching and caching.
This is a Swift version of the Facebook DataLoader.
Include this repo in your Package.swift file.
.package(url:"https://github.com/GraphQLSwift/DataLoader.git", from:"2.0.0")The AsyncDataLoader library is preferred. The DataLoader uses NIO for concurrency and is provided for backwards compatibility.
To get started, create a DataLoader. Each DataLoader instance represents a unique cache. Typically instances are created per request when used within a web-server if different users can see different things.
Batching is not an advanced feature, it's DataLoader's primary feature. Create a DataLoader by providing a batch loading function:
import AsyncDataLoader
letuserLoader=DataLoader<Int,User>(batchLoadFunction:{ keys intryUser.query(on: req).filter(\User.id ~~ keys).all().map{ users in
keys.map{ key inDataLoaderFutureValue.success(users.filter{ $0.id == key })}}})The order of the returned DataLoaderFutureValues must match the order of the input keys.
asyncletresult1= userLoader.load(key:1)asyncletresult2= userLoader.load(key:2)asyncletresult3= userLoader.load(key:1)The example above will only fetch two users, because the user with key 1 is present twice in the list.
There is also a method to load multiple keys at once
tryawait userLoader.loadMany(keys:[1,2,3])By default, a DataLoader will wait for a short time from the moment load is called to collect keys prior to running the batchLoadFunction and completing the load results. This allows keys to accumulate and batch into a smaller number of total requests. This amount of time is configurable using the executionPeriod option:
letmyLoader=DataLoader<String,String>(
options:DataLoaderOptions(executionPeriod:.milliseconds(50)),
batchLoadFunction:{ keys inself.someBatchLoader(keys: keys).map{DataLoaderFutureValue.success($0)}})Longer execution periods reduce the number of total data requests, but also reduce the responsiveness of the load futures.
If desired, you can manually execute the batchLoadFunction and complete the futures at any time, using the .execute() method.
Scheduled execution can be disabled by setting executionPeriod to nil, but be careful - you must call .execute() manually in this case. Otherwise, the futures will never complete!
It is possible to disable batching by setting batchingEnabled to false. In this case, the batchLoadFunction will be invoked immediately when a key is loaded.
DataLoader provides a memoization cache. After .load() is called with a key, the resulting value is cached for the lifetime of the DataLoader object. This eliminates redundant loads.
In addition to relieving pressure on your data storage, caching results also creates fewer objects which may relieve memory pressure on your application:
letuserLoader=DataLoader<Int,Int>(...)asyncletresult1= userLoader.load(key:1)asyncletresult2= userLoader.load(key:1)awaitprint(result1 == result2) // trueDataLoader caching does not replace Redis, Memcache, or any other shared application-level cache. DataLoader is first and foremost a data loading mechanism, and its cache only serves the purpose of not repeatedly loading the same data in the context of a single request to your Application. To do this, it maintains a simple in-memory memoization cache (more accurately: .load() is a memoized function).
Avoid multiple requests from different users using the DataLoader instance, which could result in cached data incorrectly appearing in each request. Typically, DataLoader instances are created when a Request begins, and are not used once the Request ends.
In certain uncommon cases, clearing the request cache may be necessary.
The most common example when clearing the loader's cache is necessary is after a mutation or update within the same request, when a cached value could be out of date and future loads should not use any possibly cached value.
Here's a simple example using SQL UPDATE to illustrate.
// Request begins...
letuserLoader=DataLoader<Int,Int>(...)
// And a value happens to be loaded (and cached).
tryawait userLoader.load(key:4)
// A mutation occurs, invalidating what might be in cache.
tryawaitsqlRun('UPDATE users WHERE id=4 SET username="zuck"')await userLoader.clear(key:4)
// Later the value load is loaded again so the mutated data appears.
tryawait userLoader.load(key:4)
// Request completes.If a batch load fails (that is, a batch function throws or returns a DataLoaderFutureValue.failure(Error)), then the requested values will not be cached. However if a batch function returns an Error instance for an individual value, that Error will be cached to avoid frequently loading the same Error.
In some circumstances you may wish to clear the cache for these individual Errors:
do{tryawait userLoader.load(key:1)}catch{if(/* determine if should clear error */){await userLoader.clear(key:1);
}throw error
}In certain uncommon cases, a DataLoader which does not cache may be desirable. Calling DataLoader(options: DataLoaderOptions(cachingEnabled: false), batchLoadFunction: batchLoadFunction) will ensure that every call to .load() will produce a new Future, and previously requested keys will not be saved in memory.
However, when the memoization cache is disabled, your batch function will receive an array of keys which may contain duplicates! Each key will be associated with each call to .load(). Your batch loader should provide a value for each instance of the requested key.
For example:
letmyLoader=DataLoader<String,String>(
options:DataLoaderOptions(cachingEnabled:false),
batchLoadFunction:{ keys inself.someBatchLoader(keys: keys).map{DataLoaderFutureValue.success($0)}})tryawait myLoader.load(key:"A")tryawait myLoader.load(key:"B")tryawait myLoader.load(key:"A")
// > [ "A", "B", "A" ]More complex cache behavior can be achieved by calling .clear() or .clearAll() rather than disabling the cache completely. For example, this DataLoader will provide unique keys to a batch function due to the memoization cache being enabled, but will immediately clear its cache when the batch function is called so later requests will load new values.
letmyLoader=DataLoader<String,String>(batchLoadFunction:{ keys inawait identityLoader.clearAll()returnsomeBatchLoad(keys: keys)})DataLoader pairs nicely well with GraphQL and Graphiti. GraphQL fields are designed to be stand-alone functions. Without a caching or batching mechanism, it's easy for a naive GraphQL server to issue new database requests each time a field is resolved.
Consider the following GraphQL request:
{
me {
name
bestFriend {
name
}
friends(first: 5) {
name
bestFriend {
name
}
}
}
}
Naively, if me, bestFriend and friends each need to request the backend, there could be at most 12 database requests!
By using DataLoader, we could batch our requests to a User type, and only require at most 4 database requests, and possibly fewer if there are cache hits. Here's a full example using Graphiti:
structUser:Codable{letid:Intletname:StringletbestFriendID:IntletfriendIDs:[Int]func getBestFriend(context:UserContext, arguments:NoArguments)throws->User{returntryawait context.userLoader.load(key: user.bestFriendID)}struct FriendArguments {
first: Int
}func getFriends(context:UserContext, arguments:FriendArguments)throws->[User]{returntryawait context.userLoader.loadMany(keys: user.friendIDs[0..<arguments.first])}}structUserResolver{publicfunc me(context:UserContext, arguments:NoArguments)->User{...}}classUserContext{letdatabase=...letuserLoader=DataLoader<Int,User>(){[weak self] keys inguardlet self =selfelse{throw ContextError }letusers=tryawaitUser.query(on:self.database).filter(\.$id ~~ keys).all()return keys.map{ key in
users.first{ $0.id == key }!
}}}structUserAPI:API{letresolver=UserResolver()letschema=Schema<UserResolver,UserContext>{Type(User.self){Field("name", at: \.content)Field("bestFriend", at: \.getBestFriend, as: TypeReference<User>.self)Field("friends", at: \.getFriends, as:[TypeReference<User>]?.self){Argument("first", at:.\first)}}Query{Field("me", at:UserResolver.hero, as:User.self)}}}All your feedback and help to improve this project is very welcome. Please create issues for your bugs, ideas and enhancement requests, or better yet, contribute directly by creating a PR. 😎
When reporting an issue, please add a detailed example, and if possible a code snippet or test to reproduce your problem. 💥
When creating a pull request, please adhere to the current coding style where possible, and create tests with your code so it keeps providing an awesome test coverage level 💪
This repo uses the standard swift format, and includes lint checks to enforce these formatting standards. To format your code, run:
swift format --parallel --in-place --recursive ./This library is entirely a Swift version of Facebook's DataLoader. Developed by Lee Byron and Nicholas Schrock from Facebook.