diff --git a/google/cloud/spanner_admin_database_v1/services/database_admin/async_client.py b/google/cloud/spanner_admin_database_v1/services/database_admin/async_client.py index 41dcf45c48..0e08065a7d 100644 --- a/google/cloud/spanner_admin_database_v1/services/database_admin/async_client.py +++ b/google/cloud/spanner_admin_database_v1/services/database_admin/async_client.py @@ -84,10 +84,10 @@ class DatabaseAdminAsyncClient: The Cloud Spanner Database Admin API can be used to: - - create, drop, and list databases - - update the schema of pre-existing databases - - create, delete, copy and list backups for a database - - restore a database from an existing backup + - create, drop, and list databases + - update the schema of pre-existing databases + - create, delete, copy and list backups for a database + - restore a database from an existing backup """ _client: DatabaseAdminClient @@ -749,26 +749,26 @@ async def update_database( While the operation is pending: - - The database's - [reconciling][google.spanner.admin.database.v1.Database.reconciling] - field is set to true. - - Cancelling the operation is best-effort. If the cancellation - succeeds, the operation metadata's - [cancel_time][google.spanner.admin.database.v1.UpdateDatabaseMetadata.cancel_time] - is set, the updates are reverted, and the operation - terminates with a ``CANCELLED`` status. - - New UpdateDatabase requests will return a - ``FAILED_PRECONDITION`` error until the pending operation is - done (returns successfully or with error). - - Reading the database via the API continues to give the - pre-request values. + - The database's + [reconciling][google.spanner.admin.database.v1.Database.reconciling] + field is set to true. + - Cancelling the operation is best-effort. If the cancellation + succeeds, the operation metadata's + [cancel_time][google.spanner.admin.database.v1.UpdateDatabaseMetadata.cancel_time] + is set, the updates are reverted, and the operation terminates + with a ``CANCELLED`` status. + - New UpdateDatabase requests will return a + ``FAILED_PRECONDITION`` error until the pending operation is + done (returns successfully or with error). + - Reading the database via the API continues to give the + pre-request values. Upon completion of the returned operation: - - The new values are in effect and readable via the API. - - The database's - [reconciling][google.spanner.admin.database.v1.Database.reconciling] - field becomes false. + - The new values are in effect and readable via the API. + - The database's + [reconciling][google.spanner.admin.database.v1.Database.reconciling] + field becomes false. The returned [long-running operation][google.longrunning.Operation] will have a name of the @@ -1384,19 +1384,19 @@ async def sample_set_iam_policy(): constraints based on attributes of the request, the resource, or both. To learn which resources support conditions in their IAM policies, see the [IAM - documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies). + documentation](https://cloud.google.com/iam/help/conditions/resource-policies). **JSON example:** - :literal:`\` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` + :literal:`` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` **YAML example:** - :literal:`\` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` + :literal:`` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` For a description of IAM and its features, see the [IAM - documentation](\ https://cloud.google.com/iam/docs/). + documentation](https://cloud.google.com/iam/docs/). """ # Create or coerce a protobuf request object. @@ -1531,19 +1531,19 @@ async def sample_get_iam_policy(): constraints based on attributes of the request, the resource, or both. To learn which resources support conditions in their IAM policies, see the [IAM - documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies). + documentation](https://cloud.google.com/iam/help/conditions/resource-policies). **JSON example:** - :literal:`\` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` + :literal:`` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` **YAML example:** - :literal:`\` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` + :literal:`` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` For a description of IAM and its features, see the [IAM - documentation](\ https://cloud.google.com/iam/docs/). + documentation](https://cloud.google.com/iam/docs/). """ # Create or coerce a protobuf request object. @@ -2226,7 +2226,7 @@ async def sample_update_backup(): required. Other fields are ignored. Update is only supported for the following fields: - - ``backup.expire_time``. + - ``backup.expire_time``. This corresponds to the ``backup`` field on the ``request`` instance; if ``request`` is provided, this diff --git a/google/cloud/spanner_admin_database_v1/services/database_admin/client.py b/google/cloud/spanner_admin_database_v1/services/database_admin/client.py index 08211de569..5f85aa39b1 100644 --- a/google/cloud/spanner_admin_database_v1/services/database_admin/client.py +++ b/google/cloud/spanner_admin_database_v1/services/database_admin/client.py @@ -127,10 +127,10 @@ class DatabaseAdminClient(metaclass=DatabaseAdminClientMeta): The Cloud Spanner Database Admin API can be used to: - - create, drop, and list databases - - update the schema of pre-existing databases - - create, delete, copy and list backups for a database - - restore a database from an existing backup + - create, drop, and list databases + - update the schema of pre-existing databases + - create, delete, copy and list backups for a database + - restore a database from an existing backup """ @staticmethod @@ -1297,26 +1297,26 @@ def update_database( While the operation is pending: - - The database's - [reconciling][google.spanner.admin.database.v1.Database.reconciling] - field is set to true. - - Cancelling the operation is best-effort. If the cancellation - succeeds, the operation metadata's - [cancel_time][google.spanner.admin.database.v1.UpdateDatabaseMetadata.cancel_time] - is set, the updates are reverted, and the operation - terminates with a ``CANCELLED`` status. - - New UpdateDatabase requests will return a - ``FAILED_PRECONDITION`` error until the pending operation is - done (returns successfully or with error). - - Reading the database via the API continues to give the - pre-request values. + - The database's + [reconciling][google.spanner.admin.database.v1.Database.reconciling] + field is set to true. + - Cancelling the operation is best-effort. If the cancellation + succeeds, the operation metadata's + [cancel_time][google.spanner.admin.database.v1.UpdateDatabaseMetadata.cancel_time] + is set, the updates are reverted, and the operation terminates + with a ``CANCELLED`` status. + - New UpdateDatabase requests will return a + ``FAILED_PRECONDITION`` error until the pending operation is + done (returns successfully or with error). + - Reading the database via the API continues to give the + pre-request values. Upon completion of the returned operation: - - The new values are in effect and readable via the API. - - The database's - [reconciling][google.spanner.admin.database.v1.Database.reconciling] - field becomes false. + - The new values are in effect and readable via the API. + - The database's + [reconciling][google.spanner.admin.database.v1.Database.reconciling] + field becomes false. The returned [long-running operation][google.longrunning.Operation] will have a name of the @@ -1920,19 +1920,19 @@ def sample_set_iam_policy(): constraints based on attributes of the request, the resource, or both. To learn which resources support conditions in their IAM policies, see the [IAM - documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies). + documentation](https://cloud.google.com/iam/help/conditions/resource-policies). **JSON example:** - :literal:`\` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` + :literal:`` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` **YAML example:** - :literal:`\` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` + :literal:`` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` For a description of IAM and its features, see the [IAM - documentation](\ https://cloud.google.com/iam/docs/). + documentation](https://cloud.google.com/iam/docs/). """ # Create or coerce a protobuf request object. @@ -2068,19 +2068,19 @@ def sample_get_iam_policy(): constraints based on attributes of the request, the resource, or both. To learn which resources support conditions in their IAM policies, see the [IAM - documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies). + documentation](https://cloud.google.com/iam/help/conditions/resource-policies). **JSON example:** - :literal:`\` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` + :literal:`` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` **YAML example:** - :literal:`\` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` + :literal:`` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` For a description of IAM and its features, see the [IAM - documentation](\ https://cloud.google.com/iam/docs/). + documentation](https://cloud.google.com/iam/docs/). """ # Create or coerce a protobuf request object. @@ -2756,7 +2756,7 @@ def sample_update_backup(): required. Other fields are ignored. Update is only supported for the following fields: - - ``backup.expire_time``. + - ``backup.expire_time``. This corresponds to the ``backup`` field on the ``request`` instance; if ``request`` is provided, this diff --git a/google/cloud/spanner_admin_database_v1/services/database_admin/transports/grpc.py b/google/cloud/spanner_admin_database_v1/services/database_admin/transports/grpc.py index 7d6ce40830..8f31a1fb98 100644 --- a/google/cloud/spanner_admin_database_v1/services/database_admin/transports/grpc.py +++ b/google/cloud/spanner_admin_database_v1/services/database_admin/transports/grpc.py @@ -126,10 +126,10 @@ class DatabaseAdminGrpcTransport(DatabaseAdminTransport): The Cloud Spanner Database Admin API can be used to: - - create, drop, and list databases - - update the schema of pre-existing databases - - create, delete, copy and list backups for a database - - restore a database from an existing backup + - create, drop, and list databases + - update the schema of pre-existing databases + - create, delete, copy and list backups for a database + - restore a database from an existing backup This class defines the same methods as the primary client, so the primary client can load the underlying transport implementation @@ -464,26 +464,26 @@ def update_database( While the operation is pending: - - The database's - [reconciling][google.spanner.admin.database.v1.Database.reconciling] - field is set to true. - - Cancelling the operation is best-effort. If the cancellation - succeeds, the operation metadata's - [cancel_time][google.spanner.admin.database.v1.UpdateDatabaseMetadata.cancel_time] - is set, the updates are reverted, and the operation - terminates with a ``CANCELLED`` status. - - New UpdateDatabase requests will return a - ``FAILED_PRECONDITION`` error until the pending operation is - done (returns successfully or with error). - - Reading the database via the API continues to give the - pre-request values. + - The database's + [reconciling][google.spanner.admin.database.v1.Database.reconciling] + field is set to true. + - Cancelling the operation is best-effort. If the cancellation + succeeds, the operation metadata's + [cancel_time][google.spanner.admin.database.v1.UpdateDatabaseMetadata.cancel_time] + is set, the updates are reverted, and the operation terminates + with a ``CANCELLED`` status. + - New UpdateDatabase requests will return a + ``FAILED_PRECONDITION`` error until the pending operation is + done (returns successfully or with error). + - Reading the database via the API continues to give the + pre-request values. Upon completion of the returned operation: - - The new values are in effect and readable via the API. - - The database's - [reconciling][google.spanner.admin.database.v1.Database.reconciling] - field becomes false. + - The new values are in effect and readable via the API. + - The database's + [reconciling][google.spanner.admin.database.v1.Database.reconciling] + field becomes false. The returned [long-running operation][google.longrunning.Operation] will have a name of the diff --git a/google/cloud/spanner_admin_database_v1/services/database_admin/transports/grpc_asyncio.py b/google/cloud/spanner_admin_database_v1/services/database_admin/transports/grpc_asyncio.py index 72eb10b7b3..5171d84d40 100644 --- a/google/cloud/spanner_admin_database_v1/services/database_admin/transports/grpc_asyncio.py +++ b/google/cloud/spanner_admin_database_v1/services/database_admin/transports/grpc_asyncio.py @@ -132,10 +132,10 @@ class DatabaseAdminGrpcAsyncIOTransport(DatabaseAdminTransport): The Cloud Spanner Database Admin API can be used to: - - create, drop, and list databases - - update the schema of pre-existing databases - - create, delete, copy and list backups for a database - - restore a database from an existing backup + - create, drop, and list databases + - update the schema of pre-existing databases + - create, delete, copy and list backups for a database + - restore a database from an existing backup This class defines the same methods as the primary client, so the primary client can load the underlying transport implementation @@ -475,26 +475,26 @@ def update_database( While the operation is pending: - - The database's - [reconciling][google.spanner.admin.database.v1.Database.reconciling] - field is set to true. - - Cancelling the operation is best-effort. If the cancellation - succeeds, the operation metadata's - [cancel_time][google.spanner.admin.database.v1.UpdateDatabaseMetadata.cancel_time] - is set, the updates are reverted, and the operation - terminates with a ``CANCELLED`` status. - - New UpdateDatabase requests will return a - ``FAILED_PRECONDITION`` error until the pending operation is - done (returns successfully or with error). - - Reading the database via the API continues to give the - pre-request values. + - The database's + [reconciling][google.spanner.admin.database.v1.Database.reconciling] + field is set to true. + - Cancelling the operation is best-effort. If the cancellation + succeeds, the operation metadata's + [cancel_time][google.spanner.admin.database.v1.UpdateDatabaseMetadata.cancel_time] + is set, the updates are reverted, and the operation terminates + with a ``CANCELLED`` status. + - New UpdateDatabase requests will return a + ``FAILED_PRECONDITION`` error until the pending operation is + done (returns successfully or with error). + - Reading the database via the API continues to give the + pre-request values. Upon completion of the returned operation: - - The new values are in effect and readable via the API. - - The database's - [reconciling][google.spanner.admin.database.v1.Database.reconciling] - field becomes false. + - The new values are in effect and readable via the API. + - The database's + [reconciling][google.spanner.admin.database.v1.Database.reconciling] + field becomes false. The returned [long-running operation][google.longrunning.Operation] will have a name of the diff --git a/google/cloud/spanner_admin_database_v1/services/database_admin/transports/rest.py b/google/cloud/spanner_admin_database_v1/services/database_admin/transports/rest.py index c144266a1e..df70fc5636 100644 --- a/google/cloud/spanner_admin_database_v1/services/database_admin/transports/rest.py +++ b/google/cloud/spanner_admin_database_v1/services/database_admin/transports/rest.py @@ -1584,10 +1584,10 @@ class DatabaseAdminRestTransport(_BaseDatabaseAdminRestTransport): The Cloud Spanner Database Admin API can be used to: - - create, drop, and list databases - - update the schema of pre-existing databases - - create, delete, copy and list backups for a database - - restore a database from an existing backup + - create, drop, and list databases + - update the schema of pre-existing databases + - create, delete, copy and list backups for a database + - restore a database from an existing backup This class defines the same methods as the primary client, so the primary client can load the underlying transport implementation diff --git a/google/cloud/spanner_admin_database_v1/types/backup.py b/google/cloud/spanner_admin_database_v1/types/backup.py index 15e1e2836c..da236fb4ff 100644 --- a/google/cloud/spanner_admin_database_v1/types/backup.py +++ b/google/cloud/spanner_admin_database_v1/types/backup.py @@ -540,7 +540,7 @@ class UpdateBackupRequest(proto.Message): required. Other fields are ignored. Update is only supported for the following fields: - - ``backup.expire_time``. + - ``backup.expire_time``. update_mask (google.protobuf.field_mask_pb2.FieldMask): Required. A mask specifying which fields (e.g. ``expire_time``) in the Backup resource should be updated. @@ -617,17 +617,17 @@ class ListBackupsRequest(proto.Message): [Backup][google.spanner.admin.database.v1.Backup] are eligible for filtering: - - ``name`` - - ``database`` - - ``state`` - - ``create_time`` (and values are of the format - YYYY-MM-DDTHH:MM:SSZ) - - ``expire_time`` (and values are of the format - YYYY-MM-DDTHH:MM:SSZ) - - ``version_time`` (and values are of the format - YYYY-MM-DDTHH:MM:SSZ) - - ``size_bytes`` - - ``backup_schedules`` + - ``name`` + - ``database`` + - ``state`` + - ``create_time`` (and values are of the format + YYYY-MM-DDTHH:MM:SSZ) + - ``expire_time`` (and values are of the format + YYYY-MM-DDTHH:MM:SSZ) + - ``version_time`` (and values are of the format + YYYY-MM-DDTHH:MM:SSZ) + - ``size_bytes`` + - ``backup_schedules`` You can combine multiple expressions by enclosing each expression in parentheses. By default, expressions are @@ -636,23 +636,23 @@ class ListBackupsRequest(proto.Message): Here are a few examples: - - ``name:Howl`` - The backup's name contains the string - "howl". - - ``database:prod`` - The database's name contains the - string "prod". - - ``state:CREATING`` - The backup is pending creation. - - ``state:READY`` - The backup is fully created and ready - for use. - - ``(name:howl) AND (create_time < \"2018-03-28T14:50:00Z\")`` - - The backup name contains the string "howl" and - ``create_time`` of the backup is before - 2018-03-28T14:50:00Z. - - ``expire_time < \"2018-03-28T14:50:00Z\"`` - The backup - ``expire_time`` is before 2018-03-28T14:50:00Z. - - ``size_bytes > 10000000000`` - The backup's size is - greater than 10GB - - ``backup_schedules:daily`` - The backup is created from a - schedule with "daily" in its name. + - ``name:Howl`` - The backup's name contains the string + "howl". + - ``database:prod`` - The database's name contains the + string "prod". + - ``state:CREATING`` - The backup is pending creation. + - ``state:READY`` - The backup is fully created and ready + for use. + - ``(name:howl) AND (create_time < \"2018-03-28T14:50:00Z\")`` + - The backup name contains the string "howl" and + ``create_time`` of the backup is before + 2018-03-28T14:50:00Z. + - ``expire_time < \"2018-03-28T14:50:00Z\"`` - The backup + ``expire_time`` is before 2018-03-28T14:50:00Z. + - ``size_bytes > 10000000000`` - The backup's size is + greater than 10GB + - ``backup_schedules:daily`` - The backup is created from a + schedule with "daily" in its name. page_size (int): Number of backups to be returned in the response. If 0 or less, defaults to the server's @@ -736,21 +736,21 @@ class ListBackupOperationsRequest(proto.Message): [operation][google.longrunning.Operation] are eligible for filtering: - - ``name`` - The name of the long-running operation - - ``done`` - False if the operation is in progress, else - true. - - ``metadata.@type`` - the type of metadata. For example, - the type string for - [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata] - is - ``type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata``. - - ``metadata.`` - any field in metadata.value. - ``metadata.@type`` must be specified first if filtering - on metadata fields. - - ``error`` - Error associated with the long-running - operation. - - ``response.@type`` - the type of response. - - ``response.`` - any field in response.value. + - ``name`` - The name of the long-running operation + - ``done`` - False if the operation is in progress, else + true. + - ``metadata.@type`` - the type of metadata. For example, + the type string for + [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata] + is + ``type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata``. + - ``metadata.`` - any field in metadata.value. + ``metadata.@type`` must be specified first if filtering on + metadata fields. + - ``error`` - Error associated with the long-running + operation. + - ``response.@type`` - the type of response. + - ``response.`` - any field in response.value. You can combine multiple expressions by enclosing each expression in parentheses. By default, expressions are @@ -759,55 +759,55 @@ class ListBackupOperationsRequest(proto.Message): Here are a few examples: - - ``done:true`` - The operation is complete. - - ``(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata) AND`` - ``metadata.database:prod`` - Returns operations where: - - - The operation's metadata type is - [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata]. - - The source database name of backup contains the string - "prod". - - - ``(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata) AND`` - ``(metadata.name:howl) AND`` - ``(metadata.progress.start_time < \"2018-03-28T14:50:00Z\") AND`` - ``(error:*)`` - Returns operations where: - - - The operation's metadata type is - [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata]. - - The backup name contains the string "howl". - - The operation started before 2018-03-28T14:50:00Z. - - The operation resulted in an error. - - - ``(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CopyBackupMetadata) AND`` - ``(metadata.source_backup:test) AND`` - ``(metadata.progress.start_time < \"2022-01-18T14:50:00Z\") AND`` - ``(error:*)`` - Returns operations where: - - - The operation's metadata type is - [CopyBackupMetadata][google.spanner.admin.database.v1.CopyBackupMetadata]. - - The source backup name contains the string "test". - - The operation started before 2022-01-18T14:50:00Z. - - The operation resulted in an error. - - - ``((metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata) AND`` - ``(metadata.database:test_db)) OR`` - ``((metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CopyBackupMetadata) AND`` - ``(metadata.source_backup:test_bkp)) AND`` - ``(error:*)`` - Returns operations where: - - - The operation's metadata matches either of criteria: - - - The operation's metadata type is - [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata] - AND the source database name of the backup contains - the string "test_db" - - The operation's metadata type is - [CopyBackupMetadata][google.spanner.admin.database.v1.CopyBackupMetadata] - AND the source backup name contains the string - "test_bkp" - - - The operation resulted in an error. + - ``done:true`` - The operation is complete. + - ``(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata) AND`` + ``metadata.database:prod`` - Returns operations where: + + - The operation's metadata type is + [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata]. + - The source database name of backup contains the string + "prod". + + - ``(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata) AND`` + ``(metadata.name:howl) AND`` + ``(metadata.progress.start_time < \"2018-03-28T14:50:00Z\") AND`` + ``(error:*)`` - Returns operations where: + + - The operation's metadata type is + [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata]. + - The backup name contains the string "howl". + - The operation started before 2018-03-28T14:50:00Z. + - The operation resulted in an error. + + - ``(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CopyBackupMetadata) AND`` + ``(metadata.source_backup:test) AND`` + ``(metadata.progress.start_time < \"2022-01-18T14:50:00Z\") AND`` + ``(error:*)`` - Returns operations where: + + - The operation's metadata type is + [CopyBackupMetadata][google.spanner.admin.database.v1.CopyBackupMetadata]. + - The source backup name contains the string "test". + - The operation started before 2022-01-18T14:50:00Z. + - The operation resulted in an error. + + - ``((metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata) AND`` + ``(metadata.database:test_db)) OR`` + ``((metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CopyBackupMetadata) AND`` + ``(metadata.source_backup:test_bkp)) AND`` + ``(error:*)`` - Returns operations where: + + - The operation's metadata matches either of criteria: + + - The operation's metadata type is + [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata] + AND the source database name of the backup contains + the string "test_db" + - The operation's metadata type is + [CopyBackupMetadata][google.spanner.admin.database.v1.CopyBackupMetadata] + AND the source backup name contains the string + "test_bkp" + + - The operation resulted in an error. page_size (int): Number of operations to be returned in the response. If 0 or less, defaults to the server's @@ -940,17 +940,16 @@ class CreateBackupEncryptionConfig(proto.Message): regions of the backup's instance configuration. Some examples: - - For single region instance configs, specify a single - regional location KMS key. - - For multi-regional instance configs of type - GOOGLE_MANAGED, either specify a multi-regional location - KMS key or multiple regional location KMS keys that cover - all regions in the instance config. - - For an instance config of type USER_MANAGED, please - specify only regional location KMS keys to cover each - region in the instance config. Multi-regional location - KMS keys are not supported for USER_MANAGED instance - configs. + - For single region instance configs, specify a single + regional location KMS key. + - For multi-regional instance configs of type + GOOGLE_MANAGED, either specify a multi-regional location + KMS key or multiple regional location KMS keys that cover + all regions in the instance config. + - For an instance config of type USER_MANAGED, please + specify only regional location KMS keys to cover each + region in the instance config. Multi-regional location KMS + keys are not supported for USER_MANAGED instance configs. """ class EncryptionType(proto.Enum): @@ -1014,17 +1013,16 @@ class CopyBackupEncryptionConfig(proto.Message): regions of the backup's instance configuration. Some examples: - - For single region instance configs, specify a single - regional location KMS key. - - For multi-regional instance configs of type - GOOGLE_MANAGED, either specify a multi-regional location - KMS key or multiple regional location KMS keys that cover - all regions in the instance config. - - For an instance config of type USER_MANAGED, please - specify only regional location KMS keys to cover each - region in the instance config. Multi-regional location - KMS keys are not supported for USER_MANAGED instance - configs. + - For single region instance configs, specify a single + regional location KMS key. + - For multi-regional instance configs of type + GOOGLE_MANAGED, either specify a multi-regional location + KMS key or multiple regional location KMS keys that cover + all regions in the instance config. + - For an instance config of type USER_MANAGED, please + specify only regional location KMS keys to cover each + region in the instance config. Multi-regional location KMS + keys are not supported for USER_MANAGED instance configs. """ class EncryptionType(proto.Enum): diff --git a/google/cloud/spanner_admin_database_v1/types/backup_schedule.py b/google/cloud/spanner_admin_database_v1/types/backup_schedule.py index 130c6879a3..2773c1ef63 100644 --- a/google/cloud/spanner_admin_database_v1/types/backup_schedule.py +++ b/google/cloud/spanner_admin_database_v1/types/backup_schedule.py @@ -167,15 +167,15 @@ class CrontabSpec(proto.Message): hour, 1 day, 1 week and 1 month. Examples of valid cron specifications: - - ``0 2/12 * * *`` : every 12 hours at (2, 14) hours past - midnight in UTC. - - ``0 2,14 * * *`` : every 12 hours at (2,14) hours past - midnight in UTC. - - ``0 2 * * *`` : once a day at 2 past midnight in UTC. - - ``0 2 * * 0`` : once a week every Sunday at 2 past - midnight in UTC. - - ``0 2 8 * *`` : once a month on 8th day at 2 past - midnight in UTC. + - ``0 2/12 * * *`` : every 12 hours at (2, 14) hours past + midnight in UTC. + - ``0 2,14 * * *`` : every 12 hours at (2,14) hours past + midnight in UTC. + - ``0 2 * * *`` : once a day at 2 past midnight in UTC. + - ``0 2 * * 0`` : once a week every Sunday at 2 past + midnight in UTC. + - ``0 2 8 * *`` : once a month on 8th day at 2 past midnight + in UTC. time_zone (str): Output only. The time zone of the times in ``CrontabSpec.text``. Currently only UTC is supported. diff --git a/google/cloud/spanner_admin_database_v1/types/common.py b/google/cloud/spanner_admin_database_v1/types/common.py index 3b78c4b153..fff1a8756c 100644 --- a/google/cloud/spanner_admin_database_v1/types/common.py +++ b/google/cloud/spanner_admin_database_v1/types/common.py @@ -99,17 +99,17 @@ class EncryptionConfig(proto.Message): regions of the database instance configuration. Some examples: - - For single region database instance configs, specify a - single regional location KMS key. - - For multi-regional database instance configs of type - GOOGLE_MANAGED, either specify a multi-regional location - KMS key or multiple regional location KMS keys that cover - all regions in the instance config. - - For a database instance config of type USER_MANAGED, - please specify only regional location KMS keys to cover - each region in the instance config. Multi-regional - location KMS keys are not supported for USER_MANAGED - instance configs. + - For single region database instance configs, specify a + single regional location KMS key. + - For multi-regional database instance configs of type + GOOGLE_MANAGED, either specify a multi-regional location + KMS key or multiple regional location KMS keys that cover + all regions in the instance config. + - For a database instance config of type USER_MANAGED, + please specify only regional location KMS keys to cover + each region in the instance config. Multi-regional + location KMS keys are not supported for USER_MANAGED + instance configs. """ kms_key_name: str = proto.Field( diff --git a/google/cloud/spanner_admin_database_v1/types/spanner_database_admin.py b/google/cloud/spanner_admin_database_v1/types/spanner_database_admin.py index 4f60bfc0b9..c82fdc87df 100644 --- a/google/cloud/spanner_admin_database_v1/types/spanner_database_admin.py +++ b/google/cloud/spanner_admin_database_v1/types/spanner_database_admin.py @@ -786,21 +786,21 @@ class ListDatabaseOperationsRequest(proto.Message): [Operation][google.longrunning.Operation] are eligible for filtering: - - ``name`` - The name of the long-running operation - - ``done`` - False if the operation is in progress, else - true. - - ``metadata.@type`` - the type of metadata. For example, - the type string for - [RestoreDatabaseMetadata][google.spanner.admin.database.v1.RestoreDatabaseMetadata] - is - ``type.googleapis.com/google.spanner.admin.database.v1.RestoreDatabaseMetadata``. - - ``metadata.`` - any field in metadata.value. - ``metadata.@type`` must be specified first, if filtering - on metadata fields. - - ``error`` - Error associated with the long-running - operation. - - ``response.@type`` - the type of response. - - ``response.`` - any field in response.value. + - ``name`` - The name of the long-running operation + - ``done`` - False if the operation is in progress, else + true. + - ``metadata.@type`` - the type of metadata. For example, + the type string for + [RestoreDatabaseMetadata][google.spanner.admin.database.v1.RestoreDatabaseMetadata] + is + ``type.googleapis.com/google.spanner.admin.database.v1.RestoreDatabaseMetadata``. + - ``metadata.`` - any field in metadata.value. + ``metadata.@type`` must be specified first, if filtering + on metadata fields. + - ``error`` - Error associated with the long-running + operation. + - ``response.@type`` - the type of response. + - ``response.`` - any field in response.value. You can combine multiple expressions by enclosing each expression in parentheses. By default, expressions are @@ -809,21 +809,21 @@ class ListDatabaseOperationsRequest(proto.Message): Here are a few examples: - - ``done:true`` - The operation is complete. - - ``(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.RestoreDatabaseMetadata) AND`` - ``(metadata.source_type:BACKUP) AND`` - ``(metadata.backup_info.backup:backup_howl) AND`` - ``(metadata.name:restored_howl) AND`` - ``(metadata.progress.start_time < \"2018-03-28T14:50:00Z\") AND`` - ``(error:*)`` - Return operations where: - - - The operation's metadata type is - [RestoreDatabaseMetadata][google.spanner.admin.database.v1.RestoreDatabaseMetadata]. - - The database is restored from a backup. - - The backup name contains "backup_howl". - - The restored database's name contains "restored_howl". - - The operation started before 2018-03-28T14:50:00Z. - - The operation resulted in an error. + - ``done:true`` - The operation is complete. + - ``(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.RestoreDatabaseMetadata) AND`` + ``(metadata.source_type:BACKUP) AND`` + ``(metadata.backup_info.backup:backup_howl) AND`` + ``(metadata.name:restored_howl) AND`` + ``(metadata.progress.start_time < \"2018-03-28T14:50:00Z\") AND`` + ``(error:*)`` - Return operations where: + + - The operation's metadata type is + [RestoreDatabaseMetadata][google.spanner.admin.database.v1.RestoreDatabaseMetadata]. + - The database is restored from a backup. + - The backup name contains "backup_howl". + - The restored database's name contains "restored_howl". + - The operation started before 2018-03-28T14:50:00Z. + - The operation resulted in an error. page_size (int): Number of operations to be returned in the response. If 0 or less, defaults to the server's @@ -967,17 +967,17 @@ class RestoreDatabaseEncryptionConfig(proto.Message): regions of the database instance configuration. Some examples: - - For single region database instance configs, specify a - single regional location KMS key. - - For multi-regional database instance configs of type - GOOGLE_MANAGED, either specify a multi-regional location - KMS key or multiple regional location KMS keys that cover - all regions in the instance config. - - For a database instance config of type USER_MANAGED, - please specify only regional location KMS keys to cover - each region in the instance config. Multi-regional - location KMS keys are not supported for USER_MANAGED - instance configs. + - For single region database instance configs, specify a + single regional location KMS key. + - For multi-regional database instance configs of type + GOOGLE_MANAGED, either specify a multi-regional location + KMS key or multiple regional location KMS keys that cover + all regions in the instance config. + - For a database instance config of type USER_MANAGED, + please specify only regional location KMS keys to cover + each region in the instance config. Multi-regional + location KMS keys are not supported for USER_MANAGED + instance configs. """ class EncryptionType(proto.Enum): diff --git a/google/cloud/spanner_admin_instance_v1/services/instance_admin/async_client.py b/google/cloud/spanner_admin_instance_v1/services/instance_admin/async_client.py index 549946f98c..1e87fc5a63 100644 --- a/google/cloud/spanner_admin_instance_v1/services/instance_admin/async_client.py +++ b/google/cloud/spanner_admin_instance_v1/services/instance_admin/async_client.py @@ -598,24 +598,24 @@ async def create_instance_config( Immediately after the request returns: - - The instance configuration is readable via the API, with all - requested attributes. The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field is set to true. Its state is ``CREATING``. + - The instance configuration is readable via the API, with all + requested attributes. The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field is set to true. Its state is ``CREATING``. While the operation is pending: - - Cancelling the operation renders the instance configuration - immediately unreadable via the API. - - Except for deleting the creating resource, all other attempts - to modify the instance configuration are rejected. + - Cancelling the operation renders the instance configuration + immediately unreadable via the API. + - Except for deleting the creating resource, all other attempts + to modify the instance configuration are rejected. Upon completion of the returned operation: - - Instances can be created using the instance configuration. - - The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field becomes false. Its state becomes ``READY``. + - Instances can be created using the instance configuration. + - The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field becomes false. Its state becomes ``READY``. The returned long-running operation will have a name of the format ``/operations/`` and @@ -794,31 +794,30 @@ async def update_instance_config( Immediately after the request returns: - - The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field is set to true. + - The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field is set to true. While the operation is pending: - - Cancelling the operation sets its metadata's - [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata.cancel_time]. - The operation is guaranteed to succeed at undoing all - changes, after which point it terminates with a ``CANCELLED`` - status. - - All other attempts to modify the instance configuration are - rejected. - - Reading the instance configuration via the API continues to - give the pre-request values. + - Cancelling the operation sets its metadata's + [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata.cancel_time]. + The operation is guaranteed to succeed at undoing all changes, + after which point it terminates with a ``CANCELLED`` status. + - All other attempts to modify the instance configuration are + rejected. + - Reading the instance configuration via the API continues to + give the pre-request values. Upon completion of the returned operation: - - Creating instances using the instance configuration uses the - new values. - - The new values of the instance configuration are readable via - the API. - - The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field becomes false. + - Creating instances using the instance configuration uses the + new values. + - The new values of the instance configuration are readable via + the API. + - The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field becomes false. The returned long-running operation will have a name of the format ``/operations/`` and @@ -1621,25 +1620,25 @@ async def create_instance( Immediately upon completion of this request: - - The instance is readable via the API, with all requested - attributes but no allocated resources. Its state is - ``CREATING``. + - The instance is readable via the API, with all requested + attributes but no allocated resources. Its state is + ``CREATING``. Until completion of the returned operation: - - Cancelling the operation renders the instance immediately - unreadable via the API. - - The instance can be deleted. - - All other attempts to modify the instance are rejected. + - Cancelling the operation renders the instance immediately + unreadable via the API. + - The instance can be deleted. + - All other attempts to modify the instance are rejected. Upon completion of the returned operation: - - Billing for all successfully-allocated resources begins (some - types may have lower than the requested levels). - - Databases can be created in the instance. - - The instance's allocated resource levels are readable via the - API. - - The instance's state becomes ``READY``. + - Billing for all successfully-allocated resources begins (some + types may have lower than the requested levels). + - Databases can be created in the instance. + - The instance's allocated resource levels are readable via the + API. + - The instance's state becomes ``READY``. The returned long-running operation will have a name of the format ``/operations/`` and can be @@ -1812,29 +1811,29 @@ async def update_instance( Immediately upon completion of this request: - - For resource types for which a decrease in the instance's - allocation has been requested, billing is based on the - newly-requested level. + - For resource types for which a decrease in the instance's + allocation has been requested, billing is based on the + newly-requested level. Until completion of the returned operation: - - Cancelling the operation sets its metadata's - [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], - and begins restoring resources to their pre-request values. - The operation is guaranteed to succeed at undoing all - resource changes, after which point it terminates with a - ``CANCELLED`` status. - - All other attempts to modify the instance are rejected. - - Reading the instance via the API continues to give the - pre-request resource levels. + - Cancelling the operation sets its metadata's + [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], + and begins restoring resources to their pre-request values. + The operation is guaranteed to succeed at undoing all resource + changes, after which point it terminates with a ``CANCELLED`` + status. + - All other attempts to modify the instance are rejected. + - Reading the instance via the API continues to give the + pre-request resource levels. Upon completion of the returned operation: - - Billing begins for all successfully-allocated resources (some - types may have lower than the requested levels). - - All newly-reserved resources are available for serving the - instance's tables. - - The instance's new resource levels are readable via the API. + - Billing begins for all successfully-allocated resources (some + types may have lower than the requested levels). + - All newly-reserved resources are available for serving the + instance's tables. + - The instance's new resource levels are readable via the API. The returned long-running operation will have a name of the format ``/operations/`` and can be @@ -2004,13 +2003,13 @@ async def delete_instance( Immediately upon completion of the request: - - Billing ceases for all of the instance's reserved resources. + - Billing ceases for all of the instance's reserved resources. Soon afterward: - - The instance and *all of its databases* immediately and - irrevocably disappear from the API. All data in the databases - is permanently deleted. + - The instance and *all of its databases* immediately and + irrevocably disappear from the API. All data in the databases + is permanently deleted. .. code-block:: python @@ -2182,19 +2181,19 @@ async def sample_set_iam_policy(): constraints based on attributes of the request, the resource, or both. To learn which resources support conditions in their IAM policies, see the [IAM - documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies). + documentation](https://cloud.google.com/iam/help/conditions/resource-policies). **JSON example:** - :literal:`\` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` + :literal:`` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` **YAML example:** - :literal:`\` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` + :literal:`` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` For a description of IAM and its features, see the [IAM - documentation](\ https://cloud.google.com/iam/docs/). + documentation](https://cloud.google.com/iam/docs/). """ # Create or coerce a protobuf request object. @@ -2325,19 +2324,19 @@ async def sample_get_iam_policy(): constraints based on attributes of the request, the resource, or both. To learn which resources support conditions in their IAM policies, see the [IAM - documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies). + documentation](https://cloud.google.com/iam/help/conditions/resource-policies). **JSON example:** - :literal:`\` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` + :literal:`` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` **YAML example:** - :literal:`\` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` + :literal:`` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` For a description of IAM and its features, see the [IAM - documentation](\ https://cloud.google.com/iam/docs/). + documentation](https://cloud.google.com/iam/docs/). """ # Create or coerce a protobuf request object. @@ -2651,26 +2650,26 @@ async def create_instance_partition( Immediately upon completion of this request: - - The instance partition is readable via the API, with all - requested attributes but no allocated resources. Its state is - ``CREATING``. + - The instance partition is readable via the API, with all + requested attributes but no allocated resources. Its state is + ``CREATING``. Until completion of the returned operation: - - Cancelling the operation renders the instance partition - immediately unreadable via the API. - - The instance partition can be deleted. - - All other attempts to modify the instance partition are - rejected. + - Cancelling the operation renders the instance partition + immediately unreadable via the API. + - The instance partition can be deleted. + - All other attempts to modify the instance partition are + rejected. Upon completion of the returned operation: - - Billing for all successfully-allocated resources begins (some - types may have lower than the requested levels). - - Databases can start using this instance partition. - - The instance partition's allocated resource levels are - readable via the API. - - The instance partition's state becomes ``READY``. + - Billing for all successfully-allocated resources begins (some + types may have lower than the requested levels). + - Databases can start using this instance partition. + - The instance partition's allocated resource levels are + readable via the API. + - The instance partition's state becomes ``READY``. The returned long-running operation will have a name of the format ``/operations/`` @@ -2958,31 +2957,31 @@ async def update_instance_partition( Immediately upon completion of this request: - - For resource types for which a decrease in the instance - partition's allocation has been requested, billing is based - on the newly-requested level. + - For resource types for which a decrease in the instance + partition's allocation has been requested, billing is based on + the newly-requested level. Until completion of the returned operation: - - Cancelling the operation sets its metadata's - [cancel_time][google.spanner.admin.instance.v1.UpdateInstancePartitionMetadata.cancel_time], - and begins restoring resources to their pre-request values. - The operation is guaranteed to succeed at undoing all - resource changes, after which point it terminates with a - ``CANCELLED`` status. - - All other attempts to modify the instance partition are - rejected. - - Reading the instance partition via the API continues to give - the pre-request resource levels. + - Cancelling the operation sets its metadata's + [cancel_time][google.spanner.admin.instance.v1.UpdateInstancePartitionMetadata.cancel_time], + and begins restoring resources to their pre-request values. + The operation is guaranteed to succeed at undoing all resource + changes, after which point it terminates with a ``CANCELLED`` + status. + - All other attempts to modify the instance partition are + rejected. + - Reading the instance partition via the API continues to give + the pre-request resource levels. Upon completion of the returned operation: - - Billing begins for all successfully-allocated resources (some - types may have lower than the requested levels). - - All newly-reserved resources are available for serving the - instance partition's tables. - - The instance partition's new resource levels are readable via - the API. + - Billing begins for all successfully-allocated resources (some + types may have lower than the requested levels). + - All newly-reserved resources are available for serving the + instance partition's tables. + - The instance partition's new resource levels are readable via + the API. The returned long-running operation will have a name of the format ``/operations/`` @@ -3302,33 +3301,33 @@ async def move_instance( ``MoveInstance`` returns ``FAILED_PRECONDITION`` if the instance meets any of the following criteria: - - Is undergoing a move to a different instance configuration - - Has backups - - Has an ongoing update - - Contains any CMEK-enabled databases - - Is a free trial instance + - Is undergoing a move to a different instance configuration + - Has backups + - Has an ongoing update + - Contains any CMEK-enabled databases + - Is a free trial instance While the operation is pending: - - All other attempts to modify the instance, including changes - to its compute capacity, are rejected. + - All other attempts to modify the instance, including changes + to its compute capacity, are rejected. - - The following database and backup admin operations are - rejected: + - The following database and backup admin operations are + rejected: - - ``DatabaseAdmin.CreateDatabase`` - - ``DatabaseAdmin.UpdateDatabaseDdl`` (disabled if - default_leader is specified in the request.) - - ``DatabaseAdmin.RestoreDatabase`` - - ``DatabaseAdmin.CreateBackup`` - - ``DatabaseAdmin.CopyBackup`` + - ``DatabaseAdmin.CreateDatabase`` + - ``DatabaseAdmin.UpdateDatabaseDdl`` (disabled if + default_leader is specified in the request.) + - ``DatabaseAdmin.RestoreDatabase`` + - ``DatabaseAdmin.CreateBackup`` + - ``DatabaseAdmin.CopyBackup`` - - Both the source and target instance configurations are - subject to hourly compute and storage charges. + - Both the source and target instance configurations are subject + to hourly compute and storage charges. - - The instance might experience higher read-write latencies and - a higher transaction abort rate. However, moving an instance - doesn't cause any downtime. + - The instance might experience higher read-write latencies and + a higher transaction abort rate. However, moving an instance + doesn't cause any downtime. The returned long-running operation has a name of the format ``/operations/`` and can be used to @@ -3347,10 +3346,10 @@ async def move_instance( If not cancelled, upon completion of the returned operation: - - The instance successfully moves to the target instance - configuration. - - You are billed for compute and storage in target instance - configuration. + - The instance successfully moves to the target instance + configuration. + - You are billed for compute and storage in target instance + configuration. Authorization requires the ``spanner.instances.update`` permission on the resource diff --git a/google/cloud/spanner_admin_instance_v1/services/instance_admin/client.py b/google/cloud/spanner_admin_instance_v1/services/instance_admin/client.py index ef34b5361b..c0fe398c3a 100644 --- a/google/cloud/spanner_admin_instance_v1/services/instance_admin/client.py +++ b/google/cloud/spanner_admin_instance_v1/services/instance_admin/client.py @@ -1041,24 +1041,24 @@ def create_instance_config( Immediately after the request returns: - - The instance configuration is readable via the API, with all - requested attributes. The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field is set to true. Its state is ``CREATING``. + - The instance configuration is readable via the API, with all + requested attributes. The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field is set to true. Its state is ``CREATING``. While the operation is pending: - - Cancelling the operation renders the instance configuration - immediately unreadable via the API. - - Except for deleting the creating resource, all other attempts - to modify the instance configuration are rejected. + - Cancelling the operation renders the instance configuration + immediately unreadable via the API. + - Except for deleting the creating resource, all other attempts + to modify the instance configuration are rejected. Upon completion of the returned operation: - - Instances can be created using the instance configuration. - - The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field becomes false. Its state becomes ``READY``. + - Instances can be created using the instance configuration. + - The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field becomes false. Its state becomes ``READY``. The returned long-running operation will have a name of the format ``/operations/`` and @@ -1234,31 +1234,30 @@ def update_instance_config( Immediately after the request returns: - - The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field is set to true. + - The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field is set to true. While the operation is pending: - - Cancelling the operation sets its metadata's - [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata.cancel_time]. - The operation is guaranteed to succeed at undoing all - changes, after which point it terminates with a ``CANCELLED`` - status. - - All other attempts to modify the instance configuration are - rejected. - - Reading the instance configuration via the API continues to - give the pre-request values. + - Cancelling the operation sets its metadata's + [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata.cancel_time]. + The operation is guaranteed to succeed at undoing all changes, + after which point it terminates with a ``CANCELLED`` status. + - All other attempts to modify the instance configuration are + rejected. + - Reading the instance configuration via the API continues to + give the pre-request values. Upon completion of the returned operation: - - Creating instances using the instance configuration uses the - new values. - - The new values of the instance configuration are readable via - the API. - - The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field becomes false. + - Creating instances using the instance configuration uses the + new values. + - The new values of the instance configuration are readable via + the API. + - The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field becomes false. The returned long-running operation will have a name of the format ``/operations/`` and @@ -2045,25 +2044,25 @@ def create_instance( Immediately upon completion of this request: - - The instance is readable via the API, with all requested - attributes but no allocated resources. Its state is - ``CREATING``. + - The instance is readable via the API, with all requested + attributes but no allocated resources. Its state is + ``CREATING``. Until completion of the returned operation: - - Cancelling the operation renders the instance immediately - unreadable via the API. - - The instance can be deleted. - - All other attempts to modify the instance are rejected. + - Cancelling the operation renders the instance immediately + unreadable via the API. + - The instance can be deleted. + - All other attempts to modify the instance are rejected. Upon completion of the returned operation: - - Billing for all successfully-allocated resources begins (some - types may have lower than the requested levels). - - Databases can be created in the instance. - - The instance's allocated resource levels are readable via the - API. - - The instance's state becomes ``READY``. + - Billing for all successfully-allocated resources begins (some + types may have lower than the requested levels). + - Databases can be created in the instance. + - The instance's allocated resource levels are readable via the + API. + - The instance's state becomes ``READY``. The returned long-running operation will have a name of the format ``/operations/`` and can be @@ -2233,29 +2232,29 @@ def update_instance( Immediately upon completion of this request: - - For resource types for which a decrease in the instance's - allocation has been requested, billing is based on the - newly-requested level. + - For resource types for which a decrease in the instance's + allocation has been requested, billing is based on the + newly-requested level. Until completion of the returned operation: - - Cancelling the operation sets its metadata's - [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], - and begins restoring resources to their pre-request values. - The operation is guaranteed to succeed at undoing all - resource changes, after which point it terminates with a - ``CANCELLED`` status. - - All other attempts to modify the instance are rejected. - - Reading the instance via the API continues to give the - pre-request resource levels. + - Cancelling the operation sets its metadata's + [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], + and begins restoring resources to their pre-request values. + The operation is guaranteed to succeed at undoing all resource + changes, after which point it terminates with a ``CANCELLED`` + status. + - All other attempts to modify the instance are rejected. + - Reading the instance via the API continues to give the + pre-request resource levels. Upon completion of the returned operation: - - Billing begins for all successfully-allocated resources (some - types may have lower than the requested levels). - - All newly-reserved resources are available for serving the - instance's tables. - - The instance's new resource levels are readable via the API. + - Billing begins for all successfully-allocated resources (some + types may have lower than the requested levels). + - All newly-reserved resources are available for serving the + instance's tables. + - The instance's new resource levels are readable via the API. The returned long-running operation will have a name of the format ``/operations/`` and can be @@ -2422,13 +2421,13 @@ def delete_instance( Immediately upon completion of the request: - - Billing ceases for all of the instance's reserved resources. + - Billing ceases for all of the instance's reserved resources. Soon afterward: - - The instance and *all of its databases* immediately and - irrevocably disappear from the API. All data in the databases - is permanently deleted. + - The instance and *all of its databases* immediately and + irrevocably disappear from the API. All data in the databases + is permanently deleted. .. code-block:: python @@ -2597,19 +2596,19 @@ def sample_set_iam_policy(): constraints based on attributes of the request, the resource, or both. To learn which resources support conditions in their IAM policies, see the [IAM - documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies). + documentation](https://cloud.google.com/iam/help/conditions/resource-policies). **JSON example:** - :literal:`\` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` + :literal:`` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` **YAML example:** - :literal:`\` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` + :literal:`` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` For a description of IAM and its features, see the [IAM - documentation](\ https://cloud.google.com/iam/docs/). + documentation](https://cloud.google.com/iam/docs/). """ # Create or coerce a protobuf request object. @@ -2741,19 +2740,19 @@ def sample_get_iam_policy(): constraints based on attributes of the request, the resource, or both. To learn which resources support conditions in their IAM policies, see the [IAM - documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies). + documentation](https://cloud.google.com/iam/help/conditions/resource-policies). **JSON example:** - :literal:`\` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` + :literal:`` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \` **YAML example:** - :literal:`\` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` + :literal:`` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \` For a description of IAM and its features, see the [IAM - documentation](\ https://cloud.google.com/iam/docs/). + documentation](https://cloud.google.com/iam/docs/). """ # Create or coerce a protobuf request object. @@ -3066,26 +3065,26 @@ def create_instance_partition( Immediately upon completion of this request: - - The instance partition is readable via the API, with all - requested attributes but no allocated resources. Its state is - ``CREATING``. + - The instance partition is readable via the API, with all + requested attributes but no allocated resources. Its state is + ``CREATING``. Until completion of the returned operation: - - Cancelling the operation renders the instance partition - immediately unreadable via the API. - - The instance partition can be deleted. - - All other attempts to modify the instance partition are - rejected. + - Cancelling the operation renders the instance partition + immediately unreadable via the API. + - The instance partition can be deleted. + - All other attempts to modify the instance partition are + rejected. Upon completion of the returned operation: - - Billing for all successfully-allocated resources begins (some - types may have lower than the requested levels). - - Databases can start using this instance partition. - - The instance partition's allocated resource levels are - readable via the API. - - The instance partition's state becomes ``READY``. + - Billing for all successfully-allocated resources begins (some + types may have lower than the requested levels). + - Databases can start using this instance partition. + - The instance partition's allocated resource levels are + readable via the API. + - The instance partition's state becomes ``READY``. The returned long-running operation will have a name of the format ``/operations/`` @@ -3371,31 +3370,31 @@ def update_instance_partition( Immediately upon completion of this request: - - For resource types for which a decrease in the instance - partition's allocation has been requested, billing is based - on the newly-requested level. + - For resource types for which a decrease in the instance + partition's allocation has been requested, billing is based on + the newly-requested level. Until completion of the returned operation: - - Cancelling the operation sets its metadata's - [cancel_time][google.spanner.admin.instance.v1.UpdateInstancePartitionMetadata.cancel_time], - and begins restoring resources to their pre-request values. - The operation is guaranteed to succeed at undoing all - resource changes, after which point it terminates with a - ``CANCELLED`` status. - - All other attempts to modify the instance partition are - rejected. - - Reading the instance partition via the API continues to give - the pre-request resource levels. + - Cancelling the operation sets its metadata's + [cancel_time][google.spanner.admin.instance.v1.UpdateInstancePartitionMetadata.cancel_time], + and begins restoring resources to their pre-request values. + The operation is guaranteed to succeed at undoing all resource + changes, after which point it terminates with a ``CANCELLED`` + status. + - All other attempts to modify the instance partition are + rejected. + - Reading the instance partition via the API continues to give + the pre-request resource levels. Upon completion of the returned operation: - - Billing begins for all successfully-allocated resources (some - types may have lower than the requested levels). - - All newly-reserved resources are available for serving the - instance partition's tables. - - The instance partition's new resource levels are readable via - the API. + - Billing begins for all successfully-allocated resources (some + types may have lower than the requested levels). + - All newly-reserved resources are available for serving the + instance partition's tables. + - The instance partition's new resource levels are readable via + the API. The returned long-running operation will have a name of the format ``/operations/`` @@ -3713,33 +3712,33 @@ def move_instance( ``MoveInstance`` returns ``FAILED_PRECONDITION`` if the instance meets any of the following criteria: - - Is undergoing a move to a different instance configuration - - Has backups - - Has an ongoing update - - Contains any CMEK-enabled databases - - Is a free trial instance + - Is undergoing a move to a different instance configuration + - Has backups + - Has an ongoing update + - Contains any CMEK-enabled databases + - Is a free trial instance While the operation is pending: - - All other attempts to modify the instance, including changes - to its compute capacity, are rejected. + - All other attempts to modify the instance, including changes + to its compute capacity, are rejected. - - The following database and backup admin operations are - rejected: + - The following database and backup admin operations are + rejected: - - ``DatabaseAdmin.CreateDatabase`` - - ``DatabaseAdmin.UpdateDatabaseDdl`` (disabled if - default_leader is specified in the request.) - - ``DatabaseAdmin.RestoreDatabase`` - - ``DatabaseAdmin.CreateBackup`` - - ``DatabaseAdmin.CopyBackup`` + - ``DatabaseAdmin.CreateDatabase`` + - ``DatabaseAdmin.UpdateDatabaseDdl`` (disabled if + default_leader is specified in the request.) + - ``DatabaseAdmin.RestoreDatabase`` + - ``DatabaseAdmin.CreateBackup`` + - ``DatabaseAdmin.CopyBackup`` - - Both the source and target instance configurations are - subject to hourly compute and storage charges. + - Both the source and target instance configurations are subject + to hourly compute and storage charges. - - The instance might experience higher read-write latencies and - a higher transaction abort rate. However, moving an instance - doesn't cause any downtime. + - The instance might experience higher read-write latencies and + a higher transaction abort rate. However, moving an instance + doesn't cause any downtime. The returned long-running operation has a name of the format ``/operations/`` and can be used to @@ -3758,10 +3757,10 @@ def move_instance( If not cancelled, upon completion of the returned operation: - - The instance successfully moves to the target instance - configuration. - - You are billed for compute and storage in target instance - configuration. + - The instance successfully moves to the target instance + configuration. + - You are billed for compute and storage in target instance + configuration. Authorization requires the ``spanner.instances.update`` permission on the resource diff --git a/google/cloud/spanner_admin_instance_v1/services/instance_admin/transports/grpc.py b/google/cloud/spanner_admin_instance_v1/services/instance_admin/transports/grpc.py index 9066da9b07..ee5b765210 100644 --- a/google/cloud/spanner_admin_instance_v1/services/instance_admin/transports/grpc.py +++ b/google/cloud/spanner_admin_instance_v1/services/instance_admin/transports/grpc.py @@ -443,24 +443,24 @@ def create_instance_config( Immediately after the request returns: - - The instance configuration is readable via the API, with all - requested attributes. The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field is set to true. Its state is ``CREATING``. + - The instance configuration is readable via the API, with all + requested attributes. The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field is set to true. Its state is ``CREATING``. While the operation is pending: - - Cancelling the operation renders the instance configuration - immediately unreadable via the API. - - Except for deleting the creating resource, all other attempts - to modify the instance configuration are rejected. + - Cancelling the operation renders the instance configuration + immediately unreadable via the API. + - Except for deleting the creating resource, all other attempts + to modify the instance configuration are rejected. Upon completion of the returned operation: - - Instances can be created using the instance configuration. - - The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field becomes false. Its state becomes ``READY``. + - Instances can be created using the instance configuration. + - The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field becomes false. Its state becomes ``READY``. The returned long-running operation will have a name of the format ``/operations/`` and @@ -510,31 +510,30 @@ def update_instance_config( Immediately after the request returns: - - The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field is set to true. + - The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field is set to true. While the operation is pending: - - Cancelling the operation sets its metadata's - [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata.cancel_time]. - The operation is guaranteed to succeed at undoing all - changes, after which point it terminates with a ``CANCELLED`` - status. - - All other attempts to modify the instance configuration are - rejected. - - Reading the instance configuration via the API continues to - give the pre-request values. + - Cancelling the operation sets its metadata's + [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata.cancel_time]. + The operation is guaranteed to succeed at undoing all changes, + after which point it terminates with a ``CANCELLED`` status. + - All other attempts to modify the instance configuration are + rejected. + - Reading the instance configuration via the API continues to + give the pre-request values. Upon completion of the returned operation: - - Creating instances using the instance configuration uses the - new values. - - The new values of the instance configuration are readable via - the API. - - The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field becomes false. + - Creating instances using the instance configuration uses the + new values. + - The new values of the instance configuration are readable via + the API. + - The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field becomes false. The returned long-running operation will have a name of the format ``/operations/`` and @@ -747,25 +746,25 @@ def create_instance( Immediately upon completion of this request: - - The instance is readable via the API, with all requested - attributes but no allocated resources. Its state is - ``CREATING``. + - The instance is readable via the API, with all requested + attributes but no allocated resources. Its state is + ``CREATING``. Until completion of the returned operation: - - Cancelling the operation renders the instance immediately - unreadable via the API. - - The instance can be deleted. - - All other attempts to modify the instance are rejected. + - Cancelling the operation renders the instance immediately + unreadable via the API. + - The instance can be deleted. + - All other attempts to modify the instance are rejected. Upon completion of the returned operation: - - Billing for all successfully-allocated resources begins (some - types may have lower than the requested levels). - - Databases can be created in the instance. - - The instance's allocated resource levels are readable via the - API. - - The instance's state becomes ``READY``. + - Billing for all successfully-allocated resources begins (some + types may have lower than the requested levels). + - Databases can be created in the instance. + - The instance's allocated resource levels are readable via the + API. + - The instance's state becomes ``READY``. The returned long-running operation will have a name of the format ``/operations/`` and can be @@ -809,29 +808,29 @@ def update_instance( Immediately upon completion of this request: - - For resource types for which a decrease in the instance's - allocation has been requested, billing is based on the - newly-requested level. + - For resource types for which a decrease in the instance's + allocation has been requested, billing is based on the + newly-requested level. Until completion of the returned operation: - - Cancelling the operation sets its metadata's - [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], - and begins restoring resources to their pre-request values. - The operation is guaranteed to succeed at undoing all - resource changes, after which point it terminates with a - ``CANCELLED`` status. - - All other attempts to modify the instance are rejected. - - Reading the instance via the API continues to give the - pre-request resource levels. + - Cancelling the operation sets its metadata's + [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], + and begins restoring resources to their pre-request values. + The operation is guaranteed to succeed at undoing all resource + changes, after which point it terminates with a ``CANCELLED`` + status. + - All other attempts to modify the instance are rejected. + - Reading the instance via the API continues to give the + pre-request resource levels. Upon completion of the returned operation: - - Billing begins for all successfully-allocated resources (some - types may have lower than the requested levels). - - All newly-reserved resources are available for serving the - instance's tables. - - The instance's new resource levels are readable via the API. + - Billing begins for all successfully-allocated resources (some + types may have lower than the requested levels). + - All newly-reserved resources are available for serving the + instance's tables. + - The instance's new resource levels are readable via the API. The returned long-running operation will have a name of the format ``/operations/`` and can be @@ -874,13 +873,13 @@ def delete_instance( Immediately upon completion of the request: - - Billing ceases for all of the instance's reserved resources. + - Billing ceases for all of the instance's reserved resources. Soon afterward: - - The instance and *all of its databases* immediately and - irrevocably disappear from the API. All data in the databases - is permanently deleted. + - The instance and *all of its databases* immediately and + irrevocably disappear from the API. All data in the databases + is permanently deleted. Returns: Callable[[~.DeleteInstanceRequest], @@ -1044,26 +1043,26 @@ def create_instance_partition( Immediately upon completion of this request: - - The instance partition is readable via the API, with all - requested attributes but no allocated resources. Its state is - ``CREATING``. + - The instance partition is readable via the API, with all + requested attributes but no allocated resources. Its state is + ``CREATING``. Until completion of the returned operation: - - Cancelling the operation renders the instance partition - immediately unreadable via the API. - - The instance partition can be deleted. - - All other attempts to modify the instance partition are - rejected. + - Cancelling the operation renders the instance partition + immediately unreadable via the API. + - The instance partition can be deleted. + - All other attempts to modify the instance partition are + rejected. Upon completion of the returned operation: - - Billing for all successfully-allocated resources begins (some - types may have lower than the requested levels). - - Databases can start using this instance partition. - - The instance partition's allocated resource levels are - readable via the API. - - The instance partition's state becomes ``READY``. + - Billing for all successfully-allocated resources begins (some + types may have lower than the requested levels). + - Databases can start using this instance partition. + - The instance partition's allocated resource levels are + readable via the API. + - The instance partition's state becomes ``READY``. The returned long-running operation will have a name of the format ``/operations/`` @@ -1143,31 +1142,31 @@ def update_instance_partition( Immediately upon completion of this request: - - For resource types for which a decrease in the instance - partition's allocation has been requested, billing is based - on the newly-requested level. + - For resource types for which a decrease in the instance + partition's allocation has been requested, billing is based on + the newly-requested level. Until completion of the returned operation: - - Cancelling the operation sets its metadata's - [cancel_time][google.spanner.admin.instance.v1.UpdateInstancePartitionMetadata.cancel_time], - and begins restoring resources to their pre-request values. - The operation is guaranteed to succeed at undoing all - resource changes, after which point it terminates with a - ``CANCELLED`` status. - - All other attempts to modify the instance partition are - rejected. - - Reading the instance partition via the API continues to give - the pre-request resource levels. + - Cancelling the operation sets its metadata's + [cancel_time][google.spanner.admin.instance.v1.UpdateInstancePartitionMetadata.cancel_time], + and begins restoring resources to their pre-request values. + The operation is guaranteed to succeed at undoing all resource + changes, after which point it terminates with a ``CANCELLED`` + status. + - All other attempts to modify the instance partition are + rejected. + - Reading the instance partition via the API continues to give + the pre-request resource levels. Upon completion of the returned operation: - - Billing begins for all successfully-allocated resources (some - types may have lower than the requested levels). - - All newly-reserved resources are available for serving the - instance partition's tables. - - The instance partition's new resource levels are readable via - the API. + - Billing begins for all successfully-allocated resources (some + types may have lower than the requested levels). + - All newly-reserved resources are available for serving the + instance partition's tables. + - The instance partition's new resource levels are readable via + the API. The returned long-running operation will have a name of the format ``/operations/`` @@ -1261,33 +1260,33 @@ def move_instance( ``MoveInstance`` returns ``FAILED_PRECONDITION`` if the instance meets any of the following criteria: - - Is undergoing a move to a different instance configuration - - Has backups - - Has an ongoing update - - Contains any CMEK-enabled databases - - Is a free trial instance + - Is undergoing a move to a different instance configuration + - Has backups + - Has an ongoing update + - Contains any CMEK-enabled databases + - Is a free trial instance While the operation is pending: - - All other attempts to modify the instance, including changes - to its compute capacity, are rejected. + - All other attempts to modify the instance, including changes + to its compute capacity, are rejected. - - The following database and backup admin operations are - rejected: + - The following database and backup admin operations are + rejected: - - ``DatabaseAdmin.CreateDatabase`` - - ``DatabaseAdmin.UpdateDatabaseDdl`` (disabled if - default_leader is specified in the request.) - - ``DatabaseAdmin.RestoreDatabase`` - - ``DatabaseAdmin.CreateBackup`` - - ``DatabaseAdmin.CopyBackup`` + - ``DatabaseAdmin.CreateDatabase`` + - ``DatabaseAdmin.UpdateDatabaseDdl`` (disabled if + default_leader is specified in the request.) + - ``DatabaseAdmin.RestoreDatabase`` + - ``DatabaseAdmin.CreateBackup`` + - ``DatabaseAdmin.CopyBackup`` - - Both the source and target instance configurations are - subject to hourly compute and storage charges. + - Both the source and target instance configurations are subject + to hourly compute and storage charges. - - The instance might experience higher read-write latencies and - a higher transaction abort rate. However, moving an instance - doesn't cause any downtime. + - The instance might experience higher read-write latencies and + a higher transaction abort rate. However, moving an instance + doesn't cause any downtime. The returned long-running operation has a name of the format ``/operations/`` and can be used to @@ -1306,10 +1305,10 @@ def move_instance( If not cancelled, upon completion of the returned operation: - - The instance successfully moves to the target instance - configuration. - - You are billed for compute and storage in target instance - configuration. + - The instance successfully moves to the target instance + configuration. + - You are billed for compute and storage in target instance + configuration. Authorization requires the ``spanner.instances.update`` permission on the resource diff --git a/google/cloud/spanner_admin_instance_v1/services/instance_admin/transports/grpc_asyncio.py b/google/cloud/spanner_admin_instance_v1/services/instance_admin/transports/grpc_asyncio.py index 04793a6bc3..f2df40d1f2 100644 --- a/google/cloud/spanner_admin_instance_v1/services/instance_admin/transports/grpc_asyncio.py +++ b/google/cloud/spanner_admin_instance_v1/services/instance_admin/transports/grpc_asyncio.py @@ -452,24 +452,24 @@ def create_instance_config( Immediately after the request returns: - - The instance configuration is readable via the API, with all - requested attributes. The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field is set to true. Its state is ``CREATING``. + - The instance configuration is readable via the API, with all + requested attributes. The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field is set to true. Its state is ``CREATING``. While the operation is pending: - - Cancelling the operation renders the instance configuration - immediately unreadable via the API. - - Except for deleting the creating resource, all other attempts - to modify the instance configuration are rejected. + - Cancelling the operation renders the instance configuration + immediately unreadable via the API. + - Except for deleting the creating resource, all other attempts + to modify the instance configuration are rejected. Upon completion of the returned operation: - - Instances can be created using the instance configuration. - - The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field becomes false. Its state becomes ``READY``. + - Instances can be created using the instance configuration. + - The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field becomes false. Its state becomes ``READY``. The returned long-running operation will have a name of the format ``/operations/`` and @@ -520,31 +520,30 @@ def update_instance_config( Immediately after the request returns: - - The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field is set to true. + - The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field is set to true. While the operation is pending: - - Cancelling the operation sets its metadata's - [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata.cancel_time]. - The operation is guaranteed to succeed at undoing all - changes, after which point it terminates with a ``CANCELLED`` - status. - - All other attempts to modify the instance configuration are - rejected. - - Reading the instance configuration via the API continues to - give the pre-request values. + - Cancelling the operation sets its metadata's + [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata.cancel_time]. + The operation is guaranteed to succeed at undoing all changes, + after which point it terminates with a ``CANCELLED`` status. + - All other attempts to modify the instance configuration are + rejected. + - Reading the instance configuration via the API continues to + give the pre-request values. Upon completion of the returned operation: - - Creating instances using the instance configuration uses the - new values. - - The new values of the instance configuration are readable via - the API. - - The instance configuration's - [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] - field becomes false. + - Creating instances using the instance configuration uses the + new values. + - The new values of the instance configuration are readable via + the API. + - The instance configuration's + [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling] + field becomes false. The returned long-running operation will have a name of the format ``/operations/`` and @@ -759,25 +758,25 @@ def create_instance( Immediately upon completion of this request: - - The instance is readable via the API, with all requested - attributes but no allocated resources. Its state is - ``CREATING``. + - The instance is readable via the API, with all requested + attributes but no allocated resources. Its state is + ``CREATING``. Until completion of the returned operation: - - Cancelling the operation renders the instance immediately - unreadable via the API. - - The instance can be deleted. - - All other attempts to modify the instance are rejected. + - Cancelling the operation renders the instance immediately + unreadable via the API. + - The instance can be deleted. + - All other attempts to modify the instance are rejected. Upon completion of the returned operation: - - Billing for all successfully-allocated resources begins (some - types may have lower than the requested levels). - - Databases can be created in the instance. - - The instance's allocated resource levels are readable via the - API. - - The instance's state becomes ``READY``. + - Billing for all successfully-allocated resources begins (some + types may have lower than the requested levels). + - Databases can be created in the instance. + - The instance's allocated resource levels are readable via the + API. + - The instance's state becomes ``READY``. The returned long-running operation will have a name of the format ``/operations/`` and can be @@ -822,29 +821,29 @@ def update_instance( Immediately upon completion of this request: - - For resource types for which a decrease in the instance's - allocation has been requested, billing is based on the - newly-requested level. + - For resource types for which a decrease in the instance's + allocation has been requested, billing is based on the + newly-requested level. Until completion of the returned operation: - - Cancelling the operation sets its metadata's - [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], - and begins restoring resources to their pre-request values. - The operation is guaranteed to succeed at undoing all - resource changes, after which point it terminates with a - ``CANCELLED`` status. - - All other attempts to modify the instance are rejected. - - Reading the instance via the API continues to give the - pre-request resource levels. + - Cancelling the operation sets its metadata's + [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], + and begins restoring resources to their pre-request values. + The operation is guaranteed to succeed at undoing all resource + changes, after which point it terminates with a ``CANCELLED`` + status. + - All other attempts to modify the instance are rejected. + - Reading the instance via the API continues to give the + pre-request resource levels. Upon completion of the returned operation: - - Billing begins for all successfully-allocated resources (some - types may have lower than the requested levels). - - All newly-reserved resources are available for serving the - instance's tables. - - The instance's new resource levels are readable via the API. + - Billing begins for all successfully-allocated resources (some + types may have lower than the requested levels). + - All newly-reserved resources are available for serving the + instance's tables. + - The instance's new resource levels are readable via the API. The returned long-running operation will have a name of the format ``/operations/`` and can be @@ -889,13 +888,13 @@ def delete_instance( Immediately upon completion of the request: - - Billing ceases for all of the instance's reserved resources. + - Billing ceases for all of the instance's reserved resources. Soon afterward: - - The instance and *all of its databases* immediately and - irrevocably disappear from the API. All data in the databases - is permanently deleted. + - The instance and *all of its databases* immediately and + irrevocably disappear from the API. All data in the databases + is permanently deleted. Returns: Callable[[~.DeleteInstanceRequest], @@ -1059,26 +1058,26 @@ def create_instance_partition( Immediately upon completion of this request: - - The instance partition is readable via the API, with all - requested attributes but no allocated resources. Its state is - ``CREATING``. + - The instance partition is readable via the API, with all + requested attributes but no allocated resources. Its state is + ``CREATING``. Until completion of the returned operation: - - Cancelling the operation renders the instance partition - immediately unreadable via the API. - - The instance partition can be deleted. - - All other attempts to modify the instance partition are - rejected. + - Cancelling the operation renders the instance partition + immediately unreadable via the API. + - The instance partition can be deleted. + - All other attempts to modify the instance partition are + rejected. Upon completion of the returned operation: - - Billing for all successfully-allocated resources begins (some - types may have lower than the requested levels). - - Databases can start using this instance partition. - - The instance partition's allocated resource levels are - readable via the API. - - The instance partition's state becomes ``READY``. + - Billing for all successfully-allocated resources begins (some + types may have lower than the requested levels). + - Databases can start using this instance partition. + - The instance partition's allocated resource levels are + readable via the API. + - The instance partition's state becomes ``READY``. The returned long-running operation will have a name of the format ``/operations/`` @@ -1159,31 +1158,31 @@ def update_instance_partition( Immediately upon completion of this request: - - For resource types for which a decrease in the instance - partition's allocation has been requested, billing is based - on the newly-requested level. + - For resource types for which a decrease in the instance + partition's allocation has been requested, billing is based on + the newly-requested level. Until completion of the returned operation: - - Cancelling the operation sets its metadata's - [cancel_time][google.spanner.admin.instance.v1.UpdateInstancePartitionMetadata.cancel_time], - and begins restoring resources to their pre-request values. - The operation is guaranteed to succeed at undoing all - resource changes, after which point it terminates with a - ``CANCELLED`` status. - - All other attempts to modify the instance partition are - rejected. - - Reading the instance partition via the API continues to give - the pre-request resource levels. + - Cancelling the operation sets its metadata's + [cancel_time][google.spanner.admin.instance.v1.UpdateInstancePartitionMetadata.cancel_time], + and begins restoring resources to their pre-request values. + The operation is guaranteed to succeed at undoing all resource + changes, after which point it terminates with a ``CANCELLED`` + status. + - All other attempts to modify the instance partition are + rejected. + - Reading the instance partition via the API continues to give + the pre-request resource levels. Upon completion of the returned operation: - - Billing begins for all successfully-allocated resources (some - types may have lower than the requested levels). - - All newly-reserved resources are available for serving the - instance partition's tables. - - The instance partition's new resource levels are readable via - the API. + - Billing begins for all successfully-allocated resources (some + types may have lower than the requested levels). + - All newly-reserved resources are available for serving the + instance partition's tables. + - The instance partition's new resource levels are readable via + the API. The returned long-running operation will have a name of the format ``/operations/`` @@ -1278,33 +1277,33 @@ def move_instance( ``MoveInstance`` returns ``FAILED_PRECONDITION`` if the instance meets any of the following criteria: - - Is undergoing a move to a different instance configuration - - Has backups - - Has an ongoing update - - Contains any CMEK-enabled databases - - Is a free trial instance + - Is undergoing a move to a different instance configuration + - Has backups + - Has an ongoing update + - Contains any CMEK-enabled databases + - Is a free trial instance While the operation is pending: - - All other attempts to modify the instance, including changes - to its compute capacity, are rejected. + - All other attempts to modify the instance, including changes + to its compute capacity, are rejected. - - The following database and backup admin operations are - rejected: + - The following database and backup admin operations are + rejected: - - ``DatabaseAdmin.CreateDatabase`` - - ``DatabaseAdmin.UpdateDatabaseDdl`` (disabled if - default_leader is specified in the request.) - - ``DatabaseAdmin.RestoreDatabase`` - - ``DatabaseAdmin.CreateBackup`` - - ``DatabaseAdmin.CopyBackup`` + - ``DatabaseAdmin.CreateDatabase`` + - ``DatabaseAdmin.UpdateDatabaseDdl`` (disabled if + default_leader is specified in the request.) + - ``DatabaseAdmin.RestoreDatabase`` + - ``DatabaseAdmin.CreateBackup`` + - ``DatabaseAdmin.CopyBackup`` - - Both the source and target instance configurations are - subject to hourly compute and storage charges. + - Both the source and target instance configurations are subject + to hourly compute and storage charges. - - The instance might experience higher read-write latencies and - a higher transaction abort rate. However, moving an instance - doesn't cause any downtime. + - The instance might experience higher read-write latencies and + a higher transaction abort rate. However, moving an instance + doesn't cause any downtime. The returned long-running operation has a name of the format ``/operations/`` and can be used to @@ -1323,10 +1322,10 @@ def move_instance( If not cancelled, upon completion of the returned operation: - - The instance successfully moves to the target instance - configuration. - - You are billed for compute and storage in target instance - configuration. + - The instance successfully moves to the target instance + configuration. + - You are billed for compute and storage in target instance + configuration. Authorization requires the ``spanner.instances.update`` permission on the resource diff --git a/google/cloud/spanner_admin_instance_v1/types/spanner_instance_admin.py b/google/cloud/spanner_admin_instance_v1/types/spanner_instance_admin.py index 44dc52ddc4..1e1509d1c4 100644 --- a/google/cloud/spanner_admin_instance_v1/types/spanner_instance_admin.py +++ b/google/cloud/spanner_admin_instance_v1/types/spanner_instance_admin.py @@ -99,28 +99,28 @@ class ReplicaType(proto.Enum): Read-write replicas support both reads and writes. These replicas: - - Maintain a full copy of your data. - - Serve reads. - - Can vote whether to commit a write. - - Participate in leadership election. - - Are eligible to become a leader. + - Maintain a full copy of your data. + - Serve reads. + - Can vote whether to commit a write. + - Participate in leadership election. + - Are eligible to become a leader. READ_ONLY (2): Read-only replicas only support reads (not writes). Read-only replicas: - - Maintain a full copy of your data. - - Serve reads. - - Do not participate in voting to commit writes. - - Are not eligible to become a leader. + - Maintain a full copy of your data. + - Serve reads. + - Do not participate in voting to commit writes. + - Are not eligible to become a leader. WITNESS (3): Witness replicas don't support reads but do participate in voting to commit writes. Witness replicas: - - Do not maintain a full copy of data. - - Do not serve reads. - - Vote whether to commit writes. - - Participate in leader election but are not eligible to - become leader. + - Do not maintain a full copy of data. + - Do not serve reads. + - Vote whether to commit writes. + - Participate in leader election but are not eligible to + become leader. """ TYPE_UNSPECIFIED = 0 READ_WRITE = 1 @@ -190,14 +190,14 @@ class InstanceConfig(proto.Message): management rules (e.g. route, firewall, load balancing, etc.). - - Label keys must be between 1 and 63 characters long and - must conform to the following regular expression: - ``[a-z][a-z0-9_-]{0,62}``. - - Label values must be between 0 and 63 characters long and - must conform to the regular expression - ``[a-z0-9_-]{0,63}``. - - No more than 64 labels can be associated with a given - resource. + - Label keys must be between 1 and 63 characters long and + must conform to the following regular expression: + ``[a-z][a-z0-9_-]{0,62}``. + - Label values must be between 0 and 63 characters long and + must conform to the regular expression + ``[a-z0-9_-]{0,63}``. + - No more than 64 labels can be associated with a given + resource. See https://goo.gl/xmQnxf for more information on and examples of labels. @@ -725,14 +725,14 @@ class Instance(proto.Message): management rules (e.g. route, firewall, load balancing, etc.). - - Label keys must be between 1 and 63 characters long and - must conform to the following regular expression: - ``[a-z][a-z0-9_-]{0,62}``. - - Label values must be between 0 and 63 characters long and - must conform to the regular expression - ``[a-z0-9_-]{0,63}``. - - No more than 64 labels can be associated with a given - resource. + - Label keys must be between 1 and 63 characters long and + must conform to the following regular expression: + ``[a-z][a-z0-9_-]{0,62}``. + - Label values must be between 0 and 63 characters long and + must conform to the regular expression + ``[a-z0-9_-]{0,63}``. + - No more than 64 labels can be associated with a given + resource. See https://goo.gl/xmQnxf for more information on and examples of labels. @@ -1169,21 +1169,21 @@ class ListInstanceConfigOperationsRequest(proto.Message): The following fields in the Operation are eligible for filtering: - - ``name`` - The name of the long-running operation - - ``done`` - False if the operation is in progress, else - true. - - ``metadata.@type`` - the type of metadata. For example, - the type string for - [CreateInstanceConfigMetadata][google.spanner.admin.instance.v1.CreateInstanceConfigMetadata] - is - ``type.googleapis.com/google.spanner.admin.instance.v1.CreateInstanceConfigMetadata``. - - ``metadata.`` - any field in metadata.value. - ``metadata.@type`` must be specified first, if filtering - on metadata fields. - - ``error`` - Error associated with the long-running - operation. - - ``response.@type`` - the type of response. - - ``response.`` - any field in response.value. + - ``name`` - The name of the long-running operation + - ``done`` - False if the operation is in progress, else + true. + - ``metadata.@type`` - the type of metadata. For example, + the type string for + [CreateInstanceConfigMetadata][google.spanner.admin.instance.v1.CreateInstanceConfigMetadata] + is + ``type.googleapis.com/google.spanner.admin.instance.v1.CreateInstanceConfigMetadata``. + - ``metadata.`` - any field in metadata.value. + ``metadata.@type`` must be specified first, if filtering + on metadata fields. + - ``error`` - Error associated with the long-running + operation. + - ``response.@type`` - the type of response. + - ``response.`` - any field in response.value. You can combine multiple expressions by enclosing each expression in parentheses. By default, expressions are @@ -1192,19 +1192,19 @@ class ListInstanceConfigOperationsRequest(proto.Message): Here are a few examples: - - ``done:true`` - The operation is complete. - - ``(metadata.@type=`` - ``type.googleapis.com/google.spanner.admin.instance.v1.CreateInstanceConfigMetadata) AND`` - ``(metadata.instance_config.name:custom-config) AND`` - ``(metadata.progress.start_time < \"2021-03-28T14:50:00Z\") AND`` - ``(error:*)`` - Return operations where: - - - The operation's metadata type is - [CreateInstanceConfigMetadata][google.spanner.admin.instance.v1.CreateInstanceConfigMetadata]. - - The instance configuration name contains - "custom-config". - - The operation started before 2021-03-28T14:50:00Z. - - The operation resulted in an error. + - ``done:true`` - The operation is complete. + - ``(metadata.@type=`` + ``type.googleapis.com/google.spanner.admin.instance.v1.CreateInstanceConfigMetadata) AND`` + ``(metadata.instance_config.name:custom-config) AND`` + ``(metadata.progress.start_time < \"2021-03-28T14:50:00Z\") AND`` + ``(error:*)`` - Return operations where: + + - The operation's metadata type is + [CreateInstanceConfigMetadata][google.spanner.admin.instance.v1.CreateInstanceConfigMetadata]. + - The instance configuration name contains + "custom-config". + - The operation started before 2021-03-28T14:50:00Z. + - The operation resulted in an error. page_size (int): Number of operations to be returned in the response. If 0 or less, defaults to the server's @@ -1350,23 +1350,23 @@ class ListInstancesRequest(proto.Message): Filter rules are case insensitive. The fields eligible for filtering are: - - ``name`` - - ``display_name`` - - ``labels.key`` where key is the name of a label + - ``name`` + - ``display_name`` + - ``labels.key`` where key is the name of a label Some examples of using filters are: - - ``name:*`` --> The instance has a name. - - ``name:Howl`` --> The instance's name contains the string - "howl". - - ``name:HOWL`` --> Equivalent to above. - - ``NAME:howl`` --> Equivalent to above. - - ``labels.env:*`` --> The instance has the label "env". - - ``labels.env:dev`` --> The instance has the label "env" - and the value of the label contains the string "dev". - - ``name:howl labels.env:dev`` --> The instance's name - contains "howl" and it has the label "env" with its value - containing "dev". + - ``name:*`` --> The instance has a name. + - ``name:Howl`` --> The instance's name contains the string + "howl". + - ``name:HOWL`` --> Equivalent to above. + - ``NAME:howl`` --> Equivalent to above. + - ``labels.env:*`` --> The instance has the label "env". + - ``labels.env:dev`` --> The instance has the label "env" + and the value of the label contains the string "dev". + - ``name:howl labels.env:dev`` --> The instance's name + contains "howl" and it has the label "env" with its value + containing "dev". instance_deadline (google.protobuf.timestamp_pb2.Timestamp): Deadline used while retrieving metadata for instances. Instances whose metadata cannot be retrieved within this @@ -2185,21 +2185,21 @@ class ListInstancePartitionOperationsRequest(proto.Message): The following fields in the Operation are eligible for filtering: - - ``name`` - The name of the long-running operation - - ``done`` - False if the operation is in progress, else - true. - - ``metadata.@type`` - the type of metadata. For example, - the type string for - [CreateInstancePartitionMetadata][google.spanner.admin.instance.v1.CreateInstancePartitionMetadata] - is - ``type.googleapis.com/google.spanner.admin.instance.v1.CreateInstancePartitionMetadata``. - - ``metadata.`` - any field in metadata.value. - ``metadata.@type`` must be specified first, if filtering - on metadata fields. - - ``error`` - Error associated with the long-running - operation. - - ``response.@type`` - the type of response. - - ``response.`` - any field in response.value. + - ``name`` - The name of the long-running operation + - ``done`` - False if the operation is in progress, else + true. + - ``metadata.@type`` - the type of metadata. For example, + the type string for + [CreateInstancePartitionMetadata][google.spanner.admin.instance.v1.CreateInstancePartitionMetadata] + is + ``type.googleapis.com/google.spanner.admin.instance.v1.CreateInstancePartitionMetadata``. + - ``metadata.`` - any field in metadata.value. + ``metadata.@type`` must be specified first, if filtering + on metadata fields. + - ``error`` - Error associated with the long-running + operation. + - ``response.@type`` - the type of response. + - ``response.`` - any field in response.value. You can combine multiple expressions by enclosing each expression in parentheses. By default, expressions are @@ -2208,19 +2208,19 @@ class ListInstancePartitionOperationsRequest(proto.Message): Here are a few examples: - - ``done:true`` - The operation is complete. - - ``(metadata.@type=`` - ``type.googleapis.com/google.spanner.admin.instance.v1.CreateInstancePartitionMetadata) AND`` - ``(metadata.instance_partition.name:custom-instance-partition) AND`` - ``(metadata.start_time < \"2021-03-28T14:50:00Z\") AND`` - ``(error:*)`` - Return operations where: - - - The operation's metadata type is - [CreateInstancePartitionMetadata][google.spanner.admin.instance.v1.CreateInstancePartitionMetadata]. - - The instance partition name contains - "custom-instance-partition". - - The operation started before 2021-03-28T14:50:00Z. - - The operation resulted in an error. + - ``done:true`` - The operation is complete. + - ``(metadata.@type=`` + ``type.googleapis.com/google.spanner.admin.instance.v1.CreateInstancePartitionMetadata) AND`` + ``(metadata.instance_partition.name:custom-instance-partition) AND`` + ``(metadata.start_time < \"2021-03-28T14:50:00Z\") AND`` + ``(error:*)`` - Return operations where: + + - The operation's metadata type is + [CreateInstancePartitionMetadata][google.spanner.admin.instance.v1.CreateInstancePartitionMetadata]. + - The instance partition name contains + "custom-instance-partition". + - The operation started before 2021-03-28T14:50:00Z. + - The operation resulted in an error. page_size (int): Optional. Number of operations to be returned in the response. If 0 or less, defaults to the diff --git a/google/cloud/spanner_v1/services/spanner/async_client.py b/google/cloud/spanner_v1/services/spanner/async_client.py index fbacbddcce..c48b62d532 100644 --- a/google/cloud/spanner_v1/services/spanner/async_client.py +++ b/google/cloud/spanner_v1/services/spanner/async_client.py @@ -314,14 +314,14 @@ async def create_session( transaction internally, and count toward the one transaction limit. - Active sessions use additional server resources, so it is a good + Active sessions use additional server resources, so it's a good idea to delete idle and unneeded sessions. Aside from explicit - deletes, Cloud Spanner may delete sessions for which no - operations are sent for more than an hour. If a session is - deleted, requests to it return ``NOT_FOUND``. + deletes, Cloud Spanner can delete sessions when no operations + are sent for more than an hour. If a session is deleted, + requests to it return ``NOT_FOUND``. Idle sessions can be kept alive by sending a trivial SQL query - periodically, e.g., ``"SELECT 1"``. + periodically, for example, ``"SELECT 1"``. .. code-block:: python @@ -477,10 +477,10 @@ async def sample_batch_create_sessions(): should not be set. session_count (:class:`int`): Required. The number of sessions to be created in this - batch call. The API may return fewer than the requested + batch call. The API can return fewer than the requested number of sessions. If a specific number of sessions are desired, the client can make additional calls to - BatchCreateSessions (adjusting + ``BatchCreateSessions`` (adjusting [session_count][google.spanner.v1.BatchCreateSessionsRequest.session_count] as necessary). @@ -561,7 +561,7 @@ async def get_session( timeout: Union[float, object] = gapic_v1.method.DEFAULT, metadata: Sequence[Tuple[str, Union[str, bytes]]] = (), ) -> spanner.Session: - r"""Gets a session. Returns ``NOT_FOUND`` if the session does not + r"""Gets a session. Returns ``NOT_FOUND`` if the session doesn't exist. This is mainly useful for determining whether a session is still alive. @@ -799,7 +799,7 @@ async def delete_session( metadata: Sequence[Tuple[str, Union[str, bytes]]] = (), ) -> None: r"""Ends a session, releasing server resources associated - with it. This will asynchronously trigger cancellation + with it. This asynchronously triggers the cancellation of any operations that are running with this session. .. code-block:: python @@ -899,7 +899,7 @@ async def execute_sql( metadata: Sequence[Tuple[str, Union[str, bytes]]] = (), ) -> result_set.ResultSet: r"""Executes an SQL statement, returning all results in a single - reply. This method cannot be used to return a result set larger + reply. This method can't be used to return a result set larger than 10 MiB; if the query yields more data than that, the query fails with a ``FAILED_PRECONDITION`` error. @@ -913,6 +913,9 @@ async def execute_sql( [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] instead. + The query string can be SQL or `Graph Query Language + (GQL) `__. + .. code-block:: python # This snippet has been automatically generated and should be regarded as a @@ -1006,6 +1009,9 @@ def execute_streaming_sql( individual row in the result set can exceed 100 MiB, and no column value can exceed 10 MiB. + The query string can be SQL or `Graph Query Language + (GQL) `__. + .. code-block:: python # This snippet has been automatically generated and should be regarded as a @@ -1179,8 +1185,8 @@ async def sample_execute_batch_dml(): Example 1: - - Request: 5 DML statements, all executed - successfully. + - Request: 5 DML statements, all executed + successfully. \* Response: 5 [ResultSet][google.spanner.v1.ResultSet] messages, @@ -1188,8 +1194,8 @@ async def sample_execute_batch_dml(): Example 2: - - Request: 5 DML statements. The third statement has - a syntax error. + - Request: 5 DML statements. The third statement has + a syntax error. \* Response: 2 [ResultSet][google.spanner.v1.ResultSet] messages, @@ -1243,7 +1249,7 @@ async def read( r"""Reads rows from the database using key lookups and scans, as a simple key/value style alternative to [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. This method - cannot be used to return a result set larger than 10 MiB; if the + can't be used to return a result set larger than 10 MiB; if the read matches more data than that, the read fails with a ``FAILED_PRECONDITION`` error. @@ -1573,7 +1579,7 @@ async def commit( any time; commonly, the cause is conflicts with concurrent transactions. However, it can also happen for a variety of other reasons. If ``Commit`` returns ``ABORTED``, the caller should - re-attempt the transaction from the beginning, re-using the same + retry the transaction from the beginning, reusing the same session. On very rare occasions, ``Commit`` might return ``UNKNOWN``. @@ -1643,7 +1649,7 @@ async def sample_commit(): commit with a temporary transaction is non-idempotent. That is, if the ``CommitRequest`` is sent to Cloud Spanner more than once (for instance, due to retries in - the application, or in the transport library), it is + the application, or in the transport library), it's possible that the mutations are executed more than once. If this is undesirable, use [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction] @@ -1729,7 +1735,7 @@ async def rollback( timeout: Union[float, object] = gapic_v1.method.DEFAULT, metadata: Sequence[Tuple[str, Union[str, bytes]]] = (), ) -> None: - r"""Rolls back a transaction, releasing any locks it holds. It is a + r"""Rolls back a transaction, releasing any locks it holds. It's a good idea to call this for any transaction that includes one or more [Read][google.spanner.v1.Spanner.Read] or [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] requests and @@ -1737,8 +1743,7 @@ async def rollback( ``Rollback`` returns ``OK`` if it successfully aborts the transaction, the transaction was already aborted, or the - transaction is not found. ``Rollback`` never returns - ``ABORTED``. + transaction isn't found. ``Rollback`` never returns ``ABORTED``. .. code-block:: python @@ -1850,12 +1855,12 @@ async def partition_query( [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] to specify a subset of the query result to read. The same session and read-only transaction must be used by the - PartitionQueryRequest used to create the partition tokens and - the ExecuteSqlRequests that use the partition tokens. + ``PartitionQueryRequest`` used to create the partition tokens + and the ``ExecuteSqlRequests`` that use the partition tokens. Partition tokens become invalid when the session used to create them is deleted, is idle for too long, begins a new transaction, - or becomes too old. When any of these happen, it is not possible + or becomes too old. When any of these happen, it isn't possible to resume the query, and the whole operation must be restarted from the beginning. @@ -1951,15 +1956,15 @@ async def partition_read( [StreamingRead][google.spanner.v1.Spanner.StreamingRead] to specify a subset of the read result to read. The same session and read-only transaction must be used by the - PartitionReadRequest used to create the partition tokens and the - ReadRequests that use the partition tokens. There are no + ``PartitionReadRequest`` used to create the partition tokens and + the ``ReadRequests`` that use the partition tokens. There are no ordering guarantees on rows returned among the returned - partition tokens, or even within each individual StreamingRead - call issued with a partition_token. + partition tokens, or even within each individual + ``StreamingRead`` call issued with a ``partition_token``. Partition tokens become invalid when the session used to create them is deleted, is idle for too long, begins a new transaction, - or becomes too old. When any of these happen, it is not possible + or becomes too old. When any of these happen, it isn't possible to resume the read, and the whole operation must be restarted from the beginning. @@ -2053,25 +2058,23 @@ def batch_write( timeout: Union[float, object] = gapic_v1.method.DEFAULT, metadata: Sequence[Tuple[str, Union[str, bytes]]] = (), ) -> Awaitable[AsyncIterable[spanner.BatchWriteResponse]]: - r"""Batches the supplied mutation groups in a collection - of efficient transactions. All mutations in a group are - committed atomically. However, mutations across groups - can be committed non-atomically in an unspecified order - and thus, they must be independent of each other. - Partial failure is possible, i.e., some groups may have - been committed successfully, while some may have failed. - The results of individual batches are streamed into the - response as the batches are applied. - - BatchWrite requests are not replay protected, meaning - that each mutation group may be applied more than once. - Replays of non-idempotent mutations may have undesirable - effects. For example, replays of an insert mutation may - produce an already exists error or if you use generated - or commit timestamp-based keys, it may result in - additional rows being added to the mutation's table. We - recommend structuring your mutation groups to be - idempotent to avoid this issue. + r"""Batches the supplied mutation groups in a collection of + efficient transactions. All mutations in a group are committed + atomically. However, mutations across groups can be committed + non-atomically in an unspecified order and thus, they must be + independent of each other. Partial failure is possible, that is, + some groups might have been committed successfully, while some + might have failed. The results of individual batches are + streamed into the response as the batches are applied. + + ``BatchWrite`` requests are not replay protected, meaning that + each mutation group can be applied more than once. Replays of + non-idempotent mutations can have undesirable effects. For + example, replays of an insert mutation can produce an already + exists error or if you use generated or commit timestamp-based + keys, it can result in additional rows being added to the + mutation's table. We recommend structuring your mutation groups + to be idempotent to avoid this issue. .. code-block:: python diff --git a/google/cloud/spanner_v1/services/spanner/client.py b/google/cloud/spanner_v1/services/spanner/client.py index e853b2dfd5..82dbf8375e 100644 --- a/google/cloud/spanner_v1/services/spanner/client.py +++ b/google/cloud/spanner_v1/services/spanner/client.py @@ -762,14 +762,14 @@ def create_session( transaction internally, and count toward the one transaction limit. - Active sessions use additional server resources, so it is a good + Active sessions use additional server resources, so it's a good idea to delete idle and unneeded sessions. Aside from explicit - deletes, Cloud Spanner may delete sessions for which no - operations are sent for more than an hour. If a session is - deleted, requests to it return ``NOT_FOUND``. + deletes, Cloud Spanner can delete sessions when no operations + are sent for more than an hour. If a session is deleted, + requests to it return ``NOT_FOUND``. Idle sessions can be kept alive by sending a trivial SQL query - periodically, e.g., ``"SELECT 1"``. + periodically, for example, ``"SELECT 1"``. .. code-block:: python @@ -922,10 +922,10 @@ def sample_batch_create_sessions(): should not be set. session_count (int): Required. The number of sessions to be created in this - batch call. The API may return fewer than the requested + batch call. The API can return fewer than the requested number of sessions. If a specific number of sessions are desired, the client can make additional calls to - BatchCreateSessions (adjusting + ``BatchCreateSessions`` (adjusting [session_count][google.spanner.v1.BatchCreateSessionsRequest.session_count] as necessary). @@ -1003,7 +1003,7 @@ def get_session( timeout: Union[float, object] = gapic_v1.method.DEFAULT, metadata: Sequence[Tuple[str, Union[str, bytes]]] = (), ) -> spanner.Session: - r"""Gets a session. Returns ``NOT_FOUND`` if the session does not + r"""Gets a session. Returns ``NOT_FOUND`` if the session doesn't exist. This is mainly useful for determining whether a session is still alive. @@ -1235,7 +1235,7 @@ def delete_session( metadata: Sequence[Tuple[str, Union[str, bytes]]] = (), ) -> None: r"""Ends a session, releasing server resources associated - with it. This will asynchronously trigger cancellation + with it. This asynchronously triggers the cancellation of any operations that are running with this session. .. code-block:: python @@ -1332,7 +1332,7 @@ def execute_sql( metadata: Sequence[Tuple[str, Union[str, bytes]]] = (), ) -> result_set.ResultSet: r"""Executes an SQL statement, returning all results in a single - reply. This method cannot be used to return a result set larger + reply. This method can't be used to return a result set larger than 10 MiB; if the query yields more data than that, the query fails with a ``FAILED_PRECONDITION`` error. @@ -1346,6 +1346,9 @@ def execute_sql( [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] instead. + The query string can be SQL or `Graph Query Language + (GQL) `__. + .. code-block:: python # This snippet has been automatically generated and should be regarded as a @@ -1437,6 +1440,9 @@ def execute_streaming_sql( individual row in the result set can exceed 100 MiB, and no column value can exceed 10 MiB. + The query string can be SQL or `Graph Query Language + (GQL) `__. + .. code-block:: python # This snippet has been automatically generated and should be regarded as a @@ -1608,8 +1614,8 @@ def sample_execute_batch_dml(): Example 1: - - Request: 5 DML statements, all executed - successfully. + - Request: 5 DML statements, all executed + successfully. \* Response: 5 [ResultSet][google.spanner.v1.ResultSet] messages, @@ -1617,8 +1623,8 @@ def sample_execute_batch_dml(): Example 2: - - Request: 5 DML statements. The third statement has - a syntax error. + - Request: 5 DML statements. The third statement has + a syntax error. \* Response: 2 [ResultSet][google.spanner.v1.ResultSet] messages, @@ -1670,7 +1676,7 @@ def read( r"""Reads rows from the database using key lookups and scans, as a simple key/value style alternative to [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. This method - cannot be used to return a result set larger than 10 MiB; if the + can't be used to return a result set larger than 10 MiB; if the read matches more data than that, the read fails with a ``FAILED_PRECONDITION`` error. @@ -1995,7 +2001,7 @@ def commit( any time; commonly, the cause is conflicts with concurrent transactions. However, it can also happen for a variety of other reasons. If ``Commit`` returns ``ABORTED``, the caller should - re-attempt the transaction from the beginning, re-using the same + retry the transaction from the beginning, reusing the same session. On very rare occasions, ``Commit`` might return ``UNKNOWN``. @@ -2065,7 +2071,7 @@ def sample_commit(): commit with a temporary transaction is non-idempotent. That is, if the ``CommitRequest`` is sent to Cloud Spanner more than once (for instance, due to retries in - the application, or in the transport library), it is + the application, or in the transport library), it's possible that the mutations are executed more than once. If this is undesirable, use [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction] @@ -2150,7 +2156,7 @@ def rollback( timeout: Union[float, object] = gapic_v1.method.DEFAULT, metadata: Sequence[Tuple[str, Union[str, bytes]]] = (), ) -> None: - r"""Rolls back a transaction, releasing any locks it holds. It is a + r"""Rolls back a transaction, releasing any locks it holds. It's a good idea to call this for any transaction that includes one or more [Read][google.spanner.v1.Spanner.Read] or [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] requests and @@ -2158,8 +2164,7 @@ def rollback( ``Rollback`` returns ``OK`` if it successfully aborts the transaction, the transaction was already aborted, or the - transaction is not found. ``Rollback`` never returns - ``ABORTED``. + transaction isn't found. ``Rollback`` never returns ``ABORTED``. .. code-block:: python @@ -2270,12 +2275,12 @@ def partition_query( [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] to specify a subset of the query result to read. The same session and read-only transaction must be used by the - PartitionQueryRequest used to create the partition tokens and - the ExecuteSqlRequests that use the partition tokens. + ``PartitionQueryRequest`` used to create the partition tokens + and the ``ExecuteSqlRequests`` that use the partition tokens. Partition tokens become invalid when the session used to create them is deleted, is idle for too long, begins a new transaction, - or becomes too old. When any of these happen, it is not possible + or becomes too old. When any of these happen, it isn't possible to resume the query, and the whole operation must be restarted from the beginning. @@ -2369,15 +2374,15 @@ def partition_read( [StreamingRead][google.spanner.v1.Spanner.StreamingRead] to specify a subset of the read result to read. The same session and read-only transaction must be used by the - PartitionReadRequest used to create the partition tokens and the - ReadRequests that use the partition tokens. There are no + ``PartitionReadRequest`` used to create the partition tokens and + the ``ReadRequests`` that use the partition tokens. There are no ordering guarantees on rows returned among the returned - partition tokens, or even within each individual StreamingRead - call issued with a partition_token. + partition tokens, or even within each individual + ``StreamingRead`` call issued with a ``partition_token``. Partition tokens become invalid when the session used to create them is deleted, is idle for too long, begins a new transaction, - or becomes too old. When any of these happen, it is not possible + or becomes too old. When any of these happen, it isn't possible to resume the read, and the whole operation must be restarted from the beginning. @@ -2469,25 +2474,23 @@ def batch_write( timeout: Union[float, object] = gapic_v1.method.DEFAULT, metadata: Sequence[Tuple[str, Union[str, bytes]]] = (), ) -> Iterable[spanner.BatchWriteResponse]: - r"""Batches the supplied mutation groups in a collection - of efficient transactions. All mutations in a group are - committed atomically. However, mutations across groups - can be committed non-atomically in an unspecified order - and thus, they must be independent of each other. - Partial failure is possible, i.e., some groups may have - been committed successfully, while some may have failed. - The results of individual batches are streamed into the - response as the batches are applied. - - BatchWrite requests are not replay protected, meaning - that each mutation group may be applied more than once. - Replays of non-idempotent mutations may have undesirable - effects. For example, replays of an insert mutation may - produce an already exists error or if you use generated - or commit timestamp-based keys, it may result in - additional rows being added to the mutation's table. We - recommend structuring your mutation groups to be - idempotent to avoid this issue. + r"""Batches the supplied mutation groups in a collection of + efficient transactions. All mutations in a group are committed + atomically. However, mutations across groups can be committed + non-atomically in an unspecified order and thus, they must be + independent of each other. Partial failure is possible, that is, + some groups might have been committed successfully, while some + might have failed. The results of individual batches are + streamed into the response as the batches are applied. + + ``BatchWrite`` requests are not replay protected, meaning that + each mutation group can be applied more than once. Replays of + non-idempotent mutations can have undesirable effects. For + example, replays of an insert mutation can produce an already + exists error or if you use generated or commit timestamp-based + keys, it can result in additional rows being added to the + mutation's table. We recommend structuring your mutation groups + to be idempotent to avoid this issue. .. code-block:: python diff --git a/google/cloud/spanner_v1/services/spanner/transports/grpc.py b/google/cloud/spanner_v1/services/spanner/transports/grpc.py index 148abd592a..8b377d7725 100644 --- a/google/cloud/spanner_v1/services/spanner/transports/grpc.py +++ b/google/cloud/spanner_v1/services/spanner/transports/grpc.py @@ -354,14 +354,14 @@ def create_session( transaction internally, and count toward the one transaction limit. - Active sessions use additional server resources, so it is a good + Active sessions use additional server resources, so it's a good idea to delete idle and unneeded sessions. Aside from explicit - deletes, Cloud Spanner may delete sessions for which no - operations are sent for more than an hour. If a session is - deleted, requests to it return ``NOT_FOUND``. + deletes, Cloud Spanner can delete sessions when no operations + are sent for more than an hour. If a session is deleted, + requests to it return ``NOT_FOUND``. Idle sessions can be kept alive by sending a trivial SQL query - periodically, e.g., ``"SELECT 1"``. + periodically, for example, ``"SELECT 1"``. Returns: Callable[[~.CreateSessionRequest], @@ -417,7 +417,7 @@ def batch_create_sessions( def get_session(self) -> Callable[[spanner.GetSessionRequest], spanner.Session]: r"""Return a callable for the get session method over gRPC. - Gets a session. Returns ``NOT_FOUND`` if the session does not + Gets a session. Returns ``NOT_FOUND`` if the session doesn't exist. This is mainly useful for determining whether a session is still alive. @@ -472,7 +472,7 @@ def delete_session( r"""Return a callable for the delete session method over gRPC. Ends a session, releasing server resources associated - with it. This will asynchronously trigger cancellation + with it. This asynchronously triggers the cancellation of any operations that are running with this session. Returns: @@ -500,7 +500,7 @@ def execute_sql( r"""Return a callable for the execute sql method over gRPC. Executes an SQL statement, returning all results in a single - reply. This method cannot be used to return a result set larger + reply. This method can't be used to return a result set larger than 10 MiB; if the query yields more data than that, the query fails with a ``FAILED_PRECONDITION`` error. @@ -514,6 +514,9 @@ def execute_sql( [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] instead. + The query string can be SQL or `Graph Query Language + (GQL) `__. + Returns: Callable[[~.ExecuteSqlRequest], ~.ResultSet]: @@ -545,6 +548,9 @@ def execute_streaming_sql( individual row in the result set can exceed 100 MiB, and no column value can exceed 10 MiB. + The query string can be SQL or `Graph Query Language + (GQL) `__. + Returns: Callable[[~.ExecuteSqlRequest], ~.PartialResultSet]: @@ -609,7 +615,7 @@ def read(self) -> Callable[[spanner.ReadRequest], result_set.ResultSet]: Reads rows from the database using key lookups and scans, as a simple key/value style alternative to [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. This method - cannot be used to return a result set larger than 10 MiB; if the + can't be used to return a result set larger than 10 MiB; if the read matches more data than that, the read fails with a ``FAILED_PRECONDITION`` error. @@ -714,7 +720,7 @@ def commit( any time; commonly, the cause is conflicts with concurrent transactions. However, it can also happen for a variety of other reasons. If ``Commit`` returns ``ABORTED``, the caller should - re-attempt the transaction from the beginning, re-using the same + retry the transaction from the beginning, reusing the same session. On very rare occasions, ``Commit`` might return ``UNKNOWN``. @@ -746,7 +752,7 @@ def commit( def rollback(self) -> Callable[[spanner.RollbackRequest], empty_pb2.Empty]: r"""Return a callable for the rollback method over gRPC. - Rolls back a transaction, releasing any locks it holds. It is a + Rolls back a transaction, releasing any locks it holds. It's a good idea to call this for any transaction that includes one or more [Read][google.spanner.v1.Spanner.Read] or [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] requests and @@ -754,8 +760,7 @@ def rollback(self) -> Callable[[spanner.RollbackRequest], empty_pb2.Empty]: ``Rollback`` returns ``OK`` if it successfully aborts the transaction, the transaction was already aborted, or the - transaction is not found. ``Rollback`` never returns - ``ABORTED``. + transaction isn't found. ``Rollback`` never returns ``ABORTED``. Returns: Callable[[~.RollbackRequest], @@ -787,12 +792,12 @@ def partition_query( [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] to specify a subset of the query result to read. The same session and read-only transaction must be used by the - PartitionQueryRequest used to create the partition tokens and - the ExecuteSqlRequests that use the partition tokens. + ``PartitionQueryRequest`` used to create the partition tokens + and the ``ExecuteSqlRequests`` that use the partition tokens. Partition tokens become invalid when the session used to create them is deleted, is idle for too long, begins a new transaction, - or becomes too old. When any of these happen, it is not possible + or becomes too old. When any of these happen, it isn't possible to resume the query, and the whole operation must be restarted from the beginning. @@ -826,15 +831,15 @@ def partition_read( [StreamingRead][google.spanner.v1.Spanner.StreamingRead] to specify a subset of the read result to read. The same session and read-only transaction must be used by the - PartitionReadRequest used to create the partition tokens and the - ReadRequests that use the partition tokens. There are no + ``PartitionReadRequest`` used to create the partition tokens and + the ``ReadRequests`` that use the partition tokens. There are no ordering guarantees on rows returned among the returned - partition tokens, or even within each individual StreamingRead - call issued with a partition_token. + partition tokens, or even within each individual + ``StreamingRead`` call issued with a ``partition_token``. Partition tokens become invalid when the session used to create them is deleted, is idle for too long, begins a new transaction, - or becomes too old. When any of these happen, it is not possible + or becomes too old. When any of these happen, it isn't possible to resume the read, and the whole operation must be restarted from the beginning. @@ -862,25 +867,23 @@ def batch_write( ) -> Callable[[spanner.BatchWriteRequest], spanner.BatchWriteResponse]: r"""Return a callable for the batch write method over gRPC. - Batches the supplied mutation groups in a collection - of efficient transactions. All mutations in a group are - committed atomically. However, mutations across groups - can be committed non-atomically in an unspecified order - and thus, they must be independent of each other. - Partial failure is possible, i.e., some groups may have - been committed successfully, while some may have failed. - The results of individual batches are streamed into the - response as the batches are applied. - - BatchWrite requests are not replay protected, meaning - that each mutation group may be applied more than once. - Replays of non-idempotent mutations may have undesirable - effects. For example, replays of an insert mutation may - produce an already exists error or if you use generated - or commit timestamp-based keys, it may result in - additional rows being added to the mutation's table. We - recommend structuring your mutation groups to be - idempotent to avoid this issue. + Batches the supplied mutation groups in a collection of + efficient transactions. All mutations in a group are committed + atomically. However, mutations across groups can be committed + non-atomically in an unspecified order and thus, they must be + independent of each other. Partial failure is possible, that is, + some groups might have been committed successfully, while some + might have failed. The results of individual batches are + streamed into the response as the batches are applied. + + ``BatchWrite`` requests are not replay protected, meaning that + each mutation group can be applied more than once. Replays of + non-idempotent mutations can have undesirable effects. For + example, replays of an insert mutation can produce an already + exists error or if you use generated or commit timestamp-based + keys, it can result in additional rows being added to the + mutation's table. We recommend structuring your mutation groups + to be idempotent to avoid this issue. Returns: Callable[[~.BatchWriteRequest], diff --git a/google/cloud/spanner_v1/services/spanner/transports/grpc_asyncio.py b/google/cloud/spanner_v1/services/spanner/transports/grpc_asyncio.py index 86ac4915d7..2c6cec52a9 100644 --- a/google/cloud/spanner_v1/services/spanner/transports/grpc_asyncio.py +++ b/google/cloud/spanner_v1/services/spanner/transports/grpc_asyncio.py @@ -354,14 +354,14 @@ def create_session( transaction internally, and count toward the one transaction limit. - Active sessions use additional server resources, so it is a good + Active sessions use additional server resources, so it's a good idea to delete idle and unneeded sessions. Aside from explicit - deletes, Cloud Spanner may delete sessions for which no - operations are sent for more than an hour. If a session is - deleted, requests to it return ``NOT_FOUND``. + deletes, Cloud Spanner can delete sessions when no operations + are sent for more than an hour. If a session is deleted, + requests to it return ``NOT_FOUND``. Idle sessions can be kept alive by sending a trivial SQL query - periodically, e.g., ``"SELECT 1"``. + periodically, for example, ``"SELECT 1"``. Returns: Callable[[~.CreateSessionRequest], @@ -420,7 +420,7 @@ def get_session( ) -> Callable[[spanner.GetSessionRequest], Awaitable[spanner.Session]]: r"""Return a callable for the get session method over gRPC. - Gets a session. Returns ``NOT_FOUND`` if the session does not + Gets a session. Returns ``NOT_FOUND`` if the session doesn't exist. This is mainly useful for determining whether a session is still alive. @@ -477,7 +477,7 @@ def delete_session( r"""Return a callable for the delete session method over gRPC. Ends a session, releasing server resources associated - with it. This will asynchronously trigger cancellation + with it. This asynchronously triggers the cancellation of any operations that are running with this session. Returns: @@ -505,7 +505,7 @@ def execute_sql( r"""Return a callable for the execute sql method over gRPC. Executes an SQL statement, returning all results in a single - reply. This method cannot be used to return a result set larger + reply. This method can't be used to return a result set larger than 10 MiB; if the query yields more data than that, the query fails with a ``FAILED_PRECONDITION`` error. @@ -519,6 +519,9 @@ def execute_sql( [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] instead. + The query string can be SQL or `Graph Query Language + (GQL) `__. + Returns: Callable[[~.ExecuteSqlRequest], Awaitable[~.ResultSet]]: @@ -550,6 +553,9 @@ def execute_streaming_sql( individual row in the result set can exceed 100 MiB, and no column value can exceed 10 MiB. + The query string can be SQL or `Graph Query Language + (GQL) `__. + Returns: Callable[[~.ExecuteSqlRequest], Awaitable[~.PartialResultSet]]: @@ -616,7 +622,7 @@ def read(self) -> Callable[[spanner.ReadRequest], Awaitable[result_set.ResultSet Reads rows from the database using key lookups and scans, as a simple key/value style alternative to [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. This method - cannot be used to return a result set larger than 10 MiB; if the + can't be used to return a result set larger than 10 MiB; if the read matches more data than that, the read fails with a ``FAILED_PRECONDITION`` error. @@ -723,7 +729,7 @@ def commit( any time; commonly, the cause is conflicts with concurrent transactions. However, it can also happen for a variety of other reasons. If ``Commit`` returns ``ABORTED``, the caller should - re-attempt the transaction from the beginning, re-using the same + retry the transaction from the beginning, reusing the same session. On very rare occasions, ``Commit`` might return ``UNKNOWN``. @@ -757,7 +763,7 @@ def rollback( ) -> Callable[[spanner.RollbackRequest], Awaitable[empty_pb2.Empty]]: r"""Return a callable for the rollback method over gRPC. - Rolls back a transaction, releasing any locks it holds. It is a + Rolls back a transaction, releasing any locks it holds. It's a good idea to call this for any transaction that includes one or more [Read][google.spanner.v1.Spanner.Read] or [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] requests and @@ -765,8 +771,7 @@ def rollback( ``Rollback`` returns ``OK`` if it successfully aborts the transaction, the transaction was already aborted, or the - transaction is not found. ``Rollback`` never returns - ``ABORTED``. + transaction isn't found. ``Rollback`` never returns ``ABORTED``. Returns: Callable[[~.RollbackRequest], @@ -800,12 +805,12 @@ def partition_query( [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] to specify a subset of the query result to read. The same session and read-only transaction must be used by the - PartitionQueryRequest used to create the partition tokens and - the ExecuteSqlRequests that use the partition tokens. + ``PartitionQueryRequest`` used to create the partition tokens + and the ``ExecuteSqlRequests`` that use the partition tokens. Partition tokens become invalid when the session used to create them is deleted, is idle for too long, begins a new transaction, - or becomes too old. When any of these happen, it is not possible + or becomes too old. When any of these happen, it isn't possible to resume the query, and the whole operation must be restarted from the beginning. @@ -839,15 +844,15 @@ def partition_read( [StreamingRead][google.spanner.v1.Spanner.StreamingRead] to specify a subset of the read result to read. The same session and read-only transaction must be used by the - PartitionReadRequest used to create the partition tokens and the - ReadRequests that use the partition tokens. There are no + ``PartitionReadRequest`` used to create the partition tokens and + the ``ReadRequests`` that use the partition tokens. There are no ordering guarantees on rows returned among the returned - partition tokens, or even within each individual StreamingRead - call issued with a partition_token. + partition tokens, or even within each individual + ``StreamingRead`` call issued with a ``partition_token``. Partition tokens become invalid when the session used to create them is deleted, is idle for too long, begins a new transaction, - or becomes too old. When any of these happen, it is not possible + or becomes too old. When any of these happen, it isn't possible to resume the read, and the whole operation must be restarted from the beginning. @@ -875,25 +880,23 @@ def batch_write( ) -> Callable[[spanner.BatchWriteRequest], Awaitable[spanner.BatchWriteResponse]]: r"""Return a callable for the batch write method over gRPC. - Batches the supplied mutation groups in a collection - of efficient transactions. All mutations in a group are - committed atomically. However, mutations across groups - can be committed non-atomically in an unspecified order - and thus, they must be independent of each other. - Partial failure is possible, i.e., some groups may have - been committed successfully, while some may have failed. - The results of individual batches are streamed into the - response as the batches are applied. - - BatchWrite requests are not replay protected, meaning - that each mutation group may be applied more than once. - Replays of non-idempotent mutations may have undesirable - effects. For example, replays of an insert mutation may - produce an already exists error or if you use generated - or commit timestamp-based keys, it may result in - additional rows being added to the mutation's table. We - recommend structuring your mutation groups to be - idempotent to avoid this issue. + Batches the supplied mutation groups in a collection of + efficient transactions. All mutations in a group are committed + atomically. However, mutations across groups can be committed + non-atomically in an unspecified order and thus, they must be + independent of each other. Partial failure is possible, that is, + some groups might have been committed successfully, while some + might have failed. The results of individual batches are + streamed into the response as the batches are applied. + + ``BatchWrite`` requests are not replay protected, meaning that + each mutation group can be applied more than once. Replays of + non-idempotent mutations can have undesirable effects. For + example, replays of an insert mutation can produce an already + exists error or if you use generated or commit timestamp-based + keys, it can result in additional rows being added to the + mutation's table. We recommend structuring your mutation groups + to be idempotent to avoid this issue. Returns: Callable[[~.BatchWriteRequest], diff --git a/google/cloud/spanner_v1/services/spanner/transports/rest.py b/google/cloud/spanner_v1/services/spanner/transports/rest.py index 7ad0a4e24e..7b49a0d76a 100644 --- a/google/cloud/spanner_v1/services/spanner/transports/rest.py +++ b/google/cloud/spanner_v1/services/spanner/transports/rest.py @@ -1259,6 +1259,22 @@ def __call__( resp, _ = self._interceptor.post_batch_write_with_metadata( resp, response_metadata ) + if CLIENT_LOGGING_SUPPORTED and _LOGGER.isEnabledFor( + logging.DEBUG + ): # pragma: NO COVER + http_response = { + "headers": dict(response.headers), + "status": response.status_code, + } + _LOGGER.debug( + "Received response for google.spanner_v1.SpannerClient.batch_write", + extra={ + "serviceName": "google.spanner.v1.Spanner", + "rpcName": "BatchWrite", + "metadata": http_response["headers"], + "httpResponse": http_response, + }, + ) return resp class _BeginTransaction( @@ -1910,20 +1926,20 @@ def __call__( Example 1: - - Request: 5 DML statements, all executed successfully. - - Response: 5 [ResultSet][google.spanner.v1.ResultSet] - messages, with the status ``OK``. + - Request: 5 DML statements, all executed successfully. + - Response: 5 [ResultSet][google.spanner.v1.ResultSet] + messages, with the status ``OK``. Example 2: - - Request: 5 DML statements. The third statement has a - syntax error. - - Response: 2 [ResultSet][google.spanner.v1.ResultSet] - messages, and a syntax error (``INVALID_ARGUMENT``) - status. The number of - [ResultSet][google.spanner.v1.ResultSet] messages - indicates that the third statement failed, and the - fourth and fifth statements were not executed. + - Request: 5 DML statements. The third statement has a + syntax error. + - Response: 2 [ResultSet][google.spanner.v1.ResultSet] + messages, and a syntax error (``INVALID_ARGUMENT``) + status. The number of + [ResultSet][google.spanner.v1.ResultSet] messages + indicates that the third statement failed, and the + fourth and fifth statements were not executed. """ @@ -2320,6 +2336,22 @@ def __call__( resp, _ = self._interceptor.post_execute_streaming_sql_with_metadata( resp, response_metadata ) + if CLIENT_LOGGING_SUPPORTED and _LOGGER.isEnabledFor( + logging.DEBUG + ): # pragma: NO COVER + http_response = { + "headers": dict(response.headers), + "status": response.status_code, + } + _LOGGER.debug( + "Received response for google.spanner_v1.SpannerClient.execute_streaming_sql", + extra={ + "serviceName": "google.spanner.v1.Spanner", + "rpcName": "ExecuteStreamingSql", + "metadata": http_response["headers"], + "httpResponse": http_response, + }, + ) return resp class _GetSession(_BaseSpannerRestTransport._BaseGetSession, SpannerRestStub): @@ -3331,6 +3363,22 @@ def __call__( resp, _ = self._interceptor.post_streaming_read_with_metadata( resp, response_metadata ) + if CLIENT_LOGGING_SUPPORTED and _LOGGER.isEnabledFor( + logging.DEBUG + ): # pragma: NO COVER + http_response = { + "headers": dict(response.headers), + "status": response.status_code, + } + _LOGGER.debug( + "Received response for google.spanner_v1.SpannerClient.streaming_read", + extra={ + "serviceName": "google.spanner.v1.Spanner", + "rpcName": "StreamingRead", + "metadata": http_response["headers"], + "httpResponse": http_response, + }, + ) return resp @property diff --git a/google/cloud/spanner_v1/types/change_stream.py b/google/cloud/spanner_v1/types/change_stream.py index fb88824c19..762fc6a5d5 100644 --- a/google/cloud/spanner_v1/types/change_stream.py +++ b/google/cloud/spanner_v1/types/change_stream.py @@ -42,7 +42,7 @@ class ChangeStreamRecord(proto.Message): partition_mode='MUTABLE_KEY_RANGE'. Spanner automatically creates a special Table-Valued Function (TVF) along with each Change Streams. The function provides access to the change stream's records. The - function is named READ_ (where + function is named READ\_ (where is the name of the change stream), and it returns a table with only one column called ChangeRecord. diff --git a/google/cloud/spanner_v1/types/result_set.py b/google/cloud/spanner_v1/types/result_set.py index 68119316d2..697d0fd33b 100644 --- a/google/cloud/spanner_v1/types/result_set.py +++ b/google/cloud/spanner_v1/types/result_set.py @@ -120,15 +120,15 @@ class PartialResultSet(proto.Message): field. Two or more chunked values can be merged to form a complete value as follows: - - ``bool/number/null``: can't be chunked - - ``string``: concatenate the strings - - ``list``: concatenate the lists. If the last element in a - list is a ``string``, ``list``, or ``object``, merge it - with the first element in the next list by applying these - rules recursively. - - ``object``: concatenate the (field name, field value) - pairs. If a field name is duplicated, then apply these - rules recursively to merge the field values. + - ``bool/number/null``: can't be chunked + - ``string``: concatenate the strings + - ``list``: concatenate the lists. If the last element in a + list is a ``string``, ``list``, or ``object``, merge it + with the first element in the next list by applying these + rules recursively. + - ``object``: concatenate the (field name, field value) + pairs. If a field name is duplicated, then apply these + rules recursively to merge the field values. Some examples of merging: diff --git a/google/cloud/spanner_v1/types/spanner.py b/google/cloud/spanner_v1/types/spanner.py index 67f1093448..9e7a477b46 100644 --- a/google/cloud/spanner_v1/types/spanner.py +++ b/google/cloud/spanner_v1/types/spanner.py @@ -93,13 +93,12 @@ class BatchCreateSessionsRequest(proto.Message): Required. The database in which the new sessions are created. session_template (google.cloud.spanner_v1.types.Session): - Parameters to be applied to each created - session. + Parameters to apply to each created session. session_count (int): Required. The number of sessions to be created in this batch - call. The API may return fewer than the requested number of + call. The API can return fewer than the requested number of sessions. If a specific number of sessions are desired, the - client can make additional calls to BatchCreateSessions + client can make additional calls to ``BatchCreateSessions`` (adjusting [session_count][google.spanner.v1.BatchCreateSessionsRequest.session_count] as necessary). @@ -146,14 +145,14 @@ class Session(proto.Message): labels (MutableMapping[str, str]): The labels for the session. - - Label keys must be between 1 and 63 characters long and - must conform to the following regular expression: - ``[a-z]([-a-z0-9]*[a-z0-9])?``. - - Label values must be between 0 and 63 characters long and - must conform to the regular expression - ``([a-z]([-a-z0-9]*[a-z0-9])?)?``. - - No more than 64 labels can be associated with a given - session. + - Label keys must be between 1 and 63 characters long and + must conform to the following regular expression: + ``[a-z]([-a-z0-9]*[a-z0-9])?``. + - Label values must be between 0 and 63 characters long and + must conform to the regular expression + ``([a-z]([-a-z0-9]*[a-z0-9])?)?``. + - No more than 64 labels can be associated with a given + session. See https://goo.gl/xmQnxf for more information on and examples of labels. @@ -162,20 +161,20 @@ class Session(proto.Message): is created. approximate_last_use_time (google.protobuf.timestamp_pb2.Timestamp): Output only. The approximate timestamp when - the session is last used. It is typically - earlier than the actual last use time. + the session is last used. It's typically earlier + than the actual last use time. creator_role (str): The database role which created this session. multiplexed (bool): - Optional. If true, specifies a multiplexed session. A - multiplexed session may be used for multiple, concurrent - read-only operations but can not be used for read-write - transactions, partitioned reads, or partitioned queries. - Multiplexed sessions can be created via - [CreateSession][google.spanner.v1.Spanner.CreateSession] but - not via - [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions]. - Multiplexed sessions may not be deleted nor listed. + Optional. If ``true``, specifies a multiplexed session. Use + a multiplexed session for multiple, concurrent read-only + operations. Don't use them for read-write transactions, + partitioned reads, or partitioned queries. Use + [``sessions.create``][google.spanner.v1.Spanner.CreateSession] + to create multiplexed sessions. Don't use + [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions] + to create a multiplexed session. You can't delete or list + multiplexed sessions. """ name: str = proto.Field( @@ -244,13 +243,13 @@ class ListSessionsRequest(proto.Message): Filter rules are case insensitive. The fields eligible for filtering are: - - ``labels.key`` where key is the name of a label + - ``labels.key`` where key is the name of a label Some examples of using filters are: - - ``labels.env:*`` --> The session has the label "env". - - ``labels.env:dev`` --> The session has the label "env" - and the value of the label contains the string "dev". + - ``labels.env:*`` --> The session has the label "env". + - ``labels.env:dev`` --> The session has the label "env" and + the value of the label contains the string "dev". """ database: str = proto.Field( @@ -322,47 +321,47 @@ class RequestOptions(proto.Message): Priority for the request. request_tag (str): A per-request tag which can be applied to queries or reads, - used for statistics collection. Both request_tag and - transaction_tag can be specified for a read or query that - belongs to a transaction. This field is ignored for requests - where it's not applicable (e.g. CommitRequest). Legal - characters for ``request_tag`` values are all printable - characters (ASCII 32 - 126) and the length of a request_tag - is limited to 50 characters. Values that exceed this limit - are truncated. Any leading underscore (_) characters will be - removed from the string. + used for statistics collection. Both ``request_tag`` and + ``transaction_tag`` can be specified for a read or query + that belongs to a transaction. This field is ignored for + requests where it's not applicable (for example, + ``CommitRequest``). Legal characters for ``request_tag`` + values are all printable characters (ASCII 32 - 126) and the + length of a request_tag is limited to 50 characters. Values + that exceed this limit are truncated. Any leading underscore + (\_) characters are removed from the string. transaction_tag (str): A tag used for statistics collection about this transaction. - Both request_tag and transaction_tag can be specified for a - read or query that belongs to a transaction. The value of - transaction_tag should be the same for all requests - belonging to the same transaction. If this request doesn't - belong to any transaction, transaction_tag will be ignored. - Legal characters for ``transaction_tag`` values are all - printable characters (ASCII 32 - 126) and the length of a - transaction_tag is limited to 50 characters. Values that - exceed this limit are truncated. Any leading underscore (_) - characters will be removed from the string. + Both ``request_tag`` and ``transaction_tag`` can be + specified for a read or query that belongs to a transaction. + The value of transaction_tag should be the same for all + requests belonging to the same transaction. If this request + doesn't belong to any transaction, ``transaction_tag`` is + ignored. Legal characters for ``transaction_tag`` values are + all printable characters (ASCII 32 - 126) and the length of + a ``transaction_tag`` is limited to 50 characters. Values + that exceed this limit are truncated. Any leading underscore + (\_) characters are removed from the string. """ class Priority(proto.Enum): - r"""The relative priority for requests. Note that priority is not + r"""The relative priority for requests. Note that priority isn't applicable for [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction]. - The priority acts as a hint to the Cloud Spanner scheduler and does - not guarantee priority or order of execution. For example: + The priority acts as a hint to the Cloud Spanner scheduler and + doesn't guarantee priority or order of execution. For example: - - Some parts of a write operation always execute at - ``PRIORITY_HIGH``, regardless of the specified priority. This may - cause you to see an increase in high priority workload even when - executing a low priority request. This can also potentially cause - a priority inversion where a lower priority request will be - fulfilled ahead of a higher priority request. - - If a transaction contains multiple operations with different - priorities, Cloud Spanner does not guarantee to process the - higher priority operations first. There may be other constraints - to satisfy, such as order of operations. + - Some parts of a write operation always execute at + ``PRIORITY_HIGH``, regardless of the specified priority. This can + cause you to see an increase in high priority workload even when + executing a low priority request. This can also potentially cause + a priority inversion where a lower priority request is fulfilled + ahead of a higher priority request. + - If a transaction contains multiple operations with different + priorities, Cloud Spanner doesn't guarantee to process the higher + priority operations first. There might be other constraints to + satisfy, such as the order of operations. Values: PRIORITY_UNSPECIFIED (0): @@ -398,11 +397,11 @@ class Priority(proto.Enum): class DirectedReadOptions(proto.Message): - r"""The DirectedReadOptions can be used to indicate which replicas or - regions should be used for non-transactional reads or queries. + r"""The ``DirectedReadOptions`` can be used to indicate which replicas + or regions should be used for non-transactional reads or queries. - DirectedReadOptions may only be specified for a read-only - transaction, otherwise the API will return an ``INVALID_ARGUMENT`` + ``DirectedReadOptions`` can only be specified for a read-only + transaction, otherwise the API returns an ``INVALID_ARGUMENT`` error. This message has `oneof`_ fields (mutually exclusive fields). @@ -414,18 +413,18 @@ class DirectedReadOptions(proto.Message): Attributes: include_replicas (google.cloud.spanner_v1.types.DirectedReadOptions.IncludeReplicas): - Include_replicas indicates the order of replicas (as they - appear in this list) to process the request. If - auto_failover_disabled is set to true and all replicas are - exhausted without finding a healthy replica, Spanner will - wait for a replica in the list to become available, requests - may fail due to ``DEADLINE_EXCEEDED`` errors. + ``Include_replicas`` indicates the order of replicas (as + they appear in this list) to process the request. If + ``auto_failover_disabled`` is set to ``true`` and all + replicas are exhausted without finding a healthy replica, + Spanner waits for a replica in the list to become available, + requests might fail due to ``DEADLINE_EXCEEDED`` errors. This field is a member of `oneof`_ ``replicas``. exclude_replicas (google.cloud.spanner_v1.types.DirectedReadOptions.ExcludeReplicas): - Exclude_replicas indicates that specified replicas should be - excluded from serving requests. Spanner will not route - requests to the replicas in this list. + ``Exclude_replicas`` indicates that specified replicas + should be excluded from serving requests. Spanner doesn't + route requests to the replicas in this list. This field is a member of `oneof`_ ``replicas``. """ @@ -434,24 +433,23 @@ class ReplicaSelection(proto.Message): r"""The directed read replica selector. Callers must provide one or more of the following fields for replica selection: - - ``location`` - The location must be one of the regions within the - multi-region configuration of your database. - - ``type`` - The type of the replica. + - ``location`` - The location must be one of the regions within the + multi-region configuration of your database. + - ``type`` - The type of the replica. Some examples of using replica_selectors are: - - ``location:us-east1`` --> The "us-east1" replica(s) of any - available type will be used to process the request. - - ``type:READ_ONLY`` --> The "READ_ONLY" type replica(s) in nearest - available location will be used to process the request. - - ``location:us-east1 type:READ_ONLY`` --> The "READ_ONLY" type - replica(s) in location "us-east1" will be used to process the - request. + - ``location:us-east1`` --> The "us-east1" replica(s) of any + available type is used to process the request. + - ``type:READ_ONLY`` --> The "READ_ONLY" type replica(s) in the + nearest available location are used to process the request. + - ``location:us-east1 type:READ_ONLY`` --> The "READ_ONLY" type + replica(s) in location "us-east1" is used to process the request. Attributes: location (str): The location or region of the serving - requests, e.g. "us-east1". + requests, for example, "us-east1". type_ (google.cloud.spanner_v1.types.DirectedReadOptions.ReplicaSelection.Type): The type of replica. """ @@ -484,18 +482,18 @@ class Type(proto.Enum): ) class IncludeReplicas(proto.Message): - r"""An IncludeReplicas contains a repeated set of - ReplicaSelection which indicates the order in which replicas + r"""An ``IncludeReplicas`` contains a repeated set of + ``ReplicaSelection`` which indicates the order in which replicas should be considered. Attributes: replica_selections (MutableSequence[google.cloud.spanner_v1.types.DirectedReadOptions.ReplicaSelection]): The directed read replica selector. auto_failover_disabled (bool): - If true, Spanner will not route requests to a replica - outside the include_replicas list when all of the specified - replicas are unavailable or unhealthy. Default value is - ``false``. + If ``true``, Spanner doesn't route requests to a replica + outside the <``include_replicas`` list when all of the + specified replicas are unavailable or unhealthy. Default + value is ``false``. """ replica_selections: MutableSequence[ @@ -559,7 +557,7 @@ class ExecuteSqlRequest(proto.Message): Standard DML statements require a read-write transaction. To protect against replays, - single-use transactions are not supported. The + single-use transactions are not supported. The caller must either supply an existing transaction ID or begin a new transaction. @@ -583,16 +581,16 @@ class ExecuteSqlRequest(proto.Message): ``"WHERE id > @msg_id AND id < @msg_id + 100"`` - It is an error to execute a SQL statement with unbound + It's an error to execute a SQL statement with unbound parameters. param_types (MutableMapping[str, google.cloud.spanner_v1.types.Type]): - It is not always possible for Cloud Spanner to infer the + It isn't always possible for Cloud Spanner to infer the right SQL type from a JSON value. For example, values of type ``BYTES`` and values of type ``STRING`` both appear in [params][google.spanner.v1.ExecuteSqlRequest.params] as JSON strings. - In these cases, ``param_types`` can be used to specify the + In these cases, you can use ``param_types`` to specify the exact SQL type for some or all of the SQL statement parameters. See the definition of [Type][google.spanner.v1.Type] for more information about @@ -615,24 +613,23 @@ class ExecuteSqlRequest(proto.Message): can only be set to [QueryMode.NORMAL][google.spanner.v1.ExecuteSqlRequest.QueryMode.NORMAL]. partition_token (bytes): - If present, results will be restricted to the specified - partition previously created using PartitionQuery(). There + If present, results are restricted to the specified + partition previously created using ``PartitionQuery``. There must be an exact match for the values of fields common to - this message and the PartitionQueryRequest message used to - create this partition_token. + this message and the ``PartitionQueryRequest`` message used + to create this ``partition_token``. seqno (int): A per-transaction sequence number used to identify this request. This field makes each request idempotent such that if the request is - received multiple times, at most one will - succeed. + received multiple times, at most one succeeds. The sequence number must be monotonically increasing within the transaction. If a request arrives for the first time with an out-of-order - sequence number, the transaction may be aborted. - Replays of previously handled requests will - yield the same response as the first execution. + sequence number, the transaction can be aborted. + Replays of previously handled requests yield the + same response as the first execution. Required for DML statements. Ignored for queries. @@ -648,23 +645,21 @@ class ExecuteSqlRequest(proto.Message): ``true``, the request is executed with Spanner Data Boost independent compute resources. - If the field is set to ``true`` but the request does not set + If the field is set to ``true`` but the request doesn't set ``partition_token``, the API returns an ``INVALID_ARGUMENT`` error. last_statement (bool): - Optional. If set to true, this statement - marks the end of the transaction. The - transaction should be committed or aborted after - this statement executes, and attempts to execute - any other requests against this transaction - (including reads and queries) will be rejected. - - For DML statements, setting this option may - cause some error reporting to be deferred until - commit time (e.g. validation of unique - constraints). Given this, successful execution - of a DML statement should not be assumed until a - subsequent Commit call completes successfully. + Optional. If set to ``true``, this statement marks the end + of the transaction. After this statement executes, you must + commit or abort the transaction. Attempts to execute any + other requests against this transaction (including reads and + queries) are rejected. + + For DML statements, setting this option might cause some + error reporting to be deferred until commit time (for + example, validation of unique constraints). Given this, + successful execution of a DML statement shouldn't be assumed + until a subsequent ``Commit`` call completes successfully. """ class QueryMode(proto.Enum): @@ -683,8 +678,8 @@ class QueryMode(proto.Enum): execution statistics, operator level execution statistics along with the results. This has a performance overhead compared to the other - modes. It is not recommended to use this mode - for production traffic. + modes. It isn't recommended to use this mode for + production traffic. WITH_STATS (3): This mode returns the overall (but not operator-level) execution statistics along with @@ -718,7 +713,7 @@ class QueryOptions(proto.Message): default optimizer version for query execution. The list of supported optimizer versions can be queried from - SPANNER_SYS.SUPPORTED_OPTIMIZER_VERSIONS. + ``SPANNER_SYS.SUPPORTED_OPTIMIZER_VERSIONS``. Executing a SQL statement with an invalid optimizer version fails with an ``INVALID_ARGUMENT`` error. @@ -740,13 +735,13 @@ class QueryOptions(proto.Message): use the latest generated statistics package. If not specified, Cloud Spanner uses the statistics package set at the database level options, or the latest package if the - database option is not set. + database option isn't set. The statistics package requested by the query has to be exempt from garbage collection. This can be achieved with the following DDL statement: - :: + .. code:: sql ALTER STATISTICS SET OPTIONS (allow_gc=false) @@ -861,31 +856,29 @@ class ExecuteBatchDmlRequest(proto.Message): Required. A per-transaction sequence number used to identify this request. This field makes each request idempotent such that if the request - is received multiple times, at most one will - succeed. + is received multiple times, at most one + succeeds. The sequence number must be monotonically increasing within the transaction. If a request arrives for the first time with an out-of-order - sequence number, the transaction may be aborted. - Replays of previously handled requests will + sequence number, the transaction might be + aborted. Replays of previously handled requests yield the same response as the first execution. request_options (google.cloud.spanner_v1.types.RequestOptions): Common options for this request. last_statements (bool): - Optional. If set to true, this request marks - the end of the transaction. The transaction - should be committed or aborted after these - statements execute, and attempts to execute any - other requests against this transaction - (including reads and queries) will be rejected. - - Setting this option may cause some error - reporting to be deferred until commit time (e.g. - validation of unique constraints). Given this, - successful execution of statements should not be - assumed until a subsequent Commit call completes - successfully. + Optional. If set to ``true``, this request marks the end of + the transaction. After these statements execute, you must + commit or abort the transaction. Attempts to execute any + other requests against this transaction (including reads and + queries) are rejected. + + Setting this option might cause some error reporting to be + deferred until commit time (for example, validation of + unique constraints). Given this, successful execution of + statements shouldn't be assumed until a subsequent + ``Commit`` call completes successfully. """ class Statement(proto.Message): @@ -909,10 +902,10 @@ class Statement(proto.Message): ``"WHERE id > @msg_id AND id < @msg_id + 100"`` - It is an error to execute a SQL statement with unbound + It's an error to execute a SQL statement with unbound parameters. param_types (MutableMapping[str, google.cloud.spanner_v1.types.Type]): - It is not always possible for Cloud Spanner to infer the + It isn't always possible for Cloud Spanner to infer the right SQL type from a JSON value. For example, values of type ``BYTES`` and values of type ``STRING`` both appear in [params][google.spanner.v1.ExecuteBatchDmlRequest.Statement.params] @@ -991,19 +984,18 @@ class ExecuteBatchDmlResponse(proto.Message): Example 1: - - Request: 5 DML statements, all executed successfully. - - Response: 5 [ResultSet][google.spanner.v1.ResultSet] messages, - with the status ``OK``. + - Request: 5 DML statements, all executed successfully. + - Response: 5 [ResultSet][google.spanner.v1.ResultSet] messages, + with the status ``OK``. Example 2: - - Request: 5 DML statements. The third statement has a syntax - error. - - Response: 2 [ResultSet][google.spanner.v1.ResultSet] messages, - and a syntax error (``INVALID_ARGUMENT``) status. The number of - [ResultSet][google.spanner.v1.ResultSet] messages indicates that - the third statement failed, and the fourth and fifth statements - were not executed. + - Request: 5 DML statements. The third statement has a syntax error. + - Response: 2 [ResultSet][google.spanner.v1.ResultSet] messages, and + a syntax error (``INVALID_ARGUMENT``) status. The number of + [ResultSet][google.spanner.v1.ResultSet] messages indicates that + the third statement failed, and the fourth and fifth statements + were not executed. Attributes: result_sets (MutableSequence[google.cloud.spanner_v1.types.ResultSet]): @@ -1024,13 +1016,12 @@ class ExecuteBatchDmlResponse(proto.Message): is ``OK``. Otherwise, the error status of the first failed statement. precommit_token (google.cloud.spanner_v1.types.MultiplexedSessionPrecommitToken): - Optional. A precommit token will be included if the - read-write transaction is on a multiplexed session. The - precommit token with the highest sequence number from this - transaction attempt should be passed to the + Optional. A precommit token is included if the read-write + transaction is on a multiplexed session. Pass the precommit + token with the highest sequence number from this transaction + attempt should be passed to the [Commit][google.spanner.v1.Spanner.Commit] request for this - transaction. This feature is not yet supported and will - result in an UNIMPLEMENTED error. + transaction. """ result_sets: MutableSequence[result_set.ResultSet] = proto.RepeatedField( @@ -1051,28 +1042,28 @@ class ExecuteBatchDmlResponse(proto.Message): class PartitionOptions(proto.Message): - r"""Options for a PartitionQueryRequest and - PartitionReadRequest. + r"""Options for a ``PartitionQueryRequest`` and + ``PartitionReadRequest``. Attributes: partition_size_bytes (int): - **Note:** This hint is currently ignored by PartitionQuery - and PartitionRead requests. + **Note:** This hint is currently ignored by + ``PartitionQuery`` and ``PartitionRead`` requests. The desired data size for each partition generated. The default for this option is currently 1 GiB. This is only a - hint. The actual size of each partition may be smaller or + hint. The actual size of each partition can be smaller or larger than this size request. max_partitions (int): - **Note:** This hint is currently ignored by PartitionQuery - and PartitionRead requests. + **Note:** This hint is currently ignored by + ``PartitionQuery`` and ``PartitionRead`` requests. The desired maximum number of partitions to return. For - example, this may be set to the number of workers available. - The default for this option is currently 10,000. The maximum - value is currently 200,000. This is only a hint. The actual - number of partitions returned may be smaller or larger than - this maximum count request. + example, this might be set to the number of workers + available. The default for this option is currently 10,000. + The maximum value is currently 200,000. This is only a hint. + The actual number of partitions returned can be smaller or + larger than this maximum count request. """ partition_size_bytes: int = proto.Field( @@ -1094,23 +1085,23 @@ class PartitionQueryRequest(proto.Message): Required. The session used to create the partitions. transaction (google.cloud.spanner_v1.types.TransactionSelector): - Read only snapshot transactions are - supported, read/write and single use + Read-only snapshot transactions are + supported, read and write and single-use transactions are not. sql (str): Required. The query request to generate partitions for. The - request will fail if the query is not root partitionable. - For a query to be root partitionable, it needs to satisfy a - few conditions. For example, if the query execution plan + request fails if the query isn't root partitionable. For a + query to be root partitionable, it needs to satisfy a few + conditions. For example, if the query execution plan contains a distributed union operator, then it must be the first operator in the plan. For more information about other conditions, see `Read data in parallel `__. The query request must not contain DML commands, such as - INSERT, UPDATE, or DELETE. Use - [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] - with a PartitionedDml transaction for large, + ``INSERT``, ``UPDATE``, or ``DELETE``. Use + [``ExecuteStreamingSql``][google.spanner.v1.Spanner.ExecuteStreamingSql] + with a ``PartitionedDml`` transaction for large, partition-friendly DML operations. params (google.protobuf.struct_pb2.Struct): Parameter names and values that bind to placeholders in the @@ -1127,10 +1118,10 @@ class PartitionQueryRequest(proto.Message): ``"WHERE id > @msg_id AND id < @msg_id + 100"`` - It is an error to execute a SQL statement with unbound + It's an error to execute a SQL statement with unbound parameters. param_types (MutableMapping[str, google.cloud.spanner_v1.types.Type]): - It is not always possible for Cloud Spanner to infer the + It isn't always possible for Cloud Spanner to infer the right SQL type from a JSON value. For example, values of type ``BYTES`` and values of type ``STRING`` both appear in [params][google.spanner.v1.PartitionQueryRequest.params] as @@ -1217,8 +1208,8 @@ class PartitionReadRequest(proto.Message): instead names index keys in [index][google.spanner.v1.PartitionReadRequest.index]. - It is not an error for the ``key_set`` to name rows that do - not exist in the database. Read yields nothing for + It isn't an error for the ``key_set`` to name rows that + don't exist in the database. Read yields nothing for nonexistent rows. partition_options (google.cloud.spanner_v1.types.PartitionOptions): Additional options that affect how many @@ -1264,10 +1255,9 @@ class Partition(proto.Message): Attributes: partition_token (bytes): - This token can be passed to Read, - StreamingRead, ExecuteSql, or - ExecuteStreamingSql requests to restrict the - results to those identified by this partition + This token can be passed to ``Read``, ``StreamingRead``, + ``ExecuteSql``, or ``ExecuteStreamingSql`` requests to + restrict the results to those identified by this partition token. """ @@ -1347,16 +1337,15 @@ class ReadRequest(proto.Message): [index][google.spanner.v1.ReadRequest.index] is non-empty). If the [partition_token][google.spanner.v1.ReadRequest.partition_token] - field is not empty, rows will be yielded in an unspecified - order. + field isn't empty, rows are yielded in an unspecified order. - It is not an error for the ``key_set`` to name rows that do - not exist in the database. Read yields nothing for + It isn't an error for the ``key_set`` to name rows that + don't exist in the database. Read yields nothing for nonexistent rows. limit (int): If greater than zero, only the first ``limit`` rows are yielded. If ``limit`` is zero, the default is no limit. A - limit cannot be specified if ``partition_token`` is set. + limit can't be specified if ``partition_token`` is set. resume_token (bytes): If this request is resuming a previously interrupted read, ``resume_token`` should be copied from the last @@ -1366,8 +1355,8 @@ class ReadRequest(proto.Message): request parameters must exactly match the request that yielded this token. partition_token (bytes): - If present, results will be restricted to the specified - partition previously created using PartitionRead(). There + If present, results are restricted to the specified + partition previously created using ``PartitionRead``. There must be an exact match for the values of fields common to this message and the PartitionReadRequest message used to create this partition_token. @@ -1380,19 +1369,19 @@ class ReadRequest(proto.Message): ``true``, the request is executed with Spanner Data Boost independent compute resources. - If the field is set to ``true`` but the request does not set + If the field is set to ``true`` but the request doesn't set ``partition_token``, the API returns an ``INVALID_ARGUMENT`` error. order_by (google.cloud.spanner_v1.types.ReadRequest.OrderBy): Optional. Order for the returned rows. - By default, Spanner will return result rows in primary key - order except for PartitionRead requests. For applications - that do not require rows to be returned in primary key + By default, Spanner returns result rows in primary key order + except for PartitionRead requests. For applications that + don't require rows to be returned in primary key (``ORDER_BY_PRIMARY_KEY``) order, setting ``ORDER_BY_NO_ORDER`` option allows Spanner to optimize row retrieval, resulting in lower latencies in certain cases - (e.g. bulk point lookups). + (for example, bulk point lookups). lock_hint (google.cloud.spanner_v1.types.ReadRequest.LockHint): Optional. Lock Hint for the request, it can only be used with read-write transactions. @@ -1406,12 +1395,13 @@ class OrderBy(proto.Enum): ORDER_BY_UNSPECIFIED (0): Default value. - ORDER_BY_UNSPECIFIED is equivalent to ORDER_BY_PRIMARY_KEY. + ``ORDER_BY_UNSPECIFIED`` is equivalent to + ``ORDER_BY_PRIMARY_KEY``. ORDER_BY_PRIMARY_KEY (1): Read rows are returned in primary key order. In the event that this option is used in conjunction with - the ``partition_token`` field, the API will return an + the ``partition_token`` field, the API returns an ``INVALID_ARGUMENT`` error. ORDER_BY_NO_ORDER (2): Read rows are returned in any order. @@ -1427,7 +1417,8 @@ class LockHint(proto.Enum): LOCK_HINT_UNSPECIFIED (0): Default value. - LOCK_HINT_UNSPECIFIED is equivalent to LOCK_HINT_SHARED. + ``LOCK_HINT_UNSPECIFIED`` is equivalent to + ``LOCK_HINT_SHARED``. LOCK_HINT_SHARED (1): Acquire shared locks. @@ -1460,9 +1451,9 @@ class LockHint(proto.Enum): turn to acquire the lock and avoids getting into deadlock situations. - Because the exclusive lock hint is just a hint, it should - not be considered equivalent to a mutex. In other words, you - should not use Spanner exclusive locks as a mutual exclusion + Because the exclusive lock hint is just a hint, it shouldn't + be considered equivalent to a mutex. In other words, you + shouldn't use Spanner exclusive locks as a mutual exclusion mechanism for the execution of code outside of Spanner. **Note:** Request exclusive locks judiciously because they @@ -1553,19 +1544,17 @@ class BeginTransactionRequest(proto.Message): Required. Options for the new transaction. request_options (google.cloud.spanner_v1.types.RequestOptions): Common options for this request. Priority is ignored for - this request. Setting the priority in this request_options - struct will not do anything. To set the priority for a - transaction, set it on the reads and writes that are part of - this transaction instead. + this request. Setting the priority in this + ``request_options`` struct doesn't do anything. To set the + priority for a transaction, set it on the reads and writes + that are part of this transaction instead. mutation_key (google.cloud.spanner_v1.types.Mutation): Optional. Required for read-write transactions on a multiplexed session that - commit mutations but do not perform any reads or - queries. Clients should randomly select one of - the mutations from the mutation set and send it - as a part of this request. - This feature is not yet supported and will - result in an UNIMPLEMENTED error. + commit mutations but don't perform any reads or + queries. You must randomly select one of the + mutations from the mutation set and send it as a + part of this request. """ session: str = proto.Field( @@ -1613,8 +1602,8 @@ class CommitRequest(proto.Message): with a temporary transaction is non-idempotent. That is, if the ``CommitRequest`` is sent to Cloud Spanner more than once (for instance, due to retries in the application, or in - the transport library), it is possible that the mutations - are executed more than once. If this is undesirable, use + the transport library), it's possible that the mutations are + executed more than once. If this is undesirable, use [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction] and [Commit][google.spanner.v1.Spanner.Commit] instead. @@ -1625,29 +1614,26 @@ class CommitRequest(proto.Message): atomically, in the order they appear in this list. return_commit_stats (bool): - If ``true``, then statistics related to the transaction will - be included in the + If ``true``, then statistics related to the transaction is + included in the [CommitResponse][google.spanner.v1.CommitResponse.commit_stats]. Default value is ``false``. max_commit_delay (google.protobuf.duration_pb2.Duration): Optional. The amount of latency this request - is willing to incur in order to improve - throughput. If this field is not set, Spanner + is configured to incur in order to improve + throughput. If this field isn't set, Spanner assumes requests are relatively latency sensitive and automatically determines an - appropriate delay time. You can specify a - batching delay value between 0 and 500 ms. + appropriate delay time. You can specify a commit + delay value between 0 and 500 ms. request_options (google.cloud.spanner_v1.types.RequestOptions): Common options for this request. precommit_token (google.cloud.spanner_v1.types.MultiplexedSessionPrecommitToken): - Optional. If the read-write transaction was - executed on a multiplexed session, the precommit - token with the highest sequence number received - in this transaction attempt, should be included - here. Failing to do so will result in a - FailedPrecondition error. - This feature is not yet supported and will - result in an UNIMPLEMENTED error. + Optional. If the read-write transaction was executed on a + multiplexed session, then you must include the precommit + token with the highest sequence number received in this + transaction attempt. Failing to do so results in a + ``FailedPrecondition`` error. """ session: str = proto.Field( @@ -1725,22 +1711,11 @@ class BatchWriteRequest(proto.Message): Required. The groups of mutations to be applied. exclude_txn_from_change_streams (bool): - Optional. When ``exclude_txn_from_change_streams`` is set to - ``true``: - - - Mutations from all transactions in this batch write - operation will not be recorded in change streams with DDL - option ``allow_txn_exclusion=true`` that are tracking - columns modified by these transactions. - - Mutations from all transactions in this batch write - operation will be recorded in change streams with DDL - option ``allow_txn_exclusion=false or not set`` that are - tracking columns modified by these transactions. - - When ``exclude_txn_from_change_streams`` is set to ``false`` - or not set, mutations from all transactions in this batch - write operation will be recorded in all change streams that - are tracking columns modified by these transactions. + Optional. If you don't set the + ``exclude_txn_from_change_streams`` option or if it's set to + ``false``, then any change streams monitoring columns + modified by transactions will capture the updates made + within that transaction. """ class MutationGroup(proto.Message): diff --git a/google/cloud/spanner_v1/types/transaction.py b/google/cloud/spanner_v1/types/transaction.py index 9291501c21..447c310548 100644 --- a/google/cloud/spanner_v1/types/transaction.py +++ b/google/cloud/spanner_v1/types/transaction.py @@ -75,13 +75,13 @@ class TransactionOptions(proto.Message): it prevents read or write transactions from being tracked in change streams. - - If the DDL option ``allow_txn_exclusion`` is set to - ``true``, then the updates made within this transaction - aren't recorded in the change stream. + - If the DDL option ``allow_txn_exclusion`` is set to + ``true``, then the updates made within this transaction + aren't recorded in the change stream. - - If you don't set the DDL option ``allow_txn_exclusion`` - or if it's set to ``false``, then the updates made within - this transaction are recorded in the change stream. + - If you don't set the DDL option ``allow_txn_exclusion`` or + if it's set to ``false``, then the updates made within + this transaction are recorded in the change stream. When ``exclude_txn_from_change_streams`` is set to ``false`` or not set, modifications from this transaction are recorded @@ -106,17 +106,15 @@ class IsolationLevel(proto.Enum): If the value is not specified, the ``SERIALIZABLE`` isolation level is used. SERIALIZABLE (1): - All transactions appear as if they executed - in a serial order, even if some of the reads, - writes, and other operations of distinct - transactions actually occurred in parallel. - Spanner assigns commit timestamps that reflect - the order of committed transactions to implement - this property. Spanner offers a stronger - guarantee than serializability called external - consistency. For further details, please refer - to - https://cloud.google.com/spanner/docs/true-time-external-consistency#serializability. + All transactions appear as if they executed in a serial + order, even if some of the reads, writes, and other + operations of distinct transactions actually occurred in + parallel. Spanner assigns commit timestamps that reflect the + order of committed transactions to implement this property. + Spanner offers a stronger guarantee than serializability + called external consistency. For more information, see + `TrueTime and external + consistency `__. REPEATABLE_READ (2): All reads performed during the transaction observe a consistent snapshot of the database, and the transaction is @@ -159,22 +157,22 @@ class ReadLockMode(proto.Enum): READ_LOCK_MODE_UNSPECIFIED (0): Default value. - - If isolation level is - [REPEATABLE_READ][google.spanner.v1.TransactionOptions.IsolationLevel.REPEATABLE_READ], - then it is an error to specify ``read_lock_mode``. - Locking semantics default to ``OPTIMISTIC``. No - validation checks are done for reads, except to validate - that the data that was served at the snapshot time is - unchanged at commit time in the following cases: - - 1. reads done as part of queries that use - ``SELECT FOR UPDATE`` - 2. reads done as part of statements with a - ``LOCK_SCANNED_RANGES`` hint - 3. reads done as part of DML statements - - - At all other isolation levels, if ``read_lock_mode`` is - the default value, then pessimistic read locks are used. + - If isolation level is + [REPEATABLE_READ][google.spanner.v1.TransactionOptions.IsolationLevel.REPEATABLE_READ], + then it is an error to specify ``read_lock_mode``. Locking + semantics default to ``OPTIMISTIC``. No validation checks + are done for reads, except to validate that the data that + was served at the snapshot time is unchanged at commit + time in the following cases: + + 1. reads done as part of queries that use + ``SELECT FOR UPDATE`` + 2. reads done as part of statements with a + ``LOCK_SCANNED_RANGES`` hint + 3. reads done as part of DML statements + + - At all other isolation levels, if ``read_lock_mode`` is + the default value, then pessimistic read locks are used. PESSIMISTIC (1): Pessimistic lock mode. diff --git a/google/cloud/spanner_v1/types/type.py b/google/cloud/spanner_v1/types/type.py index 8996b67388..d6d516569e 100644 --- a/google/cloud/spanner_v1/types/type.py +++ b/google/cloud/spanner_v1/types/type.py @@ -91,12 +91,12 @@ class TypeCode(proto.Enum): 7159. The following rules are applied when parsing JSON input: - - Whitespace characters are not preserved. - - If a JSON object has duplicate keys, only the first key - is preserved. - - Members of a JSON object are not guaranteed to have their - order preserved. - - JSON array elements will have their order preserved. + - Whitespace characters are not preserved. + - If a JSON object has duplicate keys, only the first key is + preserved. + - Members of a JSON object are not guaranteed to have their + order preserved. + - JSON array elements will have their order preserved. PROTO (13): Encoded as a base64-encoded ``string``, as described in RFC 4648, section 4. diff --git a/samples/generated_samples/snippet_metadata_google.spanner.admin.database.v1.json b/samples/generated_samples/snippet_metadata_google.spanner.admin.database.v1.json index e6f99e7e7d..f6bcc86bf4 100644 --- a/samples/generated_samples/snippet_metadata_google.spanner.admin.database.v1.json +++ b/samples/generated_samples/snippet_metadata_google.spanner.admin.database.v1.json @@ -8,7 +8,7 @@ ], "language": "PYTHON", "name": "google-cloud-spanner-admin-database", - "version": "3.57.0" + "version": "0.1.0" }, "snippets": [ { diff --git a/samples/generated_samples/snippet_metadata_google.spanner.admin.instance.v1.json b/samples/generated_samples/snippet_metadata_google.spanner.admin.instance.v1.json index af6c65815a..06d6291f45 100644 --- a/samples/generated_samples/snippet_metadata_google.spanner.admin.instance.v1.json +++ b/samples/generated_samples/snippet_metadata_google.spanner.admin.instance.v1.json @@ -8,7 +8,7 @@ ], "language": "PYTHON", "name": "google-cloud-spanner-admin-instance", - "version": "3.57.0" + "version": "0.1.0" }, "snippets": [ { diff --git a/samples/generated_samples/snippet_metadata_google.spanner.v1.json b/samples/generated_samples/snippet_metadata_google.spanner.v1.json index 0c303b9ff0..727606e51f 100644 --- a/samples/generated_samples/snippet_metadata_google.spanner.v1.json +++ b/samples/generated_samples/snippet_metadata_google.spanner.v1.json @@ -8,7 +8,7 @@ ], "language": "PYTHON", "name": "google-cloud-spanner", - "version": "3.57.0" + "version": "0.1.0" }, "snippets": [ { diff --git a/testing/constraints-3.8.txt b/testing/constraints-3.8.txt new file mode 100644 index 0000000000..ad3f0fa58e --- /dev/null +++ b/testing/constraints-3.8.txt @@ -0,0 +1,7 @@ +# -*- coding: utf-8 -*- +# This constraints file is required for unit tests. +# List all library dependencies and extras in this file. +google-api-core +proto-plus +protobuf +grpc-google-iam-v1