PlayerIO

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

.NET Client Reference

Multiplayer class documentationClass BigDB

Namespace: PlayerIOClient
Language: C# / .NET

The Player.IO 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

 
public void
CreateObject (string table, string key, DatabaseObject obj, Callback<DatabaseObject> successCallback, Callback<PlayerIOError> errorCallback)

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.
public void
CreateObject (string table, string key, DatabaseObject obj, Callback<DatabaseObject> successCallback)

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.
public DatabaseObject
CreateObject (string table, string key, DatabaseObject obj)

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.
public void
DeleteKeys (string table, String[] keys, Callback successCallback, Callback<PlayerIOError> errorCallback)

Delete a set of database objects from a table
public void
DeleteKeys (string table, params String[] keys)

Delete a set of database objects from a table
public void
DeleteKeys (string table, String[] keys, Callback successCallback)

Delete a set of database objects from a table
public void
DeleteRange (string table, string index, object[] indexPath, object start, object stop, Callback successCallback, Callback<PlayerIOError> errorCallback)

Delete a range of database objects from a table using an index
public void
DeleteRange (string table, string index, object[] indexPath, object start, object stop, Callback successCallback)

Delete a range of database objects from a table using an index
public void
DeleteRange (string table, string index, object[] indexPath, object start, object stop)

Delete a range of database objects from a table using an index
public void
Load (string table, string key, Callback<DatabaseObject> successCallback, Callback<PlayerIOError> errorCallback)

Load the database object with the given key from the given table.
public DatabaseObject
Load (string table, string key)

Load the database object with the given key from the given table.
public void
Load (string table, string key, Callback<DatabaseObject> successCallback)

Load the database object with the given key from the given table.
public void
LoadKeys (string table, String[] keys, Callback<DatabaseObject[]> successCallback, Callback<PlayerIOError> errorCallback)

Loads the database objects with the given keys from the given table.
public void
LoadKeys (string table, String[] keys, Callback<DatabaseObject[]> successCallback)

Loads the database objects with the given keys from the given table.
public DatabaseObject[]
LoadKeys (string table, params String[] keys)

Loads the database objects with the given keys from the given table.
public void
LoadKeysOrCreate (string table, String[] keys, Callback<DatabaseObject[]> successCallback, Callback<PlayerIOError> errorCallback)

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.
public void
LoadKeysOrCreate (string table, String[] keys, Callback<DatabaseObject[]> successCallback)

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.
public DatabaseObject[]
LoadKeysOrCreate (string table, params String[] keys)

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.
public void
LoadMyPlayerObject (Callback<DatabaseObject> successCallback)

Loads the database object corresponding to the player from the PlayerObjects table
public DatabaseObject
LoadMyPlayerObject ()

Loads the database object corresponding to the player from the PlayerObjects table
public void
LoadMyPlayerObject (Callback<DatabaseObject> successCallback, Callback<PlayerIOError> errorCallback)

Loads the database object corresponding to the player from the PlayerObjects table
public DatabaseObject
LoadOrCreate (string table, string key)

Loads or creates the database object with the given key from the given table.
public void
LoadOrCreate (string table, string key, Callback<DatabaseObject> successCallback, Callback<PlayerIOError> errorCallback)

Loads or creates the database object with the given key from the given table.
public void
LoadOrCreate (string table, string key, Callback<DatabaseObject> successCallback)

Loads or creates the database object with the given key from the given table.
public DatabaseObject[]
LoadRange (string table, string index, object[] indexPath, object start, object stop, int limit)

Load a range of database objects from a table using the specified index.
public void
LoadRange (string table, string index, object[] indexPath, object start, object stop, int limit, Callback<DatabaseObject[]> successCallback, Callback<PlayerIOError> errorCallback)

Load a range of database objects from a table using the specified index.
public void
LoadRange (string table, string index, object[] indexPath, object start, object stop, int limit, Callback<DatabaseObject[]> successCallback)

Load a range of database objects from a table using the specified index.
public DatabaseObject
LoadSingle (string table, string index, params object[] indexValue)

Load a database object from a table using the specified index.
public void
LoadSingle (string table, string index, object[] indexValue, Callback<DatabaseObject> successCallback)

Load a database object from a table using the specified index.
public void
LoadSingle (string table, string index, object[] indexValue, Callback<DatabaseObject> successCallback, Callback<PlayerIOError> errorCallback)

Load a database object from a table using the specified index.
public void
SaveChanges (bool useOptimisticLocks, bool fullOverwrite, DatabaseObject[] objects, Callback successCallback, Callback<PlayerIOError> errorCallback)

Save changes to one or more database objects in one go.
public void
SaveChanges (bool useOptimisticLocks, bool fullOverwrite, params DatabaseObject[] objects)

Save changes to one or more database objects in one go.
public void
SaveChanges (bool useOptimisticLocks, bool fullOverwrite, DatabaseObject[] objects, Callback successCallback)

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

BigDB.CreateObject

public void
CreateObject (string table, string key, DatabaseObject obj, Callback<DatabaseObject> successCallback, Callback<PlayerIOError> errorCallback)

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

string table
The name of the table to create the database object in
string key
The key to assign to the database object
DatabaseObject obj
The database object to create in the table
Callback<DatabaseObject> successCallback
Callback that will be called with a new instance of DatabaseObject from which .Save() can be called for future modifications when the object has been created.
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the object creation.

BigDB.CreateObject

public void
CreateObject (string table, string key, DatabaseObject obj, Callback<DatabaseObject> successCallback)

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

string table
The name of the table to create the database object in
string key
The key to assign to the database object
DatabaseObject obj
The database object to create in the table
Callback<DatabaseObject> successCallback
Callback to execute when the object has been created with a new instance of DatabaseObject from which .Save() can be called for future modifications.

BigDB.CreateObject

public DatabaseObject
CreateObject (string table, string key, DatabaseObject obj)

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

string table
The name of the table to create the database object in
string key
The key to assign to the database object
DatabaseObject obj
The database object to create in the table

BigDB.DeleteKeys

public void
DeleteKeys (string table, String[] keys, Callback successCallback, Callback<PlayerIOError> errorCallback)

Delete a set of database objects from a table

Arguments

string table
The table to delete the database objects from
String[] keys
The keys of the database objects to delete
Callback successCallback
Callback when the deletion has completed.
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the deletion.

BigDB.DeleteKeys

public void
DeleteKeys (string table, params String[] keys)

Delete a set of database objects from a table

Arguments

string table
The table to delete the database objects from
params String[] keys
The keys of the database objects to delete

BigDB.DeleteKeys

public void
DeleteKeys (string table, String[] keys, Callback successCallback)

Delete a set of database objects from a table

Arguments

string table
The table to delete the database objects from
String[] keys
The keys of the database objects to delete
Callback successCallback
Callback when the deletion has completed.

BigDB.DeleteRange

public void
DeleteRange (string table, string index, object[] indexPath, object start, object stop, Callback successCallback, Callback<PlayerIOError> errorCallback)

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

Arguments

string table
The table to delete the database object from
string index
The name of the index to query for the database objects to delete
object[] 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.
object 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
object 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
Callback successCallback
Callback when the deletion has completed.
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the deletion.

BigDB.DeleteRange

public void
DeleteRange (string table, string index, object[] indexPath, object start, object stop, Callback successCallback)

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

Arguments

string table
The table to delete the database object from
string index
The name of the index to query for the database objects to delete
object[] 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.
object 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
object 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
Callback successCallback
Callback when the deletion has completed.

BigDB.DeleteRange

public void
DeleteRange (string table, string index, object[] indexPath, object start, object stop)

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

Arguments

string table
The table to delete the database object from
string index
The name of the index to query for the database objects to delete
object[] 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.
object 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
object 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

BigDB.Load

public void
Load (string table, string key, Callback<DatabaseObject> successCallback, Callback<PlayerIOError> errorCallback)

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

Arguments

string table
The table to load the database object from
string key
The key of the database object to load
Callback<DatabaseObject> successCallback
Callback with the loaded database object or null if no object exists with the given key
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the load.

BigDB.Load

public DatabaseObject
Load (string table, string key)

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

Arguments

string table
The table to load the database object from
string key
The key of the database object to load

BigDB.Load

public void
Load (string table, string key, Callback<DatabaseObject> successCallback)

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

Arguments

string table
The table to load the database object from
string key
The key of the database object to load
Callback<DatabaseObject> successCallback
Callback with the loaded database object

BigDB.LoadKeys

public void
LoadKeys (string table, String[] keys, Callback<DatabaseObject[]> successCallback, Callback<PlayerIOError> errorCallback)

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

Arguments

string table
The table to load the database objects from
String[] keys
They keys of the database objects to load
Callback<DatabaseObject[]> successCallback
Callback with an array of database objects in the same order as the keys array, with null values for non-existant database objects
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the load.

BigDB.LoadKeys

public void
LoadKeys (string table, String[] keys, Callback<DatabaseObject[]> successCallback)

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

Arguments

string table
The table to load the database objects from
String[] keys
They keys of the database objects to load
Callback<DatabaseObject[]> successCallback
Callback with an array of database objects in the same order as the keys array, with null values for non-existant database objects

BigDB.LoadKeys

public DatabaseObject[]
LoadKeys (string table, params String[] keys)

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

Arguments

string table
The table to load the database objects from
params String[] keys
They keys of the database objects to load

BigDB.LoadKeysOrCreate

public void
LoadKeysOrCreate (string table, String[] keys, Callback<DatabaseObject[]> successCallback, Callback<PlayerIOError> errorCallback)

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

string table
The table to load the database objects from
String[] keys
They keys of the database objects to load
Callback<DatabaseObject[]> successCallback
Callback with an array of database objects in the same order as the keys array
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the load or create.

BigDB.LoadKeysOrCreate

public void
LoadKeysOrCreate (string table, String[] keys, Callback<DatabaseObject[]> successCallback)

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

string table
The table to load the database objects from
String[] keys
They keys of the database objects to load
Callback<DatabaseObject[]> successCallback
Callback with an array of database objects in the same order as the keys array

BigDB.LoadKeysOrCreate

public DatabaseObject[]
LoadKeysOrCreate (string table, params String[] keys)

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

string table
The table to load the database objects from
params String[] keys
They keys of the database objects to load

BigDB.LoadMyPlayerObject

public void
LoadMyPlayerObject (Callback<DatabaseObject> successCallback)

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

Arguments

Callback<DatabaseObject> successCallback
Callback with the loaded player object

BigDB.LoadMyPlayerObject

public DatabaseObject
LoadMyPlayerObject ()

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

BigDB.LoadMyPlayerObject

public void
LoadMyPlayerObject (Callback<DatabaseObject> successCallback, Callback<PlayerIOError> errorCallback)

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

Arguments

Callback<DatabaseObject> successCallback
Callback with the loaded player object
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the load.

BigDB.LoadOrCreate

public DatabaseObject
LoadOrCreate (string table, string key)

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

Arguments

string table
The table from which to load or create the database object
string key
The key of the database object to load or create

BigDB.LoadOrCreate

public void
LoadOrCreate (string table, string key, Callback<DatabaseObject> successCallback, Callback<PlayerIOError> errorCallback)

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

Arguments

string table
The table from which to load or create the database object
string key
The key of the database object to load or create
Callback<DatabaseObject> successCallback
Callback with the database object
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the load or create.

BigDB.LoadOrCreate

public void
LoadOrCreate (string table, string key, Callback<DatabaseObject> successCallback)

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

Arguments

string table
The table from which to load or create the database object
string key
The key of the database object to load or create
Callback<DatabaseObject> successCallback
Callback with the database object

BigDB.LoadRange

public DatabaseObject[]
LoadRange (string table, string index, object[] indexPath, object start, object stop, int limit)

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

Arguments

string table
The table to load the database object from
string index
The name of the index to query for the database object
object[] 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.
object 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
object 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

BigDB.LoadRange

public void
LoadRange (string table, string index, object[] indexPath, object start, object stop, int limit, Callback<DatabaseObject[]> successCallback, Callback<PlayerIOError> errorCallback)

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

Arguments

string table
The table to load the database object from
string index
The name of the index to query for the database object
object[] 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.
object 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
object 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
Callback<DatabaseObject[]> successCallback
Callback with the database objects found.
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the load.

BigDB.LoadRange

public void
LoadRange (string table, string index, object[] indexPath, object start, object stop, int limit, Callback<DatabaseObject[]> successCallback)

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

Arguments

string table
The table to load the database object from
string index
The name of the index to query for the database object
object[] 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.
object 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
object 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
Callback<DatabaseObject[]> successCallback
Callback with the database objects found.

BigDB.LoadSingle

public DatabaseObject
LoadSingle (string table, string index, params object[] indexValue)

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

Arguments

string table
The table to load the database object from
string index
The name of the index to query for the database object
params object[] indexValue
An array of objects of the same types as the index properties, specifying which object to load

BigDB.LoadSingle

public void
LoadSingle (string table, string index, object[] indexValue, Callback<DatabaseObject> successCallback)

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

Arguments

string table
The table to load the database object from
string index
The name of the index to query for the database object
object[] indexValue
An array of objects of the same types as the index properties, specifying which object to load
Callback<DatabaseObject> successCallback
Callback with the database object found, or null if no object was found

BigDB.LoadSingle

public void
LoadSingle (string table, string index, object[] indexValue, Callback<DatabaseObject> successCallback, Callback<PlayerIOError> errorCallback)

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

Arguments

string table
The table to load the database object from
string index
The name of the index to query for the database object
object[] indexValue
An array of objects of the same types as the index properties, specifying which object to load
Callback<DatabaseObject> successCallback
Callback with the database object found, or null if no object was found
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the load.

BigDB.SaveChanges

public void
SaveChanges (bool useOptimisticLocks, bool fullOverwrite, DatabaseObject[] objects, Callback successCallback, Callback<PlayerIOError> errorCallback)

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

Arguments

bool useOptimisticLocks
Should the save only go through, if no other process has modified the object since it was loaded?
bool fullOverwrite
Overwrite the stored object with the data from this object instead of only sending in the changed properties
DatabaseObject[] objects
The objects with changes to save
Callback successCallback
Callback with true if the save succeded and false if it failed (only if using optimistic locking and newer version exists in database)
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the save.

BigDB.SaveChanges

public void
SaveChanges (bool useOptimisticLocks, bool fullOverwrite, params DatabaseObject[] objects)

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

Arguments

bool useOptimisticLocks
Should the save only go through, if no other process has modified the object since it was loaded?
bool fullOverwrite
Overwrite the stored object with the data from this object instead of only sending in the changed properties
params DatabaseObject[] objects
The objects with changes to save

BigDB.SaveChanges

public void
SaveChanges (bool useOptimisticLocks, bool fullOverwrite, DatabaseObject[] objects, Callback successCallback)

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

Arguments

bool useOptimisticLocks
Should the save only go through, if no other process has modified the object since it was loaded?
bool fullOverwrite
Overwrite the stored object with the data from this object instead of only sending in the changed properties
DatabaseObject[] objects
The objects with changes to save
Callback successCallback
Callback with true if the save succeded and false if it failed (only if using optimistic locking and newer version exists in database)