Class Datastore (8.7.0)

 $ gcloud beta emulators datastore start --no-legacy 

 \[datastore\] API endpoint: http://localhost:8005 \[datastore\] If you are using a library that supports the DATASTORE\_EMULATOR\_HOST environment variable, run: \[datastore\] \[datastore\] export DATASTORE\_EMULATOR\_HOST=localhost:8005 \[datastore\] \[datastore\] Dev App Server is now running. 

Package

Examples

Import the client library

const {Datastore} = require('@google-cloud/datastore');

Create a client that uses Application Default Credentials (ADC):

const datastore = new Datastore();

Create a client with explicit credentials:

const datastore = new Datastore({
  projectId: 'your-project-id',
  keyFilename: '/path/to/keyfile.json'
});

Retrieving Records

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();

// Records, called "entities" in Datastore, are retrieved by using a key. The
// key is more than a numeric identifier, it is a complex data structure that
// can be used to model relationships. The simplest key has a string `kind`
// value, and either a numeric `id` value, or a string `name` value.
//
// A single record can be retrieved with {@link Datastore#key} and
// {@link Datastore#get}.
//-
const key = datastore.key(['Company', 'Google']);

datastore.get(key, function(err, entity) {
  // entity = The record.
  // entity[datastore.KEY] = The key for this entity.
});

//-
// 
Querying Records
//
// Create a query with {@link Datastore#createQuery}.
//-
const query = datastore.createQuery('Company');

//-
// Multiple records can be found that match criteria with
// {@link Query#filter}.
//-
query.filter('location', 'CA');

//-
// Records can also be ordered with {@link Query#order}.
//-
query.order('name');

//-
// The number of records returned can be specified with
// {@link Query#limit}.
//-
query.limit(5);

//-
// Records' key structures can also be queried with
// {@link Query#hasAncestor}.
//-
const ancestorKey = datastore.key(['ParentCompany', 'Alphabet']);

query.hasAncestor(ancestorKey);

//-
// Run the query with {@link Datastore#runQuery}.
//-
datastore.runQuery(query, (err, entities) => {
  // entities = An array of records.

  // Access the Key object for an entity.
  const firstEntityKey = entities[0][datastore.KEY];
});

Paginating Records

// Imagine building a website that allows a user to sift through hundreds of
// their contacts. You'll likely want to only display a subset of these at
// once, so you set a limit.
//-
const express = require('express');
const app = express();

const NUM_RESULTS_PER_PAGE = 15;

app.get('/contacts', (req, res) => {
  const query = datastore.createQuery('Contacts')
    .limit(NUM_RESULTS_PER_PAGE);

  if (req.query.nextPageCursor) {
    query.start(req.query.nextPageCursor);
  }

  datastore.runQuery(query, (err, entities, info) => {
    if (err) {
      // Error handling omitted.
      return;
    }

    // Respond to the front end with the contacts and the cursoring token
    // from the query we just ran.
    const frontEndResponse = {
      contacts: entities
    };

    // Check if  more results may exist.
    if (info.moreResults !== datastore.NO_MORE_RESULTS) {
      frontEndResponse.nextPageCursor = info.endCursor;
    }

    res.render('contacts', frontEndResponse);
  });
});

Creating Records

// New entities can be created and persisted with {@link Datastore#save}.
// The entity must have a key to be saved. If you don't specify an
// identifier for the key, one is generated for you.
//
// We will create a key with a `name` identifier, "Google".
//-
const key = datastore.key(['Company', 'Google']);

const data = {
  name: 'Google',
  location: 'CA'
};

datastore.save({
  key: key,
  data: data
}, (err) => {
  if (!err) {
    // Record saved successfully.
  }
});

//-
// We can verify the data was saved by using {@link Datastore#get}.
//-
datastore.get(key, (err, entity) => {
  // entity = {
  //   name: 'Google',
  //   location: 'CA'
  // }
});

//-
// If we want to update this record, we can modify the data object and re-
// save it.
//-
data.symbol = 'GOOG';

datastore.save({
  key: key, // defined above (datastore.key(['Company', 'Google']))
  data: data
}, (err, entity) => {
  if (!err) {
    // Record updated successfully.
  }
});

Deleting Records

// Entities can be removed from Datastore by passing the entity's key object
// to {@link Datastore#delete}.
//-
const key = datastore.key(['Company', 'Google']);

datastore.delete(key, (err) => {
  if (!err) {
    // Record deleted successfully.
  }
});

Transactions

// Complex logic can be wrapped in a transaction with
// {@link Datastore#transaction}. All queries and updates run within
// the transaction will be applied when the `done` function is called.
//-
const transaction = datastore.transaction();

transaction.run((err) => {
  if (err) {
    // Error handling omitted.
  }

  const key = datastore.key(['Company', 'Google']);

  transaction.get(key, (err, entity) => {
    if (err) {
      // Error handling omitted.
    }

    entity.symbol = 'GOOG';

    transaction.save(entity);

    transaction.commit((err) => {
      if (!err) {
        // Transaction committed successfully.
      }
    });
  });
});

Queries with Ancestors

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();

const customerId1 = 2993844;
const customerId2 = 4993882;
const customerKey1 = datastore.key(['Customer', customerId1]);
const customerKey2 = datastore.key(['Customer', customerId2]);
const cookieKey1 = datastore.key(['Customer', customerId1, 'Cookie',
'cookie28839']); // child entity const cookieKey2 =
datastore.key(['Customer', customerId1, 'Cookie', 'cookie78984']); // child
entity const cookieKey3 = datastore.key(['Customer', customerId2, 'Cookie',
'cookie93911']); // child entity

const entities = [];

entities.push({
  key: customerKey1,
  data: {
    name: 'Jane Doe',
    address: '4848 Liller'
  }
});

entities.push({
  key: customerKey2,
  data: {
    name: 'John Smith',
    address: '4848 Pine'
  }
});

entities.push({
  key: cookieKey1,
  data: {
    cookieVal: 'dj83kks88rkld'
  }
});

entities.push({
  key: cookieKey2,
  data: {
    cookieVal: 'sj843ka99s'
  }
});

entities.push({
  key: cookieKey3,
  data: {
    cookieVal: 'otk82k2kw'
  }
});

datastore.upsert(entities);

const query = datastore.createQuery().hasAncestor(customerKey1);

datastore.runQuery(query, (err, entities) => {
  for (let entity of entities) {
    console.log(entity[datastore.KEY]);
  }
});

const query2 = datastore.createQuery().hasAncestor(customerKey2);

datastore.runQuery(query2, (err, entities) => {
  for (let entity of entities) {
    console.log(entity[datastore.KEY]);
  }
});

datastore.runQuery(query2, (entities) => {
  console.log(entities);
});

Constructors

(constructor)(options)

constructor(options?: DatastoreOptions);

Properties

auth

auth: GoogleAuth;

baseUrl_

baseUrl_?: string;

clients_

clients_: Map<string, ClientStub>;

customEndpoint_

customEndpoint_?: boolean;

DatastoreRequest

DatastoreRequest: typeof DatastoreRequest;

defaultBaseUrl_

defaultBaseUrl_: string;

KEY

KEY: typeof entity.KEY_SYMBOL;

KEY

static KEY: typeof entity.KEY_SYMBOL;

MORE_RESULTS_AFTER_CURSOR

MORE_RESULTS_AFTER_CURSOR: string;

MORE_RESULTS_AFTER_CURSOR

static MORE_RESULTS_AFTER_CURSOR: string;

MORE_RESULTS_AFTER_LIMIT

MORE_RESULTS_AFTER_LIMIT: string;

MORE_RESULTS_AFTER_LIMIT

static MORE_RESULTS_AFTER_LIMIT: string;

namespace

namespace?: string;

NO_MORE_RESULTS

NO_MORE_RESULTS: string;

NO_MORE_RESULTS

static NO_MORE_RESULTS: string;

options

options: DatastoreOptions;

port_

port_?: number;

Query

Query: typeof Query;

Transaction

Transaction: typeof Transaction;

Methods

createAggregationQuery(query)

createAggregationQuery(query: Query): AggregateQuery;

createQuery(kind)

createQuery(kind?: string): Query;

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const query = datastore.createQuery('Company');

createQuery(kind)

createQuery(kind?: string[]): Query;

createQuery(namespace, kind)

createQuery(namespace: string, kind: string): Query;

createQuery(namespace, kind)

createQuery(namespace: string, kind: string[]): Query;

determineBaseUrl_(customApiEndpoint)

determineBaseUrl_(customApiEndpoint?: string): void;

double(value)

double(value: number): entity.Double;

double(value)

static double(value: number): entity.Double;

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const threeDouble = datastore.double(3.0);

export(config)

export(config: ExportEntitiesConfig): Promise<LongRunningResponse>;

export(config, callback)

export(config: ExportEntitiesConfig, callback: LongRunningCallback): void;

geoPoint(coordinates)

geoPoint(coordinates: entity.Coordinates): entity.GeoPoint;

geoPoint(coordinates)

static geoPoint(coordinates: entity.Coordinates): entity.GeoPoint;

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const coordinates = {
  latitude: 40.6894,
  longitude: -74.0447
};

const geoPoint = datastore.geoPoint(coordinates);

//-
// List all companies that are located at 40.123 latitude
// and -74.0447 longitude.
//-
const query = datastore.createQuery('Company');
const companyQuery = query
  .filter('geoPoint.latitude', datastore.double(40.123))
  .filter('geoPoint.longitude', datastore.double(-74.0447));

getDatabaseId()

getDatabaseId(): string | undefined;

getIndexes(options)

getIndexes(options?: GetIndexesOptions): Promise<GetIndexesResponse>;

getIndexes(options, callback)

getIndexes(options: GetIndexesOptions, callback: GetIndexesCallback): void;

getIndexes(callback)

getIndexes(callback: GetIndexesCallback): void;

getIndexesStream(options)

getIndexesStream(options?: GetIndexesOptions): NodeJS.ReadableStream;

getProjectId()

getProjectId(): Promise<string>;

import(config)

import(config: ImportEntitiesConfig): Promise<LongRunningResponse>;

import(config, callback)

import(config: ImportEntitiesConfig, callback: LongRunningCallback): void;

index(id)

index(id: string): Index;

insert(entities)

insert(entities: Entities): Promise<InsertResponse>;

insert(entities, callback)

insert(entities: Entities, callback: InsertCallback): void;

int(value)

int(value: number | string): entity.Int;

int(value)

static int(value: number | string): entity.Int;

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const sevenInteger = datastore.int(7);

//-
// Create an Int to support long Key IDs.
//-
const key = datastore.key([
  'Kind',
  datastore.int('100000000000001234')
]);

isDouble(value)

isDouble(value?: {}): boolean;

isDouble(value)

static isDouble(value?: {}): boolean;

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
datastore.isDouble(0.42); // false
datastore.isDouble(datastore.double(0.42)); // true

isGeoPoint(value)

isGeoPoint(value?: {}): boolean;

isGeoPoint(value)

static isGeoPoint(value?: {}): boolean;

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const coordinates = {
  latitude: 0,
  longitude: 0
};

datastore.isGeoPoint(coordinates); // false
datastore.isGeoPoint(datastore.geoPoint(coordinates)); // true

isInt(value)

isInt(value?: {}): boolean;

isInt(value)

static isInt(value?: {}): boolean;

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
datastore.isInt(42); // false
datastore.isInt(datastore.int(42)); // true

isKey(value)

isKey(value?: {}): boolean;

isKey(value)

static isKey(value?: {}): boolean;

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
datastore.isKey({path: ['Company', 123]}); // false
datastore.isKey(datastore.key(['Company', 123])); // true

key(options)

key(options: entity.KeyOptions): entity.Key;

Create an incomplete key with a kind value of `Company`.
Since no Id is supplied, Datastore will generate one on save.
const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const key = datastore.key('Company');

Create a complete key with a kind value of `Company` and Id `123`.
const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const key = datastore.key(['Company', 123]);

If the ID integer is outside the bounds of a JavaScript Number
object, create an Int.
const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const key = datastore.key([
  'Company',
  datastore.int('100000000000001234')
]);

Create a complete key with a kind value of `Company` and name `Google`.
Because the supplied Id is a string, Datastore will prefix it with "name=".
Had the supplied Id been numeric, Datastore would prefix it with the standard, "id=".
const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const key = datastore.key(['Company', 'Google']);

Create a complete key from a provided namespace and path.
const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const key = datastore.key({
  namespace: 'My-NS',
  path: ['Company', 123]
});

Create a complete key that specifies an ancestor. This will create a Team entity
with a name of "Datastore", which belongs to the Company with the "name=Google" key.
const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const key = datastore.key(['Company', 'Google', 'Team', 'Datastore']);

Create a incomplete key that specifies an ancestor. This will create an Employee entity
with an auto-generated Id, which belongs to the Company with the "name=Google" key.
const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const key = datastore.key(['Company', 'Google', 'Employee']);

key(path)

key(path: PathType[]): entity.Key;

key(path)

key(path: string): entity.Key;

keyFromLegacyUrlsafe(key)

keyFromLegacyUrlsafe(key: string): entity.Key;

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const urlSafeKey = 'ag9ncmFzcy1jbHVtcC00NzlyEwsSB0NvbXBhbnkiBkdvb2dsZQw';

datastore.keyFromLegacyUrlsafe(key);

keyToLegacyUrlSafe(key, locationPrefix)

keyToLegacyUrlSafe(key: entity.Key, locationPrefix?: string): Promise<string>;

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const key = datastore.key(['Company', 'Google']);

datastore.keyToLegacyUrlSafe(key, (err, urlSafeKey) => {
  if (err) {
    // Error handling omitted.
  }
  console.log(urlSafeKey);
});

//-
// Create a complete URL-safe key using a location prefix.
//-
const locationPrefix = 's~';

datastore.keyToLegacyUrlSafe(key, locationPrefix, (err, urlSafeKey) => {
  if (err) {
    // Error handling omitted.
  }
  console.log(urlSafeKey);
});

//-
// If the callback is omitted, we'll return a Promise.
//-
datastore.keyToLegacyUrlSafe(key).then((data) => {
  const urlSafeKey = data[0];
  console.log(urlSafeKey);
});

keyToLegacyUrlSafe(key, callback)

keyToLegacyUrlSafe(key: entity.Key, callback: KeyToLegacyUrlSafeCallback): void;

keyToLegacyUrlSafe(key, locationPrefix, callback)

keyToLegacyUrlSafe(key: entity.Key, locationPrefix: string, callback: KeyToLegacyUrlSafeCallback): void;

save(entities, gaxOptions)

save(entities: Entities, gaxOptions?: CallOptions): Promise<SaveResponse>;

//-
// Save a single entity.
//
// Notice that we are providing an incomplete key. After saving, the
// original Key object used to save will be updated to contain the path
// with its generated ID.
//-
const key = datastore.key('Company');
const entity = {
  key: key,
  data: {
    rating: '10'
  }
};

datastore.save(entity, (err) => {
  console.log(key.path); // [ 'Company', 5669468231434240 ]
  console.log(key.namespace); // undefined
});

//-
// Save a single entity using a provided name instead of auto-generated ID.
//
// Here we are providing a key with name instead of an ID. After saving,
// the original Key object used to save will be updated to contain the
// path with the name instead of a generated ID.
//-
const key = datastore.key(['Company', 'donutshack']);
const entity = {
  key: key,
  data: {
    name: 'DonutShack',
    rating: 8
  }
};

datastore.save(entity, (err) => {
  console.log(key.path); // ['Company', 'donutshack']
  console.log(key.namespace); // undefined
});

//-
// Save a single entity with a provided namespace. Namespaces allow for
// multitenancy. To read more about this, see
// [the Datastore docs on key concepts](https://goo.gl/M1LUAu).
//
// Here we are providing a key with namespace.
//-
const key = datastore.key({
  namespace: 'my-namespace',
  path: ['Company', 'donutshack']
});

const entity = {
  key: key,
  data: {
    name: 'DonutShack',
    rating: 8
  }
};

datastore.save(entity, (err) => {
  console.log(key.path); // ['Company', 'donutshack']
  console.log(key.namespace); // 'my-namespace'
});

//-
// Save different types of data, including ints, doubles, dates, booleans,
// blobs, and lists.
//
// Notice that we are providing an incomplete key. After saving, the
// original Key object used to save will be updated to contain the path
// with its generated ID.
//-
const key = datastore.key('Company');
const entity = {
  key: key,
  data: {
    name: 'DonutShack',
    rating: datastore.int(10),
    worth: datastore.double(123456.78),
    location: datastore.geoPoint({
      latitude: 40.6894,
      longitude: -74.0447
    }),
    numDonutsServed: 45,
    founded: new Date('Tue May 12 2015 15:30:00 GMT-0400 (EDT)'),
    isStartup: true,
    donutEmoji: Buffer.from('\uD83C\uDF69'),
    keywords: [
      'donut',
      'coffee',
      'yum'
    ]
  }
};

datastore.save(entity, (err, apiResponse) => {});

//-
// Use an array, `excludeFromIndexes`, to exclude properties from indexing.
// This will allow storing string values larger than 1500 bytes.
//-
const entity = {
  key: datastore.key('Company'),
  excludeFromIndexes: [
    'description',
    'embeddedEntity.description',
    'arrayValue[]',
    'arrayValue[].description'
  ],
  data: {
    description: 'Long string (...)',
    embeddedEntity: {
      description: 'Long string (...)'
    },
    arrayValue: [
      'Long string (...)',
      {
        description: 'Long string (...)'
      }
    ]
  }
};

datastore.save(entity, (err, apiResponse) => {});

//-
// Use boolean `excludeLargeProperties`, to auto exclude Large properties from indexing.
// This will allow storing string values larger than 1500 bytes.
//-
const entity = {
  key: datastore.key('Company'),
  data: {
    description: 'Long string (...)',
    embeddedEntity: {
      description: 'Long string (...)'
    },
    arrayValue: [
      'Long string (...)',
      {
        description: 'Long string (...)'
      }
    ]
  },
  excludeLargeProperties: true
};

datastore.save(entity, (err, apiResponse) => {});

//-
// Save multiple entities at once.
//-
const companyKey = datastore.key(['Company', 123]);
const productKey = datastore.key(['Product', 'Computer']);
const entities = [
  {
    key: companyKey,
    data: {
      HQ: 'Dallas, TX'
    }
  },
  {
    key: productKey,
    data: {
      vendor: 'Dell'
    }
  }
];

datastore.save(entities, (err, apiResponse) => {});

//-
// Explicitly attempt to 'insert' a specific entity.
//-
const userKey = datastore.key(['User', 'chilts']);
const entity = {
  key: userKey,
  method: 'insert',
  data: {
    fullName: 'Andrew Chilton'
  }
};

datastore.save(entity, (err, apiResponse) => {});

//-
// Returns a Promise if callback is omitted.
//-
datastore.save(entity).then((data) => {
  const apiResponse = data[0];
});

save(entities, gaxOptions, callback)

save(entities: Entities, gaxOptions: CallOptions, callback: SaveCallback): void;

save(entities, callback)

save(entities: Entities, callback: SaveCallback): void;

transaction(options)

transaction(options?: TransactionOptions): Transaction;

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const transaction = datastore.transaction();

update(entities)

update(entities: Entities): Promise<UpdateResponse>;

update(entities, callback)

update(entities: Entities, callback: UpdateCallback): void;

upsert(entities)

upsert(entities: Entities): Promise<UpsertResponse>;

upsert(entities, callback)

upsert(entities: Entities, callback: UpsertCallback): void;