Go 1.11은 지원이 종료되었으며 2026년 1월 31일에 지원 중단됩니다. 지원 중단 후에는 조직에서 이전에 조직 정책을 사용하여 레거시 런타임의 배포를 다시 사용 설정한 경우에도 Go 1.11 애플리케이션을 배포할 수 없습니다. 기존 Go 1.11 애플리케이션은 지원 중단 날짜 이후에도 계속 실행되고 트래픽을 수신합니다. 지원되는 최신 Go 버전으로 마이그레이션하는 것이 좋습니다.
이 페이지에서는 Google App Engine에서 Datastore를 쿼리할 때의 제한사항을 다룹니다.
다음 목록은 Datastore용으로 개발할 때 발생하는 일반적인 제한사항을 보여줍니다.
쿼리에서 명명된 속성이 없는 항목은 무시됨
동일한 종류의 항목이 반드시 동일한 속성을 가질 필요는 없습니다. 유효한 쿼리 결과를 얻으려면 항목에는 쿼리의 필터와 정렬 순서에 명명된 모든 속성에 값이 있어야 합니다(null 가능). 그렇지 않으면 쿼리를 실행하는 데 사용된 색인에서 항목이 생략되므로 쿼리 결과에 포함되지 않습니다.
색인이 생성되지 않은 속성을 필터링하면 결과가 반환되지 않음
쿼리는 색인이 생성되지 않은 속성 값을 찾을 수 없으며 그러한 속성을 정렬할 수도 없습니다.
불일치 필터는 한 가지 속성 이하로 제한됨
전체 색인을 검색할 필요가 없도록 쿼리 메커니즘은 색인에서 서로 인접해 있는 모든 잠재적 쿼리 결과에 의존합니다. 이 제약조건을 만족하기 위해 단일 쿼리는 모든 필터에서 둘 이상의 속성에 비균등 비교(<, <=, >, >=)를 사용할 수 없습니다. 예를 들어 다음 쿼리는 두 불일치 필터가 동일한 속성에 적용되므로 유효합니다.
쿼리에 정렬 순서가 지정되지 않으면 결과가 검색되는 순서대로 반환됩니다. Datastore 구현이 달라지거나 애플리케이션 색인이 변경되면 이 순서가 바뀔 수 있습니다. 따라서 애플리케이션에서 특정한 순서로 쿼리 결과가 필요하다면 정렬 순서를 쿼리에 명시적으로 지정해야 합니다.
속성에 일치 필터가 있으면 정렬 순서가 무시됨
쿼리는 지정된 속성에 일치 필터가 있으면 해당 속성에 지정된 모든 정렬 순서도 무시합니다. 그러면 모든 결과에서 속성의 값이 동일하고 더 이상 정렬할 필요가 없으므로 단일 값 속성의 불필요한 처리를 줄여 간단하게 최적화할 수 있습니다. 그러나 다중 값 속성은 일치 필터로 일치된 값 외에 다른 값도 가질 수 있습니다. 이러한 경우는 매우 드물 뿐 아니라 정렬 순서를 적용하려면 비용이 많이 들고 추가 색인이 필요하므로 Datastore 쿼리 플래너는 다중 값 속성의 경우에도 정렬 순서를 무시합니다. 따라서 지정된 정렬 순서와 다른 순서로 쿼리 결과가 반환될 수 있습니다.
불일치 필터에 사용되는 속성이 먼저 정렬되어야 함
불일치 필터와 일치하는 모든 결과를 검색하기 위해 쿼리는 필터와 일치하는 첫 번째 행을 색인에서 검색한 후 일치하지 않는 행이 나올 때까지 검색을 진행합니다. 전체 결과 집합을 연속된 행에 포함하려면 다른 속성보다 먼저 불일치 필터에 사용되는 속성에 따라 행이 정렬되어야 합니다. 따라서 쿼리에 하나 이상의 불일치 필터와 하나 이상의 정렬 순서가 함께 지정된 경우 첫 번째 정렬 순서는 불일치 필터에 지정된 속성을 참조해야 합니다. 다음은 유효한 쿼리입니다.
항목의 개별 x 값 중 어느 것도 두 필터 조건을 모두 만족하지 않지만 항목은 쿼리를 만족합니다.
마찬가지로 다중 값 속성의 정렬 순서는 일반적이지 않습니다. 이러한 속성은 고유한 값마다 색인에 한 번씩 나타나므로 색인에서 먼저 발견되는 값이 항목의 정렬 순서를 결정합니다.
쿼리 결과가 오름차순으로 정렬된 경우, 속성에서 가장 작은 값이 순서 정렬에 사용됩니다.
결과가 내림차순으로 정렬된 경우에는 가장 큰 값이 순서 정렬에 사용됩니다.
다른 값은 정렬 순서에 영향을 주지 않으며, 값의 개수도 마찬가지입니다.
이로 인해 오름차순 및 내림차순 모두에서 속성 값이 1과 9인 항목이 값이 4, 5, 6, 7인 항목보다 먼저 표시되는 비정상적인 결과가 발생합니다.
트랜잭션 내부의 쿼리에 상위 필터가 포함되어야 함
Datastore 트랜잭션은 동일한 항목 그룹에 속하는 항목(공통 상위 항목의 하위 항목)에서만 작동합니다. 이러한 제한사항을 준수하려면 트랜잭션 내에서 수행되는 모든 쿼리에는 트랜잭션의 다른 작업과 동일한 항목 그룹에 속하는 상위 항목을 지정하는 상위 필터가 포함되어야 합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eEntities must have a value for every property named in a query's filters and sort orders to be included in the results, and it is not possible to specifically query for entities lacking a property.\u003c/p\u003e\n"],["\u003cp\u003eQueries cannot find or sort property values that are not indexed, and inequality filters are limited to a maximum of one property across all query filters.\u003c/p\u003e\n"],["\u003cp\u003eWhen no sort order is specified in a query, the order of results is undefined and may change, so specifying the desired sort order explicitly is recommended.\u003c/p\u003e\n"],["\u003cp\u003eQueries with equality filters for a given property will ignore any specified sort order for that property, potentially causing results to return in an order different from what the sort order implies.\u003c/p\u003e\n"],["\u003cp\u003eQueries within transactions must use ancestor filters to restrict operations to entities within the same entity group, and entities with multiple values can behave in unexpected ways with query filters and sort orders.\u003c/p\u003e\n"]]],[],null,["# Restrictions on queries\n\n| This API is supported for first-generation runtimes and can be used when [upgrading to corresponding second-generation runtimes](/appengine/docs/standard/\n| go\n| /services/access). If you are updating to the App Engine Go 1.12+ runtime, refer to the [migration guide](/appengine/migration-center/standard/migrate-to-second-gen/go-differences) to learn about your migration options for legacy bundled services.\n\nThis page covers the restrictions on querying Datastore from Google App Engine.\nThe following list are common restrictions that you'll run into when developing for\nDatastore.\n\nEntities lacking a property named in the query are ignored\n----------------------------------------------------------\n\nEntities of the same kind need not have the same properties. To be eligible as a query result, an entity must possess a value (possibly null) for every property named in the query's filters and sort orders. If not, the entity is omitted from the indexes used to execute the query and consequently will not be included in the query's results.\n| **Note:** It is not possible to query for entities that are specifically *lacking* a given property. One alternative is to filter on a field's zero value, then filter for entities with `null` as the value of that property.\n\nFiltering on unindexed properties returns no results\n----------------------------------------------------\n\nA query can't find property values that aren't indexed, nor can it sort on such properties.\n\nInequality filters are limited to at most one property\n------------------------------------------------------\n\nTo avoid having to scan the entire index, the query mechanism relies on all of a query's potential results being adjacent to one another in the index. To satisfy this constraint, a single query may not use inequality comparisons (`\u003c`, `\u003c=`, `\u003e`, `\u003e=`) on more than one property across all of its filters. For example, the following query is valid, because both inequality filters apply to the same property: \n\n q := datastore.NewQuery(\"Person\").\n \tFilter(\"BirthYear \u003e=\", minBirthYear).\n \tFilter(\"BirthYear \u003c=\", maxBirthYear)\n\nHowever, this query is *not* valid, because it uses inequality filters on two different properties: \n\n q := datastore.NewQuery(\"Person\").\n \tFilter(\"BirthYear \u003e=\", minBirthYear).\n \tFilter(\"Height \u003c=\", maxHeight) // ERROR\n\nNote that a query *can* combine equality (`=`) filters for different properties, along with one or more inequality filters on a single property. Thus the following *is* a valid query: \n\n q := datastore.NewQuery(\"Person\").\n \tFilter(\"LastName =\", targetLastName).\n \tFilter(\"City =\", targetCity).\n \tFilter(\"BirthYear \u003e=\", minBirthYear).\n \tFilter(\"BirthYear \u003c=\", maxBirthYear)\n\nOrdering of query results is undefined when no sort order is specified\n----------------------------------------------------------------------\n\nWhen a query does not specify a sort order, the results are returned in the order they are retrieved. As the Datastore implementation evolves (or if an application's indexes change), this order may change. Therefore, if your application requires its query results in a particular order, be sure to specify that sort order explicitly in the query.\n\nSort orders are ignored on properties with equality filters\n-----------------------------------------------------------\n\nQueries that include an equality filter for a given property ignore any sort order specified for that property. This is a simple optimization to save needless processing for single-valued properties, since all results have the same value for the property and so no further sorting is needed. Multiple-valued properties, however, may have additional values besides the one matched by the equality filter. Because this use case is rare and applying the sort order would be expensive and require extra indexes, the Datastore query planner simply ignores the sort order even in the multiple-valued case. This may cause query results to be returned in a different order than the sort order appears to imply.\n\nProperties used in inequality filters must be sorted first\n----------------------------------------------------------\n\nTo retrieve all results that match an inequality filter, a query scans the index for the first row matching the filter, then scans forward until it encounters a nonmatching row. For the consecutive rows to encompass the complete result set, they must be ordered by the property used in the inequality filter before any other properties. Thus if a query specifies one or more inequality filters along with one or more sort orders, the first sort order must refer to the same property named in the inequality filters. The following is a valid query: \n\n q := datastore.NewQuery(\"Person\").\n \tFilter(\"BirthYear \u003e=\", minBirthYear).\n \tOrder(\"BirthYear\").\n \tOrder(\"LastName\")\n\nThis query is *not* valid, because it doesn't sort on the property used in the inequality filter: \n\n q := datastore.NewQuery(\"Person\").\n \tFilter(\"BirthYear \u003e=\", minBirthYear).\n \tOrder(\"LastName\") // ERROR\n\nSimilarly, this query is not valid because the property used in the inequality filter is not the first one sorted: \n\n q := datastore.NewQuery(\"Person\").\n \tFilter(\"BirthYear \u003e=\", minBirthYear).\n \tOrder(\"LastName\").\n \tOrder(\"BirthYear\") // ERROR\n\nProperties with multiple values can behave in surprising ways\n-------------------------------------------------------------\n\nBecause of the way they're indexed, entities with multiple values for the same property can sometimes interact with query filters and sort orders in unexpected and surprising ways.\n\nIf a query has multiple inequality filters on a given property, an entity will match the query only if at least one of its individual values for the property satisfies *all* of the filters. For example, if an entity of kind `Widget` has values `1` and `2` for property `x`, it will *not* match the query: \n\n q := datastore.NewQuery(\"Widget\").\n \tFilter(\"x \u003e\", 1).\n \tFilter(\"x \u003c\", 2)\n\nEach of the entity's `x` values satisfies one of the filters, but neither single value satisfies both. Note that this does not apply to equality filters. For example, the same entity *will* satisfy the query \n\n q := datastore.NewQuery(\"Widget\").\n \tFilter(\"x =\", 1).\n \tFilter(\"x =\", 2)\n\neven though neither of the entity's individual `x` values satisfies both filter conditions.\n\nSimilarly, the sort order for multiple-valued properties is unusual. Because such properties appear once in the index for each unique value, the first value seen in the index determines an entity's sort order:\n\n- If the query results are sorted in ascending order, the smallest value of the property is used for ordering.\n- If the results are sorted in descending order, the greatest value is used for ordering.\n- Other values do not affect the sort order, nor does the number of values.\n\nThis has the unusual consequence that an entity with property values `1` and `9` precedes one with values `4`, `5`, `6`, and `7` in both ascending *and* descending order.\n\nQueries inside transactions must include ancestor filters\n---------------------------------------------------------\n\nDatastore [transactions](/appengine/docs/legacy/standard/go111/datastore/transactions) operate only on entities belonging to the same [entity group](/appengine/docs/legacy/standard/go111/datastore/entities) (descended from a common ancestor). To preserve this restriction, all queries performed within a transaction must include an [ancestor filter](#ancestor_filters) specifying an ancestor in the same entity group as the other operations in the transaction."]]
