Adding and managing data

Create, update and delete documents in your database.

Accessing your database

To access your database, you must first initialise an instance of Database. If you are accessing the default database linked to your project, you do not need to specify the database ID parameter.

var myDatabase = new Database(); // Initialising this project's database
var otherDatabase = new Database("databaseId") // Initialising another project's database

Referencing a document

To get a reference to a document in the database, simply define the path like how you would navigate to the document in the Dashboard.

Path parts and field names must not contain forward slashes ( / ), and cannot start with underscores ( _ ) or dollar signs ($). Additionally, path parts cannot contain spaces. The total length of the document path cannot exceed 230 characters.

When passing data as collection IDs or document IDs, it is a good practice to sanitize inputs and prevent invalid IDs or IDs with forward slashes (the SDK will throw an error).

var playerRef = database.Collection("players").Document("player123");

With the reference to the document, you can now perform operations on the document.

Creating or replacing a document

To create or replace the document, use the Set method on the document reference. Provide a dictionary with field name as keys and field value as values.

await playerRef.Set(new Dictionary<string, object>
{
    { "name", "Player123" },
    { "joinedAt", "2025-06-28" }
});

Updating a document

To update the contents of the document or create the document if it does not exist, Sphere Kit Database provides many useful utilities, including modifying the document based on the existing data in the document. Use the Update method on the document reference, and provide a dictionary with field path as keys and update operation as values.

The field path is the path to the field or nested field in a document. For example, in a document with data:

{
    "name": "Player123",
    "hobbies": {
        "cycling": {
            "sinceDate": "2025-06-28"
        }
    },
    "virtualHouseLocations": [12345, 45678]
}

To access the value "Player123", the field path would be "name" .

To access the value "2025-06-28", the field path would be "hobbies.cycling.sinceDate".

To access the value 45678, the field path would be "virtualHouseLocations.0" .

Defining your update operations

Operation name	Purpose	Example
Set	Sets the field to the specified value, or optionally set the field only if the document does not exist by specifying the onInsert parameter as true.	DocumentDataOperation.Set("Gold")
Inc	Increases the field by the specified value (or sets the field to the specified value if the field is not set).	DocumentDataOperation.Inc(10)
Dec	Decreases the field by the specified value (or sets the field to the specified value if the field is not set).	DocumentDataOperation.Dec(10)
Min	Sets the field to the specified value if it is lesser than the current value (or sets the field to the specified value if the field is not set).	DocumentDataOperation.Min(20)
Max	Sets the field to the specified value if it is greater than the current value (or sets the field to the specified value if the field is not set).	DocumentDataOperation.Max(5)
Mul	Multiplies the field by the specified value (or sets the field to 0 if the field is not set).	DocumentDataOperation.Mul(10)
Div	Divides the field by the specified value (or sets the field to 0 if the field is not set).	DocumentDataOperation.Div(3)
Rename	Renames the field, or moves the field to a new location (no effect if the field is not set).	DocumentDataOperation.Rename("newdict.subfield")
Unset	Deletes the field.	DocumentDataOperation.Unset()
AddIfNotExists	Adds an element to the array field if the element does not already exist.	DocumentDataOperation.AddIfNotExists("sharpshooter")
AddManyIfNotExists	Adds one or more elements to the array field if they do not already exist.	DocumentDataOperation.AddManyIfNotExists(new object[] { "sharpshooter", "veteran" })
RemoveFirst	Removes the first element in the array field.	DocumentDataOperation.RemoveFirst()
RemoveLast	Removes the last element in the array field.	DocumentDataOperation.RemoveLast()
Add	Adds an element to the array field.	DocumentDataOperation.Add("sharpshooter")
AddMany	Adds one or more elements to the array field.	DocumentDataOperation.AddMany( new object[] { 12345, 45678 }, position: 1, slice: ArraySlice.First(3) )

Example

await playerRef.Update(new Dictionary<string, DocumentDataOperation>
{
    { "name", DocumentDataOperation.Set("Player123_edited") },
    { "skillLevel", DocumentDataOperation.Inc(10) },
    { "matchesPlayed", DocumentDataOperation.Inc(1) }
});

Deleting a document

To delete the document, use the Delete method on the document reference.

await playerRef.Delete();

Referencing a collection

Path parts and field names must not contain forward slashes ( / ), and cannot start with underscores ( _ ) or dollar signs ($). Additionally, path parts cannot contain spaces. The total length of the document path cannot exceed 230 characters.

When passing data as collection IDs or document IDs, it is a good practice to sanitize inputs and prevent invalid IDs or IDs with forward slashes (the SDK will throw an error).

var itemsRef = database.Collection("players").Document("player1").Collection("items");

With the reference to the collection, you can now perform operations on the collection.

Creating or replacing multiple documents

You can create or replace multiple documents in a collection using the SetDocuments method on the collection reference. Provide a dictionary with key as the document name and value as the document data (which is also a dictionary).

await itemsRef.SetDocuments(new Dictionary<string, Dictionary<string, object>>
{
    {
        "item1", new Dictionary<string, object>
        {
            { "id", "sword" },
            { "acquiredDate", "2025-06-27" }
        }
    },
    {
        "item2", new Dictionary<string, object>
        {
            { "id", "shield" },
            { "acquiredDate", "2025-06-27" }
        }
    }
});

This creates or replaces two documents in the items collection, item1 and item2.

Updating multiple documents

To update multiple documents in a collection, you can use the UpdateDocuments method on the collection reference. Optionally, you can provide a filter to determine which documents to update. See the docs on writing a query to write your filter.

To understand how updates can be written and performed based on existing document data, see the docs on updating a single document.

var playerRef = database.Collection("players");
await playerRef.UpdateDocuments(
    update: new Dictionary<string, DocumentDataOperation>
    {
        { "skillLevel", DocumentDataOperation.Inc(10) },
        { "matchesPlayed", DocumentDataOperation.Inc(1) }
    },
    filter: new[]
    {
        DocumentQueryOperation.In("playerId", new[] { "player123", "player456" })
    }
);

This finds all documents with playerId value of "player123" or "player456", and increases the skillLevel by 10 and matchesPlayed by 1.

Deleting multiple documents

To delete multiple documents in the collection, you can use the DeleteDocuments method on the collection reference. Optionally, you can also provide a filter to determine which documents to delete. See the docs on writing a query to write your filter.

await itemsRef.DeleteDocuments(new []
{
    DocumentQueryOperation.Equal("type", "weapon"),
    DocumentQueryOperation.LessThan("level", 5)
});

This deletes all documents with type value of "weapon" and level less than 5.