Datastore 쿼리

Datastore 쿼리는 지정한 조건 조합에 맞는 항목을 Cloud Datastore에서 검색합니다.

일반적인 쿼리에는 다음이 포함됩니다.

  • 쿼리가 적용되는 항목 종류
  • 항목의 속성 값, 키, 상위를 기준으로 하는 선택적 필터
  • 결과를 순차적으로 배열할 선택적 정렬 순서
쿼리가 실행되면 지정된 순서대로 정렬된 지정한 모든 필터를 만족하는 지정한 종류의 모든 항목을 검색합니다. 쿼리는 읽기 전용으로 실행됩니다.

이 페이지에서는 App Engine 내에서 Cloud Datastore로부터 데이터를 검색하는 데 사용되는 쿼리의 구조와 종류를 설명합니다.

필터

쿼리 필터는 검색할 항목의 속성, 키, 상위에 대한 제약 조건을 설정합니다.

속성 필터

속성 필터는 다음을 지정합니다.

  • 속성 이름
  • 비교 연산자
  • 속성 값
예를 들면 다음과 같습니다.

q := datastore.NewQuery("Person").Filter("Height <=", maxHeight)

속성 값은 애플리케이션에서 제공해야 합니다. 속성 값은 다른 속성을 참조하거나 그와 관련하여 계산될 수 없습니다. 비교 연산자로 설명된 방식에 따라 필터에 지정된 값과 해당 값이 비교되는 지정된 이름의 속성이 있으면 항목이 필터를 만족합니다.

비교 연산자는 다음 중 하나일 수 있습니다.

연산자 의미
= 같음
< 미만
<= 이하
> 초과
>= 이상

키 필터

항목 키의 값을 필터링하려면 특수 속성 __key__를 사용하세요.

q := datastore.NewQuery("Person").Filter("__key__ >", lastSeenKey)

비균등 비교 시 다음 순서의 기준에 따라 키가 정렬됩니다.

  1. 상위 경로
  2. 항목 종류
  3. 식별자(키 이름 또는 숫자 ID)

마찬가지로 상위 경로의 요소도 종류(문자열)에 이어 키 이름 또는 숫자 ID로 비교됩니다. 종류와 키 이름은 문자열이며 바이트 값으로 정렬되고, 숫자 ID는 정수이며 숫자로 정렬됩니다. 상위 요소 및 종류가 동일한 항목에 키 이름 문자열과 숫자 ID를 함께 사용하면 숫자 ID가 있는 항목이 키 이름이 있는 항목보다 앞에 옵니다.

키를 대상으로 하는 쿼리는 속성을 대상으로 하는 쿼리와 마찬가지로 색인을 사용하며 동일한 경우에 커스텀 색인이 필요합니다. 단, 일부 예외로 키의 비균등 필터 또는 오름차순 정렬 순서에는 커스텀 색인이 필요하지 않지만 키의 내림차순 정렬 순서에는 커스텀 색인이 필요합니다. 다른 모든 쿼리와 마찬가지로, 커스텀 색인이 필요한 쿼리를 테스트하면 개발용 웹 서버는 색인 구성 파일에 적절한 항목을 만듭니다.

상위 필터

Datastore 쿼리를 지정한 상위 항목으로 필터링하여 반환되는 결과에 이 상위 항목의 하위 항목만 포함할 수 있습니다.

q := datastore.NewQuery("Person").Ancestor(ancestorKey)

특수 쿼리 유형

특정 유형의 쿼리가 몇 가지 있습니다.

비구분 쿼리

종류 및 상위 항목 필터가 없는 쿼리는 Datastore에서 애플리케이션의 모든 항목을 검색합니다. 여기에는 다른 App Engine 기능에서 생성되고 관리되는 통계 항목, Blobstore 메타데이터 항목 등의 항목(있는 경우)이 포함됩니다. 이러한 비구분 쿼리는 속성 값에 대한 필터나 정렬 순서를 포함할 수 없습니다. 하지만 __key__를 속성 이름으로 지정하여 항목 키를 필터링할 수 있습니다.

q := datastore.NewQuery("").Filter("__key__ >", lastSeenKey)

상위 쿼리

상위 필터를 갖는 쿼리는 지정한 항목과 하위 항목으로 결과를 제한합니다.

// Create two Photo entities in the datastore with a Person as their ancestor.
tomKey := datastore.NewKey(ctx, "Person", "Tom", 0, nil)

wPhoto := Photo{URL: "http://example.com/some/path/to/wedding_photo.jpg"}
wKey := datastore.NewKey(ctx, "Photo", "", 0, tomKey)
_, err := datastore.Put(ctx, wKey, wPhoto)
// check err

bPhoto := Photo{URL: "http://example.com/some/path/to/baby_photo.jpg"}
bKey := datastore.NewKey(ctx, "Photo", "", 0, tomKey)
_, err = datastore.Put(ctx, bKey, bPhoto)
// check err

// Now fetch all Photos that have tomKey as an ancestor.
// This will populate the photos slice with wPhoto and bPhoto.
q := datastore.NewQuery("Photo").Ancestor(tomKey)
var photos []Photo
_, err = q.GetAll(ctx, &photos)
// check err
// do something with photos

비구분 상위 쿼리

상위 항목 필터를 포함하는 비구분 쿼리는 지정한 상위 항목과 모든 해당 하위 항목을 종류에 관계없이 검색합니다. 이러한 유형의 쿼리에는 커스텀 색인이 필요하지 않습니다. 다른 모든 비구분 쿼리와 같이 속성 값에 대한 필터 또는 정렬 순서가 포함될 수 없지만 항목의 키를 기준으로 필터링될 수 있습니다.

q := datastore.NewQuery("").Ancestor(ancestorKey).Filter("__key__ >", lastSeenKey)

다음 예는 지정된 상위 항목의 모든 하위 항목을 검색하는 방법을 보여 줍니다.

tomKey := datastore.NewKey(ctx, "Person", "Tom", 0, nil)

weddingPhoto := &Photo{URL: "http://example.com/some/path/to/wedding_photo.jpg"}
_, err := datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Photo", tomKey), weddingPhoto)

weddingVideo := &Video{URL: "http://example.com/some/path/to/wedding_video.avi"}
_, err = datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Video", tomKey), weddingVideo)

// The following query returns both weddingPhoto and weddingVideo,
// even though they are of different entity kinds.
q := datastore.NewQuery("").Ancestor(tomKey)
t := q.Run(ctx)
for {
	var x interface{}
	_, err := t.Next(&x)
	if err == datastore.Done {
		break
	}
	if err != nil {
		log.Errorf(ctx, "fetching next Photo/Video: %v", err)
		break
	}
	// Do something (e.g. switch on types)
	doSomething(x)
}

키 전용 쿼리

키 전용 쿼리는 항목 자체가 아니라 결과 항목의 키만 반환하므로, 전체 항목을 검색할 때보다 지연 시간이 적고 비용이 낮습니다.

q := datastore.NewQuery("Person").KeysOnly()

실제로 필요한 것보다 많은 항목을 가져올 수 있는 일반 쿼리 실행 대신에 키 전용 쿼리를 먼저 실행한 후 결과에서 항목 하위 집합을 가져오는 것이 더 경제적인 경우가 종종 있습니다.

키 전용 쿼리는 1,000개가 넘는 결과를 반환할 수 있지만 GetAll은 한 번에 1,000개의 키만 검색할 수 있으며 더 많은 결과에서 호출하면 오류가 발생합니다. 따라서 쿼리에 키 1,000개 제한을 추가하는 것이 좋습니다.

프로젝션 쿼리

쿼리 결과 중에 몇 가지 특정한 속성의 값만 필요한 경우가 있습니다. 이러한 경우 프로젝션 쿼리를 사용하면 실제로 필요한 속성만 검색하여 전체 항목을 검색할 때보다 지연 시간과 비용을 줄일 수 있습니다. 자세한 내용은 프로젝션 쿼리 페이지를 참조하세요.

정렬 순서

쿼리 정렬 순서는 다음을 지정합니다.

  • 속성 이름
  • 정렬 방향(오름차순 또는 내림차순)

Go에서 내림차순 정렬 순서는 속성 이름 앞에 하이픈(-)이 표시됩니다. 하이픈을 생략하면 기본적으로 오름차순으로 지정됩니다. 예를 들면 다음과 같습니다.

// Order alphabetically by last name:
q := datastore.NewQuery("Person").Order("LastName")

// Order by height, tallest to shortest:
q = datastore.NewQuery("Person").Order("-Height")

쿼리에 정렬 순서가 여러 개 있으면 지정한 순서대로 적용됩니다. 다음 예시에서는 먼저 성을 기준으로 오름차순으로 정렬한 다음 키를 기준으로 내림차순으로 정렬합니다.

q := datastore.NewQuery("Person").Order("LastName").Order("-Height")

정렬 순서가 지정되지 않으면 결과는 Datastore에서 검색된 순서대로 반환됩니다.

참고: 쿼리에 속성에 대한 불일치 필터와 다른 속성에 대한 정렬 순서가 지정되어 있으면 Datastore의 쿼리 실행 방식으로 인해 불일치 필터에 사용된 속성이 다른 속성보다 먼저 정렬되어야 합니다.

색인

모든 Datastore 쿼리는 색인의 속성에 지정된 순서대로 항목 키와 항목의 상위 항목(선택사항)을 포함하는 색인을 1개 이상 사용하여 결과를 계산합니다. 색인은 애플리케이션이 해당 항목을 대상으로 수행하는 모든 변경 내용을 반영하도록 증분 방식으로 업데이트되므로 추가 계산 없이도 모든 쿼리의 결과가 올바르게 제공됩니다.

App Engine은 항목의 각 속성에 대한 간단한 색인을 사전 정의합니다. App Engine 애플리케이션은 index.yaml이라는 색인 구성 파일에서 커스텀 색인을 추가로 정의할 수 있습니다. 개발 서버는 기존 색인으로 실행할 수 없는 쿼리를 발견하면 이 파일에 자동으로 제안 항목을 추가합니다. 애플리케이션을 업로드하기 전에 이 파일을 수정하여 색인을 수동으로 미세 조정할 수 있습니다.

쿼리 인터페이스 예시

Go Datastore API는 쿼리 준비와 실행을 위한 쿼리 유형을 제공합니다.

type Person struct {
	FirstName string
	LastName  string
	City      string
	BirthYear int
	Height    int
}

func handle(w http.ResponseWriter, r *http.Request) {
	ctx := appengine.NewContext(r)

	// The Query type and its methods are used to construct a query.
	q := datastore.NewQuery("Person").
		Filter("LastName =", "Smith").
		Filter("Height <=", maxHeight).
		Order("-Height")

	// To retrieve the results,
	// you must execute the Query using its GetAll or Run methods.
	var people []Person
	if _, err := q.GetAll(ctx, &people); err != nil {
		// Handle error.
	}
	// ...
}

다음 단계