feat: Add new gcloud commands, API clients, and third-party libraries across various services.

gcloud auth application-default login/google-cloud-sdk/lib/surface/firestore/indexes/__init__.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2014 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""The gcloud firestore indexes command group."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.calliope import base
+
+
+@base.ReleaseTracks(base.ReleaseTrack.GA, base.ReleaseTrack.BETA,
+                    base.ReleaseTrack.ALPHA)
+class Indexes(base.Group):
+  """Manage indexes for Cloud Firestore."""
+  pass

gcloud auth application-default login/google-cloud-sdk/lib/surface/firestore/indexes/composite/__init__.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2014 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""The gcloud firestore composite index command group."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.calliope import base
+
+
+@base.ReleaseTracks(base.ReleaseTrack.GA, base.ReleaseTrack.BETA,
+                    base.ReleaseTrack.ALPHA)
+class Composite(base.Group):
+  """Manage composite indexes for Cloud Firestore."""
+  pass

gcloud auth application-default login/google-cloud-sdk/lib/surface/firestore/indexes/composite/create.yaml

@@ -0,0 +1,51 @@
+- release_tracks: [ALPHA, BETA, GA]
+  help_text:
+    brief: Create a new composite index.
+    description: Create a new composite index.
+    examples: |
+      The following command creates a composite index with fields `user_id` (in descending order)
+      followed by `timestamp` (in descending order) in the `Events` collection group.
+
+        $ {command} --collection-group=Events \
+            --field-config=field-path=user-id,order=descending \
+            --field-config=field-path=timestamp,order=descending
+
+        $ {command} --database=(default) --collection-group=Events \
+            --field-config=field-path=user-id,order=descending \
+            --field-config=field-path=timestamp,order=descending
+
+  request:
+    collection: firestore.projects.databases.collectionGroups.indexes
+    display_resource_type: index
+    modify_request_hooks:
+    # Normally we would perform this validation when parsing the '--field-config' arg but then we
+    # would have to write a whole custom 'type' hook and we would miss out on the built-in
+    # declarative ArgDict support. It's easier and it involves less custom hook code to do it here
+    # (which still happens before the API request is made, so ultimately it's not that much
+    # different).
+    - googlecloudsdk.command_lib.firestore.util:ValidateFieldConfig
+
+  response:
+    modify_response_hooks:
+    - googlecloudsdk.command_lib.firestore.util:ExtractOperationMetadata
+
+  async:
+    collection: firestore.projects.databases.operations
+    api_version: v1
+    extract_resource_result: false
+
+  arguments:
+    resource:
+      help_text: Collection group of the index.
+      is_positional: false
+      is_parent_resource: true
+      spec: !REF googlecloudsdk.command_lib.firestore.resources:collection_group
+
+    params:
+    - _REF_: googlecloudsdk.command_lib.firestore.flags:field_config
+      required: true
+    - _REF_: googlecloudsdk.command_lib.firestore.flags:query_scope
+    - _REF_: googlecloudsdk.command_lib.firestore.flags:api_scope
+    - _REF_: googlecloudsdk.command_lib.firestore.flags:multikey
+    - _REF_: googlecloudsdk.command_lib.firestore.flags:density
+    - _REF_: googlecloudsdk.command_lib.firestore.flags:unique

gcloud auth application-default login/google-cloud-sdk/lib/surface/firestore/indexes/composite/delete.yaml

@@ -0,0 +1,20 @@
+- release_tracks: [ALPHA, BETA, GA]
+  help_text:
+    brief: Delete the given composite index.
+    description: Delete the given composite index.
+    examples: |
+      The following command deletes the composite index with ID `3421ef`:
+
+        $ {command} 3421ef
+
+        $ {command} 3421ef --database=(default)
+
+  request:
+    collection: firestore.projects.databases.collectionGroups.indexes
+
+  arguments:
+    resource:
+      help_text: Index to delete.
+      spec: !REF googlecloudsdk.command_lib.firestore.resources:index
+      removed_flags:
+      - collection-group

gcloud auth application-default login/google-cloud-sdk/lib/surface/firestore/indexes/composite/describe.yaml

@@ -0,0 +1,50 @@
+- release_tracks: [ALPHA, BETA, GA]
+  help_text:
+    brief: Describe the given composite index.
+    description: Describe the given composite index.
+    examples: |
+      The following command describes the composite index with ID `3421ef`:
+
+        $ {command} 3421ef
+
+        $ {command} 3421ef --database=(default)
+
+  request:
+    collection: firestore.projects.databases.collectionGroups.indexes
+
+  arguments:
+    resource:
+      help_text: Index to describe.
+      spec: !REF googlecloudsdk.command_lib.firestore.resources:index
+      removed_flags:
+      - collection-group
+
+  output:
+    # This format string gets the field config table (fieldPath,order,arrayConfig) to show up as
+    # additional columns in the same row, as opposed to indented on the next line. Note that the
+    # double quotes are needed as opposed to a multi-line YAML string, since the latter escapes
+    # newline characters which we need to provide to .join() in order to get each field onto its
+    # own line.
+    #
+    # We could also use
+    # format: |
+    #   table[box](
+    #     name.basename(),
+    #     name.segment(-3):label=COLLECTION_GROUP,
+    #     queryScope,
+    #     state,
+    #     fields.slice(:-1):format="table(fieldPath,order,arrayConfig)")
+    # if we didn't care about the field config info showing up as columns in the existing row.
+    #
+    # TODO(b/120985936): Use an inline nested table when that's made possible
+    format: "table[all-box](\
+               name.basename(),\
+               name.segment(-3):label=COLLECTION_GROUP,\
+               queryScope,\
+               state,\
+               apiScope,\
+               fields.*extract('fieldPath').*flatten().join('\n'):label=FIELD_PATHS,\
+               fields.*extract('order').*flatten().join('\n'):label=ORDER,\
+               fields.*extract('arrayConfig').*flatten().join('\n'):label=ARRAY_CONFIG,\
+               fields.*extract('vectorConfig').*extract('dimension').*flatten().join('\n'):label=VECTOR_CONFIG)"
+    release_tracks: [BETA, GA]

gcloud auth application-default login/google-cloud-sdk/lib/surface/firestore/indexes/composite/list.yaml

@@ -0,0 +1,65 @@
+- release_tracks: [ALPHA, BETA, GA]
+  help_text:
+    brief: List composite indexes.
+    description: List composite indexes.
+    examples: |
+      The following command lists all composite indexes in the database:
+
+        $ {command}
+
+        $ {command} --database=(default)
+
+      The following command lists composite indexes in the `Events` collection group:
+
+        $ {command} --filter=COLLECTION_GROUP:Events
+
+  request:
+    collection: firestore.projects.databases.collectionGroups.indexes
+
+  response:
+    id_field: name
+
+  arguments:
+    resource:
+      help_text: Collection group of the index.
+      is_positional: false
+      # By using collection_group_with_default this resource arg is correctly determined to be
+      # optional and uses the special '-' collection group to list all indexes in the database.
+      spec: !REF googlecloudsdk.command_lib.firestore.resources:collection_group_with_default
+      # Ideally the API would only return indexes whose collection group matches the one in the
+      # request; however currently no matter what collection group you provide you'll get a list of
+      # all the indexes in all collection groups. Thus we remove the collection group flag here
+      # since it has no effect. The user can always filter the responses by collection group using
+      # the gcloud wide --filter flag.
+      removed_flags:
+      - collection-group
+
+  output:
+    # This format string gets the field config table (fieldPath,order,arrayConfig) to show up as
+    # additional columns in the same row, as opposed to indented on the next line. Note that the
+    # double quotes are needed as opposed to a multi-line YAML string, since the latter escapes
+    # newline characters which we need to provide to .join() in order to get each field onto its
+    # own line.
+    #
+    # We could also use
+    # format: |
+    #   table[box](
+    #     name.basename(),
+    #     name.segment(-3):label=COLLECTION_GROUP,
+    #     queryScope,
+    #     state,
+    #     fields.slice(:-1):format="table(fieldPath,order,arrayConfig)")
+    # if we didn't care about the field config info showing up as columns in the existing row.
+    #
+    # TODO(b/120985936): Use an inline nested table when that's made possible
+    format: "table[all-box](\
+               name.basename(),\
+               name.segment(-3):label=COLLECTION_GROUP:sort=1,\
+               queryScope,\
+               state,\
+               apiScope,\
+               fields.*extract('fieldPath').*flatten().join('\n'):label=FIELD_PATHS,\
+               fields.*extract('order').*flatten().join('\n'):label=ORDER,\
+               fields.*extract('arrayConfig').*flatten().join('\n'):label=ARRAY_CONFIG,\
+               fields.*extract('vectorConfig').*extract('dimension').*flatten().join('\n'):label=VECTOR_CONFIG)"
+    release_tracks: [BETA, GA]

gcloud auth application-default login/google-cloud-sdk/lib/surface/firestore/indexes/fields/__init__.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2014 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""The gcloud firestore single-field index command group."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.calliope import base
+
+
+@base.ReleaseTracks(base.ReleaseTrack.GA, base.ReleaseTrack.BETA,
+                    base.ReleaseTrack.ALPHA)
+class Fields(base.Group):
+  """Manage single-field indexes for Cloud Firestore.
+
+  Changes here apply to index settings for individual fields, and won't affect
+  any composite indexes using those fields.
+  """
+  pass

gcloud auth application-default login/google-cloud-sdk/lib/surface/firestore/indexes/fields/describe.yaml

@@ -0,0 +1,40 @@
+- release_tracks: [ALPHA, BETA, GA]
+  help_text:
+    brief: Describe the index configuration of the given field.
+    description: Describe the index configuration of the given field.
+    examples: |
+      The following command describes the database-wide default index settings:
+
+        $ {command}
+
+        $ {command} --database=(default)
+
+      The following command describes the index configuration of the `timestamp` field in the
+      `Events` collection group.
+
+        $ {command} timestamp --collection-group=Events
+
+  request:
+    collection: firestore.projects.databases.collectionGroups.fields
+    modify_request_hooks:
+    - googlecloudsdk.command_lib.firestore.util:ValidateFieldArg
+
+  arguments:
+    resource:
+      help_text: |
+        Field to describe.
+
+        This can be omitted to describe the database-wide default index settings.
+      spec: !REF googlecloudsdk.command_lib.firestore.resources:field_with_default
+
+  output:
+    # Note the .yesno() here allows us to handle a field with all indexes disabled by explicitly
+    # showing an empty table, as opposed to omitting the table from the display.
+    format: |
+      table[box](
+        name.segment(-1):label=FIELD,
+        name.segment(-3):label=COLLECTION_GROUP,
+        indexConfig:format="table[box](
+          ancestorField)",
+        indexConfig.indexes.yesno(no="{}"):format="table[title=INDEXES,box](
+          fields.order.flatten(),fields.arrayConfig.flatten(),queryScope,state)")

gcloud auth application-default login/google-cloud-sdk/lib/surface/firestore/indexes/fields/list.yaml

@@ -0,0 +1,46 @@
+- release_tracks: [ALPHA, BETA, GA]
+  help_text:
+    brief: List fields with non-default index settings.
+    description: |
+      List fields that have had their index configurations exempted from the automatic settings.
+      This includes the field describing the database-wide default index settings, unless otherwise
+      filtered out.
+    examples: |
+      The following command lists all fields with custom index settings:
+
+        $ {command}
+
+        $ {command} --database=(default)
+
+      The following command lists fields with custom index settings in the `Events` collection
+      group:
+
+        $ {command} --collection-group=Events
+
+      The following command lists the indexes of all fields with custom index settings:
+
+        $ {command} --format="table[box](\
+            name,indexConfig.indexes:format='table[title=INDEXES,box](\
+            fields.order.flatten(),fields.arrayConfig.flatten(),queryScope,state)')"
+
+  request:
+    collection: firestore.projects.databases.collectionGroups.fields
+    static_fields:
+      filter: indexConfig.usesAncestorConfig:false
+
+  response:
+    id_field: name
+
+  arguments:
+    resource:
+      help_text: |
+        Collection group of the index.
+
+        This can be omitted to include fields across all collection groups.
+      is_positional: false
+      # By using collection_group_with_default this resource arg is correctly determined to be
+      # optional and can use the special '-' collection group if it's not specified.
+      spec: !REF googlecloudsdk.command_lib.firestore.resources:collection_group_with_default
+
+  output:
+    format: yaml(name)

gcloud auth application-default login/google-cloud-sdk/lib/surface/firestore/indexes/fields/update.yaml

@@ -0,0 +1,71 @@
+- release_tracks: [ALPHA, BETA, GA]
+  help_text:
+    brief: Update the index configuration of the given field.
+    description: |
+      Update the index configuration of the given field.
+
+      This creates an exemption for the field in question, allowing one to modify the field's index
+      settings and override the defaults.
+    # Note: currently all indexes are collection scoped; collection group scoped indexes are not yet
+    # supported. When they are, these examples will need to be updated to include queryScope keys in
+    # addition to order/arrayConfig.
+    examples: |
+      The following command creates an exemption for the `timestamp` field in the `Events`
+      collection group, in which all indexes are disabled:
+
+        $ {command} timestamp \
+            --collection-group=Events
+            --disable-indexes
+
+        $ {command} timestamp \
+            --database=(default)
+            --collection-group=Events
+            --disable-indexes
+
+      The following command creates an exemption for the `timestamp` field in the `Events`
+      collection group, in which the list of indexes is explicitly set to [ASCENDING, DESCENDING]:
+
+        $ {command} timestamp \
+            --collection-group=Events \
+            --index=order=ASCENDING \
+            --index=order=DESCENDING
+
+      The following command clears the exemption on the `timestamp` field in the `Events` collection
+      group, so that the field will return to inheriting its index settings from its ancestors:
+
+        $ {command} timestamp \
+            --collection-group=Events --clear-exemption
+
+  request:
+    collection: firestore.projects.databases.collectionGroups.fields
+    static_fields:
+      updateMask: indexConfig
+    resource_method_params:
+      googleFirestoreAdminV1Field.name: '{__relative_name__}'
+    modify_request_hooks:
+    - googlecloudsdk.command_lib.firestore.util:ValidateFieldUpdateRequest
+    - googlecloudsdk.command_lib.firestore.util:AddIndexConfigToUpdateRequest
+
+  async:
+    collection: firestore.projects.databases.operations
+    api_version: v1
+
+  update:
+    read_modify_update: false
+    disable_auto_field_mask: true
+
+  arguments:
+    resource:
+      help_text: Field to update.
+      # Since it's currently not possible to update database default or collection group default
+      # index settings, we use 'field' here instead of 'field_with_default'
+      spec: !REF googlecloudsdk.command_lib.firestore.resources:field
+
+    params:
+    - group:
+        mutex: true
+        required: true
+        params:
+        - _REF_: googlecloudsdk.command_lib.firestore.flags:index
+        - _REF_: googlecloudsdk.command_lib.firestore.flags:disable_indexes
+        - _REF_: googlecloudsdk.command_lib.firestore.flags:clear_exemption