쿼리 클래스

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

Query 클래스는 App Engine Datastore에서 항목을 검색하는 데 사용되는 쿼리를 나타냅니다. SQL과 유사한 쿼리 언어인 GQL을 사용하여 쿼리를 정의하는 관련 GqlQuery 클래스도 참조하세요.

Query은 모듈 google.appengine.ext.db에 정의됩니다.

참고: 색인 기준 쿼리 메커니즘은 다양한 쿼리를 지원하고 대부분의 애플리케이션에 적합하지만 다른 데이터베이스 기술에서 일반적으로 사용되는 몇몇 종류의 쿼리는 지원하지 않습니다. 특히 조인 및 집계 쿼리는 Datastore 쿼리 엔진에서 지원되지 않습니다. Datastore 쿼리의 제한사항은 Datastore 쿼리 페이지를 참조하세요.

소개

애플리케이션에서 특정 항목 종류의 쿼리 객체를 만들려면 Query 생성자를 직접 호출합니다.

class Song(db.Model):
  title = db.StringProperty()
  composer = db.StringProperty()
  date = db.DateTimeProperty()

q = db.Query(Song)

또는 종류의 모델 클래스에 대한 클래스 메서드 all()을 호출합니다.

q = Song.all()

Query 클래스의 결과 인스턴스는 추가 수정 없이 지정된 종류의 기존 항목을 모두 가져옵니다. 그런 다음 객체에서 메소드 호출을 사용하여 추가 필터 기준, 상위 조건, 정렬 순서와 함께 쿼리를 맞춤설정할 수 있습니다.

q.filter('title =', 'Imagine')
q.ancestor(ancestor_key)
q.order('-date')

편의를 위해 모든 메소드는 단일 구문에서 하위로 전파될 수 있도록 쿼리 객체 자체를 반환합니다.

q.filter('title =', 'Imagine').ancestor(key).order('-date')

그러면 애플리케이션은 다음 방법 중 한 가지를 사용하여 쿼리를 실행하고 결과에 액세스할 수 있습니다.

  • 쿼리 객체를 반복 가능한 것으로 취급하여 일치하는 항목을 한 번에 하나씩 처리합니다.

    for song in q:
  print song.title

    이는 암시적으로 쿼리의 run() 메서드를 호출하여 일치하는 항목을 생성하며, 따라서 다음과 동일합니다.

    for song in q.run():
  print song.title

    키워드 인수 limit으로 처리할 수 있는 결과 수에 한도를 설정할 수 있습니다.

    for song in q.run(limit=5):
  print song.title

    반복자 인터페이스는 결과를 캐시하지 않으므로 쿼리 객체에서 새로운 반복자를 만들면 동일한 쿼리가 처음부터 반복됩니다.

  • Datastore에서 찾은 첫 번째 단일 일치 항목을 가져오려면 쿼리의 get() 메서드를 호출합니다.

    song = q.get()
print song.title

  • 지정된 결과 수만큼 일치하는 모든 항목의 목록을 가져오려면 쿼리의 fetch() 메서드를 호출합니다.

    results = q.fetch(limit=5)
for song in results:
  print song.title

    run()과 마찬가지로 쿼리 객체는 결과를 캐시하지 않으므로 fetch()를 두 번째 호출하면 동일한 쿼리가 다시 실행됩니다.

    참고: 이 메서드는 거의 사용할 필요가 없으며, 거의 모든 경우에 run()을 대신 사용하는 것이 좋습니다.

생성자

Query 클래스의 생성자는 다음과 같이 정의됩니다.

class Query(model_class=None, keys_only=False, cursor=None, namespace=None, projection=None, distinct=False)

App Engine Datastore에서 항목을 검색하는 데 사용할 Query 클래스의 인스턴스를 만듭니다.

결과 쿼리 객체는 추가 수정 없이 model_class에서 지정된 종류의 모든 기존 항목을 검색합니다. 그러면 인스턴스 메서드 filter(), ancestor(),, order()를 사용하여 추가 필터 기준, 상위 조건, 정렬 순서로 쿼리를 맞춤설정할 수 있습니다.

인수

model_class
쿼리가 적용하는 항목 종류를 나타내는 모델(또는 Expando) 클래스입니다.
keys_only
true인 경우 전체 항목 대신 키만 반환합니다. 키 전용 쿼리는 전체 항목을 반환하는 쿼리보다 빠르고 경제적입니다.
cursor
쿼리를 다시 시작할 커서 위치입니다.
namespace
쿼리에 사용할 네임스페이스입니다.
projection
반환할 속성 이름의 목록 또는 튜플입니다. 지정된 속성을 가진 항목만 반환되며, 지정되지 않은 경우 기본적으로 전체 항목이 반환됩니다. 프로젝션 쿼리는 전체 항목을 반환하는 쿼리보다 빠르고 경제적입니다.

참고: 이 매개변수를 지정하면 쿼리의 색인 요구사항이 변경될 수 있습니다.

distinct
프로젝션 쿼리의 경우 distinct=True를 설정하면 결과 집합에서 완전히 고유한 결과만 반환됩니다. 즉, 프로젝션되는 속성 값이 동일한 항목의 첫 번째 결과만 반환됩니다.
True
프로젝션에서 고유한 각 속성 값 세트에 대해 첫 번째 결과만 반환됩니다.
False
모든 결과가 반환됩니다.

인스턴스 메서드

Query 클래스의 인스턴스에는 다음과 같은 메서드가 있습니다.

filter(property_operator, value)

쿼리에 속성 필터를 추가합니다. 모든 필터를 충족하는 속성을 가진 항목만 반환됩니다.

인수

property_operator
속성 이름 및 선택적 비교 연산자(=, !=, <, <=, >, >=, IN)로 구성된 문자열로, 'age >'와 같이 공백으로 구분됩니다. 비교 연산자 없이 속성 이름만 지정하면 필터는 기본적으로 서로 균등(=)한지 비교합니다.
value
속성값과 비교할 값입니다. 예를 들면 다음과 같습니다.

q.filter('height >', 42).filter('city =', 'Seattle')
q.filter('user =', users.get_current_user())

지정된 비교 값과 비교할 속성 값의 값 유형이 동일해야 합니다.

ancestor(ancestor)

쿼리에 상위 필터를 추가합니다. 상위가 지정된 항목만 반환됩니다.

인수

ancestor
상위 항목 또는 키입니다.
order(property)

쿼리에 정렬 순서를 추가합니다. 정렬 순서가 둘 이상 추가되면 지정한 순서대로 적용됩니다.

인수

property
정렬의 기준이 되는 속성의 이름을 제공하는 문자열로, 필요한 경우 문자열 앞에 하이픈(-)을 사용하여 내림차순으로 지정할 수 있습니다. 하이픈을 생략하면 기본적으로 오름차순이 지정됩니다. 예를 들면 다음과 같습니다. 
# Order alphabetically by last name:
q.order('last_name')

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

프로젝션의 속성 튜플 또는 None을 반환합니다.

is_keys_only()

쿼리가 키 전용 쿼리인지 여부를 나타내는 부울 값을 반환합니다.

run (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=None, batch_size=20, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

쿼리 결과를 루프 처리하기 위한 반복 가능 항목을 반환합니다. 이를 통해 매개변수 설정으로 쿼리의 작업을 지정하고 결과에 반복적으로 액세스할 수 있습니다.

  1. offset 인수로 지정된 결과 수만큼 검색하고 삭제합니다.
  2. limit 인수로 지정된 최대 결과 수만큼 검색하고 반환합니다.

따라서 루프의 성능은 offset과 limit의 합계에 따라 선형적으로 확장됩니다. 검색하려는 결과 수를 알고 있다면 limit 값을 항상 명시적으로 설정해야 합니다.

이 메서드는 성능 향상을 위해 비동기식 프리페치를 사용합니다. 기본적으로 Datastore에서 소규모 배치로 결과를 검색하므로 애플리케이션이 반복을 중단하여 필요 이상으로 결과를 검색하지 않도록 할 수 있습니다.

팁: 결과 수를 모르는 경우 사용 가능한 모든 결과를 검색하려면 batch_size를 1000과 같이 큰 값으로 설정하세요.

팁: 기본 인수 값을 변경할 필요가 없으면 루프를 제어하기 위한 반복 가능 항목으로 쿼리 객체를 직접 사용하면 됩니다. 그러면 기본 인수를 사용하여 run()이 암시적으로 호출됩니다.

인수

read_policy
원하는 수준의 데이터 일관성을 지정하는 읽기 정책입니다.
STRONG_CONSISTENCY
최신 결과를 보장하지만 단일 항목 그룹으로 제한됩니다.
EVENTUAL_CONSISTENCY
여러 항목 그룹을 포괄할 수 있지만 경우에 따라 오래된 결과를 반환하는 경우가 있습니다. 일반적으로 최종 일관성을 지닌 쿼리는 강력한 일관성을 지닌 쿼리보다 더 빨리 실행되지만 아무것도 보장되지 않습니다.

참고: 상위가 아닌 전역 쿼리는 이 인수를 무시합니다.

deadline
오류가 발생하여 중단되기 전 Datastore에서 결과를 반환하기까지 기다리는 최대 시간(초)입니다. 정수 또는 부동 소수점 값을 허용합니다. 기본값(60초)보다 높게 설정할 수는 없지만 특정 작업이 빠르게 실패하도록 하기 위해 낮게 조정할 수는 있습니다(예: 사용자에게 응답을 더 빨리 반환, 작업 재시도, 다른 작업 시도, 작업 대기열에 작업 추가).
offset
첫 번째 결과를 반환하기 전에 건너뛸 결과 수입니다.
limit
반환할 최대 결과 수입니다. 생략하거나 None으로 설정하면 기본적으로 사용 가능한 모든 결과를 가져옵니다.
batch_size
배치당 검색을 시도할 결과 수입니다. limit를 설정하면 지정된 한도로 기본 설정됩니다. 그렇지 않으면 기본값은 20입니다.
keys_only
true인 경우 전체 항목 대신 키만 반환합니다. 키 전용 쿼리는 전체 항목을 반환하는 쿼리보다 빠르고 경제적입니다.
projection
반환할 속성 이름의 목록 또는 튜플입니다. 지정된 속성을 가진 항목만 반환되며, 지정되지 않은 경우 기본적으로 전체 항목이 반환됩니다. 프로젝션 쿼리는 전체 항목을 반환하는 쿼리보다 빠르고 경제적입니다.

참고: 이 매개변수를 지정하면 쿼리의 색인 요구사항이 변경될 수 있습니다.

start_cursor
쿼리를 시작할 커서 위치입니다.
end_cursor
쿼리를 종료할 커서 위치입니다.
get (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

쿼리를 실행하고 첫 번째 결과를 반환하거나, 결과가 없으면 None을 반환합니다.

인수

read_policy
원하는 수준의 데이터 일관성을 지정하는 읽기 정책입니다.
STRONG_CONSISTENCY
최신 결과를 보장하지만 단일 항목 그룹으로 제한됩니다.
EVENTUAL_CONSISTENCY
여러 항목 그룹을 포괄할 수 있지만 경우에 따라 오래된 결과를 반환하는 경우가 있습니다. 일반적으로 최종 일관성을 지닌 쿼리는 강력한 일관성을 지닌 쿼리보다 더 빨리 실행되지만 아무것도 보장되지 않습니다.

참고: 상위가 아닌 전역 쿼리는 이 인수를 무시합니다.

deadline
오류가 발생하여 중단되기 전 Datastore에서 결과를 반환하기까지 기다리는 최대 시간(초)입니다. 정수 또는 부동 소수점 값을 허용합니다. 기본값(60초)보다 높게 설정할 수는 없지만 특정 작업이 빠르게 실패하도록 하기 위해 낮게 조정할 수는 있습니다(예: 사용자에게 응답을 더 빨리 반환, 작업 재시도, 다른 작업 시도, 작업 대기열에 작업 추가).
offset
첫 번째 결과를 반환하기 전에 건너뛸 결과 수입니다.
keys_only
true인 경우 전체 항목 대신 키만 반환합니다. 키 전용 쿼리는 전체 항목을 반환하는 쿼리보다 빠르고 경제적입니다.
projection
반환할 속성 이름의 목록 또는 튜플입니다. 지정된 속성을 가진 항목만 반환되며, 지정되지 않은 경우 기본적으로 전체 항목이 반환됩니다. 프로젝션 쿼리는 전체 항목을 반환하는 쿼리보다 빠르고 경제적입니다.

참고: 이 매개변수를 지정하면 쿼리의 색인 요구사항이 변경될 수 있습니다.

start_cursor
쿼리를 시작할 커서 위치입니다.
end_cursor
쿼리를 종료할 커서 위치입니다.
fetch (limit, read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

쿼리를 실행하고 (비어 있을 수 있는) 결과 목록을 반환합니다.

  1. offset 인수로 지정된 결과 수만큼 검색하고 삭제합니다.
  2. limit 인수로 지정된 최대 결과 수만큼 검색하고 반환합니다.

따라서 메서드의 성능은 offset과 limit의 합계에 따라 선형적으로 확장됩니다.

참고: 이 메서드는 run() 메서드 주변의 씬 래퍼에 불과하며 run()을 직접 사용하는 것보다 효율성은 낮고 메모리는 더 많이 소모합니다. fetch()는 거의 사용할 필요가 없으며, 주로 쿼리 결과의 메모리 내 전체 목록을 검색해야 하는 경우 편의를 위해 제공됩니다.

팁: fetch() 메서드는 limit 인수로 지정된 결과 수만큼만 검색하도록 설계되었습니다. 결과 수를 모르는 경우 사용 가능한 모든 결과를 검색하려면 fetch() 대신 run()를 큰 값(예: run(batch_size=1000))으로 설정해 사용하세요.

인수

limit
반환할 최대 결과 수입니다. None으로 설정하면 사용 가능한 모든 결과가 검색됩니다.
read_policy
원하는 수준의 데이터 일관성을 지정하는 읽기 정책입니다.
STRONG_CONSISTENCY
최신 결과를 보장하지만 단일 항목 그룹으로 제한됩니다.
EVENTUAL_CONSISTENCY
여러 항목 그룹을 포괄할 수 있지만 경우에 따라 오래된 결과를 반환하는 경우가 있습니다. 일반적으로 최종 일관성을 지닌 쿼리는 강력한 일관성을 지닌 쿼리보다 더 빨리 실행되지만 아무것도 보장되지 않습니다.

참고: 상위가 아닌 전역 쿼리는 이 인수를 무시합니다.

deadline
오류가 발생하여 중단되기 전 Datastore에서 결과를 반환하기까지 기다리는 최대 시간(초)입니다. 정수 또는 부동 소수점 값을 허용합니다. 기본값(60초)보다 높게 설정할 수는 없지만 특정 작업이 빠르게 실패하도록 하기 위해 낮게 조정할 수는 있습니다(예: 사용자에게 응답을 더 빨리 반환, 작업 재시도, 다른 작업 시도, 작업 대기열에 작업 추가).
offset
첫 번째 결과를 반환하기 전에 건너뛸 결과 수입니다.
keys_only
true인 경우 전체 항목 대신 키만 반환합니다. 키 전용 쿼리는 전체 항목을 반환하는 쿼리보다 빠르고 경제적입니다.
projection
반환할 속성 이름의 목록 또는 튜플입니다. 지정된 속성을 가진 항목만 반환되며, 지정되지 않은 경우 기본적으로 전체 항목이 반환됩니다. 프로젝션 쿼리는 전체 항목을 반환하는 쿼리보다 빠르고 경제적입니다.

참고: 이 매개변수를 지정하면 쿼리의 색인 요구사항이 변경될 수 있습니다.

start_cursor
쿼리를 시작할 커서 위치입니다.
end_cursor
쿼리를 종료할 커서 위치입니다.
count (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=1000, start_cursor=None, end_cursor=None)

쿼리와 일치하는 결과의 개수를 반환합니다. 이는 모든 결과를 실제 검색하는 것보다 일정한 비율만큼 더 빠르지만 실행 시간은 여전히 offset과 limit의 합에 따라 선형적으로 확장됩니다. 결과 수가 작을 것으로 예상되는 경우를 제외하면 limit 인수를 지정하는 것이 가장 좋습니다. 그렇지 않으면 계수가 끝나거나 타임아웃될 때까지 메서드가 계속 실행됩니다.

인수

read_policy
원하는 수준의 데이터 일관성을 지정하는 읽기 정책입니다.
STRONG_CONSISTENCY
최신 결과를 보장하지만 단일 항목 그룹으로 제한됩니다.
EVENTUAL_CONSISTENCY
여러 항목 그룹을 포괄할 수 있지만 경우에 따라 오래된 결과를 반환하는 경우가 있습니다. 일반적으로 최종 일관성을 지닌 쿼리는 강력한 일관성을 지닌 쿼리보다 더 빨리 실행되지만 아무것도 보장되지 않습니다.

참고: 상위가 아닌 전역 쿼리는 이 인수를 무시합니다.

deadline
오류가 발생하여 중단되기 전 Datastore에서 결과를 반환하기까지 기다리는 최대 시간(초)입니다. 정수 또는 부동 소수점 값을 허용합니다. 기본값(60초)보다 높게 설정할 수는 없지만 특정 작업이 빠르게 실패하도록 하기 위해 낮게 조정할 수는 있습니다(예: 사용자에게 응답을 더 빨리 반환, 작업 재시도, 다른 작업 시도, 작업 대기열에 작업 추가).
offset
첫 번째 결과를 계수하기 전에 건너뛸 결과 수입니다.
limit
카운트할 최대 결과 수입니다.
start_cursor
쿼리를 시작할 커서 위치입니다.
end_cursor
쿼리를 종료할 커서 위치입니다.
index_list()

기본, 복합, 종류, 단일 속성 색인을 비롯하여 실행된 쿼리에서 사용되는 색인 목록을 반환합니다.

주의: 아직 실행되지 않은 쿼리에서 이 메서드를 호출하면 AssertionError 예외가 발생합니다.

참고: 이 기능은 개발 서버에서 완벽하게 지원되지 않습니다. 개발 서버에서 사용하는 경우 결과는 빈 목록이거나 정확히 하나의 복합 색인이 포함된 목록입니다.

예를 들어 다음 코드는 쿼리에서 사용하는 색인에 대해 다양한 정보를 인쇄합니다.

# other imports ...
import webapp2
from google.appengine.api import users
from google.appengine.ext import db

class Greeting(db.Model):
  author = db.StringProperty()
  content = db.StringProperty(multiline=True)
  date = db.DateTimeProperty(auto_now_add=True)

class MainPage(webapp2.RequestHandler):
  def get(self):
    user = users.get_current_user()
    q = db.Query(Greeting)
    q.filter("author =", user.user_id())
    q.order("-date")
    q.fetch(100)
    index_list = q.index_list()
    for ix in index_list:
      self.response.out.write("Kind: %s" % ix.kind())
      self.response.out.write("<br />")
      self.response.out.write("Has ancestor? %s" % ix.has_ancestor())
      self.response.out.write("<br />")
      for name, direction in ix.properties():
        self.response.out.write("Property name: "+name)
        self.response.out.write("<br />")
        if direction == db.Index.DESCENDING:
          self.response.out.write("Sort direction: DESCENDING")
        else:
          self.response.out.write("Sort direction: ASCENDING")
        self.response.out.write("<br />")

이는 각 색인에 대해 다음과 같은 내용을 출력합니다.

Kind: Greeting
Has ancestor? False
Property name: author
Sort direction: ASCENDING
Property name: date
Sort direction: DESCENDING
cursor()

검색된 마지막 결과 다음에 오는 쿼리 결과 집합의 위치를 나타내는 base64로 인코딩된 커서 문자열을 반환합니다. 커서 문자열은 HTTP GET 및 POST 매개변수에 사용하기에 안전하며 Datastore 또는 Memcache에도 저장할 수 있습니다. 나중에 동일한 쿼리를 호출할 때 start_cursor 매개변수 또는 with_cursor() 메서드를 통해 이 문자열을 제공하면 이 위치에서 결과를 계속 검색할 수 있습니다.

주의: 아직 실행되지 않은 쿼리에서 이 메서드를 호출하면 AssertionError 예외가 발생합니다.

참고: 모든 쿼리가 커서와 호환되는 것은 아닙니다. 자세한 정보는 Datastore 쿼리 페이지를 참조하세요.

with_cursor (start_cursor, end_cursor=None)

결과를 검색할 쿼리 결과 집합 내의 시작 위치와 (필요한 경우) 종료 위치를 지정합니다. 이전 쿼리를 호출한 후 cursor()를 호출하여 시작 위치와 종료 위치를 나타내는 커서 문자열을 가져올 수 있습니다. 현재 쿼리는 항목 종류, 속성 필터, 상위 필터, 정렬 순서를 포함하여 이전 호출과 동일해야 합니다.

인수

start_cursor
쿼리를 시작할 위치를 지정하는 Base64로 인코딩된 커서 문자열입니다.
end_cursor
쿼리를 종료할 위치를 지정하는 Base64로 인코딩된 커서 문자열입니다.