Collections

Every app or game has data which is specific to the project.

This information must be stored for each user, as well as updated, retrieved, and displayed within various parts of a UI. For this purpose the server incorporates a storage engine with a design optimized for object ownership, access permissions, and batch operations.

Data is stored in collections with one or more objects which contain a unique key with JSON content. A collection is created without any configuration required. This creates a simple nested namespace which represents the location of a object.

This design gives great flexibility for developers to group sets of information which belong together within a game or app.

Collection
+---------------------------------------------------------------------+
|  Object                                                             |
|  +----------+------------+-------------+-----+-------------------+  |
|  | ?UserId? | Identifier | Permissions | ... |       Value       |  |
|  +---------------------------------------------------------------+  |
+---------------------------------------------------------------------+

The Collection and Key are used to identify the object itself. The UserId is used to identify the owner of an object, and to check for the needed read/write permissions when calling those operations on a object from the client.

Writing custom SQL is discouraged in favor of using the built-in features of the Storage Engine. If custom SQL is needed for your use case, please contact Heroic Labs before proceeding.

The creation of custom tables is strongly discouraged.

Write objects #

A user can write one or more objects which will be stored in the database server. These objects will be written in a single transaction which guarantees the writes succeed together.

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
curl -X PUT "http://127.0.0.1:7350/v2/storage" \
  -H 'Authorization: Bearer <session token>' \
  -d '{"objects":
    [
      {
        "collection": "saves",
        "key": "savegame",
        "value": "{\"progress\": \"50\"}"
      },
      {
        "collection": "stats",
        "key": "skill",
        "value": "{\"progress\": \"24\"}"
      }
    ]
  }'

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
var save_game = { "progress": 50 };
var my_stats = { "skill": 24 };

const object_ids = await client.writeStorageObjects(session, [
  {
    "collection": "saves",
    "key": "savegame",
    "value": save_game
  }, {
    "collection": "stats",
    "key": "skills",
    "value": my_stats
  }
]);

console.info("Successfully stored objects: ", object_ids);

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
var saveGame = "{ \"progress\": 50 }";
var myStats = "{ \"skill\": 24 }";

var writeObjects = new [] {
    new WriteStorageObject
    {
        Collection = "saves",
        Key = "savegame",
        Value = saveGame
    },
    new WriteStorageObject
    {
        Collection = "stats",
        Key = "skills",
        Value = myStats
    }
};

await client.WriteStorageObjectsAsync(session, writeObjects);
Console.WriteLine("Successfully stored objects: [{0}]", string.Join(",\n  ", objectIds));

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
let saveGame = "{ \"progress\": 50 }"
let myStats = "{ \"skill\": 24 }"

let writeObjects = [
    WriteStorageObject(collection: "saves", key: "savegame", value: saveGame),
    WriteStorageObject(collection: "stats", key: "skills", value: myStats)
]

let acks = try await client.writeStorageObjects(session: session, objects: writeObjects)
debugPrint("Successfully stored objects:", acks)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
const saveGame = '{"progress": 50}';
const myStats = '{"skill": 24}';

var writeObjects = [
  WriteStorageObject(collection: 'saves', key: 'savegame', value: saveGame),
  WriteStorageObject(collection: 'stats', key: 'skills', value: myStats),
];

for (final wo in writeObjects) {
  await client.writeStorageObject(
    session: session,
    collection: wo.collection,
    key: wo.key,
    value: wo.value,
  );
}
print('Successfully stored objects: $writeObjects');

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
auto successCallback = [](const NStorageObjectAcks& acks)
{
    std::cout << "Successfully stored objects " << acks.size() << std::endl;
};

std::vector<NStorageObjectWrite> objects;
NStorageObjectWrite savesObject, statsObject;
savesObject.collection = "saves";
savesObject.key = "savegame";
savesObject.value = "{ \"progress\": 50 }";
objects.push_back(savesObject);

statsObject.collection = "stats";
statsObject.key = "skills";
statsObject.value = "{ \"skill\": 24 }";
objects.push_back(statsObject);
client->writeStorageObjects(session, objects, successCallback);

Client
1
2
3
4
5
6
String saveGame = "{ \"progress\": 50 }";
String myStats = "{ \"skill\": 24 }";
StorageObjectWrite saveGameObject = new StorageObjectWrite("saves", "savegame", saveGame, PermissionRead.OWNER_READ, PermissionWrite.OWNER_WRITE);
StorageObjectWrite statsObject = new StorageObjectWrite("stats", "skills", myStats, PermissionRead.OWNER_READ, PermissionWrite.OWNER_WRITE);
StorageObjectAcks acks = client.writeStorageObjects(session, saveGameObject, statsObject).get();
System.out.format("Stored objects %s", acks.getAcksList());

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
var save_game = "{ \"progress\": 50 }"
var my_stats = "{ \"skill\": 24 }"
var can_read = 1
var can_write = 1
var version = ""

var acks : NakamaAPI.ApiStorageObjectAcks = yield(client.write_storage_objects_async(session, [
    NakamaWriteStorageObject.new("saves", "savegame", can_read, can_write, save_game, version),
    NakamaWriteStorageObject.new("stats", "skills", can_read, can_write, my_stats, version)
]), "completed")

if acks.is_exception():
    print("An error occurred: %s" % acks)
    return

print("Successfully stored objects:")

for a in acks.acks:
    print("%s" % a)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
var save_game = "{ \"progress\": 50 }"
var my_stats = "{ \"skill\": 24 }"
var can_read = 1
var can_write = 1
var version = ""

var acks : NakamaAPI.ApiStorageObjectAcks = await client.write_storage_objects_async(session, [
    NakamaWriteStorageObject.new("saves", "savegame", can_read, can_write, save_game, version),
    NakamaWriteStorageObject.new("stats", "skills", can_read, can_write, my_stats, version)
])

if acks.is_exception():
    print("An error occurred: %s" % acks)
    return

print("Successfully stored objects:")

for a in acks.acks:
    print("%s" % a)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
PUT /v2/storage
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
{
  "objects": [
    {
      "collection": "saves",
      "key": "key",
      "value": "{\"hello\": \"world\"}"
    },
    {
      "collection": "stats",
      "key": "skill",
      "value": "{\"progress\": \"24\"}"
    }
  ]
}

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
local save_game = json.encode({ progress = 50 })
local my_stats = json.encode({ skill = 24 })
local can_read = 1
local can_write = 1
local version = ""

local objects = {
  {
    collection = "saves",
    key = "savegame",
    permissionRead = can_read,
    permissionWrite = can_write,
    value = save_game,
    version = version,
  },
  {
    collection = "stats",
    key = "skills",
    permissionRead = can_read,
    permissionWrite = can_write,
    value = my_stats,
    version = version,
  }
}

local result = client.write_storage_objects(objects)

if result.error then
  print(result.message)
  return
end

for _,ack in ipairs(result.acks) do
  pprint(ack)
end

Conditional writes #

When objects are successfully stored a version is returned which can be used with further updates to perform concurrent modification checks with the next write. This is known as a conditional write.

A conditional write ensures a client can only update the object if they’ve seen the previous version of the object. The purpose is to prevent a change to the object if another client has changed the value between the first client’s read and its next write.

When the version doesn’t match, the server rejects the write and returns gRPC InvalidArgument (code 3), which maps to HTTP 400, with the message Storage write rejected. A conditional delete that fails its version check returns the same code with Storage delete rejected. Client libraries surface this as an error or exception carrying that code.

The server returns this same code and message when it rejects a write for insufficient permissions, so the response alone doesn’t tell you which of the two happened. Treat a rejection as a signal to re-read the object, take its current version, and retry the write with that version. For the full set of status codes and their HTTP mappings, see the Error reference.

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
curl -X PUT "http://127.0.0.1:7350/v2/storage" \
  -H 'Authorization: Bearer <session token>' \
  -d '{
    "objects": [
      {
        "collection": "saves",
        "key": "savegame",
        "value": "{\"progress\": \"50\"}",
        "version": "some-previous-version"
      }
    ]
  }'

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
var save_game = { "progress": 50 };

const object_ids = await client.writeStorageObjects(session, [
  {
    "collection": "saves",
    "key": "savegame",
    "value": save_game,
    "version": "<version>"
  }
]);

console.info("Stored objects: %o", object_ids);

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
var saveGame = "{ \"progress\": 50 }";

var objectIds = await client.WriteStorageObjectsAsync(session, new [] { 
  new WriteStorageObject
  {
      Collection = "saves",
      Key = "savegame",
      Value = saveGame,
      Version = "<version>"
  }
});

Console.WriteLine("Stored objects: [{0}]", string.Join(",\n  ", objectIds));

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
let saveGame = "{ \"progress\": 50 }"

let acks = try await client.writeStorageObjects(session: session, WriteStorageObject(
    collection: "saves",
    key: "savegame",
    value: saveGame,
    version: "<version>"
))

debugPrint("Stored objects:", objectIds)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const saveGame = '{"progress": 50}';

await client.writeStorageObject(
    session: session,
    collection: 'saves',
    key: 'savegame',
    value: saveGame,
    version: '<version>',
);

print('Stored objects:');

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
auto successCallback = [](const NStorageObjectAcks& acks)
{
    std::cout << "Successfully stored objects " << acks.size() << std::endl;
};

std::vector<NStorageObjectWrite> objects;
NStorageObjectWrite savesObject;
savesObject.collection = "saves";
savesObject.key = "savegame";
savesObject.value = "{ \"progress\": 50 }";
savesObject.version = "<version>";
objects.push_back(savesObject);
client->writeStorageObjects(session, objects, successCallback);

Client
1
2
3
4
5
String saveGame = "{ \"progress\": 50 }";
StorageObjectWrite object = new StorageObjectWrite("saves", "savegame", saveGame, PermissionRead.OWNER_READ, PermissionWrite.OWNER_WRITE);
object.setVersion("<version>");
StorageObjectAcks acks = client.writeStorageObjects(session, object).get();
System.out.format("Stored objects %s", acks.getAcksList());

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
var save_game = "{ \"progress\": 50 }"
var can_read = 1
var can_write = 1
var version = "<version>"

var acks : NakamaAPI.ApiStorageObjectAcks = yield(client.write_storage_objects_async(session, [
    NakamaWriteStorageObject.new("saves", "savegame", can_read, can_write, save_game, version)
]), "completed")

if acks.is_exception():
    print("An error occurred: %s" % acks)
    return

print("Successfully stored objects:")

for a in acks.acks:
    print("%s" % a)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
var save_game = "{ \"progress\": 50 }"
var can_read = 1
var can_write = 1
var version = "<version>"

var acks : NakamaAPI.ApiStorageObjectAcks = await client.write_storage_objects_async(session, [
    NakamaWriteStorageObject.new("saves", "savegame", can_read, can_write, save_game, version)
])

if acks.is_exception():
    print("An error occurred: %s" % acks)
    return

print("Successfully stored objects:")

for a in acks.acks:
    print("%s" % a)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
PUT /v2/storage
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
{
  "objects": [
    {
      "collection": "saves",
      "key": "key",
      "value": "{\"hello\": \"world\"}",
      "version": "<version>"
    }
  ]
}

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
local save_game = json.encode({ progress = 50 })
local can_read = 1
local can_write = 1
local version = "some previous version"

local objects = {
  {
    collection = "saves",
    key = "savegame",
    permissionRead = can_read,
    permissionWrite = can_write,
    value = save_game,
    version = version,
  }
}

local result = client.write_storage_objects(objects)

if result.error then
  print(result.message)
  return
end

for _,ack in ipairs(result.acks) do
  pprint(ack)
end

Create-only writes #

Setting version to "*" writes the object only if none already exists for that collection, key, and user ID. If an object already exists, the write fails.

This is useful for initializing an object exactly once without reading first to check for existence, and for distributed locking: when multiple processes race to write the same key, only the first write succeeds.

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
curl -X PUT "http://127.0.0.1:7350/v2/storage" \
  -H 'Authorization: Bearer <session token>' \
  -d '{
    "objects": [
      {
        "collection": "saves",
        "key": "savegame",
        "value": "{\"progress\": \"50\"}",
        "version": "*"
      }
    ]
  }'

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
var save_game = { "progress": 50 };
const object_ids = await client.writeStorageObjects(session, [
  {
    "collection": "saves",
    "key": "savegame",
    "value": save_game,
    "version": "*"
  }
]);
console.info("Stored objects: %o", object_ids);

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
var saveGame = "{ \"progress\": 50 }";

var objectIds = await client.WriteStorageObjectsAsync(session, new [] {
  new WriteStorageObject
  {
      Collection = "saves",
      Key = "savegame",
      Value = saveGame,
      Version = "*"
  }
});

Console.WriteLine("Stored objects: [{0}]", string.Join(",\n  ", objectIds));

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
let saveGame = "{ \"progress\": 50 }"

let acks = try await client.writeStorageObjects(session: session, WriteStorageObject(
    collection: "saves",
    key: "savegame",
    value: saveGame,
    version: "*"
))

debugPrint("Stored objects:", objectIds)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const saveGame = '{"progress": 50}';

await client.writeStorageObject(
    session: session,
    collection: 'saves',
    key: 'savegame',
    value: saveGame,
    version: '*',
);

print('Stored objects:');

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
auto successCallback = [](const NStorageObjectAcks& acks)
{
    std::cout << "Successfully stored objects " << acks.size() << std::endl;
};

std::vector<NStorageObjectWrite> objects;
NStorageObjectWrite savesObject;
savesObject.collection = "saves";
savesObject.key = "savegame";
savesObject.value = "{ \"progress\": 50 }";
savesObject.version = "*";
objects.push_back(savesObject);
client->writeStorageObjects(session, objects, successCallback);

Client
1
2
3
4
5
String saveGame = "{ \"progress\": 50 }";
StorageObjectWrite object = new StorageObjectWrite("saves", "savegame", saveGame, PermissionRead.OWNER_READ, PermissionWrite.OWNER_WRITE);
object.setVersion("*");
StorageObjectAcks acks = client.writeStorageObjects(session, object).get();
System.out.format("Stored objects %s", acks.getAcksList());

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Requires Nakama 1.x

String saveGame = "{\"progress\": 1}";
String version = "*"; // write only if the object does not exist.

CollatedMessage<ResultSet<RecordId>> message = StorageWriteMessage.Builder.newBuilder()
    .record("myapp", "saves", "savegame", saveGame, version)
    .build();

Deferred<ResultSet<RecordId>> deferred = client.send(message);

deferred.addCallback(new Callback<ResultSet<RecordId>, ResultSet<RecordId>>() {
    @Override
    public ResultSet<RecordId> call(ResultSet<RecordId> list) throws Exception {
        // Cache updated version for next write.
        version = list.getResults().get(0).getVersion();
        return list;
    }
}).addErrback(new Callback<Error, Error>() {
    @Override
    public Error call(Error err) throws Exception {
        System.err.format("Error('%s', '%s')", err.getCode(), err.getMessage());
        return err;
    }
});

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
var save_game = "{ \"progress\": 50 }"
var can_read = 1
var can_write = 1
var version = "*" # write only if the object does not exist.

var acks : NakamaAPI.ApiStorageObjectAcks = yield(client.write_storage_objects_async(session, [
    NakamaWriteStorageObject.new("saves", "savegame", can_read, can_write, save_game, version)
]), "completed")

if acks.is_exception():
    print("An error occurred: %s" % acks)
    return

print("Successfully stored objects:")

for a in acks.acks:
    print("%s" % a)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
var save_game = "{ \"progress\": 50 }"
var can_read = 1
var can_write = 1
var version = "*" # write only if the object does not exist.

var acks : NakamaAPI.ApiStorageObjectAcks = await client.write_storage_objects_async(session, [
    NakamaWriteStorageObject.new("saves", "savegame", can_read, can_write, save_game, version)
])

if acks.is_exception():
    print("An error occurred: %s" % acks)
    return

print("Successfully stored objects:")

for a in acks.acks:
    print("%s" % a)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
PUT /v2/storage
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
{
  "objects": [
    {
      "collection": "saves",
      "key": "key",
      "value": "{\"hello\": \"world\"}",
      "version": "*"
    }
  ]
}

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
local save_game = json.encode({ progress = 50 })
local can_read = 1
local can_write = 1
local version = "*"   -- write only if the object does not exist


local objects = {
  {
    collection = "saves",
    key = "savegame",
    permissionRead = can_read,
    permissionWrite = can_write,
    value = save_game,
    version = version,
  }
}

local result = client.write_storage_objects(objects)

if result.error then
  print(result.message)
  return
end

for _,ack in ipairs(result.acks) do
  pprint(ack)
end

Handle version conflicts #

A conditional write that loses the race is rejected with Storage write rejected - version check failed. Nothing is written, and if the write was part of a batch the whole batch is rejected.

Conflicts happen at the level of the object, not the field you changed. Every write replaces the object’s entire value, so two updates to unrelated keys in the same object still collide. That is what makes the check worth keeping: without it, the second write would silently discard the first one’s changes.

Conflicts are expected under concurrency, so treat them as a normal condition. Either serialize the writes, awaiting each one before starting the next, or retry with a fresh read. If you retry, always reapply your change to the newly read value, never to the value from the failed attempt, which is missing whichever change beat you to it.

StorageWriteRetry runs that read, apply, and write loop for you, repeating on conflict up to maxRetries times (0 to 10). Your update function runs again on each attempt, so it must derive the new value from the objects it is passed:

Server
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
reads := []*runtime.StorageRead{{Collection: "stats", Key: "player", UserID: userID}}

acks, err := nk.StorageWriteRetry(ctx, reads, func(objects []*api.StorageObject) ([]*runtime.StorageWrite, error) {
  stats := map[string]int64{}
  version := "*"                              // No object yet, so write only if one still doesn't exist.
  permissionRead, permissionWrite := 1, 1     // Set some defaults
  if len(objects) > 0 {
    if err := json.Unmarshal([]byte(objects[0].Value), &stats); err != nil {
      return nil, err
    }
    version = objects[0].Version
    permissionRead = int(objects[0].PermissionRead)   // Keep the existing permissions
    permissionWrite = int(objects[0].PermissionWrite)
  }

  stats["matches_played"]++ // Apply the change to the value just read.

  value, err := json.Marshal(stats)
  if err != nil {
    return nil, err
  }
  return []*runtime.StorageWrite{{
    Collection: "stats", Key: "player", UserID: userID,
    Value: string(value), Version: version,
    PermissionRead: permissionRead, PermissionWrite: permissionWrite,
  }}, nil
}, 5)
if err != nil {
  return err // "Storage write retries exhausted."
}

Server
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
let reads: nkruntime.StorageReadRequest[] = [{ collection: 'stats', key: 'player', userId: userId }];

let acks = nk.storageWriteRetry(reads, (objects) => {
    let stats: { [key: string]: number } = {};
    let version = '*'; // No object yet, so write only if one still doesn't exist.
    let permissionRead = 1, permissionWrite = 1;
    if (objects.length > 0) {
        stats = objects[0].value as { [key: string]: number };
        version = objects[0].version;
        permissionRead = objects[0].permissionRead;
        permissionWrite = objects[0].permissionWrite;
    }

    stats.matches_played = (stats.matches_played || 0) + 1; // Apply the change to the value just read.

    return [{
        collection: 'stats', key: 'player', userId: userId,
        value: stats, version: version,
        permissionRead: permissionRead, permissionWrite: permissionWrite
    }];
}, 5);

Setting permissions

Set permissions on every write, as shown above. A write replaces the entire object, including its permissions. To keep the existing ones, fetch the object first and pass its values back, as with version. In Go an unset PermissionRead or PermissionWrite is sent as 0, while the TypeScript and Lua runtimes default both fields to 1 instead.

Sustained conflicts on one object usually mean the data is modelled too coarsely. Splitting a frequently updated object into separate keys, so unrelated updates no longer compete for the same version, removes the conflict instead of retrying through it. See Modeling for Scalability for more on choosing collection and key boundaries.

Read objects #

Just like with writing objects you can read one or more objects from the database server.

Each object has an owner and permissions. An object can only be read if the permissions allow it. An object which has no owner can be fetched with "null" and is useful for global objects which all users should be able to read.

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
curl -X POST "http://127.0.0.1:7350/v2/storage" \
  -H 'Authorization: Bearer <session token>' \
  -d '{
    "object_ids": [
      {
        "collection": "saves",
        "key": "savegame",
        "user_id": "some-user-id"
      }
    ]
  }'

Client
1
2
3
4
5
6
7
8
const objects = await client.readStorageObjects(session, {
  "object_ids": [{
    "collection": "saves",
    "key": "savegame",
    "user_id": session.user_id
  }]
});
console.info("Read objects: %o", objects);

Client
1
2
3
4
5
6
7
8
9
var result = await client.ReadStorageObjectsAsync(session, new [] {
  new StorageObjectId {
    Collection = "saves",
    Key = "savegame",
    UserId = session.UserId
  }
});

Console.WriteLine("Read objects: [{0}]", string.Join(",\n  ", result.Objects));

Client
1
2
3
4
5
6
var result = try await client.readStorageObjects(session: session, ids: [
    StorageObjectId(collection: "saves", key: "savegame", userId: session.UserId)
  ]
)

debugPrint("Read objects:", result.objects)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
auto successCallback = [](const NStorageObjects& objects)
{
  for (auto& object : objects)
    {
        std::cout << "Object key: " << object.key << ", value: " << object.value << std::endl;
    }
};

std::vector<NReadStorageObjectId> objectIds;
NReadStorageObjectId objectId;
objectId.collection = "saves";
objectId.key = "savegame";
objectId.userId = session->getUserId();
objectIds.push_back(objectId);
client->readStorageObjects(session, objectIds, successCallback);

Client
1
2
3
4
5
StorageObjectId objectId = new StorageObjectId("saves");
objectId.setKey("savegame");
objectId.setUserId(session.getUserId());
StorageObjects objects = client.readStorageObjects(session, objectId).get();
System.out.format("Read objects %s", objects.getObjectsList().toString());

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
var result : NakamaAPI.ApiStorageObjects = yield(client.read_storage_objects_async(session, [
    NakamaStorageObjectId.new("saves", "savegame", session.user_id)
]), "completed")

if result.is_exception():
    print("An error occurred: %s" % result)
    return

print("Read objects:")

for o in result.objects:
    print("%s" % o)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
var result : NakamaAPI.ApiStorageObjects = await client.read_storage_objects_async(session, [
    NakamaStorageObjectId.new("saves", "savegame", session.user_id)
])

if result.is_exception():
    print("An error occurred: %s" % result)
    return

print("Read objects:")

for o in result.objects:
    print("%s" % o)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
POST /v2/storage
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
{
  "object_ids": [
    {
      "collection": "saves",
      "key": "savegame",
      "user_id": "some-user-id"
    }
  ]
}

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
local user_id = "some user id"

local objects_ids = {
  {
    collection = "saves",
    key = "savegame",
    userId = user_id
  }
}

local result = client.read_storage_objects(objects_ids)

if result.error then
  print(result.message)
  return
end

for _,object in ipairs(result.objects) do
  pprint(object)
end

List objects #

You can list objects in a collection and page through results.

The objects returned can be filtered to those owned by a specific user, or "null" for all public records.

Client
1
2
3
4
5
6
7
8
const limit = 100; // default is 10.
final result = await client.listStorageObjects(
  session: session,
  collection: 'saves',
  userId: session.userId,
  limit: limit,
);
print('List objects: ${result.objects}');

Client
1
2
3
4
5
6
7
8
auto successCallback = [](NStorageObjectListPtr list)
{
    for (auto& object : list->objects)
    {
        std::cout << "Object key: " << object.key << ", value: " << object.value << std::endl;
    }
};
client->listUsersStorageObjects(session, "saves", session->getUserId(), opt::nullopt, opt::nullopt, successCallback);

Client
1
2
3
4
5
6
7
8
var limit = 100 # default is 10.
var objects : NakamaAPI.ApiStorageObjectList = yield(client.list_storage_objects_async(session, "saves", session.user_id, limit), "completed")

if objects.is_exception():
  print("An error occurred: %s" % objects)
  return

print("List objects: %s" % objects)

Client
1
2
3
4
5
6
7
8
var limit = 100 # default is 10.
var objects : NakamaAPI.ApiStorageObjectList = await client.list_storage_objects_async(session, "saves", session.user_id, limit)

if objects.is_exception():
  print("An error occurred: %s" % objects)
  return

print("List objects: %s" % objects)

Client
1
2
3
4
5
GET /v2/storage/<collection>?user_id=<user_id>&limit=<limit>&cursor=<cursor>
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
local user_id = "some user id"
local limit = 10
local result = client.list_storage_objects("saves", user_id, limit)

if result.error then
  print(result.message)
  return
end

for _,object in ipairs(result.objects) do
  pprint(object)
end

Remove objects #

A user can remove an object if it has the correct permissions and they own it.

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
curl -X PUT "http://127.0.0.1:7350/v2/storage/delete" \
  -H 'Authorization: Bearer <session token>' \
  -d '{
    "object_ids": [
      {
        "collection": "saves",
        "key": "savegame"
      }
    ]
  }'

Client
1
2
3
4
5
6
7
8
var result = await client.DeleteStorageObjectsAsync(session, new [] {
  new StorageObjectId {
    Collection = "saves",
    Key = "savegame"
  }
});

Console.WriteLine("Deleted objects.");

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
final result = await client.deleteStorageObjects(
  session: session,
  ids: [
    StorageObjectId(
      collection: 'saves',
      key: 'savegame',
    ),
  ],
);

print('Deleted objects.');

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
auto successCallback = []()
{
    std::cout << "Deleted objects." << std::endl;
};

std::vector<NDeleteStorageObjectId> objectIds;
NDeleteStorageObjectId objectId;
objectId.collection = "saves";
objectId.key = "savegame";
objectIds.push_back(objectId);
client->deleteStorageObjects(session, objectIds, successCallback);

Client
1
2
3
4
5
6
7
8
9
var del : NakamaAsyncResult = yield(client.delete_storage_objects_async(session, [
  NakamaStorageObjectId.new("saves", "savegame")
]), "completed")

if del.is_exception():
  print("An error occurred: %s" % del)
  return

print("Deleted objects.")

Client
1
2
3
4
5
6
7
8
9
var del : NakamaAsyncResult = await client.delete_storage_objects_async(session, [
  NakamaStorageObjectId.new("saves", "savegame")
])

if del.is_exception():
  print("An error occurred: %s" % del)
  return

print("Deleted objects.")

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
PUT /v2/storage/delete
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
{
  "object_ids": [
    {
      "collection": "saves",
      "key": "savegame"
    }
  ]
}

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
local objects_ids = {
  {
    collection = "saves",
    key = "savegame"
  }
}

local result = client.delete_storage_objects(object_ids)

if result.error then
  print(result.message)
  return
end

You can also conditionally remove an object if the object version matches the version sent by the client.

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
curl -X PUT \
  http://127.0.0.1:7350/v2/storage/delete \
  -H 'Authorization: Bearer <session token>' \
  -d '{
    "object_ids": [
      {
        "collection": "saves",
        "key": "savegame",
        "version": "<version>"
      }
    ]
  }'

Client
1
2
3
4
5
6
7
8
await client.deleteStorageObjects(session, {
  "object_ids": [{
    "collection": "saves",
    "key": "savegame",
    "version": "<version>"
  }]
});
console.info("Deleted objects.");

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
var result = await client.DeleteStorageObjectsAsync(session, new [] {
  new StorageObjectId {
    Collection = "saves",
    Key = "savegame",
    UserId = session.UserId,
    Version = "<version>"
  }
});

Console.WriteLine("Deleted objects.");

Client
1
2
3
4
5
var result = try await client.deleteStorageObjects(session: session, ids: [
    StorageObjectId(collection: "saves", key: "savegame", userId: session.userId, version = "<version>")
])

debugPrint("Deleted objects.");

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
final result = try await client.deleteStorageObjects(
  session: session,
  ids: [
    StorageObjectId(
      collection: 'saves',
      key: 'savegame',
      userId: session.userId,
      version = '<version>',
    ),
  ],
);

print('Deleted objects.');

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
auto successCallback = []()
{
    std::cout << "Deleted objects." << std::endl;
};

std::vector<NDeleteStorageObjectId> objectIds;
NDeleteStorageObjectId objectId;
objectId.collection = "saves";
objectId.key = "savegame";
objectId.version = "<version>";
objectIds.push_back(objectId);
client->deleteStorageObjects(session, objectIds, successCallback);

Client
1
2
3
4
5
StorageObjectId objectId = new StorageObjectId("saves");
objectId.setKey("savegame");
objectId.setVersion("<version>");
client.deleteStorageObjects(session, objectId).get();
System.out.format("Deleted objects.");

Client
1
2
3
4
5
6
7
8
9
var del = yield(client.delete_storage_objects_async(session, [
  NakamaStorageObjectId.new("saves", "savegame", session.user_id, "<version>")
]), "completed")

if del.is_exception():
  print("An error occurred: %s" % del)
  return

print("Deleted objects.")

Client
1
2
3
4
5
6
7
8
9
var del = await client.delete_storage_objects_async(session, [
  NakamaStorageObjectId.new("saves", "savegame", session.user_id, "<version>")
])

if del.is_exception():
  print("An error occurred: %s" % del)
  return

print("Deleted objects.")

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
PUT /v2/storage/delete
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
{
  "object_ids": [
    {
      "collection": "saves",
      "key": "savegame",
      "version": "<version>"
    }
  ]
}

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
local objects_ids = {
  {
    collection = "saves",
    key = "savegame",
    version = "some version"
  }
}

local result = nakama.delete_storage_objects(object_ids)

if result.error then
  print(result.message)
  return
end

Heroic Cloud