Not translated yet — showing English.
Writing Records
To change a record, edit its value and save it: PlayServ sends only the fields you changed. You create records with CreateAsync, save them with SaveAsync, and delete them one by one or by a filter. The examples use the Sky Arena schema; the C# types are set up in Reading Records.
using Playserv.Data;
using Playserv.Wrapper;
using UnityEngine;
var pilots = PlayServData.Records<Pilots>();
var pilot = await pilots.LoadByNaturalKeyAsync(PlayServNaturalKey<Pilots>.For(p => p.Callsign, "Falcon"));
pilot.Value.Level++;
await pilot.SaveAsync();
The game can write to an entity only if Client Write is on for it, see Access Control.
Create a record
Fill in the value
Create the C# object and set every field you need. All its fields are sent, including the ones you didn't set: a number you leave alone is sent as 0 and a string as null. The schema's default only applies to a field your class doesn't have, so set values such as Level = 1 yourself.
Create it
CreateAsync returns the new record, with the ID PlayServ gave it.
var pilot = await pilots.CreateAsync(new Pilots { Callsign = "Falcon", Level = 1 });
Debug.Log(pilot.Id);On an entity owned by players, the new record belongs to the signed-in player, and pilot.Owner is their ID. The game must be connected with a player for this, see Player-owned entities.
To set a relation, use the target's ID: Ship = new PlayServRecordRef<Ships>(shipId).
Save changes
SaveAsync() sends the top-level fields you changed since the record was loaded or last saved. A changed part or list is sent whole. Fields you didn't touch are left as they are on the platform, even if someone else changed them meanwhile.
Each save checks that the record hasn't changed since you loaded it. If another player or a function saved it first, SaveAsync throws PlayServRecordConflictException with Kind = StaleVersion, and nothing is written.
A conflict means someone saved first
Call ReloadAsync() to get the current record, apply your change again, and save. ReloadAsync() discards your unsaved edits: the platform's version wins.
Create a record only once
| Call | What it does |
|---|---|
LoadOrCreateAsync(key, () => new Pilots { … }) | Loads the record with that natural key, or creates it from your factory if there isn't one. WasCreated tells you which. If another client creates the same record at that moment, the call can throw PlayServRecordConflictException; call it again to load the record. |
UpsertByNaturalKeyAsync(key, value, mode) | Creates the record, or updates it if it exists. With PlayServUpsertMode.Seed an existing record is left as it is; with Managed the fields you pass are updated. |
var key = PlayServNaturalKey<Pilots>.For(p => p.Callsign, "Falcon");
var result = await pilots.LoadOrCreateAsync(key, () => new Pilots { Callsign = "Falcon" });
if (result.WasCreated) Debug.Log("Welcome, new pilot");
The key's field must be marked Unique in the schema.
Delete
| Call | What it does |
|---|---|
record.DeleteAsync() | Deletes a loaded record, if it hasn't changed since you loaded it. |
DeleteByIdAsync(id) | Deletes a record by ID, without loading it. |
DeleteMatchingAsync(query, confirmation) | Deletes every record that matches the query, in one call: all of them or none. |
DeleteMatchingAsync takes only Where and Search. Pass PlayServDeleteAllConfirmation.MatchingRecords with a filter, or AllRecords to empty the entity. Up to 100,000 records can be deleted at once when every filter is a simple comparison on a top-level number, boolean, text or enum field; with Search or other filters, up to 200. A filter the platform can't apply this way is refused. If the match is larger than the limit, or a matching record is still referenced by a record outside the match, nothing is deleted and you get an error.
await PlayServData.Records<MatchResults>().DeleteMatchingAsync(
new PlayServRecordQuery<MatchResults>().Where(m => m.Score == 0),
PlayServDeleteAllConfirmation.MatchingRecords);
Write many records
| Call | Rows | All or none? |
|---|---|---|
BulkCreateAsync(values) | 1–200 | Yes: if one row fails, none is created. |
BulkUpsertAsync(rows, mode) | 1–200 | Yes. Each row is a PlayServBulkUpsertRow<T> with its natural key. |
BulkSaveAsync(records) · BulkDeleteAsync(records) | Any | No: each record is saved or deleted on its own. |
DeleteAllAsync(query, confirmation) | Up to 10,000 by default | No. Prefer DeleteMatchingAsync. |
The non-atomic calls return a result per record: check IsSuccess, FailedCount and Items.
No increments and no transactions
A save sends the value the client has, so two players adding to the same counter at once can lose an update. There are no multi-record transactions either, apart from the bulk calls above. Keep changes that must be exact, such as match results or currency, in a Cloud Function.
Retry safely
CreateAsync, BulkCreateAsync and the upserts accept an idempotency key: a string you make up for this write, up to 128 characters. If you retry the call with the same key, for example after a lost connection, the record isn't created twice. Without a key, the SDK makes a new one for every call, so a retry you make yourself creates a second record. Use the same key only with the same value.
await pilots.CreateAsync(new Pilots { Callsign = "Falcon" }, idempotencyKey: writeId);
Singletons
Edit the singleton's value and save it, like a record:
var config = await PlayServData.GetSingletonAsync<ArenaConfig>();
config.Value.MatchDuration = 240;
await config.SaveAsync();
You don't create a singleton: PlayServ creates it with its default values the first time it's read. It can't be deleted. Saving it from the game needs Client Write on the entity, like any other write.
When a write is refused
| Exception | When | What to do |
|---|---|---|
PlayServDataAccessDeniedException | Client Write is off for this entity. | Turn it on, or make the change in a function. |
PlayServRecordConflictException | StaleVersion: someone saved the record first. Otherwise a Unique field already has this value; Kind is then Unknown. | Reload and save again; or choose another value. |
PlayServRecordNotFoundException | The record was deleted, or belongs to another player. | — |
PlayServDataException, BackendCode acting_player_required | A write to a player-owned entity without a signed-in player. | Connect with a player first. |
PlayServDataException, validation error | The value doesn't fit the schema: BackendCode is unknown_field, missing_required_field, invalid_field_type or validation_failed. | Check the field names and types against the schema, case included. |
InvalidOperationException | Saving a partial record. | Reload it first. |
Next steps
- Live Records — get changes as they happen
- Access Control — who may write each entity
- Functions — changes that must run on the server
Last updated on 21 Oct 2026