trials

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

Overview

Name	trials
Type	Resource
Id	google.aiplatform.trials

Fields

The following fields are returned by SELECT queries:

get

Successful response

Name	Datatype	Description
id	string	Output only. The identifier of the Trial assigned by the service.
name	string	Output only. Resource name of the Trial assigned by the service.
clientId	string	Output only. The identifier of the client that originally requested this Trial. Each client is identified by a unique client_id. When a client asks for a suggestion, Vertex AI Vizier will assign it a Trial. The client should evaluate the Trial, complete it, and report back to Vertex AI Vizier. If suggestion is asked again by same client_id before the Trial is completed, the same Trial will be returned. Multiple clients with different client_ids can ask for suggestions simultaneously, each of them will get their own Trial.
customJob	string	Output only. The CustomJob name linked to the Trial. It's set for a HyperparameterTuningJob's Trial.
endTime	string (google-datetime)	Output only. Time when the Trial's status changed to SUCCEEDED or INFEASIBLE.
finalMeasurement	object	Output only. The final measurement containing the objective value. (id: GoogleCloudAiplatformV1Measurement)
infeasibleReason	string	Output only. A human readable string describing why the Trial is infeasible. This is set only if Trial state is INFEASIBLE.
measurements	array	Output only. A list of measurements that are strictly lexicographically ordered by their induced tuples (steps, elapsed_duration). These are used for early stopping computations.
parameters	array	Output only. The parameters of the Trial.
startTime	string (google-datetime)	Output only. Time when the Trial was started.
state	string	Output only. The detailed state of the Trial.
webAccessUris	object	Output only. URIs for accessing interactive shells (one URI for each training node). Only available if this trial is part of a HyperparameterTuningJob and the job's trial_job_spec.enable_web_access field is true. The keys are names of each node used for the trial; for example, workerpool0-0 for the primary node, workerpool1-0 for the first node in the second worker pool, and workerpool1-1 for the second node in the second worker pool. The values are the URIs for each node's interactive shell.

list

Successful response

Name	Datatype	Description
id	string	Output only. The identifier of the Trial assigned by the service.
name	string	Output only. Resource name of the Trial assigned by the service.
clientId	string	Output only. The identifier of the client that originally requested this Trial. Each client is identified by a unique client_id. When a client asks for a suggestion, Vertex AI Vizier will assign it a Trial. The client should evaluate the Trial, complete it, and report back to Vertex AI Vizier. If suggestion is asked again by same client_id before the Trial is completed, the same Trial will be returned. Multiple clients with different client_ids can ask for suggestions simultaneously, each of them will get their own Trial.
customJob	string	Output only. The CustomJob name linked to the Trial. It's set for a HyperparameterTuningJob's Trial.
endTime	string (google-datetime)	Output only. Time when the Trial's status changed to SUCCEEDED or INFEASIBLE.
finalMeasurement	object	Output only. The final measurement containing the objective value. (id: GoogleCloudAiplatformV1Measurement)
infeasibleReason	string	Output only. A human readable string describing why the Trial is infeasible. This is set only if Trial state is INFEASIBLE.
measurements	array	Output only. A list of measurements that are strictly lexicographically ordered by their induced tuples (steps, elapsed_duration). These are used for early stopping computations.
parameters	array	Output only. The parameters of the Trial.
startTime	string (google-datetime)	Output only. Time when the Trial was started.
state	string	Output only. The detailed state of the Trial.
webAccessUris	object	Output only. URIs for accessing interactive shells (one URI for each training node). Only available if this trial is part of a HyperparameterTuningJob and the job's trial_job_spec.enable_web_access field is true. The keys are names of each node used for the trial; for example, workerpool0-0 for the primary node, workerpool1-0 for the first node in the second worker pool, and workerpool1-1 for the second node in the second worker pool. The values are the URIs for each node's interactive shell.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	projectsId, locationsId, studiesId, trialsId		Gets a Trial.
list	select	projectsId, locationsId, studiesId	pageToken, pageSize	Lists the Trials associated with a Study.
create	insert	projectsId, locationsId, studiesId		Adds a user provided Trial to a Study.
delete	delete	projectsId, locationsId, studiesId, trialsId		Deletes a Trial.
suggest	exec	projectsId, locationsId, studiesId		Adds one or more Trials to a Study, with parameter values suggested by Vertex AI Vizier. Returns a long-running operation associated with the generation of Trial suggestions. When this long-running operation succeeds, it will contain a SuggestTrialsResponse.
add_trial_measurement	exec	projectsId, locationsId, studiesId, trialsId		Adds a measurement of the objective metrics to a Trial. This measurement is assumed to have been taken before the Trial is complete.
complete	exec	projectsId, locationsId, studiesId, trialsId		Marks a Trial as complete.
check_trial_early_stopping_state	exec	projectsId, locationsId, studiesId, trialsId		Checks whether a Trial should stop or not. Returns a long-running operation. When the operation is successful, it will contain a CheckTrialEarlyStoppingStateResponse.
stop	exec	projectsId, locationsId, studiesId, trialsId		Stops a Trial.

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
locationsId	string
projectsId	string
studiesId	string
trialsId	string
pageSize	integer (int32)
pageToken	string

SELECT examples

get

Gets a Trial.

SELECT
id,
name,
clientId,
customJob,
endTime,
finalMeasurement,
infeasibleReason,
measurements,
parameters,
startTime,
state,
webAccessUris
FROM google.aiplatform.trials
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND studiesId = '{{ studiesId }}' -- required
AND trialsId = '{{ trialsId }}' -- required;

list

Lists the Trials associated with a Study.

SELECT
id,
name,
clientId,
customJob,
endTime,
finalMeasurement,
infeasibleReason,
measurements,
parameters,
startTime,
state,
webAccessUris
FROM google.aiplatform.trials
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND studiesId = '{{ studiesId }}' -- required
AND pageToken = '{{ pageToken }}'
AND pageSize = '{{ pageSize }}';

INSERT examples

create

Adds a user provided Trial to a Study.

INSERT INTO google.aiplatform.trials (
projectsId,
locationsId,
studiesId
)
SELECT 
'{{ projectsId }}',
'{{ locationsId }}',
'{{ studiesId }}'
RETURNING
id,
name,
clientId,
customJob,
endTime,
finalMeasurement,
infeasibleReason,
measurements,
parameters,
startTime,
state,
webAccessUris
;

Manifest

# Description fields are for documentation purposes
- name: trials
  props:
    - name: projectsId
      value: string
      description: Required parameter for the trials resource.
    - name: locationsId
      value: string
      description: Required parameter for the trials resource.
    - name: studiesId
      value: string
      description: Required parameter for the trials resource.

DELETE examples

delete

Deletes a Trial.

DELETE FROM google.aiplatform.trials
WHERE projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND studiesId = '{{ studiesId }}' --required
AND trialsId = '{{ trialsId }}' --required;

Lifecycle Methods

suggest

Adds one or more Trials to a Study, with parameter values suggested by Vertex AI Vizier. Returns a long-running operation associated with the generation of Trial suggestions. When this long-running operation succeeds, it will contain a SuggestTrialsResponse.

EXEC google.aiplatform.trials.suggest 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@studiesId='{{ studiesId }}' --required 
@@json=
'{
"suggestionCount": {{ suggestionCount }}, 
"clientId": "{{ clientId }}", 
"contexts": "{{ contexts }}"
}';

add_trial_measurement

Adds a measurement of the objective metrics to a Trial. This measurement is assumed to have been taken before the Trial is complete.

EXEC google.aiplatform.trials.add_trial_measurement 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@studiesId='{{ studiesId }}' --required, 
@trialsId='{{ trialsId }}' --required 
@@json=
'{
"measurement": "{{ measurement }}"
}';

complete

Marks a Trial as complete.

EXEC google.aiplatform.trials.complete 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@studiesId='{{ studiesId }}' --required, 
@trialsId='{{ trialsId }}' --required 
@@json=
'{
"finalMeasurement": "{{ finalMeasurement }}", 
"trialInfeasible": {{ trialInfeasible }}, 
"infeasibleReason": "{{ infeasibleReason }}"
}';

check_trial_early_stopping_state

Checks whether a Trial should stop or not. Returns a long-running operation. When the operation is successful, it will contain a CheckTrialEarlyStoppingStateResponse.

EXEC google.aiplatform.trials.check_trial_early_stopping_state 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@studiesId='{{ studiesId }}' --required, 
@trialsId='{{ trialsId }}' --required;

stop

Stops a Trial.

EXEC google.aiplatform.trials.stop 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@studiesId='{{ studiesId }}' --required, 
@trialsId='{{ trialsId }}' --required;