Use entity keys in Cloud Datastore queries

To find entities by key, include a key literal or URL-safe key in your query. 

Console options

Query by kind and filter by key

1. Open  > Storage > Datastore in the console.

2. Click Entities in the lefthand menu.

3. Select Query by kind.

4. Select a kind from the Kinds menu. If your datastore has multiple namespaces, you will see a Namespace menu that you can choose from as well.

5. Click Filter entities to add a key filter row. Use the + icon and drop-down menus to add more types of filters if needed.

6. Enter a key literal or URL-safe key in the key filter row. 

7. Click Apply filters.

Learn more: use GQL in the console or use GQL programmatically.

Query by GQL and include a key

1. Go to   > Storage > Datastore in the console.

2. Click Entities in the lefthand menu.

3. Select Query by GQL.

4. If your datastore has multiple namespaces, you will see a Namespace menu you can choose from. Otherwise, skip this step.

5. Enter a query that references a key literal. Do not use a URL-safe key.

6. Click Run query.

Sample query

Queries use Google Query Language. This simple query finds entities based on their kind and key:

SELECT * FROM <kind> WHERE __key__ = <key>

• <kind> is the name of the entity kind. Do not wrap in single quotations.
• <key> is the entity key in the form of a key literal.

Query with a key literal:

SELECT * FROM person WHERE __key__ = key(user,'email@domain')

Full GQL query reference at cloud.google.com. 

Key format

Key literals

Format

• Basic format: key(<kind>, <identifier>)

• Has ancestor: Include the complete path: key(<kind>, <identifier>, <kind>, <identifier>, [...])

• In entity properties: Same as above, but include the namespace and/or project ID if either is different from entity where you are adding the property: key(PROJECT('<project ID>'), NAMESPACE('<namespace>'), <kind>, <identifier>, [...])

  • ​See the guidelines below for more help formatting.

Examples

• Key literal with custom name identifier: key(user, 'email@domain')

• Key literal with numeric ID identifier: key(user, 1234567890123456)

• Key literal for entity with ancestors: key(AncestorKind1, 'dad', AncestorKind2, 123, Kind, 'family')

• Key literal in entity property: In this example, the property type is key, the value is a key literal, and the key literal references entity in a different namespace and project. See the guidelines below.  key(PROJECT('your-company'), NAMESPACE('supermarket'), deli, 12345)

​Guidelines

• <kind> is the name of the entity kind. If the kind name includes spaces or quotation marks, wrap in backticks (`).

• <identifier> is a numeric ID or a custom name that identifies your entity. 

  • Wrap key identifiers in single quotations if they are custom names rather than numeric IDs. For example, custom name email@domain should be 'email@domain' in your key literal: key(user,'email@domain').

  • You can check identifiers in the Name/ID column of your entity list in the console. 

  • You can also check identifiers in your entity's key in the entity properties. Identifiers are included in the key either as id:<identifier> or name:<identifier>.

• Ancestor: Include the complete path in your key literal. An ancestor is a set of additional pairs of kinds and identifiers included in the entity key, along with the particular kind and identifier of the entity. Ancestors are used in Datastore to help organize entities. 

• Entity properties: You can specify a property of type key and enter the key literal of any entity as the value. This includes key literals for entities in a different project or namespace. If the namespace and/or project is different from that of the entity, include it in the key literal, as shown below.

  • Wrap the project ID and namespace in single double quotations (' or "). Project ID and namespace are case-insensitive.

  • For the default namespace, put nothing in between your quotation marks:  NAMESPACE('').

  • To specify the default namespace ([default]), put nothing in between your quotation marks:  NAMESPACE('')

  • ​Namespace and project ID are always supported in key literals, but only necessary for this scenario.
    
    Example:

  1. Your entity is in namespace farm and project ID my-company.

  2. You want to add a property of type key and enter a key literal as the value.

  3. However, the key literal references an entity in a diffeerent namespace and project: namespace supermarket and project ID your-company.

  4. In this case, you would specify both the namespace and the project ID in the key literal, because both are different from that of the entity where you are adding the property. That could look like this key literal:
     
     key(PROJECT('your-company'), NAMESPACE('supermarket'), deli, 12345)

  5. If only the namespace is different, you wouldn't need to include the project ID. You could just enter:
     
     key(NAMESPACE('supermarket'), deli, 12345)

Learn more: use GQL in the console or use GQL programmatically.

URL-safe keys

A URL-safe key is a base64-encoded, serialized version of your entity key. The encoding method is available in any Cloud Datastore client library. Open an entity in the console to check its URL-safe key. 

Only supported in key filters for query by kind. Not supported in query by GQL.

• Example: agVoZWxsb3IPCxIHQWNjb3VudBiZiwIM 

Learn more: use GQL in the console or use GQL programmatically.