# Cloud Save クエリ

> Understand indexes and query types for both numerical and text data stored in player and game data.

Cloud Save を使用すると、**プレイヤーデータ** と **ゲームデータ** に保存された数値データとテキストデータの両方のクエリを実行できます。

ギルドやクランシステムを作成する、マッチメイキングを追加する、経済システムやオークションハウスを実装する、マルチプレイヤー環境で NPC やアイテムのデータを返すなど、さまざまな目的でクエリを使用できます。

## インデックスの作成##index-creation

Cloud Save 内のデータは、クエリを実行する前にインデックスを作成する必要があります。インデックスの作成と管理は [Unity Dashboard](https://cloud.unity.com/home/organizations/default/projects/default/environments/default/cloud-save/indexes)、[Unity CLI](https://services.docs.unity.com/guides/ugs-cli/latest/cloud-save/Cloud%20Save%20Command%20Line/overview/)、または [Admin REST API](/cloud-save/reference/rest-api.md) で行うことができます。

個々の Cloud Save キーでインデックスを形成することも、複数のキーを特定の順序で組み合わせて複合インデックスを形成することもできます。Cloud Save は、各キーを、インデックスを昇順と降順のどちらでソートするかを指定するブーリアン値でマークします。インデックスを使用するのに、追加料金はかかりません。

## クエリタイプ##query-types

Cloud Save では、以下のタイプのクエリがサポートされています。

* `EQ` - 等しい
* `NE` - 等しくない
* `LT` - より小さい
* `LE` - 以下
* `GT` - より大きい
* `GE` - 以上

Cloud Save は、文字列データの場合は辞書的に、数値データの場合は数値的に、値をインデックス化された値と比較します。

## ランダムサンプリング##random-sampling

Cloud Save では、(デフォルトの動作である) ページ分割可能なソートされた結果セット全体を返す必要がない場合に、クエリ結果のランダムサンプルを返すことができます。

この機能を使用するには、クエリを実行するときに `sampleSize` オプションを渡し、Cloud Save が返す結果の最大数を指定します。

プレイヤーが参加できるギルドのリストを表示したり、同じような統計値の 2 人のプレイヤーをランダムに対戦させたりといったユースケースにサンプリングを使用できます。

## 制限##limits

### クエリの制限##limits-on-queries

クライアントまたはサーバーからクエリを実行できるデータは、インデックス化されたキーの **アクセスクラス** によって定義されます。

* ゲームクライアントは、**Cloud Save SDK for Unity** を使用して、[公開アクセスクラスのプレイヤーデータに対してクエリを実行](/cloud-save/tutorials/unity-sdk.md#query-player-data) したり、[デフォルトアクセスクラスで保存されているゲームデータに対してクエリを実行](/cloud-save/tutorials/unity-sdk.md#query-custom-items) したりできます。

* [Cloud Code 向け Cloud Save SDK](https://cloud-code-sdk-documentation.cloud.unity3d.com/cloud-save/) を使用するか、CLI または Admin REST API を使用することで、任意のアクセスクラス (**デフォルト**、**公開**、**非公開**、**保護済み** など) のインデックス化されたキーに対してクエリを実行できます。

### インデックスの制限##limits-on-indexes

* インデックス化できる値の最大サイズは 128 バイトです。

  128 バイトを超える値はインデックス化されません。128 バイトを超える値をインデックス化されたキーに書き込もうとすると、失敗します (データは Cloud Save に保存されますが、インデックス化されません)。
* 最大 20 個のキーを定義可能で、すべてのインデックス、すべてのアクセスクラス、プレイヤー状態およびゲーム状態にわたってキーをインデックス化できます。

  つまり、インデックス化されたキーの合計数が制限を超えない限り、インデックス化されたキー 1 個を含む最大 20 個のインデックス、キー 20 個を含む 1 つのインデックス、あるいはその中間の任意の組み合わせを持つことができます。

> **Important:**
>
> **重要**: クエリを実行できるのは、インデックスを作成した後に保存したデータのみです。クエリの応答には、インデックス作成前に保存したデータは含まれません。

## 追加リソース##additional-resources

* [Unity Dashboard での Cloud Save](https://cloud.unity.com/home/organizations/default/projects/default/environments/default/cloud-save/indexes)
* [Unity SDK を使用したプレイヤーデータのクエリ](/cloud-save/tutorials/unity-sdk.md#query-player-data)
* [Unity SDK を使用したカスタム項目のクエリ](/cloud-save/tutorials/unity-sdk.md#query-custom-items)
* [Cloud Code 向け Cloud Save SDK](https://cloud-code-sdk-documentation.cloud.unity3d.com/cloud-save/)
* [Cloud Save REST API](https://services.docs.unity.com/cloud-save/v1/index.html#section/Introduction)
* [Cloud Save Admin REST API](https://services.docs.unity.com/cloud-save-admin/v1/index.html#section/Introduction)