Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)



Datasets: lookup

Requires authorization

Look up some entities by key. Try it now .

Request

HTTP request 

POST https://www.googleapis.com/datastore/v1beta2/datasets/datasetId/lookup

Parameters

Parameter name Value Description
Path parameters
datasetId string Identifies the dataset.

Authorization

This request requires authorization with at least one of the following scopes ( read more about authentication and authorization ).

Scope
https://www.googleapis.com/auth/datastore
https://www.googleapis.com/auth/userinfo.email

Request body

In the request body, supply data with the following structure: 

{
  "readOptions": {
    "readConsistency": string,
    "transaction": bytes
  },
  "keys": [
    {
      "partitionId": {
        "datasetId": string,
        "namespace": string
      },
      "path": [
        {
          "kind": string,
          "id": long,
          "name": string
        }
      ]
    }
  ]
}
Property name Value Description Notes
readOptions nested object Options for this lookup request. Optional.
readOptions. readConsistency string The read consistency to use. One of default , strong , or eventual . Cannot be set when transaction is set. Lookup and ancestor queries default to strong , global queries default to eventual and cannot be set to strong . Optional. Default is default .

Acceptable values are:
  • " DEFAULT ":
  • " EVENTUAL ":
  • " STRONG ":
readOptions. transaction bytes The transaction to use. Optional.
keys[] list Keys of entities to look up from the datastore.
keys[]. partitionId nested object Entities are partitioned into subsets, currently identified by a dataset (usually implicitly specified by the project) and namespace ID. Queries are scoped to a single partition.
keys[].partitionId. datasetId string The dataset ID.
keys[].partitionId. namespace string The namespace.
keys[]. path[] list The entity path. An entity path consists of one or more elements composed of a kind and a string or numerical identifier, which identify entities. The first element identifies a root entity , the second element identifies a child of the root entity, the third element a child of the second entity, and so forth. The entities identified by all prefixes of the path are called the element's ancestors . An entity path is always fully complete: ALL of the entity's ancestors are required to be in the path along with the entity identifier itself. The only exception is that in some documented cases, the identifier in the last path element (for the entity) itself may be omitted. A path can never be empty.
keys[].path[]. kind string The kind of the entity. A kind matching regex "__.*__" is reserved/read-only. A kind must not contain more than 500 characters. Cannot be "".
keys[].path[]. id long The ID of the entity. Never equal to zero. Values less than zero are discouraged and will not be supported in the future.
keys[].path[]. name string The name of the entity. A name matching regex "__.*__" is reserved/read-only. A name must not be more than 500 characters. Cannot be "".

Response

If successful, this method returns a response body with the following structure: 

{
  "header": {
    "kind": "datastore#responseHeader"
  },
  "found": [
    {
      "entity": {
        "key": {
          "partitionId": {
            "datasetId": string,
            "namespace": string
          },
          "path": [
            {
              "kind": string,
              "id": long,
              "name": string
            }
          ]
        },
        "properties": {
          (key): {
            "booleanValue": boolean,
            "integerValue": long,
            "doubleValue": double,
            "dateTimeValue": datetime,
            "keyValue": {
              "partitionId": {
                "datasetId": string,
                "namespace": string
              },
              "path": [
                {
                  "kind": string,
                  "id": long,
                  "name": string
                }
              ]
            },
            "blobKeyValue": string,
            "stringValue": string,
            "blobValue": bytes,
            "entityValue": (Entity),
            "listValue": [
              {
                "booleanValue": boolean,
                "integerValue": long,
                "doubleValue": double,
                "dateTimeValue": datetime,
                "keyValue": {
                  "partitionId": {
                    "datasetId": string,
                    "namespace": string
                  },
                  "path": [
                    {
                      "kind": string,
                      "id": long,
                      "name": string
                    }
                  ]
                },
                "blobKeyValue": string,
                "stringValue": string,
                "blobValue": bytes,
                "entityValue": (Entity),
                "listValue": [
                  (Value)
                ],
                "meaning": integer,
                "indexed": boolean
              }
            ],
            "meaning": integer,
            "indexed": boolean
          }
        }
      }
    }
  ],
  "missing": [
    {
      "entity": {
        "key": {
          "partitionId": {
            "datasetId": string,
            "namespace": string
          },
          "path": [
            {
              "kind": string,
              "id": long,
              "name": string
            }
          ]
        },
        "properties": {
          (key): {
            "booleanValue": boolean,
            "integerValue": long,
            "doubleValue": double,
            "dateTimeValue": datetime,
            "keyValue": {
              "partitionId": {
                "datasetId": string,
                "namespace": string
              },
              "path": [
                {
                  "kind": string,
                  "id": long,
                  "name": string
                }
              ]
            },
            "blobKeyValue": string,
            "stringValue": string,
            "blobValue": bytes,
            "entityValue": (Entity),
            "listValue": [
              {
                "booleanValue": boolean,
                "integerValue": long,
                "doubleValue": double,
                "dateTimeValue": datetime,
                "keyValue": {
                  "partitionId": {
                    "datasetId": string,
                    "namespace": string
                  },
                  "path": [
                    {
                      "kind": string,
                      "id": long,
                      "name": string
                    }
                  ]
                },
                "blobKeyValue": string,
                "stringValue": string,
                "blobValue": bytes,
                "entityValue": (Entity),
                "listValue": [
                  (Value)
                ],
                "meaning": integer,
                "indexed": boolean
              }
            ],
            "meaning": integer,
            "indexed": boolean
          }
        }
      }
    }
  ],
  "deferred": [
    {
      "partitionId": {
        "datasetId": string,
        "namespace": string
      },
      "path": [
        {
          "kind": string,
          "id": long,
          "name": string
        }
      ]
    }
  ]
}
Property name Value Description Notes
header. kind string Identifies what kind of resource this is. Value: the fixed string "datastore#responseHeader" .
found[] list Entities found.
found[]. entity nested object The resulting entity.
found[].entity. key nested object The entity's key.

An entity must have a key, unless otherwise documented (for example, an entity in Value.entityValue may have no key). An entity's kind is its key's path's last element's kind, or null if it has no key.

found[].entity.key. partitionId nested object Entities are partitioned into subsets, currently identified by a dataset (usually implicitly specified by the project) and namespace ID. Queries are scoped to a single partition.
found[].entity.key.partitionId. datasetId string The dataset ID.
found[].entity.key.partitionId. namespace string The namespace.
found[].entity.key. path[] list The entity path. An entity path consists of one or more elements composed of a kind and a string or numerical identifier, which identify entities. The first element identifies a root entity , the second element identifies a child of the root entity, the third element a child of the second entity, and so forth. The entities identified by all prefixes of the path are called the element's ancestors . An entity path is always fully complete: ALL of the entity's ancestors are required to be in the path along with the entity identifier itself. The only exception is that in some documented cases, the identifier in the last path element (for the entity) itself may be omitted. A path can never be empty.
found[].entity.key.path[]. kind string The kind of the entity. A kind matching regex "__.*__" is reserved/read-only. A kind must not contain more than 500 characters. Cannot be "".
found[].entity.key.path[]. id long The ID of the entity. Never equal to zero. Values less than zero are discouraged and will not be supported in the future.
found[].entity.key.path[]. name string The name of the entity. A name matching regex "__.*__" is reserved/read-only. A name must not be more than 500 characters. Cannot be "".
found[].entity. properties object The entity's properties.
found[].entity.properties. (key) nested object The name of the property. A property name matching regex "__.*__" is reserved. A reserved property name is forbidden in certain documented contexts. The name must not contain more than 500 characters. Cannot be "".
found[].entity.properties.(key). booleanValue boolean A boolean value.
found[].entity.properties.(key). integerValue long An integer value.
found[].entity.properties.(key). doubleValue double A double value.
found[].entity.properties.(key). dateTimeValue datetime A timestamp value.
found[].entity.properties.(key). keyValue nested object A key value.
found[].entity.properties.(key).keyValue. partitionId nested object Entities are partitioned into subsets, currently identified by a dataset (usually implicitly specified by the project) and namespace ID. Queries are scoped to a single partition.
found[].entity.properties.(key).keyValue.partitionId. datasetId string The dataset ID.
found[].entity.properties.(key).keyValue.partitionId. namespace string The namespace.
found[].entity.properties.(key).keyValue. path[] list The entity path. An entity path consists of one or more elements composed of a kind and a string or numerical identifier, which identify entities. The first element identifies a root entity , the second element identifies a child of the root entity, the third element a child of the second entity, and so forth. The entities identified by all prefixes of the path are called the element's ancestors . An entity path is always fully complete: ALL of the entity's ancestors are required to be in the path along with the entity identifier itself. The only exception is that in some documented cases, the identifier in the last path element (for the entity) itself may be omitted. A path can never be empty.
found[].entity.properties.(key).keyValue.path[]. kind string The kind of the entity. A kind matching regex "__.*__" is reserved/read-only. A kind must not contain more than 500 characters. Cannot be "".
found[].entity.properties.(key).keyValue.path[]. id long The ID of the entity. Never equal to zero. Values less than zero are discouraged and will not be supported in the future.
found[].entity.properties.(key).keyValue.path[]. name string The name of the entity. A name matching regex "__.*__" is reserved/read-only. A name must not be more than 500 characters. Cannot be "".
found[].entity.properties.(key). blobKeyValue string A blob key value.
found[].entity.properties.(key). stringValue string A UTF-8 encoded string value.
found[].entity.properties.(key). blobValue bytes A blob value.
found[].entity.properties.(key). entityValue nested object An entity value. May have no key. May have a key with an incomplete key path. May have a reserved/read-only key.
found[].entity.properties.(key). listValue[] list A list value. Cannot contain another list value. Cannot also have a meaning and indexing set.
found[].entity.properties.(key).listValue[]. booleanValue boolean A boolean value.
found[].entity.properties.(key).listValue[]. integerValue long An integer value.
found[].entity.properties.(key).listValue[]. doubleValue double A double value.
found[].entity.properties.(key).listValue[]. dateTimeValue datetime A timestamp value.
found[].entity.properties.(key).listValue[]. keyValue nested object A key value.
found[].entity.properties.(key).listValue[].keyValue. partitionId nested object Entities are partitioned into subsets, currently identified by a dataset (usually implicitly specified by the project) and namespace ID. Queries are scoped to a single partition.
found[].entity.properties.(key).listValue[].keyValue.partitionId. datasetId string The dataset ID.
found[].entity.properties.(key).listValue[].keyValue.partitionId. namespace string The namespace.
found[].entity.properties.(key).listValue[].keyValue. path[] list The entity path. An entity path consists of one or more elements composed of a kind and a string or numerical identifier, which identify entities. The first element identifies a root entity , the second element identifies a child of the root entity, the third element a child of the second entity, and so forth. The entities identified by all prefixes of the path are called the element's ancestors . An entity path is always fully complete: ALL of the entity's ancestors are required to be in the path along with the entity identifier itself. The only exception is that in some documented cases, the identifier in the last path element (for the entity) itself may be omitted. A path can never be empty.
found[].entity.properties.(key).listValue[].keyValue.path[]. kind string The kind of the entity. A kind matching regex "__.*__" is reserved/read-only. A kind must not contain more than 500 characters. Cannot be "".
found[].entity.properties.(key).listValue[].keyValue.path[]. id long The ID of the entity. Never equal to zero. Values less than zero are discouraged and will not be supported in the future.
found[].entity.properties.(key).listValue[].keyValue.path[]. name string The name of the entity. A name matching regex "__.*__" is reserved/read-only. A name must not be more than 500 characters. Cannot be "".
found[].entity.properties.(key).listValue[]. blobKeyValue string A blob key value.
found[].entity.properties.(key).listValue[]. stringValue string A UTF-8 encoded string value.
found[].entity.properties.(key).listValue[]. blobValue bytes A blob value.
found[].entity.properties.(key).listValue[]. entityValue nested object An entity value. May have no key. May have a key with an incomplete key path. May have a reserved/read-only key.
found[].entity.properties.(key).listValue[]. listValue[] list A list value. Cannot contain another list value. Cannot also have a meaning and indexing set.
found[].entity.properties.(key).listValue[]. meaning integer The meaning field is reserved and should not be used.
found[].entity.properties.(key).listValue[]. indexed boolean If the value should be indexed.

The indexed property may be set for a null value. When indexed is true , stringValue is limited to 500 characters and the blob value is limited to 500 bytes. Input values by default have indexed set to true ; however, you can explicitly set indexed to true if you want. (An output value never has indexed explicitly set to true .) If a value is itself an entity, it cannot have indexed set to true .

found[].entity.properties.(key). meaning integer The meaning field is reserved and should not be used.
found[].entity.properties.(key). indexed boolean If the value should be indexed.

The indexed property may be set for a null value. When indexed is true , stringValue is limited to 500 characters and the blob value is limited to 500 bytes. Input values by default have indexed set to true ; however, you can explicitly set indexed to true if you want. (An output value never has indexed explicitly set to true .) If a value is itself an entity, it cannot have indexed set to true .

missing[] list Entities not found, with only the key populated.
missing[]. entity nested object The resulting entity.
missing[].entity. key nested object The entity's key.

An entity must have a key, unless otherwise documented (for example, an entity in Value.entityValue may have no key). An entity's kind is its key's path's last element's kind, or null if it has no key.

missing[].entity.key. partitionId nested object Entities are partitioned into subsets, currently identified by a dataset (usually implicitly specified by the project) and namespace ID. Queries are scoped to a single partition.
missing[].entity.key.partitionId. datasetId string The dataset ID.
missing[].entity.key.partitionId. namespace string The namespace.
missing[].entity.key. path[] list The entity path. An entity path consists of one or more elements composed of a kind and a string or numerical identifier, which identify entities. The first element identifies a root entity , the second element identifies a child of the root entity, the third element a child of the second entity, and so forth. The entities identified by all prefixes of the path are called the element's ancestors . An entity path is always fully complete: ALL of the entity's ancestors are required to be in the path along with the entity identifier itself. The only exception is that in some documented cases, the identifier in the last path element (for the entity) itself may be omitted. A path can never be empty.
missing[].entity.key.path[]. kind string The kind of the entity. A kind matching regex "__.*__" is reserved/read-only. A kind must not contain more than 500 characters. Cannot be "".
missing[].entity.key.path[]. id long The ID of the entity. Never equal to zero. Values less than zero are discouraged and will not be supported in the future.
missing[].entity.key.path[]. name string The name of the entity. A name matching regex "__.*__" is reserved/read-only. A name must not be more than 500 characters. Cannot be "".
missing[].entity. properties object The entity's properties.
missing[].entity.properties. (key) nested object The name of the property. A property name matching regex "__.*__" is reserved. A reserved property name is forbidden in certain documented contexts. The name must not contain more than 500 characters. Cannot be "".
missing[].entity.properties.(key). booleanValue boolean A boolean value.
missing[].entity.properties.(key). integerValue long An integer value.
missing[].entity.properties.(key). doubleValue double A double value.
missing[].entity.properties.(key). dateTimeValue datetime A timestamp value.
missing[].entity.properties.(key). keyValue nested object A key value.
missing[].entity.properties.(key).keyValue. partitionId nested object Entities are partitioned into subsets, currently identified by a dataset (usually implicitly specified by the project) and namespace ID. Queries are scoped to a single partition.
missing[].entity.properties.(key).keyValue.partitionId. datasetId string The dataset ID.
missing[].entity.properties.(key).keyValue.partitionId. namespace string The namespace.
missing[].entity.properties.(key).keyValue. path[] list The entity path. An entity path consists of one or more elements composed of a kind and a string or numerical identifier, which identify entities. The first element identifies a root entity , the second element identifies a child of the root entity, the third element a child of the second entity, and so forth. The entities identified by all prefixes of the path are called the element's ancestors . An entity path is always fully complete: ALL of the entity's ancestors are required to be in the path along with the entity identifier itself. The only exception is that in some documented cases, the identifier in the last path element (for the entity) itself may be omitted. A path can never be empty.
missing[].entity.properties.(key).keyValue.path[]. kind string The kind of the entity. A kind matching regex "__.*__" is reserved/read-only. A kind must not contain more than 500 characters. Cannot be "".
missing[].entity.properties.(key).keyValue.path[]. id long The ID of the entity. Never equal to zero. Values less than zero are discouraged and will not be supported in the future.
missing[].entity.properties.(key).keyValue.path[]. name string The name of the entity. A name matching regex "__.*__" is reserved/read-only. A name must not be more than 500 characters. Cannot be "".
missing[].entity.properties.(key). blobKeyValue string A blob key value.
missing[].entity.properties.(key). stringValue string A UTF-8 encoded string value.
missing[].entity.properties.(key). blobValue bytes A blob value.
missing[].entity.properties.(key). entityValue nested object An entity value. May have no key. May have a key with an incomplete key path. May have a reserved/read-only key.
missing[].entity.properties.(key). listValue[] list A list value. Cannot contain another list value. Cannot also have a meaning and indexing set.
missing[].entity.properties.(key).listValue[]. booleanValue boolean A boolean value.
missing[].entity.properties.(key).listValue[]. integerValue long An integer value.
missing[].entity.properties.(key).listValue[]. doubleValue double A double value.
missing[].entity.properties.(key).listValue[]. dateTimeValue datetime A timestamp value.
missing[].entity.properties.(key).listValue[]. keyValue nested object A key value.
missing[].entity.properties.(key).listValue[].keyValue. partitionId nested object Entities are partitioned into subsets, currently identified by a dataset (usually implicitly specified by the project) and namespace ID. Queries are scoped to a single partition.
missing[].entity.properties.(key).listValue[].keyValue.partitionId. datasetId string The dataset ID.
missing[].entity.properties.(key).listValue[].keyValue.partitionId. namespace string The namespace.
missing[].entity.properties.(key).listValue[].keyValue. path[] list The entity path. An entity path consists of one or more elements composed of a kind and a string or numerical identifier, which identify entities. The first element identifies a root entity , the second element identifies a child of the root entity, the third element a child of the second entity, and so forth. The entities identified by all prefixes of the path are called the element's ancestors . An entity path is always fully complete: ALL of the entity's ancestors are required to be in the path along with the entity identifier itself. The only exception is that in some documented cases, the identifier in the last path element (for the entity) itself may be omitted. A path can never be empty.
missing[].entity.properties.(key).listValue[].keyValue.path[]. kind string The kind of the entity. A kind matching regex "__.*__" is reserved/read-only. A kind must not contain more than 500 characters. Cannot be "".
missing[].entity.properties.(key).listValue[].keyValue.path[]. id long The ID of the entity. Never equal to zero. Values less than zero are discouraged and will not be supported in the future.
missing[].entity.properties.(key).listValue[].keyValue.path[]. name string The name of the entity. A name matching regex "__.*__" is reserved/read-only. A name must not be more than 500 characters. Cannot be "".
missing[].entity.properties.(key).listValue[]. blobKeyValue string A blob key value.
missing[].entity.properties.(key).listValue[]. stringValue string A UTF-8 encoded string value.
missing[].entity.properties.(key).listValue[]. blobValue bytes A blob value.
missing[].entity.properties.(key).listValue[]. entityValue nested object An entity value. May have no key. May have a key with an incomplete key path. May have a reserved/read-only key.
missing[].entity.properties.(key).listValue[]. listValue[] list A list value. Cannot contain another list value. Cannot also have a meaning and indexing set.
missing[].entity.properties.(key).listValue[]. meaning integer The meaning field is reserved and should not be used.
missing[].entity.properties.(key).listValue[]. indexed boolean If the value should be indexed.

The indexed property may be set for a null value. When indexed is true , stringValue is limited to 500 characters and the blob value is limited to 500 bytes. Input values by default have indexed set to true ; however, you can explicitly set indexed to true if you want. (An output value never has indexed explicitly set to true .) If a value is itself an entity, it cannot have indexed set to true .

missing[].entity.properties.(key). meaning integer The meaning field is reserved and should not be used.
missing[].entity.properties.(key). indexed boolean If the value should be indexed.

The indexed property may be set for a null value. When indexed is true , stringValue is limited to 500 characters and the blob value is limited to 500 bytes. Input values by default have indexed set to true ; however, you can explicitly set indexed to true if you want. (An output value never has indexed explicitly set to true .) If a value is itself an entity, it cannot have indexed set to true .

deferred[] list A list of keys that were not looked up due to resource constraints.
deferred[]. partitionId nested object Entities are partitioned into subsets, currently identified by a dataset (usually implicitly specified by the project) and namespace ID. Queries are scoped to a single partition.
deferred[].partitionId. datasetId string The dataset ID.
deferred[].partitionId. namespace string The namespace.
deferred[]. path[] list The entity path. An entity path consists of one or more elements composed of a kind and a string or numerical identifier, which identify entities. The first element identifies a root entity , the second element identifies a child of the root entity, the third element a child of the second entity, and so forth. The entities identified by all prefixes of the path are called the element's ancestors . An entity path is always fully complete: ALL of the entity's ancestors are required to be in the path along with the entity identifier itself. The only exception is that in some documented cases, the identifier in the last path element (for the entity) itself may be omitted. A path can never be empty.
deferred[].path[]. kind string The kind of the entity. A kind matching regex "__.*__" is reserved/read-only. A kind must not contain more than 500 characters. Cannot be "".
deferred[].path[]. id long The ID of the entity. Never equal to zero. Values less than zero are discouraged and will not be supported in the future.
deferred[].path[]. name string The name of the entity. A name matching regex "__.*__" is reserved/read-only. A name must not be more than 500 characters. Cannot be "".

Try it!

Use the APIs Explorer below to call this method on live data and see the response. Alternatively, try the standalone Explorer .

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.