Structuring your data

Organise your data to retrieve them quickly and conveniently.

Sphere Kit provides a fast, secure and scalable NoSQL database that is easy to use while having advanced functionalities. Sphere Kit Database offers several advantages over traditional SQL databases:

• Scalability: NoSQL databases provide horizontal scalability, making it easier to handle large data volumes across distributed systems.

• Flexibility: They allow for schema-less data management, allowing you to easily change the structure of your data as your game develops.

These benefits make Sphere Kit Database perfect for rapidly-growing modern online games like yours.

Collections and documents

Documents are the basic units of Sphere Kit Database. They contain the data related to a particular instance of an entity, for example, a weapon in the game.

Collections are like folders in your computer - they contain a number of documents. However, documents can also contain sub-collections.

How should I structure my collections and documents?

The key principle to structuring your collections and documents is to ensure that all relevant players can retrieve the data in as few operations as possible.

For example, if a game had gems at various locations, and players could acquire these gems if they visited these locations, and your game wants to display the list of players who have acquired each gem and the list of gems acquired by each player, how would you structure your data?

❌ A: Use sub-collections in each gem to store a list of players that acquired the gem

This allows us to easily retrieve the list of players who have acquired each gem, but requires many queries to find out which gems each player has acquired.

❌ B: Use sub-collections in each player to store a list of gems that the player has acquired

This allows us to easily retrieve the list of gems acquired by the player with one operation; however, many queries are required to retrieve the list of players who have acquired each gem.

✅ C: Use a separate collection to record the acquisition of a gem by a player

Example of a gemAcquisitions document:

{
    "playerUID": "player1",
    "gemID": "gem1",
    "acquireDate": "2025-06-28"
}

This allows us to fulfil both requirements, since to find the list of players who acquired each gem, we can query by gemID, and to find the list of gems acquired by each player, we can query by playerID.

---

However, in another example, if a game allowed players to store their weapons wish list, and the player can only access their own wish list, and the weapons information are stored in another collection, it may be more appropriate and neat to use a sub-collection as shown:

Example of a wishList document:

{
    "weaponID": "sword",
    "addedDate": "2025-06-28"
}

About lists in documents

Although Sphere Kit Database allows you to create documents up to 9MB in size, having long lists in documents will make retrieving your documents very slow. Therefore, you should consider using sub-collections or collections instead. It is perfectly alright to have documents with no data!

Conclusion

In conclusion, structuring data effectively is crucial for the efficient retrieval, management, and scalability of applications. Most of the time, we should use collections that associate entities for better query performance (e.g. gemAcquisitions in Example C) . However, when the data is specific to the entity, it may be better to use sub-collections (e.g. wishList).