Using Cloud Datastore

You can use Google Cloud Datastore to store application data from your App Engine app. Cloud Datastore is a database built for automatic scaling, high performance, and ease of application development.

This document describes how to use the Google Cloud Client Library to store and retrieve data using Cloud Datastore in an App Engine app.

Prerequisites and setup

Follow the instructions in "Hello, World!" for Node.js on App Engine to set up your environment and project, and to understand how Node.js apps are structured in App Engine. Write down and save your project ID, because you will need it to run the sample application described in this document.

Clone the repository

Download (clone) the sample:

$ git clone
$ cd nodejs-docs-samples/appengine/datastore

Edit project configuration and set dependencies

In app.yaml, set GCLOUD_PROJECT for your project. This value is your project ID.

# Copyright 2015-2016, Google, Inc.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# See the License for the specific language governing permissions and
# limitations under the License.

# [START app_yaml]
runtime: nodejs
vm: true

# [START env_variables]
    GCLOUD_PROJECT: <your-project-id>
# [END env_variables]
# [END app_yaml]

In package.json, set gcloud as a dependency, which provides the functions to use Cloud Datastore.

  "name": "appengine-datastore",
  "description": "Sample for Google Cloud Datastore on Google App Engine",
  "version": "0.0.1",
  "private": true,
  "license": "Apache Version 2.0",
  "author": "Google Inc.",
  "engines": {
    "node": "^4.2.2"
  "scripts": {
    "start": "node app.js",
    "test": "mocha -R spec -t 120000 --require intelli-espower-loader ../../test/_setup.js test/*.test.js"
  "dependencies": {
    "@google-cloud/datastore": "^0.1.1",
    "express": "^4.13.4"
  "devDependencies": {
    "mocha": "^3.0.2"

Application code

The sample application logs, retrieves, and displays visitor IPs. You can see that a log entry is a simple two-field class that is given the type visit, and is saved to Cloud Datastore using the Dataset save command. Then, the ten most recent visits are retrieved in descending order, using the Dataset runQuery command.

'use strict';

var express = require('express');
var crypto = require('crypto');

var app = express();
app.enable('trust proxy');

// By default, the client will authenticate using the service account file
// specified by the GOOGLE_APPLICATION_CREDENTIALS environment variable and use
// the project specified by the GCLOUD_PROJECT environment variable. See
// These environment variables are set automatically on Google App Engine
var Datastore = require('@google-cloud/datastore');

// Instantiate a datastore client
var datastore = Datastore();

 * Insert a visit record into the database.
 * @param {object} visit The visit record to insert.
 * @param {function} callback The callback function.
function insertVisit (visit, callback) {{
    key: datastore.key('visit'),
    data: visit
  }, function (err) {
    if (err) {
      return callback(err);
    return callback();

 * Retrieve the latest 10 visit records from the database.
 * @param {function} callback The callback function.
function getVisits (callback) {
  var query = datastore.createQuery('visit')

  datastore.runQuery(query, function (err, entities) {
    if (err) {
      return callback(err);
    return callback(null, (entity) {
      return 'Time: ' + + ', AddrHash: ' +;

app.get('/', function (req, res, next) {
  // Create a visit record to be stored in the database
  var visit = {
    timestamp: new Date(),
    // Store a hash of the visitor's ip address
    userIp: crypto.createHash('sha256').update(req.ip).digest('hex').substr(0, 7)

  insertVisit(visit, function (err) {
    if (err) {
      return next(err);

    // Query the last 10 visits from the datastore.
    getVisits(function (err, visits) {
      if (err) {
        return next(err);

      return res
        .set('Content-Type', 'text/plain')
        .send('Last 10 visits:\n' + visits.join('\n'));

var server = app.listen(process.env.PORT || 8080, function () {
  console.log('App listening on port %s', server.address().port);
  console.log('Press Ctrl+C to quit.');

Using index.yaml files

The sample app performs simple queries. More elaborate Datastore queries require one or more indexes, which you must specify in an index.yaml file that you upload along with your app. This file may be created manually, or generated automatically while testing your app locally.

For more information

For complete information on Cloud Datastore, including optimizations and concepts, see the Cloud Datastore documentation.

Send feedback about...

App Engine flexible environment for Node.js docs