1  syntax = "proto2";
  2  
  3  package mlflow.unitycatalog;
  4  
  5  import "databricks.proto";
  6  import "scalapb/scalapb.proto";
  7  
  8  option java_generate_equals_and_hash = true;
  9  option java_package = "com.databricks.api.proto.managedcatalog";
 10  option (scalapb.options) = {flat_package: true};
 11  
 12  // Registered Model Management API
 13  message RegisteredModelInfo {
 14    // Input fields:
 15  
 16    // [Create:REQ Update:OPT] Name of Model, relative to parent Schema.
 17    optional string name = 1;
 18    // [Create:REQ Update:IGN] Name of parent Catalog.
 19    optional string catalog_name = 2;
 20    // [Create:REQ Update:IGN] Name of parent Schema relative to its parent Catalog.
 21    optional string schema_name = 3;
 22    // [Create,Update:OPT] User-provided free-form text description.
 23    optional string comment = 5;
 24  
 25    // Output-only fields:
 26  
 27    // [Create,Update:IGN] Storage root URL for model
 28    optional string storage_location = 6;
 29    // [Create,Update:IGN] Full name of Model, in form of <catalog_name>.<schema_name>.<model_name>
 30    optional string full_name = 9;
 31    // [Create,Update:IGN] Time at which this Model was created, in epoch milliseconds.
 32    optional int64 created_at = 11;
 33    // [Create,Update:IGN] Username of Model creator.
 34    optional string created_by = 12;
 35    // [Create,Update:IGN] Time at which this Model was last modified, in epoch milliseconds.
 36    optional int64 updated_at = 13;
 37    // [Create,Update:IGN] Username of user who last modified the Model.
 38    optional string updated_by = 14;
 39    // [Create,Update:IGN] ID of the securable that can be used in paging tokens
 40    optional string id = 18;
 41    // [Create,Update:IGN] Indicate if current model info contains only browsable metadata
 42    optional bool browse_only = 21;
 43    // [Create,Update:IGN] Encryption options to use when accessing cloud storage.
 44    //  optional EncryptionDetails encryption_details = 22;
 45  }
 46  
 47  message CreateRegisteredModel {
 48    // [Create:REQ Update:OPT] Name of Model, relative to parent Schema.
 49    optional string name = 1;
 50    // [Create:REQ Update:IGN] Name of parent Catalog.
 51    optional string catalog_name = 2;
 52    // [Create:REQ Update:IGN] Name of parent Schema relative to its parent Catalog.
 53    optional string schema_name = 3;
 54    // [Create,Update:OPT] User-provided free-form text description.
 55    optional string comment = 5;
 56    // [Create,Update:IGN] Storage root URL for model
 57    optional string storage_location = 6;
 58  
 59    message Response {
 60      optional RegisteredModelInfo registered_model_info = 1;
 61    }
 62  }
 63  
 64  message DeleteRegisteredModel {
 65    // Required. Full name of the model.
 66    optional string full_name = 1;
 67    // Optional. Force deletion even if the registered model is not empty. Default is false.
 68    optional bool force = 2;
 69  
 70    message Response {}
 71  }
 72  
 73  message GetRegisteredModel {
 74    // Required. Full name of the Model.
 75    optional string full_name = 1 [(validate_required) = true];
 76  
 77    message Response {
 78      optional RegisteredModelInfo registered_model_info = 1;
 79    }
 80  }
 81  
 82  message UpdateRegisteredModel {
 83    // Required. Full name of the Model.
 84    optional string full_name = 1;
 85  
 86    // Optional. New name of registered model (replaces registered_model_info.name for specifying new name).
 87    optional string new_name = 3;
 88  
 89    // Optional. New comment for registered model. (replaces registered_model_info.comment).
 90    optional string comment = 2;
 91  
 92    message Response {
 93      optional RegisteredModelInfo registered_model_info = 1;
 94    }
 95  }
 96  
 97  message ListRegisteredModels {
 98    // Optional. Name of parent catalog for models of interest.
 99    optional string catalog_name = 1;
100    // Optional. Parent schema of models.
101    optional string schema_name = 2;
102  
103    // If catalog and schema are unspecified, max_results must be specified.
104    // If max_results is unspecified, we return all results, starting from the page specified by page_token
105    // Maximum number of models to return (page length).
106    optional int64 max_results = 5;
107  
108    // If page_token is unspecified, results begin from the first page of db results
109    // Optional. Opaque token to send for the next page of results (pagination).
110    optional string page_token = 6;
111  
112    message Response {
113      repeated RegisteredModelInfo registered_models = 1;
114      // Optional. Opaque token for pagination.
115      optional string next_page_token = 2;
116    }
117  }
118  
119  message ModelVersionInfo {
120    // [Create:REQ Update:IGN] Name of parent model, relative to parent Schema.
121    optional string model_name = 1;
122    // [Create:REQ Update:IGN] Name of parent Catalog.
123    optional string catalog_name = 2;
124    // [Create:REQ Update:IGN] Name of parent Schema relative to its parent Catalog.
125    optional string schema_name = 3;
126    // [Create:REQ Update:IGN] URI indicating the location of the source model artifacts, used
127    // when creating ``model_version``
128    optional string source = 5;
129  
130    // OPTIONAL input fields (for Create and/or Update):
131  
132    // [Create,Update:OPT] User-provided free-form text description.
133    optional string comment = 4;
134    // [Create:OPT Update:IGN] MLflow run ID used when creating ``model_version``, if ``source``
135    // was generated by an experiment run stored in MLflow tracking server.
136    optional string run_id = 6;
137    // [Create:OPT Update:IGN] ID of the workspace containing the MLflow run that
138    // generated this model version
139  
140    // Output-only fields:
141  
142    // [Create,Update:IGN] Current status of ``model_version``
143    optional ModelVersionStatus status = 8;
144    // [Create,Update:IGN] Numeric model version Id
145    optional int64 version = 9;
146    // [Create,Update:IGN] Storage root URL for model version
147    optional string storage_location = 10;
148    // [Create,Update:IGN] Unique identifier of parent Metastore.
149    optional int64 created_at = 12;
150    // [Create,Update:IGN] Username of model version creator.
151    optional string created_by = 13;
152    // [Create,Update:IGN] Time at which this model version was last modified, in epoch milliseconds.
153    optional int64 updated_at = 14;
154    // [Create,Update:IGN] Username of user who last modified the model version.
155    optional string updated_by = 15;
156    // [Create,Update:IGN] Unique identifier of model version.
157    optional string id = 16;
158  }
159  
160  message CreateModelVersion {
161    // Name of Model, relative to parent Schema.
162    optional string model_name = 1;
163    // Name of parent Catalog.
164    optional string catalog_name = 2;
165    // Name of parent Schema relative to its parent Catalog.
166    optional string schema_name = 3;
167    // URI indicating the location of the source model artifacts, used
168    // when creating ``model_version``
169    optional string source = 4;
170    // MLflow run ID used when creating ``model_version``, if ``source``
171    // was generated by an experiment run stored in MLflow tracking server.
172    optional string run_id = 5;
173    // User-provided free-form text description.
174    optional string comment = 6;
175  
176    message Response {
177      optional ModelVersionInfo model_version_info = 1;
178    }
179  }
180  
181  message DeleteModelVersion {
182    // Required. Full name of the parent registered model (from URL).
183    optional string full_name = 1;
184  
185    // Required. Integer model version number (from URL).
186    optional int64 version = 2;
187  
188    message Response {}
189  }
190  
191  message FinalizeModelVersion {
192    // Required. Full name of the parent registered model (from URL).
193    optional string full_name = 1;
194  
195    // Required. Integer model version number (from URL).
196    optional int64 version = 2;
197  
198    message Response {
199      optional ModelVersionInfo model_version_info = 1;
200    }
201  }
202  
203  message GetModelVersion {
204    // Required. Full name of the parent registered model (from URL)..
205    optional string full_name = 1;
206  
207    // Required. Integer model version number (from URL).
208    optional int64 version = 2;
209  
210    message Response {
211      optional ModelVersionInfo model_version_info = 1;
212    }
213  }
214  
215  message UpdateModelVersion {
216    // Required. Full name of the parent registered model (from URL).
217    optional string full_name = 1;
218  
219    // Required. Integer model version number (from URL).
220    optional int64 version = 2;
221  
222    // Required. Partial ModelVersionInfo with fields to change.
223    optional string comment = 3;
224  
225    message Response {
226      optional ModelVersionInfo model_version_info = 1;
227    }
228  }
229  
230  message ListModelVersions {
231    // Required. Full name of the parent registered model (from URL).
232    optional string full_name = 1;
233  
234    // Maximum number of model versions to return (i.e., the page length). Defaults to 100.
235    // Maximum allowed value is 1000.
236    optional int64 max_results = 4;
237  
238    // Optional. Opaque token to send for the next page of results (pagination).
239    optional string page_token = 5;
240  
241    message Response {
242      repeated ModelVersionInfo model_versions = 1;
243      // Opaque token for pagination.
244      optional string next_page_token = 2;
245    }
246  }
247  
248  enum ModelVersionStatus {
249    MODEL_VERSION_STATUS_UNKNOWN = 0;
250    // Request to register a new model version is pending as client uploads model files.
251    PENDING_REGISTRATION = 1;
252    // Request to register a new model version has failed.
253    FAILED_REGISTRATION = 2;
254    // Model version is ready for use.
255    READY = 3;
256  }
257  
258  // Credentials Related Protos
259  
260  message TemporaryCredentials {
261    optional AwsCredentials aws_temp_credentials = 2;
262    optional AzureUserDelegationSAS azure_user_delegation_sas = 3;
263    optional GcpOauthToken gcp_oauth_token = 4;
264  
265    // Server time when the credential will expire, in epoch milliseconds.
266    // The API client is advised to cache the credential given this expiration time.
267    optional int64 expiration_time = 1;
268  }
269  
270  // AWS temporary credentials for API authentication.
271  // Read more at https://docs.aws.amazon.com/STS/latest/APIReference/API_Credentials.html.
272  message AwsCredentials {
273    // The access key ID that identifies the temporary credentials.
274    optional string access_key_id = 1;
275  
276    // The secret access key that can be used to sign AWS API requests.
277    optional string secret_access_key = 2;
278  
279    // The token that users must pass to AWS API to use the temporary credentials.
280    optional string session_token = 3;
281  }
282  
283  // Azure temporary credentials for API authentication.
284  // Read more at https://docs.microsoft.com/en-us/rest/api/storageservices/create-user-delegation-sas
285  message AzureUserDelegationSAS {
286    // The signed URI (SAS Token) used to access blob services for a given path
287    optional string sas_token = 1;
288  }
289  
290  // GCP temporary credentials for API authentication.
291  // Read more at https://developers.google.com/identity/protocols/oauth2/service-account
292  message GcpOauthToken {
293    optional string oauth_token = 1;
294  }
295  
296  message GenerateTemporaryModelVersionCredential {
297    // Required. Name of parent catalog for model version of interest.
298    optional string catalog_name = 1;
299    // Required. Name of parent schema of model version.
300    optional string schema_name = 2;
301    // Required. Name of parent registered model of model version.
302    optional string model_name = 3;
303    // Required. Numeric model version Id
304    optional int64 version = 4;
305  
306    // Required. Type of operation (read or write) to perform on the model version
307    // Note that model version files can only be written at creation time
308    optional ModelVersionOperation operation = 5;
309  
310    message Response {
311      // Temporary credentials for model version read/write
312      optional TemporaryCredentials credentials = 1;
313    }
314  }
315  
316  enum ModelVersionOperation {
317    UNKNOWN_MODEL_VERSION_OPERATION = 0;
318    READ_MODEL_VERSION = 1;
319    READ_WRITE_MODEL_VERSION = 2;
320  }