feat(model): dataset model support

package.json

@@ -44,7 +44,8 @@
     "pretest": "npm run compile",
     "posttest": "npm run check",
     "docs-test": "linkinator docs -r --skip www.googleapis.com",
-    "predocs-test": "npm run docs"
+    "predocs-test": "npm run docs",
+    "types": "dtsd bigquery v2 > ./src/types.d.ts"
   },
   "dependencies": {
     "@google-cloud/common": "^1.0.0",
@@ -74,6 +75,7 @@
     "@types/tmp": "0.1.0",
     "@types/uuid": "^3.4.4",
     "codecov": "^3.0.0",
+    "discovery-tsd": "^0.1.0",
     "eslint": "^5.0.0",
     "eslint-config-prettier": "^4.0.0",
     "eslint-plugin-node": "^9.0.0",

src/dataset.ts

@@ -43,6 +43,7 @@ import {
   TableMetadata,
   TableOptions,
 } from './table';
+import {Model} from './model';
 import bigquery from './types';
 
 export interface DatasetDeleteOptions {
@@ -55,6 +56,18 @@ export interface DatasetOptions {
 
 export type CreateDatasetOptions = bigquery.IDataset;
 
+export type GetModelsOptions = PagedRequest<bigquery.models.IListParams>;
+export type GetModelsResponse = PagedResponse<
+  Model,
+  GetModelsOptions,
+  bigquery.IListModelsResponse
+>;
+export type GetModelsCallback = PagedCallback<
+  Model,
+  GetModelsOptions,
+  bigquery.IListModelsResponse
+>;
+
 export type GetTablesOptions = PagedRequest<bigquery.tables.IListParams>;
 export type GetTablesResponse = PagedResponse<
   Table,
@@ -89,6 +102,7 @@ export type TableCallback = ResourceCallback<Table, bigquery.ITable>;
 class Dataset extends ServiceObject {
   bigQuery: BigQuery;
   location?: string;
+  getModelsStream: (options?: GetModelsOptions) => ResourceStream<Model>;
   getTablesStream: (options?: GetTablesOptions) => ResourceStream<Table>;
   constructor(bigQuery: BigQuery, id: string, options?: DatasetOptions) {
     const methods = {
@@ -288,6 +302,35 @@ class Dataset extends ServiceObject {
       },
     });
 
+    /**
+     * List all or some of the {module:bigquery/model} objects in your project
+     * as a readable object stream.
+     *
+     * @param {object} [options] Configuration object. See
+     *     {@link Dataset#getModels} for a complete list of options.
+     * @return {stream}
+     *
+     * @example
+     * const {BigQuery} = require('@google-cloud/bigquery');
+     * const bigquery = new BigQuery();
+     * const dataset = bigquery.dataset('institutions');
+     *
+     * dataset.getModelsStream()
+     *   .on('error', console.error)
+     *   .on('data', (model) => {})
+     *   .on('end', () => {
+     *     // All models have been retrieved
+     *   });
+     *
+     * @example <caption>If you anticipate many results, you can end a stream
+     * early to prevent unnecessary processing and API requests.</caption>
+     * dataset.getModelsStream()
+     *   .on('data', function(model) {
+     *     this.end();
+     *   });
+     */
+    this.getModelsStream = paginator.streamify<Model>('getModels');
+
     /**
      * List all or some of the {module:bigquery/table} objects in your project
      * as a readable object stream.
@@ -529,6 +572,91 @@ class Dataset extends ServiceObject {
     );
   }
 
+  getModels(options?: GetModelsOptions): Promise<GetModelsResponse>;
+  getModels(options: GetModelsOptions, callback: GetModelsCallback): void;
+  getModels(callback: GetModelsCallback): void;
+  /**
+   * Get a list of models.
+   *
+   * @see [Models: list API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/rest/v2/models/list}
+   *
+   * @param {object} [options] Configuration object.
+   * @param {boolean} [options.autoPaginate=true] Have pagination handled
+   *     automatically.
+   * @param {number} [options.maxApiCalls] Maximum number of API calls to make.
+   * @param {number} [options.maxResults] Maximum number of results to return.
+   * @param {string} [options.pageToken] Token returned from a previous call, to
+   *     request the next page of results.
+   * @param {function} [callback] The callback function.
+   * @param {?error} callback.err An error returned while making this request
+   * @param {Model[]} callback.models The list of models from
+   *     your Dataset.
+   * @returns {Promise}
+   *
+   * @example
+   * const {BigQuery} = require('@google-cloud/bigquery');
+   * const bigquery = new BigQuery();
+   * const dataset = bigquery.dataset('institutions');
+   *
+   * dataset.getModels((err, models) => {
+   *   // models is an array of `Model` objects.
+   * });
+   *
+   * @example <caption>To control how many API requests are made and page
+   * through the results manually, set `autoPaginate` to `false`.</caption>
+   * function manualPaginationCallback(err, models, nextQuery, apiResponse) {
+   *   if (nextQuery) {
+   *     // More results exist.
+   *     dataset.getModels(nextQuery, manualPaginationCallback);
+   *   }
+   * }
+   *
+   * dataset.getModels({
+   *   autoPaginate: false
+   * }, manualPaginationCallback);
+   *
+   * @example <caption>If the callback is omitted, we'll return a Promise.
+   * </caption>
+   * dataset.getModels().then((data) => {
+   *   const models = data[0];
+   * });
+   */
+  getModels(
+    optsOrCb?: GetModelsOptions | GetModelsCallback,
+    cb?: GetModelsCallback
+  ): void | Promise<GetModelsResponse> {
+    const options = typeof optsOrCb === 'object' ? optsOrCb : {};
+    const callback = typeof optsOrCb === 'function' ? optsOrCb : cb;
+
+    this.request(
+      {
+        uri: '/models',
+        qs: options,
+      },
+      (err: null | Error, resp: bigquery.IListModelsResponse) => {
+        if (err) {
+          callback!(err, null, null, resp);
+          return;
+        }
+
+        let nextQuery: {} | null = null;
+        if (resp.nextPageToken) {
+          nextQuery = extend({}, options, {
+            pageToken: resp.nextPageToken,
+          });
+        }
+
+        const models = (resp.models || []).map(modelObject => {
+          const model = this.model(modelObject.modelReference!.modelId!);
+          model.metadata = modelObject;
+          return model;
+        });
+
+        callback!(null, models, nextQuery, resp);
+      }
+    );
+  }
+
   /**
    * Get a list of tables.
    *
@@ -620,6 +748,29 @@ class Dataset extends ServiceObject {
     );
   }
 
+  /**
+   * Create a Model object.
+   *
+   * @throws {TypeError} if model ID is missing.
+   *
+   * @param {string} id The ID of the model.
+   * @return {Model}
+   *
+   * @example
+   * const {BigQuery} = require('@google-cloud/bigquery');
+   * const bigquery = new BigQuery();
+   * const dataset = bigquery.dataset('institutions');
+   *
+   * const model = dataset.model('my-model');
+   */
+  model(id: string): Model {
+    if (typeof id !== 'string') {
+      throw new TypeError('A model ID is required.');
+    }
+
+    return new Model(this, id);
+  }
+
   /**
    * Run a query scoped to your dataset.
    *
@@ -692,15 +843,15 @@ class Dataset extends ServiceObject {
  *
  * These methods can be auto-paginated.
  */
-paginator.extend(Dataset, ['getTables']);
+paginator.extend(Dataset, ['getModels', 'getTables']);
 
 /*! Developer Documentation
  *
  * All async methods (except for streams) will return a Promise in the event
  * that a callback is omitted.
  */
 promisifyAll(Dataset, {
-  exclude: ['table'],
+  exclude: ['model', 'table'],
 });
 
 /**

src/index.ts

@@ -27,6 +27,7 @@ import * as uuid from 'uuid';
 
 import {Dataset, DatasetOptions} from './dataset';
 import {Job, JobOptions, QueryResultsOptions} from './job';
+import {Model} from './model';
 import {
   Table,
   TableField,
@@ -1718,6 +1719,15 @@ export {Dataset};
  */
 export {Job};
 
+/**
+ * {@link Model} class.
+ *
+ * @name BigQuery.Model
+ * @see Model
+ * @type {constructor}
+ */
+export {Model};
+
 /**
  * {@link Table} class.
  *