firegraph

Description:

firegraph

Firegraph #
Firegraph is a plugin that lets you query firestore with GraphQL.
Getting Started #
Its very simple to get started. Just Install and use!
Installing #
To get the package from pub, run following command in your project directory
flutter pub get firegraph
copied to clipboard
You can also include the package directly into pubspec.yaml file as
dependencies:
firegraph: ^1.0.0
copied to clipboard
Usage #
To use firegraph, one must import the following into their file
import 'package:firegraph/firegraph.dart'
copied to clipboard
Querying #
Querying Collections #
A collection can be queried same as a graphQL type query. For example, to query the collection posts with id and message fields for each document, the instruction would be:
Map posts = await Firegraph.resolve(FirebaseFirestore.instance, r'''
query{
posts{
id
body
}
}
''');
copied to clipboard
Querying Subcollections #
A subcollection can be treated as same as a type inside a parent type. For example, to query the subcollection comments inside document in the collection posts (the hierarchy is posts/doc/comments/doc) the instruction would be:
Map posts = await Firegraph.resolve(FirebaseFirestore.instance, r'''
query{
posts{
id
body
comments{
id
message
}
}
}
''');
copied to clipboard
This way you can query subcollections as deep as possible.
Querying Reference documents #
A DocumentReference field holding a reference to a document or a string field holding plain path to a document can be queried as a child of original document.
For example, a document in posts collections holds author DocumentReference which is a document in users collection, this can be queried in the following manner:
Map posts = await Firegraph.resolve(FirebaseFirestore.instance, r'''
query{
posts{
id
body
author{
id
name
age
}
}
}
''');
copied to clipboard
For String fields that hold the path to the document, same can be done. Aditionally, a parent path to document can be provided with path parameter. Example:
Map posts = await Firegraph.resolve(FirebaseFirestore.instance, r'''
query{
posts{
id
body
authorId(path:"users/"){
id
name
age
}
}
}
''');
copied to clipboard
for more reference on queries collections, subcollections & Documents, checkout examples.
Aliases #
We support aliases with same query structure as GraphQL. example:
Map posts = await Firegraph.resolve(FirebaseFirestore.instance, r'''
query{
articles: posts{
id
articleBody: body
writer: author{
id
name
age
}
}
}
''');
copied to clipboard
Filtering queries #
Document queries can be filtered using where query of firebase. We have support for every where query of firebase as graphql where arguments.
For example, if you want to query all users with age>30 you have to use _gt (greater than) suffix in where filter. Example query would be:
Map users = await Firegraph.resolve(FirebaseFirestore.instance, r'''
query{
users(where:{
age_gt: 30
}){
id
name
age
}
}
''');
copied to clipboard
so for any key, its suffix determines the operator. all the supported filters with suffixes are listed below.



Where filter
Suffix
Accepted values




.where(key, isEqualTo: value)
key_eq: value
any


.where(key, isNotEqualTo: value)
key_neq: value
any


.where(key, isGreaterThan: value)
key_gt: value
any


.where(key, isGreaterThanOrEqualTo: value)
key_gte: value
any


.where(key, isLessThan: value)
key_lt: value
any


.where(key, isLessThanOrEqualTo: value)
key_lte: value
any


.where(key, isNull: value)
key_null: value
boolean


.where(key, arrayContains: value)
key_contains: value
any


.where(key, arrayContainsAny: value)
key_containsAny: value
List


.where(key, whereIn: value)
key_in: value
List


.where(key, whereNotIn: value)
key_notIn: value
List



These filters can be applied to any collection or subcollection query, whether nested any deep! and in any amount. For more references, checkout the examples.
NOTE: For some queries you must have indexes already created in your firebase project. To create or view indexes in your firebase project, follow this link.
Ordering queries #
Document queries can be ordered using orderBy query of firebase. You can supply an orderBy argument of object type, defining the fields you want to sort by and the order of those fields as ascending or descending.
For example, if you want to query the users in ascending order of their age, your query would look like:
Map users = await Firegraph.resolve(FirebaseFirestore.instance, r'''
query{
users(orderBy:{
age: "asc"
}){
id
name
age
}
}
''');
copied to clipboard
For more references, checkout the examples.
Limit queries #
To limit the number of queried documents in a collection or subcollection, supply limit argument.
For example, to query only 10 users, your query would look like:
Map users = await Firegraph.resolve(FirebaseFirestore.instance, r'''
query{
users(limit: 10){
id
name
age
}
}
''');
copied to clipboard
Caching #
Firegraph implements a simple cache mechanism that stores all referenced documents queried via collections and sub-collections and provides cache benefit to explicitly referenced documents i.e. documents those are queried by reference.
Note that cache is distinct for each and every query.
Contributing #
Thank you for your interest! You are welcome (and encouraged) to submit Issues and Pull Requests. You are welcome to ping me on Twitter as well: @taosif7