Skip to main content
Data & Schema

Not translated yet — showing English.

Reading Records

Your game reads its data as typed C# records with PlayServData.Records<T>(). Each entity of your schema has a C# class; you load a record by its ID or query many with filters, sorting and pages. The examples use the Sky Arena schema: Ships, Pilots, MatchResults and the ArenaConfig singleton.

using Playserv.Data;
using Playserv.Wrapper;
using UnityEngine;

var ships = PlayServData.Records<Ships>();

// One record by ID
PlayServRecord<Ships> ship = await ships.LoadAsync(shipId);
Debug.Log(ship.Value.Name);

// Ships up to 500, cheapest first, 20 per page
var page = await ships.QueryAsync(
    new PlayServRecordQuery<Ships>()
        .Where(s => s.Price <= 500)
        .OrderBy(s => s.Price),
    new PlayServPagination(limit: 20));

C# types for your entities

Each entity needs a C# class with the same name and fields. You can generate them from the schema, or write them yourself.

WayHow
Generate from the schemaIn Tools ▸ PlayServ ▸ Settings, under Schema Workflows, choose Import JSON & Generate. The classes are written to Assets/Shared/Generated/Models and replaced each time you generate.
Write them yourselfPlain C# classes, no base class needed. With the local schema tool, the same classes can also define the schema, see Access Control.
public class Ships
{
    public string Name;
    public ShipClass Class;
    public Stats Stats;      // an included part
    public int Price;
}

public class Stats { public double Speed; public int Armor; public int Damage; }

public class Pilots
{
    public string Callsign;
    public int Level;
    public PlayServRecordRef<Ships> Ship;   // a relation
    public Loadout Loadout;
}
RuleWhy
The class is named exactly like the entity.Records<Ships>() finds the entity by the class name. Use Records<T>("ent_…") with the entity's ID if they differ.
Field names match the schema exactly, case included.Fields are sent under their C# names. [PlayServField("name")] maps a different name, [PlayServIgnore] leaves a member out.
Included parts are nested classes or lists.They are stored inside the record.
Relations are PlayServRecordRef<T> (SDK 0.6.4 and later), or the target's ID as a string, as in generated classes.The record stores only the ID; see Relations.

A loaded record comes as PlayServRecord<T>: its fields are in Value, and the record also carries its Id, Owner, CreatedAt and UpdatedAt. You never set the ID yourself: PlayServ creates it.


Load one record

CallReturns
LoadAsync(id)The record with that ID. Throws PlayServRecordNotFoundException if there isn't one.
LoadByNaturalKeyAsync(PlayServNaturalKey<T>.For(x => x.Name, "Falcon"))The record whose unique field has that value. The field must be marked Unique in the schema.
LoadManyAsync(ids)Several records by ID, in the order you asked, with a result per ID.
var falcon = await ships.LoadByNaturalKeyAsync(PlayServNaturalKey<Ships>.For(s => s.Name, "Falcon"));

Query

QueryAsync(query, pagination) returns a page of records that match a PlayServRecordQuery<T>.

MethodWhat it does
Where(x => …) · And(x => …)Filters with a C# condition: ==, !=, >, >=, <, <=, null checks, &&, and list.Contains(x.Field).
Where(x => x.Field, PlayServQueryOperator.…, value)Filters with an operator: Eq, Neq, Gt, Gte, Lt, Lte, In, Nin, Between, Contains, StartsWith, EndsWith, IsNull, IsNotNull, IsEmpty, IsNotEmpty, and Count… for list sizes.
OrderBy(x => …) · OrderByDescending(x => …)Sorts.
Search("text")Full-text search over the entity.
SelectFields(...) · Hide(...)Loads only some fields, see below.
PagingWhat it does
new PlayServPagination(limit: 20)Records per page: 50 by default, up to 200.
page.Records · page.HasMore · page.NextCursorThe records, whether there are more, and the cursor of the next page: pass it as new PlayServPagination(page.NextCursor, 20).
LoadAllAsync(query)Pages through for you, up to 1000 records by default; IsTruncated says whether there were more.

Filter enum fields by name

To filter on an enum field, compare it with the value's name: Where("Class", PlayServQueryOperator.Eq, "Fighter"). A C# condition on the enum, such as x.Class == ShipClass.Fighter, may not match.


Relations and parts

Parts are part of the record: they load with it, and you can filter on their fields with a nested path, such as .Where(s => s.Stats.Speed > 10).

Relations store only the target's ID. To get the target record:

CallWhat it does
await pilot.Value.Ship.LoadAsync()Loads the related ship. Returns null, not an exception, if it no longer exists.
.Include(p => p.Ship) on a queryLoads the related records together with the page: the ship's fields are then in pilot.Value.Ship.Value, with no extra call. A query includes direct relations only; live records can include nested ones.

Load only some fields

SelectFields loads only the fields you name, and Hide loads all but those; you can use one or the other. A record loaded this way is partial: IsPartial is true, and it can't be saved until you call ReloadAsync().

A partial record can't be saved

The SDK refuses to save it and throws InvalidOperationException. Reload the record first, or load it without SelectFields.


Singletons

A singleton entity has exactly one record, read with GetSingletonAsync<T>():

PlayServSingleton<ArenaConfig> config = await PlayServData.GetSingletonAsync<ArenaConfig>();
int maxPlayers = config.Value.MaxPlayers;

A singleton has no ID and can't be deleted or subscribed to.


Errors

ExceptionWhen
PlayServRecordNotFoundExceptionNo record with that ID or natural key.
PlayServDataAccessDeniedExceptionThe game may not read this entity, see Access Control.
PlayServQueryCapabilityExceptionThe query uses something the call doesn't support, see Live Records.
PlayServDataExceptionAnything else: StatusCode, BackendCode and IsNetworkError say what happened.

Players see only their own records of a player-owned entity

On an entity owned by players, with read access Owner, a query returns only the signed-in player's records. See Player-owned entities.


Next steps

Last updated on 21 Oct 2026