SFRestAPI (QueryBuilder) Category

If you’re unsure of the correct syntax for a SOQL query or a SOSL search, you can get help from the SFRestAPI (QueryBuilder) category methods. These methods build query strings from basic conditions that you specify, and return the formatted string. You can pass the returned string to SFRestAPI or RestClient request methods for query or search.

SFRestAPI (QueryBuilder) provides two static methods each for SOQL queries and SOSL searches: one takes minimal parameters, while the other accepts a full list of options. Swift versions of these methods are not defined explicitly by Mobile SDK. To code these methods in Swift, use the autocomplete suggestions offered by the Xcode compiler. These suggested method and parameter names are determined by Swift compiler heuristics and can differ from their Objective-C equivalents.

SOSL Methods

SOSL query builder methods are:

Swift (Compiler-generated)

1RestClient.soslSearch(withSearchTerm:objectScope:)
2RestClient.soslSearch(withSearchTerm:fieldScope:objectScope:limit:)

Objective-C

1+ (NSString *) SOSLSearchWithSearchTerm:(NSString *)term 
2                            objectScope:(NSDictionary *)objectScope;
3
4
5+ (NSString *) SOSLSearchWithSearchTerm:(NSString *)term 
6                             fieldScope:(NSString *)fieldScope 
7                            objectScope:(NSDictionary *)objectScope 
8                                  limit:(NSInteger)limit;

Parameters for the SOSL search methods are:

Swift	Objective-C
`withSearchTerm`	`term`

The search string. This string can be any arbitrary value. The method escapes any SOSL reserved characters before processing the search.

Swift	Objective-C
`fieldScope`	`fieldScope`

Indicates which fields to search. It’s either nil or one of the IN search group expressions: “IN ALL FIELDS”, “IN EMAIL FIELDS”, “IN NAME FIELDS”, “IN PHONE FIELDS”, or “IN SIDEBAR FIELDS”. A nil value defaults to “IN NAME FIELDS”. See Salesforce Object Search Language (SOSL).

Swift	Objective-C
`objectScope`	`objectScope`

Specifies the objects to search. Acceptable values are:

nil—No scope restrictions. Searches all searchable objects.
An NSDictionary object pointer—Corresponds to the SOSL RETURNING fieldspec. Each key is an sObject name; each value is a string that contains a field list as well as optional WHERE, ORDER BY, and LIMIT clauses for the key object.
If you use an NSDictionary object, each value must contain at least a field list. For example, to represent the following SOSL statement in a dictionary entry:
1FIND {Widget Smith} 2IN Name Fields 3RETURNING Widget__c (name Where createddate = THIS_FISCAL_QUARTER)
set the key to “Widget__c” and its value to “name WHERE createddate = “THIS_FISCAL_QUARTER”. For example:
1[SFRestAPI 2 SOSLSearchWithSearchTerm:@"all of these will be escaped:~{]" 3 objectScope:[NSDictionary 4 dictionaryWithObject:@"name WHERE 5 createddate="THIS_FISCAL_QUARTER" 6 forKey:@"Widget__c"]];
NSNull—No scope specified.

Swift	Objective-C
`limit`	`limit`

To limit the number of results returned, set this parameter to the maximum number of results you want to receive.

SOQL Methods

SOQL QueryBuilder methods that construct SOQL strings are:

Swift (Compiler-generated)

1RestClient.soqlQuery(withFields:sObject:whereClause:limit:)
2RestClient.soqlQuery(withFields:sObject:whereClause:groupBy:having:orderBy:limit:)

Objective-C

1+ (NSString *) SOQLQueryWithFields:(NSArray *)fields 
2                           sObject:(NSString *)sObject 
3                             where:(NSString *)where 
4                             limit:(NSInteger)limit;
5
6+ (NSString *) SOQLQueryWithFields:(NSArray *)fields 
7                           sObject:(NSString *)sObject 
8                             where:(NSString *)where 
9                           groupBy:(NSArray *)groupBy 
10                            having:(NSString *)having
11                           orderBy:(NSArray *)orderBy 
12                             limit:(NSInteger)limit;

Parameters for the SOQL methods correspond to SOQL query syntax. All parameters except withFields/fields and sObject can be set to nil.

Swift	Objective-C
`withFields`	`fields`

An array of field names to be queried.

Swift	Objective-C
`sObject`	`sObject`

Name of the object to query.

Swift	Objective-C
`whereClause`	`where`

An expression specifying one or more query conditions.

Swift	Objective-C
`groupBy`	`groupBy`

An array of field names to use for grouping the resulting records.

Swift	Objective-C
`having`	`having`

An expression, usually using an aggregate function, for filtering the grouped results. Used only with groupBy.

Swift	Objective-C
`orderBy`	`orderBy`

An array of fields name to use for ordering the resulting records.

Swift	Objective-C
`limit`	`limit`

Maximum number of records you want returned.

See SOQL SELECT Syntax.

SOSL Sanitizing

The QueryBuilder category also provides a class method for cleaning SOSL search terms:

Swift

1RestClient.sanitizeSOSLSearchTerm(_:)

Objective-C

1+ (NSString *) sanitizeSOSLSearchTerm:(NSString *)searchTerm;

This method escapes every SOSL reserved character in the input string, and returns the escaped version. For example:

Swift

1let cleanSOSL = RestClient.sanitizeSOSLSearchTerm(_: "FIND {MyProspect}")

Objective-C

1NSString *soslClean = [SFRestAPI sanitizeSOSLSearchTerm:@"FIND {MyProspect}"];

This call returns “FIND \{MyProspect\}”.

The sanitizeSOSLSearchTerm method is called in the implementation of the SOSL and SOQL QueryBuilder methods, so you don’t need to call it on strings that you’re passing to those methods. However, you can use it if, for instance, you’re building your own queries manually. SOSL reserved characters include:

\ ? & | ! { } [ ] ( ) ^ ~ * : " ' + -

Mobile SDK Development Guide

SFRestAPI (QueryBuilder) Category

SOSL Methods

SOQL Methods

SOSL Sanitizing