PlayerIO

The fastest way to build online games without breaking a sweat.

Objective-C Client Reference

Class PIOBigDB

Language: Objective-C

The BigDB service.

This class is used to create, load, and delete database objects. All database objects are stored in tables and have a unique key. You can set up tables in your admin panel, and you can also set up indexes there for when you want to load objects by properties or ranges of properties. Please note that all methods are asynchronous and any handling of results have to be done in a callback. If you don't care about the results of a method call, typically for create or delete functions, you can just pass in a null callback.

Here's how to store and update an object:

This is how you load an object:

In case you always want to modify an object, you can use the LoadOrCreate method to ensure you get an object back:

BigDB also supports indexes for retrieving objects by a specific property, a range of properties, or to sort objects by properties. Indexes need to be set up in the admin panel for each table, each index needs a name, and a list of properties, and for each property you also need to specify a sort order.

Imagine that we have objects that look like this:

That we have defined an index called "ByUsername" that looks like this:

{Property:"username", Type:String, Order:Ascending}

And an index called "ByCreated" that looks like this:

{Property:"created", Type:Datetime, Order:Descending}

Then we can do lookups like these:

BigDB also supports compound indexes, that is indexes with more than one property. Given our example object above, we can create an index called "ByLocationAgeCreated" that looks like this:

{Property:"location", Type:String, Order:Ascending}

{Property:"age", Type:Integer, Order:Ascending}

{Property:"created", Type:Datetime, Order:Descending}

With this index, we can then lookup on either location, or location and age, or location and age and created. If we use more than one property in the lookup, we can only specify the range for the last one, the preceding ones have to be fixed and are sent in via the path parameter.

Finally, deleting objects is as easy as calling the DeleteKeys method, or DeleteRange if you want to delete by an index.

Methods

- (void)

createObjectWithKey:inTable:object:successBlock:

Creates a new database object in the given table with the specified key. If no key is specified (null), the object will receive an autogenerated id.

- (void)

createObjectWithKey:inTable:object:successBlock:errorBlock:

Creates a new database object in the given table with the specified key. If no key is specified (null), the object will receive an autogenerated id.

- (void)

deleteKeys:fromTable:successBlock:

Delete a set of database objects from a table.

- (void)

deleteKeys:fromTable:successBlock:errorBlock:

Delete a set of database objects from a table.

- (void)

deleteRangeFromTable:index:indexPath:start:stop:successBlock:

Delete a range of database objects from a table using an index.

- (void)

deleteRangeFromTable:index:indexPath:start:stop:successBlock:errorBlock:

Delete a range of database objects from a table using an index.

- (void)

loadMyPlayerObjectWithSuccessBlock:

Loads the database object corresponding to the player from the PlayerObjects table.

- (void)

loadMyPlayerObjectWithSuccessBlock:errorBlock:

Loads the database object corresponding to the player from the PlayerObjects table.

- (void)

loadObjectsWithKeys:fromTable:successBlock:

Loads the database objects with the given keys from the given table.

- (void)

loadObjectsWithKeys:fromTable:successBlock:errorBlock:

Loads the database objects with the given keys from the given table.

- (void)

loadObjectWithKey:fromTable:successBlock:

Load the database object with the given key from the given table.

- (void)

loadObjectWithKey:fromTable:successBlock:errorBlock:

Load the database object with the given key from the given table.

- (void)

loadOrCreateObjectsWithKeys:fromTable:successBlock:

Loads or creates database objects with the given keys from the given table. New objects are created if there are no existing objects for the given keys.

- (void)

loadOrCreateObjectsWithKeys:fromTable:successBlock:errorBlock:

Loads or creates database objects with the given keys from the given table. New objects are created if there are no existing objects for the given keys.

- (void)

loadOrCreateObjectWithKey:fromTable:successBlock:

Loads or creates the database object with the given key from the given table.

- (void)

loadOrCreateObjectWithKey:fromTable:successBlock:errorBlock:

Loads or creates the database object with the given key from the given table.

- (void)

loadRangeFromTable:index:indexPath:start:stop:limit:successBlock:

Load a range of database objects from a table using the specified index.

- (void)

loadRangeFromTable:index:indexPath:start:stop:limit:successBlock:errorBlock:

Load a range of database objects from a table using the specified index.

- (void)

loadSingleFromTable:index:indexValue:successBlock:

Load a database object from a table using the specified index.

- (void)

loadSingleFromTable:index:indexValue:successBlock:errorBlock:

Load a database object from a table using the specified index.

- (void)

saveChanges:useOptimisticLocks:fullOverwrite:successBlock:

Save changes to one or more database objects in one go.

- (void)

saveChanges:useOptimisticLocks:fullOverwrite:successBlock:errorBlock:

Save changes to one or more database objects in one go.

createObjectWithKey:inTable:object:successBlock:

Creates a new database object in the given table with the specified key. If no key is specified (null), the object will receive an autogenerated id.

Arguments

NSString*	key
	The key to assign to the database object.
NSString*	table
	The name of the table to create the database object in.
PIODatabaseObject*	object
	The database object to create in the table.
void(^)(PIODatabaseObject*created)	successBlock
	A callback block that will be called with the created database object from which -save: can be called for future modifications.

createObjectWithKey:inTable:object:successBlock:errorBlock:

Creates a new database object in the given table with the specified key. If no key is specified (null), the object will receive an autogenerated id.

Arguments

NSString*	key
	The key to assign to the database object.
NSString*	table
	The name of the table to create the database object in.
PIODatabaseObject*	object
	The database object to create in the table.
void(^)(PIODatabaseObject*created)	successBlock
	A callback block that will be called with the created database object from which -save: can be called for future modifications.
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

deleteKeys:fromTable:successBlock:

Delete a set of database objects from a table.

Arguments

NSArray*	keys
	The keys of the database objects to delete.
NSString*	table
	The table to delete the database objects from.
void(^)(void)	successBlock
	A callback block that will be called when the objects have been successfully deleted

deleteKeys:fromTable:successBlock:errorBlock:

Delete a set of database objects from a table.

Arguments

NSArray*	keys
	The keys of the database objects to delete.
NSString*	table
	The table to delete the database objects from.
void(^)(void)	successBlock
	A callback block that will be called when the objects have been successfully deleted
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

deleteRangeFromTable:index:indexPath:start:stop:successBlock:

Delete a range of database objects from a table using an index.

Arguments

NSString*	table
	The table to delete the database object from.
NSString*	index
	The name of the index to query for the database objects to delete.
NSArray*	indexPath
	Where in the index to start the range delete: An array of objects of the same types as the index properties, specifying where in the index to start loading database objects from. For instance, in the index [Mode,Map,Score] you might use new object[]{"expert","skyland"} as the indexPath and use the start and stop arguments to determine the range of scores you wish to delete. IndexPath can be set to null instead of an empty array.
id	start
	Where to start the range delete. For instance, if the index is [Mode,Map,Score] and indexPath is ["expert","skyland"], then start defines the minimum score to delete.
id	stop
	Where to stop the range delete. For instance, if the index is [Mode,Map,Score] and indexPath is ["expert","skyland"], then stop defines the maximum score to delete.
void(^)(void)	successBlock
	A callback block that will be called when the objects have been successfully deleted.

deleteRangeFromTable:index:indexPath:start:stop:successBlock:errorBlock:

Delete a range of database objects from a table using an index.

Arguments

NSString*	table
	The table to delete the database object from.
NSString*	index
	The name of the index to query for the database objects to delete.
NSArray*	indexPath
	Where in the index to start the range delete: An array of objects of the same types as the index properties, specifying where in the index to start loading database objects from. For instance, in the index [Mode,Map,Score] you might use new object[]{"expert","skyland"} as the indexPath and use the start and stop arguments to determine the range of scores you wish to delete. IndexPath can be set to null instead of an empty array.
id	start
	Where to start the range delete. For instance, if the index is [Mode,Map,Score] and indexPath is ["expert","skyland"], then start defines the minimum score to delete.
id	stop
	Where to stop the range delete. For instance, if the index is [Mode,Map,Score] and indexPath is ["expert","skyland"], then stop defines the maximum score to delete.
void(^)(void)	successBlock
	A callback block that will be called when the objects have been successfully deleted.
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

loadMyPlayerObjectWithSuccessBlock:

Loads the database object corresponding to the player from the PlayerObjects table.

Arguments

void(^)(PIODatabaseObject*playerObject)	successBlock
	A callback block that will be called with the database object corresponding to the player in the PlayerObjects table.

loadMyPlayerObjectWithSuccessBlock:errorBlock:

Loads the database object corresponding to the player from the PlayerObjects table.

Arguments

void(^)(PIODatabaseObject*playerObject)	successBlock
	A callback block that will be called with the database object corresponding to the player in the PlayerObjects table.
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

loadObjectsWithKeys:fromTable:successBlock:

Loads the database objects with the given keys from the given table.

Arguments

NSArray*	keys
	The keys of the database objects to load.
NSString*	table
	The table to load the database objects from.
void(^)(NSArray*objects)	successBlock
	A callback block that will be called with the database objects found

loadObjectsWithKeys:fromTable:successBlock:errorBlock:

Loads the database objects with the given keys from the given table.

Arguments

NSArray*	keys
	The keys of the database objects to load.
NSString*	table
	The table to load the database objects from.
void(^)(NSArray*objects)	successBlock
	A callback block that will be called with the database objects found
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

loadObjectWithKey:fromTable:successBlock:

Load the database object with the given key from the given table.

Arguments

NSString*	key
	The key of the database object to load.
NSString*	table
	The table to load the database object from.
void(^)(PIODatabaseObject*object)	successBlock
	A callback block that will be called with the database object found

loadObjectWithKey:fromTable:successBlock:errorBlock:

Load the database object with the given key from the given table.

Arguments

NSString*	key
	The key of the database object to load.
NSString*	table
	The table to load the database object from.
void(^)(PIODatabaseObject*object)	successBlock
	A callback block that will be called with the database object found
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

loadOrCreateObjectsWithKeys:fromTable:successBlock:

Loads or creates database objects with the given keys from the given table. New objects are created if there are no existing objects for the given keys.

Arguments

NSArray*	keys
	The keys of the database objects to load or create.
NSString*	table
	The table from which to load or create the database objects.
void(^)(NSArray*objects)	successBlock
	A callback block that will be called with the database objects found or created in the same order as the keys array

loadOrCreateObjectsWithKeys:fromTable:successBlock:errorBlock:

Loads or creates database objects with the given keys from the given table. New objects are created if there are no existing objects for the given keys.

Arguments

NSArray*	keys
	The keys of the database objects to load or create.
NSString*	table
	The table from which to load or create the database objects.
void(^)(NSArray*objects)	successBlock
	A callback block that will be called with the database objects found or created in the same order as the keys array
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

loadOrCreateObjectWithKey:fromTable:successBlock:

Loads or creates the database object with the given key from the given table.

Arguments

NSString*	key
	The key of the database object to load or create
NSString*	table
	The table from which to load or create the database object
void(^)(PIODatabaseObject*object)	successBlock
	A callback block that will be called with the database object found or created

loadOrCreateObjectWithKey:fromTable:successBlock:errorBlock:

Loads or creates the database object with the given key from the given table.

Arguments

NSString*	key
	The key of the database object to load or create
NSString*	table
	The table from which to load or create the database object
void(^)(PIODatabaseObject*object)	successBlock
	A callback block that will be called with the database object found or created
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

loadRangeFromTable:index:indexPath:start:stop:limit:successBlock:

Load a range of database objects from a table using the specified index.

Arguments

NSString*	table
	The table to load the database objects from.
NSString*	index
	The name of the index to query for the database objects.
NSArray*	indexPath
	Where in the index to start the range search: An array of objects of the same types as the index properties, specifying where in the index to start loading database objects from. For instance, in the index [Mode,Map,Score] you might use new object[]{"expert","skyland"} as the indexPath and use the start and stop arguments to determine the range of scores you wish to return. IndexPath can be set to null if there is only one property in the index.
id	start
	Where to start the range search. For instance, if the index is [Mode,Map,Score] and indexPath is ["expert","skyland"], then start defines the minimum score to include in the results.
id	stop
	Where to stop the range search. For instance, if the index is [Mode,Map,Score] and indexPath is ["expert","skyland"], then stop defines the maximum score to include in the results.
int	limit
	The max amount of objects to return.
void(^)(NSArray*objects)	successBlock
	A callback block that will be called with an array of found database objects

loadRangeFromTable:index:indexPath:start:stop:limit:successBlock:errorBlock:

Load a range of database objects from a table using the specified index.

Arguments

NSString*	table
	The table to load the database objects from.
NSString*	index
	The name of the index to query for the database objects.
NSArray*	indexPath
	Where in the index to start the range search: An array of objects of the same types as the index properties, specifying where in the index to start loading database objects from. For instance, in the index [Mode,Map,Score] you might use new object[]{"expert","skyland"} as the indexPath and use the start and stop arguments to determine the range of scores you wish to return. IndexPath can be set to null if there is only one property in the index.
id	start
	Where to start the range search. For instance, if the index is [Mode,Map,Score] and indexPath is ["expert","skyland"], then start defines the minimum score to include in the results.
id	stop
	Where to stop the range search. For instance, if the index is [Mode,Map,Score] and indexPath is ["expert","skyland"], then stop defines the maximum score to include in the results.
int	limit
	The max amount of objects to return.
void(^)(NSArray*objects)	successBlock
	A callback block that will be called with an array of found database objects
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

loadSingleFromTable:index:indexValue:successBlock:

Load a database object from a table using the specified index.

Arguments

NSString*	table
	The table to load the database object from.
NSString*	index
	The name of the index to query for the database object.
NSArray*	indexValue
	An array of objects of the same types as the index properties, specifying which object to load.
void(^)(PIODatabaseObject*object)	successBlock
	A callback block that will be called with the found database object (or nil of no object was found).

loadSingleFromTable:index:indexValue:successBlock:errorBlock:

Load a database object from a table using the specified index.

Arguments

NSString*	table
	The table to load the database object from.
NSString*	index
	The name of the index to query for the database object.
NSArray*	indexValue
	An array of objects of the same types as the index properties, specifying which object to load.
void(^)(PIODatabaseObject*object)	successBlock
	A callback block that will be called with the found database object (or nil of no object was found).
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

saveChanges:useOptimisticLocks:fullOverwrite:successBlock:

Save changes to one or more database objects in one go.

Arguments

NSArray*	objects
	The objects with changes to save.
BOOL	useOptimisticLocks
	Should the save only go through, if no other process has modified the object since it was loaded?
BOOL	fullOverwrite
	Will completely overwrite the database object in BigDB with the properties in this instance, instead of just sending the changed properties to the server.
void(^)(void)	successBlock
	A callback block that will be called when the changes have been successfully saved

saveChanges:useOptimisticLocks:fullOverwrite:successBlock:errorBlock:

Save changes to one or more database objects in one go.

Arguments

NSArray*	objects
	The objects with changes to save.
BOOL	useOptimisticLocks
	Should the save only go through, if no other process has modified the object since it was loaded?
BOOL	fullOverwrite
	Will completely overwrite the database object in BigDB with the properties in this instance, instead of just sending the changed properties to the server.
void(^)(void)	successBlock
	A callback block that will be called when the changes have been successfully saved
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.