Resolvers
#
AboutResolvers are functions that read/write data from your database based on parameters that we pass in.
You can read more about them here.
Please note that mutation resolvers that create entities are not provided IDs, since most databases generate IDs for you. If your database does not generate IDs, then you must do this manually in your resolver before you write to your database.
Every resolver function accepts context as the final parameter. See the context guide for more info.
info
If you are using the default database, then you can skip this step by using the default resolvers. More details here.
If you are using the default database, you can skip to the authentication guide.
info
If you are using an SQL-like database, we recommend using the SQL Resolver Generator package for easier and faster implementation.
warning
The examples below use a fictional ORM to make queries to the database. You can use any method you want to make database queries, as long as your resolver function returns the correct data.
#
TimestampsBy default, any field called createdAt
, updatedAt
or lastRead
will be set to whatever value you return from your getNow
callback.
Any field called annotationCreatedAt
will be set to a unix timestamp in MS, which you must convert to your databases format.
See the timestamps guide for more info.
#
Query resolversQuery resolvers are passed in via the Query
property on the resolvers object.
Most query resolvers come with a set of filters that you must apply to each query.
user
#
user(id, context): Promise<User>
id
(string) the id of the user to fetchcontext
(Context) context about the user. See the context guide for more info.
Used to get a user entity by its ID.
Must return a promise that resolves to a user, or null if a user is not found.
Example
userWithEmail
#
userWithEmail(email, context): Promise<User>
email
(string) the email of the user we need to fetchcontext
(Context) context about the user. See the context guide for more info.
Used to get a user entity by their email. This is used for invites.
Must return a promise that resolves to a user, or null if not found.
Example
userByIdentifier
#
OPTIONAL - This resolver is only required if using the offline annotation sync feature or the snapshots feature
userByIdentifier(identifier, context): Promise<User>
identifier
(string) either the email or username of the usercontext
(Context) context about the user. See the context guide for more info.
Used to get a user entity by an unknown identifier. Your resolver should query by both email and username.
Must return a promise that resolves to a user, or null if not found.
Example
annotations
#
info
Please read this spec carefully and make sure to follow all the guidelines provided!
annotation(query, context): Promise<Annotations[]>
query
(object) an object containing data and filters to query withids
(string[]) a list of annotation IDs to fetch. If this is not provided, fetch all annotations that match the rest of the criteria.annotationIds
(string[]) if provided, only fetch annotations that match one of the providedannotationId
documentId
(string) if provided, only fetch annotations belonging to this documentpageNumbers
(number[]) if provided, only fetch annotations that match one of the provided page numbersinReplyTo
(string) if provided, only fetch annotations whoseinReplyTo
field matches this IDfilters
(Filters) an object containing filters to apply to the query.
context
(Context) context about the user. See the context guide for more info.
Used to get a list of annotations.
Must return a promise that resolves to an array of annotations.
Example
documents
#
info
Please read this spec carefully and make sure to follow all the guidelines provided!
documents(query, context): Promise<Document[]>
query
(object) an object containing data and filters to query withids
(string[]) a list of document IDs to fetch. If this is not provided, fetch all documents that match the rest of the criteria.userId
(string) if provided, only fetch documents that this user belongs to (requires a query to document members - see the example below)isPublic
(boolean) if true, only return documents that are publicfilters
(Filters) an object containing filters to apply to the query.
context
(Context) context about the user. See the context guide for more info.
Used to get a list of documents.
Must return a promise that resolves to an array of documents.
Example
annotationMembers
#
info
Please read this spec carefully and make sure to follow all the guidelines provided!
annotationMembers(query, context): Promise<AnnotationMember[]>
query
(object) an object containing data and filters to query withids
(string[]) a list of document IDs to fetch. If this is not provided, fetch all members that match the rest of the criteria.annotationId
(string) if provided, only fetch members that belong to this annotationdocumentId
(string) if provided, only fetch annotation members with this document IDuserId
(string) if provided, only fetch memberships that belong to this userfilters
(Filters) an object containing filters to apply to the query.
context
(Context) context about the user. See the context guide for more info.
Used to get a user's membership to an annotation.
Must return a promise that resolves to a list of annotation members.
Example
documentMembers
#
info
Please read this spec carefully and make sure to follow all the guidelines provided!
documentMembers(query, context): Promise<DocumentMember[]>
query
(object) an object containing data and filters to query withids
(string[]) a list of document IDs to fetch. If this is not provided, fetch all members that match the rest of the criteria.documentId
(string) if provided, only fetch members that belong to this documentuserId
(string) if provided, only fetch memberships that belong to this userfilters
(Filters) an object containing filters to apply to the query.
context
(Context) context about the user. See the context guide for more info.
Used to get a user's membership to a document.
Must return a promise that resolves to a an array of document member.
Example
mentions
#
info
Please read this spec carefully and make sure to follow all the guidelines provided!
mentions(query, context): Promise<Mentions[]>
query
(object) an object containing data and filters to query withids
(string[]) a list of mention IDs to fetch. If this is not provided, fetch all mentions that match the rest of the criteria.annotationId
(string) if provided, only fetch mentions that belong to this annotationuserId
(string) if provided, only fetch mentions that belong to this userdocumentId
(string) if provided, fetch all mentions that belong to this documentfilters
(Filters) an object containing filters to apply to the query.
context
(Context) context about the user. See the context guide for more info.
Used to get a user's mention to an annotation.
Must return a promise that resolves to a list of mentions.
Example
annotationCount
#
annotationCount(query, context): Promise<number>
query
(object)documentId
(string) query the number of annotations for this documentsince
(number - timestamp in ms) query the number of annotations that were created after this time
context
(Context) context about the user. See the context guide for more info.
This is a very important query that is used to calculate the number of unread messages for a user. It needs to return the number of annotations belonging to the specified document that were created AFTER the since
parameter.
Note: it should only query annotations where the author ID is not null.
Example
annotationMemberCount
#
annotationMemberCount(query, context): Promise<number>
query
(object)documentId
(string) query the number of annotation members for this documentuserId
(string) query memberships for this usersince
(number - timestamp in ms) query the number of annotation members where "annotation_created_at" is greater than this timestamp
context
(Context) context about the user. See the context guide for more info.
This is another important query that we use to calculate unread count for a document. It needs to return the number of annotation members where annotation_created_at
is greater than the since
parameter.
In other words, this query returns the number of annotation members whose corresponding annotation was created after since
.
Example
snapshots
#
This resolver is only required if you are using the snapshots feature
snapshots(query, context): Promise<Snapshot[]>
query
(object)ids
(string[]) if provided, fetch only the snapshots with these IDsdocumentId
(string) if provided, fetch snapshots only belonging to this document IDfilters
(Filters) an object containing filters to apply to the query.
context
(Context) context about the user. See the context guide for more info.
Used to get all the snapshots for a document.
Must return a promise that resolves to an array of Snapshots.
Example
snapshotAssets
#
This resolver is only required if you are using the snapshots feature
snapshotAssets(query, context): Promise<SnapshotAssets[]>
query
(object)ids
(string[]) if provided, fetch only the snapshot assets with these IDssnapshotId
(string) if provided, fetch snapshot assets only belonging to this snapshot ID
context
(Context) context about the user. See the context guide for more info.
Used to get all the snapshot assets for a document.
Must return a promise that resolves to an array of snapshots assets.
Example
#
Mutation resolversMutation resolvers are passed in via the Mutation
property on the resolvers object.
Mutation resolvers that create entities are required to return the created entity.
warning
Since most databases generate IDs for new entities, we do not pass an ID field to the mutation resolvers. If your database does not generate IDs for you, then you need to do this manually in your resolvers.
addUser
#
addUser(user, context): Promise<User>
user
(User) The user entity to write to the databasecontext
(Context) context about the user. See the context guide for more info.
Used to create new users in the database. This is mainly for creating anonymous users when a person without an account is invited.
Must resolve with the written user entity.
Example
addAnnotation
#
addAnnotation(annotation, context): Promise<Annotation>
annotation
(Annotation) the annotation to createcontext
(Context) context about the user. See the context guide for more info.
Used to save an annotation to the database.
Must resolve with the saved annotation object.
Example
batchAddAnnotations
#
OPTIONAL - This resolver is optional, but highly recommended as batch inserting data can greatly increase write speeds. If this resolver is not provided, we will instead loop over the addAnnotation
resolver.
batchAddAnnotations(annotations, context): Promise<Annotation[]>
annotations
(Annotation[]) An array of annotations to createcontext
(Context) context about the user. See the context guide for more info.
Used to save multiple annotations to the database.
Must resolve with an array of annotation objects.
Example
editAnnotation
#
editAnnotation(id, editAnnotInput, context): Promise<Annotation>
id
(string) the ID of the annotation to editeditAnnotInput
(object) an object containing the fields to edit. Can contain the following (both optional)xfdf
(string) The annotation's new XFDF (optional)pageNumber
(number) The annotation's new pageNumber (optional)updatedAt
(number) the timestamp of when the entity was updated at
context
(Context) context about the user. See the context guide for more info.
Used to edit an annotation. This is called when an existing annotation is moved, changed, etc.
Must resolve to the new annotation entity.
Example
deleteAnnotation
#
deleteAnnotation(id, context): Promise<{ successful: boolean }>
id
(string) the id of the annotation to deletecontext
(Context) context about the user. See the context guide for more info.
Used to delete annotations from the database.
Must resolve to an object with a successful
boolean, indicating if the operation was successful.
Example
addDocument
#
addDocument(document, context): Promise<Document>
document
(Document) the document to write to the databasecontext
(Context) context about the user. See the context guide for more info.
Used to add a document to the database.
Must resolve with the new document object
Example
editDocument
#
editDocument(id, editDocInput, context): Promise<Document>
id
(string) the id of the document to editeditDocInput
(object) the fields to edit on the document (all properties are optional)name
(string) the document's new nameisPublic
(boolean) whether or not the document is now publicupdatedAt
(number) the timestamp of when the entity was updated at
context
(Context) context about the user. See the context guide for more info.
Used to edit a document.
Must resolve with the updated document entity.
Example
deleteDocument
#
deleteDocument(id, context): Promise<{ successful: boolean }>
id
(string) the id of the document to deletecontext
(Context) context about the user. See the context guide for more info.
Used to delete a document from the DB.
Must resolve with an object with a successful
property indicating if the operation was successful.
Example
addDocumentMember
#
addDocumentMember(member, context): Promise<DocumentMember>
member
(DocumentMember) the document member to write to the databasecontext
(Context) context about the user. See the context guide for more info.
Used to write a document membership to the database.
Must resolve with the created document member entity.
Example
editDocumentMember
#
editDocumentMember(id, editMemberInput, context): Promise<DocumentMember>
id
(string) the id of the document member to editeditMemberInput
(object) the properties to edit on the memberlastRead
(number) the timestamp of when the person read the documentupdatedAt
(number) the timestamp of when the entity was updated at
context
(Context) context about the user. See the context guide for more info.
Used to edit the membership of a document member.
Must resolve to the updated document member
Example
deleteDocumentMember
#
deleteDocumentMember(id, context): Promise<{ successful: boolean }>
id
(string) the id of the document member to deletecontext
(Context) context about the user. See the context guide for more info.
Used to delete a document member from the database.
Must resolve to an object with a successful
property indicating if the operation was successful or not.
Example
addAnnotationMember
#
addAnnotationMember(member, context): Promise<AnnotationMember>
member
(AnnotationMember) the annotation member to writecontext
(Context) context about the user. See the context guide for more info.
Used to write an annotation member to the database.
Must resolve with the new annotation member.
Example
batchAddAnnotationMembers
#
OPTIONAL - This resolver is optional, but highly recommended as batch inserting data can greatly increase write speeds. If this resolver is not provided, we will instead loop over the addAnnotationMember
resolver.
batchAddAnnotationMembers(members, context): Promise<AnnotationMember[]>
members
(AnnotationMember[]) the annotation members to writecontext
(Context) context about the user. See the context guide for more info.
Used to write multiple annotation members to the database.
Must resolve with an array of annotation member.
Example
editAnnotationMember
#
editAnnotationMember(id, editMemberInput, context): Promise<AnnotationMember>
id
(string) the id of the annotation member to editeditMemberInput
(object) the properties to update on the annotation member (all are optional)lastRead
(number) the timestamp of when the last time the person read the annotationupdatedAt
(number) the timestamp of when the entity was updated at
context
(Context) context about the user. See the context guide for more info.
Used to update a user's membership to an annotation.
Must resolve with the updated annotation member.
Example
deleteAnnotationMember
#
deleteAnnotationMember(id, context): Promise<{ successful: boolean }>
id
(string) the id of the member to deletecontext
(Context) context about the user. See the context guide for more info.
Used to delete an annotation member.
Must resolve with an object containing a successful
property indicating if the operation was successful or not.
Example
addMention
#
addMention(mention, context): Promise<mention>
mention
(Mention) the mention to writecontext
(Context) context about the user. See the context guide for more info.
Used to write a mention to the database.
Must resolve with the new mention.
Example
deleteMention
#
deleteMention(id, context): Promise<{ successful: boolean }>
id
(string) the id of the mention to deletecontext
(Context) context about the user. See the context guide for more info.
Used to delete a mention.
Must resolve with an object containing a successful
property indicating if the operation was successful or not.
Example
addSnapshot
#
This resolver is only required if you are using the snapshots feature
addSnapshot(snapshot, context): Promise<Snapshot>
snapshot
(Snapshot) the snapshot to writecontext
(Context) context about the user. See the context guide for more info.
Used to write a snapshot to the database.
Must resolve with the new snapshot.
Example
editSnapshot
#
This resolver is only required if you are using the snapshots feature
editSnapshot(id, params, context): Promise<Snapshot>
id
(string) The ID of the snapshot to editparams
Properties of the snapshot to editparams.name
(string) The new name of the snapshotparams.updatedAt
(number) The timestamp the entity was edited at
context
(Context) context about the user. See the context guide for more info.
Used to edit a snapshot in the database.
Must resolve with the updated snapshot.
Example
deleteSnapshot
#
This resolver is only required if you are using the snapshots feature
deleteSnapshot(id, context): Promise<{ success: boolean }>
id
(string) The ID of the snapshot to editcontext
(Context) context about the user. See the context guide for more info.
Used to delete a snapshot.
Must resolve with an object containing a successful
property indicating if the operation was successful or not.
Example
addSnapshotAsset
#
This resolver is only required if you are using the snapshots feature
addSnapshotAsset(snapshotAsset, context): Promise<SnapshotAsset>
snapshotAsset
(SnapshotAsset) the snapshot asset to writecontext
(Context) context about the user. See the context guide for more info.
Used to write a snapshot asset to the database.
Must resolve with the new snapshot asset.
Example
editSnapshotAsset
#
This resolver is only required if you are using the snapshots feature
editSnapshotAsset(id, params, context): Promise<SnapshotAsset>
id
(string) The ID of the snapshot asset to editparams
Properties of the snapshot to editparams.snapshotId
(string) The new ID of the snapshotparams.updatedAt
(number) The timestamp the entity was edited at
context
(Context) context about the user. See the context guide for more info.
Used to edit a snapshot asset in the database.
Must resolve with the updated snapshot asset.
Example
deleteSnapshotAsset
#
This resolver is only required if you are using the snapshots feature
deleteSnapshotAsset(id, context): Promise<{ success: boolean }>
id
(string) The ID of the snapshot asset to editcontext
(Context) context about the user. See the context guide for more info.
Used to delete a snapshot asset.
Must resolve with an object containing a successful
property indicating if the operation was successful or not.
Example
#
Resolver entitiesUser entity
#
A user entity is an object with the following shape. Properties with a ?
are optional (but recommended).
Document entity
#
A document entity is an object with the following shape. Properties with a ?
are optional (but recommended).
Annotation entity
#
An annotation entity is an object with the following shape. Properties with a ?
are optional (but recommended).
note
More information on the annotationId
field can be found here
DocumentMember entity
#
AnnotationMember entity
#
An annotation member entity is an object with the following shape. Properties with a ?
are optional (but recommended).
An annotation member represents a user's 'membership' to an annotation. It is also used to track if a user has read an annotation or not.
Mention entity
#
A mention entity is an object with the following shape. Properties with a ?
are optional (but recommended).
A mention represents a mentioned user in an annotation.
Snapshot entity
#
A snapshot entity is an object with the following shape. Properties with a ?
are optional (but recommended).
A snapshot represents the state of a document at a certain period of time
Snapshot asset entity
#
A snapshot asset entity is an object with the following shape. Properties with a ?
are optional (but recommended).
A snapshot asset represents a large annotation belonging to a snapshot.
#
FiltersMost Query
resolvers come with a filter
object, containing 7 properties that should be used when making your query.
filters
(object) an object containing filters to apply to the querycreatedBefore
(number - timestamp in MS) If provided, only fetch entities created before this datecreatedAfter
(number - timestamp in MS) If provided, only fetch entities created after this dateupdatedBefore
(number - timestamp in MS) If provided, only fetch entities updated before this dateupdatedAfter
(number - timestamp in MS) If provided, only fetch entities updated after this dateorderBy
('updatedAt' | 'createdAt') if provided, order/sort your query byupdatedAt
orcreatedAt
orderDirection
('ASC' | 'DESC') if provided, order your query in the provided directionlimit
(number) if provided, limit your query to this amount
It is important that these filters are used properly, as they are what allows the application to scale.
note
Since these filters are the same across all queries, it is recommended to create a utility function to apply the filters to your queries!