// Copyright 2019 Google LLC.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

syntax = "proto3";

package google.cloud.datacatalog.v1beta1;

import "google/api/annotations.proto";
import "google/cloud/datacatalog/v1beta1/schema.proto";
import "google/cloud/datacatalog/v1beta1/search.proto";
import "google/cloud/datacatalog/v1beta1/table_spec.proto";
import "google/cloud/datacatalog/v1beta1/tags.proto";
import "google/cloud/datacatalog/v1beta1/timestamps.proto";
import "google/iam/v1/iam_policy.proto";
import "google/iam/v1/policy.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/api/client.proto";

option cc_enable_arenas = true;
option go_package = "google.golang.org/genproto/googleapis/cloud/datacatalog/v1beta1;datacatalog";
option java_multiple_files = true;
option java_package = "com.google.cloud.datacatalog";

// Data Catalog API service allows clients to discover, understand, and manage
// their data.
service DataCatalog {
  option (google.api.default_host) = "datacatalog.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";

  // Searches Data Catalog for multiple resources like entries, tags that
  // match a query.
  //
  // This is a custom method
  // (https://cloud.google.com/apis/design/custom_methods) and does not return
  // the complete resource, only the resource identifier and high level
  // fields. Clients can subsequentally call Get methods.
  //
  // Note that searches do not have full recall. There may be results that match
  // your query but are not returned, even in subsequent pages of results. These
  // missing results may vary across repeated calls to search. Do not rely on
  // this method if you need to guarantee full recall.
  //
  // See [Data Catalog Search
  // Syntax](/data-catalog/docs/how-to/search-reference) for more information.
  rpc SearchCatalog(SearchCatalogRequest) returns (SearchCatalogResponse) {
    option (google.api.http) = {
      post: "/v1beta1/catalog:search"
      body: "*"
    };
  }

  // Updates an existing entry.
  rpc UpdateEntry(UpdateEntryRequest) returns (Entry) {
    option (google.api.http) = {
      patch: "/v1beta1/{entry.name=projects/*/locations/*/entryGroups/*/entries/*}"
      body: "entry"
    };
  }

  // Gets an entry.
  rpc GetEntry(GetEntryRequest) returns (Entry) {
    option (google.api.http) = {
      get: "/v1beta1/{name=projects/*/locations/*/entryGroups/*/entries/*}"
    };
  }

  // Get an entry by target resource name. This method allows clients to use
  // the resource name from the source Google Cloud Platform service to get the
  // Data Catalog Entry.
  rpc LookupEntry(LookupEntryRequest) returns (Entry) {
    option (google.api.http) = {
      get: "/v1beta1/entries:lookup"
    };
  }

  // Creates a tag template.
  rpc CreateTagTemplate(CreateTagTemplateRequest) returns (TagTemplate) {
    option (google.api.http) = {
      post: "/v1beta1/{parent=projects/*/locations/*}/tagTemplates"
      body: "tag_template"
    };
  }

  // Gets a tag template.
  rpc GetTagTemplate(GetTagTemplateRequest) returns (TagTemplate) {
    option (google.api.http) = {
      get: "/v1beta1/{name=projects/*/locations/*/tagTemplates/*}"
    };
  }

  // Updates a tag template. This method cannot be used to update the fields of
  // a template. The tag template fields are represented as separate resources
  // and should be updated using their own create/update/delete methods.
  rpc UpdateTagTemplate(UpdateTagTemplateRequest) returns (TagTemplate) {
    option (google.api.http) = {
      patch: "/v1beta1/{tag_template.name=projects/*/locations/*/tagTemplates/*}"
      body: "tag_template"
    };
  }

  // Deletes a tag template and all tags using the template.
  rpc DeleteTagTemplate(DeleteTagTemplateRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1beta1/{name=projects/*/locations/*/tagTemplates/*}"
    };
  }

  // Creates a field in a tag template.
  rpc CreateTagTemplateField(CreateTagTemplateFieldRequest) returns (TagTemplateField) {
    option (google.api.http) = {
      post: "/v1beta1/{parent=projects/*/locations/*/tagTemplates/*}/fields"
      body: "tag_template_field"
    };
  }

  // Updates a field in a tag template. This method cannot be used to update the
  // field type.
  rpc UpdateTagTemplateField(UpdateTagTemplateFieldRequest) returns (TagTemplateField) {
    option (google.api.http) = {
      patch: "/v1beta1/{name=projects/*/locations/*/tagTemplates/*/fields/*}"
      body: "tag_template_field"
    };
  }

  // Renames a field in a tag template.
  rpc RenameTagTemplateField(RenameTagTemplateFieldRequest) returns (TagTemplateField) {
    option (google.api.http) = {
      post: "/v1beta1/{name=projects/*/locations/*/tagTemplates/*/fields/*}:rename"
      body: "*"
    };
  }

  // Deletes a field in a tag template and all uses of that field.
  rpc DeleteTagTemplateField(DeleteTagTemplateFieldRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1beta1/{name=projects/*/locations/*/tagTemplates/*/fields/*}"
    };
  }

  // Creates a tag on an [Entry][google.cloud.datacatalog.v1beta1.Entry].
  rpc CreateTag(CreateTagRequest) returns (Tag) {
    option (google.api.http) = {
      post: "/v1beta1/{parent=projects/*/locations/*/entryGroups/*/entries/*}/tags"
      body: "tag"
    };
  }

  // Updates an existing tag.
  rpc UpdateTag(UpdateTagRequest) returns (Tag) {
    option (google.api.http) = {
      patch: "/v1beta1/{tag.name=projects/*/locations/*/entryGroups/*/entries/*/tags/*}"
      body: "tag"
    };
  }

  // Deletes a tag.
  rpc DeleteTag(DeleteTagRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1beta1/{name=projects/*/locations/*/entryGroups/*/entries/*/tags/*}"
    };
  }

  // Lists the tags on an [Entry][google.cloud.datacatalog.v1beta1.Entry].
  rpc ListTags(ListTagsRequest) returns (ListTagsResponse) {
    option (google.api.http) = {
      get: "/v1beta1/{parent=projects/*/locations/*/entryGroups/*/entries/*}/tags"
    };
  }

  // Sets the access control policy for a resource. Replaces any existing
  // policy.
  // Supported resources are:
  //   - Tag templates.
  // Note, this method cannot be used to manage policies for BigQuery, Cloud
  // Pub/Sub and any external Google Cloud Platform resources synced to Cloud
  // Data Catalog.
  //
  // Callers must have following Google IAM permission
  // `datacatalog.tagTemplates.setIamPolicy` to set policies on tag templates.
  rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) {
    option (google.api.http) = {
      post: "/v1beta1/{resource=projects/*/locations/*/tagTemplates/*}:setIamPolicy"
      body: "*"
    };
  }

  // Gets the access control policy for a resource. A `NOT_FOUND` error
  // is returned if the resource does not exist. An empty policy is returned
  // if the resource exists but does not have a policy set on it.
  //
  // Supported resources are:
  //   - Tag templates.
  // Note, this method cannot be used to manage policies for BigQuery, Cloud
  // Pub/Sub and any external Google Cloud Platform resources synced to Cloud
  // Data Catalog.
  //
  // Callers must have following Google IAM permission
  // `datacatalog.tagTemplates.getIamPolicy` to get policies on tag templates.
  rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) {
    option (google.api.http) = {
      post: "/v1beta1/{resource=projects/*/locations/*/tagTemplates/*}:getIamPolicy"
      body: "*"
    };
  }

  // Returns the caller's permissions on a resource.
  // If the resource does not exist, an empty set of permissions is returned
  // (We don't return a `NOT_FOUND` error).
  //
  // Supported resource are:
  //   - tag templates.
  // Note, this method cannot be used to manage policies for BigQuery, Cloud
  // Pub/Sub and any external Google Cloud Platform resources synced to Cloud
  // Data Catalog.
  //
  // A caller is not required to have Google IAM permission to make this
  // request.
  rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) {
    option (google.api.http) = {
      post: "/v1beta1/{resource=projects/*/locations/*/tagTemplates/*}:testIamPermissions"
      body: "*"
    };
  }
}

// Request message for
// [SearchCatalog][google.cloud.datacatalog.v1beta1.DataCatalog.SearchCatalog].
message SearchCatalogRequest {
  message Scope {
    // Data Catalog tries to automatically choose the right corpus of data to
    // search through. You can ensure an organization is included by adding it
    // to "include_org_ids". You can ensure a project's org is included with
    // "include_project_ids". You must specify at least one organization
    // using "include_org_ids" or "include_project_ids" in all search requests.
    //
    // List of organization IDs to search within. To find your organization ID,
    // follow instructions in
    // https://cloud.google.com/resource-manager/docs/creating-managing-organization
    repeated string include_org_ids = 2;

    // List of project IDs to search within. To learn more about the
    // distinction between project names/IDs/numbers, go to
    // https://cloud.google.com/docs/overview/#projects
    repeated string include_project_ids = 3;

    // If true, include Google Cloud Platform (GCP) public datasets in the
    // search results. Info on GCP public datasets is available at
    // https://cloud.google.com/public-datasets/. By default, GCP public
    // datasets are excluded.
    bool include_gcp_public_datasets = 7;
  }

  // Required. The scope of this search request.
  Scope scope = 6;

  // Required. The query string in search query syntax. The query must be
  // non-empty.
  //
  // Query strings can be simple as "x" or more qualified as:
  //
  // * name:x
  // * column:x
  // * description:y
  //
  // Note: Query tokens need to have a minimum of 3 characters for substring
  // matching to work correctly. See [Data Catalog Search
  // Syntax](/data-catalog/docs/how-to/search-reference) for more information.
  string query = 1;

  // Number of results in the search page. If <=0 then defaults to 10. Max limit
  // for page_size is 1000. Throws an invalid argument for page_size > 1000.
  int32 page_size = 2;

  // Optional pagination token returned in an earlier
  // [SearchCatalogResponse.next_page_token][google.cloud.datacatalog.v1beta1.DataCatalog.SearchCatalogResponse.next_page_token];
  // indicates that this is a continuation of a prior
  // [SearchCatalog][google.cloud.datacatalog.v1beta1.DataCatalog.SearchCatalog]
  // call, and that the system should return the next page of data. If empty
  // then the first page is returned.
  string page_token = 3;

  // Specifies the ordering of results, currently supported case-sensitive
  // choices are:
  // <ul>
  //   <li> relevance </li>
  //   <li> last_access_timestamp [asc|desc], defaults to descending if not
  //   specified, </li>
  //   <li> last_modified_timestamp [asc|desc], defaults to descending if not
  //   specified. </li>
  // </ul>
  string order_by = 5;
}

// Response message for
// [SearchCatalog][google.cloud.datacatalog.v1beta1.DataCatalog.SearchCatalog].
message SearchCatalogResponse {
  // Search results in descending order of relevance.
  repeated SearchCatalogResult results = 1;

  // The token that can be used to retrieve the next page of results.
  string next_page_token = 3;
}

// Request message for
// [UpdateEntry][google.cloud.datacatalog.v1beta1.DataCatalog.UpdateEntry].
message UpdateEntryRequest {
  // Required. The updated Entry.
  Entry entry = 1;

  // Optional. The fields to update on the entry.  If absent or empty, all
  // modifiable fields are updated.
  //
  // Modifiable fields in synced entries:
  //
  // 1. schema (Pub/Sub topics only)
  //
  // Modifiable fields in native entries:
  //
  // 1. display_name
  // 2. description
  // 3. schema
  google.protobuf.FieldMask update_mask = 2;
}

// Request message for
// [GetEntry][google.cloud.datacatalog.v1beta1.DataCatalog.GetEntry].
message GetEntryRequest {
  // Required. The name of the entry. For example,
  // "projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id}".
  string name = 1;
}

// Request message for
// [LookupEntry][google.cloud.datacatalog.v1beta1.DataCatalog.LookupEntry].
message LookupEntryRequest {
  // Required. Represents either the Google Cloud Platform resource or SQL name
  // for a Google Cloud Platform resource.
  oneof target_name {
    // The full name of the Google Cloud Platform resource the Data Catalog
    // entry represents. See:
    // https://cloud.google.com/apis/design/resource_names#full_resource_name
    // Full names are case-sensitive.
    //
    // Examples:
    // "//bigquery.googleapis.com/projects/projectId/datasets/datasetId/tables/tableId".
    // "//pubsub.googleapis.com/projects/projectId/topics/topicId"
    string linked_resource = 1;

    // The SQL name of the entry. SQL names are case-sensitive.
    //
    // Examples:
    // <ul>
    //   <li>cloud_pubsub.project_id.topic_id</li>
    //   <li>pubsub.project_id.`topic.id.with.dots`</li>
    //   <li>bigquery.project_id.dataset_id.table_id</li>
    //   <li>datacatalog.project_id.location_id.entry_group_id.entry_id</li>
    // </ul>
    // *_ids shoud satisfy the standard SQL rules for identifiers.
    // https://cloud.google.com/bigquery/docs/reference/standard-sql/lexical
    string sql_resource = 3;
  }
}

// Entry Metadata.
// A Data Catalog Entry resource represents another resource in Google
// Cloud Platform, such as a BigQuery Dataset or a Pub/Sub Topic. Clients can
// use the `linked_resource` field in the Entry resource to refer to the
// original resource id of the source system.
//
// An Entry resource contains resource details, such as its schema. An Entry can
// also be used to attach flexible metadata, such as a
// [Tag][google.cloud.datacatalog.v1beta1.Tag].
message Entry {
  // Required when used in
  // [UpdateEntryRequest][google.cloud.datacatalog.v1beta1.UpdateEntryRequest].
  // The Data Catalog resource name of the entry in URL format. For example,
  // "projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id}".
  // Note that this Entry and its child resources may not actually be stored in
  // the location in this name.
  string name = 1;

  // Output only. The full name of the cloud resource the entry belongs to. See:
  // https://cloud.google.com/apis/design/resource_names#full_resource_name
  //
  // Data Catalog supports resources from select Google Cloud Platform systems.
  // `linked_resource` is the full name of the Google Cloud Platform resource.
  // For example, the `linked_resource` for a table resource from BigQuery is:
  //
  // "//bigquery.googleapis.com/projects/projectId/datasets/datasetId/tables/tableId".
  string linked_resource = 9;

  // Required. Type of entry.
  EntryType type = 2;

  // Optional. Type specification information.
  oneof type_spec {
    // Specification that applies to a BigQuery table. This is only valid on
    // entries of type TABLE.
    BigQueryTableSpec bigquery_table_spec = 12;

    // Specification for a group of BigQuery tables with name pattern
    // [prefix]YYYYMMDD. Context:
    // https://cloud.google.com/bigquery/docs/partitioned-tables#partitioning_versus_sharding
    BigQueryDateShardedSpec bigquery_date_sharded_spec = 15;
  }

  // Optional. Display information such as title and description. A short name
  // to identify the entry, for example, "Analytics Data - Jan 2011". Default
  // value is an empty string.
  string display_name = 3;

  // Optional. Entry description, which can consist of several sentences or
  // paragraphs that describe entry contents. Default value is an empty string.
  string description = 4;

  // Optional. Schema of the entry. An entry might not have any schema attached
  // to it.
  Schema schema = 5;

  // Output only. Timestamps about the underlying Google Cloud Platform resource
  // -- not about this Data Catalog Entry.
  SystemTimestamps source_system_timestamps = 7;
}

// Request message for
// [CreateTagTemplate][google.cloud.datacatalog.v1beta1.DataCatalog.CreateTagTemplate].
message CreateTagTemplateRequest {
  // Required. The name of the project and the location this template is in.
  // Example: "projects/{project_id}/locations/{location}". Note that this
  // TagTemplate and its child resources may not actually be stored in the
  // location in this name.
  string parent = 1;

  // Required. The id of the tag template to create.
  string tag_template_id = 3;

  // Required. The tag template to create.
  TagTemplate tag_template = 2;
}

// Request message for
// [GetTagTemplate][google.cloud.datacatalog.v1beta1.DataCatalog.GetTagTemplate].
message GetTagTemplateRequest {
  // Required. The name of the tag template. For example,
  // "projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}".
  string name = 1;
}

// Request message for
// [UpdateTagTemplate][google.cloud.datacatalog.v1beta1.DataCatalog.UpdateTagTemplate].
message UpdateTagTemplateRequest {
  // Required. The template to update.
  TagTemplate tag_template = 1;

  // Optional. The field mask specifies the parts of the template to overwrite.
  //
  // Allowed fields:
  //
  //   * display_name
  //
  // If update_mask is omitted, all of the allowed fields above will be updated.
  google.protobuf.FieldMask update_mask = 2;
}

// Request message for
// [DeleteTagTemplate][google.cloud.datacatalog.v1beta1.DataCatalog.DeleteTagTemplate].
message DeleteTagTemplateRequest {
  // Required. The name of the tag template to delete. For example,
  // "projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}".
  string name = 1;

  // Required. Currently, this field must always be set to <code>true</code>.
  // This confirms the deletion of any possible tags using this template.
  // <code>force = false</code> will be supported in the future.
  bool force = 2;
}

// Request message for
// [CreateTag][google.cloud.datacatalog.v1beta1.DataCatalog.CreateTag].
message CreateTagRequest {
  // Required.
  // The name of the resource to attach this tag to. Tags can be attached to
  // Entries. (example:
  // "projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id}").
  // Note that this Tag and its child resources may not actually be stored in
  // the location in this name.
  string parent = 1;

  // Required. The tag to create.
  Tag tag = 2;
}

// Request message for
// [UpdateTag][google.cloud.datacatalog.v1beta1.DataCatalog.UpdateTag].
message UpdateTagRequest {
  // Required. The updated tag.
  Tag tag = 1;

  // Optional. The fields to update on the Tag.  If absent or empty, all
  // modifiable fields are updated. Currently the only modifiable field is the
  // field `fields`.
  google.protobuf.FieldMask update_mask = 2;
}

// Request message for
// [DeleteTag][google.cloud.datacatalog.v1beta1.DataCatalog.DeleteTag].
message DeleteTagRequest {
  // Required. The name of the tag to delete. For example,
  // "projects/{project_id}/locations/{location}/entryGroups/{entry_group_id}/entries/{entry_id}/tags/{tag_id}".
  string name = 1;
}

// Request message for
// [CreateTagTemplateField][google.cloud.datacatalog.v1beta1.DataCatalog.CreateTagTemplateField].
message CreateTagTemplateFieldRequest {
  // Required. The name of the project this template is in. Example:
  // "projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}".
  // Note that this TagTemplateField may not actually be stored in the location
  // in this name.
  string parent = 1;

  // Required. The id of the tag template field to create.
  // Field ids can contain letters (both uppercase and lowercase), numbers
  // (0-9), underscores (_) and dashes (-). Field ids must be at least 1
  // character long and at most 128 characters long. Field ids must also be
  // unique to their template.
  string tag_template_field_id = 2;

  // Required. The tag template field to create.
  TagTemplateField tag_template_field = 3;
}

// Request message for
// [UpdateTagTemplateField][google.cloud.datacatalog.v1beta1.DataCatalog.UpdateTagTemplateField].
message UpdateTagTemplateFieldRequest {
  // Required. The name of the tag template field. For example,
  // "projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id}".
  string name = 1;

  // Required. The template to update.
  TagTemplateField tag_template_field = 2;

  // Optional. The field mask specifies the parts of the template to overwrite.
  // Allowed fields:
  //
  //   * display_name
  //   * type.enum_type
  //
  // If update_mask is omitted, all of the allowed fields above will be updated.
  //
  // When updating an enum type, the provided values will be merged with the
  // existing values. Therefore, enum values can only be added, existing enum
  // values cannot be deleted nor renamed.
  google.protobuf.FieldMask update_mask = 3;
}

// Request message for
// [RenameTagTemplateField][google.cloud.datacatalog.v1beta1.DataCatalog.RenameTagTemplateField].
message RenameTagTemplateFieldRequest {
  // Required. The name of the tag template. For example,
  // "projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id}".
  string name = 1;

  // Required. The new ID of this tag template field. For example,
  // "my_new_field".
  string new_tag_template_field_id = 2;
}

// Entry resources in Data Catalog can be of different types e.g. BigQuery
// Table entry is of type 'TABLE'. This enum describes all the possible types
// Data Catalog contains.
enum EntryType {
  // Default unknown type
  ENTRY_TYPE_UNSPECIFIED = 0;

  // The type of entry that has a GoogleSQL schema, including logical views.
  TABLE = 2;

  // An entry type which is used for streaming entries. Example - Pub/Sub.
  DATA_STREAM = 3;
}

// Request message for
// [DeleteTagTemplateField][google.cloud.datacatalog.v1beta1.DataCatalog.DeleteTagTemplateField].
message DeleteTagTemplateFieldRequest {
  // Required. The name of the tag template field to delete. For example,
  // "projects/{project_id}/locations/{location}/tagTemplates/{tag_template_id}/fields/{tag_template_field_id}".
  string name = 1;

  // Required. Currently, this field must always be set to <code>true</code>.
  // This confirms the deletion of this field from any tags using this field.
  // <code>force = false</code> will be supported in the future.
  bool force = 2;
}

// Request message for
// [ListTags][google.cloud.datacatalog.v1beta1.DataCatalog.ListTags].
message ListTagsRequest {
  // Required. The name of the Data Catalog resource to list the tags of. The
  // resource could be an [Entry][google.cloud.datacatalog.v1beta1.Entry].
  string parent = 1;

  // Optional. The maximum number of tags to return. Default is 10. Max limit is
  // 1000.
  int32 page_size = 2;

  // Optional. Token that specifies which page is requested. If empty, the first
  // page is returned.
  string page_token = 3;
}

// Response message for
// [ListTags][google.cloud.datacatalog.v1beta1.DataCatalog.ListTags].
message ListTagsResponse {
  // [Tag][google.cloud.datacatalog.v1beta1.Tag] details.
  repeated Tag tags = 1;

  // Token to retrieve the next page of results. It is set to empty if no items
  // remain in results.
  string next_page_token = 2;
}
