It is quite straightforward to setup Delta Queries with an existing Graphback template, by following the steps outlined below:
Create a new Graphback project using:
When asked, choose the
apollo-mongo-datasync-server-ts template and proceed to the next step when the CLI has finished bootstrapping the project.
Annotate the required models
@datasync annotation to your model(s) in your GraphQL SDL found in the
@datasync annotation is used infer if a given model requires Delta Queries. If your business logic requires delete mutations,
@datasync also ensures that deleted objects are maintained in the database for a given amount of time. This can either be specified by the optional
ttl argument (given in seconds) otherwise defaults to a duration of 2 days (or 172800 seconds) This is done so clients can be informed about deletions in a delta query. The items are eventually deleted using a MongoDB TTL Index.
In the default configuration,
@datasync transforms your model by adding a
_lastUpdatedAt field to it:
_lastUpdatedAt field is automatically indexed by Graphback for faster delta queries.
@datasync annotation adds a
sync query or the delta query:
This allows you to get all the changed documents (updated and deleted) in a collection since the
lastSync timestamp. Internally this uses the
_lastUpdatedAt database field to check if any documents in the database have been modified, by comparing client provided
lastSync timestamp value.
sync query also accepts a filter argument for filtering as well as a limit argument for limiting the number of items retrieved.
@datasync annotation also adds a
Delta type and a
Delta type for a model consists of all of the model's transformed properties, as well as a
_deleted field which is used internally to mark documents as deleted in the database. Thus
delete mutations only mark documents with
_deleted: true instead of actually removing them.
DeltaList is a container for
Delta type, which also returns a
lastSync timestamp, that can be used in a subsequent
Modify the template to use
src/index.ts file of the template, use
createDataSyncAPI instead of
The data sources provided by
createDataSyncAPI ensure that:
- The documents are always soft deleted
- In the current configuration, provides out of the box delta queries for models that are annotated with
Issuing Delta/Sync queries from client
As an example consider the usecase when your application has stayed offline for a while. You can then use the
sync<Type>s query to retrieve only the changed documents rather than having to re-fetch all of the documents.
As an example response you might get:
The response is a list of the latest versions of the changed documents along with a
_deleted flag that is set to
true if the document has been deleted since
false otherwise. The response also contains a
lastSync timestamp which can be used in the next
In the example response, we get that the "First!" comment has been deleted, while another comment "Second!" has been updated.
There is no support for querying relationships through a delta query, all relationship fields are removed when constructing a delta Type.
Taking an example model definition with a
oneToMany relationship from the
Note type to the
Comment type has a
@datasync annotation, Graphback will construct a
CommentDelta type as follows:
Notice that there are is no relationship field in the