iaincollins · March 10, 2025 11:50 · Mar 10, 2025 · Sep 24, 2024 · Sep 24, 2024 · Sep 24, 2024
diff --git a/...d Save - How to find and match players.md → ... use Queries to find and match players.md b/...d Save - How to find and match players.md → ... use Queries to find and match players.md
@@ -1,15 +1,17 @@
-# How to use Cloud Save to find and match players
+# How to use Queries in Cloud Save to find and match players
 
 This guide describes how you can use [Unity Cloud Save](https://docs.unity.com/cloud-save) to find players by name (or any other property).
 
-This functionality is supported in Cloud Save SDK for Unity and the C# and JavaScript SDKs for Unity Cloud Code.
+This functionality is supported in **Cloud Save SDK for Unity** and the C# and JavaScript SDKs for **Unity Cloud Code**.
 
 # 1. Create Indexes for the keys you want to query on
 
-Before saving data, first define an Index for the keys you want to query on (e.g. in the Unity Cloud Dashboard or using the Unity CLI) so that you can query on these keys.
-
 This example assumes there are indexes on the keys *"name"* and *"level"* in the **Public Access Class** for **Player Data**.
 
+You can create and edit **Indexes** using the the [Unity Cloud Dashboard](https://cloud.unity.com/home/organizations/default/projects/default/environments/default/cloud-save/indexes) or using the [Unity Gaming Services CLI](https://services.docs.unity.com/guides/ugs-cli/latest/cloud-save/Cloud%20Save%20Command%20Line/Commands/Data%20Index/data-index-player-create/).
+
+IMPORTANT: Before saving data you want to query, first create an **Index** for the keys you want to query on. If you already have data saved in a key in Cloud Save that you want to query on which was saved before an index was created, the data will need to be re-saved before you can query it.
+
 # 2. Save Player Data to the Public Access Class
 
 Write to the data you want to use for matching (e.g. the keys *"name"* and *"level"*) to **Player Data** in the **Public Access Class** (public data is directly readable by other players, but only the player the data belongs to can write to it).
@@ -23,13 +25,14 @@ using SaveOptions = Unity.Services.CloudSave.Models.Data.Player.SaveOptions;
 
 var playerName = "Alex";
 var playerLevel = "5";
+
 var data = new Dictionary<string, object> { { "name", playerName }, { "level", playerLevel } };
 await CloudSaveService.Instance.Data.Player.SaveAsync(data, new SaveOptions(new PublicWriteAccessClassOptions()));
 ```
 
 # 3. Query for data from your game
 
-You can now find other players using a query in your game.
+You can now find other players using a query in your game. This example shows how to query Cloud Save from the Unity runtime, but can also do this from [Unity Cloud Code](https://cloud-code-sdk-documentation.cloud.unity3d.com/cloud-save) for server authoritative game logic.
 
 ```C#
 using System.Collections.Generic;
@@ -41,13 +44,15 @@ using SaveOptions = Unity.Services.CloudSave.Models.Data.Player.SaveOptions;
 // Query to find all players named Alex AND who are level 5 or above
 var playerName = "Alex";
 var playerLevel = "5";
+
 var query = new Query(
   new List<FieldFilter> {
     new FieldFilter("name", playerName, FieldFilter.OpOptions.EQ, true),
     new FieldFilter("level", playerLevel, FieldFilter.OpOptions.GE, true)
   },
   new HashSet<string> {
-   "name", "level", "location", "avatar" // List of any keys in the Public Access Class to return along with results
+   // List of any keys in the Public Access Class to return along with results
+   "name", "level", "location", "avatar" 
   }
 );
 var results = await CloudSaveService.Instance.Data.Player.QueryAsync(query, new QueryOptions());
@@ -67,7 +72,7 @@ results.ForEach(r => {
 
 If you want players to be able to query data belonging to other players that is not in the **Public Access Class** then you can use Cloud Code (or a game server). Cloud Code Modules (C#) and Cloud Code Scripts (JavaScript) can query and return data for any player, in any Access Class.
 
-For example, in a real game you might want to store a players level in the **Protected Access Class** - which a player can read from, but only Cloud Code (or a game server) can write to. Alternatively, you could use **Access Controls** to disable clients from writing to data in the **Public Access Class**. Both approaches are good ways to implement server authortative game logic.
+For example, in a real game you might want to store a players level in the **Protected Access Class** - which a player can read from, but only Cloud Code (or a game server) can write to. Alternatively, you could use **Access Controls** to disable clients from writing to data in the **Public Access Class**. Both approaches are good ways to implement server authoritative game logic.
 
 ## Enforcing Uniqueness
 
@@ -77,14 +82,11 @@ Cloud Save does not support enforcing uniqueness on values, if that is something
 
 This is only intended an example of how you _can_ use Unity Cloud Save, and may not be the best approach for all use cases.
 
-The Unity Authentication service natively supports the concepts of Player Names, you should consider if that is appropriate to use for your use case.
+For example, the Unity Authentication service natively supports the concepts of Player Names, you should consider if that is appropriate to use for your use case.
 
 ## Documentation
 
-* About Cloud Save Queries https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/concepts/queries
-* About Player Data Access Classes https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/concepts/player-data#Access_Classes
-* How to query Player Data https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/tutorials/unity-sdk#Query_Player_Data
-
-See also:
-
+* [About Cloud Save Queries](https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/concepts/queries)
+* [About Player Data Access Classes](https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/concepts/player-data#Access_Classes)
+* [How to query Player Data](https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/tutorials/unity-sdk#Query_Player_Data)
 * [How to use Cloud Save to find players using Queries](https://gist.github.com/iaincollins/afd07fd3b809ee91face5c246a5f011c)
diff --git a/Unity Cloud Save - How to find and match players.md b/Unity Cloud Save - How to find and match players.md
@@ -87,4 +87,4 @@ The Unity Authentication service natively supports the concepts of Player Names,
 
 See also:
 
-* [How to use Cloud Save Queries to find players using Indexes and Queries](https://gist.github.com/iaincollins/afd07fd3b809ee91face5c246a5f011c)
+* [How to use Cloud Save to find players using Queries](https://gist.github.com/iaincollins/afd07fd3b809ee91face5c246a5f011c)
diff --git a/Unity Cloud Save - How to find and match players.md b/Unity Cloud Save - How to find and match players.md
@@ -87,4 +87,4 @@ The Unity Authentication service natively supports the concepts of Player Names,
 
 See also:
 
-* [How to use Cloud Save Queries to find players using Indexes and Queries]([https://gist.github.com/iaincollins/0fc748e227fe18364ced0ccf3eee503e](https://gist.github.com/iaincollins/afd07fd3b809ee91face5c246a5f011c))
+* [How to use Cloud Save Queries to find players using Indexes and Queries](https://gist.github.com/iaincollins/afd07fd3b809ee91face5c246a5f011c)
diff --git a/Unity Cloud Save - How to find and match players.md b/Unity Cloud Save - How to find and match players.md
@@ -84,3 +84,7 @@ The Unity Authentication service natively supports the concepts of Player Names,
 * About Cloud Save Queries https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/concepts/queries
 * About Player Data Access Classes https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/concepts/player-data#Access_Classes
 * How to query Player Data https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/tutorials/unity-sdk#Query_Player_Data
+
+See also:
+
+* [How to use Cloud Save Queries to find players using Indexes and Queries]([https://gist.github.com/iaincollins/0fc748e227fe18364ced0ccf3eee503e](https://gist.github.com/iaincollins/afd07fd3b809ee91face5c246a5f011c))
diff --git a/Unity Cloud Save - How to find and match players.md b/Unity Cloud Save - How to find and match players.md
@@ -1,4 +1,4 @@
-# How to use Cloud Save Queries for finding players
+# How to use Cloud Save to find and match players
 
 This guide describes how you can use [Unity Cloud Save](https://docs.unity.com/cloud-save) to find players by name (or any other property).
 

diff --git a/... Files - How to find and match players.md → ...d Save - How to find and match players.md b/... Files - How to find and match players.md → ...d Save - How to find and match players.md
diff --git a/Cloud Save Files - How to find and match players.md b/Cloud Save Files - How to find and match players.md
@@ -18,8 +18,8 @@ Write to the data you want to use for matching (e.g. the keys *"name"* and *"lev
 using System.Collections.Generic;
 using Unity.Services.CloudSave;
 using Unity.Services.CloudSave.Models;
+using Unity.Services.CloudSave.Models.Data.Player;
 using SaveOptions = Unity.Services.CloudSave.Models.Data.Player.SaveOptions;
-using PublicWriteAccessClassOptions = Unity.Services.CloudSave.Models.Data.Player.PublicWriteAccessClassOptions;
 
 var playerName = "Alex";
 var playerLevel = "5";
@@ -35,7 +35,7 @@ You can now find other players using a query in your game.
 using System.Collections.Generic;
 using Unity.Services.CloudSave;
 using Unity.Services.CloudSave.Models;
-using QueryOptions = Unity.Services.CloudSave.Models.Data.Player.QueryOptions;
+using Unity.Services.CloudSave.Models.Data.Player;
 using SaveOptions = Unity.Services.CloudSave.Models.Data.Player.SaveOptions;
 
 // Query to find all players named Alex AND who are level 5 or above

diff --git a/Cloud Save Files - How to find and match players.md b/Cloud Save Files - How to find and match players.md
@@ -55,7 +55,7 @@ var results = await CloudSaveService.Instance.Data.Player.QueryAsync(query, new
 Debug.Log($"Number of players returned {results.Count}");
 results.ForEach(r => {
   Debug.Log($"Player ID: {r.Id}");
-  r.Data.ForEach(d => Log($"Key: {d.Key}, Value: {d.Value.GetAsString()}"));
+  r.Data.ForEach(d => Debug.Log($"Key: {d.Key}, Value: {d.Value.GetAsString()}"));
 });
 ```
 

diff --git a/Cloud Save Files - How to find and match players.md b/Cloud Save Files - How to find and match players.md
@@ -15,9 +15,11 @@ This example assumes there are indexes on the keys *"name"* and *"level"* in the
 Write to the data you want to use for matching (e.g. the keys *"name"* and *"level"*) to **Player Data** in the **Public Access Class** (public data is directly readable by other players, but only the player the data belongs to can write to it).
 
 ```C#
+using System.Collections.Generic;
 using Unity.Services.CloudSave;
 using Unity.Services.CloudSave.Models;
 using SaveOptions = Unity.Services.CloudSave.Models.Data.Player.SaveOptions;
+using PublicWriteAccessClassOptions = Unity.Services.CloudSave.Models.Data.Player.PublicWriteAccessClassOptions;
 
 var playerName = "Alex";
 var playerLevel = "5";
@@ -30,20 +32,25 @@ await CloudSaveService.Instance.Data.Player.SaveAsync(data, new SaveOptions(new
 You can now find other players using a query in your game.
 
 ```C#
+using System.Collections.Generic;
 using Unity.Services.CloudSave;
 using Unity.Services.CloudSave.Models;
+using QueryOptions = Unity.Services.CloudSave.Models.Data.Player.QueryOptions;
+using SaveOptions = Unity.Services.CloudSave.Models.Data.Player.SaveOptions;
 
 // Query to find all players named Alex AND who are level 5 or above
 var playerName = "Alex";
 var playerLevel = "5";
 var query = new Query(
   new List<FieldFilter> {
-    new FieldFilter("name", playerName, FieldFilter.OpOptions.EQ, true)
+    new FieldFilter("name", playerName, FieldFilter.OpOptions.EQ, true),
     new FieldFilter("level", playerLevel, FieldFilter.OpOptions.GE, true)
   },
-  { "level", "name", "location", "avatar" } // List of any keys in the Public Access Class to return along with results
+  new HashSet<string> {
+   "name", "level", "location", "avatar" // List of any keys in the Public Access Class to return along with results
+  }
 );
-var results = await CloudSaveService.Instance.Data.Player.QueryAsync(query);
+var results = await CloudSaveService.Instance.Data.Player.QueryAsync(query, new QueryOptions());
 
 Debug.Log($"Number of players returned {results.Count}");
 results.ForEach(r => {

diff --git a/Cloud Save Files - How to find and match players.md b/Cloud Save Files - How to find and match players.md
@@ -0,0 +1,79 @@
+# How to use Cloud Save Queries for finding players
+
+This guide describes how you can use [Unity Cloud Save](https://docs.unity.com/cloud-save) to find players by name (or any other property).
+
+This functionality is supported in Cloud Save SDK for Unity and the C# and JavaScript SDKs for Unity Cloud Code.
+
+# 1. Create Indexes for the keys you want to query on
+
+Before saving data, first define an Index for the keys you want to query on (e.g. in the Unity Cloud Dashboard or using the Unity CLI) so that you can query on these keys.
+
+This example assumes there are indexes on the keys *"name"* and *"level"* in the **Public Access Class** for **Player Data**.
+
+# 2. Save Player Data to the Public Access Class
+
+Write to the data you want to use for matching (e.g. the keys *"name"* and *"level"*) to **Player Data** in the **Public Access Class** (public data is directly readable by other players, but only the player the data belongs to can write to it).
+
+```C#
+using Unity.Services.CloudSave;
+using Unity.Services.CloudSave.Models;
+using SaveOptions = Unity.Services.CloudSave.Models.Data.Player.SaveOptions;
+
+var playerName = "Alex";
+var playerLevel = "5";
+var data = new Dictionary<string, object> { { "name", playerName }, { "level", playerLevel } };
+await CloudSaveService.Instance.Data.Player.SaveAsync(data, new SaveOptions(new PublicWriteAccessClassOptions()));
+```
+
+# 3. Query for data from your game
+
+You can now find other players using a query in your game.
+
+```C#
+using Unity.Services.CloudSave;
+using Unity.Services.CloudSave.Models;
+
+// Query to find all players named Alex AND who are level 5 or above
+var playerName = "Alex";
+var playerLevel = "5";
+var query = new Query(
+  new List<FieldFilter> {
+    new FieldFilter("name", playerName, FieldFilter.OpOptions.EQ, true)
+    new FieldFilter("level", playerLevel, FieldFilter.OpOptions.GE, true)
+  },
+  { "level", "name", "location", "avatar" } // List of any keys in the Public Access Class to return along with results
+);
+var results = await CloudSaveService.Instance.Data.Player.QueryAsync(query);
+
+Debug.Log($"Number of players returned {results.Count}");
+results.ForEach(r => {
+  Debug.Log($"Player ID: {r.Id}");
+  r.Data.ForEach(d => Log($"Key: {d.Key}, Value: {d.Value.GetAsString()}"));
+});
+```
+
+---
+
+# Additional information
+
+## Server authoritative game logic
+
+If you want players to be able to query data belonging to other players that is not in the **Public Access Class** then you can use Cloud Code (or a game server). Cloud Code Modules (C#) and Cloud Code Scripts (JavaScript) can query and return data for any player, in any Access Class.
+
+For example, in a real game you might want to store a players level in the **Protected Access Class** - which a player can read from, but only Cloud Code (or a game server) can write to. Alternatively, you could use **Access Controls** to disable clients from writing to data in the **Public Access Class**. Both approaches are good ways to implement server authortative game logic.
+
+## Enforcing Uniqueness
+
+Cloud Save does not support enforcing uniqueness on values, if that is something you need you would need to write code to implement that logic.
+
+## Alternative approaches
+
+This is only intended an example of how you _can_ use Unity Cloud Save, and may not be the best approach for all use cases.
+
+The Unity Authentication service natively supports the concepts of Player Names, you should consider if that is appropriate to use for your use case.
+
+## Documentation
+
+* About Cloud Save Queries https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/concepts/queries
+* About Player Data Access Classes https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/concepts/player-data#Access_Classes
+* How to query Player Data https://docs.unity.com/ugs/en-us/manual/cloud-save/manual/tutorials/unity-sdk#Query_Player_Data