BuiltQuery Class Reference

Inherits from NSObject
Declared in BuiltQuery.h

Overview

A class that defines a query on Built.io Backend.

Other Methods

  extensionKey

To set extensionKey for the query. // ‘blt5d4sample2633b’ is a dummy Application API key

@property (nonnull, nonatomic, strong) NSString *extensionKey

Discussion

//Obj-C BuiltApplication builtApplication = [Built applicationWithAPIKey:@“blt5d4sample2633b”]; BuiltClass projectClass = [builtApplication classWithUID:@“project”]; BuiltQuery *projectQuery = [projectClass query]; projectQuery.extensionKey = @“new_extension”;

//Swift var builtApplication:BuiltApplication = Built.applicationWithAPIKey(“blt5d4sample2633b”) var projectClass:BuiltClass = builtApplication.classWithUID(“project”) var projectQuery:BuiltQuery = projectClass.query() projectQuery.extensionKey = “new_extension”;

Declared In

BuiltQuery.h

Manually set headers

– setHeader:forKey:

Set a header for an application

- (void)setHeader:(NSString *)headerValue forKey:(NSString *)headerKey

Parameters

headerValue

The header key

headerKey

The header value

Discussion

 //Obj-C
 BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
 BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
 BuiltQuery *projectQuery = [projectClass query];
 [projectQuery setHeader:@"MyHeaderValue" forKey:@"My-Custom-Header-Key"];


 //Swift
 var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
 var projectClass:BuiltClass = builtApplication.classWithUID("project")
 var projectQuery:BuiltQuery = projectClass.query()
 projectQuery.setHeader("MyHeaderValue", forKey:"My-Custom-Header-Key")

Declared In

BuiltQuery.h

– addHeadersWithDictionary:

Set a header for an application

- (void)addHeadersWithDictionary:(NSDictionary *)headers

Parameters

headers

The headers as dictionary which needs to be added to the application

Discussion

 //Obj-C
 BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
 BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
 BuiltQuery *projectQuery = [projectClass query];
 [projectQuery addHeadersWithDictionary:@{@"My-Custom-Header-Key":@"MyHeaderValue"}];

 //Swift
 var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
 var projectClass:BuiltClass = builtApplication.classWithUID("project")
 var projectQuery:BuiltQuery = projectClass.query()
 projectQuery.addHeadersWithDictionary(["My-Custom-Header-Key":"MyHeaderValue"])

Declared In

BuiltQuery.h

– removeHeaderForKey:

Removes a header from this application.

- (void)removeHeaderForKey:(NSString *)headerKey

Parameters

headerKey

The header key that needs to be removed

Discussion

 //Obj-C
 BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
 BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
 BuiltQuery *projectQuery = [projectClass query];
 [projectQuery removeHeaderForKey:@"My-Custom-Header-Key"];

 //Swift
 var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
 var projectClass:BuiltClass = builtApplication.classWithUID("project")
 var projectQuery:BuiltQuery = projectClass.query()
 projectQuery.removeHeaderForKey("My-Custom-Header-Key")

Declared In

BuiltQuery.h

AND OR over query

– orWithSubqueries:

Accepts an array of queries, and ORs them.

 // 'blt5d4sample2633b' is a dummy Application API key
 // 'project' is a uid of a class on Built.io Backend

 //Obj-C
 BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
 BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
 BuiltQuery *projectQuery = [projectClass query];
 NSArray *subQueryArray = [NSArray arrayWithObjects:@"query",@"sub query", nil];
 [projectQuery orWithSubqueries:subQueryArray];

 //Swift
 var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
 var projectClass:BuiltClass = builtApplication.classWithUID("task")
 var projectQuery:BuiltQuery = projectClass.query()
 var subQueryArray = ["query", "sub query"];
 projectQuery.orWithSubqueries(subQueryArray)
- (void)orWithSubqueries:(NSArray *)queries

Parameters

queries

Array of BuiltQuerys to apply OR on.

Discussion

The query object on which you call this method will be OR of the passed queries.

Declared In

BuiltQuery.h

– andWithSubqueries:

Accepts an array of queries, and ANDs them.

 //Obj-C
 BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
 BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
 BuiltQuery *projectQuery = [projectClass query];
 NSArray *queryArray = [NSArray arrayWithObjects:@"query",@"sub query", nil];
 [projectQuery andWithSubqueries:queryArray];

 //Swift
 var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
 var projectClass:BuiltClass = builtApplication.classWithUID("project")
 var projectQuery:BuiltQuery = projectClass.query()
 var queryArray = ["query", "sub query"];
 projectQuery.andWithSubqueries(queryArray)
- (void)andWithSubqueries:(NSArray *)queries

Parameters

queries

Array of BuiltQuerys to apply AND on.

Discussion

The query object on which you call this method will be AND of the passed queries.

Declared In

BuiltQuery.h

– orderByAscending:

Sort the results in ascending order with the given key.

 //Obj-C
 BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
 BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
 BuiltQuery *projectQuery = [projectClass query];
 [projectQuery orderByAscending:@"name"];

 //Swift
 var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
 var projectClass:BuiltClass = builtApplication.classWithUID("project")
 var projectQuery:BuiltQuery = projectClass.query()
 projectQuery.orderByAscending("name")
- (void)orderByAscending:(NSString *)key

Parameters

key

The key to order by.

Discussion

The asc parameter will sort the returned objects in ascending order of the provided field uid.

Declared In

BuiltQuery.h

– orderByDescending:

Sort the results in descending order with the given key.

 //Obj-C
 BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
 BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
 BuiltQuery *projectQuery = [projectClass query];
 [projectQuery orderByDescending:@"name"];

 //Swift
 var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
 var projectClass:BuiltClass = builtApplication.classWithUID("project")
 var projectQuery:BuiltQuery = projectClass.query()
 projectQuery.orderByDescending("name")
- (void)orderByDescending:(NSString *)key

Parameters

key

The key to order by.

Discussion

The desc parameter will sort the returned objects in descending order of the provided field uid.

Declared In

BuiltQuery.h

Include

– objectsCount

Gives only the count of objects returned in response.

 //Obj-C
 [projectQuery objectsCount];

 //Swift
 projectQuery.objectsCount()
- (void)objectsCount

Discussion

Gives only the count of objects returned in response.

Declared In

BuiltQuery.h

– includeDrafts

Include all unpublished objects of a class.

 //Obj-C
 [projectQuery includeDrafts];

 //Swift
 projectQuery.includeDrafts()
- (void)includeDrafts

Discussion

The “include_unpublished” parameter, when set to “true”, also includes all the objects that are unpublished (published=false).

Declared In

BuiltQuery.h

– includeSchema

Includes schemas of all returned objects alongwith objects themselves.

 //Obj-C
 [projectQuery includeSchema];

 //Swift
 projectQuery.includeSchema()
- (void)includeSchema

Discussion

When set to “true”, this parameter allows you to include the schema portion of your class in the objects response.

Declared In

BuiltQuery.h

– includeOwner

Include the owner’s profile in the objects' data.

 //Obj-C
 [projectQuery includeOwner];

 //Swift
 projectQuery.includeOwner()
- (void)includeOwner

Discussion

When set to “true”, the returned objects will also contain a key “_owner”, which will include the owner’s profile in the objects' data.

Declared In

BuiltQuery.h

– includeCount

Gives object count alongwith objects returned in response.

 //Obj-C
 [projectQuery includeCount];

 //Swift
 projectQuery.includeCount()
- (void)includeCount

Discussion

Gives object count alongwith objects returned in response.

Declared In

BuiltQuery.h

– onlyDrafts

use this method if you want only drafts to appear in the response of a query.

 //Obj-C
 [projectQuery onlyDrafts];

 //Swift
 projectQuery.onlyDrafts()
- (void)onlyDrafts

Declared In

BuiltQuery.h

Pagination

– limitObjects:

A limit on the number of objects to return.

 //Obj-C
 [projectQuery limitObjects:5];

 //Swift
 projectQuery.limitObjects(5)
- (void)limitObjects:(NSNumber *)number

Parameters

number

No of objects to limit.

Discussion

The limit parameter can be used for pagination. “limit” specifies the number of objects to limit to in the response.

Declared In

BuiltQuery.h

– skipObjects:

The number of objects to skip before returning any.

 //Obj-C
 [projectQuery skipObjects:2];

 //Swift
 projectQuery.skipObjects(2)
- (void)skipObjects:(NSNumber *)number

Parameters

number

No of objects to skip from returned objects.

Discussion

The skip parameter can be used for pagination. “skip” specifies the number of objects to skip in the response.

Declared In

BuiltQuery.h

Adding Basic Constraints

– addQueryWithKey:andValue:

  • Include custom query using a key and a value.
- (void)addQueryWithKey:(NSString *)key andValue:(id)value

Parameters

key

name of the query.

value

value for the query.

Discussion

 //Obj-C
 [projectQuery addQueryWithKey:@"key_name" andValue:@"MyValue"];

 //Swift
 projectQuery.addQueryWithKey("key_name", andValue:"MyValue")

Include custom query using a key and a value.

Declared In

BuiltQuery.h

– addQueryParams:

A custom dictionary can be provided to a query that can specify the conditions for retrieving objects.

 //Obj-C
 [projectQuery addQueryParams:@{@"Query_Key":@"Query Value"}];

 //Swift
 projectQuery.addQueryParams(["Query_Key":"Query Value"])
- (void)addQueryParams:(NSDictionary *)queryDict

Parameters

queryDict

A dictionary with all the necessary conditions for retrieving objects.

Discussion

If a complex query needs to be performed and if it is difficult to specify it using the query methods, a dictionary can be provided that specifies all the conditions. The dictionary should be as per the JSON format specified in the REST API docs.

Declared In

BuiltQuery.h

– removeQueryWithKey:

Removes custom query.

- (void)removeQueryWithKey:(NSString *)key

Parameters

key

name of the query.

Discussion

 //Obj-C
 [projectQuery removeQueryWithKey:@"Query_Key"];

 //Swift
 projectQuery.removeQueryWithKey("Query_Key")

Declared In

BuiltQuery.h

– whereKey:equalTo:

Add a constraint to the query that requires a particular key’s object to be equal to the provided object.

 //Obj-C
 // 'bltf4fbsample851db' is a uid of an object we wish to search
 [projectQuery whereKey:@"uid" equalTo:@"bltf4fbsample851db"];

 //Swift
 // 'bltf4fbsample851db' is a uid of an object we wish to search
 projectQuery.whereKey("uid", equalTo:"bltf4fbsample851db")
- (void)whereKey:(NSString *)key equalTo:(id)object

Parameters

key

The key to be constrained.

object

The object that must be equalled.

Declared In

BuiltQuery.h

– whereKey:notEqualTo:

Add a constraint to the query that requires a particular key’s object to be not equal to the provided object.

 //Obj-C
 // 'bltf4fbsample851db' is a uid of an object we wish to search
 [projectQuery whereKey:@"uid" notEqualTo:@"bltf4fbsample851db"];

 //Swift
 // 'bltf4fbsample851db' is a uid of an object we wish to search
 projectQuery.whereKey("uid", notEqualTo:"bltf4fbsample851db")
- (void)whereKey:(NSString *)key notEqualTo:(id)object

Parameters

key

The key to be constrained

object

The object that must not be equalled.

Declared In

BuiltQuery.h

– whereKey:lessThan:

Add a constraint to the query that requires a particular key’s object to be less than the provided object.

 //Obj-C
 BuiltClass *bugsClass = [builtApplication classWithUID:@"bugs"];
 BuiltQuery *bugsQuery = [bugsClass query];
 [bugsQuery whereKey:@"due_date" lessThan:@"2013-06-25T00:00:00+05:30"];

 //Swift
 var bugsClass:BuiltClass = builtApplication.classWithUID("bugs")
 var bugsQuery:BuiltQuery = bugsClass.query()
 bugsQuery.whereKey("due_date", lessThan: "2013-06-25T00:00:00+05:30")
- (void)whereKey:(NSString *)key lessThan:(id)object

Parameters

key

The key to be constrained.

object

The object that provides an upper bound.

Declared In

BuiltQuery.h

– whereKey:greaterThan:

Add a constraint to the query that requires a particular key’s object to be greater than the provided object.

 //Obj-C
 BuiltClass *bugsClass = [builtApplication classWithUID:@"bugs"];
 BuiltQuery *bugsQuery = [bugsClass query];
 [bugsQuery whereKey:@"due_date" greaterThan:@"2013-06-25T00:00:00+05:30"];

 //Swift
 var bugsClass:BuiltClass = builtApplication.classWithUID("bugs")
 var bugsQuery:BuiltQuery = bugsClass.query()
 bugsQuery.whereKey("due_date", greaterThan: "2013-06-25T00:00:00+05:30")
- (void)whereKey:(NSString *)key greaterThan:(id)object

Parameters

key

The key to be constrained.

object

The object that must be equalled.

Declared In

BuiltQuery.h

– whereKey:lessThanOrEqualTo:

Add a constraint to the query that requires a particular key’s object to be less than or equal to the provided object.

 //Obj-C
 BuiltClass *bugsClass = [builtApplication classWithUID:@"bugs"];
 BuiltQuery *bugsQuery = [bugsClass query];
 [bugsQuery whereKey:@"due_date" lessThanOrEqualTo:@"2013-06-25T00:00:00+05:30"];

 //Swift
 var bugsClass:BuiltClass = builtApplication.classWithUID("bugs")
 var bugsQuery:BuiltQuery = bugsClass.query()
 bugsQuery.whereKey("due_date", lessThanOrEqualTo: "2013-06-25T00:00:00+05:30")
- (void)whereKey:(NSString *)key lessThanOrEqualTo:(id)object

Parameters

key

The key to be constrained.

object

The object that must be equalled.

Declared In

BuiltQuery.h

– whereKey:greaterThanOrEqualTo:

Add a constraint to the query that requires a particular key’s object to be greater than or equal to the provided object.

 //Obj-C
 BuiltClass *bugsClass = [builtApplication classWithUID:@"bugs"];
 BuiltQuery *bugsQuery = [bugsClass query];
 [bugsQuery whereKey:@"due_date" greaterThanOrEqualTo:@"2013-06-25T00:00:00+05:30"];

 //Swift
 var bugsClass:BuiltClass = builtApplication.classWithUID("bugs")
 var bugsQuery:BuiltQuery = bugsClass.query()
 bugsQuery.whereKey("due_date", greaterThanOrEqualTo: "2013-06-25T00:00:00+05:30")
- (void)whereKey:(NSString *)key greaterThanOrEqualTo:(id)object

Parameters

key

The key to be constrained.

object

The object that must be equalled.

Declared In

BuiltQuery.h

– whereKey:containedIn:

Add a constraint to the query that requires a particular key’s object to be contained in the provided array.

 //Obj-C
 BuiltClass *bugsClass = [builtApplication classWithUID:@"bugs"];
 BuiltQuery *bugsQuery = [bugsClass query];
 [bugsQuery whereKey:@"severity" containedIn:@[@"Show Stopper", @"Critical"]];


 //Swift
 var bugsClass:BuiltClass = builtApplication.classWithUID("bugs")
 var bugsQuery:BuiltQuery = bugsClass.query()
 bugsQuery.whereKey("severity", containedIn: ["Show Stopper","Critical"])
- (void)whereKey:(NSString *)key containedIn:(NSArray *)array

Parameters

key

The key to be constrained.

array

The possible values for the key’s object.

Declared In

BuiltQuery.h

– whereKey:notContainedIn:

Add a constraint to the query that requires a particular key’s object not be contained in the provided array.

 //Obj-C
 BuiltClass *bugsClass = [builtApplication classWithUID:@"bugs"];
 BuiltQuery *bugsQuery = [bugsClass query];
 [bugsQuery whereKey:@"severity" notContainedIn:@[@"Show Stopper", @"Critical"]];


 //Swift
 var bugsClass:BuiltClass = builtApplication.classWithUID("bugs")
 var bugsQuery:BuiltQuery = bugsClass.query()
 bugsQuery.whereKey("severity", notContainedIn: ["Show Stopper","Critical"])
- (void)whereKey:(NSString *)key notContainedIn:(NSArray *)array

Parameters

key

The key to be constrained.

array

The list of values the key’s object should not be.

Declared In

BuiltQuery.h

– whereKeyExists:

Add a constraint that requires a particular key’s value exists.

 //Obj-C
 BuiltClass *bugsClass = [builtApplication classWithUID:@"bugs"];
 BuiltQuery *bugsQuery = [bugsClass query];
 [bugsQuery whereKeyExists:@"status"];


 //Swift
 var bugsClass:BuiltClass = builtApplication.classWithUID("bugs")
 var bugsQuery:BuiltQuery = bugsClass.query()
 bugsQuery.whereKeyExists("status")
- (void)whereKeyExists:(NSString *)key

Parameters

key

The key of which value to be constrained.

Declared In

BuiltQuery.h

– whereKeyDoesNotExist:

Add a constraint that requires a particular key’s value not exist.

 //Obj-C
 BuiltClass *bugsClass = [builtApplication classWithUID:@"bugs"];
 BuiltQuery *bugsQuery = [bugsClass query];
 [bugsQuery whereKeyDoesNotExist:@"due_date"];


 //Swift
 var bugsClass:BuiltClass = builtApplication.classWithUID("bugs")
 var bugsQuery:BuiltQuery = bugsClass.query()
 bugsQuery.whereKeyDoesNotExist("status")
- (void)whereKeyDoesNotExist:(NSString *)key

Parameters

key

The key of which value to be constrained.

Declared In

BuiltQuery.h

– whereKey:matchesRegex:

Add a regular expression constraint for finding string values that match the provided regular expression. This may be slow for large datasets.

 //Obj-C
 BuiltClass *bugsClass = [builtApplication classWithUID:@"bugs"];
 BuiltQuery *bugsQuery = [bugsClass query];
 [bugsQuery whereKey:@"name" matchesRegex:@"^browser"];

 //Swift
 var bugsClass:BuiltClass = builtApplication.classWithUID("bugs")
 var bugsQuery:BuiltQuery = bugsClass.query()
 bugsQuery.whereKey("name", matchesRegex: "^browser")
- (void)whereKey:(NSString *)key matchesRegex:(NSString *)regex

Parameters

key

The key to be constrained

regex

The regular expression pattern to match.

Discussion

Add a regular expression constraint for finding string values that match the provided regular expression. This may be slow for large datasets.

Declared In

BuiltQuery.h

– whereKey:matchesRegex:modifiers:

Add a regular expression constraint for finding string values that match the provided regular expression. This may be slow for large datasets.

 //Obj-C
 BuiltClass *bugsClass = [builtApplication classWithUID:@"bugs"];
 BuiltQuery *bugsQuery = [bugsClass query];
 [bugsQuery whereKey:@"name" matchesRegex:@"^browser" modifiers:@"i"];

 //Swift
 var bugsClass:BuiltClass = builtApplication.classWithUID("bugs")
 var bugsQuery:BuiltQuery = bugsClass.query()
 bugsQuery.whereKey("name", matchesRegex: "^browser", modifiers: "i")
- (void)whereKey:(NSString *)key matchesRegex:(NSString *)regex modifiers:(NSString *)modifier

Parameters

key

The key to be constrained

regex

The regular expression pattern to match.

modifier

Any of the following supported Regex modifiers

Discussion

Add a regular expression constraint for finding string values that match the provided regular expression. This may be slow for large datasets.

Declared In

BuiltQuery.h

– whereKey:equalToResultOfSelectQuery:forKey:

Add a constraint to the query that requires a particular key’s object to be equal to the provided object.

 //Obj-C
 BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
 BuiltQuery *selectQuery = [projectClass query];
 [selectQuery whereKey:@"description" equalTo:@"test"];

 BuiltClass *bugsClass = [builtApplication classWithUID:@"bugs"];
 BuiltQuery *bugsQuery = [bugsClass query];
 [bugsQuery whereKey:@"project" equalToResultOfSelectQuery:selectQuery forKey:@"name"];

 //Swift
 var projectClass:BuiltClass = builtApplication.classWithUID("project")
 var selectQuery:BuiltQuery = projectClass.query()
 selectQuery.whereKey("description", equalTo: "test")

 var bugsClass:BuiltClass = builtApplication.classWithUID("bugs")
 var bugsQuery:BuiltQuery = bugsClass.query()
 bugsQuery.whereKey("project", equalToResultOfSelectQuery:selectQuery, forKey: "name")
- (void)whereKey:(NSString *)key equalToResultOfSelectQuery:(BuiltQuery *)selectQuery forKey:(NSString *)pickedKey

Parameters

key

The key to be constrained.

selectQuery

The select query to be performed on another class

pickedKey

the key for which the values should be returned after the select query is performed

Declared In

BuiltQuery.h

– whereKey:equalToResultOfDontSelectQuery:forKey:

Add a constraint to the query that requires a particular key’s object to be equal to the provided object.

 //Obj-C
 BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
 BuiltQuery *selectQuery = [projectClass query];
 [selectQuery whereKey:@"description" equalTo:@"test"];

 BuiltClass *bugsClass = [builtApplication classWithUID:@"bugs"];
 BuiltQuery *bugsQuery = [bugsClass query];
 [bugsQuery whereKey:@"project" equalToResultOfDontSelectQuery:selectQuery forKey:@"name"];

 //Swift
 var projectClass:BuiltClass = builtApplication.classWithUID("project")
 var selectQuery:BuiltQuery = projectClass.query()
 selectQuery.whereKey("description", equalTo: "test")

 var bugsClass:BuiltClass = builtApplication.classWithUID("bugs")
 var bugsQuery:BuiltQuery = bugsClass.query()
 bugsQuery.whereKey("project", equalToResultOfDontSelectQuery:selectQuery, forKey: "name")
- (void)whereKey:(NSString *)key equalToResultOfDontSelectQuery:(BuiltQuery *)dontSelectQuery forKey:(NSString *)pickedKey

Parameters

key

The key to be constrained.

dontSelectQuery

The dont_select query to be performed on another class. This is the inverse of the select query. Returns all the objects that do not match the conditions.

pickedKey

the key for which the values should be returned after the dont_select query is performed

Declared In

BuiltQuery.h

– whereTagsContains:

Tags in which to search objects

- (void)whereTagsContains:(NSArray *)tags

Parameters

tags

Array of tags string.

Discussion

 //Obj-C
 BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
 BuiltQuery *selectQuery = [projectClass query];
 [selectQuery whereTagsContains:@[@"ui", @"ux", @"design"]];

 //Swift
 var projectClass:BuiltClass = builtApplication.classWithUID("project")
 var selectQuery:BuiltQuery = projectClass.query()
 selectQuery.whereTagsContains(["ui", "ux", "design"])

Declared In

BuiltQuery.h

Selective fields using includeOnly/includeAll

– includeOnlyFields:

Specifies an array of ‘only’ keys in BASE object that would be included in the response.

 //Obj-C
 BuiltQuery *projectQuery = [projectClass query];
 [projectQuery includeOnlyFields:@["name"]];

 //Swift
 var projectQuery:BuiltQuery = projectClass.query()
 projectQuery.includeOnlyFields(["name"])
- (void)includeOnlyFields:(NSArray *)fieldUIDs

Parameters

fieldUIDs

Array of the ‘only’ keys to be included in response.

Discussion

Specifies an array of keys in BASE object that would be included in the response.

Declared In

BuiltQuery.h

– includeAllFieldsExcept:

Specifies an array of keys in reference class object that would be ‘excluded’ from the response.

 //Obj-C
 BuiltQuery *projectQuery = [projectClass query];
 [projectQuery includeAllFieldsExcept:@["name"]];

 //Swift
 var projectQuery:BuiltQuery = projectClass.query()
 projectQuery.includeAllFieldsExcept(["name"])
- (void)includeAllFieldsExcept:(NSArray *)fieldUIDs

Parameters

fieldUIDs

Array of keys to be excluded from the response.

Discussion

Specifies an array of keys in BASE object that would be ‘excluded’ from the response.

Declared In

BuiltQuery.h

Sub query using inQuery/notInQuery

– inQuery:forKey:

perform query based on referred objects

 //Obj-C
 BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
 BuiltQuery *projectQuery = [projectClass query];
 [projectQuery whereKey:@"name" equalTo:@"Super Project #41!"];

 BuiltClass *bugsClass = [builtApplication classWithUID:@"bugs"];
 BuiltQuery *bugsQuery = [bugsClass query];
 [bugsQuery inQuery:projectQuery forKey:@"project"];

 //Swift
 var projectClass:BuiltClass = builtApplication.classWithUID("project")
 var projectQuery:BuiltQuery = projectClass.query()
 projectQuery.whereKey("name", equalTo: "Super Project #41")

 var bugsClass:BuiltClass = builtApplication.classWithUID("bugs")
 var bugsQuery:BuiltQuery = bugsClass.query()
 bugsQuery.inQuery(projectQuery, forKey:"project")
- (void)inQuery:(BuiltQuery *)query forKey:(NSString *)key

Parameters

query

the query to perform on the referred object

key

the key of the referred object

Discussion

fetch objects for a class by querying the fields in the referred object. Use inQuery if you want to fetch objects that match the conditions specified. Can be used for nested references.(referred object inside referred object and so on)

Declared In

BuiltQuery.h

– notInQuery:forKey:

perform query based on referred objects

 //Obj-C
 BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
 BuiltQuery *projectQuery = [projectClass query];
 [projectQuery whereKey:@"name" equalTo:@"Super Project #41!"];

 BuiltClass *bugsClass = [builtApplication classWithUID:@"bugs"];
 BuiltQuery *bugsQuery = [bugsClass query];
 [bugsQuery notInQuery:projectQuery forKey:@"project"];

 //Swift
 var projectClass:BuiltClass = builtApplication.classWithUID("project")
 var projectQuery:BuiltQuery = projectClass.query()
 projectQuery.whereKey("name", equalTo: "Super Project #41")

 var bugsClass:BuiltClass = builtApplication.classWithUID("bugs")
 var bugsQuery:BuiltQuery = bugsClass.query()
 bugsQuery.notInQuery(projectQuery, forKey:"project")
- (void)notInQuery:(BuiltQuery *)query forKey:(NSString *)key

Parameters

query

the query to perform on the referred object

key

the key of the referred object

Discussion

fetch objects for a class by querying the fields in the referred object. Use notinQuery if you want to fetch objects that do not match the conditions specified (negation of inQuery). Can be used for nested references.(referred object inside referred object and so on)

Declared In

BuiltQuery.h

Reference Query (Query Conditions on Reference fields)

– includeReference:

Include reference objects with given key in response

 //Obj-C
 BuiltClass *commentClass = [builtApplication classWithUID:@"comment"];
 BuiltQuery *commentQuery = [commentClass query];
 [commentQuery includeReference:@[@"for_bug"]];

 //Swift
 var commentClass:BuiltClass = builtApplication.classWithUID("comment")
 var commentQuery:BuiltQuery = commentClass.query()
 commentQuery.includeReference(["for_bug"])
- (void)includeReference:(NSArray *)key

Parameters

key

Array of reference keys to include in response.

Discussion

The include parameter accepts the name of a reference field. By default, no reference field is bought along with the object, only the uids are. To include any reference, this parameter must be used. Nested references can be bought by “.” separating the references. This will work for references which are nested inside groups or references which are nested inside other references.

Declared In

BuiltQuery.h

– includeReference:onlyFields:

Specifies an array of ‘only’ keys in reference class object that would be included in the response.

 //Obj-C
 BuiltClass *commentClass = [builtApplication classWithUID:@"comment"];
 BuiltQuery *commentQuery = [commentClass query];
 [commentQuery includeReference:@[@"for_bug"] onlyFields:@[@"name",@"description"]];

 //Swift
 var commentClass:BuiltClass = builtApplication.classWithUID("comment")
 var commentQuery:BuiltQuery = commentClass.query()
 commentQuery.includeReference(["for_bug"], onlyFields:["name","description"])
- (void)includeReference:(NSString *)key onlyFields:(NSArray *)fieldUIDs

Parameters

key

Key who has reference to some other class object.

fieldUIDs

Array of the ‘only’ reference keys to be included in response.

Discussion

Specifies an array of keys in reference class object that would be included in the response.

Declared In

BuiltQuery.h

– includeReference:excludingFields:

Specifies an array of keys in reference class object that would be ‘excluded’ from the response.

 //Obj-C
 BuiltClass *commentClass = [builtApplication classWithUID:@"comment"];
 BuiltQuery *commentQuery = [commentClass query];
 [commentQuery includeReference:@[@"for_bug"] excludingFields:@[@"description"]];

 //Swift
 var commentClass:BuiltClass = builtApplication.classWithUID("comment")
 var commentQuery:BuiltQuery = commentClass.query()
 commentQuery.includeReference(["for_bug"], excludingFields:["description"])
- (void)includeReference:(NSString *)key excludingFields:(NSArray *)fieldUIDs

Parameters

key

Key who has reference to some other class object.

fieldUIDs

Array of the ‘only’ reference keys to be ‘excluded’ from the response.

Discussion

Specifies an array of keys in reference class object that would be ‘excluded’ from the response.

Declared In

BuiltQuery.h

Geo Queries

– withinLocations:

fetch objects that are within specified locations.

//Obj-C
BuiltClass *personClass = [builtApplication classWithUID:@"person"];
BuiltQuery *personQuery = [personClass query];

// create a location object
BuiltLocation *locationObj1 = [BuiltLocation locationWithLongitude:72.82519 andLatitude:19.47468];
BuiltLocation *locationObj2 = [BuiltLocation locationWithLongitude:72.83172 andLatitude:19.47582];
BuiltLocation *locationObj3 = [BuiltLocation locationWithLongitude:72.82854  andLatitude:19.47161];

[personQuery withinLocations:@[locationObj1, locationObj2, locationObj3]];


//Swift
var personClass:BuiltClass = builtApplication.classWithUID("person")
var personQuery:BuiltQuery = personClass.query()

// create a location object
var locationObj1:BuiltLocation = BuiltLocation(longitude: 72.82519, andLatitude: 19.47468)
var locationObj2:BuiltLocation = BuiltLocation(longitude: 72.83172, andLatitude: 19.47582)
var locationObj3:BuiltLocation = BuiltLocation(longitude: 72.82854, andLatitude: 19.47161)

personQuery.withinLocations([locationObj1, locationObj2, locationObj3])
- (void)withinLocations:(NSArray *)locations

Parameters

locations

an array of locations. Locations can have objects of BuiltLocation or object uids. If object uid is passed, the location of that object will be used. At least three locations need to be passed so that the search area is a polygon.

Declared In

BuiltQuery.h

– nearLocation:withRadius:

fetch objects that are near a specified location within a given radius

 //Obj-C
 BuiltClass *personClass = [builtApplication classWithUID:@"person"];
 BuiltQuery *personQuery = [personClass query];

 // create a location object
 BuiltLocation *locationObj = [BuiltLocation locationWithLongitude:72.8 andLatitude:19.4667];
 [personQuery nearLocation:locationObj withRadius:1000];

 //Swift
 var personClass:BuiltClass = builtApplication.classWithUID("person")
 var personQuery:BuiltQuery = personClass.query()

 // create a location object
 var locationObj:BuiltLocation = BuiltLocation(longitude: 72.8, andLatitude: 19.4667)
 personQuery.nearLocation(locationObj, withRadius: 1000)
- (void)nearLocation:(id)location withRadius:(double)radius

Parameters

location

the location near which you wish to query. Location can be an object of BuiltLocation or an object uid. In the latter case, it will use the object’s location.

radius

the radius within which you wish to query

Declared In

BuiltQuery.h

RawQuery

– setRawQuery:

Set a raw query to execute.

- (void)setRawQuery:(NSString *)rawQueryString

Parameters

rawQueryString

Query string you get from AdvanceQuery from buil.io Backend WebUI

Discussion

 //Obj-C
 BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
 BuiltQuery *projectQuery = [projectClass query];
 [personQuery setRawQuery:[NSString stringWithFormat:@"{\"name\":%@,\"description\":{\"$regex\":%@,\"$options\":\"i\"}}",@"Project showcase #1 !",@"checking"]];

 //Swift
 var projectClass:BuiltClass = builtApplication.classWithUID("project")
 var projectQuery:BuiltQuery = projectClass.query()
 personQuery.setRawQuery("{\"name\":\"" + "Project showcase #1 !" + "\",\"description\":{\"$regex\":\"" + "checking" + "\",\"$options\":\"i\"}}")

Declared In

BuiltQuery.h

Delta methods

– createdAt:

Get delta objects created on and after certain time given by user

 //Obj-C
 NSDate *createDate = @"25-03-2015";// Create new instance of date in this format
 [projectQuery createdAt:createDate];

 //Swift
 var createDate:NSDate = "25-03-2015";// Create new instance of date in this format
 projectQuery.createdAt(createDate)
- (void)createdAt:(NSDate *)date

Parameters

date

Date condition on which delta to be applied.

Discussion

Time in format of DD-MM-YYYY OR DD-MM-YYYY HH:MM:SS.

Declared In

BuiltQuery.h

– updatedAt:

Get delta objects updated on and after certain time given by user

 //Obj-C
 NSDate *updateDate = @"25-03-2015";// Create new instance of date in this format
 [projectQuery updatedAt:updateDate];

 //Swift
 var updateDate:NSDate = "25-03-2015";// Create new instance of date in this format
 projectQuery.updatedAt(updateDate)
- (void)updatedAt:(NSDate *)date

Parameters

date

Date condition on which delta to be applied.

Discussion

Time in format of DD-MM-YYYY OR DD-MM-YYYY HH:MM:SS.

Declared In

BuiltQuery.h

– deletedAt:

Get delta objects deleted on and after certain time given by user

 //Obj-C
 NSDate *deleteDate = @"25-03-2015";// Create new instance of date in this format
 [projectQuery deletedAt:deleteDate];

 //Swift
 var deleteDate:NSDate = "25-03-2015";// Create new instance of date in this format
 projectQuery.deletedAt(deleteDate)
- (void)deletedAt:(NSDate *)date

Parameters

date

Date condition on which delta to be applied.

Discussion

Time in format of DD-MM-YYYY OR DD-MM-YYYY HH:MM:SS.

Declared In

BuiltQuery.h

– allDeltaAt:

Get ALL delta objects updated, deleted, created on and after certain time given by user

 //Obj-C
 NSDate *date = @"25-03-2015";// Create new instance of date in this format
 [projectQuery allDeltaAt:date];

 //Swift
 var date:NSDate = "25-03-2015";// Create new instance of date in this format
 projectQuery.allDeltaAt(date)
- (void)allDeltaAt:(NSDate *)date

Parameters

date

Date condition on which delta to be applied.

Discussion

Time in format of DD-MM-YYYY OR DD-MM-YYYY HH:MM:SS.

Declared In

BuiltQuery.h

Execute Query

– exec:

Execute a Query asynchronously.

 //Obj-C
 [projectQuery exec:^(BuiltResponseType type, BuiltQueryResult *result, NSError *error) {

 }];

 //Swift
 projectQuery.exec { (responseType, result!, error!) -> Void in

 }
- (void)exec:(void ( ^ ) ( BuiltResponseType type , BuiltQueryResult *BUILT_NULLABLE_P result , NSError *BUILT_NULLABLE_P error ))completionBlock

Parameters

completionBlock

CallBack called after network call.

Discussion

Executes a single or a chained query and callbacks the QueryResult with ResponseType.

Declared In

BuiltQuery.h

Export Excel

– exportToExcel:

exports excel file asyncronously from Built.io Backend server to app

- (void)exportToExcel:(void ( ^ ) ( BuiltResponseType responseType , NSString *BUILT_NULLABLE_P filePath , NSError *BUILT_NULLABLE_P error ))completionBlock

Parameters

completionBlock

Completion block with params (BuiltResponseType responseType, NSString * BUILT_NULLABLE_P filePath, NSError * BUILT_NULLABLE_P error)

Discussion

 //Obj-C
  BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
  BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
  BuiltQuery *query = [projectClass query];
  [query exportToExcel:^(BuiltResponseType responseType, NSString * _Nonnull filePath, NSError * _Nonnull error) {
  }];

  //Swift
  var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
  var projectClass:BuiltClass = builtApplication.classWithUID("project")
  let query:BuiltQuery = builtApplication.userQuery()
  query.export { (responseType, filePath, error) in

  }

Declared In

BuiltQuery.h

– exportToExcelAtPath:completion:

exports excel file asyncronously from Built.io Backend server to app

- (void)exportToExcelAtPath:(NSString *)folderPath completion:(void ( ^ ) ( BuiltResponseType responseType , NSString *BUILT_NULLABLE_P filePath , NSError *BUILT_NULLABLE_P error ))completionBlock

Parameters

folderPath

should be valid path with read and write permission where we wish to export to.

completionBlock

Completion block with params (BuiltResponseType responseType, NSString * BUILT_NULLABLE_P filePath, NSError * BUILT_NULLABLE_P error)

Discussion

  //Obj-C
  BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
  BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
  BuiltQuery *query = [projectClass query];
  NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
  NSString *documentsDirectory = [paths objectAtIndex:0];
  NSString *folderPath = [documentsDirectory stringByAppendingPathComponent:@"/UserFolder"];
  [query exportToExcelAtPath:folderPath completion:^(BuiltResponseType responseType, NSString * _Nonnull filePath, NSError * _Nonnull error) {

 }];

  //Swift
  var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
  var projectClass:BuiltClass = builtApplication.classWithUID("project")
  let query:BuiltQuery = projectClass.userQuery()
  let fileManager = FileManager.default
  if let documentsDirectory = fileManager.urls(for: .documentDirectory, in: .userDomainMask).first {
  let folderPath = documentsDirectory.appendingPathComponent("/UserFolder").path
  query.exportToExcel(atPath: folderPath) { (responseType, filePath, error) in

  }

Note: folderPath should have read/write permission.

Declared In

BuiltQuery.h

Cancel execution

– cancelRequests

Advises the operation object that it should stop executing its task.

 //Obj-C
 [projectQuery cancelRequests];

 //Swift
 projectQuery.cancelRequests()
- (void)cancelRequests

Discussion

This method does not force your operation code to stop. Instead, it updates the object’s internal flags to reflect the change in state. If the operation has already finished executing, this method has no effect. Canceling an operation that is currently in an operation queue, but not yet executing, makes it possible to remove the operation from the queue sooner than usual.

Declared In

BuiltQuery.h

LocalStore Methods

– offline

Fetch the objects from offline DB.

- (void)offline

Discussion

 //Assuming 'projectQuery' is a BuiltQuery instance

 //Obj-C
 [projectQuery offline];
 [projectQuery exec:^(BuiltResponseType type, BuiltQueryResult *result, NSError *error) {
    //objects is been fetched from offline db
 }];

 //Swift
 projectQuery.offline();
 projectQuery.exec { (responseType, result!, error!) -> Void in
    //objects is been fetched from offline db
 }

Warning: Not supported in watchOS

Declared In

BuiltQuery+LocalStore.h