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

GqlQuery 클래스

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

GqlQuery 클래스는 SQL과 비슷한 App Engine 쿼리 언어인 GQL을 사용하여 App Engine Datastore에서 항목을 검색하기 위한 쿼리를 나타냅니다. GQL 구문 및 기능에 대한 자세한 설명은 GQL 참조를 확인하세요. 또한 GQL 대신 객체 및 메서드를 사용하여 쿼리를 준비하는 관련 클래스인 Query도 참조하세요.

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

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

소개

애플리케이션은 GqlQuery 생성자를 직접 호출하거나 항목 종류 모델 클래스의 gql() 클래스 메서드를 호출하여 GQL 객체를 만듭니다. GqlQuery 생성자는 쿼리 문자열을 인수로 사용합니다. 이 문자열은 SELECT ... FROM model-name으로 시작하는 전체 GQL 문입니다. WHERE 절의 값은 숫자 또는 문자열 리터럴이거나 값에 대한 매개변수 바인딩을 사용할 수 있습니다. 매개변수는 위치 또는 키워드 인수를 사용하여 바인딩할 수 있습니다.

q = GqlQuery("SELECT * FROM Song WHERE composer = 'Lennon, John'")

q = GqlQuery("SELECT __key__ FROM Song WHERE composer = :1", "Lennon, John")

q = GqlQuery("SELECT * FROM Song WHERE composer = :composer", composer="Lennon, John")

편의를 위해 Model 및 Expando 클래스에는 GqlQuery 인스턴스를 반환하는 gql() 클래스 메서드가 포함됩니다. 이 메서드는 암시적인 SELECT ... FROM model-name 프리픽스 없이 GQL 문자열을 사용합니다.

q = Song.gql("WHERE composer = 'Lennon, John'")

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

쿼리 객체를 반복 가능한 것으로 취급하여 일치하는 항목을 한 번에 하나씩 처리합니다.
```
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()을 대신 사용하는 것이 좋습니다.

생성자

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

class GqlQuery (query_string, *args, **kwds)

GQL 쿼리 언어를 사용하여 App Engine Datastore에서 항목을 검색하는 GqlQuery 클래스의 인스턴스를 생성합니다.

인수

query_string: 전체 GQL 문을 포함하는 문자열입니다.
args: 위치 매개변수 값입니다.
kwds: 키워드 매개변수 값입니다.

인스턴스 메서드

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

bind (*args, **kwds)

쿼리의 매개변수 값을 다시 바인딩합니다. 수정된 쿼리는 해당 매개변수가 다시 바인딩된 후 결과에 처음 액세스할 때 실행됩니다.

기존 GqlQuery 객체에 다시 바인딩할 경우 문자열을 다시 파싱할 필요가 없으므로 새로운 GqlQuery 객체를 빌드할 때보다 속도가 빠릅니다.

인수

args: 새로운 위치 매개변수 값입니다.
kwds: 새로운 키워드 매개변수 값입니다.

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)

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

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

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

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

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

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

인수

read_policy

원하는 수준의 데이터 일관성을 지정하는 읽기 정책입니다.

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

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

deadline

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

offset

첫 번째 결과를 반환하기 전에 건너뛸 결과 수입니다.

limit

반환할 최대 결과 수입니다. 이 매개변수를 생략하면 GQL 쿼리 문자열의 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을 반환합니다. 최대 1개의 결과가 Datastore에서 검색됩니다. GQL 쿼리 문자열의 LIMIT 절은 무시됩니다(있는 경우).

인수

read_policy

원하는 수준의 데이터 일관성을 지정하는 읽기 정책입니다.

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

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

deadline

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)

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

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

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

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

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

인수

limit

반환할 최대 결과 수입니다. None으로 설정하면 사용 가능한 모든 결과가 검색됩니다.

read_policy

원하는 수준의 데이터 일관성을 지정하는 읽기 정책입니다.

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

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

deadline

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

offset

첫 번째 결과를 계수하기 전에 건너뛸 결과 수입니다.

limit

계수할 최대 결과 수입니다.

참고: 명시적으로 지정된 경우, 이 매개변수가 GQL 쿼리 문자열의 LIMIT 절에 설정된 값을 재정의합니다. 하지만 매개변수가 생략된 경우에는 기본값 1000이 GQL 쿼리의 LIMIT 절을 재정의하지 않으며, 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.GqlQuery(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로 인코딩된 커서 문자열입니다.