Query Cookbook

parse query cookbook in flutter introduction we’ve already seen how a querybuilder querybuilder with get get can retrieve a single parseobject parseobject from back4app there are many other ways to retrieve data with querybuilder querybuilder you can retrieve many objects at once, use conditions on the objects you wish to retrieve, and more in this guide, you will ding deep into the querybuilder querybuilder class and see all the methods you can use to build your queries you will use a simple database class with some mocked data to perform the queries using flutter on back4app prerequisites android studio https //developer android com/studio or vs code installed (with plugins dart and flutter) an app created on back4app note follow the new parse app tutorial to learn how to create a parse app on back4app an flutter app connected to back4app note follow the install parse sdk on flutter project to create an flutter project connected to back4app a device (or virtual device) running android or ios goal explore the querybuilder querybuilder class different methods the querybuilder class any parse query operation uses the querybuilder querybuilder object type, which will help you retrieve specific data from your database throughout your app to create a new querybuilder querybuilder , you need to pass as a parameter the desired parseobject parseobject subclass, which is the one that will contain your query results it is crucial to know that a querybuilder querybuilder will only resolve after calling a retrieve method query query , so a query can be set up and several modifiers can be chained before actually being called you can read more about the querybuilder class here at the official documentation using the javascript console on back4app inside your back4app application’s dashboard, you will find a very useful api console in which you can run javascript code directly in this guide you will use to store data objects in back4app on your app main dashboard go to core >api console >javascript core >api console >javascript save your data objects to run the queries on this guide you’ll need first to populate your app with some data let’s create a sample class called profile profile , which mocks a social media profile class using famous people names and the following fields string type name name date type birthday birthday number (integer) type friendcount friendcount array (string list) type favoritefoods favoritefoods array (number list) type luckynumbers luckynumbers geopoint type lastloginlocation lastloginlocation here is the parse object parse object classes creation code, so go ahead and run it in your api console 1 // add profile objects and create table 2 // adam sandler 3 let profile = new parse object('profile'); 4 profile set('name', 'adam sandler'); 5 profile set('birthday', new date('09/09/1966')); 6 profile set('friendcount', 2); 7 profile set('favoritefoods', \['lobster', 'bread']); 8 profile set('luckynumbers', \[2, 7]); 9 profile set('lastloginlocation', new parse geopoint(37 38412167489413, 122 01268034622319)); 10 await profile save(); 11 12 // britney spears 13 profile = new parse object('profile'); 14 profile set('name', 'britney spears'); 15 profile set('birthday', new date('12/02/1981')); 16 profile set('friendcount', 52); 17 profile set('favoritefoods', \['cake', 'bread']); 18 profile set('luckynumbers', \[22, 7]); 19 profile set('lastloginlocation', new parse geopoint(37 38412167489413, 122 01268034622319)); 20 await profile save(); 21 22 // carson kressley 23 profile = new parse object('profile'); 24 profile set('name', 'carson kressley'); 25 profile set('birthday', new date('11/11/1969')); 26 profile set('friendcount', 12); 27 profile set('favoritefoods', \['fish', 'cookies']); 28 profile set('luckynumbers', \[8, 2]); 29 profile set('lastloginlocation', new parse geopoint(37 38412167489413, 122 01268034622319)); 30 await profile save(); 31 32 // dan aykroyd 33 // creates related object membership for this user only 34 let membership = new parse object('membership'); 35 membership set('name', 'premium'); 36 membership set('expirationdate', new date('10/10/2030')) 37 await membership save(); 38 39 profile = new parse object('profile'); 40 profile set('name', 'dan aykroyd'); 41 profile set('birthday', new date('07/01/1952')); 42 profile set('friendcount', 66); 43 profile set('favoritefoods', \['jam', 'peanut butter']); 44 profile set('luckynumbers', \[22, 77]); 45 profile set('lastloginlocation', new parse geopoint(37 38412167489413, 122 01268034622319)); 46 profile set('premiummembership', membership); 47 await profile save(); 48 49 // eddie murphy 50 profile = new parse object('profile'); 51 profile set('name', 'eddie murphy'); 52 profile set('birthday', new date('04/03/1961')); 53 profile set('friendcount', 49); 54 profile set('favoritefoods', \['lettuce', 'pepper']); 55 profile set('luckynumbers', \[6, 5]); 56 profile set('lastloginlocation', new parse geopoint( 27 104919974838154, 52 61428045237739)); 57 await profile save(); 58 59 // fergie 60 profile = new parse object('profile'); 61 profile set('name', 'fergie'); 62 profile set('birthday', new date('03/27/1975')); 63 profile set('friendcount', 55); 64 profile set('favoritefoods', \['lobster', 'shrimp']); 65 profile set('luckynumbers', \[13, 7]); 66 profile set('lastloginlocation', new parse geopoint( 27 104919974838154, 52 61428045237739)); 67 await profile save(); 68 69 console log('success!'); after running this code, you should now have a profile profile class in your database with six objects created your new class should look like this let’s now take a look at examples from every querybuilder querybuilder method, along with brief explanations on what they do please note that some methods in this list can take options options as an additional argument, but in most cases, it is only related to masterkey masterkey usage and not relevant to this guide content, so this possibility will be omitted whenever not relevant query retrievers these methods are responsible for running the query and retrieving its results, being always present in your query implementation count //retrieves the count of parseobject results that meet the query criteria 1 querybuilder\<parseobject> querybuilder = querybuilder\<parseobject>(parseobject('profile')); 2 var apiresponse = await queryplayers count(); 3 if (apiresponse success && apiresponse result != null) { 4 int countgames = apiresponse count; 5 } getobject //this quick method is used to retrieve a single parseobject instance when you know its objectid 1 ///to retrieve one object of a class it is not necessary to create a parsequery 2 ///we can query using parseobject 3 final apiresponse = await parseobject('profile') getobject('c6endlnfdq'); 4 5 if (apiresponse success && apiresponse results != null) { 6 for (var o in apiresponse results) { 7 final object = o as parseobject; 8 print('${object objectid} ${object get\<string>('name')}'); 9 } 10 } getall //retrieves a complete list of parseobjects 1 ///to retrieve all objects of a class it is not necessary to create a parsequery 2 ///we can query using parseobject 3 final apiresponse = await parseobject('profile') getall(); 4 5 if (apiresponse success && apiresponse results != null) { 6 for (var o in apiresponse results) { 7 final object = o as parseobject; 8 print('${object objectid} ${object get\<string>('name')}'); 9 } 10 } query //this is the basic method for retrieving your query results, always returning an list of parseobject instances, being empty when none are found 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 // when using query() in a query without other operations, you will 3 // get every object saved in your class 4 final apiresponse = await parsequery query(); 5 6 if (apiresponse success && apiresponse results != null) { 7 for (var o in apiresponse results) { 8 final object = o as parseobject; 9 print('${object objectid} ${object get\<string>('name')}'); 10 } 11 } query conditioners these methods give you the possibility of applying conditional constraints to your query, which are arguably the most important operations in querying remember that these operations can all be chained before the results are retrieved, so many combinations can be achieved to solve your querying needs wheredoesnotmatchkeyinquery //requires that a key’s value does not match a value in an object returned by a different parse query useful for multi object querying 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery wheredoesnotmatchkeyinquery( 3 'friendcount', 4 'friendcount', 5 querybuilder\<parseobject>(parseobject('profile')) 6 wherelessthan('friendcount', 50)); 7 parsequery wheregreaterthan('friendcount', 10); 8 final apiresponse = await parsequery query(); 9 10 if (apiresponse success && apiresponse results != null) { 11 for (var object in apiresponse results as list\<parseobject>) { 12 print('${object objectid} name ${object get\<string>('name')} friendcount ${object get\<int>('friendcount')}'); 13 } 14 } wherearraycontainsall //filters objects in which an array type key value must contain every value provided 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery wherearraycontainsall('luckynumbers', \[2, 7]); 3 final apiresponse = await parsequery query(); 4 5 if (apiresponse success && apiresponse results != null) { 6 for (var object in apiresponse results as list\<parseobject>) { 7 print('${object objectid} ${object get\<string>('name')}'); 8 } 9 } wherecoitainedin //filters objects in which a key value is contained in the provided array of values 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery wherecontainedin('luckynumbers', \[2, 7]); 3 final apiresponse = await parsequery query(); 4 5 if (apiresponse success && apiresponse results != null) { 6 for (var object in apiresponse results as list\<parseobject>) { 7 print('${object objectid} ${object get\<string>('name')}'); 8 } 9 } wherecontains //filters objects in which a string key value contains the provided text value be aware that this condition is case sensitive 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 // this can be slow in large databases 3 parsequery wherecontains('name', 'an'); 4 final apiresponse = await parsequery query(); 5 6 if (apiresponse success && apiresponse results != null) { 7 for (var object in apiresponse results as list\<parseobject>) { 8 print('${object objectid} ${object get\<string>('name')}'); 9 } 10 } wheredoesnotmatchquery //requires that an object contained in the given key does not match another query useful for multi object querying 1 final querybuilder\<parseobject> innerquery = querybuilder\<parseobject>(parseobject('membership')); 2 innerquery wheregreaterthan('expirationdate', datetime now()); 3 4 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 5 6 parsequery wheredoesnotmatchquery('premiummembership', innerquery); 7 8 final apiresponse = await parsequery query(); 9 10 if (apiresponse success && apiresponse results != null) { 11 for (var object in apiresponse results as list\<parseobject>) { 12 print('${object objectid} name ${object get\<string>('name')}'); 13 } 14 } whereendswith //filters objects where specific key’s value ends with value 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 3 parsequery whereendswith('name', 'ie'); 4 final apiresponse = await parsequery query(); 5 6 if (apiresponse success && apiresponse results != null) { 7 for (var o in apiresponse results) { 8 final object = o as parseobject; 9 print('${object objectid} ${object get\<string>('name')}'); 10 } 11 } whereequalto //filters objects in which a specific key’s value is equal to the provided value 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 3 parsequery whereequalto('friendcount', 2); 4 final apiresponse = await parsequery query(); 5 6 if (apiresponse success && apiresponse results != null) { 7 for (var o in apiresponse results) { 8 final object = o as parseobject; 9 print('${object objectid} ${object get\<string>('name')}'); 10 } 11 } wheregreaterthan //filters objects in which a specific key’s value is greater than the provided value 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 3 parsequery wheregreaterthan('birthday', datetime(1980, 08, 19)); 4 final apiresponse = await parsequery query(); 5 6 if (apiresponse success && apiresponse results != null) { 7 for (var object in apiresponse results as list\<parseobject>) { 8 print('${object objectid} ${object get\<string>('name')}'); 9 } 10 } wheregreaterthanorequalsto //filters objects in which a specific key’s value is greater than or equal to the provided value 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 3 parsequery wheregreaterthanorequalsto('friendcount', 49); 4 final apiresponse = await parsequery query(); 5 6 if (apiresponse success && apiresponse results != null) { 7 for (var object in apiresponse results as list\<parseobject>) { 8 print('${object objectid} ${object get\<string>('name')}'); 9 } 10 } wherelessthan //filters objects in which a specific key’s value is lesser than the provided value 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 3 parsequery wherelessthan('birthday', datetime(1980, 08, 19)); 4 final apiresponse = await parsequery query(); 5 6 if (apiresponse success && apiresponse results != null) { 7 for (var object in apiresponse results as list\<parseobject>) { 8 print('${object objectid} ${object get\<string>('name')}'); 9 } 10 } wherelessthanorequalto //filters objects in which a specific key’s value is lesser than or equal to the provided value 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 3 parsequery wherelessthanorequalto('friendcount', 49); 4 final apiresponse = await parsequery query(); 5 6 if (apiresponse success && apiresponse results != null) { 7 for (var object in apiresponse results as list\<parseobject>) { 8 print('${object objectid} ${object get\<string>('name')}'); 9 } 10 } wherematcheskeyinquery //requires that a key’s value matches a value in an object returned by a different parse query useful for multi object querying 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery wherematcheskeyinquery( 3 'friendcount', 4 'friendcount', 5 querybuilder\<parseobject>(parseobject('profile')) 6 wherelessthan('friendcount', 50)); 7 8 final apiresponse = await parsequery query(); 9 10 if (apiresponse success && apiresponse results != null) { 11 for (var object in apiresponse results as list\<parseobject>) { 12 print('${object objectid} name ${object get\<string>('name')} friendcount ${object get\<int>('friendcount')}'); 13 } 14 } wherematchesquery //requires that an object contained in the given key matches another query useful for multi object querying 1 final querybuilder\<parseobject> innerquery = querybuilder\<parseobject>(parseobject('membership')); 2 innerquery wheregreaterthan('expirationdate', datetime now()); 3 4 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 5 6 parsequery wherevalueexists('premiummembership', true); 7 parsequery wherematchesquery('premiummembership', innerquery); 8 9 final apiresponse = await parsequery query(); 10 11 if (apiresponse success && apiresponse results != null) { 12 for (var object in apiresponse results as list\<parseobject>) { 13 print('${object objectid} name ${object get\<string>('name')}'); 14 } 15 } wherenotcontainedin //filters objects in which a key value is not contained in the provided array of values 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery wherenotcontainedin('luckynumbers', \[2, 7]); 3 final apiresponse = await parsequery query(); 4 5 if (apiresponse success && apiresponse results != null) { 6 for (var object in apiresponse results as list\<parseobject>) { 7 print('${object objectid} ${object get\<string>('name')}'); 8 } 9 } wherenotequalto //filters objects in which a specific key’s value is not equal to the provided value 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 3 parsequery wherenotequalto('friendcount', 2); 4 final apiresponse = await parsequery query(); 5 6 if (apiresponse success && apiresponse results != null) { 7 for (var object in apiresponse results as list\<parseobject>) { 8 print('${object objectid} ${object get\<string>('name')}'); 9 } 10 } wherestartswith //filters objects where specific key’s value starts with value 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 3 parsequery wherestartswith('name', 'adam'); 4 final apiresponse = await parsequery query(); 5 6 if (apiresponse success && apiresponse results != null) { 7 for (var o in apiresponse results) { 8 final object = o as parseobject; 9 print('${object objectid} ${object get\<string>('name')}'); 10 } 11 } wherevalueexists //filters objects in which a key value is set or no 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 //true retrieve documents with field set 3 //false retrieve documents without field set 4 parsequery wherevalueexists('premiummembership', true); 5 final apiresponse = await parsequery query(); 6 7 if (apiresponse success && apiresponse results != null) { 8 for (var object in apiresponse results as list\<parseobject>) { 9 print('${object objectid} ${object get\<string>('name')}'); 10 } 11 } query ordering essential in most queries, ordering can be easily achieved in parse and even chained between two or more ordering constraints orderbyascending //sort the results in ascending order, this can be chained without overwriting previous orderings multiple keys can be used to solve ordering ties 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery orderbyascending('name'); 3 final apiresponse = await parsequery query(); 4 5 if (apiresponse success && apiresponse results != null) { 6 for (var object in apiresponse results as list\<parseobject>) { 7 print('${object objectid} ${object get\<string>('name')}'); 8 } 9 } orderbydescending //sort the results in descending order, this can be chained without overwriting previous orderings multiple keys can be used to solve ordering ties 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery orderbydescending('name'); 3 final apiresponse = await parsequery query(); 4 5 if (apiresponse success && apiresponse results != null) { 6 for (var object in apiresponse results as list\<parseobject>) { 7 print('${object objectid} ${object get\<string>('name')}'); 8 } 9 } field selecting these methods affect which field values can be in your query results excludekeys //return all fields in the returned objects except the ones specified 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery excludekeys(\['name']); 3 final apiresponse = await parsequery query(); 4 5 if (apiresponse success && apiresponse results != null) { 6 for (var object in apiresponse results as list\<parseobject>) { 7 //name = null 8 print('${object objectid} name ${object get\<string>('name')} birthday ${object get\<datetime>('birthday')}'); 9 } 10 } includeobject //includes nested parseobjects for the provided key 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery includeobject(\['premiummembership']); 3 final apiresponse = await parsequery query(); 4 5 if (apiresponse success && apiresponse results != null) { 6 for (var object in apiresponse results as list\<parseobject>) { 7 //name = null 8 print('${object objectid} name ${object get\<string>('name')} premiummembership ${object get\<parseobject>('premiummembership') tostring()}'); 9 } 10 } keystoreturn //return only the specified fields in the returned objects 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery keystoreturn(\['name']); 3 final apiresponse = await parsequery query(); 4 5 if (apiresponse success && apiresponse results != null) { 6 for (var object in apiresponse results as list\<parseobject>) { 7 //birthday = null 8 print('${object objectid} name ${object get\<string>('name')} birthday ${object get\<datetime>('birthday')}'); 9 } 10 } geopoint querying these are methods specific to geopoint querying wherenear //return all fields in the returned objects except the ones specified 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery wherenear( 3 'lastloginlocation', 4 parsegeopoint(latitude 37 38412167489413, longitude 122 01268034622319) 5 ); 6 7 final apiresponse = await parsequery query(); 8 9 if (apiresponse success && apiresponse results != null) { 10 for (var object in apiresponse results as list\<parseobject>) { 11 print('${object objectid} name ${object get\<string>('name')} geopoint ${object get\<parsegeopoint>('lastloginlocation') tojson()}'); 12 } 13 } wherewithingeobox 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery wherewithingeobox( 3 'lastloginlocation', 4 parsegeopoint(latitude 37 38412167489413, longitude 122 01268034622319), 5 parsegeopoint(latitude 37 28412167489413, longitude 121 91268034622319) 6 ); 7 8 final apiresponse = await parsequery query(); 9 10 if (apiresponse success && apiresponse results != null) { 11 for (var object in apiresponse results as list\<parseobject>) { 12 print('${object objectid} name ${object get\<string>('name')} geopoint ${object get\<parsegeopoint>('lastloginlocation') tojson()}'); 13 } 14 } wherewithinkilometers 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery wherewithinkilometers( 3 'lastloginlocation', 4 parsegeopoint(latitude 37 38412167489413, longitude 122 01268034622319), 5 100 6 ); 7 8 final apiresponse = await parsequery query(); 9 10 if (apiresponse success && apiresponse results != null) { 11 for (var object in apiresponse results as list\<parseobject>) { 12 print('${object objectid} name ${object get\<string>('name')} geopoint ${object get\<parsegeopoint>('lastloginlocation') tojson()}'); 13 } 14 } wherewithinmiles 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery wherewithinmiles( 3 'lastloginlocation', 4 parsegeopoint(latitude 37 38412167489413, longitude 122 01268034622319), 5 100 6 ); 7 8 final apiresponse = await parsequery query(); 9 10 if (apiresponse success && apiresponse results != null) { 11 for (var object in apiresponse results as list\<parseobject>) { 12 print('${object objectid} name ${object get\<string>('name')} geopoint ${object get\<parsegeopoint>('lastloginlocation') tojson()}'); 13 } 14 } wherewithinradians 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery wherewithinradians( 3 'lastloginlocation', 4 parsegeopoint(latitude 37 38412167489413, longitude 122 01268034622319), 5 100 6 ); 7 8 final apiresponse = await parsequery query(); 9 10 if (apiresponse success && apiresponse results != null) { 11 for (var object in apiresponse results as list\<parseobject>) { 12 print('${object objectid} name ${object get\<string>('name')} geopoint ${object get\<parsegeopoint>('lastloginlocation') tojson()}'); 13 } 14 } pagination these methods are related to pagination utilities, useful for queries that will retrieve a large number of results setamounttoskip 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery setamounttoskip(2); 3 final apiresponse = await parsequery query(); 4 5 if (apiresponse success && apiresponse results != null) { 6 for (var object in apiresponse results as list\<parseobject>) { 7 print('${object objectid} name ${object get\<string>('name')}'); 8 } 9 } setlimit 1 final querybuilder\<parseobject> parsequery = querybuilder\<parseobject>(parseobject('profile')); 2 parsequery setlimit(2); 3 final apiresponse = await parsequery query(); 4 5 if (apiresponse success && apiresponse results != null) { 6 for (var object in apiresponse results as list\<parseobject>) { 7 print('${object objectid} name ${object get\<string>('name')}'); 8 } 9 } compound query these method will create compound queries, which can combine more than one parsequery instance to achieve more complex results or //compose a compound query that is the or of the passed queries 1 final querybuilder\<parseobject> query1 = querybuilder\<parseobject>(parseobject('profile')); 2 query1 wheregreaterthan('friendcount', 10); 3 4 final querybuilder\<parseobject> query2 = querybuilder\<parseobject>(parseobject('profile')); 5 query2 wherelessthan('friendcount', 50); 6 7 querybuilder\<parseobject> mainquery = querybuilder or( 8 parseobject("profile"), 9 \[query1, query2], 10 ); 11 12 final apiresponse = await mainquery query(); 13 14 if (apiresponse success && apiresponse results != null) { 15 for (var object in apiresponse results as list\<parseobject>) { 16 print('${object objectid} name ${object get\<string>('name')}'); 17 } 18 } conclusion at the end of this guide, you learned how to perform every data query method in parse in the next guide, you will learn about complex parse querying in flutter