Datastore

Example

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

Example

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

const geoPoint = datastore.geoPoint(coordinates);

Example

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')
]);

Example

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

Example

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

Example

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

Example

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

Example

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

//-
// The following call will create 100 new IDs from the Company kind, which
// exists under the default namespace.
//-
datastore.allocateIds(incompleteKey, 100, (err, keys) => {});

//-
// Or, if you're using a transaction object.
//-
const transaction = datastore.transaction();

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

  transaction.allocateIds(incompleteKey, 100, (err, keys) => {
    if (err) {
      // Error handling omitted.
    }

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

//-
// You may prefer to create IDs from a non-default namespace by providing
an
// incomplete key with a namespace. Similar to the previous example, the
call
// below will create 100 new IDs, but from the Company kind that exists
under
// the "ns-test" namespace.
//-
const incompleteKey = datastore.key({
  namespace: 'ns-test',
  path: ['Company']
});

function callback(err, keys, apiResponse) {}

datastore.allocateIds(incompleteKey, 100, callback);

//-
// Returns a Promise if callback is omitted.
//-
datastore.allocateIds(incompleteKey, 100).then((data) => {
  const keys = data[0];
  const apiResponse = data[1];
});

Example

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

Example

const keys = [
  datastore.key(['Company', 123]),
  datastore.key(['Product', 'Computer'])
];

datastore.createReadStream(keys)
  .on('error', (err) =>  {})
  .on('data', (entity) => {
    // entity is an entity object.
  })
  .on('end', () => {
    // All entities retrieved.
  });

Example

const key = datastore.key(['Company', 123]);
datastore.delete(key, (err, apiResp) => {});

//-
// Or, if you're using a transaction object.
//-
const transaction = datastore.transaction();

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

  transaction.delete(key);

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

//-
// Delete multiple entities at once.
//-
datastore.delete([
  datastore.key(['Company', 123]),
  datastore.key(['Product', 'Computer'])
], (err, apiResponse) => {});

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

Example

//-
// Get a single entity.
//-
const key = datastore.key(['Company', 123]);

datastore.get(key, (err, entity) => {});

//-
// Or, if you're using a transaction object.
//-
const transaction = datastore.transaction();

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

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

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

//-
// Get multiple entities at once with a callback.
//-
const keys = [
  datastore.key(['Company', 123]),
  datastore.key(['Product', 'Computer'])
];

datastore.get(keys, (err, entities) => {});

//-
// Below is how to update the value of an entity with the help of the
// `save` method.
//-
datastore.get(key, (err, entity) => {
  if (err) {
    // Error handling omitted.
  }

  entity.newValue = true;

  datastore.save({
    key: key,
    data: entity
  }, (err) => {});
});

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

Examples

Create an incomplete key with a kind value of `Company`.

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

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

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

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
// Create a complete key with a kind value of `Company` and name `Google`.
// Note: `id` is used for numeric identifiers and `name` is used otherwise.
const key = datastore.key(['Company', 'Google']);

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

Example

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

datastore.keyFromLegacyUrlsafe(key);

Example

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);
});

Example

//-
// Where you see `transaction`, assume this is the context that's relevant
to
// your use, whether that be a Datastore or a Transaction object.
//-
const query = datastore.createQuery('Lion');

datastore.runQuery(query, (err, entities, info) => {
  // entities = An array of records.

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

//-
// Or, if you're using a transaction object.
//-
const transaction = datastore.transaction();

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

  transaction.runQuery(query, (err, entities) => {
    if (err) {
      // Error handling omitted.
    }

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

//-
// A keys-only query returns just the keys of the result entities instead
of
// the entities themselves, at lower latency and cost.
//-
const keysOnlyQuery = datastore.createQuery('Lion').select('__key__');

datastore.runQuery(keysOnlyQuery, (err, entities) => {
  const keys = entities.map((entity) => {
    return entity[datastore.KEY];
  });
});

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

Example

datastore.runQueryStream(query)
  .on('error', console.error)
  .on('data', (entity) => {
    // Access the Key object for this entity.
    const key = entity[datastore.KEY];
  })
  .on('info', (info) => {})
  .on('end', () => {
    // All entities retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
datastore.runQueryStream(query)
  .on('data', (entity) => {
    this.end();
  });

Example

//-
// 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];
});

Example

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