feat: [google-cloud-bigquery-reservation] Add Reservation.max_slots field to Reservation proto, indicating the total max number of slots this reservation can use up to (#14243)

BEGIN_COMMIT_OVERRIDE
feat: Add Reservation.max_slots field to Reservation proto, indicating
the total max number of slots this reservation can use up to
feat: Add Reservation.scaling_mode field and its corresponding enum
message ScalingMode. This field should be used together with
Reservation.max_slots
END_COMMIT_OVERRIDE

- [ ] Regenerate this pull request now.

feat: Add Reservation.scaling_mode field and its corresponding enum
message ScalingMode. This field should be used together with
Reservation.max_slots
PiperOrigin-RevId: 795606766

Source-Link:
googleapis/googleapis@6388d14

Source-Link:
googleapis/googleapis-gen@9fc20ac
Copy-Tag:
eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLWJpZ3F1ZXJ5LXJlc2VydmF0aW9uLy5Pd2xCb3QueWFtbCIsImgiOiI5ZmMyMGFjMDdkZDFkNGUxYzMxYzViNTZiYzEwYzlmZDMzYzU1ZjkwIn0=

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
Co-authored-by: ohmayr <[email protected]>

Author: gcf-owl-bot[bot]

packages/google-cloud-bigquery-reservation/google/cloud/bigquery_reservation/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "1.17.2"  # {x-release-please-version}
+__version__ = "0.0.0"  # {x-release-please-version}

packages/google-cloud-bigquery-reservation/google/cloud/bigquery_reservation_v1/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "1.17.2"  # {x-release-please-version}
+__version__ = "0.0.0"  # {x-release-please-version}

packages/google-cloud-bigquery-reservation/google/cloud/bigquery_reservation_v1/types/reservation.py

@@ -90,6 +90,9 @@ class Reservation(proto.Message):
     r"""A reservation is a mechanism used to guarantee slots to
     users.
 
+
+    .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
     Attributes:
         name (str):
             The resource name of the reservation, e.g.,
@@ -177,6 +180,60 @@ class Reservation(proto.Message):
             only during the failover reservation's creation.
             All billing charges for the failover reservation
             will be applied to this location.
+        max_slots (int):
+            Optional. The overall max slots for the reservation,
+            covering slot_capacity (baseline), idle slots (if
+            ignore_idle_slots is false) and scaled slots. If present,
+            the reservation won't use more than the specified number of
+            slots, even if there is demand and supply (from idle slots).
+            NOTE: capping a reservation's idle slot usage is best effort
+            and its usage may exceed the max_slots value. However, in
+            terms of autoscale.current_slots (which accounts for the
+            additional added slots), it will never exceed the max_slots
+            - baseline.
+
+            This field must be set together with the scaling_mode enum
+            value.
+
+            If the max_slots and scaling_mode are set, the autoscale or
+            autoscale.max_slots field must be unset. However, the
+            autoscale field may still be in the output. The
+            autopscale.max_slots will always show as 0 and the
+            autoscaler.current_slots will represent the current slots
+            from autoscaler excluding idle slots. For example, if the
+            max_slots is 1000 and scaling_mode is AUTOSCALE_ONLY, then
+            in the output, the autoscaler.max_slots will be 0 and the
+            autoscaler.current_slots may be any value between 0 and
+            1000.
+
+            If the max_slots is 1000, scaling_mode is ALL_SLOTS, the
+            baseline is 100 and idle slots usage is 200, then in the
+            output, the autoscaler.max_slots will be 0 and the
+            autoscaler.current_slots will not be higher than 700.
+
+            If the max_slots is 1000, scaling_mode is IDLE_SLOTS_ONLY,
+            then in the output, the autoscaler field will be null.
+
+            If the max_slots and scaling_mode are set, then the
+            ignore_idle_slots field must be aligned with the
+            scaling_mode enum value.(See details in ScalingMode
+            comments).
+
+            Please note, the max_slots is for user to manage the part of
+            slots greater than the baseline. Therefore, we don't allow
+            users to set max_slots smaller or equal to the baseline as
+            it will not be meaningful. If the field is present and
+            slot_capacity>=max_slots.
+
+            Please note that if max_slots is set to 0, we will treat it
+            as unset. Customers can set max_slots to 0 and set
+            scaling_mode to SCALING_MODE_UNSPECIFIED to disable the
+            max_slots feature.
+
+            This field is a member of `oneof`_ ``_max_slots``.
+        scaling_mode (google.cloud.bigquery_reservation_v1.types.Reservation.ScalingMode):
+            Optional. The scaling mode for the reservation. If the field
+            is present but max_slots is not present.
         replication_status (google.cloud.bigquery_reservation_v1.types.Reservation.ReplicationStatus):
             Output only. The Disaster Recovery(DR)
             replication status of the reservation. This is
@@ -192,6 +249,73 @@ class Reservation(proto.Message):
             reservation have succeeded.
     """
 
+    class ScalingMode(proto.Enum):
+        r"""The scaling mode for the reservation. This enum determines
+        how the reservation scales up and down.
+
+        Values:
+            SCALING_MODE_UNSPECIFIED (0):
+                Default value of ScalingMode.
+            AUTOSCALE_ONLY (1):
+                The reservation will scale up only using slots from
+                autoscaling. It will not use any idle slots even if there
+                may be some available. The upper limit that autoscaling can
+                scale up to will be max_slots - baseline. For example, if
+                max_slots is 1000, baseline is 200 and customer sets
+                ScalingMode to AUTOSCALE_ONLY, then autoscalerg will scale
+                up to 800 slots and no idle slots will be used.
+
+                Please note, in this mode, the ignore_idle_slots field must
+                be set to true.
+            IDLE_SLOTS_ONLY (2):
+                The reservation will scale up using only idle slots
+                contributed by other reservations or from unassigned
+                commitments. If no idle slots are available it will not
+                scale up further. If the idle slots which it is using are
+                reclaimed by the contributing reservation(s) it may be
+                forced to scale down. The max idle slots the reservation can
+                be max_slots - baseline capacity. For example, if max_slots
+                is 1000, baseline is 200 and customer sets ScalingMode to
+                IDLE_SLOTS_ONLY,
+
+                1. if there are 1000 idle slots available in other
+                   reservations, the reservation will scale up to 1000 slots
+                   with 200 baseline and 800 idle slots.
+                2. if there are 500 idle slots available in other
+                   reservations, the reservation will scale up to 700 slots
+                   with 200 baseline and 300 idle slots. Please note, in
+                   this mode, the reservation might not be able to scale up
+                   to max_slots.
+
+                Please note, in this mode, the ignore_idle_slots field must
+                be set to false.
+            ALL_SLOTS (3):
+                The reservation will scale up using all slots available to
+                it. It will use idle slots contributed by other reservations
+                or from unassigned commitments first. If no idle slots are
+                available it will scale up using autoscaling. For example,
+                if max_slots is 1000, baseline is 200 and customer sets
+                ScalingMode to ALL_SLOTS,
+
+                1. if there are 800 idle slots available in other
+                   reservations, the reservation will scale up to 1000 slots
+                   with 200 baseline and 800 idle slots.
+                2. if there are 500 idle slots available in other
+                   reservations, the reservation will scale up to 1000 slots
+                   with 200 baseline, 500 idle slots and 300 autoscaling
+                   slots.
+                3. if there are no idle slots available in other
+                   reservations, it will scale up to 1000 slots with 200
+                   baseline and 800 autoscaling slots.
+
+                Please note, in this mode, the ignore_idle_slots field must
+                be set to false.
+        """
+        SCALING_MODE_UNSPECIFIED = 0
+        AUTOSCALE_ONLY = 1
+        IDLE_SLOTS_ONLY = 2
+        ALL_SLOTS = 3
+
     class Autoscale(proto.Message):
         r"""Auto scaling settings.
 
@@ -305,6 +429,16 @@ class ReplicationStatus(proto.Message):
         proto.STRING,
         number=20,
     )
+    max_slots: int = proto.Field(
+        proto.INT64,
+        number=21,
+        optional=True,
+    )
+    scaling_mode: ScalingMode = proto.Field(
+        proto.ENUM,
+        number=22,
+        enum=ScalingMode,
+    )
     replication_status: ReplicationStatus = proto.Field(
         proto.MESSAGE,
         number=24,

packages/google-cloud-bigquery-reservation/samples/generated_samples/snippet_metadata_google.cloud.bigquery.reservation.v1.json

@@ -8,7 +8,7 @@
     ],
     "language": "PYTHON",
     "name": "google-cloud-bigquery-reservation",
-    "version": "1.17.2"
+    "version": "0.1.0"
   },
   "snippets": [
     {