How to Store Player Profiles and Leaderboards

Store player profiles and leaderboards in the platform's NoSQL database using a simple key structure. Each player gets a profile record with their name, stats, and achievements. Leaderboards are built by querying all player scores under a game or level ID. Every read and write costs 1-2 credits, and the data loads in milliseconds.

Before You Start

Install the NoSQL app from your admin panel. If you have not used the key-value database before, read How to Set Up a Key-Value Database for Your App for the basics of partition keys and sort keys.

Step-by-Step: Player Profiles

Step 1: Choose your key structure for profiles.
Use the player's unique ID as the partition key and "profile" as the sort key. This lets you store one profile record per player and retrieve it instantly with a single lookup. Example: partition key "player-abc123", sort key "profile".

Step 2: Define your profile data.
Store the player's display name, avatar, level, experience points, join date, and any other fields your game needs. The data is a JSON object, so you can include nested structures like an achievements array or a stats object with individual counters. There is no fixed schema, so different players can have different fields.

Step 3: Create the profile on registration.
When a new player registers or first launches the game, write their initial profile record. Set default values for level (1), experience (0), and any starter data. This single API call creates the record instantly.

Step 4: Update profiles as players progress.
When a player earns experience, levels up, or unlocks an achievement, update just the changed fields. You do not need to rewrite the entire profile. The API supports updating individual fields, so an "add 50 XP" operation only writes the experience field.

Step-by-Step: Leaderboards

Step 1: Choose your leaderboard key structure.
Use the game or level identifier as the partition key and the player ID as the sort key. This groups all scores for one game together. Example: partition key "leaderboard-level5", sort key "player-abc123". Each record holds the player's best score, display name, and the timestamp when the score was set.

Step 2: Submit scores after gameplay.
When a player finishes a level or match, compare their new score against their stored best. If it is higher, update the record. If no record exists yet, create one. This keeps only each player's best score in the leaderboard.

Step 3: Load the leaderboard.
Query all records under the leaderboard partition key to get every player's best score for that game or level. The API returns all matching records in one call. Sort the results by score in your game client to display rankings.

Step 4: Display rankings in your game.
Parse the returned JSON array and display it in your leaderboard UI. Include the player name, score, rank number, and optionally the date. Highlight the current player's position so they can see where they stand.

Leaderboard Design Patterns

Global Leaderboards

Use a single partition key like "leaderboard-global" to track overall best scores across the entire game. Every player who submits a score gets a record. Query this key to show the all-time best players.

Per-Level Leaderboards

Use partition keys like "leaderboard-level1", "leaderboard-level2", etc. Each level has its own independent leaderboard. Players can compete for the top spot on each level separately.

Time-Limited Leaderboards

For weekly or monthly competitions, include the time period in the partition key: "leaderboard-weekly-2026-12" or "leaderboard-march2026". When the period ends, the leaderboard freezes and a new one starts with the next time key. Old leaderboards remain queryable for historical viewing.

Friend Leaderboards

Store a friends list in each player's profile. When displaying a friend leaderboard, fetch scores for just those player IDs from the global leaderboard. Filter client-side to show only friends.

Scaling: The NoSQL database handles leaderboards with thousands of players efficiently. For leaderboards with tens of thousands of entries, consider caching the sorted results or showing only the top 100 plus the current player's position to keep response sizes manageable.

Combining Profiles and Leaderboards

Since profiles and leaderboards use different partition keys, they coexist naturally. When displaying a leaderboard entry, the player name is stored directly in the leaderboard record (denormalized) so you do not need a second lookup to the profile. When the player changes their display name, update both the profile and their leaderboard entries.

For a complete game backend setup including inventory, save data, and session management, see How to Build a Game Backend With NoSQL.

Add player profiles and leaderboards to your game in minutes. Simple API, no servers needed.

Get Started Free

View the NoSQL App