Stay organized with collections Save and categorize content based on your preferences.
This API is supported for first-generation runtimes and can be used when upgrading to corresponding second-generation runtimes. If you are updating to the App Engine Java 11/17 runtime, refer to the migration guide to learn about your migration options for legacy bundled services.Most Datastore queries return whole entities as their results, but often an application is actually interested in only a few of the entity's properties. Projection queries allow you to query Datastore for just those specific properties of an entity that you actually need, at lower latency and cost than retrieving the entire entity.
Projection queries are similar to SQL queries of the form:
SELECT name, email, phone FROM CUSTOMER
You can use all of the filtering and sorting features available for standard entity queries, subject to the limitations described below. The query returns abridged results with only the specified properties (name, email, and phone in the example) populated with values; all other properties have no data.
To build a projection query, you create a Query object and add properties to it using the addProjection() method:
The type you specify for each property must match the type you used when you first defined the property with Entity.setProperty(). The following example shows how to process the query's results by iterating through the list of entities returned and casting each property value to the expected type:
Query.addProjection() method, you can simply pass null for the type. The property's value will then be returned as a RawValue object, which you can test to determine its type. (In the processing example above, you would cast the property to RawValue instead of a specific type.) Grouping(experimental)
Projection queries can use the setDistinct() method to ensure that only completely unique results will be returned in a result set. This will only return the first result for entities which have the same values for the properties that are being projected.
Projection queries are subject to the following limitations:
Only indexed properties can be projected.
Projection is not supported for properties that are not indexed, whether explicitly or implicitly. Long text strings (Text) and long byte strings (Blob) are not indexed.
The same property cannot be projected more than once.
Properties referenced in an equality (EQUAL) or membership (IN) filter cannot be projected.
For example,
SELECT A FROM kind WHERE B = 1
is valid (projected property not used in the equality filter), as is
SELECT A FROM kind WHERE A > 1
(not an equality filter), but
SELECT A FROM kind WHERE A = 1
(projected property used in equality filter) is not.
Results returned by a projection query should not be saved back to Datastore.
Because the query returns results that are only partially populated, you should not write them back to Datastore.
Projecting a property with multiple values will not populate all values for that property. Instead, a separate entity will be returned for each unique combination of projected values matching the query. For example, suppose you have an entity of kind Foo with two multiple-valued properties, A and B:
Then the projection query
SELECT A, B FROM Foo WHERE A < 3
will return four entities with the following combinations of values:
A = 1, B = 'x'A = 1, B = 'y'A = 2, B = 'x'A = 2, B = 'y'
Note that if an entity has a multiple-valued property with no values, no entries will be included in the index, and no results for that entity will be returned from a projection query including that property.
Warning: Including more than one multiple-valued property in a projection will result in an exploding index. Indexes for projectionsProjection queries require all properties specified in the projection to be included in a Datastore index. The App Engine development server automatically generates the needed indexes for you in the index configuration file, datastore-indexes-auto.xml, which is uploaded with your application.
One way to minimize the number of indexes required is to project the same properties consistently, even when not all of them are always needed. For example, these queries require two separate indexes:
SELECT A, B FROM Kind
SELECT A, B, C FROM Kind
However, if you always project properties A, B, and C, even when C is not required, only one index will be needed.
Converting an existing query into a projection query may require building a new index if the properties in the projection are not already included in another part of the query. For example, suppose you had an existing query like
SELECT * FROM Kind WHERE A > 1 ORDER BY A, B
which requires the index
Index(Kind, A, B)
Converting this to either of the projection queries
SELECT C FROM Kind WHERE A > 1 ORDER BY A, B
SELECT A, B, C FROM Kind WHERE A > 1 ORDER BY A, B
introduces a new property (C) and thus will require building a new index Index(Kind, A, B, C). Note that the projection query
SELECT A, B FROM Kind WHERE A > 1 ORDER BY A, B
would not change the required index, since the projected properties A and B were already included in the existing query.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-07 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-07 UTC."],[[["This API supports first-generation runtimes and is applicable when upgrading to second-generation runtimes, and if you are moving to App Engine Java 11/17, refer to the migration guide for details."],["Projection queries allow you to retrieve only specific properties of an entity from Datastore, reducing latency and costs compared to retrieving entire entities."],["Projection queries are built by adding properties to a `Query` object using the `addProjection()` method, and the type specified for each property must match its original definition type."],["Using `setDistinct()` in projection queries ensures that only unique results are returned, eliminating duplicate entities with the same projected property values."],["Projection queries are limited to indexed properties, cannot project the same property more than once, and properties in equality or membership filters cannot be projected, and results should not be written back to Datastore."]]],[]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4