Registering a Soup through Code

Before you try to access a soup, you’re required to register it.

To register a soup, you provide a soup name and a list of one or more index specifications. If, for some reason, you can’t use a configuration file to define your soup structures, here’s how you can do the same thing through code. Each of the following code examples builds an index spec array consisting of name, ID, and owner (or parent) ID fields.

You index a soup on one or more fields found in its entries. SmartStore makes sure that these indexes reflect any insert, update, and delete operations. Always specify at least one index field when registering a soup. For example, if you are using the soup as a simple key-value store, use a single index specification with a string type.

As of Mobile SDK 6.0, you can register soups in native apps through a JSON configuration file. Where possible, we recommend this strategy over coding. See Registering Soups with Configuration Files.
If your soup contains unusually large elements (> 1 MB), consider registering it to use external storage. See Using External Storage for Large Soup Elements.

Note

Hybrid Apps

The JavaScript function for registering a soup requires callback functions for success and error conditions.

1var sfSmartstore = function () {
2  return cordova.require("com.salesforce.plugin.smartstore");
3};
4sfSmartstore().registerSoup(soupName, indexSpecs, successCallback, errorCallback);

If the soup does not exist, this function creates it. If the soup exists, registering lets you access it.

indexSpecs

Use the indexSpecs array to create the soup with predefined indexing. Entries in the indexSpecs array specify how to index the soup. Each entry consists of a path:type pair. path is the name of an index field; type is either “string”, “integer”, “floating”, “full_text”, or “json1”.

1var indexSpecs = [
2  { path: "Name", type: "string" },
3  { path: "Id", type: "string" },
4];

Index paths are case-sensitive and can include compound paths, such as Owner.Name.
Index entries that are missing any fields described in an indexSpecs array are not tracked in that index.
The type of the index applies only to the index. When you query an indexed field (for example, “select {soup:path} from {soup}”), the query returns data of the type that you specified in the index specification.
Index columns can contain null fields.
Beginning in Mobile SDK 4.1, you can specify index paths that point to internal (non-leaf) nodes. You can use these paths with like and match (full-text) queries. Use the string type when you define internal node paths.

For example, consider this element in a soup named “spies”:
1{ 2 "first_name":"James", 3 "last_name":"Bond", 4 "address":{ 5 "street_number":10, 6 "street_name":"downing", 7 "city":"london" 8 } 9}
In this case, “address” is an internal node because it has children. Through the index on the path “address”, you can use a like or match query to find the “city” value—“london”—in “address”. For example:
1SELECT {spies:first_name, spies:last_name} FROM spies WHERE {spies:address} LIKE 'london'
Beginning in Mobile SDK 4.1, you can include arrays in index paths, with some restrictions. See Using Arrays in Index Paths.

Still running into issues? See “Creating Index Specs” in the Mobile SDK Development Guide for advanced rules and restrictions.

Note

successCallback

The success callback function you supply takes one argument: the soup name. For example:

1function(soupName) { alert("Soup " + soupName + " was successfully created"); }

When the soup is successfully created, registerSoup() calls the success callback function to indicate that the soup is ready. Wait to complete the transaction and receive the callback before you begin any activity. If you register a soup under the passed name, the success callback function returns the soup.

errorCallback

The error callback function takes one argument: the error description string.

1function(err) { alert ("registerSoup failed with error: " + err); }

During soup creation, errors can happen for various reasons, including:

An invalid or bad soup name
No index (at least one index must be specified)
Other unexpected errors, such as a database error

To find out if a soup exists, use:

1navigator.smartstore.soupExists(soupName, successCallback, errorCallback);

Android Native Apps

For Android, you define index specs in an array of type com.salesforce.androidsdk.smartstore.store.IndexSpec. Each index spec comprises a path—the name of an index field—and a type. Index spec types are defined in the SmartStore.Type enum and include the following values:

string
integer
floating
full_text
json1

1public class OfflineStorage extends SalesforceActivity {
2    private  smartStore;
3    final IndexSpec[] ACCOUNTS_INDEX_SPEC = {
4        new IndexSpec("Name", .Type.string),
5        new IndexSpec("Id", .Type.string),
6        new IndexSpec("OwnerId", .Type.string)
7    };
8
9    public OfflineStorage() {
10        smartStore = SmartStoreSDKManager.getInstance().getSmartStore();
11        smartStore.registerSoup("Account", ACCOUNTS_INDEX_SPEC);
12    }
13
14    // ...
15}

iOS Native Apps

For iOS, you define index specs in an array of SFSoupIndex objects. Each index spec comprises a path—the name of an index field—and a type. Index spec types are defined as constants in the SFSoupIndex class and include the following values:

kSoupIndexTypeString
kSoupIndexTypeInteger
kSoupIndexTypeFloating
kSoupIndexTypeFullText
kSoupIndexTypeJSON1

Swift

In Mobile SDK 8.0 and later, a SmartStore native Swift extension provides the following soup registration method:

1func createAccountsSoup(name: String) {
2    guard let user = UserAccountManager.shared.currentUserAccount,
3        let store = SmartStore.shared(withName: SmartStore.defaultStoreName,
4            forUserAccount: user),
5        let  index1 = SoupIndex(path: "Name", indexType: "String",
6            columnName: "Name"),
7        let  index2 = SoupIndex(path: "Id", indexType: "String",
8            columnName: "Id")
9    else {
10        return
11    }
12
13    do {
14        try store.registerSoup(withName: name, withIndices:[index1,index2])
15    } catch (let error) {
16        SalesforceLogger.d(RootViewController.self,
17            message:"Couldn’t create soup \(name).
18                Error: \(error.localizedDescription)")
19        return
20    }
21}

Objective-C

1NSString* const kAccountSoupName = @"Account";
2
3...
4- (SFSmartStore *)store
5{
6    return [SFSmartStore sharedStoreWithName:kDefaultSmartStoreName];
7}
8
9...
10- (void)createAccountsSoup {
11    if (![self.store soupExists:kAccountSoupName]) {
12        NSArray *keys = @[@"path", @"type"];
13        NSArray *nameValues = @[@"Name", kSoupIndexTypeString];
14        NSDictionary *nameDictionary = [NSDictionary
15            dictionaryWithObjects:nameValues forKeys:keys];
16
17        NSArray *idValues = @[@"Id", kSoupIndexTypeString];
18        NSDictionary *idDictionary =
19            [NSDictionary dictionaryWithObjects:idValues forKeys:keys];
20
21        NSArray *ownerIdValues = @[@"OwnerId", kSoupIndexTypeString];
22        NSDictionary *ownerIdDictionary =
23            [NSDictionary dictionaryWithObjects:ownerIdValues
24                forKeys:keys];
25
26        NSArray *accountIndexSpecs =
27            [SFSoupIndex asArraySoupIndexes:@[nameDictionary,
28                idDictionary, ownerIdDictionary]];
29
30        NSError* error = nil;
31        [self.store registerSoup:kAccountSoupName
32                  withIndexSpecs:accountIndexSpecs
33                           error:&error];
34        if (error) {
35            NSLog(@"Cannot create  soup '%@'\nError: '%@'",
36                kAccountSoupName, error.localizedDescription);
37        }
38    }
39}

See Also

We've Moved

Welcome to the new home of the Mobile SDK Developer Guide! For now, the Japanese guide can be found in PDF form.