# 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/), 또는 [관리자 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가 반환할 최대 결과 수를 지정해야 합니다.

샘플링은 플레이어가 가입할 수 있는 길드 목록을 표시하거나, 유사한 통계를 가진 두 플레이어를 무작위로 매칭하는 등의 사용 사례에 활용할 수 있습니다.

## 제한 사항##limits

### 쿼리 제한 사항##limits-on-queries

클라이언트나 서버에서 쿼리할 수 있는 데이터는 인덱싱된 키의 **액세스 클래스**에 의해 정의됩니다.

* **Unity용 Cloud Save SDK**를 사용하면, 게임 클라이언트는 [공개 액세스 클래스에서 플레이어 데이터를 쿼리](/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 또는 관리자 REST API를 사용하면 어떤 액세스 클래스(예: **기본**, **공개**, **비공개**, **보호**)에서든 인덱싱된 키를 쿼리할 수 있습니다.

### 인덱스 제한 사항##limits-on-indexes

* 인덱싱할 수 있는 값의 최대 크기는 128바이트입니다.

  128바이트보다 큰 값은 인덱싱되지 않으며, 128바이트보다 큰 값을 인덱싱된 키에 쓰려고 시도하면 인덱스가 실패합니다(데이터는 여전히 Cloud Save에 저장되지만 인덱싱되지 않음).
* 모든 인덱스와 모든 액세스 클래스, 플레이어 상태, 게임 상태에서 인덱싱할 수 있는 키를 최대 20개까지 정의할 수 있습니다.

  즉, 단일 인덱스 키로 최대 20개의 인덱스나 20개의 키가 포함된 단일 인덱스가 있을 수 있고, 전체 인덱스 키 개수가 제한을 초과하지 않으면 그 사이에 어떠한 조합이라도 있을 수 있음을 의미합니다.

> **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 관리자 REST API](https://services.docs.unity.com/cloud-save-admin/v1/index.html#section/Introduction)