Filtering when listing

You can use filtering to return more specific results when listing resources, evaluations, or operations.

Key point: In general, you filter by appending the following syntax to the request URL:

• ?filter="[filter_name=]filter-value" - returns all JSON objects that match the filter-value.
• ?filter="" - an unset filter. No matches are returned.
• ?filter="*" - a filter that matches all possible values.

Operations

You can filter listed operations using the following parameters:

Filters

• operation_id - returns all operations with an ID equal to the provided value. You can also specify operations not equal (!=) to a certain value.
• done - returns all operations with a status of "done": true. You can also specify operations that are still ongoing (not "done").

  Queries:

  • ?filter="done=true"
  • ?filter="done!=true"
• worksOn - returns all operations that work on a resource (dataset or model). You can also specify operations not equal (!=) to a certain value.

  Queries:

  • dataset - ?filter="worksOn=projects/project-id/locations/us-central1/datasets/dataset-id"
  • model - ?filter="worksOn=projects/project-id/locations/us-central1/models/model-id"

Additional query parameters

• pageSize - Limits the results returned to a set number of lines. If not specified, the server will choose a default size.
• pageToken - A token to retrieve next page of results. An initial query with a set pageSize and results greater than will fit on that page size also returns a nextPageToken. This token can then be passed to pageToken to get subsequent results.

The following command line code sample shows how to filter listed operations by operations that are completed (have a status of "done": true).

Before using any of the request data, make the following replacements:

• project-id: your Google Cloud Platform project ID.

HTTP method and URL:

GET https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/operations?filter="done=true"

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     "https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/operations?filter="done=true""

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/operations?filter="done=true"" | Select-Object -Expand Content

If the request is successful, the server returns a 200 OK HTTP status code and the response in JSON format.

The following response is from a project with multiple AutoML operations, filtered by operations that have completed (?filter="done=true").

Response

{
  "operations": [
    {
      "name": "projects/project-id/locations/us-central1/operations/VCN1765936620487311360",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.automl.v1.OperationMetadata",
        "createTime": "2019-12-12T19:50:54.701276Z",
        "updateTime": "2019-12-12T21:44:41.398588Z",
        "createModelDetails": {}
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.cloud.automl.v1.Model",
        "name": "projects/project-id/locations/us-central1/models/VCN3089482538515693568"
      }
    },
    {
      "name": "projects/project-id/locations/us-central1/operations/ICN4019988233986244608",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.automl.v1.OperationMetadata",
        "partialFailures": [
          {
            "code": 3,
            "message": "Error: gs://storage-bucket/csv/all_data.csv line 2269: The label is already a ground truth."
          },
          {
            "code": 3,
            "message": "Error: Single label example 6192816919589105442 can have at most one approved positive annotation."
          },
          {
            "code": 3,
            "message": "Error: gs://storage-bucket/csv/all_data.csv line 2267: The label is already a ground truth."
          }
        ],
        "createTime": "2019-12-12T20:24:26.992578Z",
        "updateTime": "2019-12-12T20:40:39.672070Z",
        "importDataDetails": {}
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.protobuf.Empty"
      }
    },
    {
      "name": "projects/project-id/locations/us-central1/operations/TBL1400159888251813888",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.automl.v1.OperationMetadata",
        "createTime": "2019-12-11T23:08:07.315450Z",
        "updateTime": "2019-12-12T00:48:44.703974Z",
        "createModelDetails": {}
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.cloud.automl.v1.Model",
        "name": "projects/project-id/locations/us-central1/models/TBL5737009781177057280"
      }
    },
    {
      "name": "projects/project-id/locations/us-central1/operations/TBL7492967234130673664",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.automl.v1.OperationMetadata",
        "createTime": "2019-12-11T23:07:36.217459Z",
        "updateTime": "2019-12-11T23:08:17.727121Z",
        "createModelDetails": {}
      },
      "done": true,
      "error": {
        "code": 1,
        "message": "CANCELLED"
      }
    },
    {
      "name": "projects/project-id/locations/us-central1/operations/TBL6841634138022215680",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.automl.v1.OperationMetadata",
        "createTime": "2019-12-11T23:02:56.089038Z",
        "updateTime": "2019-12-11T23:02:59.300928Z",
        "deleteDetails": {}
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.protobuf.Empty"
      }
    },
    {
      "name": "projects/project-id/locations/us-central1/operations/TBL8322192515520266240",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.automl.v1.OperationMetadata",
        "createTime": "2019-12-11T22:57:14.840747Z",
        "updateTime": "2019-12-11T22:59:00.764354Z",
        "importDataDetails": {}
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.protobuf.Empty"
      }
    },
    {
      "name": "projects/project-id/locations/us-central1/operations/TCN7841151780321755136",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.automl.v1.OperationMetadata",
        "partialFailures": [
          {
            "code": 3,
            "message": "Error: DUPLICATE_CONTENT: Duplicated content detected. Multiple documents (line 2552 and line 3528) share the same content."
          },
          {
            "code": 3,
            "message": "Error: gs://automl-docs-filtering-vcm/happiness.csv line 3527: The label is already a ground truth."
          }
        ],
        "createTime": "2019-12-11T22:22:40.789066Z",
        "updateTime": "2019-12-11T22:36:40.388359Z",
        "importDataDetails": {}
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.protobuf.Empty"
      }
    }
  ]
}

Additional query parameters

To query with other parameters (pageSize, pageToken) append the parameter to the URL:

https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/model/model-id/modelEvaluations?pageSize=INT

You can also concatenate parameters with an ampersand (&):

https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/model/model-id/modelEvaluations?filter="done=true&pageSize=INT&pageToken=next-page-token"

Datasets

You can filter listed datasets using the following parameters:

Filters

• dataset_metadata - returns all datasets with the target metadata type.

  Available values

  • imageClassificationDatasetMetadata:* (AutoML Vision - Image Classification)
  • imageObjectDetectionDatasetMetadata:* (AutoML Vision - Object Detection)
  • textClassificationDatasetMetadata:* (AutoML Natural Language - Classification)
  • textExtractionDatasetMetadata:* (AutoML Natural Language - Entity Extraction)
  • textSentimentDatasetMetadata:* (AutoML Natural Language - Sentiment Analysis)
  • translationDatasetMetadata:* (AutoML Translation)

Additional query parameters

• pageSize - Limits the results returned to a set number of lines. If not specified, the server will choose a default size.
• pageToken - A token to retrieve next page of results. An initial query with a set pageSize and results greater than will fit on that page size also returns a nextPageToken. This token can then be passed to pageToken to get subsequent results.

The following command line code sample shows how to filter listed datasets by specifying the dataset_metadata.

Before using any of the request data, make the following replacements:

• project-id: your Google Cloud Platform project ID.
• dataset-metadata-value: the type of dataset_metadata you are filtering. These values depend on the AutoML problem type.

HTTP method and URL:

GET https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/datasets?filter="dataset-metadata-value"

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     "https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/datasets?filter="dataset-metadata-value""

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/datasets?filter="dataset-metadata-value"" | Select-Object -Expand Content

If the request is successful, the server returns a 200 OK HTTP status code and the response in JSON format.

The following response is from a project with multiple AutoML dataset types, filtered for AutoML Translation datasets (?filter="translationDatasetMetadata:*").

Response:

Response

{
  "datasets": [
    {
      "name": "projects/project-id/locations/us-central1/datasets/dataset-id1",
      "displayName": "display-name1",
      "createTime": "2019-12-12T16:47:46.087383Z",
      "etag": "AB3BwFoNzSb-7OEMHn3QQb1sa2Xs5cJ4S5J1UlkYWbQlCAntibE1rbOzVFzTpSIRWek=",
      "exampleCount": 8720,
      "translationDatasetMetadata": {
        "sourceLanguageCode": "en",
        "targetLanguageCode": "es"
      }
    },
    {
      "name": "projects/project-id/locations/us-central1/datasets/dataset-id2",
      "displayName": "display-name2",
      "createTime": "2019-12-12T16:46:05.674490Z",
      "etag": "AB3BwFqxV5dZHNxry9nuJTX3KwpPENGT0cdop39h8rzryec3umRU-daaPztYwLCZMV2J",
      "exampleCount": 8720,
      "translationDatasetMetadata": {
        "sourceLanguageCode": "en",
        "targetLanguageCode": "es"
      }
    },
    {
      "name": "projects/project-id/locations/us-central1/datasets/dataset-id3",
      "displayName": "display-name3",
      "createTime": "2019-12-12T16:43:19.988997Z",
      "etag": "AB3BwFqulR4Lud3ndHJIrzrOYkaQORNw3rzZM4WR9_xzvvu_iG45CEvmG_ph2QXnR3m7",
      "exampleCount": 8720,
      "translationDatasetMetadata": {
        "sourceLanguageCode": "en",
        "targetLanguageCode": "es"
      }
    }
  ]
}

Additional query parameters

To query with other parameters (pageSize, pageToken) append the parameter to the URL:

https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/datasets?pageSize=INT

You can also concatenate parameters with an ampersand (&):

https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/datasets?filter="dataset-metadata-value&pageSize=INT&pageToken=next-page-token"

Models

You can filter listed models using the following parameters:

Filters

• model_metadata - returns all models with the target metadata type.

  Available values

  • imageClassificationModelMetadata:* (AutoML Vision - Image Classification)
  • imageObjectDetectionModelMetadata:* (AutoML Vision - Object Detection)
  • textClassificationModelMetadata:* (AutoML Natural Language - Classification)
  • textExtractionModelMetadata:* (AutoML Natural Language - Entity Extraction)
  • textSentimentModelMetadata:* (AutoML Natural Language - Sentiment Analysis)
  • translationModelMetadata:* (AutoML Translation)
• datasetId - returns all models created from a specific dataset.

Additional query parameters

• pageSize - Limits the results returned to a set number of lines. If not specified, the server will choose a default size.
• pageToken - A token to retrieve next page of results. An initial query with a set pageSize and results greater than will fit on that page size also returns a nextPageToken. This token can then be passed to pageToken to get subsequent results.

The following command line code sample shows how to filter listed models by specifying the model_metadata.

Before using any of the request data, make the following replacements:

• project-id: your Google Cloud Platform project ID.
• model-metadata-value: the type of model_metadata you are filtering. These values depend on the AutoML problem type.

HTTP method and URL:

GET https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/models?filter="model-metadata-value"

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     "https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/models?filter="model-metadata-value""

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/models?filter="model-metadata-value"" | Select-Object -Expand Content

If the request is successful, the server returns a 200 OK HTTP status code and the response in JSON format.

The following response is from a project with multiple AutoML model types, filtered for AutoML Natural Language models (?filter="textClassificationModelMetadata:*").

Response

{
  "model": [
    {
      "name": "projects/project-id/locations/us-central1/models/model-id1",
      "displayName": "display-name1",
      "datasetId": "dataset-id",
      "createTime": "2019-12-11T22:45:24.351490Z",
      "deploymentState": "UNDEPLOYED",
      "updateTime": "2019-12-12T16:07:03.117529Z",
      "textClassificationModelMetadata": {
        "classificationType": "MULTICLASS"
      }
    },
    {
      "name": "projects/project-id/locations/us-central1/models/model-id2",
      "displayName": "display-name2",
      "datasetId": "dataset-id",
      "createTime": "2019-12-11T22:44:45.865731Z",
      "deploymentState": "UNDEPLOYED",
      "updateTime": "2019-12-12T16:04:42.287184Z",
      "textClassificationModelMetadata": {
        "classificationType": "MULTICLASS"
      }
    },
    {
      "name": "projects/project-id/locations/us-central1/models/model-id3",
      "displayName": "display-name2",
      "datasetId": "dataset-id",
      "createTime": "2019-12-11T22:45:05.000640Z",
      "deploymentState": "DEPLOYED",
      "updateTime": "2019-12-12T02:34:15.294401Z",
      "textClassificationModelMetadata": {
        "classificationType": "MULTICLASS"
      }
    }
  ]
}

Additional query parameters

To query with other parameters (pageSize, pageToken) append the parameter to the URL:

https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/models?pageSize=INT

You can also concatenate parameters with an ampersand (&):

https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/models?filter="model-metadata-value&pageSize=INT&pageToken=next-page-token"

modelEvaulations

You can filter listed model evaluations using the following parameters:

Filters

• annotationSpecId - returns all model evaluations with an ID equal to the provided value. You can also specify model evaulations not equal (!=) to a certain value.

Additional query parameters

• pageSize - Limits the results returned to a set number of lines. If not specified, the server will choose a default size.
• pageToken - A token to retrieve next page of results. An initial query with a set pageSize and results greater than will fit on that page size also returns a nextPageToken. This token can then be passed to pageToken to get subsequent results.

The following command line code sample shows how to filter listed model evaluations by specifying the annotationSpecId.

Before using any of the request data, make the following replacements:

• project-id: your Google Cloud Platform project ID.
• model-id: the ID of the model you want evaluations for.
• annotation-spec-id: The ID of the annotation spec that the model evaluation applies to. The The ID is empty for the overall model evaluation.

HTTP method and URL:

GET https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/models/model-id/modelEvaluations?filter="annotationSpecId=annotation-spec-id"

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     "https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/models/model-id/modelEvaluations?filter="annotationSpecId=annotation-spec-id""

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/models/model-id/modelEvaluations?filter="annotationSpecId=annotation-spec-id"" | Select-Object -Expand Content

If the request is successful, the server returns a 200 OK HTTP status code and the response in JSON format.

The following response is from a project with multiple AutoML model types, filtered for model evaluations from a single model (?filter="annotationSpecId=1231173747155664896").

Response

{
  "modelEvaluation": [
    {
      "name": "projects/project-id/locations/us-central1/models/model-id/modelEvaluations/model-evaluation-id",
      "annotationSpecId": "1231173747155664896",
      "createTime": "2019-12-12T21:39:22.737188Z",
      "evaluatedExampleCount": 150,
      "classificationEvaluationMetrics": {
        "auPrc": 1,
        "confidenceMetricsEntry": [
          {
            "confidenceThreshold": 0.915923,
            "recall": 1,
            "precision": 1,
            "f1Score": 1,
            "recallAt1": 1,
            "precisionAt1": 1,
            "f1ScoreAt1": 1
          },
          {
            "confidenceThreshold": 0.91773844,
            "recall": 0.96666664,
            "precision": 1,
            "f1Score": 0.9830508,
            "recallAt1": 0.96666664,
            "precisionAt1": 1,
            "f1ScoreAt1": 0.9830508
          },
          {
            "confidenceThreshold": 0.922848,
            "recall": 0.93333334,
            "precision": 1,
            "f1Score": 0.9655172,
            "recallAt1": 0.93333334,
            "precisionAt1": 1,
            "f1ScoreAt1": 0.9655172
          },
          {
            "confidenceThreshold": 0.93254685,
            "recall": 0.9,
            "precision": 1,
            "f1Score": 0.94736844,
            "recallAt1": 0.9,
            "precisionAt1": 1,
            "f1ScoreAt1": 0.94736844
          },
          ...
          {
            "confidenceThreshold": 0.9732056,
            "recall": 0.13333334,
            "precision": 1,
            "f1Score": 0.23529412,
            "recallAt1": 0.13333334,
            "precisionAt1": 1,
            "f1ScoreAt1": 0.23529412
          },
          {
            "confidenceThreshold": 0.97356653,
            "recall": 0.1,
            "precision": 1,
            "f1Score": 0.18181819,
            "recallAt1": 0.1,
            "precisionAt1": 1,
            "f1ScoreAt1": 0.18181819
          },
          {
            "confidenceThreshold": 0.97429,
            "recall": 0.06666667,
            "precision": 1,
            "f1Score": 0.125,
            "recallAt1": 0.06666667,
            "precisionAt1": 1,
            "f1ScoreAt1": 0.125
          },
          {
            "confidenceThreshold": 0.9773706,
            "recall": 0.033333335,
            "precision": 1,
            "f1Score": 0.06451613,
            "recallAt1": 0.033333335,
            "precisionAt1": 1,
            "f1ScoreAt1": 0.06451613
          },
          {
            "confidenceThreshold": 1,
            "precision": 1
          }
        ],
        "confusionMatrix": {}
      },
      "displayName": "golf"
    }
  ]
}

Additional query parameters

To query with other parameters (pageSize, pageToken) append the parameter to the URL:

https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/model/model-id/modelEvaluations?pageSize=INT

You can also concatenate parameters with an ampersand (&):

https://automl.googleapis.com/v1/projects/project-id/locations/us-central1/model/model-id/modelEvaluations?filter="annotationSpecId=annotation-spec-id&pageSize=INT&pageToken=next-page-token"