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

NDB 쿼리 클래스

Query 객체는 필터링 및 정렬된 항목 목록을 요청하는 NDB 쿼리를 나타냅니다.

이 페이지에는 참조 문서가 포함되어 있습니다. NDB 쿼리에 대한 일반적인 설명은 쿼리를 참조하세요.

쿼리 옵션

많은 쿼리 메서드에 keys_only=True 등의 키워드 인수나 options=QueryOptions(...)을 통해 전달되는 QueryOptions 객체와 같은 표준 추가 옵션 집합이 사용됩니다.

쿼리는 다양한 구성 옵션을 지원합니다. 이러한 옵션은 Query 메서드에 대한 키워드 인수로 지정됩니다.

인수	유형	기본값	설명
keys_only	`bool`	`False`	모든 작업이 항목 대신 키를 반환합니다.
projection	속성 또는 문자열의 튜플 또는 목록	`None`	작업이 지정된 속성이 설정된 항목만 반환합니다. `projection=[Article.title, Article.date]` 또는 `projection=['title', 'date']`는 해당 두 필드만 설정된 항목을 가져옵니다. 프로젝션 쿼리를 참조하세요.
offset	`int`	`0`	건너뛸 쿼리 결과 수입니다.
limit	`int`	제한 없음	반환할 최대 쿼리 결과 수입니다.
batch_size	`int`	`20`	배치 크기입니다. 쿼리의 효율성에만 영향을 미칩니다. 배치 크기가 클수록 메모리를 더 많이 사용하지만 RPC 호출은 더 적게 실행합니다.
prefetch_size	`int`	`None`	반환되는 첫 번째 배치의 배치 크기를 재정의합니다.
produce_cursors	`bool`	`False`	쿼리에서 커서를 생성합니다. 쿼리 반복기 및 쿼리 커서를 참조하세요.
start_cursor	`Cursor`	`None`	검색의 시작점입니다. 쿼리 커서를 참조하세요.
end_cursor	`Cursor`	`None`	검색의 끝점입니다. 쿼리 커서를 참조하세요.
deadline	`int`	`Context`에 따라 다름	RPC 기한을 재정의합니다. `Context` 생성 시 재정의하지 않은 경우 기본값은 5초입니다.
read_policy	`ndb.EVENTUAL_CONSISTENCY`		읽기 정책입니다. Datastore가 대기 중인 변경사항을 반환된 모든 레코드에 적용할 때까지 기다리지 않고 결과를 더 빠르게 가져오려면 `ndb.EVENTUAL_CONSISTENCY`로 설정합니다.

특정 옵션 집합을 사용하여 쿼리를 실행하려면 키워드 인수를 해당 메서드에 전달합니다.

qry = Employee.query().filter(...).order(...) # Create a query
for acct in qry.fetch(10, offset=20): # Skip the first 20
  print acct

쿼리 옵션 집합을 보관해 두었다가 다양한 곳에 사용하려고 할 수 있습니다. 단순히 쿼리 옵션을 사전에 보관해 두고 **kwds를 사용하여 이 사전을 메서드에 전달할 수 있지만 QueryOptions 객체를 만들고 옵션 키워드 인수를 사용하여 이를 전달할 수도 있습니다. 다음 두 예시는 동일합니다.

qo = ndb.QueryOptions(keys_only=True, offset=20)
results = qry.fetch(10, options=qo)
results = qry.fetch(10, keys_only=True, offset=20)

생성자

일반적으로 애플리케이션은 Model.query()를 호출하여 Query를 만듭니다. 하지만 ndb.Query()를 호출할 수도 있습니다.

인수

kind: 선택적 종류 문자열입니다. 일반적으로 항목 클래스의 이름입니다.
ancestor: 선택적 상위 키입니다.
filters: 필터 표현식 트리를 나타내는 선택적 노드입니다.
orders: 선택적 datastore_query.Order 객체입니다.
app: 선택적 앱 ID입니다.
namespace: 선택적 네임스페이스입니다. 값을 지정하지 않을 경우 쿼리 실행 당시의 기본 네임스페이스가 사용됩니다.
projection: 프로젝션할 속성의 선택사항인 목록 또는 튜플입니다.
group_by: 그룹화할 속성의 선택적 목록 또는 튜플입니다.
default_options: 쿼리가 실행될 때 사용할 기본 쿼리 옵션을 제공하는 선택적 QueryOptions 객체입니다.

인스턴스 메서드

filter(filter1, filter2, ...)

추가 필터가 적용된 새 Query를 반환합니다. 쿼리에 설명된 대로 필터 인수를 사용합니다. qry.filter(filter1).filter(filter2)는 qry.filter(filter1, filter2)와 동일합니다.

get(**q_options)

첫 번째 쿼리 결과가 있는 경우 이를 반환하고 그렇지 않으면 None을 반환합니다. q.fetch(1)을 호출하고 결과 목록의 첫 번째 항목을 반환하는 것과 비슷합니다.

인수

**q_options: 모든 쿼리 옵션 키워드 인수가 지원됩니다.

order(order1, order2, ...)

추가 정렬 순서가 적용된 새 Query를 반환합니다. 속성 또는 '부정' 속성인 하나 이상의 인수를 사용합니다. 예를 들어 연령별로 사용자를 정렬하고 이름별 '연결을 끊으려면' qry.order(-Account.birthday, Account.name) 등을 사용할 수 있습니다.

bind(...values...)

이 함수는 매개변수 바인딩(:1, :2 등)이나 이름이 지정된 바인딩(:foo, :bar 등)을 사용하는 GQL 쿼리용입니다. 이 함수는 전달된 값을 매개변수에 바인딩합니다.

매개변수를 바인딩하려면 qry.bind("USA", 49) 등을 호출할 수 있습니다. 이름이 지정된 매개변수를 바인딩하려면 qry.bind(region = "USA", threshold = 49) 등을 호출할 수 있습니다.

매개변수 값이 바인딩된 새 Query 객체를 반환합니다.

count(limit=None, **q_options)

쿼리 결과의 수를 한도까지 반환합니다. 반환되는 결과는 len(q.fetch(limit))와 같지만 더 효율적입니다.

인수

limit: 셀 최대 결과 수입니다.
**q_options: 모든 쿼리 옵션 키워드 인수 및 컨텍스트 옵션이 지원됩니다.

count_async(limit, **q_options)

쿼리 결과의 수를 한도까지 비동기적으로 집계합니다. 결과가 숫자인 Future를 반환합니다. count()의 비동기 버전입니다.

fetch(limit, **q_options)

쿼리 결과의 목록을 한도까지 가져옵니다.

인수

limit: 셀 최대 결과 수입니다.
**q_options: 모든 쿼리 옵션 키워드 인수가 지원됩니다.

fetch_async(limit, **q_options)

쿼리 결과의 목록을 한도까지 비동기적으로 가져옵니다. 결과가 결과 목록인 Future를 반환합니다. fetch()의 비동기 버전입니다.

fetch_page(page_size, **q_options)

결과의 '페이지'를 가져옵니다. 페이징 사용자 인터페이스용 특수 메소드입니다.

인수

page_size: 반환할 최대 결과 수입니다.
**q_options: 모든 쿼리 옵션 키워드 인수가 지원됩니다.

(results,
     cursor, more)

튜플을 반환합니다.

results 쿼리 결과 목록
cursor '다음' 결과 배치를 가리키는 쿼리 커서. 결과가 더 없으면 None일 수 있습니다.
이 배치 이후에 결과가 더 있는지(그럴 가능성이 있는) 여부를 나타내는 more bool. False이면 결과가 더 이상 없고, True이면 결과가 더 있을 가능성이 있습니다.

다음 페이지를 가져오려면 start_cursor=cursor를 사용하여 하나의 호출을 통해 반환되는 커서를 다음 호출로 전달합니다. 일반적인 관용구는 cursor.urlsafe()를 사용하여 커서를 클라이언트에 전달하고 Cursor(urlsafe=string)를 사용하여 후속 요청에서 해당 커서를 재구성하는 것입니다.

fetch_page_async(page_size, **q_options)

결과의 '페이지'를 비동기적으로 가져옵니다. fetch_page()의 비동기 버전입니다.

get_async(**q_options)

첫 번째 쿼리 결과가 있는 경우 비동기적으로 반환하고 그렇지 않으면 None을 반환합니다. get()의 비동기 버전입니다.

iter(**q_options)

쿼리에 대해 반복기를 생성하여 반환합니다.

인수

**q_options: 모든 쿼리 옵션 키워드 인수가 지원됩니다.

QueryIterator 객체를 반환합니다.

map(callback, pass_batch_into_callback=None, merge_future=None, **q_options)

쿼리 결과에 대해 콜백 함수 또는 tasklet을 매핑합니다. 즉, 쿼리 결과의 각 항목에 함수 또는 tasklet을 적용합니다.

인수

callback: 각 결과에 적용할 함수 또는 tasklet입니다.
pass_batch_into_callback: True이면 아래에 설명된 대로 배치 정보 인수를 사용하여 콜백을 호출합니다.
merge_future: 선택적 Future 서브클래스입니다. 아래를 참조하세요.
**q_options: 모든 쿼리 옵션 키워드 인수가 지원됩니다.

콜백 서명 콜백은 일반적으로 항목을 인수로 사용하여 호출됩니다. 하지만 keys_only=True를 지정할 경우 키를 사용하여 호출됩니다. pass_batch_into_callback=True를 지정할 경우 콜백은 현재 배치, 배치 내의 색인, 해당 색인의 항목 또는 Key라는 세 가지 인수를 사용하여 호출됩니다. 콜백은 원하는 것은 무엇이든 반환할 수 있습니다. 콜백이 None일 경우에는 전달된 항목 또는 키만 반환하는 간단한 콜백이라고 가정됩니다.

선택적 merge_future. merge_future는 콜백 결과가 전체 map() 반환 값으로 결합되는 방법을 재정의하는 데 사용할 수 있는 고급 인수입니다. 기본적으로 콜백 반환 값 목록 하나가 생성됩니다. 적은 수의 특수 대안 중 하나를 대체하여 다른 결과를 얻을 수도 있습니다. tasklets.MultiFuture의 소스 코드를 참조하면 기본 구현과 merge_future 객체가 구현해야 하는 프로토콜의 설명을 확인할 수 있습니다. 동일한 모듈의 대안으로는 QueueFuture, SerialQueueFuture, ReducingFuture가 있습니다.

모든 콜백의 결과 목록을 반환합니다. 위의 '선택적 merge_future'를 참조하세요. 쿼리가 완료되고 모든 콜백이 반환될 경우 반환됩니다.

map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)

쿼리 결과에 대해 콜백 함수 또는 tasklet을 비동기적으로 매핑합니다. map()의 비동기 버전입니다.