feat: You can now configure listings for multiple regions for shared datasets and linked dataset replicas in BigQuery sharing

Google APIs · copybara-github · commit b49565973e49 · 2025-09-02T11:10:44.000-07:00
docs:Add new category GOOGLE EARTH ENGINE and Increase limit of max Categories per Listing to 5 For more information, see [Create a listing](https://cloud.google.com/bigquery/docs/analytics-hub-manage-listings#create_a_listing). This feature is in [preview](https://cloud.google.com/products#product-launch-stages) PiperOrigin-RevId: 802216997
diff --git a/google/cloud/bigquery/analyticshub/v1/analyticshub.proto b/google/cloud/bigquery/analyticshub/v1/analyticshub.proto
@@ -315,6 +315,70 @@ service AnalyticsHubService {
       }
     };
   }
+
+  // Creates a new QueryTemplate
+  rpc CreateQueryTemplate(CreateQueryTemplateRequest) returns (QueryTemplate) {
+    option (google.api.http) = {
+      post: "/v1/{parent=projects/*/locations/*/dataExchanges/*}/queryTemplates"
+      body: "query_template"
+    };
+    option (google.api.method_signature) =
+        "parent,query_template,query_template_id";
+  }
+
+  // Gets a QueryTemplate
+  rpc GetQueryTemplate(GetQueryTemplateRequest) returns (QueryTemplate) {
+    option (google.api.http) = {
+      get: "/v1/{name=projects/*/locations/*/dataExchanges/*/queryTemplates/*}"
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Lists all QueryTemplates in a given project and location.
+  rpc ListQueryTemplates(ListQueryTemplatesRequest)
+      returns (ListQueryTemplatesResponse) {
+    option (google.api.http) = {
+      get: "/v1/{parent=projects/*/locations/*/dataExchanges/*}/queryTemplates"
+    };
+    option (google.api.method_signature) = "parent";
+  }
+
+  // Updates an existing QueryTemplate
+  rpc UpdateQueryTemplate(UpdateQueryTemplateRequest) returns (QueryTemplate) {
+    option (google.api.http) = {
+      patch: "/v1/{query_template.name=projects/*/locations/*/dataExchanges/*/queryTemplates/*}"
+      body: "query_template"
+    };
+    option (google.api.method_signature) = "query_template,update_mask";
+  }
+
+  // Deletes a query template.
+  rpc DeleteQueryTemplate(DeleteQueryTemplateRequest)
+      returns (google.protobuf.Empty) {
+    option (google.api.http) = {
+      delete: "/v1/{name=projects/*/locations/*/dataExchanges/*/queryTemplates/*}"
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Submits a query template for approval.
+  rpc SubmitQueryTemplate(SubmitQueryTemplateRequest) returns (QueryTemplate) {
+    option (google.api.http) = {
+      post: "/v1/{name=projects/*/locations/*/dataExchanges/*/queryTemplates/*}:submit"
+      body: "*"
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Approves a query template.
+  rpc ApproveQueryTemplate(ApproveQueryTemplateRequest)
+      returns (QueryTemplate) {
+    option (google.api.http) = {
+      post: "/v1/{name=projects/*/locations/*/dataExchanges/*/queryTemplates/*}:approve"
+      body: "*"
+    };
+    option (google.api.method_signature) = "name";
+  }
 }
 
 // Specifies the type of discovery on the discovery page. Note that
@@ -404,6 +468,209 @@ message DataExchange {
       [(google.api.field_behavior) = OPTIONAL];
 }
 
+// A query template is a container for sharing table-valued functions defined by
+// contributors in a data clean room.
+message QueryTemplate {
+  option (google.api.resource) = {
+    type: "analyticshub.googleapis.com/QueryTemplate"
+    pattern: "projects/{project}/locations/{location}/dataExchanges/{data_exchange}/queryTemplates/{query_template}"
+    plural: "queryTemplates"
+    singular: "queryTemplate"
+  };
+
+  // The QueryTemplate lifecycle state.
+  enum State {
+    // Default value. This value is unused.
+    STATE_UNSPECIFIED = 0;
+
+    // The QueryTemplate is in draft state.
+    DRAFTED = 1;
+
+    // The QueryTemplate is in pending state.
+    PENDING = 2;
+
+    // The QueryTemplate is in deleted state.
+    DELETED = 3;
+
+    // The QueryTemplate is in approved state.
+    APPROVED = 4;
+  }
+
+  // Output only. The resource name of the QueryTemplate.
+  // e.g. `projects/myproject/locations/us/dataExchanges/123/queryTemplates/456`
+  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Required. Human-readable display name of the QueryTemplate. The display
+  // name must contain only Unicode letters, numbers (0-9), underscores (_),
+  // dashes (-), spaces ( ), ampersands (&) and can't start or end with spaces.
+  // Default value is an empty string. Max length: 63 bytes.
+  string display_name = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. Short description of the QueryTemplate. The description must not
+  // contain Unicode non-characters and C0 and C1 control codes except tabs
+  // (HT), new lines (LF), carriage returns (CR), and page breaks (FF). Default
+  // value is an empty string. Max length: 2000 bytes.
+  string description = 3 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Will be deprecated.
+  // Email or URL of the primary point of contact of the QueryTemplate.
+  // Max Length: 1000 bytes.
+  string proposer = 4 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Email or URL of the primary point of contact of the
+  // QueryTemplate. Max Length: 1000 bytes.
+  string primary_contact = 10 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Documentation describing the QueryTemplate.
+  string documentation = 5 [(google.api.field_behavior) = OPTIONAL];
+
+  // Output only. The QueryTemplate lifecycle state.
+  State state = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Optional. The routine associated with the QueryTemplate.
+  Routine routine = 7 [(google.api.field_behavior) = OPTIONAL];
+
+  // Output only. Timestamp when the QueryTemplate was created.
+  google.protobuf.Timestamp create_time = 8
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. Timestamp when the QueryTemplate was last modified.
+  google.protobuf.Timestamp update_time = 9
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
+// Represents a bigquery routine.
+message Routine {
+  // Represents the type of a given routine.
+  enum RoutineType {
+    // Default value.
+    ROUTINE_TYPE_UNSPECIFIED = 0;
+
+    // Non-built-in persistent TVF.
+    TABLE_VALUED_FUNCTION = 1;
+  }
+
+  // Required. The type of routine.
+  RoutineType routine_type = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. The definition body of the routine.
+  string definition_body = 2 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Message for creating a QueryTemplate.
+message CreateQueryTemplateRequest {
+  // Required. The parent resource path of the QueryTemplate.
+  // e.g.
+  // `projects/myproject/locations/us/dataExchanges/123/queryTemplates/myQueryTemplate`.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "analyticshub.googleapis.com/DataExchange"
+    }
+  ];
+
+  // Required. The ID of the QueryTemplate to create.
+  // Must contain only Unicode letters, numbers (0-9), underscores (_).
+  // Max length: 100 bytes.
+  string query_template_id = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The QueryTemplate to create.
+  QueryTemplate query_template = 3 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Message for creating a QueryTemplate.
+message GetQueryTemplateRequest {
+  // Required. The parent resource path of the QueryTemplate.
+  // e.g.
+  // `projects/myproject/locations/us/dataExchanges/123/queryTemplates/myqueryTemplate`.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "analyticshub.googleapis.com/QueryTemplate"
+    }
+  ];
+}
+
+// Message for requesting the list of QueryTemplates.
+message ListQueryTemplatesRequest {
+  // Required. The parent resource path of the QueryTemplates.
+  // e.g. `projects/myproject/locations/us/dataExchanges/123`.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "analyticshub.googleapis.com/DataExchange"
+    }
+  ];
+
+  // Optional. The maximum number of results to return in a single response
+  // page. Leverage the page tokens to iterate through the entire collection.
+  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Page token, returned by a previous call, to request the next page
+  // of results.
+  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Message for response to the list of QueryTemplates.
+message ListQueryTemplatesResponse {
+  // The list of QueryTemplates.
+  repeated QueryTemplate query_templates = 1;
+
+  // A token to request the next page of results.
+  string next_page_token = 2;
+}
+
+// Message for updating a QueryTemplate.
+message UpdateQueryTemplateRequest {
+  // Optional. Field mask specifies the fields to update in the query template
+  // resource. The fields specified in the `updateMask` are relative to the
+  // resource and are not a full request.
+  google.protobuf.FieldMask update_mask = 1
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Required. The QueryTemplate to update.
+  QueryTemplate query_template = 2 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Message for deleting a QueryTemplate.
+message DeleteQueryTemplateRequest {
+  // Required. The resource path of the QueryTemplate.
+  // e.g.
+  // `projects/myproject/locations/us/dataExchanges/123/queryTemplates/myqueryTemplate`.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "analyticshub.googleapis.com/QueryTemplate"
+    }
+  ];
+}
+
+// Message for submitting a QueryTemplate.
+message SubmitQueryTemplateRequest {
+  // Required. The resource path of the QueryTemplate.
+  // e.g.
+  // `projects/myproject/locations/us/dataExchanges/123/queryTemplates/myqueryTemplate`.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "analyticshub.googleapis.com/QueryTemplate"
+    }
+  ];
+}
+
+// Message for approving a QueryTemplate.
+message ApproveQueryTemplateRequest {
+  // Required. The resource path of the QueryTemplate.
+  // e.g.
+  // `projects/myproject/locations/us/dataExchanges/123/queryTemplates/myqueryTemplate`.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "analyticshub.googleapis.com/QueryTemplate"
+    }
+  ];
+}
+
 // Sharing environment is a behavior model for sharing data within a
 // data exchange. This option is configurable for a data exchange.
 message SharingEnvironmentConfig {
@@ -494,6 +761,12 @@ message DestinationDataset {
   // https://cloud.google.com/bigquery/docs/locations for supported
   // locations.
   string location = 5 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. The geographic locations where the dataset should be replicated.
+  // See [BigQuery locations](https://cloud.google.com/bigquery/docs/locations)
+  // for supported locations.
+  repeated string replica_locations = 6
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Defines the destination Pub/Sub subscription.
@@ -566,6 +839,48 @@ message Listing {
           [(google.api.field_behavior) = OPTIONAL];
     }
 
+    // Represents the state of a replica of a shared dataset.
+    // It includes the geographic location of the replica and
+    // system-computed, output-only fields indicating its replication state and
+    // whether it is the primary replica.
+    message Replica {
+      // Replica state of the shared dataset.
+      enum ReplicaState {
+        // Default value. This value is unused.
+        REPLICA_STATE_UNSPECIFIED = 0;
+
+        // The replica is backfilled and ready to use.
+        READY_TO_USE = 1;
+
+        // The replica is unavailable, does not exist, or has not been
+        // backfilled yet.
+        UNAVAILABLE = 2;
+      }
+
+      // Primary state of the replica. Set only for the primary replica.
+      enum PrimaryState {
+        // Default value. This value is unused.
+        PRIMARY_STATE_UNSPECIFIED = 0;
+
+        // The replica is the primary replica.
+        PRIMARY_REPLICA = 1;
+      }
+
+      // Output only. The geographic location where the replica resides. See
+      // [BigQuery locations](https://cloud.google.com/bigquery/docs/locations)
+      // for supported locations. Eg. "us-central1".
+      string location = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+      // Output only. Assigned by Analytics Hub based on real BigQuery
+      // replication state.
+      ReplicaState replica_state = 2
+          [(google.api.field_behavior) = OUTPUT_ONLY];
+
+      // Output only. Indicates that this replica is the primary replica.
+      optional PrimaryState primary_state = 3
+          [(google.api.field_behavior) = OUTPUT_ONLY];
+    }
+
     // Optional. Resource name of the dataset source for this listing.
     // e.g. `projects/myproject/datasets/123`
     string dataset = 1 [
@@ -584,6 +899,18 @@ message Listing {
     // enforced on the linked dataset.
     RestrictedExportPolicy restricted_export_policy = 3
         [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. A list of regions where the publisher has created shared
+    // dataset replicas.
+    repeated string replica_locations = 5
+        [(google.api.field_behavior) = OPTIONAL];
+
+    // Output only. Server-owned effective state of replicas.
+    // Contains both primary and secondary replicas.
+    // Each replica includes a system-computed (output-only) state and primary
+    // designation.
+    repeated Replica effective_replicas = 6
+        [(google.api.field_behavior) = OUTPUT_ONLY];
   }
 
   // Pub/Sub topic source.
@@ -707,6 +1034,8 @@ message Listing {
     CATEGORY_TRANSPORTATION_AND_LOGISTICS = 18;
 
     CATEGORY_TRAVEL_AND_TOURISM = 19;
+
+    CATEGORY_GOOGLE_EARTH_ENGINE = 20;
   }
 
   // Listing source.
@@ -754,7 +1083,7 @@ message Listing {
   // Optional. Details of the data provider who owns the source data.
   DataProvider data_provider = 9 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. Categories of the listing. Up to two categories are allowed.
+  // Optional. Categories of the listing. Up to five categories are allowed.
   repeated Category categories = 10 [(google.api.field_behavior) = OPTIONAL];
 
   // Optional. Details of the publisher who owns the listing and who can share
