Datastore queries

A query retrieves entities from Firestore in Datastore mode that meet a specified set of conditions.

The query operates on entities of a given kind ; it can specify filters on the entities' property values, keys, and ancestors, and can return zero or more entities as results . A query can also specify sort orders to sequence the results by their property values. The results include all entities that have at least one value for every property named in the filters and sort orders, and whose property values meet all the specified filter criteria. The query can return entire entities, projected entities, or just entity keys.

A typical query includes the following:

• An entity kind to which the query applies
• Zero or more filters based on the entities' property values, keys, and ancestors
• Zero or more sort orders to sequence the results

When executed, the query retrieves all entities of the given kind that satisfy all of the given filters, sorted in the specified order. Queries execute as read-only.

Note:To conserve memory and improve performance, a query should, whenever possible, specify a limit on the number of results returned.

Every query computes its results using one or more indexes , which contain entity keys in a sequence specified by the index's properties and, optionally, the entity's ancestors. The indexes are updated incrementally to reflect any changes the application makes to its entities, so that the correct results of all queries are available with no further computation needed.

The index-based query mechanism supports a wide range of queries and is suitable for most applications, except for non-scaling queries, such as join queries. For more information about limitations on Datastore mode queries, see Restrictions on queries .

Query interface

You can issue a query against a Datastore mode database. The following example shows how to retrieve all tasks that are not yet done with priorities greater than or equal to 4, sorted in descending order by priority:

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 ( 
 "Task" 
 ) 
 { 
  
 Filter 
  
 = 
  
 Filter 
 . 
 And 
 ( 
 Filter 
 . 
 Equal 
 ( 
 "done" 
 , 
  
 false 
 ), 
  
 Filter 
 . 
 GreaterThanOrEqual 
 ( 
 "priority" 
 , 
  
 4 
 )), 
  
 Order 
  
 = 
  
 { 
  
 { 
  
 "priority" 
 , 
  
 PropertyOrder 
 . 
 Types 
 . 
 Direction 
 . 
 Descending 
  
 } 
  
 } 
 }; 
 

  query 
  
 := 
  
 datastore 
 . 
 NewQuery 
 ( 
 "Task" 
 ). 
  
 FilterField 
 ( 
 "Done" 
 , 
  
 "=" 
 , 
  
 false 
 ). 
  
 FilterField 
 ( 
 "Priority" 
 , 
  
 ">=" 
 , 
  
 4 
 ). 
  
 Order 
 ( 
 "-Priority" 
 ) 
 

  Query<Entity> 
  
 query 
  
 = 
  
 Query 
 . 
 newEntityQueryBuilder 
 () 
  
 . 
 setKind 
 ( 
 "Task" 
 ) 
  
 . 
 setFilter 
 ( 
  
 CompositeFilter 
 . 
 and 
 ( 
  
 PropertyFilter 
 . 
 eq 
 ( 
 "done" 
 , 
  
 false 
 ), 
  
 PropertyFilter 
 . 
 ge 
 ( 
 "priority" 
 , 
  
 4 
 ))) 
  
 . 
 setOrderBy 
 ( 
 OrderBy 
 . 
 desc 
 ( 
 "priority" 
 )) 
  
 . 
 build 
 (); 
 

  const 
  
 query 
  
 = 
  
 datastore 
  
 . 
 createQuery 
 ( 
 'Task' 
 ) 
  
 . 
 filter 
 ( 
  
 and 
 ([ 
  
 new 
  
 PropertyFilter 
 ( 
 'done' 
 , 
  
 '=' 
 , 
  
 false 
 ), 
  
 new 
  
 PropertyFilter 
 ( 
 'priority' 
 , 
  
 '>=' 
 , 
  
 4 
 ), 
  
 ]), 
  
 ) 
  
 . 
 order 
 ( 
 'priority' 
 , 
  
 { 
  
 descending 
 : 
  
 true 
 , 
  
 }); 
 

  $query = $datastore->query() 
 ->kind('Task') 
 ->filter('done', '=', false) 
 ->filter('priority', '>=', 4) 
 ->order('priority', Query::ORDER_DESCENDING); 
 

  from 
  
 google.cloud 
  
 import 
  datastore 
 
 # For help authenticating your client, visit 
 # https://cloud.google.com/docs/authentication/getting-started 
 client 
 = 
  datastore 
 
 . 
  Client 
 
 () 
 query 
 = 
 client 
 . 
  query 
 
 ( 
 kind 
 = 
 "Task" 
 ) 
 query 
 . 
  add_filter 
 
 ( 
 filter 
 = 
  datastore 
 
 . 
 query 
 . 
  PropertyFilter 
 
 ( 
 "done" 
 , 
 "=" 
 , 
 False 
 )) 
 query 
 . 
  add_filter 
 
 ( 
 filter 
 = 
  datastore 
 
 . 
 query 
 . 
  PropertyFilter 
 
 ( 
 "priority" 
 , 
 ">=" 
 , 
 4 
 )) 
 query 
 . 
  order 
 
 = 
 [ 
 "-priority" 
 ] 
 

  query 
  
 = 
  
 datastore 
 . 
 query 
 ( 
 "Task" 
 ) 
  
 . 
 where 
 ( 
 "done" 
 , 
  
 "=" 
 , 
  
 false 
 ) 
  
 . 
 where 
 ( 
 "priority" 
 , 
  
 ">=" 
 , 
  
 4 
 ) 
  
 . 
 order 
 ( 
 "priority" 
 , 
  
 :desc 
 ) 
 

 SELECT 
  
 * 
  
 FROM 
  
 Task 
 WHERE 
  
 done 
  
 = 
  
 FALSE 
  
 AND 
  
 priority 
  
> = 
  
 4 
 ORDER 
  
 BY 
  
 priority 
  
 DESC 

The following example shows how to run a query:

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 ( 
 "Task" 
 ); 
 DatastoreQueryResults 
  
 tasks 
  
 = 
  
 _db 
 . 
 RunQuery 
 ( 
 query 
 ); 
 

  it 
  
 := 
  
 client 
 . 
 Run 
 ( 
 ctx 
 , 
  
 query 
 ) 
 for 
  
 { 
  
 var 
  
 task 
  
 Task 
  
 _ 
 , 
  
 err 
  
 := 
  
 it 
 . 
 Next 
 ( 
& task 
 ) 
  
 if 
  
 err 
  
 == 
  
 iterator 
 . 
 Done 
  
 { 
  
 break 
  
 } 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 log 
 . 
 Fatalf 
 ( 
 "Error fetching next task: %v" 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Printf 
 ( 
 "Task %q, Priority %d\n" 
 , 
  
 task 
 . 
 Description 
 , 
  
 task 
 . 
 Priority 
 ) 
 } 
 

  QueryResults<Entity> 
  
 tasks 
  
 = 
  
 datastore 
 . 
 run 
 ( 
 query 
 ); 
 

  const 
  
 [ 
 tasks 
 ] 
  
 = 
  
 await 
  
 datastore 
 . 
 runQuery 
 ( 
 query 
 ); 
 console 
 . 
 log 
 ( 
 'Tasks:' 
 ); 
 tasks 
 . 
 forEach 
 ( 
 task 
  
 = 
>  
 console 
 . 
 log 
 ( 
 task 
 )); 
 

  $result = $datastore->runQuery($query); 
 

  from 
  
 google.cloud 
  
 import 
  datastore 
 
 # For help authenticating your client, visit 
 # https://cloud.google.com/docs/authentication/getting-started 
 client 
 = 
  datastore 
 
 . 
  Client 
 
 () 
 query 
 = 
 client 
 . 
  query 
 
 () 
 results 
 = 
 list 
 ( 
 query 
 . 
 fetch 
 ()) 
 

  tasks 
  
 = 
  
 datastore 
 . 
 run 
  
 query 
 

Query structure

A query can specify an entity kind , zero or more filters , and zero or more sort orders .

Filters

A query's filters set constraints on the properties , keys , and ancestors of the entities to be retrieved.

Property filters

A property filter specifies the following:

• A property name
• A comparison operator
• A property value

The following example returns task entities that are marked not done:

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 ( 
 "Task" 
 ) 
 { 
  
 Filter 
  
 = 
  
 Filter 
 . 
 Equal 
 ( 
 "done" 
 , 
  
 false 
 ) 
 }; 
 

  query 
  
 := 
  
 datastore 
 . 
 NewQuery 
 ( 
 "Task" 
 ). 
 FilterField 
 ( 
 "Done" 
 , 
  
 "=" 
 , 
  
 false 
 ) 
 

  Query<Entity> 
  
 query 
  
 = 
  
 Query 
 . 
 newEntityQueryBuilder 
 () 
  
 . 
 setKind 
 ( 
 "Task" 
 ) 
  
 . 
 setFilter 
 ( 
 PropertyFilter 
 . 
 eq 
 ( 
 "done" 
 , 
  
 false 
 )) 
  
 . 
 build 
 (); 
 

  const 
  
 query 
  
 = 
  
 datastore 
  
 . 
 createQuery 
 ( 
 'Task' 
 ) 
  
 . 
 filter 
 ( 
 new 
  
 PropertyFilter 
 ( 
 'done' 
 , 
  
 '=' 
 , 
  
 false 
 )); 
 

  $query = $datastore->query() 
 ->kind('Task') 
 ->filter('done', '=', false); 
 

  from 
  
 google.cloud 
  
 import 
  datastore 
 
 # For help authenticating your client, visit 
 # https://cloud.google.com/docs/authentication/getting-started 
 client 
 = 
  datastore 
 
 . 
  Client 
 
 () 
 query 
 = 
 client 
 . 
  query 
 
 ( 
 kind 
 = 
 "Task" 
 ) 
 query 
 . 
  add_filter 
 
 ( 
 filter 
 = 
  datastore 
 
 . 
 query 
 . 
  PropertyFilter 
 
 ( 
 "done" 
 , 
 "=" 
 , 
 False 
 )) 
 

  query 
  
 = 
  
 datastore 
 . 
 query 
 ( 
 "Task" 
 ) 
  
 . 
 where 
 ( 
 "done" 
 , 
  
 "=" 
 , 
  
 false 
 ) 
 

 SELECT 
  
 * 
  
 FROM 
  
 Task 
  
 WHERE 
  
 done 
  
 = 
  
 FALSE 

The property value must be supplied by the application; it cannot refer to or be calculated in terms of other properties. An entity satisfies the filter if it has a property of the given name whose value compares to the value specified in the filter in the manner described by the comparison operator. If the property of the given name is array-valued, the entity satisfies the filter if any of the values compares to the value specified in the filter in the manner described by the comparison operator.

The comparison operator can be any of the following:

Composite filters

A composite filter consists of more than one property filter. You can combine filters with AND and OR . The following example returns Task entities that are marked not done and have a priority of 4:

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 ( 
 "Task" 
 ) 
 { 
  
 Filter 
  
 = 
  
 Filter 
 . 
 And 
 ( 
 Filter 
 . 
 Equal 
 ( 
 "done" 
 , 
  
 false 
 ), 
  
 Filter 
 . 
 Equal 
 ( 
 "priority" 
 , 
  
 4 
 )), 
 }; 
 

  query 
  
 := 
  
 datastore 
 . 
 NewQuery 
 ( 
 "Task" 
 ). 
  
 FilterField 
 ( 
 "Done" 
 , 
  
 "=" 
 , 
  
 false 
 ). 
  
 FilterField 
 ( 
 "Priority" 
 , 
  
 "=" 
 , 
  
 4 
 ) 
 

  Query<Entity> 
  
 query 
  
 = 
  
 Query 
 . 
 newEntityQueryBuilder 
 () 
  
 . 
 setKind 
 ( 
 "Task" 
 ) 
  
 . 
 setFilter 
 ( 
  
 CompositeFilter 
 . 
 and 
 ( 
  
 PropertyFilter 
 . 
 eq 
 ( 
 "done" 
 , 
  
 false 
 ), 
  
 PropertyFilter 
 . 
 eq 
 ( 
 "priority" 
 , 
  
 4 
 ))) 
  
 . 
 build 
 (); 
 

  const 
  
 query 
  
 = 
  
 datastore 
  
 . 
 createQuery 
 ( 
 'Task' 
 ) 
  
 . 
 filter 
 ( 
  
 and 
 ([ 
  
 new 
  
 PropertyFilter 
 ( 
 'done' 
 , 
  
 '=' 
 , 
  
 false 
 ), 
  
 new 
  
 PropertyFilter 
 ( 
 'priority' 
 , 
  
 '=' 
 , 
  
 4 
 ), 
  
 ]), 
  
 ); 
 

  $query = $datastore->query() 
 ->kind('Task') 
 ->filter('done', '=', false) 
 ->filter('priority', '=', 4); 
 

  from 
  
 google.cloud 
  
 import 
  datastore 
 
 # For help authenticating your client, visit 
 # https://cloud.google.com/docs/authentication/getting-started 
 client 
 = 
  datastore 
 
 . 
  Client 
 
 () 
 query 
 = 
 client 
 . 
  query 
 
 ( 
 kind 
 = 
 "Task" 
 ) 
 query 
 . 
  add_filter 
 
 ( 
 filter 
 = 
  datastore 
 
 . 
 query 
 . 
  PropertyFilter 
 
 ( 
 "done" 
 , 
 "=" 
 , 
 False 
 )) 
 query 
 . 
  add_filter 
 
 ( 
 filter 
 = 
  datastore 
 
 . 
 query 
 . 
  PropertyFilter 
 
 ( 
 "priority" 
 , 
 "=" 
 , 
 4 
 )) 
 

  query 
  
 = 
  
 datastore 
 . 
 query 
 ( 
 "Task" 
 ) 
  
 . 
 where 
 ( 
 "done" 
 , 
  
 "=" 
 , 
  
 false 
 ) 
  
 . 
 where 
 ( 
 "priority" 
 , 
  
 "=" 
 , 
  
 4 
 ) 
 

 SELECT 
  
 * 
  
 FROM 
  
 Task 
  
 WHERE 
  
 done 
  
 = 
  
 FALSE 
  
 AND 
  
 priority 
  
 = 
  
 4 

The following example combines filters with a logical OR :

  import 
  
 com.google.cloud.datastore. Datastore 
 
 ; 
 import 
  
 com.google.cloud.datastore. DatastoreOptions 
 
 ; 
 import 
  
 com.google.cloud.datastore. Entity 
 
 ; 
 import 
  
 com.google.cloud.datastore. Query 
 
 ; 
 import 
  
 com.google.cloud.datastore. QueryResults 
 
 ; 
 import 
  
 com.google.cloud.datastore. StructuredQuery 
. CompositeFilter 
 
 ; 
 import 
  
 com.google.cloud.datastore. StructuredQuery 
. Filter 
 
 ; 
 import 
  
 com.google.cloud.datastore. StructuredQuery 
. PropertyFilter 
 
 ; 
 public 
  
 class 
 OrFilterQuery 
  
 { 
  
 public 
  
 static 
  
 void 
  
 invoke 
 () 
  
 throws 
  
 Exception 
  
 { 
  
 // Instantiates a client 
  
  Datastore 
 
  
 datastore 
  
 = 
  
  DatastoreOptions 
 
 . 
  getDefaultInstance 
 
 (). 
 getService 
 (); 
  
 String 
  
 propertyName 
  
 = 
  
 "description" 
 ; 
  
 // Create the two filters 
  
  Filter 
 
  
 orFilter 
  
 = 
  
  CompositeFilter 
 
 . 
  or 
 
 ( 
  
  PropertyFilter 
 
 . 
  eq 
 
 ( 
 propertyName 
 , 
  
 "Feed cats" 
 ), 
  
  PropertyFilter 
 
 . 
  eq 
 
 ( 
 propertyName 
 , 
  
 "Buy milk" 
 )); 
  
 // Build the query 
  
 Query<Entity> 
  
 query 
  
 = 
  
  Query 
 
 . 
  newEntityQueryBuilder 
 
 (). 
 setKind 
 ( 
 "Task" 
 ). 
  setFilter 
 
 ( 
 orFilter 
 ). 
 build 
 (); 
  
 // Get the results back from Datastore 
  
 QueryResults<Entity> 
  
 results 
  
 = 
  
 datastore 
 . 
  run 
 
 ( 
 query 
 ); 
  
 if 
  
 ( 
 ! 
 results 
 . 
 hasNext 
 ()) 
  
 { 
  
 throw 
  
 new 
  
 Exception 
 ( 
 "query yielded no results" 
 ); 
  
 } 
  
 while 
  
 ( 
 results 
 . 
 hasNext 
 ()) 
  
 { 
  
  Entity 
 
  
 entity 
  
 = 
  
 results 
 . 
 next 
 (); 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Entity: %s%n" 
 , 
  
 entity 
 ); 
  
 } 
  
 } 
 } 
 

  /** 
 * TODO(developer): Uncomment these variables before running the sample. 
 */ 
 // const projectId = "your Google Cloud project id"; 
 // Imports the Cloud Datastore 
 const 
  
 { 
 Datastore 
 , 
  
 PropertyFilter 
 , 
  
 or 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/datastore 
' 
 ); 
 async 
  
 function 
  
 queryFilterOr 
 () 
  
 { 
  
 // Instantiate the Datastore 
  
 const 
  
 datastore 
  
 = 
  
 new 
  
  Datastore 
 
 (); 
  
 const 
  
 query 
  
 = 
  
 datastore 
  
 . 
 createQuery 
 ( 
 'Task' 
 ) 
  
 . 
  filter 
 
 ( 
  
 or 
 ([ 
  
 new 
  
  PropertyFilter 
 
 ( 
 'description' 
 , 
  
 '=' 
 , 
  
 'Buy milk' 
 ), 
  
 new 
  
  PropertyFilter 
 
 ( 
 'description' 
 , 
  
 '=' 
 , 
  
 'Feed cats' 
 ), 
  
 ]), 
  
 ); 
  
 const 
  
 [ 
 entities 
 ] 
  
 = 
  
 await 
  
 datastore 
 . 
 runQuery 
 ( 
 query 
 ); 
  
 for 
  
 ( 
 const 
  
 entity 
  
 of 
  
 entities 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
 `Entity found: 
 ${ 
 entity 
 [ 
 'description' 
 ] 
 } 
 ` 
 ); 
  
 } 
 } 
 queryFilterOr 
 (); 
 

  from 
  
 google.cloud 
  
 import 
  datastore 
 
 from 
  
 google.cloud.datastore 
  
 import 
 query 
 def 
  
 query_filter_or 
 ( 
 project_id 
 : 
 str 
 ) 
 - 
> None 
 : 
  
 """Builds a union of two queries (OR) filter. 
 Arguments: 
 project_id: your Google Cloud Project ID 
 """ 
 client 
 = 
  datastore 
 
 . 
  Client 
 
 ( 
 project 
 = 
 project_id 
 ) 
 or_query 
 = 
 client 
 . 
  query 
 
 ( 
 kind 
 = 
 "Task" 
 ) 
 or_filter 
 = 
 query 
 . 
  Or 
 
 ( 
 [ 
 query 
 . 
  PropertyFilter 
 
 ( 
 "description" 
 , 
 "=" 
 , 
 "Buy milk" 
 ), 
 query 
 . 
  PropertyFilter 
 
 ( 
 "description" 
 , 
 "=" 
 , 
 "Feed cats" 
 ), 
 ] 
 ) 
 or_query 
 . 
  add_filter 
 
 ( 
 filter 
 = 
 or_filter 
 ) 
 results 
 = 
 list 
 ( 
 or_query 
 . 
 fetch 
 ()) 
 for 
 result 
 in 
 results 
 : 
 print 
 ( 
 result 
 [ 
 "description" 
 ]) 
 

 Query<Entity> 
  
 query 
  
 = 
  
 Query 
 . 
 newEntityQueryBuilder 
 () 
  
 . 
 setKind 
 ( 
 "Task" 
 ) 
  
 . 
 setFilter 
 ( 
 CompositeFilter 
 . 
 or 
 ( 
  
 PropertyFilter 
 . 
 eq 
 ( 
 "starred" 
 , 
  
 true 
 )), 
  
 CompositeFilter 
 . 
 and 
 ( 
  
 PropertyFilter 
 . 
 eq 
 ( 
 "done" 
 , 
  
 false 
 ), 
  
 PropertyFilter 
 . 
 eq 
 ( 
 "priority" 
 , 
  
 4 
 ))) 
  
 . 
 build 
 (); 

 and_or_query 
 = 
 client 
 . 
 query 
 ( 
 kind 
 = 
 "Task" 
 ) 
 query_filter 
 = 
 query 
 . 
 Or 
 ( 
 [ 
 query 
 . 
 PropertyFilter 
 ( 
 "starred" 
 , 
 "=" 
 , 
 True 
 ), 
 query 
 . 
 And 
 ([ 
 query 
 . 
 PropertyFilter 
 ( 
 "done" 
 , 
 "=" 
 , 
 False 
 ), 
 query 
 . 
 PropertyFilter 
 ( 
 "priority" 
 , 
 "=" 
 , 
 4 
 ,), 
 ] 
 ) 
 ] 
 ) 
 and_or_query 
 . 
 add_filter 
 ( 
 filter 
 = 
 query_filter 
 ) 
 results 
 = 
 and_or_query 
 . 
 fetch 
 () 
 for 
 result 
 in 
 results 
 : 
 print 
 ( 
 result 
 [ 
 "description" 
 ]) 

Key filters

To filter on the value of an entity's key, use the special property __key__ :

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 ( 
 "Task" 
 ) 
 { 
  
 Filter 
  
 = 
  
 Filter 
 . 
 GreaterThan 
 ( 
 "__key__" 
 , 
  
 _keyFactory 
 . 
 CreateKey 
 ( 
 "aTask" 
 )) 
 }; 
 

  key 
  
 := 
  
 datastore 
 . 
 NameKey 
 ( 
 "Task" 
 , 
  
 "someTask" 
 , 
  
 nil 
 ) 
 query 
  
 := 
  
 datastore 
 . 
 NewQuery 
 ( 
 "Task" 
 ). 
 FilterField 
 ( 
 "__key__" 
 , 
  
 ">" 
 , 
  
 key 
 ) 
 

  Query<Entity> 
  
 query 
  
 = 
  
 Query 
 . 
 newEntityQueryBuilder 
 () 
  
 . 
 setKind 
 ( 
 "Task" 
 ) 
  
 . 
 setFilter 
 ( 
 PropertyFilter 
 . 
 gt 
 ( 
 "__key__" 
 , 
  
 keyFactory 
 . 
 newKey 
 ( 
 "someTask" 
 ))) 
  
 . 
 build 
 (); 
 

  const 
  
 query 
  
 = 
  
 datastore 
  
 . 
 createQuery 
 ( 
 'Task' 
 ) 
  
 . 
 filter 
 ( 
  
 new 
  
 PropertyFilter 
 ( 
 '__key__' 
 , 
  
 '>' 
 , 
  
 datastore 
 . 
 key 
 ([ 
 'Task' 
 , 
  
 'someTask' 
 ])), 
  
 ); 
 

  $query = $datastore->query() 
 ->kind('Task') 
 ->filter('__key__', '>', $datastore->key('Task', 'someTask')); 
 

  from 
  
 google.cloud 
  
 import 
  datastore 
 
 # For help authenticating your client, visit 
 # https://cloud.google.com/docs/authentication/getting-started 
 client 
 = 
  datastore 
 
 . 
  Client 
 
 () 
 query 
 = 
 client 
 . 
  query 
 
 ( 
 kind 
 = 
 "Task" 
 ) 
 first_key 
 = 
 client 
 . 
  key 
 
 ( 
 "Task" 
 , 
 "first_task" 
 ) 
 # key_filter(key, op) translates to add_filter('__key__', op, key). 
 query 
 . 
  key_filter 
 
 ( 
 first_key 
 , 
 ">" 
 ) 
 

  query 
  
 = 
  
 datastore 
 . 
 query 
 ( 
 "Task" 
 ) 
  
 . 
 where 
 ( 
 "__key__" 
 , 
  
 ">" 
 , 
  
 datastore 
 . 
 key 
 ( 
 "Task" 
 , 
  
 "someTask" 
 )) 
 

 SELECT 
  
 * 
  
 FROM 
  
 Task 
  
 WHERE 
  
 __key__ 
 > 
 KEY 
 ( 
 Task 
 , 
  
 'someTask' 
 ) 

When comparing for inequality, keys are ordered by the following criteria, in order:

1. Ancestor path
2. Entity kind
3. Identifier (key name or numeric ID)

Elements of the ancestor path are compared similarly: by kind (string), then by key name or numeric ID. Kinds and key names are strings and are ordered by byte value; numeric IDs are integers and are ordered numerically. If entities with the same parent and kind use a mix of key name strings and numeric IDs, those with numeric IDs precede those with key names.

Queries on keys use indexes just like queries on properties and require custom indexes in the same cases. The following exceptions don't require a custom index:

• Inequality filters
• Ascending sort order on the key

A descending sort order on the key requires a custom index. As with all queries, the development server creates appropriate entries in the index configuration file when a query that needs a custom index is used in the development environment.

Sort orders

A query sort order specifies the following:

• A property name.
• A sort direction (ascending or descending). By default the sort order is ascending.

This example sorts Task entities by creation time in ascending order:

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 ( 
 "Task" 
 ) 
 { 
  
 Order 
  
 = 
  
 { 
  
 { 
  
 "created" 
 , 
  
 PropertyOrder 
 . 
 Types 
 . 
 Direction 
 . 
 Ascending 
  
 } 
  
 } 
 }; 
 

  query 
  
 := 
  
 datastore 
 . 
 NewQuery 
 ( 
 "Task" 
 ). 
 Order 
 ( 
 "created" 
 ) 
 

  Query<Entity> 
  
 query 
  
 = 
  
 Query 
 . 
 newEntityQueryBuilder 
 (). 
 setKind 
 ( 
 "Task" 
 ). 
 setOrderBy 
 ( 
 OrderBy 
 . 
 asc 
 ( 
 "created" 
 )). 
 build 
 (); 
 

  const 
  
 query 
  
 = 
  
 datastore 
 . 
 createQuery 
 ( 
 'Task' 
 ). 
 order 
 ( 
 'created' 
 ); 
 

  $query = $datastore->query() 
 ->kind('Task') 
 ->order('created'); 
 

  from 
  
 google.cloud 
  
 import 
  datastore 
 
 # For help authenticating your client, visit 
 # https://cloud.google.com/docs/authentication/getting-started 
 client 
 = 
  datastore 
 
 . 
  Client 
 
 () 
 query 
 = 
 client 
 . 
  query 
 
 ( 
 kind 
 = 
 "Task" 
 ) 
 query 
 . 
  order 
 
 = 
 [ 
 "created" 
 ] 
 

  query 
  
 = 
  
 datastore 
 . 
 query 
 ( 
 "Task" 
 ) 
  
 . 
 order 
 ( 
 "created" 
 , 
  
 :asc 
 ) 
 

 SELECT 
  
 * 
  
 FROM 
  
 Task 
  
 ORDER 
  
 BY 
  
 created 
  
 ASC 

This example sorts Task entities by creation time in descending order:

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 ( 
 "Task" 
 ) 
 { 
  
 Order 
  
 = 
  
 { 
  
 { 
  
 "created" 
 , 
  
 PropertyOrder 
 . 
 Types 
 . 
 Direction 
 . 
 Descending 
  
 } 
  
 } 
 }; 
 

  query 
  
 := 
  
 datastore 
 . 
 NewQuery 
 ( 
 "Task" 
 ). 
 Order 
 ( 
 "-created" 
 ) 
 

  Query<Entity> 
  
 query 
  
 = 
  
 Query 
 . 
 newEntityQueryBuilder 
 (). 
 setKind 
 ( 
 "Task" 
 ). 
 setOrderBy 
 ( 
 OrderBy 
 . 
 desc 
 ( 
 "created" 
 )). 
 build 
 (); 
 

  const 
  
 query 
  
 = 
  
 datastore 
 . 
 createQuery 
 ( 
 'Task' 
 ). 
 order 
 ( 
 'created' 
 , 
  
 { 
  
 descending 
 : 
  
 true 
 , 
 }); 
 

  $query = $datastore->query() 
 ->kind('Task') 
 ->order('created', Query::ORDER_DESCENDING); 
 

  from 
  
 google.cloud 
  
 import 
  datastore 
 
 # For help authenticating your client, visit 
 # https://cloud.google.com/docs/authentication/getting-started 
 client 
 = 
  datastore 
 
 . 
  Client 
 
 () 
 query 
 = 
 client 
 . 
  query 
 
 ( 
 kind 
 = 
 "Task" 
 ) 
 query 
 . 
  order 
 
 = 
 [ 
 "-created" 
 ] 
 

  query 
  
 = 
  
 datastore 
 . 
 query 
 ( 
 "Task" 
 ) 
  
 . 
 order 
 ( 
 "created" 
 , 
  
 :desc 
 ) 
 

 SELECT 
  
 * 
  
 FROM 
  
 Task 
  
 ORDER 
  
 BY 
  
 created 
  
 DESC 

If a query includes multiple sort orders, they are applied in the sequence specified. The following example sorts first by descending priority and then by ascending creation time:

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 ( 
 "Task" 
 ) 
 { 
  
 Order 
  
 = 
  
 { 
  
 { 
  
 "priority" 
 , 
  
 PropertyOrder 
 . 
 Types 
 . 
 Direction 
 . 
 Descending 
  
 }, 
  
 { 
  
 "created" 
 , 
  
 PropertyOrder 
 . 
 Types 
 . 
 Direction 
 . 
 Ascending 
  
 } 
  
 } 
 }; 
 

  query 
  
 := 
  
 datastore 
 . 
 NewQuery 
 ( 
 "Task" 
 ). 
 Order 
 ( 
 "-priority" 
 ). 
 Order 
 ( 
 "created" 
 ) 
 

  Query<Entity> 
  
 query 
  
 = 
  
 Query 
 . 
 newEntityQueryBuilder 
 () 
  
 . 
 setKind 
 ( 
 "Task" 
 ) 
  
 . 
 setOrderBy 
 ( 
 OrderBy 
 . 
 desc 
 ( 
 "priority" 
 ), 
  
 OrderBy 
 . 
 asc 
 ( 
 "created" 
 )) 
  
 . 
 build 
 (); 
 

  const 
  
 query 
  
 = 
  
 datastore 
  
 . 
 createQuery 
 ( 
 'Task' 
 ) 
  
 . 
 order 
 ( 
 'priority' 
 , 
  
 { 
  
 descending 
 : 
  
 true 
 , 
  
 }) 
  
 . 
 order 
 ( 
 'created' 
 ); 
 

  $query = $datastore->query() 
 ->kind('Task') 
 ->order('priority', Query::ORDER_DESCENDING) 
 ->order('created'); 
 

  from 
  
 google.cloud 
  
 import 
  datastore 
 
 # For help authenticating your client, visit 
 # https://cloud.google.com/docs/authentication/getting-started 
 client 
 = 
  datastore 
 
 . 
  Client 
 
 () 
 query 
 = 
 client 
 . 
  query 
 
 ( 
 kind 
 = 
 "Task" 
 ) 
 query 
 . 
  order 
 
 = 
 [ 
 "-priority" 
 , 
 "created" 
 ] 
 

  query 
  
 = 
  
 datastore 
 . 
 query 
 ( 
 "Task" 
 ) 
  
 . 
 order 
 ( 
 "priority" 
 , 
  
 :desc 
 ) 
  
 . 
 order 
 ( 
 "created" 
 , 
  
 :asc 
 ) 
 

 SELECT 
  
 * 
  
 FROM 
  
 Task 
  
 ORDER 
  
 BY 
  
 priority 
  
 DESC 
 , 
  
 created 
  
 ASC 

If no sort orders are specified, the results are returned in the order they are retrieved from Datastore mode.

Restrictions

Sort orders have the following restrictions:

• Because of the way Datastore mode executes queries, if a query specifies inequality filters on a property and sort orders on other properties, the property used in the inequality filters must be ordered before the other properties .
• If ordering is specified, the set of properties specified in the distinct on clause must appear before any non- distinct on properties in the sort orders . For more information, see grouping queries .
• Sort orders on properties with equality filters are all ignored .

Special query types

Some specific types of query deserve special mention:

!= Not equal

Use the not-equal ( != ) operator to return entities where the given property exists and doesn't match the comparison value.

  package 
  
 datastore_snippets 
 import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "cloud.google.com/go/datastore" 
  
 "google.golang.org/api/iterator" 
 ) 
 func 
  
 queryNotEquals 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 projectId 
  
 string 
 ) 
  
 error 
  
 { 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 datastore 
 . 
  NewClient 
 
 ( 
 ctx 
 , 
  
 projectId 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "NewClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 q 
  
 := 
  
 datastore 
 . 
  NewQuery 
 
 ( 
 "TaskList" 
 ) 
  
 q 
 . 
  FilterField 
 
 ( 
 "Task" 
 , 
  
 "!=" 
 , 
  
 [] 
 string 
 { 
 "notASimpleTask" 
 }) 
  
 it 
  
 := 
  
 client 
 . 
  Run 
 
 ( 
 ctx 
 , 
  
 q 
 ) 
  
 for 
  
 { 
  
 var 
  
 dst 
  
 struct 
  
 { 
  
 Task 
  
 string 
  
 } 
  
 key 
 , 
  
 err 
  
 := 
  
 it 
 . 
 Next 
 ( 
& dst 
 ) 
  
 if 
  
 err 
  
 == 
  
 iterator 
 . 
 Done 
  
 { 
  
 break 
  
 } 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 err 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Key retrieved: %v\n" 
 , 
  
 key 
 ) 
  
 } 
  
 return 
  
 nil 
 } 
 

  Query<Entity> 
  
 query 
  
 = 
  
 Query 
 . 
 newEntityQueryBuilder 
 () 
  
 . 
 setKind 
 ( 
 "Task" 
 ) 
  
 . 
 setFilter 
 ( 
 PropertyFilter 
 . 
 neq 
 ( 
 "category" 
 , 
  
 "Work" 
 )) 
  
 . 
 build 
 (); 
 

  query 
 = 
 client 
 . 
 query 
 ( 
 kind 
 = 
 "Task" 
 ) 
 query 
 . 
 add_filter 
 ( 
 "category" 
 , 
 "!=" 
 , 
 "work" 
 ) 
 

 SELECT 
  
 * 
  
 FROM 
  
 Task 
  
 WHERE 
  
 category 
  
 != 
  
 'work' 

This query returns every Task entity where the category property exists and is set to any value other than Work .

This query doesn't return entities where the category property doesn't exist. Not-equal ( != ) and NOT_IN queries exclude entities where the given property doesn't exist or where the property is excluded from indexing. A property exists when it's set to any value, including an empty string or null .

Limitations

Note the following limitations for != queries:

• Only entities where the given property exists can match the query.
• Only a single NOT_IN or != is allowed per query.

IN

Use the IN operator to combine up to 30 equality ( == ) clauses on the same property with a logical OR . An IN query returns entities where the given property matches any of the comparison values.

  package 
  
 datastore_snippets 
 import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "cloud.google.com/go/datastore" 
  
 "google.golang.org/api/iterator" 
 ) 
 func 
  
 queryIn 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 projectId 
  
 string 
 ) 
  
 error 
  
 { 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 datastore 
 . 
  NewClient 
 
 ( 
 ctx 
 , 
  
 projectId 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "NewClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 q 
  
 := 
  
 datastore 
 . 
  NewQuery 
 
 ( 
 "TaskList" 
 ) 
  
 q 
 . 
  FilterField 
 
 ( 
 "Task" 
 , 
  
 "in" 
 , 
  
 [] 
 string 
 { 
 "simpleTask" 
 , 
  
 "easyTask" 
 }) 
  
 it 
  
 := 
  
 client 
 . 
  Run 
 
 ( 
 ctx 
 , 
  
 q 
 ) 
  
 for 
  
 { 
  
 var 
  
 dst 
  
 struct 
  
 { 
  
 Task 
  
 string 
  
 } 
  
 key 
 , 
  
 err 
  
 := 
  
 it 
 . 
 Next 
 ( 
& dst 
 ) 
  
 if 
  
 err 
  
 == 
  
 iterator 
 . 
 Done 
  
 { 
  
 break 
  
 } 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 err 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Key retrieved: %v\n" 
 , 
  
 key 
 ) 
  
 } 
  
 return 
  
 nil 
 } 
 

  Query<Entity> 
  
 query 
  
 = 
  
 Query 
 . 
 newEntityQueryBuilder 
 () 
  
 . 
 setKind 
 ( 
 "Task" 
 ) 
  
 . 
 setFilter 
 ( 
 PropertyFilter 
 . 
 in 
 ( 
 "tag" 
 , 
  
 ListValue 
 . 
 of 
 ( 
 "learn" 
 , 
  
 "study" 
 ))) 
  
 . 
 build 
 (); 
 

  query 
 = 
 client 
 . 
 query 
 ( 
 kind 
 = 
 "Task" 
 ) 
 query 
 . 
 add_filter 
 ( 
 "tag" 
 , 
 "IN" 
 , 
 [ 
 "learn" 
 , 
 "study" 
 ]) 
 

 SELECT 
  
 * 
  
 FROM 
  
 Task 
  
 WHERE 
  
 tag 
  
 IN 
  
 ARRAY 
 ( 
 'learn' 
 , 
  
 'study' 
 ) 

This query returns every Task entity where the tag property is set to learn or study . This includes Task entities where the tag property includes one of these values but not the other.

NOT_IN

Use the NOT_IN operator to combine up to 10 not-equal ( != ) clauses on the same property with a logical AND . A NOT_IN query returns entities where the given property exists and doesn't match any of the comparison values.

  package 
  
 datastore_snippets 
 import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "cloud.google.com/go/datastore" 
  
 "google.golang.org/api/iterator" 
 ) 
 func 
  
 queryNotIn 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 projectId 
  
 string 
 ) 
  
 error 
  
 { 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 datastore 
 . 
  NewClient 
 
 ( 
 ctx 
 , 
  
 projectId 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "NewClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 q 
  
 := 
  
 datastore 
 . 
  NewQuery 
 
 ( 
 "TaskList" 
 ) 
  
 q 
 . 
  FilterField 
 
 ( 
 "Task" 
 , 
  
 "not-in" 
 , 
  
 [] 
 string 
 { 
 "notASimpleTask" 
 , 
  
 "notAnEasyTask" 
 }) 
  
 it 
  
 := 
  
 client 
 . 
  Run 
 
 ( 
 ctx 
 , 
  
 q 
 ) 
  
 for 
  
 { 
  
 var 
  
 dst 
  
 struct 
  
 { 
  
 Task 
  
 string 
  
 } 
  
 key 
 , 
  
 err 
  
 := 
  
 it 
 . 
 Next 
 ( 
& dst 
 ) 
  
 if 
  
 err 
  
 == 
  
 iterator 
 . 
 Done 
  
 { 
  
 break 
  
 } 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 err 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Key retrieved: %v\n" 
 , 
  
 key 
 ) 
  
 } 
  
 return 
  
 nil 
 } 
 

  Query<Entity> 
  
 query 
  
 = 
  
 Query 
 . 
 newEntityQueryBuilder 
 () 
  
 . 
 setKind 
 ( 
 "Task" 
 ) 
  
 . 
 setFilter 
 ( 
 PropertyFilter 
 . 
 not_in 
 ( 
 "category" 
 , 
  
 ListValue 
 . 
 of 
 ( 
 "Work" 
 , 
  
 "Chores" 
 , 
  
 "School" 
 ))) 
  
 . 
 build 
 (); 
 

  query 
 = 
 client 
 . 
 query 
 ( 
 kind 
 = 
 "Task" 
 ) 
 query 
 . 
 add_filter 
 ( 
 "category" 
 , 
 "NOT_IN" 
 , 
 [ 
 "work" 
 , 
 "chores" 
 , 
 "school" 
 ]) 
 

 SELECT 
  
 * 
  
 FROM 
  
 Task 
  
 WHERE 
  
 category 
  
 NOT 
  
 IN 
  
 ARRAY 
 ( 
 'work' 
 , 
  
 'chores' 
 , 
  
 'school' 
 ) 

This query doesn't return entities where the category entity doesn't exist. Not-equal ( != ) and NOT_IN queries exclude entities where the given property doesn't exist. A property exists when it's set to any value, including an empty string or null .

Limitations

Note the following limitations for NOT_IN queries:

• Only entities where the given property exists can match the query.
• Only a single NOT_IN or != is allowed per query.

Ancestor queries

An ancestor query limits its results to the specified entity and its descendants. This example returns all Task entities that have the specified TaskList entity as an ancestor:

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 ( 
 "Task" 
 ) 
 { 
  
 Filter 
  
 = 
  
 Filter 
 . 
 HasAncestor 
 ( 
 _db 
 . 
 CreateKeyFactory 
 ( 
 "TaskList" 
 ) 
  
 . 
 CreateKey 
 ( 
 keyName 
 )) 
 }; 
 

  ancestor 
  
 := 
  
 datastore 
 . 
 NameKey 
 ( 
 "TaskList" 
 , 
  
 "default" 
 , 
  
 nil 
 ) 
 query 
  
 := 
  
 datastore 
 . 
 NewQuery 
 ( 
 "Task" 
 ). 
 Ancestor 
 ( 
 ancestor 
 ) 
 

  Query<Entity> 
  
 query 
  
 = 
  
 Query 
 . 
 newEntityQueryBuilder 
 () 
  
 . 
 setKind 
 ( 
 "Task" 
 ) 
  
 . 
 setFilter 
 ( 
  
 PropertyFilter 
 . 
 hasAncestor 
 ( 
  
 datastore 
 . 
 newKeyFactory 
 (). 
 setKind 
 ( 
 "TaskList" 
 ). 
 newKey 
 ( 
 "default" 
 ))) 
  
 . 
 build 
 (); 
 

  const 
  
 ancestorKey 
  
 = 
  
 datastore 
 . 
 key 
 ([ 
 'TaskList' 
 , 
  
 'default' 
 ]); 
 const 
  
 query 
  
 = 
  
 datastore 
 . 
 createQuery 
 ( 
 'Task' 
 ). 
 hasAncestor 
 ( 
 ancestorKey 
 ); 
 

  $ancestorKey = $datastore->key('TaskList', 'default'); 
 $query = $datastore->query() 
 ->kind('Task') 
 ->hasAncestor($ancestorKey); 
 

  from 
  
 google.cloud 
  
 import 
  datastore 
 
 # For help authenticating your client, visit 
 # https://cloud.google.com/docs/authentication/getting-started 
 client 
 = 
  datastore 
 
 . 
  Client 
 
 () 
 # Query filters are omitted in this example as any ancestor queries with a 
 # non-key filter require a composite index. 
 ancestor 
 = 
 client 
 . 
  key 
 
 ( 
 "TaskList" 
 , 
 "default" 
 ) 
 query 
 = 
 client 
 . 
  query 
 
 ( 
 kind 
 = 
 "Task" 
 , 
 ancestor 
 = 
 ancestor 
 ) 
 

  # task_list_name = "default" 
 ancestor_key 
  
 = 
  
 datastore 
 . 
 key 
  
 "TaskList" 
 , 
  
 task_list_name 
 query 
  
 = 
  
 datastore 
 . 
 query 
 ( 
 "Task" 
 ) 
  
 . 
 ancestor 
 ( 
 ancestor_key 
 ) 
 

 SELECT 
  
 * 
  
 FROM 
  
 Task 
  
 WHERE 
  
 __key__ 
  
 HAS 
  
 ANCESTOR 
  
 KEY 
 ( 
 TaskList 
 , 
  
 'default' 
 ) 

Limitations on Ancestor queries

Note the following limitations for Ancestor queries:

• All evaluated disjunctions must have the same ancestor filter.

Kindless queries

A query with no kind and no ancestor retrieves all of the entities of an application from Datastore mode. Such kindless queries cannot include filters or sort orders on property values. They can, however, filter on entity keys and use ancestor filters. Key filters can be used by specifying __key__ as the property name:

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 () 
 { 
  
 Filter 
  
 = 
  
 Filter 
 . 
 GreaterThan 
 ( 
 "__key__" 
 , 
  
 _keyFactory 
 . 
 CreateKey 
 ( 
 "aTask" 
 )) 
 }; 
 

  query 
  
 := 
  
 datastore 
 . 
 NewQuery 
 ( 
 "" 
 ). 
 FilterField 
 ( 
 "__key__" 
 , 
  
 ">" 
 , 
  
 lastSeenKey 
 ) 
 

  Query<Entity> 
  
 query 
  
 = 
  
 Query 
 . 
 newEntityQueryBuilder 
 (). 
 setFilter 
 ( 
 PropertyFilter 
 . 
 gt 
 ( 
 "__key__" 
 , 
  
 lastSeenKey 
 )). 
 build 
 (); 
 

  const 
  
 query 
  
 = 
  
 datastore 
  
 . 
 createQuery 
 () 
  
 . 
 filter 
 ( 
 new 
  
 PropertyFilter 
 ( 
 '__key__' 
 , 
  
 '>' 
 , 
  
 lastSeenKey 
 )) 
  
 . 
 limit 
 ( 
 1 
 ); 
 

  $query = $datastore->query() 
 ->filter('__key__', '>', $lastSeenKey); 
 

  from 
  
 google.cloud 
  
 import 
  datastore 
 
 # For help authenticating your client, visit 
 # https://cloud.google.com/docs/authentication/getting-started 
 client 
 = 
  datastore 
 
 . 
  Client 
 
 () 
 last_seen_key 
 = 
 client 
 . 
  key 
 
 ( 
 "Task" 
 , 
 "a" 
 ) 
 query 
 = 
 client 
 . 
  query 
 
 () 
 query 
 . 
  key_filter 
 
 ( 
 last_seen_key 
 , 
 ">" 
 ) 
 

  query 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
 Datastore 
 :: 
 Query 
 . 
 new 
 query 
 . 
 where 
  
 "__key__" 
 , 
  
 ">" 
 , 
  
 last_seen_key 
 

 SELECT 
  
 * 
  
 WHERE 
  
 __key__ 
 > 
 KEY 
 ( 
 Task 
 , 
  
 'someTask' 
 ) 

Projection queries

Most 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 for just those specific properties of an entity that you actually need, at lower latency and cost than retrieving the entire entity.

Projection queries require the specified properties to be indexed.

Keys-only queries

A keys-only query (which is a type of projection query) returns just the keys of the result entities instead of the entities themselves, at lower latency and cost than retrieving entire entities.

It is often more economical to do a keys-only query first, and then fetch a subset of entities from the results, rather than executing a general query which may fetch more entities than you actually need.

Here's how to create a keys-only query:

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 ( 
 "Task" 
 ) 
 { 
  
 Projection 
  
 = 
  
 { 
  
 "__key__" 
  
 } 
 }; 
 

  query 
  
 := 
  
 datastore 
 . 
 NewQuery 
 ( 
 "Task" 
 ). 
 KeysOnly 
 () 
 

  Query<Key> 
  
 query 
  
 = 
  
 Query 
 . 
 newKeyQueryBuilder 
 (). 
 setKind 
 ( 
 "Task" 
 ). 
 build 
 (); 
 

  const 
  
 query 
  
 = 
  
 datastore 
 . 
 createQuery 
 (). 
 select 
 ( 
 '__key__' 
 ). 
 limit 
 ( 
 1 
 ); 
 

  $query = $datastore->query() 
 ->keysOnly(); 
 

  from 
  
 google.cloud 
  
 import 
  datastore 
 
 # For help authenticating your client, visit 
 # https://cloud.google.com/docs/authentication/getting-started 
 client 
 = 
  datastore 
 
 . 
  Client 
 
 () 
 query 
 = 
 client 
 . 
  query 
 
 () 
 query 
 . 
  keys_only 
 
 () 
 

  query 
  
 = 
  
 datastore 
 . 
 query 
 ( 
 "Task" 
 ) 
  
 . 
 select 
 ( 
 "__key__" 
 ) 
 

 SELECT 
  
 __key__ 
  
 FROM 
  
 Task 

A keys-only query is a small operation and counts as only a single entity read for the query itself.

Projections

Projection queries are similar to SQL queries of the form:

 SELECT priority, percent_complete FROM Task 

You can use all of the filtering and sorting features available for standard entity queries, but note these limitations .

The example SQL query returns abridged results with only the specified properties, priority and percent_complete , populated with values; all other properties are not populated. Here's how you construct this as a projection query:

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 ( 
 "Task" 
 ) 
 { 
  
 Projection 
  
 = 
  
 { 
  
 "priority" 
 , 
  
 "percent_complete" 
  
 } 
 }; 
 

  query 
  
 := 
  
 datastore 
 . 
 NewQuery 
 ( 
 "Task" 
 ). 
 Project 
 ( 
 "Priority" 
 , 
  
 "PercentComplete" 
 ) 
 

  Query<ProjectionEntity> 
  
 query 
  
 = 
  
 Query 
 . 
 newProjectionEntityQueryBuilder 
 () 
  
 . 
 setKind 
 ( 
 "Task" 
 ) 
  
 . 
 setProjection 
 ( 
 "priority" 
 , 
  
 "percent_complete" 
 ) 
  
 . 
 build 
 (); 
 

  const 
  
 query 
  
 = 
  
 datastore 
  
 . 
 createQuery 
 ( 
 'Task' 
 ) 
  
 . 
 select 
 ([ 
 'priority' 
 , 
  
 'percent_complete' 
 ]); 
 

  $query = $datastore->query() 
 ->kind('Task') 
 ->projection(['priority', 'percent_complete']); 
 

  from 
  
 google.cloud 
  
 import 
  datastore 
 
 # For help authenticating your client, visit 
 # https://cloud.google.com/docs/authentication/getting-started 
 client 
 = 
  datastore 
 
 . 
  Client 
 
 () 
 query 
 = 
 client 
 . 
  query 
 
 ( 
 kind 
 = 
 "Task" 
 ) 
 query 
 . 
  projection 
 
 = 
 [ 
 "priority" 
 , 
 "percent_complete" 
 ] 
 

  query 
  
 = 
  
 datastore 
 . 
 query 
 ( 
 "Task" 
 ) 
  
 . 
 select 
 ( 
 "priority" 
 , 
  
 "percent_complete" 
 ) 
 

 SELECT 
  
 priority 
 , 
  
 percent_complete 
  
 FROM 
  
 Task 

And here's how to run the projection query:

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 ( 
 "Task" 
 ) 
 { 
  
 Projection 
  
 = 
  
 { 
  
 "priority" 
 , 
  
 "percent_complete" 
  
 } 
 }; 
 List<long> 
  
 priorities 
  
 = 
  
 new 
  
 List<long> 
 (); 
 List<double> 
  
 percentCompletes 
  
 = 
  
 new 
  
 List<double> 
 (); 
 foreach 
  
 ( 
 var 
  
 entity 
  
 in 
  
 _db 
 . 
 RunQuery 
 ( 
 query 
 ). 
 Entities 
 ) 
 { 
  
 priorities 
 . 
 Add 
 (( 
 long 
 ) 
 entity 
 [ 
 "priority" 
 ]); 
  
 percentCompletes 
 . 
 Add 
 (( 
 double 
 ) 
 entity 
 [ 
 "percent_complete" 
 ]); 
 } 
 

  var 
  
 priorities 
  
 [] 
 int 
 var 
  
 percents 
  
 [] 
 float64 
 it 
  
 := 
  
 client 
 . 
 Run 
 ( 
 ctx 
 , 
  
 query 
 ) 
 for 
  
 { 
  
 var 
  
 task 
  
 Task 
  
 if 
  
 _ 
 , 
  
 err 
  
 := 
  
 it 
 . 
 Next 
 ( 
& task 
 ); 
  
 err 
  
 == 
  
 iterator 
 . 
 Done 
  
 { 
  
 break 
  
 } 
  
 else 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 log 
 . 
 Fatal 
 ( 
 err 
 ) 
  
 } 
  
 priorities 
  
 = 
  
 append 
 ( 
 priorities 
 , 
  
 task 
 . 
 Priority 
 ) 
  
 percents 
  
 = 
  
 append 
 ( 
 percents 
 , 
  
 task 
 . 
 PercentComplete 
 ) 
 } 
 

  List<Long> 
  
 priorities 
  
 = 
  
 new 
  
 LinkedList 
<> (); 
 List<Double> 
  
 percentCompletes 
  
 = 
  
 new 
  
 LinkedList 
<> (); 
 QueryResults<ProjectionEntity> 
  
 tasks 
  
 = 
  
 datastore 
 . 
 run 
 ( 
 query 
 ); 
 while 
  
 ( 
 tasks 
 . 
 hasNext 
 ()) 
  
 { 
  
 ProjectionEntity 
  
 task 
  
 = 
  
 tasks 
 . 
 next 
 (); 
  
 priorities 
 . 
 add 
 ( 
 task 
 . 
 getLong 
 ( 
 "priority" 
 )); 
  
 percentCompletes 
 . 
 add 
 ( 
 task 
 . 
 getDouble 
 ( 
 "percent_complete" 
 )); 
 } 
 

  async 
  
 function 
  
 runProjectionQuery 
 () 
  
 { 
  
 const 
  
 priorities 
  
 = 
  
 []; 
  
 const 
  
 percentCompletes 
  
 = 
  
 []; 
  
 const 
  
 [ 
 tasks 
 ] 
  
 = 
  
 await 
  
 datastore 
 . 
 runQuery 
 ( 
 query 
 ); 
  
 tasks 
 . 
 forEach 
 ( 
 task 
  
 = 
>  
 { 
  
 priorities 
 . 
 push 
 ( 
 task 
 . 
 priority 
 ); 
  
 percentCompletes 
 . 
 push 
 ( 
 task 
 . 
 percent_complete 
 ); 
  
 }); 
  
 return 
  
 { 
  
 priorities 
 : 
  
 priorities 
 , 
  
 percentCompletes 
 : 
  
 percentCompletes 
 , 
  
 }; 
 } 
 

  $priorities = array(); 
 $percentCompletes = array(); 
 $result = $datastore->runQuery($query); 
 /* @var Entity $task */ 
 foreach ($result as $task) { 
 $priorities[] = $task['priority']; 
 $percentCompletes[] = $task['percent_complete']; 
 } 
 

  priorities 
 = 
 [] 
 percent_completes 
 = 
 [] 
 for 
 task 
 in 
 query 
 . 
 fetch 
 (): 
 priorities 
 . 
 append 
 ( 
 task 
 [ 
 "priority" 
 ]) 
 percent_completes 
 . 
 append 
 ( 
 task 
 [ 
 "percent_complete" 
 ]) 
 

  priorities 
  
 = 
  
 [] 
 percent_completes 
  
 = 
  
 [] 
 datastore 
 . 
 run 
 ( 
 query 
 ) 
 . 
 each 
  
 do 
  
 | 
 task 
 | 
  
 priorities 
 << 
 task 
 [ 
 "priority" 
 ] 
  
 percent_completes 
 << 
 task 
 [ 
 "percent_complete" 
 ] 
 end 
 

A projection query that doesn't use the distinct on clause is a small operation and counts as only a single entity read for the query itself.

Grouping

Projection queries can use the distinct on clause to ensure that only the first result for each distinct combination of values for the specified properties will be returned. This will return only the first result for entities which have the same values for the properties that are being projected.

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 ( 
 "Task" 
 ) 
 { 
  
 Projection 
  
 = 
  
 { 
  
 "category" 
 , 
  
 "priority" 
  
 }, 
  
 DistinctOn 
  
 = 
  
 { 
  
 "category" 
  
 }, 
  
 Order 
  
 = 
  
 { 
  
 { 
  
 "category" 
 , 
  
 PropertyOrder 
 . 
 Types 
 . 
 Direction 
 . 
 Ascending 
 }, 
  
 { 
 "priority" 
 , 
  
 PropertyOrder 
 . 
 Types 
 . 
 Direction 
 . 
 Ascending 
  
 } 
  
 } 
 }; 
 

  query 
  
 := 
  
 datastore 
 . 
 NewQuery 
 ( 
 "Task" 
 ). 
  
 Project 
 ( 
 "Priority" 
 , 
  
 "Category" 
 ). 
  
 DistinctOn 
 ( 
 "Category" 
 ). 
  
 Order 
 ( 
 "Category" 
 ). 
 Order 
 ( 
 "Priority" 
 ) 
 

  Query<ProjectionEntity> 
  
 query 
  
 = 
  
 Query 
 . 
 newProjectionEntityQueryBuilder 
 () 
  
 . 
 setKind 
 ( 
 "Task" 
 ) 
  
 . 
 setProjection 
 ( 
 "category" 
 , 
  
 "priority" 
 ) 
  
 . 
 setDistinctOn 
 ( 
 "category" 
 ) 
  
 . 
 setOrderBy 
 ( 
 OrderBy 
 . 
 asc 
 ( 
 "category" 
 ), 
  
 OrderBy 
 . 
 asc 
 ( 
 "priority" 
 )) 
  
 . 
 build 
 (); 
 

  const 
  
 query 
  
 = 
  
 datastore 
  
 . 
 createQuery 
 ( 
 'Task' 
 ) 
  
 . 
 groupBy 
 ( 
 'category' 
 ) 
  
 . 
 order 
 ( 
 'category' 
 ) 
  
 . 
 order 
 ( 
 'priority' 
 ); 
 

  $query = $datastore->query() 
 ->kind('Task') 
 ->order('category') 
 ->order('priority') 
 ->projection(['category', 'priority']) 
 ->distinctOn('category'); 
 

  from 
  
 google.cloud 
  
 import 
  datastore 
 
 # For help authenticating your client, visit 
 # https://cloud.google.com/docs/authentication/getting-started 
 client 
 = 
  datastore 
 
 . 
  Client 
 
 () 
 query 
 = 
 client 
 . 
  query 
 
 ( 
 kind 
 = 
 "Task" 
 ) 
 query 
 . 
  distinct_on 
 
 = 
 [ 
 "category" 
 ] 
 query 
 . 
  order 
 
 = 
 [ 
 "category" 
 , 
 "priority" 
 ] 
 

  query 
  
 = 
  
 datastore 
 . 
 query 
 ( 
 "Task" 
 ) 
  
 . 
 select 
 ( 
 "category" 
 , 
  
 "priority" 
 ) 
  
 . 
 distinct_on 
 ( 
 "category" 
 ) 
  
 . 
 order 
 ( 
 "category" 
 ) 
  
 . 
 order 
 ( 
 "priority" 
 ) 
 

 SELECT 
  
 DISTINCT 
  
 ON 
  
 ( 
 category 
 ) 
  
 category 
 , 
  
 priority 
  
 FROM 
  
 Task 
 ORDER 
  
 BY 
  
 category 
 , 
  
 priority 

The set of properties specified in the distinct on clause must appear before any non- distinct on properties in the order by clause if order by is specified.

Aggregation queries

Firestore in Datastore mode supports the count() aggregation query. See Aggregation queries .

Range and inequality filters on multiple properties

Firestore in Datastore mode supports multiple inequality filters in a compound query. See Query using range and inequality filters on multiple properties .

Array values

Datastore mode indexes each unique array property value once per index. Thus to query if an array contains a value use an equality filter.

Consider the following when your query includes properties with array values.

Inequality Filters

Because 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.

If 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 Task has values fun and programming for property tag , it will not match the query:

  Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 ( 
 "Task" 
 ) 
 { 
  
 Filter 
  
 = 
  
 Filter 
 . 
 And 
 ( 
 Filter 
 . 
 GreaterThan 
 ( 
 "tag" 
 , 
  
 "learn" 
 ), 
  
 Filter 
 . 
 LessThan 
 ( 
 "tag" 
 , 
  
 "math" 
 )) 
 }; 
 

  query 
  
 := 
  
 datastore 
 . 
 NewQuery 
 ( 
 "Task" 
 ). 
  
 FilterField 
 ( 
 "Tag" 
 , 
  
 ">" 
 , 
  
 "learn" 
 ). 
  
 FilterField 
 ( 
 "Tag" 
 , 
  
 "<" 
 , 
  
 "math" 
 )