Python 2.7 has reached end of support
and will be
deprecated
on January 31, 2026. After deprecation, you won't be able to deploy Python 2.7
applications, even if your organization previously used an organization policy to
re-enable deployments of legacy runtimes. Your existing Python
2.7 applications will continue to run and receive traffic after their
deprecation date. We recommend that
you
migrate to the latest supported version of Python.
Retrieving query results
Stay organized with collections
Save and categorize content based on your preferences.
After constructing a query, you can specify a number of retrieval options to
further control the results it returns.
See datastore queries for more information on structuring queries for your app.
Retrieving a single entity
To retrieve just a single entity matching your query, use the method Query.get()
(or GqlQuery.get()
):
q = Person.all()
q.filter("last_name =", target_last_name)
result = q.get()
This returns the first result found in the index that matches the query.
Iterating through query results
When iterating through the results of a query using the run()
method of a Query
or GqlQuery
object, Cloud Datastore retrieves the results in batches. By default each batch contains 20 results, but you can change this value using the method's batch_size
parameter. You can continue iterating through query results until all are returned or the request times out.
Retrieving selected properties from an entity
To retrieve only selected properties of an entity rather than the entire entity, use a projection query. This type of query runs faster and costs less than one that returns complete entities.
Similarly, a keys-only query saves time and resources by returning just the keys to the entities it matches, rather than the full entities themselves. To create this type of query, set keys_only=True
when constructing the query object:
q = Person.all(keys_only=True)
Setting a limit for your query
You can specify a limit for your query to control the maximum number of results returned in one batch. The following example retrieves the five tallest people from Cloud Datastore:
q = Person.all()
q.order("-height")
for p in q.run(limit=5):
print "%s %s, %d inches tall" % (p.first_name, p.last_name, p.height)
What's next?
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-29 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-29 UTC."],[[["\u003cp\u003eYou can refine query results by using various retrieval options to control the data returned.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eQuery.get()\u003c/code\u003e method allows for the retrieval of a single entity that matches the query criteria.\u003c/p\u003e\n"],["\u003cp\u003eQuery results can be iterated through in batches, with the default batch size being 20, which can be adjusted with the \u003ccode\u003ebatch_size\u003c/code\u003e parameter.\u003c/p\u003e\n"],["\u003cp\u003eProjection queries allow you to retrieve only selected properties of an entity, enhancing query speed and efficiency, while keys-only queries only return the keys to the entities, saving time and resources.\u003c/p\u003e\n"],["\u003cp\u003eA limit can be set on queries to restrict the number of results returned in a single batch, useful for controlling the amount of data processed.\u003c/p\u003e\n"]]],[],null,["# Retrieving query results\n\nAfter constructing a query, you can specify a number of retrieval options to\nfurther control the results it returns.\nSee [datastore queries](/appengine/docs/legacy/standard/python/datastore/queries) for more information on structuring queries for your app.\n\nRetrieving a single entity\n--------------------------\n\n\u003cbr /\u003e\n\nTo retrieve just a single entity matching your query, use the method [`Query.get()`](/appengine/docs/legacy/standard/python/datastore/queryclass#Query_get) (or [`GqlQuery.get()`](/appengine/docs/legacy/standard/python/datastore/gqlqueryclass#GqlQuery_get)): \n\n q = Person.all()\n q.filter(\"last_name =\", target_last_name)\n\n result = q.get()\n\nThis returns the first result found in the index that matches the query.\n\n\nIterating through query results\n-------------------------------\n\nWhen iterating through the results of a query using the `run()` method of a [`Query`](/appengine/docs/legacy/standard/python/datastore/queryclass#Query_run) or [`GqlQuery`](/appengine/docs/legacy/standard/python/datastore/gqlqueryclass#GqlQuery_run) object, Cloud Datastore retrieves the results in batches. By default each batch contains 20 results, but you can change this value using the method's `batch_size` parameter. You can continue iterating through query results until all are returned or the request times out.\n\nRetrieving selected properties from an entity\n---------------------------------------------\n\nTo retrieve only selected properties of an entity rather than the entire entity, use a [*projection query*](/appengine/docs/legacy/standard/python/datastore/projectionqueries). This type of query runs faster and costs less than one that returns complete entities.\n\nSimilarly, a [*keys-only query*](/appengine/docs/legacy/standard/python/datastore/queries#keys-only_queries) saves time and resources by returning just the keys to the entities it matches, rather than the full entities themselves. To create this type of query, set `keys_only=True` when constructing the query object: \n\n q = Person.all(keys_only=True)\n\nSetting a limit for your query\n------------------------------\n\nYou can specify a *limit* for your query to control the maximum number of results returned in one batch. The following example retrieves the five tallest people from Cloud Datastore: \n\n q = Person.all()\n q.order(\"-height\")\n\n for p in q.run(limit=5):\n print \"%s %s, %d inches tall\" % (p.first_name, p.last_name, p.height)\n\nWhat's next?\n------------\n\n- Learn the [common restrictions](/appengine/docs/legacy/standard/python/datastore/query-restrictions) for queries on Cloud Datastore.\n- Learn about [query cursors](/appengine/docs/legacy/standard/python/datastore/query-cursors), which allow an application to retrieve a query's results in convenient batches.\n- [Understand data consistency](/appengine/docs/legacy/standard/python/datastore/data-consistency) and how data consistency works with different types of queries on Cloud Datastore.\n- Learn the [basic syntax and structure of queries](/appengine/docs/legacy/standard/python/datastore/queries) for Cloud Datastore."]]