1// Copyright 2023 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.cloud.aiplatform.v1; 18 19import "google/api/field_behavior.proto"; 20import "google/api/resource.proto"; 21import "google/protobuf/timestamp.proto"; 22 23option csharp_namespace = "Google.Cloud.AIPlatform.V1"; 24option go_package = "cloud.google.com/go/aiplatform/apiv1/aiplatformpb;aiplatformpb"; 25option java_multiple_files = true; 26option java_outer_classname = "FeatureViewProto"; 27option java_package = "com.google.cloud.aiplatform.v1"; 28option php_namespace = "Google\\Cloud\\AIPlatform\\V1"; 29option ruby_package = "Google::Cloud::AIPlatform::V1"; 30 31// FeatureView is representation of values that the FeatureOnlineStore will 32// serve based on its syncConfig. 33message FeatureView { 34 option (google.api.resource) = { 35 type: "aiplatform.googleapis.com/FeatureView" 36 pattern: "projects/{project}/locations/{location}/featureOnlineStores/{feature_online_store}/featureViews/{feature_view}" 37 }; 38 39 message BigQuerySource { 40 // Required. The BigQuery view URI that will be materialized on each sync 41 // trigger based on FeatureView.SyncConfig. 42 string uri = 1 [(google.api.field_behavior) = REQUIRED]; 43 44 // Required. Columns to construct entity_id / row keys. 45 repeated string entity_id_columns = 2 46 [(google.api.field_behavior) = REQUIRED]; 47 } 48 49 // Configuration for Sync. Only one option is set. 50 message SyncConfig { 51 // Cron schedule (https://en.wikipedia.org/wiki/Cron) to launch scheduled 52 // runs. To explicitly set a timezone to the cron tab, apply a prefix in 53 // the cron tab: "CRON_TZ=${IANA_TIME_ZONE}" or "TZ=${IANA_TIME_ZONE}". 54 // The ${IANA_TIME_ZONE} may only be a valid string from IANA time zone 55 // database. For example, "CRON_TZ=America/New_York 1 * * * *", or 56 // "TZ=America/New_York 1 * * * *". 57 string cron = 1; 58 } 59 60 // Configuration for vector indexing. 61 message IndexConfig { 62 // Configuration options for using brute force search. 63 message BruteForceConfig {} 64 65 // Configuration options for the tree-AH algorithm. 66 message TreeAHConfig { 67 // Optional. Number of embeddings on each leaf node. The default value is 68 // 1000 if not set. 69 optional int64 leaf_node_embedding_count = 1 70 [(google.api.field_behavior) = OPTIONAL]; 71 } 72 73 // The distance measure used in nearest neighbor search. 74 enum DistanceMeasureType { 75 // Should not be set. 76 DISTANCE_MEASURE_TYPE_UNSPECIFIED = 0; 77 78 // Euclidean (L_2) Distance. 79 SQUARED_L2_DISTANCE = 1; 80 81 // Cosine Distance. Defined as 1 - cosine similarity. 82 // 83 // We strongly suggest using DOT_PRODUCT_DISTANCE + UNIT_L2_NORM instead 84 // of COSINE distance. Our algorithms have been more optimized for 85 // DOT_PRODUCT distance which, when combined with UNIT_L2_NORM, is 86 // mathematically equivalent to COSINE distance and results in the same 87 // ranking. 88 COSINE_DISTANCE = 2; 89 90 // Dot Product Distance. Defined as a negative of the dot product. 91 DOT_PRODUCT_DISTANCE = 3; 92 } 93 94 // The configuration with regard to the algorithms used for efficient 95 // search. 96 oneof algorithm_config { 97 // Optional. Configuration options for the tree-AH algorithm (Shallow tree 98 // + Asymmetric Hashing). Please refer to this paper for more details: 99 // https://arxiv.org/abs/1908.10396 100 TreeAHConfig tree_ah_config = 6 [(google.api.field_behavior) = OPTIONAL]; 101 102 // Optional. Configuration options for using brute force search, which 103 // simply implements the standard linear search in the database for each 104 // query. It is primarily meant for benchmarking and to generate the 105 // ground truth for approximate search. 106 BruteForceConfig brute_force_config = 7 107 [(google.api.field_behavior) = OPTIONAL]; 108 } 109 110 // Optional. Column of embedding. This column contains the source data to 111 // create index for vector search. embedding_column must be set when using 112 // vector search. 113 string embedding_column = 1 [(google.api.field_behavior) = OPTIONAL]; 114 115 // Optional. Columns of features that're used to filter vector search 116 // results. 117 repeated string filter_columns = 2 [(google.api.field_behavior) = OPTIONAL]; 118 119 // Optional. Column of crowding. This column contains crowding attribute 120 // which is a constraint on a neighbor list produced by 121 // [FeatureOnlineStoreService.SearchNearestEntities][google.cloud.aiplatform.v1.FeatureOnlineStoreService.SearchNearestEntities] 122 // to diversify search results. If 123 // [NearestNeighborQuery.per_crowding_attribute_neighbor_count][google.cloud.aiplatform.v1.NearestNeighborQuery.per_crowding_attribute_neighbor_count] 124 // is set to K in 125 // [SearchNearestEntitiesRequest][google.cloud.aiplatform.v1.SearchNearestEntitiesRequest], 126 // it's guaranteed that no more than K entities of the same crowding 127 // attribute are returned in the response. 128 string crowding_column = 3 [(google.api.field_behavior) = OPTIONAL]; 129 130 // Optional. The number of dimensions of the input embedding. 131 optional int32 embedding_dimension = 4 132 [(google.api.field_behavior) = OPTIONAL]; 133 134 // Optional. The distance measure used in nearest neighbor search. 135 DistanceMeasureType distance_measure_type = 5 136 [(google.api.field_behavior) = OPTIONAL]; 137 } 138 139 // A Feature Registry source for features that need to be synced to Online 140 // Store. 141 message FeatureRegistrySource { 142 // Features belonging to a single feature group that will be 143 // synced to Online Store. 144 message FeatureGroup { 145 // Required. Identifier of the feature group. 146 string feature_group_id = 1 [(google.api.field_behavior) = REQUIRED]; 147 148 // Required. Identifiers of features under the feature group. 149 repeated string feature_ids = 2 [(google.api.field_behavior) = REQUIRED]; 150 } 151 152 // Required. List of features that need to be synced to Online Store. 153 repeated FeatureGroup feature_groups = 1 154 [(google.api.field_behavior) = REQUIRED]; 155 156 // Optional. The project number of the parent project of the Feature Groups. 157 optional int64 project_number = 2 [(google.api.field_behavior) = OPTIONAL]; 158 } 159 160 oneof source { 161 // Optional. Configures how data is supposed to be extracted from a BigQuery 162 // source to be loaded onto the FeatureOnlineStore. 163 BigQuerySource big_query_source = 6 164 [(google.api.field_behavior) = OPTIONAL]; 165 166 // Optional. Configures the features from a Feature Registry source that 167 // need to be loaded onto the FeatureOnlineStore. 168 FeatureRegistrySource feature_registry_source = 9 169 [(google.api.field_behavior) = OPTIONAL]; 170 } 171 172 // Identifier. Name of the FeatureView. Format: 173 // `projects/{project}/locations/{location}/featureOnlineStores/{feature_online_store}/featureViews/{feature_view}` 174 string name = 1 [(google.api.field_behavior) = IDENTIFIER]; 175 176 // Output only. Timestamp when this FeatureView was created. 177 google.protobuf.Timestamp create_time = 2 178 [(google.api.field_behavior) = OUTPUT_ONLY]; 179 180 // Output only. Timestamp when this FeatureView was last updated. 181 google.protobuf.Timestamp update_time = 3 182 [(google.api.field_behavior) = OUTPUT_ONLY]; 183 184 // Optional. Used to perform consistent read-modify-write updates. If not set, 185 // a blind "overwrite" update happens. 186 string etag = 4 [(google.api.field_behavior) = OPTIONAL]; 187 188 // Optional. The labels with user-defined metadata to organize your 189 // FeatureViews. 190 // 191 // Label keys and values can be no longer than 64 characters 192 // (Unicode codepoints), can only contain lowercase letters, numeric 193 // characters, underscores and dashes. International characters are allowed. 194 // 195 // See https://goo.gl/xmQnxf for more information on and examples of labels. 196 // No more than 64 user labels can be associated with one 197 // FeatureOnlineStore(System labels are excluded)." System reserved label keys 198 // are prefixed with "aiplatform.googleapis.com/" and are immutable. 199 map<string, string> labels = 5 [(google.api.field_behavior) = OPTIONAL]; 200 201 // Configures when data is to be synced/updated for this FeatureView. At the 202 // end of the sync the latest featureValues for each entityId of this 203 // FeatureView are made ready for online serving. 204 SyncConfig sync_config = 7; 205 206 // Optional. Configuration for index preparation for vector search. It 207 // contains the required configurations to create an index from source data, 208 // so that approximate nearest neighbor (a.k.a ANN) algorithms search can be 209 // performed during online serving. 210 IndexConfig index_config = 15 [(google.api.field_behavior) = OPTIONAL]; 211} 212