This page shows you how to create and manage AML AI prediction results. Prediction results are saved to BigQuery tables.
For more information about the content of prediction results, see Understand prediction outputs.
Before you begin
-
To get the permissions that you need to create and manage prediction results, ask your administrator to grant you the Financial Services Admin (
financialservices.admin
) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.You might also be able to get the required permissions through custom roles or other predefined roles.
- Create an instance
- Create a model
- Create a dataset
Create prediction results
Some API methods return a long-running operation (LRO). These methods are asynchronous and return an Operation object; for details, see REST Reference. The operation might not be completed when the method returns a response. For these methods, send the request and then check for the result. In general, all POST, PUT, UPDATE, and DELETE operations are long-running.
Send the request
To create prediction results, use the
projects.locations.instances.predictionResults.create
method.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.v1predictions.create
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the instance; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
: a user-defined identifier for the instanceINSTANCE_ID
: a user-defined identifier for the prediction resultsPREDICTION_RESULTS_ID
: a user-defined identifier for the modelMODEL_ID
: the user-defined identifier for the dataset used for predictions; tables should not have the training label columnsDATASET_ID
: The latest time from which data is used to generate features for predictions. This date should be the same or earlier than the end time of the datasets. Use RFC3339 UTC "Zulu" format (for example,PREDICTION_END_DATE 2014-10-02T15:01:23Z
).
: The number of consecutive months to produce predictions for, ending with the last full month prior to the prediction end date according to the dataset's timezone.PREDICTION_PERIODS
: the name of the output BigQuery dataset used for predictionBQ_OUTPUT_DATASET_NAME
: the user-defined identifier for the output BigQuery table used for predictionsBQ_OUTPUT_PREDICTION_TABLE
: the user-defined identifier for the output explainability BigQuery table used for prediction; remove the optionalBQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE explainabilityDestination
object from the request JSON if you don't want to export to a BigQuery table
: the action that occurs if the destination table already exists; use one of the following values:WRITE_DISPOSITION -
WRITE_EMPTY
: Only export data if the BigQuery table is empty. -
WRITE_TRUNCATE
: Erase all existing data in the BigQuery table before writing to the table.
-
Request JSON body:
{ "model": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /models/MODEL_ID ", "dataset": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /datasets/DATASET_ID ", "endTime": "PREDICTION_END_DATE ", "predictionPeriods": "PREDICTION_PERIODS ", "outputs": { "predictionDestination": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .BQ_OUTPUT_PREDICTION_TABLE ", "writeDisposition": "WRITE_DISPOSITION " }, "explainabilityDestination": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE ", "writeDisposition": "WRITE_DISPOSITION " } } }
To send your request, choose one of these options:
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
cat > request.json << 'EOF' { "model": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /models/MODEL_ID ", "dataset": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /datasets/DATASET_ID ", "endTime": "PREDICTION_END_DATE ", "predictionPeriods": "PREDICTION_PERIODS ", "outputs": { "predictionDestination": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .BQ_OUTPUT_PREDICTION_TABLE ", "writeDisposition": "WRITE_DISPOSITION " }, "explainabilityDestination": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE ", "writeDisposition": "WRITE_DISPOSITION " } } } EOF
Then execute the following command to send your REST request:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults?prediction_result_id=PREDICTION_RESULTS_ID "
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
@' { "model": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /models/MODEL_ID ", "dataset": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /datasets/DATASET_ID ", "endTime": "PREDICTION_END_DATE ", "predictionPeriods": "PREDICTION_PERIODS ", "outputs": { "predictionDestination": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .BQ_OUTPUT_PREDICTION_TABLE ", "writeDisposition": "WRITE_DISPOSITION " }, "explainabilityDestination": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE ", "writeDisposition": "WRITE_DISPOSITION " } } } '@ | Out-File -FilePath request.json -Encoding utf8
Then execute the following command to send your REST request:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults?prediction_result_id=PREDICTION_RESULTS_ID " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID /locations/LOCATION /operations/OPERATION_ID ", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": "2023-03-14T15:52:55.358979323Z", "target": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID ", "verb": "create", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
Check for the result
Use the
projects.locations.operations.get
method to check if prediction results have been created. If the response contains
"done": false
, repeat the command until the response contains "done": true
.
These operations can take a few minutes to several hours to complete.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.operations.get
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the instance; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
: the identifier for the operationOPERATION_ID
To send your request, choose one of these options:
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /operations/OPERATION_ID "
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /operations/OPERATION_ID " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID /locations/LOCATION /operations/OPERATION_ID ", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": "2023-03-14T15:52:55.358979323Z", "endTime": "2023-03-14T16:52:55.358979323Z", "target": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID ", "verb": "create", "requestedCancellation": false, "apiVersion": "v1" }, "done": true, "response": { "@type": "type.googleapis.com/dataresidency.monitoring.DataResidencyAugmentedView", "tpIds": [ "i608e8cf4abb2a7d9-tp" ] } }
Export metadata
To export metadata from prediction results, use the
projects.locations.instances.predictionResults.exportMetadata
method.
For more information, see Exported metadata in the AML output data model.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.v1predictions.exportMetadata
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the instance; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
: the user-defined identifier for the instanceINSTANCE_ID
: the user-defined identifier for the prediction resultsPREDICTION_RESULTS_ID
: a BigQuery dataset in which to export a table that describes the structured metadata of the prediction resultsBQ_OUTPUT_DATASET_NAME
: the table to write the structured metadata toSTRUCTURED_METADATA_TABLE
: the action that occurs if the destination table already exists; use one of the following values:WRITE_DISPOSITION -
WRITE_EMPTY
: Only export data if the BigQuery table is empty. -
WRITE_TRUNCATE
: Erase all existing data in the BigQuery table before writing to the table.
-
Request JSON body:
{ "structuredMetadataDestination": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .STRUCTURED_METADATA_TABLE ", "writeDisposition": "WRITE_DISPOSITION " } }
To send your request, choose one of these options:
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
cat > request.json << 'EOF' { "structuredMetadataDestination": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .STRUCTURED_METADATA_TABLE ", "writeDisposition": "WRITE_DISPOSITION " } } EOF
Then execute the following command to send your REST request:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID :exportMetadata"
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
@' { "structuredMetadataDestination": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .STRUCTURED_METADATA_TABLE ", "writeDisposition": "WRITE_DISPOSITION " } } '@ | Out-File -FilePath request.json -Encoding utf8
Then execute the following command to send your REST request:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID :exportMetadata" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID /locations/LOCATION /operations/OPERATION_ID ", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": "2023-03-14T15:52:55.358979323Z", "target": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID ", "verb": "exportMetadata", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
For more information on how to get the result of the long-running operation (LRO), see Check for the result.
Get prediction results
To get prediction results, use the
projects.locations.instances.predictionResults.get
method.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.v1predictions.get
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the instance; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
: the user-defined identifier for the instanceINSTANCE_ID
: the user-defined identifier for the prediction resultsPREDICTION_RESULTS_ID
To send your request, choose one of these options:
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID "
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID ", "createTime": "2023-03-14T15:52:55.358979323Z", "updateTime": "2023-03-15T15:52:55.358979323Z", "state": "ACTIVE", "model": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /models/MODEL_ID ", "dataset": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /datasets/DATASET_ID ", "endTime": "PREDICTION_END_DATE ", "predictionPeriods":PREDICTION_PERIODS , "outputs": { "predictionDestination": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .BQ_OUTPUT_PREDICTION_TABLE ", "writeDisposition": "WRITE_DISPOSITION " }, "explainabilityDestination": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE ", "writeDisposition": "WRITE_DISPOSITION " } }, "lineOfBusiness": "RETAIL" }
Update prediction results
To update prediction results, use the
projects.locations.instances.predictionResults.patch
method.
Only the labels
field in prediction results can be updated. The following example
updates the key-value pair
user labels
associated with the prediction results.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.v1predictions.update
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the instance; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
: the user-defined identifier for the instanceINSTANCE_ID
: the user-defined identifier for the prediction resultsPREDICTION_RESULTS_ID
: The key in a key-value pair used to organize prediction results. SeeKEY labels
for more information.
: The value in a key-value pair used to organize prediction results. SeeVALUE labels
for more information.
Request JSON body:
{ "labels": { "KEY ": "VALUE " } }
To send your request, choose one of these options:
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
cat > request.json << 'EOF' { "labels": { "KEY ": "VALUE " } } EOF
Then execute the following command to send your REST request:
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID ?updateMask=labels"
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
@' { "labels": { "KEY ": "VALUE " } } '@ | Out-File -FilePath request.json -Encoding utf8
Then execute the following command to send your REST request:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID ?updateMask=labels" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID /locations/LOCATION /operations/OPERATION_ID ", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": "2023-03-14T15:52:55.358979323Z", "target": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID ", "verb": "update", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
For more information on how to get the result of the long-running operation (LRO), see Check for the result.
List the prediction results
To list the prediction results for a given instance, use the
projects.locations.instances.predictionResults.list
method.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.v1predictions.list
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the instance; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
: the user-defined identifier for the instanceINSTANCE_ID
To send your request, choose one of these options:
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults"
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "predictionResults": [ { "name": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID ", "createTime": "2023-03-14T15:52:55.358979323Z", "updateTime": "2023-03-15T15:52:55.358979323Z", "state": "ACTIVE", "model": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /models/MODEL_ID ", "dataset": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /datasets/DATASET_ID ", "endTime": "PREDICTION_END_DATE ", "predictionPeriods":PREDICTION_PERIODS , "outputs": { "predictionDestination": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .BQ_OUTPUT_PREDICTION_TABLE ", "writeDisposition": "WRITE_DISPOSITION " }, "explainabilityDestination": { "tableUri": "bq://PROJECT_ID .BQ_OUTPUT_DATASET_NAME .BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE ", "writeDisposition": "WRITE_DISPOSITION " } }, "lineOfBusiness": "RETAIL" } ] }
Delete prediction results
To delete prediction results, use the
projects.locations.instances.predictionResults.delete
method.
Permissions required for this task
To perform this task, you must have been granted the following permissions:
Permissions
financialservices.v1predictions.delete
Before using any of the request data, make the following replacements:
: your Google Cloud project ID listed in the IAM SettingsPROJECT_ID
: the location of the instance; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
: the user-defined identifier for the instanceINSTANCE_ID
: the user-defined identifier for the prediction resultsPREDICTION_RESULTS_ID
To send your request, choose one of these options:
Execute the following command:
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID "
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID /locations/LOCATION /operations/OPERATION_ID ", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": "2023-03-14T15:52:55.358979323Z", "target": "projects/PROJECT_ID /locations/LOCATION /instances/INSTANCE_ID /predictionResults/PREDICTION_RESULTS_ID ", "verb": "delete", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
For more information on how to get the result of the long-running operation (LRO), see Check for the result.