참고: Python 2.7은 2024년 1월 31일 지원 종료됩니다. 기존 Python 2.7 애플리케이션을 계속 실행하고 트래픽을 받을 수 있습니다. 그러나 지원 종료 날짜 이후에는 해당 런타임을 사용하는 애플리케이션의 재배포를 App Engine에서 차단할 수 있습니다. 지원되는 최신 Python 버전으로 마이그레이션하는 것이 좋습니다.

Datastore 쿼리

참고: 새로운 애플리케이션을 빌드하는 개발자는 NDB 클라이언트 라이브러리를 사용하는 것이 좋습니다. NDB 클라이언트 라이브러리는 이 클라이언트 라이브러리와 비교할 때 Memcache API를 통한 자동 항목 캐싱과 같은 여러 이점이 있습니다. 현재 이전 DB 클라이언트 라이브러리를 사용 중인 경우 DB에서 NDB로의 마이그레이션 가이드를 참조하세요.

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

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

쿼리가 적용되는 항목 종류
항목의 속성 값, 키, 상위를 기준으로 하는 선택적 필터
결과를 순차적으로 배열할 선택적 정렬 순서

쿼리가 실행되면 지정된 순서대로 정렬된 지정한 모든 필터를 만족하는 지정한 종류의 모든 항목을 검색합니다. 쿼리는 읽기 전용으로 실행됩니다.

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

필터

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

속성 필터

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

속성 이름
비교 연산자
속성 값

예를 들면 다음과 같습니다.

q = Person.all()
q.filter("height <=", max_height)

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

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

연산자	의미
`=`	같음
`<`	미만
`<=`	이하
`>`	초과
`>=`	이상
`!=`	같지 않음
`IN`	구성원 관계(지정된 목록의 값 중 하나라도 일치)

같지 않음(!=) 연산자는 실제로는 쿼리 두 개를 수행합니다. 즉, 다른 모든 필터는 변경되지 않고 같지 않음 필터가 보다 작음(<) 필터로 대체되는 쿼리 하나와, 보다 큼(>) 필터로 대체되는 쿼리 하나가 수행됩니다. 그런 다음 결과를 순서대로 병합합니다. 하나의 쿼리에 같지 않음 필터가 두 개 이상 있을 수 없으며, 이 필터가 있는 쿼리에는 다른 같지 않음 필터가 존재할 수 없습니다.

IN 연산자도 여러 쿼리를 수행합니다. 지정된 목록의 항목마다 쿼리가 한 개씩 실행되며 다른 모든 필터를 변경하지 않고 IN 필터를 같음(=) 필터로 바꿉니다. 결과는 목록에 있는 항목의 순서대로 병합됩니다. 한 쿼리에 IN 필터가 두 개 이상 있으면 IN 목록의 가능한 값 조합마다 하나씩 여러 개의 쿼리로 수행됩니다.

같지 않음(!=) 또는 IN 연산자가 포함된 단일 쿼리에서는 하위 쿼리가 최대 30개로 제한됩니다.

키 필터

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

q = Person.all()
q.filter('__key__ >', last_seen_key)

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

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

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

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

상위 필터

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

q = Person.all()
q.ancestor(ancestor_key)

특수 쿼리 유형

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

비구분 쿼리

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

q = db.Query()
q.filter('__key__ >', last_seen_key)

Python에서 쿼리에 의해 반환되는 모든 항목에는 항목의 종류에 정의된 해당 모델 클래스가 있어야 합니다. 통계 항목 종류의 모델 클래스를 정의하려면 stats 패키지를 가져와야 합니다.

from google.appengine.ext.db import stats

애플리케이션에 Blobstore 값이 있으면 다음 코드를 추가하여 __BlobInfo__ 항목 종류가 인식되도록 쿼리 API를 가져와야 합니다. Blobstore API 가져오기로는 이 클래스가 정의되지 않습니다.

from google.appengine.ext import db

class BlobInfo(db.Expando):
  @classmethod
  def kind(cls):
    return '__BlobInfo__'

상위 쿼리

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

tom = Person(key_name='Tom')

wedding_photo = Photo(parent=tom)
wedding_photo.image_url='http://domain.com/some/path/to/wedding_photo.jpg'
wedding_photo.put()

baby_photo = Photo(parent=tom)
baby_photo.image_url='http://domain.com/some/path/to/baby_photo.jpg'
baby_photo.put()

dance_photo = Photo(parent=tom)
dance_photo.image_url='http://domain.com/some/path/to/dance_photo.jpg'
dance_photo.put()

camping_photo = Photo()
camping_photo.image_url='http://domain.com/some/path/to/camping_photo.jpg'
camping_photo.put()


photo_query = Photo.all()
photo_query.ancestor(tom)


# This returns wedding_photo, baby_photo, and dance_photo,
# but not camping_photo, because tom is not an ancestor
for photo in photo_query.run(limit=5):
  # Do something with photo

비구분 상위 쿼리

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

q = db.Query()
q.ancestor(ancestor_key)
q.filter('__key__ >', last_seen_key)

GQL을 사용하여 비구분 상위 쿼리를 수행하려면 App Engine 관리 콘솔에서 또는 GqlQuery 클래스를 사용하여 FROM 절을 생략합니다.

q = db.GqlQuery('SELECT * WHERE ANCESTOR IS :1 AND __key__ > :2',
                ancestor_key,
                last_seen_key)

다음 예시에서는 특정 상위 항목의 모든 하위 항목을 검색하는 방법을 보여줍니다.

tom = Person(key_name='Tom')

wedding_photo = Photo(parent=tom)
wedding_photo.image_url='http://domain.com/some/path/to/wedding_photo.jpg'
wedding_photo.put()

wedding_video = Video(parent=tom)
wedding_video.video_url='http://domain.com/some/path/to/wedding_video.avi'
wedding_video.put()

# The following query returns both weddingPhoto and weddingVideo,
# even though they are of different entity kinds
media_query = db.query_descendants(tom)
for media in media_query.run(limit=5):
  # Do something with media

키 전용 쿼리

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

q = Person.all(keys_only=True)

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

프로젝션 쿼리

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

정렬 순서

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

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

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

# Order alphabetically by last name:
q = Person.all()
q.order('last_name')

# Order by height, tallest to shortest:
q = Person.all()
q.order('-height')

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

q = Person.all()
q.order('lastName')
q.order('-height')

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

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

색인

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

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

쿼리 인터페이스 예시

Python Datastore API는 쿼리 준비 및 실행을 위한 두 가지 클래스를 제공합니다.

Query는 메서드 호출을 사용하여 쿼리를 준비합니다.
GqlQuery는 SQL과 유사한 GQL이라는 쿼리 언어를 사용하여 쿼리 문자열에서 쿼리를 준비합니다.

class Person(db.Model):
  first_name = db.StringProperty()
  last_name = db.StringProperty()
  city = db.StringProperty()
  birth_year = db.IntegerProperty()
  height = db.IntegerProperty()


# Query interface constructs a query using instance methods
q = Person.all()
q.filter("last_name =", "Smith")
q.filter("height <=", max_height)
q.order("-height")


# GqlQuery interface constructs a query using a GQL query string
q = db.GqlQuery("SELECT * FROM Person " +
                "WHERE last_name = :1 AND height <= :2 " +
                "ORDER BY height DESC",
                "Smith", max_height)


# Query is not executed until results are accessed
for p in q.run(limit=5):
  print "%s %s, %d inches tall" % (p.first_name, p.last_name, p.height)

다음 단계

쿼리가 반환하는 대상을 지정하고 쿼리 결과를 자세히 제어하는 방법 알아보기
Cloud Datastore의 쿼리에 대한 일반적인 제한사항 알아보기
애플리케이션에서 편리하게 일괄적으로 쿼리 결과를 검색할 수 있게 해주는 쿼리 커서 알아보기
데이터 일관성 및 Cloud Datastore의 다양한 쿼리 유형에서 데이터 일관성이 유지되는 방식 이해하기