diff --git a/lib/datastore/index.js b/lib/datastore/index.js index b94789ab246..815f9216a99 100644 --- a/lib/datastore/index.js +++ b/lib/datastore/index.js @@ -110,6 +110,15 @@ Datastore.dataset = Dataset; * server (usually "http://localhost:8080"). * @param {string} options.namespace - Namespace to isolate transactions to. * @return {module:datastore/dataset} + * + * @example + * var gcloud = require('gcloud')({ + * keyFilename: '/path/to/keyfile.json', + * projectId: 'my-project' + * }); + * + * var datastore = gcloud.datastore; + * var dataset = datastore.dataset(); */ Datastore.prototype.dataset = function(options) { options = options || {}; diff --git a/lib/datastore/query.js b/lib/datastore/query.js index 3c8c38eb746..9f09fd8ab5b 100644 --- a/lib/datastore/query.js +++ b/lib/datastore/query.js @@ -75,7 +75,25 @@ function Query(namespace, kinds) { } /** + * @param {boolean=} autoPaginateVal - Have pagination handled automatically. + * Default: true. * @return {module:datastore/query} + * + * @example + * // Retrieve a list of people related to person "1234", + * // disabling auto pagination + * var query = dataset.createQuery('Person') + * .hasAncestor(dataset.key(['Person', 1234])) + * .autoPaginate(false); + * + * var callback = function(err, entities, nextQuery, apiResponse) { + * if (nextQuery) { + * // More results might exist, so we'll manually fetch them + * dataset.runQuery(nextQuery, callback); + * } + * }; + * + * dataset.runQuery(query, callback); */ Query.prototype.autoPaginate = function(autoPaginateVal) { this.autoPaginateVal = autoPaginateVal !== false; diff --git a/lib/datastore/request.js b/lib/datastore/request.js index af72ed2fb74..8fa08e02084 100644 --- a/lib/datastore/request.js +++ b/lib/datastore/request.js @@ -118,14 +118,15 @@ function DatastoreRequest() {} * * @example * //- - * // Where you see `transaction`, assume this is the context that's relevant to - * // your use, whether that be a Dataset or Transaction object. + * // Get a single entity. * //- + * var key = dataset.key(['Company', 123]); + * + * dataset.get(key, function(err, entity) {}); * * //- - * // Get a single entity. + * // Or, if you're using a transaction object. * //- - * var key = dataset.key(['Company', 123]); * * transaction.get(key, function(err, entity) {}); * @@ -137,12 +138,12 @@ function DatastoreRequest() {} * dataset.key(['Product', 'Computer']) * ]; * - * transaction.get(keys, function(err, entities) {}); + * dataset.get(keys, function(err, entities) {}); * * //- * // Or, get the entities as a readable object stream. * //- - * transaction.get(keys) + * dataset.get(keys) * .on('error', function(err) {}) * .on('data', function(entity) { * // entity is an entity object. @@ -483,16 +484,18 @@ DatastoreRequest.prototype.save = function(entities, callback) { * @param {object} callback.apiResponse - The full API response. * * @example + * dataset.delete(dataset.key(['Company', 123]), function(err, apiResp) {}); + * * //- - * // Where you see `transaction`, assume this is the context that's relevant to - * // your use case, whether that be a Dataset or a Transaction object. + * // Or, if you're using a transaction object. * //- * - * // Delete a single entity. * transaction.delete(dataset.key(['Company', 123]), function(err, apiResp) {}); * + * //- * // Delete multiple entities at once. - * transaction.delete([ + * //- + * dataset.delete([ * dataset.key(['Company', 123]), * dataset.key(['Product', 'Computer']) * ], function(err, apiResponse) {}); @@ -555,11 +558,13 @@ DatastoreRequest.prototype.delete = function(keys, callback) { * //- * var query = dataset.createQuery('Lion'); * - * transaction.runQuery(query, function(err, entities) { - * if (!err) { - * // Handle entities here. - * } - * }); + * dataset.runQuery(query, function(err, entities) {}); + * + * //- + * // Or, if you're using a transaction object. + * //- + * + * transaction.runQuery(query, function(err, entities) {}); * * //- * // To control how many API requests are made and page through the results @@ -574,14 +579,14 @@ DatastoreRequest.prototype.delete = function(keys, callback) { * } * }; * - * transaction.runQuery(manualPageQuery, callback); + * dataset.runQuery(manualPageQuery, callback); * * //- * // If you omit the callback, runQuery will automatically call subsequent * // queries until no results remain. Entity objects will be pushed as they are * // found. * //- - * transaction.runQuery(query) + * dataset.runQuery(query) * .on('error', console.error) * .on('data', function (entity) {}) * .on('end', function() { @@ -594,7 +599,7 @@ DatastoreRequest.prototype.delete = function(keys, callback) { * //- * var keysOnlyQuery = dataset.createQuery('Lion').select('__key__'); * - * transaction.runQuery(keysOnlyQuery, function(err, entities) { + * dataset.runQuery(keysOnlyQuery, function(err, entities) { * // entities[].key = Key object * // entities[].data = Empty object * }); @@ -644,15 +649,16 @@ DatastoreRequest.prototype.runQuery = function(query, callback) { * @param {object} callback.apiResponse - The full API response. * * @example - * //- - * // Where you see `transaction`, assume this is the context that's relevant to - * // your use, whether that be a Dataset or a Transaction object. - * //- - * * var incompleteKey = dataset.key(['Company']); * * // The following call will create 100 new IDs from the Company kind, which * // exists under the default namespace. + * dataset.allocateIds(incompleteKey, 100, function(err, keys) {}); + * + * //- + * // Or, if you're using a transaction object. + * //- + * * transaction.allocateIds(incompleteKey, 100, function(err, keys) {}); * * // You may prefer to create IDs from a non-default namespace by providing an @@ -664,7 +670,7 @@ DatastoreRequest.prototype.runQuery = function(query, callback) { * path: ['Company'] * }); * var callback = function(err, keys, apiResponse) {}; - * transaction.allocateIds(incompleteKey, 100, callback); + * dataset.allocateIds(incompleteKey, 100, callback); */ DatastoreRequest.prototype.allocateIds = function(incompleteKey, n, callback) { if (entity.isKeyComplete(incompleteKey)) {