models

Creates, updates, deletes, gets or lists a models resource.

Overview

Name	models
Type	Resource
Id	google.retail.models

Fields

The following fields are returned by SELECT queries:

projects_locations_catalogs_models_get

Successful response

Name	Datatype	Description
name	string	Required. The fully qualified resource name of the model. Format: projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/models/{model_id} catalog_id has char limit of 50. recommendation_model_id has char limit of 40.
createTime	string (google-datetime)	Output only. Timestamp the Recommendation Model was created at.
dataState	string	Output only. The state of data requirements for this model: DATA_OK and DATA_ERROR. Recommendation model cannot be trained if the data is in DATA_ERROR state. Recommendation model can have DATA_ERROR state even if serving state is ACTIVE: models were trained successfully before, but cannot be refreshed because model no longer has sufficient data for training.
displayName	string	Required. The display name of the model. Should be human readable, used to display Recommendation Models in the Retail Cloud Console Dashboard. UTF-8 encoded string with limit of 1024 characters.
filteringOption	string	Optional. If RECOMMENDATIONS_FILTERING_ENABLED, recommendation filtering by attributes is enabled for the model.
lastTuneTime	string (google-datetime)	Output only. The timestamp when the latest successful tune finished.
modelFeaturesConfig	object	Optional. Additional model features config. (id: GoogleCloudRetailV2ModelModelFeaturesConfig)
optimizationObjective	string	Optional. The optimization objective e.g. cvr. Currently supported values: ctr, cvr, revenue-per-order. If not specified, we choose default based on model type. Default depends on type of recommendation: recommended-for-you => ctr others-you-may-like => ctr frequently-bought-together => revenue_per_order This field together with optimization_objective describe model metadata to use to control model training and serving. See https://cloud.google.com/retail/docs/models for more details on what the model metadata control and which combination of parameters are valid. For invalid combinations of parameters (e.g. type = frequently-bought-together and optimization_objective = ctr), you receive an error 400 if you try to create/update a recommendation with this set of knobs.
periodicTuningState	string	Optional. The state of periodic tuning. The period we use is 3 months - to do a one-off tune earlier use the TuneModel method. Default value is PERIODIC_TUNING_ENABLED.
servingConfigLists	array	Output only. The list of valid serving configs associated with the PageOptimizationConfig.
servingState	string	Output only. The serving state of the model: ACTIVE, NOT_ACTIVE.
trainingState	string	Optional. The training state that the model is in (e.g. TRAINING or PAUSED). Since part of the cost of running the service is frequency of training - this can be used to determine when to train model in order to control cost. If not specified: the default value for CreateModel method is TRAINING. The default value for UpdateModel method is to keep the state the same as before.
tuningOperation	string	Output only. The tune operation associated with the model. Can be used to determine if there is an ongoing tune for this recommendation. Empty field implies no tune is goig on.
type	string	Required. The type of model e.g. home-page. Currently supported values: recommended-for-you, others-you-may-like, frequently-bought-together, page-optimization, similar-items, buy-it-again, on-sale-items, and recently-viewed(readonly value). This field together with optimization_objective describe model metadata to use to control model training and serving. See https://cloud.google.com/retail/docs/models for more details on what the model metadata control and which combination of parameters are valid. For invalid combinations of parameters (e.g. type = frequently-bought-together and optimization_objective = ctr), you receive an error 400 if you try to create/update a recommendation with this set of knobs.
updateTime	string (google-datetime)	Output only. Timestamp the Recommendation Model was last updated. E.g. if a Recommendation Model was paused - this would be the time the pause was initiated.

projects_locations_catalogs_models_list

Successful response

Name	Datatype	Description
name	string	Required. The fully qualified resource name of the model. Format: projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/models/{model_id} catalog_id has char limit of 50. recommendation_model_id has char limit of 40.
createTime	string (google-datetime)	Output only. Timestamp the Recommendation Model was created at.
dataState	string	Output only. The state of data requirements for this model: DATA_OK and DATA_ERROR. Recommendation model cannot be trained if the data is in DATA_ERROR state. Recommendation model can have DATA_ERROR state even if serving state is ACTIVE: models were trained successfully before, but cannot be refreshed because model no longer has sufficient data for training.
displayName	string	Required. The display name of the model. Should be human readable, used to display Recommendation Models in the Retail Cloud Console Dashboard. UTF-8 encoded string with limit of 1024 characters.
filteringOption	string	Optional. If RECOMMENDATIONS_FILTERING_ENABLED, recommendation filtering by attributes is enabled for the model.
lastTuneTime	string (google-datetime)	Output only. The timestamp when the latest successful tune finished.
modelFeaturesConfig	object	Optional. Additional model features config. (id: GoogleCloudRetailV2ModelModelFeaturesConfig)
optimizationObjective	string	Optional. The optimization objective e.g. cvr. Currently supported values: ctr, cvr, revenue-per-order. If not specified, we choose default based on model type. Default depends on type of recommendation: recommended-for-you => ctr others-you-may-like => ctr frequently-bought-together => revenue_per_order This field together with optimization_objective describe model metadata to use to control model training and serving. See https://cloud.google.com/retail/docs/models for more details on what the model metadata control and which combination of parameters are valid. For invalid combinations of parameters (e.g. type = frequently-bought-together and optimization_objective = ctr), you receive an error 400 if you try to create/update a recommendation with this set of knobs.
periodicTuningState	string	Optional. The state of periodic tuning. The period we use is 3 months - to do a one-off tune earlier use the TuneModel method. Default value is PERIODIC_TUNING_ENABLED.
servingConfigLists	array	Output only. The list of valid serving configs associated with the PageOptimizationConfig.
servingState	string	Output only. The serving state of the model: ACTIVE, NOT_ACTIVE.
trainingState	string	Optional. The training state that the model is in (e.g. TRAINING or PAUSED). Since part of the cost of running the service is frequency of training - this can be used to determine when to train model in order to control cost. If not specified: the default value for CreateModel method is TRAINING. The default value for UpdateModel method is to keep the state the same as before.
tuningOperation	string	Output only. The tune operation associated with the model. Can be used to determine if there is an ongoing tune for this recommendation. Empty field implies no tune is goig on.
type	string	Required. The type of model e.g. home-page. Currently supported values: recommended-for-you, others-you-may-like, frequently-bought-together, page-optimization, similar-items, buy-it-again, on-sale-items, and recently-viewed(readonly value). This field together with optimization_objective describe model metadata to use to control model training and serving. See https://cloud.google.com/retail/docs/models for more details on what the model metadata control and which combination of parameters are valid. For invalid combinations of parameters (e.g. type = frequently-bought-together and optimization_objective = ctr), you receive an error 400 if you try to create/update a recommendation with this set of knobs.
updateTime	string (google-datetime)	Output only. Timestamp the Recommendation Model was last updated. E.g. if a Recommendation Model was paused - this would be the time the pause was initiated.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
projects_locations_catalogs_models_get	select	projectsId, locationsId, catalogsId, modelsId		Gets a model.
projects_locations_catalogs_models_list	select	projectsId, locationsId, catalogsId	pageSize, pageToken	Lists all the models linked to this event store.
projects_locations_catalogs_models_create	insert	projectsId, locationsId, catalogsId	dryRun	Creates a new model.
projects_locations_catalogs_models_patch	update	projectsId, locationsId, catalogsId, modelsId	updateMask	Update of model metadata. Only fields that currently can be updated are: filtering_option and periodic_tuning_state. If other values are provided, this API method ignores them.
projects_locations_catalogs_models_delete	delete	projectsId, locationsId, catalogsId, modelsId		Deletes an existing model.
projects_locations_catalogs_models_pause	exec	projectsId, locationsId, catalogsId, modelsId		Pauses the training of an existing model.
projects_locations_catalogs_models_resume	exec	projectsId, locationsId, catalogsId, modelsId		Resumes the training of an existing model.
projects_locations_catalogs_models_tune	exec	projectsId, locationsId, catalogsId, modelsId		Tunes an existing model.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
catalogsId	string
locationsId	string
modelsId	string
projectsId	string
dryRun	boolean
pageSize	integer (int32)
pageToken	string
updateMask	string (google-fieldmask)

SELECT examples

projects_locations_catalogs_models_get

Gets a model.

SELECT
name,
createTime,
dataState,
displayName,
filteringOption,
lastTuneTime,
modelFeaturesConfig,
optimizationObjective,
periodicTuningState,
servingConfigLists,
servingState,
trainingState,
tuningOperation,
type,
updateTime
FROM google.retail.models
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND catalogsId = '{{ catalogsId }}' -- required
AND modelsId = '{{ modelsId }}' -- required;

projects_locations_catalogs_models_list

Lists all the models linked to this event store.

SELECT
name,
createTime,
dataState,
displayName,
filteringOption,
lastTuneTime,
modelFeaturesConfig,
optimizationObjective,
periodicTuningState,
servingConfigLists,
servingState,
trainingState,
tuningOperation,
type,
updateTime
FROM google.retail.models
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND catalogsId = '{{ catalogsId }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}';

INSERT examples

projects_locations_catalogs_models_create

Creates a new model.

INSERT INTO google.retail.models (
data__name,
data__displayName,
data__trainingState,
data__type,
data__optimizationObjective,
data__periodicTuningState,
data__filteringOption,
data__modelFeaturesConfig,
projectsId,
locationsId,
catalogsId,
dryRun
)
SELECT 
'{{ name }}',
'{{ displayName }}',
'{{ trainingState }}',
'{{ type }}',
'{{ optimizationObjective }}',
'{{ periodicTuningState }}',
'{{ filteringOption }}',
'{{ modelFeaturesConfig }}',
'{{ projectsId }}',
'{{ locationsId }}',
'{{ catalogsId }}',
'{{ dryRun }}'
RETURNING
name,
done,
error,
metadata,
response
;

Manifest

# Description fields are for documentation purposes
- name: models
  props:
    - name: projectsId
      value: string
      description: Required parameter for the models resource.
    - name: locationsId
      value: string
      description: Required parameter for the models resource.
    - name: catalogsId
      value: string
      description: Required parameter for the models resource.
    - name: name
      value: string
      description: >
        Required. The fully qualified resource name of the model. Format: `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/models/{model_id}` catalog_id has char limit of 50. recommendation_model_id has char limit of 40.
        
    - name: displayName
      value: string
      description: >
        Required. The display name of the model. Should be human readable, used to display Recommendation Models in the Retail Cloud Console Dashboard. UTF-8 encoded string with limit of 1024 characters.
        
    - name: trainingState
      value: string
      description: >
        Optional. The training state that the model is in (e.g. `TRAINING` or `PAUSED`). Since part of the cost of running the service is frequency of training - this can be used to determine when to train model in order to control cost. If not specified: the default value for `CreateModel` method is `TRAINING`. The default value for `UpdateModel` method is to keep the state the same as before.
        
      valid_values: ['TRAINING_STATE_UNSPECIFIED', 'PAUSED', 'TRAINING']
    - name: type
      value: string
      description: >
        Required. The type of model e.g. `home-page`. Currently supported values: `recommended-for-you`, `others-you-may-like`, `frequently-bought-together`, `page-optimization`, `similar-items`, `buy-it-again`, `on-sale-items`, and `recently-viewed`(readonly value). This field together with optimization_objective describe model metadata to use to control model training and serving. See https://cloud.google.com/retail/docs/models for more details on what the model metadata control and which combination of parameters are valid. For invalid combinations of parameters (e.g. type = `frequently-bought-together` and optimization_objective = `ctr`), you receive an error 400 if you try to create/update a recommendation with this set of knobs.
        
    - name: optimizationObjective
      value: string
      description: >
        Optional. The optimization objective e.g. `cvr`. Currently supported values: `ctr`, `cvr`, `revenue-per-order`. If not specified, we choose default based on model type. Default depends on type of recommendation: `recommended-for-you` => `ctr` `others-you-may-like` => `ctr` `frequently-bought-together` => `revenue_per_order` This field together with optimization_objective describe model metadata to use to control model training and serving. See https://cloud.google.com/retail/docs/models for more details on what the model metadata control and which combination of parameters are valid. For invalid combinations of parameters (e.g. type = `frequently-bought-together` and optimization_objective = `ctr`), you receive an error 400 if you try to create/update a recommendation with this set of knobs.
        
    - name: periodicTuningState
      value: string
      description: >
        Optional. The state of periodic tuning. The period we use is 3 months - to do a one-off tune earlier use the `TuneModel` method. Default value is `PERIODIC_TUNING_ENABLED`.
        
      valid_values: ['PERIODIC_TUNING_STATE_UNSPECIFIED', 'PERIODIC_TUNING_DISABLED', 'ALL_TUNING_DISABLED', 'PERIODIC_TUNING_ENABLED']
    - name: filteringOption
      value: string
      description: >
        Optional. If `RECOMMENDATIONS_FILTERING_ENABLED`, recommendation filtering by attributes is enabled for the model.
        
      valid_values: ['RECOMMENDATIONS_FILTERING_OPTION_UNSPECIFIED', 'RECOMMENDATIONS_FILTERING_DISABLED', 'RECOMMENDATIONS_FILTERING_ENABLED']
    - name: modelFeaturesConfig
      value: object
      description: >
        Optional. Additional model features config.
        
    - name: dryRun
      value: boolean

UPDATE examples

projects_locations_catalogs_models_patch

Update of model metadata. Only fields that currently can be updated are: filtering_option and periodic_tuning_state. If other values are provided, this API method ignores them.

UPDATE google.retail.models
SET 
data__name = '{{ name }}',
data__displayName = '{{ displayName }}',
data__trainingState = '{{ trainingState }}',
data__type = '{{ type }}',
data__optimizationObjective = '{{ optimizationObjective }}',
data__periodicTuningState = '{{ periodicTuningState }}',
data__filteringOption = '{{ filteringOption }}',
data__modelFeaturesConfig = '{{ modelFeaturesConfig }}'
WHERE 
projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND catalogsId = '{{ catalogsId }}' --required
AND modelsId = '{{ modelsId }}' --required
AND updateMask = '{{ updateMask}}'
RETURNING
name,
createTime,
dataState,
displayName,
filteringOption,
lastTuneTime,
modelFeaturesConfig,
optimizationObjective,
periodicTuningState,
servingConfigLists,
servingState,
trainingState,
tuningOperation,
type,
updateTime;

DELETE examples

projects_locations_catalogs_models_delete

Deletes an existing model.

DELETE FROM google.retail.models
WHERE projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND catalogsId = '{{ catalogsId }}' --required
AND modelsId = '{{ modelsId }}' --required;

Lifecycle Methods

projects_locations_catalogs_models_pause

Pauses the training of an existing model.

EXEC google.retail.models.projects_locations_catalogs_models_pause 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@catalogsId='{{ catalogsId }}' --required, 
@modelsId='{{ modelsId }}' --required;

projects_locations_catalogs_models_resume

Resumes the training of an existing model.

EXEC google.retail.models.projects_locations_catalogs_models_resume 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@catalogsId='{{ catalogsId }}' --required, 
@modelsId='{{ modelsId }}' --required;

projects_locations_catalogs_models_tune

Tunes an existing model.

EXEC google.retail.models.projects_locations_catalogs_models_tune 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@catalogsId='{{ catalogsId }}' --required, 
@modelsId='{{ modelsId }}' --required;