You can either write queries inside your JavaScript files with gql, or if you use webpack, you can use graphql-tag/loader to import GraphQL query files (*.graphql) directly.
Collections
Every top-level name in a query is considered a Firestore collection. For
example, in the query below, we are querying every document in the posts
collection and retrieving the id, title, and body values from each
document in the response. Note: id is a special field that actually retrieves
the document key.
const { posts } = await firegraph.resolve(firestore, gql`
query {
posts {
id
title
body
}
}
`)
Subcollections
When you have nested values (e.g. in the query below), they are processed
as child collections. To clarify, for each doc in the posts collection,
we also retrieve the posts/${doc.id}/comments collection. This result is
stored in the comments key for each document that is returned.
const { posts: postsWithComments } = await firegraph.resolve(firestore, gql`
query {
posts {
id
title
body
comments {
id
body
}
}
}
`)
Document References
Right now, we are assuming that post.author is a string that matches the ID of some document in the users collection. In the future we will leverage Firestore's DocumentReference value type to handle both use cases.
const { posts: postsWithAuthorAndComments } = await firegraph.resolve(firestore, gql`
query {
posts {
id
title
body
author(matchesKeyFromCollection: "users") {
id
displayName
}
comments {
id
body
author(matchesKeyFromCollection: "users") {
id
displayName
}
}
}
}
`)
Filtering Results
One of our primary goals is to wrap the Firestore API in its entirety. That said, the where
clause in Firegraph maps directly to the expected behavior in Firestore:
someKey: someValue maps to .where(someKey, '==', someValue)someKey_gt: someValue maps to .where(someKey, '>', someValue)someKey_gte: someValue maps to .where(someKey, '>=', someValue)someKey_lt: someValue maps to .where(someKey, '<', someValue)someKey_lte: someValue maps to .where(someKey, '>=', someValue)someKey_contains: someValue maps to .where(someKey, 'array-contains', someValue)
For the last one, of course, someKey would have to use Firestore's array type. All of the restrictions
related to compound queries with Firestore (no logical OR or inequality testing) still apply but those
are some of the first things we are hoping to add support for.
const authorId = 'sZOgUC33ijsGSzX17ybT';
const { posts: postsBySomeAuthor } = await firegraph.resolve(firestore, gql`
query {
posts(where: {
author: ${authorId},
}) {
id
message
author(matchesKeyFromCollection: "users") {
id
}
}
}
`);
Roadmap
- [x] Querying values from collections
- [x] Querying nested collections
- [ ] GraphQL mutations allowing updates to multiple documents at once
- [ ] Basic search functionality (on par with current Firestore API)
- [ ] More advanced search functionality (GraphQL params, fragments, etc)
Contributing
Thank you for your interest! You are welcome (and encouraged) to submit Issues and Pull Requests. If you want to add features, check out the roadmap above (which will have more information as time passes). You are welcome to ping me on Twitter as well: @sjroot
