From a865431f35549afb9a66289aed226f5158407608 Mon Sep 17 00:00:00 2001 From: Sebastian Schmidt Date: Thu, 20 Jan 2022 15:44:31 -0700 Subject: [PATCH] Run Owlbot --- .github/generated-files-bot.yml | 4 +- .github/workflows/ci.yaml | 2 +- .jsdoc.js | 4 +- README.md | 14 +- dev/src/v1/firestore_admin_client.ts | 396 ++++++++++++++- dev/src/v1/firestore_admin_client_config.json | 12 + dev/src/v1/firestore_admin_proto_list.json | 1 + dev/src/v1/firestore_client.ts | 2 +- dev/src/v1beta1/firestore_client.ts | 4 +- dev/test/gapic_firestore_admin_v1.ts | 460 +++++++++++++++++- dev/test/gapic_firestore_v1.ts | 2 +- dev/test/gapic_firestore_v1beta1.ts | 2 +- owlbot.py | 8 +- samples/README.md | 6 +- types/v1/firestore_admin_client.d.ts | 308 ++++++++++-- types/v1/firestore_client.d.ts | 420 ++++++++++++++-- types/v1beta1/firestore_client.d.ts | 420 ++++++++++++++-- 17 files changed, 1884 insertions(+), 181 deletions(-) diff --git a/.github/generated-files-bot.yml b/.github/generated-files-bot.yml index 992ccef4a..7bb7ce54c 100644 --- a/.github/generated-files-bot.yml +++ b/.github/generated-files-bot.yml @@ -8,9 +8,9 @@ generatedFiles: - path: '.github/generated-files-bot.+(yml|yaml)' message: '`.github/generated-files-bot.(yml|yaml)` should be updated in [`synthtool`](https://github.com/googleapis/synthtool)' - path: 'README.md' - message: '`README.md` is managed by [`synthtool`](https://github.com/googleapis/synthtool). However, a partials file can be used to update the README, e.g.: https://github.com/googleapis/nodejs-storage/blob/main/.readme-partials.yaml' + message: '`README.md` is managed by [`synthtool`](https://github.com/googleapis/synthtool). However, a partials file can be used to update the README, e.g.: https://github.com/googleapis/nodejs-storage/blob/master/.readme-partials.yaml' - path: 'samples/README.md' - message: '`samples/README.md` is managed by [`synthtool`](https://github.com/googleapis/synthtool). However, a partials file can be used to update the README, e.g.: https://github.com/googleapis/nodejs-storage/blob/main/.readme-partials.yaml' + message: '`samples/README.md` is managed by [`synthtool`](https://github.com/googleapis/synthtool). However, a partials file can be used to update the README, e.g.: https://github.com/googleapis/nodejs-storage/blob/master/.readme-partials.yaml' ignoreAuthors: - 'gcf-owl-bot[bot]' - 'yoshi-automation' diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index a9517884b..397792ed8 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -1,7 +1,7 @@ on: push: branches: - - main + - master pull_request: name: ci jobs: diff --git a/.jsdoc.js b/.jsdoc.js index c796b7836..8ec3fbeb9 100644 --- a/.jsdoc.js +++ b/.jsdoc.js @@ -1,4 +1,4 @@ -// Copyright 2021 Google LLC +// Copyright 2022 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -40,7 +40,7 @@ module.exports = { includePattern: '\\.js$' }, templates: { - copyright: 'Copyright 2021 Google LLC', + copyright: 'Copyright 2022 Google LLC', includeDate: false, sourceFiles: false, systemName: '@google-cloud/firestore', diff --git a/README.md b/README.md index 56a5401f7..2c4c9bc09 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Applications that use Google's Server SDKs should not be used in end-user e A comprehensive list of changes in each version may be found in -[the CHANGELOG](https://github.com/googleapis/nodejs-firestore/blob/main/CHANGELOG.md). +[the CHANGELOG](https://github.com/googleapis/nodejs-firestore/blob/master/CHANGELOG.md). * [Cloud Firestore Node.js Client API Reference][client-docs] * [Cloud Firestore Documentation][product-docs] @@ -102,13 +102,13 @@ quickstart(); ## Samples -Samples are in the [`samples/`](https://github.com/googleapis/nodejs-firestore/tree/main/samples) directory. Each sample's `README.md` has instructions for running its sample. +Samples are in the [`samples/`](https://github.com/googleapis/nodejs-firestore/tree/master/samples) directory. Each sample's `README.md` has instructions for running its sample. | Sample | Source Code | Try it | | --------------------------- | --------------------------------- | ------ | -| Limit-to-last-query | [source code](https://github.com/googleapis/nodejs-firestore/blob/main/samples/limit-to-last-query.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-firestore&page=editor&open_in_editor=samples/limit-to-last-query.js,samples/README.md) | -| Quickstart | [source code](https://github.com/googleapis/nodejs-firestore/blob/main/samples/quickstart.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-firestore&page=editor&open_in_editor=samples/quickstart.js,samples/README.md) | -| Solution-counters | [source code](https://github.com/googleapis/nodejs-firestore/blob/main/samples/solution-counters.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-firestore&page=editor&open_in_editor=samples/solution-counters.js,samples/README.md) | +| Limit-to-last-query | [source code](https://github.com/googleapis/nodejs-firestore/blob/master/samples/limit-to-last-query.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-firestore&page=editor&open_in_editor=samples/limit-to-last-query.js,samples/README.md) | +| Quickstart | [source code](https://github.com/googleapis/nodejs-firestore/blob/master/samples/quickstart.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-firestore&page=editor&open_in_editor=samples/quickstart.js,samples/README.md) | +| Solution-counters | [source code](https://github.com/googleapis/nodejs-firestore/blob/master/samples/solution-counters.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-firestore&page=editor&open_in_editor=samples/solution-counters.js,samples/README.md) | @@ -158,7 +158,7 @@ More Information: [Google Cloud Platform Launch Stages][launch_stages] ## Contributing -Contributions welcome! See the [Contributing Guide](https://github.com/googleapis/nodejs-firestore/blob/main/CONTRIBUTING.md). +Contributions welcome! See the [Contributing Guide](https://github.com/googleapis/nodejs-firestore/blob/master/CONTRIBUTING.md). Please note that this `README.md`, the `samples/README.md`, and a variety of configuration files in this repository (including `.nycrc` and `tsconfig.json`) @@ -170,7 +170,7 @@ to its templates in Apache Version 2.0 -See [LICENSE](https://github.com/googleapis/nodejs-firestore/blob/main/LICENSE) +See [LICENSE](https://github.com/googleapis/nodejs-firestore/blob/master/LICENSE) [client-docs]: https://cloud.google.com/nodejs/docs/reference/firestore/latest [product-docs]: https://cloud.google.com/firestore diff --git a/dev/src/v1/firestore_admin_client.ts b/dev/src/v1/firestore_admin_client.ts index 28b6c159b..d9ee94f56 100644 --- a/dev/src/v1/firestore_admin_client.ts +++ b/dev/src/v1/firestore_admin_client.ts @@ -1,4 +1,4 @@ -// Copyright 2021 Google LLC +// Copyright 2022 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -42,6 +42,32 @@ import {operationsProtos} from 'google-gax'; const version = require('../../../package.json').version; /** + * The Cloud Firestore Admin API. + * + * This API provides several administrative services for Cloud Firestore. + * + * Project, Database, Namespace, Collection, Collection Group, and Document are + * used as defined in the Google Cloud Firestore API. + * + * Operation: An Operation represents work being performed in the background. + * + * The index service manages Cloud Firestore indexes. + * + * Index creation is performed asynchronously. + * An Operation resource is created for each such asynchronous operation. + * The state of the operation (including any errors encountered) + * may be queried via the Operation resource. + * + * The Operations collection provides a record of actions performed for the + * specified Project (including any Operations in progress). Operations are not + * created directly but through calls on other collections or resources. + * + * An Operation that is done may be deleted so that it is no longer listed as + * part of the Operation collection. Operations are garbage collected after + * 30 days. By default, ListOperations will only return in progress and failed + * operations. To list completed operation, issue a ListOperations request with + * the filter `done: true`. + * * Operations are created by service `FirestoreAdmin`, but are accessed via * service `google.longrunning.Operations`. * @class @@ -179,6 +205,9 @@ export class FirestoreAdminClient { indexPathTemplate: new this._gaxModule.PathTemplate( 'projects/{project}/databases/{database}/collectionGroups/{collection}/indexes/{index}' ), + projectPathTemplate: new this._gaxModule.PathTemplate( + 'projects/{project}' + ), }; // Some of the methods on this service return "paged" results, @@ -233,6 +262,12 @@ export class FirestoreAdminClient { const importDocumentsMetadata = protoFilesRoot.lookup( '.google.firestore.admin.v1.ImportDocumentsMetadata' ) as gax.protobuf.Type; + const updateDatabaseResponse = protoFilesRoot.lookup( + '.google.firestore.admin.v1.Database' + ) as gax.protobuf.Type; + const updateDatabaseMetadata = protoFilesRoot.lookup( + '.google.firestore.admin.v1.UpdateDatabaseMetadata' + ) as gax.protobuf.Type; this.descriptors.longrunning = { createIndex: new this._gaxModule.LongrunningDescriptor( @@ -255,6 +290,11 @@ export class FirestoreAdminClient { importDocumentsResponse.decode.bind(importDocumentsResponse), importDocumentsMetadata.decode.bind(importDocumentsMetadata) ), + updateDatabase: new this._gaxModule.LongrunningDescriptor( + this.operationsClient, + updateDatabaseResponse.decode.bind(updateDatabaseResponse), + updateDatabaseMetadata.decode.bind(updateDatabaseMetadata) + ), }; // Put together the default options sent with requests. @@ -316,6 +356,9 @@ export class FirestoreAdminClient { 'listFields', 'exportDocuments', 'importDocuments', + 'getDatabase', + 'listDatabases', + 'updateDatabase', ]; for (const methodName of firestoreAdminStubMethods) { const callPromise = this.firestoreAdminStub.then( @@ -658,6 +701,178 @@ export class FirestoreAdminClient { this.initialize(); return this.innerApiCalls.getField(request, options, callback); } + /** + * Gets information about a database. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.name + * Required. A name of the form + * `projects/{project_id}/databases/{database_id}` + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Database]{@link google.firestore.admin.v1.Database}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1/firestore_admin.get_database.js + * region_tag:firestore_v1_generated_FirestoreAdmin_GetDatabase_async + */ + getDatabase( + request?: protos.google.firestore.admin.v1.IGetDatabaseRequest, + options?: CallOptions + ): Promise< + [ + protos.google.firestore.admin.v1.IDatabase, + protos.google.firestore.admin.v1.IGetDatabaseRequest | undefined, + {} | undefined + ] + >; + getDatabase( + request: protos.google.firestore.admin.v1.IGetDatabaseRequest, + options: CallOptions, + callback: Callback< + protos.google.firestore.admin.v1.IDatabase, + protos.google.firestore.admin.v1.IGetDatabaseRequest | null | undefined, + {} | null | undefined + > + ): void; + getDatabase( + request: protos.google.firestore.admin.v1.IGetDatabaseRequest, + callback: Callback< + protos.google.firestore.admin.v1.IDatabase, + protos.google.firestore.admin.v1.IGetDatabaseRequest | null | undefined, + {} | null | undefined + > + ): void; + getDatabase( + request?: protos.google.firestore.admin.v1.IGetDatabaseRequest, + optionsOrCallback?: + | CallOptions + | Callback< + protos.google.firestore.admin.v1.IDatabase, + | protos.google.firestore.admin.v1.IGetDatabaseRequest + | null + | undefined, + {} | null | undefined + >, + callback?: Callback< + protos.google.firestore.admin.v1.IDatabase, + protos.google.firestore.admin.v1.IGetDatabaseRequest | null | undefined, + {} | null | undefined + > + ): Promise< + [ + protos.google.firestore.admin.v1.IDatabase, + protos.google.firestore.admin.v1.IGetDatabaseRequest | undefined, + {} | undefined + ] + > | void { + request = request || {}; + let options: CallOptions; + if (typeof optionsOrCallback === 'function' && callback === undefined) { + callback = optionsOrCallback; + options = {}; + } else { + options = optionsOrCallback as CallOptions; + } + options = options || {}; + options.otherArgs = options.otherArgs || {}; + options.otherArgs.headers = options.otherArgs.headers || {}; + options.otherArgs.headers['x-goog-request-params'] = + gax.routingHeader.fromParams({ + name: request.name || '', + }); + this.initialize(); + return this.innerApiCalls.getDatabase(request, options, callback); + } + /** + * List all the databases in the project. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. A parent name of the form + * `projects/{project_id}` + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [ListDatabasesResponse]{@link google.firestore.admin.v1.ListDatabasesResponse}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1/firestore_admin.list_databases.js + * region_tag:firestore_v1_generated_FirestoreAdmin_ListDatabases_async + */ + listDatabases( + request?: protos.google.firestore.admin.v1.IListDatabasesRequest, + options?: CallOptions + ): Promise< + [ + protos.google.firestore.admin.v1.IListDatabasesResponse, + protos.google.firestore.admin.v1.IListDatabasesRequest | undefined, + {} | undefined + ] + >; + listDatabases( + request: protos.google.firestore.admin.v1.IListDatabasesRequest, + options: CallOptions, + callback: Callback< + protos.google.firestore.admin.v1.IListDatabasesResponse, + protos.google.firestore.admin.v1.IListDatabasesRequest | null | undefined, + {} | null | undefined + > + ): void; + listDatabases( + request: protos.google.firestore.admin.v1.IListDatabasesRequest, + callback: Callback< + protos.google.firestore.admin.v1.IListDatabasesResponse, + protos.google.firestore.admin.v1.IListDatabasesRequest | null | undefined, + {} | null | undefined + > + ): void; + listDatabases( + request?: protos.google.firestore.admin.v1.IListDatabasesRequest, + optionsOrCallback?: + | CallOptions + | Callback< + protos.google.firestore.admin.v1.IListDatabasesResponse, + | protos.google.firestore.admin.v1.IListDatabasesRequest + | null + | undefined, + {} | null | undefined + >, + callback?: Callback< + protos.google.firestore.admin.v1.IListDatabasesResponse, + protos.google.firestore.admin.v1.IListDatabasesRequest | null | undefined, + {} | null | undefined + > + ): Promise< + [ + protos.google.firestore.admin.v1.IListDatabasesResponse, + protos.google.firestore.admin.v1.IListDatabasesRequest | undefined, + {} | undefined + ] + > | void { + request = request || {}; + let options: CallOptions; + if (typeof optionsOrCallback === 'function' && callback === undefined) { + callback = optionsOrCallback; + options = {}; + } else { + options = optionsOrCallback as CallOptions; + } + options = options || {}; + options.otherArgs = options.otherArgs || {}; + options.otherArgs.headers = options.otherArgs.headers || {}; + options.otherArgs.headers['x-goog-request-params'] = + gax.routingHeader.fromParams({ + parent: request.parent || '', + }); + this.initialize(); + return this.innerApiCalls.listDatabases(request, options, callback); + } /** * Creates a composite index. This returns a {@link google.longrunning.Operation|google.longrunning.Operation} @@ -963,6 +1178,9 @@ export class FirestoreAdminClient { * cancelled before completion it may leave partial data behind in Google * Cloud Storage. * + * For more details on export behavior and output format, refer to: + * https://cloud.google.com/firestore/docs/manage-data/export-import + * * @param {Object} request * The request object that will be sent. * @param {string} request.name @@ -1260,6 +1478,145 @@ export class FirestoreAdminClient { protos.google.firestore.admin.v1.ImportDocumentsMetadata >; } + /** + * Updates a database. + * + * @param {Object} request + * The request object that will be sent. + * @param {google.firestore.admin.v1.Database} request.database + * Required. The database to update. + * @param {google.protobuf.FieldMask} request.updateMask + * The list of fields to be updated. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing + * a long running operation. Its `promise()` method returns a promise + * you can `await` for. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) + * for more details and examples. + * @example include:samples/generated/v1/firestore_admin.update_database.js + * region_tag:firestore_v1_generated_FirestoreAdmin_UpdateDatabase_async + */ + updateDatabase( + request?: protos.google.firestore.admin.v1.IUpdateDatabaseRequest, + options?: CallOptions + ): Promise< + [ + LROperation< + protos.google.firestore.admin.v1.IDatabase, + protos.google.firestore.admin.v1.IUpdateDatabaseMetadata + >, + protos.google.longrunning.IOperation | undefined, + {} | undefined + ] + >; + updateDatabase( + request: protos.google.firestore.admin.v1.IUpdateDatabaseRequest, + options: CallOptions, + callback: Callback< + LROperation< + protos.google.firestore.admin.v1.IDatabase, + protos.google.firestore.admin.v1.IUpdateDatabaseMetadata + >, + protos.google.longrunning.IOperation | null | undefined, + {} | null | undefined + > + ): void; + updateDatabase( + request: protos.google.firestore.admin.v1.IUpdateDatabaseRequest, + callback: Callback< + LROperation< + protos.google.firestore.admin.v1.IDatabase, + protos.google.firestore.admin.v1.IUpdateDatabaseMetadata + >, + protos.google.longrunning.IOperation | null | undefined, + {} | null | undefined + > + ): void; + updateDatabase( + request?: protos.google.firestore.admin.v1.IUpdateDatabaseRequest, + optionsOrCallback?: + | CallOptions + | Callback< + LROperation< + protos.google.firestore.admin.v1.IDatabase, + protos.google.firestore.admin.v1.IUpdateDatabaseMetadata + >, + protos.google.longrunning.IOperation | null | undefined, + {} | null | undefined + >, + callback?: Callback< + LROperation< + protos.google.firestore.admin.v1.IDatabase, + protos.google.firestore.admin.v1.IUpdateDatabaseMetadata + >, + protos.google.longrunning.IOperation | null | undefined, + {} | null | undefined + > + ): Promise< + [ + LROperation< + protos.google.firestore.admin.v1.IDatabase, + protos.google.firestore.admin.v1.IUpdateDatabaseMetadata + >, + protos.google.longrunning.IOperation | undefined, + {} | undefined + ] + > | void { + request = request || {}; + let options: CallOptions; + if (typeof optionsOrCallback === 'function' && callback === undefined) { + callback = optionsOrCallback; + options = {}; + } else { + options = optionsOrCallback as CallOptions; + } + options = options || {}; + options.otherArgs = options.otherArgs || {}; + options.otherArgs.headers = options.otherArgs.headers || {}; + options.otherArgs.headers['x-goog-request-params'] = + gax.routingHeader.fromParams({ + 'database.name': request.database!.name || '', + }); + this.initialize(); + return this.innerApiCalls.updateDatabase(request, options, callback); + } + /** + * Check the status of the long running operation returned by `updateDatabase()`. + * @param {String} name + * The operation name that will be passed. + * @returns {Promise} - The promise which resolves to an object. + * The decoded operation object has result and metadata field to get information from. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) + * for more details and examples. + * @example include:samples/generated/v1/firestore_admin.update_database.js + * region_tag:firestore_v1_generated_FirestoreAdmin_UpdateDatabase_async + */ + async checkUpdateDatabaseProgress( + name: string + ): Promise< + LROperation< + protos.google.firestore.admin.v1.Database, + protos.google.firestore.admin.v1.UpdateDatabaseMetadata + > + > { + const request = new operationsProtos.google.longrunning.GetOperationRequest( + {name} + ); + const [operation] = await this.operationsClient.getOperation(request); + const decodeOperation = new gax.Operation( + operation, + this.descriptors.longrunning.updateDatabase, + gax.createDefaultBackoffSettings() + ); + return decodeOperation as LROperation< + protos.google.firestore.admin.v1.Database, + protos.google.firestore.admin.v1.UpdateDatabaseMetadata + >; + } /** * Lists composite indexes. * @@ -1464,7 +1821,7 @@ export class FirestoreAdminClient { * Currently, {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} only supports listing fields * that have been explicitly overridden. To issue this query, call * {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} with the filter set to - * `indexConfig.usesAncestorConfig:false`. + * `indexConfig.usesAncestorConfig:false` . * * @param {Object} request * The request object that will be sent. @@ -1475,8 +1832,8 @@ export class FirestoreAdminClient { * The filter to apply to list results. Currently, * {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} only supports listing fields * that have been explicitly overridden. To issue this query, call - * {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} with the filter set to - * `indexConfig.usesAncestorConfig:false`. + * {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} with a filter that includes + * `indexConfig.usesAncestorConfig:false` . * @param {number} request.pageSize * The number of results to return. * @param {string} request.pageToken @@ -1576,8 +1933,8 @@ export class FirestoreAdminClient { * The filter to apply to list results. Currently, * {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} only supports listing fields * that have been explicitly overridden. To issue this query, call - * {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} with the filter set to - * `indexConfig.usesAncestorConfig:false`. + * {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} with a filter that includes + * `indexConfig.usesAncestorConfig:false` . * @param {number} request.pageSize * The number of results to return. * @param {string} request.pageToken @@ -1631,8 +1988,8 @@ export class FirestoreAdminClient { * The filter to apply to list results. Currently, * {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} only supports listing fields * that have been explicitly overridden. To issue this query, call - * {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} with the filter set to - * `indexConfig.usesAncestorConfig:false`. + * {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} with a filter that includes + * `indexConfig.usesAncestorConfig:false` . * @param {number} request.pageSize * The number of results to return. * @param {string} request.pageToken @@ -1902,6 +2259,29 @@ export class FirestoreAdminClient { return this.pathTemplates.indexPathTemplate.match(indexName).index; } + /** + * Return a fully-qualified project resource name string. + * + * @param {string} project + * @returns {string} Resource name string. + */ + projectPath(project: string) { + return this.pathTemplates.projectPathTemplate.render({ + project: project, + }); + } + + /** + * Parse the project from Project resource. + * + * @param {string} projectName + * A fully-qualified path representing Project resource. + * @returns {string} A string representing the project. + */ + matchProjectFromProjectName(projectName: string) { + return this.pathTemplates.projectPathTemplate.match(projectName).project; + } + /** * Terminate the gRPC channel and close the client. * diff --git a/dev/src/v1/firestore_admin_client_config.json b/dev/src/v1/firestore_admin_client_config.json index b73e97016..f2b58181b 100644 --- a/dev/src/v1/firestore_admin_client_config.json +++ b/dev/src/v1/firestore_admin_client_config.json @@ -69,6 +69,18 @@ "timeout_millis": 60000, "retry_codes_name": "non_idempotent", "retry_params_name": "default" + }, + "GetDatabase": { + "retry_codes_name": "non_idempotent", + "retry_params_name": "default" + }, + "ListDatabases": { + "retry_codes_name": "non_idempotent", + "retry_params_name": "default" + }, + "UpdateDatabase": { + "retry_codes_name": "non_idempotent", + "retry_params_name": "default" } } } diff --git a/dev/src/v1/firestore_admin_proto_list.json b/dev/src/v1/firestore_admin_proto_list.json index e50187de7..11c6963e5 100644 --- a/dev/src/v1/firestore_admin_proto_list.json +++ b/dev/src/v1/firestore_admin_proto_list.json @@ -1,4 +1,5 @@ [ + "../../protos/google/firestore/admin/v1/database.proto", "../../protos/google/firestore/admin/v1/field.proto", "../../protos/google/firestore/admin/v1/firestore_admin.proto", "../../protos/google/firestore/admin/v1/index.proto", diff --git a/dev/src/v1/firestore_client.ts b/dev/src/v1/firestore_client.ts index fd1aabf37..547d305c5 100644 --- a/dev/src/v1/firestore_client.ts +++ b/dev/src/v1/firestore_client.ts @@ -1,4 +1,4 @@ -// Copyright 2021 Google LLC +// Copyright 2022 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/dev/src/v1beta1/firestore_client.ts b/dev/src/v1beta1/firestore_client.ts index 077718d2a..ee9233ba3 100644 --- a/dev/src/v1beta1/firestore_client.ts +++ b/dev/src/v1beta1/firestore_client.ts @@ -1,4 +1,4 @@ -// Copyright 2021 Google LLC +// Copyright 2022 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -30,7 +30,7 @@ import { import {Transform} from 'stream'; import {RequestType} from 'google-gax/build/src/apitypes'; import * as protos from '../../protos/firestore_v1beta1_proto_api'; -import jsonProtos = require('../../protos/v1beta1.json'); +import jsonProtos = require('../../protos/protos.json'); /** * Client JSON configuration object, loaded from * `src/v1beta1/firestore_client_config.json`. diff --git a/dev/test/gapic_firestore_admin_v1.ts b/dev/test/gapic_firestore_admin_v1.ts index 85d34175c..a804d2c0e 100644 --- a/dev/test/gapic_firestore_admin_v1.ts +++ b/dev/test/gapic_firestore_admin_v1.ts @@ -1,4 +1,4 @@ -// Copyright 2021 Google LLC +// Copyright 2022 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -552,6 +552,228 @@ describe('v1.FirestoreAdminClient', () => { }); }); + describe('getDatabase', () => { + it('invokes getDatabase without error', async () => { + const client = new firestoreadminModule.FirestoreAdminClient({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + client.initialize(); + const request = generateSampleMessage( + new protos.google.firestore.admin.v1.GetDatabaseRequest() + ); + request.name = ''; + const expectedHeaderRequestParams = 'name='; + const expectedOptions = { + otherArgs: { + headers: { + 'x-goog-request-params': expectedHeaderRequestParams, + }, + }, + }; + const expectedResponse = generateSampleMessage( + new protos.google.firestore.admin.v1.Database() + ); + client.innerApiCalls.getDatabase = stubSimpleCall(expectedResponse); + const [response] = await client.getDatabase(request); + assert.deepStrictEqual(response, expectedResponse); + assert( + (client.innerApiCalls.getDatabase as SinonStub) + .getCall(0) + .calledWith(request, expectedOptions, undefined) + ); + }); + + it('invokes getDatabase without error using callback', async () => { + const client = new firestoreadminModule.FirestoreAdminClient({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + client.initialize(); + const request = generateSampleMessage( + new protos.google.firestore.admin.v1.GetDatabaseRequest() + ); + request.name = ''; + const expectedHeaderRequestParams = 'name='; + const expectedOptions = { + otherArgs: { + headers: { + 'x-goog-request-params': expectedHeaderRequestParams, + }, + }, + }; + const expectedResponse = generateSampleMessage( + new protos.google.firestore.admin.v1.Database() + ); + client.innerApiCalls.getDatabase = + stubSimpleCallWithCallback(expectedResponse); + const promise = new Promise((resolve, reject) => { + client.getDatabase( + request, + ( + err?: Error | null, + result?: protos.google.firestore.admin.v1.IDatabase | null + ) => { + if (err) { + reject(err); + } else { + resolve(result); + } + } + ); + }); + const response = await promise; + assert.deepStrictEqual(response, expectedResponse); + assert( + (client.innerApiCalls.getDatabase as SinonStub) + .getCall(0) + .calledWith(request, expectedOptions /*, callback defined above */) + ); + }); + + it('invokes getDatabase with error', async () => { + const client = new firestoreadminModule.FirestoreAdminClient({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + client.initialize(); + const request = generateSampleMessage( + new protos.google.firestore.admin.v1.GetDatabaseRequest() + ); + request.name = ''; + const expectedHeaderRequestParams = 'name='; + const expectedOptions = { + otherArgs: { + headers: { + 'x-goog-request-params': expectedHeaderRequestParams, + }, + }, + }; + const expectedError = new Error('expected'); + client.innerApiCalls.getDatabase = stubSimpleCall( + undefined, + expectedError + ); + await assert.rejects(client.getDatabase(request), expectedError); + assert( + (client.innerApiCalls.getDatabase as SinonStub) + .getCall(0) + .calledWith(request, expectedOptions, undefined) + ); + }); + }); + + describe('listDatabases', () => { + it('invokes listDatabases without error', async () => { + const client = new firestoreadminModule.FirestoreAdminClient({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + client.initialize(); + const request = generateSampleMessage( + new protos.google.firestore.admin.v1.ListDatabasesRequest() + ); + request.parent = ''; + const expectedHeaderRequestParams = 'parent='; + const expectedOptions = { + otherArgs: { + headers: { + 'x-goog-request-params': expectedHeaderRequestParams, + }, + }, + }; + const expectedResponse = generateSampleMessage( + new protos.google.firestore.admin.v1.ListDatabasesResponse() + ); + client.innerApiCalls.listDatabases = stubSimpleCall(expectedResponse); + const [response] = await client.listDatabases(request); + assert.deepStrictEqual(response, expectedResponse); + assert( + (client.innerApiCalls.listDatabases as SinonStub) + .getCall(0) + .calledWith(request, expectedOptions, undefined) + ); + }); + + it('invokes listDatabases without error using callback', async () => { + const client = new firestoreadminModule.FirestoreAdminClient({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + client.initialize(); + const request = generateSampleMessage( + new protos.google.firestore.admin.v1.ListDatabasesRequest() + ); + request.parent = ''; + const expectedHeaderRequestParams = 'parent='; + const expectedOptions = { + otherArgs: { + headers: { + 'x-goog-request-params': expectedHeaderRequestParams, + }, + }, + }; + const expectedResponse = generateSampleMessage( + new protos.google.firestore.admin.v1.ListDatabasesResponse() + ); + client.innerApiCalls.listDatabases = + stubSimpleCallWithCallback(expectedResponse); + const promise = new Promise((resolve, reject) => { + client.listDatabases( + request, + ( + err?: Error | null, + result?: protos.google.firestore.admin.v1.IListDatabasesResponse | null + ) => { + if (err) { + reject(err); + } else { + resolve(result); + } + } + ); + }); + const response = await promise; + assert.deepStrictEqual(response, expectedResponse); + assert( + (client.innerApiCalls.listDatabases as SinonStub) + .getCall(0) + .calledWith(request, expectedOptions /*, callback defined above */) + ); + }); + + it('invokes listDatabases with error', async () => { + const client = new firestoreadminModule.FirestoreAdminClient({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + client.initialize(); + const request = generateSampleMessage( + new protos.google.firestore.admin.v1.ListDatabasesRequest() + ); + request.parent = ''; + const expectedHeaderRequestParams = 'parent='; + const expectedOptions = { + otherArgs: { + headers: { + 'x-goog-request-params': expectedHeaderRequestParams, + }, + }, + }; + const expectedError = new Error('expected'); + client.innerApiCalls.listDatabases = stubSimpleCall( + undefined, + expectedError + ); + await assert.rejects(client.listDatabases(request), expectedError); + assert( + (client.innerApiCalls.listDatabases as SinonStub) + .getCall(0) + .calledWith(request, expectedOptions, undefined) + ); + }); + }); + describe('createIndex', () => { it('invokes createIndex without error', async () => { const client = new firestoreadminModule.FirestoreAdminClient({ @@ -1324,6 +1546,204 @@ describe('v1.FirestoreAdminClient', () => { }); }); + describe('updateDatabase', () => { + it('invokes updateDatabase without error', async () => { + const client = new firestoreadminModule.FirestoreAdminClient({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + client.initialize(); + const request = generateSampleMessage( + new protos.google.firestore.admin.v1.UpdateDatabaseRequest() + ); + request.database = {}; + request.database.name = ''; + const expectedHeaderRequestParams = 'database.name='; + const expectedOptions = { + otherArgs: { + headers: { + 'x-goog-request-params': expectedHeaderRequestParams, + }, + }, + }; + const expectedResponse = generateSampleMessage( + new protos.google.longrunning.Operation() + ); + client.innerApiCalls.updateDatabase = + stubLongRunningCall(expectedResponse); + const [operation] = await client.updateDatabase(request); + const [response] = await operation.promise(); + assert.deepStrictEqual(response, expectedResponse); + assert( + (client.innerApiCalls.updateDatabase as SinonStub) + .getCall(0) + .calledWith(request, expectedOptions, undefined) + ); + }); + + it('invokes updateDatabase without error using callback', async () => { + const client = new firestoreadminModule.FirestoreAdminClient({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + client.initialize(); + const request = generateSampleMessage( + new protos.google.firestore.admin.v1.UpdateDatabaseRequest() + ); + request.database = {}; + request.database.name = ''; + const expectedHeaderRequestParams = 'database.name='; + const expectedOptions = { + otherArgs: { + headers: { + 'x-goog-request-params': expectedHeaderRequestParams, + }, + }, + }; + const expectedResponse = generateSampleMessage( + new protos.google.longrunning.Operation() + ); + client.innerApiCalls.updateDatabase = + stubLongRunningCallWithCallback(expectedResponse); + const promise = new Promise((resolve, reject) => { + client.updateDatabase( + request, + ( + err?: Error | null, + result?: LROperation< + protos.google.firestore.admin.v1.IDatabase, + protos.google.firestore.admin.v1.IUpdateDatabaseMetadata + > | null + ) => { + if (err) { + reject(err); + } else { + resolve(result); + } + } + ); + }); + const operation = (await promise) as LROperation< + protos.google.firestore.admin.v1.IDatabase, + protos.google.firestore.admin.v1.IUpdateDatabaseMetadata + >; + const [response] = await operation.promise(); + assert.deepStrictEqual(response, expectedResponse); + assert( + (client.innerApiCalls.updateDatabase as SinonStub) + .getCall(0) + .calledWith(request, expectedOptions /*, callback defined above */) + ); + }); + + it('invokes updateDatabase with call error', async () => { + const client = new firestoreadminModule.FirestoreAdminClient({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + client.initialize(); + const request = generateSampleMessage( + new protos.google.firestore.admin.v1.UpdateDatabaseRequest() + ); + request.database = {}; + request.database.name = ''; + const expectedHeaderRequestParams = 'database.name='; + const expectedOptions = { + otherArgs: { + headers: { + 'x-goog-request-params': expectedHeaderRequestParams, + }, + }, + }; + const expectedError = new Error('expected'); + client.innerApiCalls.updateDatabase = stubLongRunningCall( + undefined, + expectedError + ); + await assert.rejects(client.updateDatabase(request), expectedError); + assert( + (client.innerApiCalls.updateDatabase as SinonStub) + .getCall(0) + .calledWith(request, expectedOptions, undefined) + ); + }); + + it('invokes updateDatabase with LRO error', async () => { + const client = new firestoreadminModule.FirestoreAdminClient({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + client.initialize(); + const request = generateSampleMessage( + new protos.google.firestore.admin.v1.UpdateDatabaseRequest() + ); + request.database = {}; + request.database.name = ''; + const expectedHeaderRequestParams = 'database.name='; + const expectedOptions = { + otherArgs: { + headers: { + 'x-goog-request-params': expectedHeaderRequestParams, + }, + }, + }; + const expectedError = new Error('expected'); + client.innerApiCalls.updateDatabase = stubLongRunningCall( + undefined, + undefined, + expectedError + ); + const [operation] = await client.updateDatabase(request); + await assert.rejects(operation.promise(), expectedError); + assert( + (client.innerApiCalls.updateDatabase as SinonStub) + .getCall(0) + .calledWith(request, expectedOptions, undefined) + ); + }); + + it('invokes checkUpdateDatabaseProgress without error', async () => { + const client = new firestoreadminModule.FirestoreAdminClient({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + client.initialize(); + const expectedResponse = generateSampleMessage( + new operationsProtos.google.longrunning.Operation() + ); + expectedResponse.name = 'test'; + expectedResponse.response = {type_url: 'url', value: Buffer.from('')}; + expectedResponse.metadata = {type_url: 'url', value: Buffer.from('')}; + + client.operationsClient.getOperation = stubSimpleCall(expectedResponse); + const decodedOperation = await client.checkUpdateDatabaseProgress( + expectedResponse.name + ); + assert.deepStrictEqual(decodedOperation.name, expectedResponse.name); + assert(decodedOperation.metadata); + assert((client.operationsClient.getOperation as SinonStub).getCall(0)); + }); + + it('invokes checkUpdateDatabaseProgress with error', async () => { + const client = new firestoreadminModule.FirestoreAdminClient({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + client.initialize(); + const expectedError = new Error('expected'); + + client.operationsClient.getOperation = stubSimpleCall( + undefined, + expectedError + ); + await assert.rejects( + client.checkUpdateDatabaseProgress(''), + expectedError + ); + assert((client.operationsClient.getOperation as SinonStub).getCall(0)); + }); + }); + describe('listIndexes', () => { it('invokes listIndexes without error', async () => { const client = new firestoreadminModule.FirestoreAdminClient({ @@ -2159,5 +2579,43 @@ describe('v1.FirestoreAdminClient', () => { ); }); }); + + describe('project', () => { + const fakePath = '/rendered/path/project'; + const expectedParameters = { + project: 'projectValue', + }; + const client = new firestoreadminModule.FirestoreAdminClient({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + client.initialize(); + client.pathTemplates.projectPathTemplate.render = sinon + .stub() + .returns(fakePath); + client.pathTemplates.projectPathTemplate.match = sinon + .stub() + .returns(expectedParameters); + + it('projectPath', () => { + const result = client.projectPath('projectValue'); + assert.strictEqual(result, fakePath); + assert( + (client.pathTemplates.projectPathTemplate.render as SinonStub) + .getCall(-1) + .calledWith(expectedParameters) + ); + }); + + it('matchProjectFromProjectName', () => { + const result = client.matchProjectFromProjectName(fakePath); + assert.strictEqual(result, 'projectValue'); + assert( + (client.pathTemplates.projectPathTemplate.match as SinonStub) + .getCall(-1) + .calledWith(fakePath) + ); + }); + }); }); }); diff --git a/dev/test/gapic_firestore_v1.ts b/dev/test/gapic_firestore_v1.ts index 79e305af4..393705808 100644 --- a/dev/test/gapic_firestore_v1.ts +++ b/dev/test/gapic_firestore_v1.ts @@ -1,4 +1,4 @@ -// Copyright 2021 Google LLC +// Copyright 2022 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/dev/test/gapic_firestore_v1beta1.ts b/dev/test/gapic_firestore_v1beta1.ts index 00b9d9dd2..e93719780 100644 --- a/dev/test/gapic_firestore_v1beta1.ts +++ b/dev/test/gapic_firestore_v1beta1.ts @@ -1,4 +1,4 @@ -// Copyright 2021 Google LLC +// Copyright 2022 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/owlbot.py b/owlbot.py index c0acbf37a..a9c0b08d4 100644 --- a/owlbot.py +++ b/owlbot.py @@ -126,17 +126,17 @@ ) s.replace( "dev/src/v1/firestore_client.ts", - "../../protos/protos.json", + "\.\./\.\./protos/protos.json", "../../protos/v1.json" ) s.replace( "dev/src/v1/firestore_admin_client.ts", - "../../protos/protos.json", + "\.\./\.\./protos/protos.json", "../../protos/v1.json" ) s.replace( - "dev/src/v1beta1/firestore_admin_client.ts", - "../../protos/protos.json", + "dev/src/v1beta1/firestore_client.ts", + "\.\./\.\./protos/protos.json", "../../protos/v1beta1.json" ) diff --git a/samples/README.md b/samples/README.md index 3a6b9d555..48d2baf5e 100644 --- a/samples/README.md +++ b/samples/README.md @@ -41,7 +41,7 @@ Before running the samples, make sure you've followed the steps outlined in ### Limit-to-last-query -View the [source code](https://github.com/googleapis/nodejs-firestore/blob/main/samples/limit-to-last-query.js). +View the [source code](https://github.com/googleapis/nodejs-firestore/blob/master/samples/limit-to-last-query.js). [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-firestore&page=editor&open_in_editor=samples/limit-to-last-query.js,samples/README.md) @@ -58,7 +58,7 @@ __Usage:__ ### Quickstart -View the [source code](https://github.com/googleapis/nodejs-firestore/blob/main/samples/quickstart.js). +View the [source code](https://github.com/googleapis/nodejs-firestore/blob/master/samples/quickstart.js). [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-firestore&page=editor&open_in_editor=samples/quickstart.js,samples/README.md) @@ -75,7 +75,7 @@ __Usage:__ ### Solution-counters -View the [source code](https://github.com/googleapis/nodejs-firestore/blob/main/samples/solution-counters.js). +View the [source code](https://github.com/googleapis/nodejs-firestore/blob/master/samples/solution-counters.js). [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-firestore&page=editor&open_in_editor=samples/solution-counters.js,samples/README.md) diff --git a/types/v1/firestore_admin_client.d.ts b/types/v1/firestore_admin_client.d.ts index 523c92ad7..5ec48f751 100644 --- a/types/v1/firestore_admin_client.d.ts +++ b/types/v1/firestore_admin_client.d.ts @@ -1,19 +1,3 @@ -/*! - * Copyright 2021 Google LLC - * - * 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 - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - /// import * as gax from 'google-gax'; import { @@ -126,6 +110,24 @@ export declare class FirestoreAdminClient { static get scopes(): string[]; getProjectId(): Promise; getProjectId(callback: Callback): void; + /** + * Gets a composite index. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.name + * Required. A name of the form + * `projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/indexes/{index_id}` + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Index]{@link google.firestore.admin.v1.Index}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1/firestore_admin.get_index.js + * region_tag:firestore_v1_generated_FirestoreAdmin_GetIndex_async + */ getIndex( request?: protos.google.firestore.admin.v1.IGetIndexRequest, options?: CallOptions @@ -153,6 +155,24 @@ export declare class FirestoreAdminClient { {} | null | undefined > ): void; + /** + * Deletes a composite index. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.name + * Required. A name of the form + * `projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/indexes/{index_id}` + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Empty]{@link google.protobuf.Empty}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1/firestore_admin.delete_index.js + * region_tag:firestore_v1_generated_FirestoreAdmin_DeleteIndex_async + */ deleteIndex( request?: protos.google.firestore.admin.v1.IDeleteIndexRequest, options?: CallOptions @@ -180,6 +200,24 @@ export declare class FirestoreAdminClient { {} | null | undefined > ): void; + /** + * Gets the metadata and configuration for a Field. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.name + * Required. A name of the form + * `projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/fields/{field_id}` + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Field]{@link google.firestore.admin.v1.Field}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1/firestore_admin.get_field.js + * region_tag:firestore_v1_generated_FirestoreAdmin_GetField_async + */ getField( request?: protos.google.firestore.admin.v1.IGetFieldRequest, options?: CallOptions @@ -207,6 +245,30 @@ export declare class FirestoreAdminClient { {} | null | undefined > ): void; + /** + * Creates a composite index. This returns a {@link google.longrunning.Operation|google.longrunning.Operation} + * which may be used to track the status of the creation. The metadata for + * the operation will be the type {@link google.firestore.admin.v1.IndexOperationMetadata|IndexOperationMetadata}. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. A parent name of the form + * `projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}` + * @param {google.firestore.admin.v1.Index} request.index + * Required. The composite index to create. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing + * a long running operation. Its `promise()` method returns a promise + * you can `await` for. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) + * for more details and examples. + * @example include:samples/generated/v1/firestore_admin.create_index.js + * region_tag:firestore_v1_generated_FirestoreAdmin_CreateIndex_async + */ createIndex( request?: protos.google.firestore.admin.v1.ICreateIndexRequest, options?: CallOptions @@ -252,11 +314,8 @@ export declare class FirestoreAdminClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) * for more details and examples. - * @example - * const decodedOperation = await checkCreateIndexProgress(name); - * console.log(decodedOperation.result); - * console.log(decodedOperation.done); - * console.log(decodedOperation.metadata); + * @example include:samples/generated/v1/firestore_admin.create_index.js + * region_tag:firestore_v1_generated_FirestoreAdmin_CreateIndex_async */ checkCreateIndexProgress( name: string @@ -266,6 +325,40 @@ export declare class FirestoreAdminClient { protos.google.firestore.admin.v1.IndexOperationMetadata > >; + /** + * Updates a field configuration. Currently, field updates apply only to + * single field index configuration. However, calls to + * {@link google.firestore.admin.v1.FirestoreAdmin.UpdateField|FirestoreAdmin.UpdateField} should provide a field mask to avoid + * changing any configuration that the caller isn't aware of. The field mask + * should be specified as: `{ paths: "index_config" }`. + * + * This call returns a {@link google.longrunning.Operation|google.longrunning.Operation} which may be used to + * track the status of the field update. The metadata for + * the operation will be the type {@link google.firestore.admin.v1.FieldOperationMetadata|FieldOperationMetadata}. + * + * To configure the default field settings for the database, use + * the special `Field` with resource name: + * `projects/{project_id}/databases/{database_id}/collectionGroups/__default__/fields/*`. + * + * @param {Object} request + * The request object that will be sent. + * @param {google.firestore.admin.v1.Field} request.field + * Required. The field to be updated. + * @param {google.protobuf.FieldMask} request.updateMask + * A mask, relative to the field. If specified, only configuration specified + * by this field_mask will be updated in the field. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing + * a long running operation. Its `promise()` method returns a promise + * you can `await` for. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) + * for more details and examples. + * @example include:samples/generated/v1/firestore_admin.update_field.js + * region_tag:firestore_v1_generated_FirestoreAdmin_UpdateField_async + */ updateField( request?: protos.google.firestore.admin.v1.IUpdateFieldRequest, options?: CallOptions @@ -311,11 +404,8 @@ export declare class FirestoreAdminClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) * for more details and examples. - * @example - * const decodedOperation = await checkUpdateFieldProgress(name); - * console.log(decodedOperation.result); - * console.log(decodedOperation.done); - * console.log(decodedOperation.metadata); + * @example include:samples/generated/v1/firestore_admin.update_field.js + * region_tag:firestore_v1_generated_FirestoreAdmin_UpdateField_async */ checkUpdateFieldProgress( name: string @@ -325,6 +415,44 @@ export declare class FirestoreAdminClient { protos.google.firestore.admin.v1.FieldOperationMetadata > >; + /** + * Exports a copy of all or a subset of documents from Google Cloud Firestore + * to another storage system, such as Google Cloud Storage. Recent updates to + * documents may not be reflected in the export. The export occurs in the + * background and its progress can be monitored and managed via the + * Operation resource that is created. The output of an export may only be + * used once the associated operation is done. If an export operation is + * cancelled before completion it may leave partial data behind in Google + * Cloud Storage. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.name + * Required. Database to export. Should be of the form: + * `projects/{project_id}/databases/{database_id}`. + * @param {string[]} request.collectionIds + * Which collection ids to export. Unspecified means all collections. + * @param {string} request.outputUriPrefix + * The output URI. Currently only supports Google Cloud Storage URIs of the + * form: `gs://BUCKET_NAME[/NAMESPACE_PATH]`, where `BUCKET_NAME` is the name + * of the Google Cloud Storage bucket and `NAMESPACE_PATH` is an optional + * Google Cloud Storage namespace path. When + * choosing a name, be sure to consider Google Cloud Storage naming + * guidelines: https://cloud.google.com/storage/docs/naming. + * If the URI is a bucket (without a namespace path), a prefix will be + * generated based on the start time. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing + * a long running operation. Its `promise()` method returns a promise + * you can `await` for. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) + * for more details and examples. + * @example include:samples/generated/v1/firestore_admin.export_documents.js + * region_tag:firestore_v1_generated_FirestoreAdmin_ExportDocuments_async + */ exportDocuments( request?: protos.google.firestore.admin.v1.IExportDocumentsRequest, options?: CallOptions @@ -370,11 +498,8 @@ export declare class FirestoreAdminClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) * for more details and examples. - * @example - * const decodedOperation = await checkExportDocumentsProgress(name); - * console.log(decodedOperation.result); - * console.log(decodedOperation.done); - * console.log(decodedOperation.metadata); + * @example include:samples/generated/v1/firestore_admin.export_documents.js + * region_tag:firestore_v1_generated_FirestoreAdmin_ExportDocuments_async */ checkExportDocumentsProgress( name: string @@ -384,6 +509,39 @@ export declare class FirestoreAdminClient { protos.google.firestore.admin.v1.ExportDocumentsMetadata > >; + /** + * Imports documents into Google Cloud Firestore. Existing documents with the + * same name are overwritten. The import occurs in the background and its + * progress can be monitored and managed via the Operation resource that is + * created. If an ImportDocuments operation is cancelled, it is possible + * that a subset of the data has already been imported to Cloud Firestore. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.name + * Required. Database to import into. Should be of the form: + * `projects/{project_id}/databases/{database_id}`. + * @param {string[]} request.collectionIds + * Which collection ids to import. Unspecified means all collections included + * in the import. + * @param {string} request.inputUriPrefix + * Location of the exported files. + * This must match the output_uri_prefix of an ExportDocumentsResponse from + * an export that has completed successfully. + * See: + * {@link google.firestore.admin.v1.ExportDocumentsResponse.output_uri_prefix|google.firestore.admin.v1.ExportDocumentsResponse.output_uri_prefix}. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing + * a long running operation. Its `promise()` method returns a promise + * you can `await` for. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) + * for more details and examples. + * @example include:samples/generated/v1/firestore_admin.import_documents.js + * region_tag:firestore_v1_generated_FirestoreAdmin_ImportDocuments_async + */ importDocuments( request?: protos.google.firestore.admin.v1.IImportDocumentsRequest, options?: CallOptions @@ -429,11 +587,8 @@ export declare class FirestoreAdminClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) * for more details and examples. - * @example - * const decodedOperation = await checkImportDocumentsProgress(name); - * console.log(decodedOperation.result); - * console.log(decodedOperation.done); - * console.log(decodedOperation.metadata); + * @example include:samples/generated/v1/firestore_admin.import_documents.js + * region_tag:firestore_v1_generated_FirestoreAdmin_ImportDocuments_async */ checkImportDocumentsProgress( name: string @@ -443,6 +598,35 @@ export declare class FirestoreAdminClient { protos.google.firestore.admin.v1.ImportDocumentsMetadata > >; + /** + * Lists composite indexes. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. A parent name of the form + * `projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}` + * @param {string} request.filter + * The filter to apply to list results. + * @param {number} request.pageSize + * The number of results to return. + * @param {string} request.pageToken + * A page token, returned from a previous call to + * {@link google.firestore.admin.v1.FirestoreAdmin.ListIndexes|FirestoreAdmin.ListIndexes}, that may be used to get the next + * page of results. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is Array of [Index]{@link google.firestore.admin.v1.Index}. + * The client library will perform auto-pagination by default: it will call the API as many + * times as needed and will merge results from all the pages into this array. + * Note that it can affect your quota. + * We recommend using `listIndexesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + */ listIndexes( request?: protos.google.firestore.admin.v1.IListIndexesRequest, options?: CallOptions @@ -528,16 +712,51 @@ export declare class FirestoreAdminClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) * for more details and examples. - * @example - * const iterable = client.listIndexesAsync(request); - * for await (const response of iterable) { - * // process response - * } + * @example include:samples/generated/v1/firestore_admin.list_indexes.js + * region_tag:firestore_v1_generated_FirestoreAdmin_ListIndexes_async */ listIndexesAsync( request?: protos.google.firestore.admin.v1.IListIndexesRequest, options?: CallOptions ): AsyncIterable; + /** + * Lists the field configuration and metadata for this database. + * + * Currently, {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} only supports listing fields + * that have been explicitly overridden. To issue this query, call + * {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} with the filter set to + * `indexConfig.usesAncestorConfig:false`. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. A parent name of the form + * `projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}` + * @param {string} request.filter + * The filter to apply to list results. Currently, + * {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} only supports listing fields + * that have been explicitly overridden. To issue this query, call + * {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields} with the filter set to + * `indexConfig.usesAncestorConfig:false`. + * @param {number} request.pageSize + * The number of results to return. + * @param {string} request.pageToken + * A page token, returned from a previous call to + * {@link google.firestore.admin.v1.FirestoreAdmin.ListFields|FirestoreAdmin.ListFields}, that may be used to get the next + * page of results. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is Array of [Field]{@link google.firestore.admin.v1.Field}. + * The client library will perform auto-pagination by default: it will call the API as many + * times as needed and will merge results from all the pages into this array. + * Note that it can affect your quota. + * We recommend using `listFieldsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + */ listFields( request?: protos.google.firestore.admin.v1.IListFieldsRequest, options?: CallOptions @@ -631,11 +850,8 @@ export declare class FirestoreAdminClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) * for more details and examples. - * @example - * const iterable = client.listFieldsAsync(request); - * for await (const response of iterable) { - * // process response - * } + * @example include:samples/generated/v1/firestore_admin.list_fields.js + * region_tag:firestore_v1_generated_FirestoreAdmin_ListFields_async */ listFieldsAsync( request?: protos.google.firestore.admin.v1.IListFieldsRequest, diff --git a/types/v1/firestore_client.d.ts b/types/v1/firestore_client.d.ts index 139527dd9..096273124 100644 --- a/types/v1/firestore_client.d.ts +++ b/types/v1/firestore_client.d.ts @@ -1,19 +1,3 @@ -/*! - * Copyright 2021 Google LLC - * - * 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 - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - /// import * as gax from 'google-gax'; import { @@ -127,6 +111,34 @@ export declare class FirestoreClient { static get scopes(): string[]; getProjectId(): Promise; getProjectId(callback: Callback): void; + /** + * Gets a single document. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.name + * Required. The resource name of the Document to get. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * @param {google.firestore.v1.DocumentMask} request.mask + * The fields to return. If not set, returns all fields. + * + * If the document has a field that is not present in this mask, that field + * will not be returned in the response. + * @param {Buffer} request.transaction + * Reads the document in a transaction. + * @param {google.protobuf.Timestamp} request.readTime + * Reads the version of the document at the given time. + * This may not be older than 270 seconds. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Document]{@link google.firestore.v1.Document}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1/firestore.get_document.js + * region_tag:firestore_v1_generated_Firestore_GetDocument_async + */ getDocument( request?: protos.google.firestore.v1.IGetDocumentRequest, options?: CallOptions @@ -154,6 +166,40 @@ export declare class FirestoreClient { {} | null | undefined > ): void; + /** + * Updates or inserts a document. + * + * @param {Object} request + * The request object that will be sent. + * @param {google.firestore.v1.Document} request.document + * Required. The updated document. + * Creates the document if it does not already exist. + * @param {google.firestore.v1.DocumentMask} request.updateMask + * The fields to update. + * None of the field paths in the mask may contain a reserved name. + * + * If the document exists on the server and has fields not referenced in the + * mask, they are left unchanged. + * Fields referenced in the mask, but not present in the input document, are + * deleted from the document on the server. + * @param {google.firestore.v1.DocumentMask} request.mask + * The fields to return. If not set, returns all fields. + * + * If the document has a field that is not present in this mask, that field + * will not be returned in the response. + * @param {google.firestore.v1.Precondition} request.currentDocument + * An optional precondition on the document. + * The request will fail if this is set and not met by the target document. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Document]{@link google.firestore.v1.Document}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1/firestore.update_document.js + * region_tag:firestore_v1_generated_Firestore_UpdateDocument_async + */ updateDocument( request?: protos.google.firestore.v1.IUpdateDocumentRequest, options?: CallOptions @@ -181,6 +227,27 @@ export declare class FirestoreClient { {} | null | undefined > ): void; + /** + * Deletes a document. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.name + * Required. The resource name of the Document to delete. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * @param {google.firestore.v1.Precondition} request.currentDocument + * An optional precondition on the document. + * The request will fail if this is set and not met by the target document. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Empty]{@link google.protobuf.Empty}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1/firestore.delete_document.js + * region_tag:firestore_v1_generated_Firestore_DeleteDocument_async + */ deleteDocument( request?: protos.google.firestore.v1.IDeleteDocumentRequest, options?: CallOptions @@ -208,6 +275,27 @@ export declare class FirestoreClient { {} | null | undefined > ): void; + /** + * Starts a new transaction. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.database + * Required. The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * @param {google.firestore.v1.TransactionOptions} request.options + * The options for the transaction. + * Defaults to a read-write transaction. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [BeginTransactionResponse]{@link google.firestore.v1.BeginTransactionResponse}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1/firestore.begin_transaction.js + * region_tag:firestore_v1_generated_Firestore_BeginTransaction_async + */ beginTransaction( request?: protos.google.firestore.v1.IBeginTransactionRequest, options?: CallOptions @@ -235,6 +323,30 @@ export declare class FirestoreClient { {} | null | undefined > ): void; + /** + * Commits a transaction, while optionally updating documents. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.database + * Required. The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * @param {number[]} request.writes + * The writes to apply. + * + * Always executed atomically and in order. + * @param {Buffer} request.transaction + * If set, applies all writes in this transaction, and commits it. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [CommitResponse]{@link google.firestore.v1.CommitResponse}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1/firestore.commit.js + * region_tag:firestore_v1_generated_Firestore_Commit_async + */ commit( request?: protos.google.firestore.v1.ICommitRequest, options?: CallOptions @@ -262,6 +374,26 @@ export declare class FirestoreClient { {} | null | undefined > ): void; + /** + * Rolls back a transaction. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.database + * Required. The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * @param {Buffer} request.transaction + * Required. The transaction to roll back. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Empty]{@link google.protobuf.Empty}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1/firestore.rollback.js + * region_tag:firestore_v1_generated_Firestore_Rollback_async + */ rollback( request?: protos.google.firestore.v1.IRollbackRequest, options?: CallOptions @@ -289,6 +421,40 @@ export declare class FirestoreClient { {} | null | undefined > ): void; + /** + * Applies a batch of write operations. + * + * The BatchWrite method does not apply the write operations atomically + * and can apply them out of order. Method does not allow more than one write + * per document. Each write succeeds or fails independently. See the + * {@link google.firestore.v1.BatchWriteResponse|BatchWriteResponse} for the success status of each write. + * + * If you require an atomically applied set of writes, use + * {@link google.firestore.v1.Firestore.Commit|Commit} instead. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.database + * Required. The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * @param {number[]} request.writes + * The writes to apply. + * + * Method does not apply writes atomically and does not guarantee ordering. + * Each write succeeds or fails independently. You cannot write to the same + * document more than once per request. + * @param {number[]} request.labels + * Labels associated with this batch write. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [BatchWriteResponse]{@link google.firestore.v1.BatchWriteResponse}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1/firestore.batch_write.js + * region_tag:firestore_v1_generated_Firestore_BatchWrite_async + */ batchWrite( request?: protos.google.firestore.v1.IBatchWriteRequest, options?: CallOptions @@ -316,6 +482,38 @@ export declare class FirestoreClient { {} | null | undefined > ): void; + /** + * Creates a new document. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. The parent resource. For example: + * `projects/{project_id}/databases/{database_id}/documents` or + * `projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}` + * @param {string} request.collectionId + * Required. The collection ID, relative to `parent`, to list. For example: `chatrooms`. + * @param {string} request.documentId + * The client-assigned document ID to use for this document. + * + * Optional. If not specified, an ID will be assigned by the service. + * @param {google.firestore.v1.Document} request.document + * Required. The document to create. `name` must not be set. + * @param {google.firestore.v1.DocumentMask} request.mask + * The fields to return. If not set, returns all fields. + * + * If the document has a field that is not present in this mask, that field + * will not be returned in the response. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Document]{@link google.firestore.v1.Document}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1/firestore.create_document.js + * region_tag:firestore_v1_generated_Firestore_CreateDocument_async + */ createDocument( request?: protos.google.firestore.v1.ICreateDocumentRequest, options?: CallOptions @@ -381,10 +579,8 @@ export declare class FirestoreClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#server-streaming) * for more details and examples. - * @example - * const stream = client.batchGetDocuments(request); - * stream.on('data', (response) => { ... }); - * stream.on('end', () => { ... }); + * @example include:samples/generated/v1/firestore.batch_get_documents.js + * region_tag:firestore_v1_generated_Firestore_BatchGetDocuments_async */ batchGetDocuments( request?: protos.google.firestore.v1.IBatchGetDocumentsRequest, @@ -421,10 +617,8 @@ export declare class FirestoreClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#server-streaming) * for more details and examples. - * @example - * const stream = client.runQuery(request); - * stream.on('data', (response) => { ... }); - * stream.on('end', () => { ... }); + * @example include:samples/generated/v1/firestore.run_query.js + * region_tag:firestore_v1_generated_Firestore_RunQuery_async */ runQuery( request?: protos.google.firestore.v1.IRunQueryRequest, @@ -442,12 +636,8 @@ export declare class FirestoreClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#bi-directional-streaming) * for more details and examples. - * @example - * const stream = client.write(); - * stream.on('data', (response) => { ... }); - * stream.on('end', () => { ... }); - * stream.write(request); - * stream.end(); + * @example include:samples/generated/v1/firestore.write.js + * region_tag:firestore_v1_generated_Firestore_Write_async */ write(options?: CallOptions): gax.CancellableStream; /** @@ -462,14 +652,62 @@ export declare class FirestoreClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#bi-directional-streaming) * for more details and examples. - * @example - * const stream = client.listen(); - * stream.on('data', (response) => { ... }); - * stream.on('end', () => { ... }); - * stream.write(request); - * stream.end(); + * @example include:samples/generated/v1/firestore.listen.js + * region_tag:firestore_v1_generated_Firestore_Listen_async */ listen(options?: CallOptions): gax.CancellableStream; + /** + * Lists documents. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. The parent resource name. In the format: + * `projects/{project_id}/databases/{database_id}/documents` or + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * For example: + * `projects/my-project/databases/my-database/documents` or + * `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + * @param {string} request.collectionId + * Required. The collection ID, relative to `parent`, to list. For example: `chatrooms` + * or `messages`. + * @param {number} request.pageSize + * The maximum number of documents to return. + * @param {string} request.pageToken + * The `next_page_token` value returned from a previous List request, if any. + * @param {string} request.orderBy + * The order to sort results by. For example: `priority desc, name`. + * @param {google.firestore.v1.DocumentMask} request.mask + * The fields to return. If not set, returns all fields. + * + * If a document has a field that is not present in this mask, that field + * will not be returned in the response. + * @param {Buffer} request.transaction + * Reads documents in a transaction. + * @param {google.protobuf.Timestamp} request.readTime + * Reads documents as they were at the given time. + * This may not be older than 270 seconds. + * @param {boolean} request.showMissing + * If the list should show missing documents. A missing document is a + * document that does not exist but has sub-documents. These documents will + * be returned with a key but will not have fields, {@link google.firestore.v1.Document.create_time|Document.create_time}, + * or {@link google.firestore.v1.Document.update_time|Document.update_time} set. + * + * Requests with `show_missing` may not specify `where` or + * `order_by`. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is Array of [Document]{@link google.firestore.v1.Document}. + * The client library will perform auto-pagination by default: it will call the API as many + * times as needed and will merge results from all the pages into this array. + * Note that it can affect your quota. + * We recommend using `listDocumentsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + */ listDocuments( request?: protos.google.firestore.v1.IListDocumentsRequest, options?: CallOptions @@ -601,16 +839,74 @@ export declare class FirestoreClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) * for more details and examples. - * @example - * const iterable = client.listDocumentsAsync(request); - * for await (const response of iterable) { - * // process response - * } + * @example include:samples/generated/v1/firestore.list_documents.js + * region_tag:firestore_v1_generated_Firestore_ListDocuments_async */ listDocumentsAsync( request?: protos.google.firestore.v1.IListDocumentsRequest, options?: CallOptions ): AsyncIterable; + /** + * Partitions a query by returning partition cursors that can be used to run + * the query in parallel. The returned partition cursors are split points that + * can be used by RunQuery as starting/end points for the query results. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. The parent resource name. In the format: + * `projects/{project_id}/databases/{database_id}/documents`. + * Document resource names are not supported; only database resource names + * can be specified. + * @param {google.firestore.v1.StructuredQuery} request.structuredQuery + * A structured query. + * Query must specify collection with all descendants and be ordered by name + * ascending. Other filters, order bys, limits, offsets, and start/end + * cursors are not supported. + * @param {number} request.partitionCount + * The desired maximum number of partition points. + * The partitions may be returned across multiple pages of results. + * The number must be positive. The actual number of partitions + * returned may be fewer. + * + * For example, this may be set to one fewer than the number of parallel + * queries to be run, or in running a data pipeline job, one fewer than the + * number of workers or compute instances available. + * @param {string} request.pageToken + * The `next_page_token` value returned from a previous call to + * PartitionQuery that may be used to get an additional set of results. + * There are no ordering guarantees between sets of results. Thus, using + * multiple sets of results will require merging the different result sets. + * + * For example, two subsequent calls using a page_token may return: + * + * * cursor B, cursor M, cursor Q + * * cursor A, cursor U, cursor W + * + * To obtain a complete result set ordered with respect to the results of the + * query supplied to PartitionQuery, the results sets should be merged: + * cursor A, cursor B, cursor M, cursor Q, cursor U, cursor W + * @param {number} request.pageSize + * The maximum number of partitions to return in this call, subject to + * `partition_count`. + * + * For example, if `partition_count` = 10 and `page_size` = 8, the first call + * to PartitionQuery will return up to 8 partitions and a `next_page_token` + * if more results exist. A second call to PartitionQuery will return up to + * 2 partitions, to complete the total of 10 specified in `partition_count`. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is Array of [Cursor]{@link google.firestore.v1.Cursor}. + * The client library will perform auto-pagination by default: it will call the API as many + * times as needed and will merge results from all the pages into this array. + * Note that it can affect your quota. + * We recommend using `partitionQueryAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + */ partitionQuery( request?: protos.google.firestore.v1.IPartitionQueryRequest, options?: CallOptions @@ -756,16 +1052,41 @@ export declare class FirestoreClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) * for more details and examples. - * @example - * const iterable = client.partitionQueryAsync(request); - * for await (const response of iterable) { - * // process response - * } + * @example include:samples/generated/v1/firestore.partition_query.js + * region_tag:firestore_v1_generated_Firestore_PartitionQuery_async */ partitionQueryAsync( request?: protos.google.firestore.v1.IPartitionQueryRequest, options?: CallOptions ): AsyncIterable; + /** + * Lists all the collection IDs underneath a document. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. The parent document. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * For example: + * `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + * @param {number} request.pageSize + * The maximum number of results to return. + * @param {string} request.pageToken + * A page token. Must be a value from + * {@link google.firestore.v1.ListCollectionIdsResponse|ListCollectionIdsResponse}. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is Array of string. + * The client library will perform auto-pagination by default: it will call the API as many + * times as needed and will merge results from all the pages into this array. + * Note that it can affect your quota. + * We recommend using `listCollectionIdsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + */ listCollectionIds( request?: protos.google.firestore.v1.IListCollectionIdsRequest, options?: CallOptions @@ -849,11 +1170,8 @@ export declare class FirestoreClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) * for more details and examples. - * @example - * const iterable = client.listCollectionIdsAsync(request); - * for await (const response of iterable) { - * // process response - * } + * @example include:samples/generated/v1/firestore.list_collection_ids.js + * region_tag:firestore_v1_generated_Firestore_ListCollectionIds_async */ listCollectionIdsAsync( request?: protos.google.firestore.v1.IListCollectionIdsRequest, diff --git a/types/v1beta1/firestore_client.d.ts b/types/v1beta1/firestore_client.d.ts index 24ea51b39..feaf38e8d 100644 --- a/types/v1beta1/firestore_client.d.ts +++ b/types/v1beta1/firestore_client.d.ts @@ -1,19 +1,3 @@ -/*! - * Copyright 2021 Google LLC - * - * 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 - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - /// import * as gax from 'google-gax'; import { @@ -128,6 +112,34 @@ export declare class FirestoreClient { static get scopes(): string[]; getProjectId(): Promise; getProjectId(callback: Callback): void; + /** + * Gets a single document. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.name + * Required. The resource name of the Document to get. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * @param {google.firestore.v1beta1.DocumentMask} request.mask + * The fields to return. If not set, returns all fields. + * + * If the document has a field that is not present in this mask, that field + * will not be returned in the response. + * @param {Buffer} request.transaction + * Reads the document in a transaction. + * @param {google.protobuf.Timestamp} request.readTime + * Reads the version of the document at the given time. + * This may not be older than 270 seconds. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Document]{@link google.firestore.v1beta1.Document}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1beta1/firestore.get_document.js + * region_tag:firestore_v1beta1_generated_Firestore_GetDocument_async + */ getDocument( request?: protos.google.firestore.v1beta1.IGetDocumentRequest, options?: CallOptions @@ -155,6 +167,40 @@ export declare class FirestoreClient { {} | null | undefined > ): void; + /** + * Updates or inserts a document. + * + * @param {Object} request + * The request object that will be sent. + * @param {google.firestore.v1beta1.Document} request.document + * Required. The updated document. + * Creates the document if it does not already exist. + * @param {google.firestore.v1beta1.DocumentMask} request.updateMask + * The fields to update. + * None of the field paths in the mask may contain a reserved name. + * + * If the document exists on the server and has fields not referenced in the + * mask, they are left unchanged. + * Fields referenced in the mask, but not present in the input document, are + * deleted from the document on the server. + * @param {google.firestore.v1beta1.DocumentMask} request.mask + * The fields to return. If not set, returns all fields. + * + * If the document has a field that is not present in this mask, that field + * will not be returned in the response. + * @param {google.firestore.v1beta1.Precondition} request.currentDocument + * An optional precondition on the document. + * The request will fail if this is set and not met by the target document. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Document]{@link google.firestore.v1beta1.Document}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1beta1/firestore.update_document.js + * region_tag:firestore_v1beta1_generated_Firestore_UpdateDocument_async + */ updateDocument( request?: protos.google.firestore.v1beta1.IUpdateDocumentRequest, options?: CallOptions @@ -182,6 +228,27 @@ export declare class FirestoreClient { {} | null | undefined > ): void; + /** + * Deletes a document. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.name + * Required. The resource name of the Document to delete. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * @param {google.firestore.v1beta1.Precondition} request.currentDocument + * An optional precondition on the document. + * The request will fail if this is set and not met by the target document. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Empty]{@link google.protobuf.Empty}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1beta1/firestore.delete_document.js + * region_tag:firestore_v1beta1_generated_Firestore_DeleteDocument_async + */ deleteDocument( request?: protos.google.firestore.v1beta1.IDeleteDocumentRequest, options?: CallOptions @@ -209,6 +276,27 @@ export declare class FirestoreClient { {} | null | undefined > ): void; + /** + * Starts a new transaction. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.database + * Required. The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * @param {google.firestore.v1beta1.TransactionOptions} request.options + * The options for the transaction. + * Defaults to a read-write transaction. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [BeginTransactionResponse]{@link google.firestore.v1beta1.BeginTransactionResponse}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1beta1/firestore.begin_transaction.js + * region_tag:firestore_v1beta1_generated_Firestore_BeginTransaction_async + */ beginTransaction( request?: protos.google.firestore.v1beta1.IBeginTransactionRequest, options?: CallOptions @@ -240,6 +328,30 @@ export declare class FirestoreClient { {} | null | undefined > ): void; + /** + * Commits a transaction, while optionally updating documents. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.database + * Required. The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * @param {number[]} request.writes + * The writes to apply. + * + * Always executed atomically and in order. + * @param {Buffer} request.transaction + * If set, applies all writes in this transaction, and commits it. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [CommitResponse]{@link google.firestore.v1beta1.CommitResponse}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1beta1/firestore.commit.js + * region_tag:firestore_v1beta1_generated_Firestore_Commit_async + */ commit( request?: protos.google.firestore.v1beta1.ICommitRequest, options?: CallOptions @@ -267,6 +379,26 @@ export declare class FirestoreClient { {} | null | undefined > ): void; + /** + * Rolls back a transaction. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.database + * Required. The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * @param {Buffer} request.transaction + * Required. The transaction to roll back. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Empty]{@link google.protobuf.Empty}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1beta1/firestore.rollback.js + * region_tag:firestore_v1beta1_generated_Firestore_Rollback_async + */ rollback( request?: protos.google.firestore.v1beta1.IRollbackRequest, options?: CallOptions @@ -294,6 +426,40 @@ export declare class FirestoreClient { {} | null | undefined > ): void; + /** + * Applies a batch of write operations. + * + * The BatchWrite method does not apply the write operations atomically + * and can apply them out of order. Method does not allow more than one write + * per document. Each write succeeds or fails independently. See the + * {@link google.firestore.v1beta1.BatchWriteResponse|BatchWriteResponse} for the success status of each write. + * + * If you require an atomically applied set of writes, use + * {@link google.firestore.v1beta1.Firestore.Commit|Commit} instead. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.database + * Required. The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * @param {number[]} request.writes + * The writes to apply. + * + * Method does not apply writes atomically and does not guarantee ordering. + * Each write succeeds or fails independently. You cannot write to the same + * document more than once per request. + * @param {number[]} request.labels + * Labels associated with this batch write. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [BatchWriteResponse]{@link google.firestore.v1beta1.BatchWriteResponse}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1beta1/firestore.batch_write.js + * region_tag:firestore_v1beta1_generated_Firestore_BatchWrite_async + */ batchWrite( request?: protos.google.firestore.v1beta1.IBatchWriteRequest, options?: CallOptions @@ -321,6 +487,38 @@ export declare class FirestoreClient { {} | null | undefined > ): void; + /** + * Creates a new document. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. The parent resource. For example: + * `projects/{project_id}/databases/{database_id}/documents` or + * `projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}` + * @param {string} request.collectionId + * Required. The collection ID, relative to `parent`, to list. For example: `chatrooms`. + * @param {string} request.documentId + * The client-assigned document ID to use for this document. + * + * Optional. If not specified, an ID will be assigned by the service. + * @param {google.firestore.v1beta1.Document} request.document + * Required. The document to create. `name` must not be set. + * @param {google.firestore.v1beta1.DocumentMask} request.mask + * The fields to return. If not set, returns all fields. + * + * If the document has a field that is not present in this mask, that field + * will not be returned in the response. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Document]{@link google.firestore.v1beta1.Document}. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example include:samples/generated/v1beta1/firestore.create_document.js + * region_tag:firestore_v1beta1_generated_Firestore_CreateDocument_async + */ createDocument( request?: protos.google.firestore.v1beta1.ICreateDocumentRequest, options?: CallOptions @@ -386,10 +584,8 @@ export declare class FirestoreClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#server-streaming) * for more details and examples. - * @example - * const stream = client.batchGetDocuments(request); - * stream.on('data', (response) => { ... }); - * stream.on('end', () => { ... }); + * @example include:samples/generated/v1beta1/firestore.batch_get_documents.js + * region_tag:firestore_v1beta1_generated_Firestore_BatchGetDocuments_async */ batchGetDocuments( request?: protos.google.firestore.v1beta1.IBatchGetDocumentsRequest, @@ -426,10 +622,8 @@ export declare class FirestoreClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#server-streaming) * for more details and examples. - * @example - * const stream = client.runQuery(request); - * stream.on('data', (response) => { ... }); - * stream.on('end', () => { ... }); + * @example include:samples/generated/v1beta1/firestore.run_query.js + * region_tag:firestore_v1beta1_generated_Firestore_RunQuery_async */ runQuery( request?: protos.google.firestore.v1beta1.IRunQueryRequest, @@ -447,12 +641,8 @@ export declare class FirestoreClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#bi-directional-streaming) * for more details and examples. - * @example - * const stream = client.write(); - * stream.on('data', (response) => { ... }); - * stream.on('end', () => { ... }); - * stream.write(request); - * stream.end(); + * @example include:samples/generated/v1beta1/firestore.write.js + * region_tag:firestore_v1beta1_generated_Firestore_Write_async */ write(options?: CallOptions): gax.CancellableStream; /** @@ -467,14 +657,62 @@ export declare class FirestoreClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#bi-directional-streaming) * for more details and examples. - * @example - * const stream = client.listen(); - * stream.on('data', (response) => { ... }); - * stream.on('end', () => { ... }); - * stream.write(request); - * stream.end(); + * @example include:samples/generated/v1beta1/firestore.listen.js + * region_tag:firestore_v1beta1_generated_Firestore_Listen_async */ listen(options?: CallOptions): gax.CancellableStream; + /** + * Lists documents. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. The parent resource name. In the format: + * `projects/{project_id}/databases/{database_id}/documents` or + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * For example: + * `projects/my-project/databases/my-database/documents` or + * `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + * @param {string} request.collectionId + * Required. The collection ID, relative to `parent`, to list. For example: `chatrooms` + * or `messages`. + * @param {number} request.pageSize + * The maximum number of documents to return. + * @param {string} request.pageToken + * The `next_page_token` value returned from a previous List request, if any. + * @param {string} request.orderBy + * The order to sort results by. For example: `priority desc, name`. + * @param {google.firestore.v1beta1.DocumentMask} request.mask + * The fields to return. If not set, returns all fields. + * + * If a document has a field that is not present in this mask, that field + * will not be returned in the response. + * @param {Buffer} request.transaction + * Reads documents in a transaction. + * @param {google.protobuf.Timestamp} request.readTime + * Reads documents as they were at the given time. + * This may not be older than 270 seconds. + * @param {boolean} request.showMissing + * If the list should show missing documents. A missing document is a + * document that does not exist but has sub-documents. These documents will + * be returned with a key but will not have fields, {@link google.firestore.v1beta1.Document.create_time|Document.create_time}, + * or {@link google.firestore.v1beta1.Document.update_time|Document.update_time} set. + * + * Requests with `show_missing` may not specify `where` or + * `order_by`. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is Array of [Document]{@link google.firestore.v1beta1.Document}. + * The client library will perform auto-pagination by default: it will call the API as many + * times as needed and will merge results from all the pages into this array. + * Note that it can affect your quota. + * We recommend using `listDocumentsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + */ listDocuments( request?: protos.google.firestore.v1beta1.IListDocumentsRequest, options?: CallOptions @@ -606,16 +844,74 @@ export declare class FirestoreClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) * for more details and examples. - * @example - * const iterable = client.listDocumentsAsync(request); - * for await (const response of iterable) { - * // process response - * } + * @example include:samples/generated/v1beta1/firestore.list_documents.js + * region_tag:firestore_v1beta1_generated_Firestore_ListDocuments_async */ listDocumentsAsync( request?: protos.google.firestore.v1beta1.IListDocumentsRequest, options?: CallOptions ): AsyncIterable; + /** + * Partitions a query by returning partition cursors that can be used to run + * the query in parallel. The returned partition cursors are split points that + * can be used by RunQuery as starting/end points for the query results. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. The parent resource name. In the format: + * `projects/{project_id}/databases/{database_id}/documents`. + * Document resource names are not supported; only database resource names + * can be specified. + * @param {google.firestore.v1beta1.StructuredQuery} request.structuredQuery + * A structured query. + * Query must specify collection with all descendants and be ordered by name + * ascending. Other filters, order bys, limits, offsets, and start/end + * cursors are not supported. + * @param {number} request.partitionCount + * The desired maximum number of partition points. + * The partitions may be returned across multiple pages of results. + * The number must be positive. The actual number of partitions + * returned may be fewer. + * + * For example, this may be set to one fewer than the number of parallel + * queries to be run, or in running a data pipeline job, one fewer than the + * number of workers or compute instances available. + * @param {string} request.pageToken + * The `next_page_token` value returned from a previous call to + * PartitionQuery that may be used to get an additional set of results. + * There are no ordering guarantees between sets of results. Thus, using + * multiple sets of results will require merging the different result sets. + * + * For example, two subsequent calls using a page_token may return: + * + * * cursor B, cursor M, cursor Q + * * cursor A, cursor U, cursor W + * + * To obtain a complete result set ordered with respect to the results of the + * query supplied to PartitionQuery, the results sets should be merged: + * cursor A, cursor B, cursor M, cursor Q, cursor U, cursor W + * @param {number} request.pageSize + * The maximum number of partitions to return in this call, subject to + * `partition_count`. + * + * For example, if `partition_count` = 10 and `page_size` = 8, the first call + * to PartitionQuery will return up to 8 partitions and a `next_page_token` + * if more results exist. A second call to PartitionQuery will return up to + * 2 partitions, to complete the total of 10 specified in `partition_count`. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is Array of [Cursor]{@link google.firestore.v1beta1.Cursor}. + * The client library will perform auto-pagination by default: it will call the API as many + * times as needed and will merge results from all the pages into this array. + * Note that it can affect your quota. + * We recommend using `partitionQueryAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + */ partitionQuery( request?: protos.google.firestore.v1beta1.IPartitionQueryRequest, options?: CallOptions @@ -765,16 +1061,41 @@ export declare class FirestoreClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) * for more details and examples. - * @example - * const iterable = client.partitionQueryAsync(request); - * for await (const response of iterable) { - * // process response - * } + * @example include:samples/generated/v1beta1/firestore.partition_query.js + * region_tag:firestore_v1beta1_generated_Firestore_PartitionQuery_async */ partitionQueryAsync( request?: protos.google.firestore.v1beta1.IPartitionQueryRequest, options?: CallOptions ): AsyncIterable; + /** + * Lists all the collection IDs underneath a document. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. The parent document. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * For example: + * `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + * @param {number} request.pageSize + * The maximum number of results to return. + * @param {string} request.pageToken + * A page token. Must be a value from + * {@link google.firestore.v1beta1.ListCollectionIdsResponse|ListCollectionIdsResponse}. + * @param {object} [options] + * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is Array of string. + * The client library will perform auto-pagination by default: it will call the API as many + * times as needed and will merge results from all the pages into this array. + * Note that it can affect your quota. + * We recommend using `listCollectionIdsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + */ listCollectionIds( request?: protos.google.firestore.v1beta1.IListCollectionIdsRequest, options?: CallOptions @@ -862,11 +1183,8 @@ export declare class FirestoreClient { * Please see the * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) * for more details and examples. - * @example - * const iterable = client.listCollectionIdsAsync(request); - * for await (const response of iterable) { - * // process response - * } + * @example include:samples/generated/v1beta1/firestore.list_collection_ids.js + * region_tag:firestore_v1beta1_generated_Firestore_ListCollectionIds_async */ listCollectionIdsAsync( request?: protos.google.firestore.v1beta1.IListCollectionIdsRequest,