Datastore 쿼리는 지정한 조건 집합을 충족하는 항목을 Cloud Datastore에서 검색합니다.
일반적인 쿼리에는 다음이 포함됩니다.
쿼리가 실행되면 지정된 순서대로 정렬된 지정한 모든 필터를 만족하는 지정한 종류의 모든 항목을 검색합니다. 쿼리는 읽기 전용으로 실행됩니다.이 페이지에서는 App Engine 내에서 Cloud Datastore로부터 데이터를 검색하는 데 사용되는 쿼리의 구조와 종류를 설명합니다.
필터
쿼리 필터는 검색할 항목의 속성, 키, 상위에 대한 제약 조건을 설정합니다.
속성 필터
속성 필터는 다음을 지정합니다.
- 속성 이름
- 비교 연산자
- 속성 값
속성 값은 애플리케이션에서 제공해야 합니다. 속성 값은 다른 속성을 참조하거나 그와 관련하여 계산될 수 없습니다. 비교 연산자로 설명된 방식에 따라 필터에 지정된 값과 해당 값이 비교되는 지정된 이름의 속성이 있으면 항목이 필터를 만족합니다.
비교 연산자는 다음 중 하나일 수 있으며
Query.FilterOperator
중첩 클래스의 열거형 상수로 정의됩니다.
연산자 | 의미 |
---|---|
EQUAL |
같음 |
LESS_THAN |
미만 |
LESS_THAN_OR_EQUAL |
이하 |
GREATER_THAN |
초과 |
GREATER_THAN_OR_EQUAL |
이상 |
NOT_EQUAL |
같지 않음 |
IN |
구성원 관계(지정된 목록의 값 중 하나라도 일치) |
NOT_EQUAL
연산자는 실제로 쿼리 두 개를 수행합니다. 다른 모든 필터를 변경하지 않고 NOT_EQUAL
필터를 LESS_THAN
필터로 바꾸는 쿼리 하나와 GREATER_THAN
필터로 바꾸는 쿼리 하나입니다. 그런 다음 결과를 순서대로 병합합니다. 한 쿼리에 NOT_EQUAL
필터가 두 개 이상 있을 수 없으며, 이 필터가 있는 쿼리에는 다른 같지 않음 필터가 있을 수 없습니다.
IN
연산자도 여러 쿼리를 수행합니다. 지정된 목록의 항목마다 쿼리가 한 개씩 실행되며 다른 모든 필터를 변경하지 않고 IN
필터를 EQUAL
필터로 바꿉니다. 결과는 목록에 있는 항목의 순서대로 병합됩니다. 한 쿼리에 IN
필터가 한 개 넘게 있으면 IN
목록의 가능한 값 조합마다 하나씩 여러 개의 쿼리로 수행됩니다.
NOT_EQUAL
또는 IN
연산자가 포함된 단일 쿼리는 최대 30개의 서브 쿼리로 제한됩니다.
JDO/JPA 프레임워크에서 NOT_EQUAL
및 IN
쿼리가 여러 쿼리로 변환되는 방법에 대한 자세한 내용은 Queries with != and IN filters를 참조하세요.
키 필터
항목 키의 값을 필터링하려면 특수 속성 Entity.KEY_RESERVED_PROPERTY
를 사용하세요.
Entity.KEY_RESERVED_PROPERTY
에 대한 오름차순 정렬도 지원됩니다.
비균등 비교 시 다음 순서의 기준에 따라 키가 정렬됩니다.
- 상위 경로
- 항목 종류
- 식별자(키 이름 또는 숫자 ID)
마찬가지로 상위 경로의 요소도 종류(문자열)에 이어 키 이름 또는 숫자 ID로 비교됩니다. 종류와 키 이름은 문자열이며 바이트 값으로 정렬되고, 숫자 ID는 정수이며 숫자로 정렬됩니다. 상위 요소 및 종류가 동일한 항목에 키 이름 문자열과 숫자 ID를 함께 사용하면 숫자 ID가 있는 항목이 키 이름이 있는 항목보다 앞에 옵니다.
키를 대상으로 하는 쿼리는 속성을 대상으로 하는 쿼리와 마찬가지로 색인을 사용하며 동일한 경우에 커스텀 색인이 필요합니다. 단, 일부 예외로 키의 비균등 필터 또는 오름차순 정렬 순서에는 커스텀 색인이 필요하지 않지만 키의 내림차순 정렬 순서에는 커스텀 색인이 필요합니다. 모든 쿼리와 마찬가지로, 커스텀 색인이 필요한 쿼리를 테스트하면 개발용 웹 서버가 색인 구성 파일에 적절한 항목을 만듭니다.
상위 필터
Datastore 쿼리를 지정한 상위 항목으로 필터링하여, 반환되는 결과에 해당 상위 항목의 하위 항목만 포함되도록 할 수 있습니다.
특수 쿼리 유형
특정 유형의 쿼리가 몇 가지 있습니다.
비구분 쿼리
종류 및 상위 항목 필터가 없는 쿼리는 Datastore에서 애플리케이션의 모든 항목을 검색합니다. 여기에는 다른 App Engine 기능에서 생성되고 관리되는 통계 항목, Blobstore 메타데이터 항목 등의 항목(있는 경우)이 포함됩니다. 이러한 비구분 쿼리는 속성 값에 대한 필터나 정렬 순서를 포함할 수 없습니다. 하지만 Entity.KEY_RESERVED_PROPERTY
을 속성 이름으로 지정하여 항목 키를 필터링할 수 있습니다.
상위 쿼리
상위 항목 필터가 있는 쿼리는 지정한 항목과 하위 항목으로 결과를 제한합니다.
비구분 상위 쿼리
상위 항목 필터를 포함하는 비구분 쿼리는 지정한 상위 항목과 모든 해당 하위 항목을 종류에 관계없이 검색합니다. 이러한 유형의 쿼리에는 커스텀 색인이 필요하지 않습니다. 다른 모든 비구분 쿼리와 같이 속성 값에 대한 필터 또는 정렬 순서가 포함될 수 없지만 항목의 키를 기준으로 필터링될 수 있습니다.
다음 예는 지정된 상위 항목의 모든 하위 항목을 검색하는 방법을 보여 줍니다.
키 전용 쿼리
키 전용 쿼리는 항목 자체가 아니라 결과 항목의 키만 반환하므로, 전체 항목을 검색할 때보다 지연 시간이 적고 비용이 낮습니다.
실제로 필요한 것보다 많은 항목을 가져올 수 있는 일반 쿼리를 실행하는 대신 키 전용 쿼리를 먼저 실행한 후 결과에서 항목의 하위 집합을 가져오는 것이 더 경제적인 경우가 종종 있습니다.
프로젝션 쿼리
쿼리 결과 중에 몇 가지 특정한 속성의 값만 필요한 경우가 있습니다. 이러한 경우 프로젝션 쿼리를 사용하면 실제로 필요한 속성만 검색하여 전체 항목을 검색할 때보다 지연 시간과 비용을 줄일 수 있습니다. 자세한 내용은 프로젝션 쿼리 페이지를 참조하세요.
정렬 순서
쿼리 정렬 순서는 다음을 지정합니다.
- 속성 이름
- 정렬 방향(오름차순 또는 내림차순)
예를 들면 다음과 같습니다.
쿼리에 정렬 순서가 여러 개 있으면 지정한 순서대로 적용됩니다. 다음 예시에서는 먼저 성을 기준으로 오름차순으로 정렬한 다음 키를 기준으로 내림차순으로 정렬합니다.
정렬 순서가 지정되지 않으면 결과는 Datastore에서 검색된 순서대로 반환됩니다.
참고: 쿼리에 속성에 대한 불일치 필터와 다른 속성에 대한 정렬 순서가 지정되어 있으면 Datastore의 쿼리 실행 방식으로 인해 불일치 필터에 사용된 속성이 다른 속성보다 먼저 정렬되어야 합니다.
색인
모든 Datastore 쿼리는 색인의 속성에 지정된 순서대로 항목 키와 항목의 선택적 상위를 포함하는 색인을 한 개 이상 사용하여 결과를 계산합니다. 색인은 애플리케이션이 해당 항목을 대상으로 수행하는 모든 변경 내용을 반영하도록 증분 방식으로 업데이트되므로 추가 계산 없이도 모든 쿼리의 결과가 올바르게 제공됩니다.
App Engine은 항목의 각 속성에 대한 간단한 색인을 사전 정의합니다.
App Engine 애플리케이션은 애플리케이션의 /war/WEB-INF/appengine-generated
디렉터리에서 생성된 datastore-indexes.xml
라는 색인 구성 파일에서 커스텀 색인을 추가로 정의합니다. 개발 서버는 기존 색인으로 실행할 수 없는 쿼리를 발견하면 이 파일에 자동으로 제안 항목을 추가합니다.
애플리케이션을 업로드하기 전에 이 파일을 수정하여 색인을 수동으로 미세 조정할 수 있습니다.
쿼리 인터페이스 예시
하위 수준 자바 Datastore API는 쿼리 구성을 위한 클래스 Query
클래스 및 Datastore에서 항목을 검색하는 PreparedQuery
인터페이스를 제공합니다.
FilterPredicate
및 CompositeFilter
를 사용하여 필터를 생성한다는 점에 유의하세요. 쿼리에 필터를 하나만 설정하는 경우에는 FilterPredicate
만 사용해도 됩니다.
그러나 쿼리에 필터를 두 개 이상 설정하려는 경우에는 최소한 두 개 이상의 필터가 필요한 CompositeFilter
를 사용해야 합니다. 위의 예시에서는 단축 도우미 CompositeFilterOperator.and
를 사용하며, 다음 예시에서는 복합 OR 필터를 구성하는 방법 중 하나를 보여줍니다.
다음 단계
- 쿼리가 반환하는 대상을 지정하고 쿼리 결과를 자세히 제어하는 방법 알아보기
- Cloud Datastore의 쿼리에 대한 일반적인 제한사항 알아보기
- 애플리케이션에서 편리하게 일괄적으로 쿼리 결과를 검색할 수 있게 해주는 쿼리 커서 알아보기
- 데이터 일관성 및 Cloud Datastore의 다양한 쿼리 유형에서 데이터 일관성이 유지되는 방식 이해하기