Create and manage hypernyms

Restrictions

There are a few restrictions on how you can use custom hypernyms and synonyms:

  • The mapping size is limited. For example, one string cannot be mapped to more than eight other strings.
  • The strings that you use in the mapping must only be letters and numbers between 2 and 50 characters long.

Create a search hypernym

REST

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

  • REGIONALIZED_ENDPOINT: Endpoint might include a prefix matching the LOCATION_ID such as europe-west4-. See more about regionalized endpoints.
  • PROJECT_NUMBER: Your Google Cloud project number.
  • LOCATION_ID: The region where you are using Vertex AI Vision. For example: us-central1, europe-west4. See available regions.
  • CORPUS_ID: The ID of your target corpus.
  • HYPERNYM_ID: The search hypernym id. If omitted, a random UUID is generated.

HTTP method and URL: 

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms?search_hypernym_id={HYPERNYM_ID}

Request JSON body: 

{
  "hypernym": "HYPERNYM",
  "hyponyms": "HYPONYM_1",
  "hyponyms": "HYPONYM_2",
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms?search_hypernym_id={HYPERNYM_ID}"

PowerShell

Save the request body in a file named request.json, and execute the following command: 

$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://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms?search_hypernym_id={HYPERNYM_ID}" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms/HYPERNYM_ID",
}

Update a search hypernym

REST & CMD LINE

The following code updates a search hypernym of the given hypernym ID specified.

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

  • REGIONALIZED_ENDPOINT: Endpoint might include a prefix matching the LOCATION_ID such as europe-west4-. See more about regionalized endpoints.
  • PROJECT_NUMBER: Your Google Cloud project number.
  • LOCATION_ID: The region where you are using Vertex AI Vision. For example: us-central1, europe-west4. See available regions.
  • CORPUS_ID: The ID of your target corpus.
  • HYPERNYM_ID: The search hypernym id. If omitted, a random UUID is generated.

HTTP method and URL: 

PATCH https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms/HYPERNYM_ID

Request JSON body: 

{
  "hypernym": "UPDATED_HYPERNYM",
  "hyponyms": "UPDATED_HYPONYM_1",
  "hyponyms": "UPDATED_HYPONYM_2",
  "hyponyms": "UPDATED_HYPONYM_3",
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command: 

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms/HYPERNYM_ID"

PowerShell

Save the request body in a file named request.json, and execute the following command: 

$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://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms/HYPERNYM_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms/HYPERNYM_ID",
  "hypernym": "UPDATED_HYPERNYM",
  "hyponyms": "UPDATED_HYPONYM_1",
  "hyponyms": "UPDATED_HYPONYM_2",
  "hyponyms": "UPDATED_HYPONYM_3",
}

Get a search hypernym

REST & CMD LINE

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

  • REGIONALIZED_ENDPOINT: Endpoint might include a prefix matching the LOCATION_ID such as europe-west4-. See more about regionalized endpoints.
  • PROJECT_NUMBER: Your Google Cloud project number.
  • LOCATION_ID: The region where you are using Vertex AI Vision. For example: us-central1, europe-west4. See available regions.
  • CORPUS_ID: The ID of your target corpus.
  • HYPERNYM_ID: The search hypernym id. If omitted, a random UUID is generated.

HTTP method and URL: 

GET https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms/HYPERNYM_ID

To send your request, choose one of these options:

curl

Execute the following command: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms/HYPERNYM_ID"

PowerShell

Execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms/HYPERNYM_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms/HYPERNYM_ID",
  "hypernym": "HYPERNYM",
  "hyponyms": "HYPONYM_1",
  "hyponyms": "HYPONYM_2",
}

List search hypernyms

REST & CMD LINE

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

  • REGIONALIZED_ENDPOINT: Endpoint might include a prefix matching the LOCATION_ID such as europe-west4-. See more about regionalized endpoints.
  • PROJECT_NUMBER: Your Google Cloud project number.
  • LOCATION_ID: The region where you are using Vertex AI Vision. For example: us-central1, europe-west4. See available regions.
  • CORPUS_ID: The ID of your target corpus.

HTTP method and URL: 

GET https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms

To send your request, choose one of these options:

curl

Execute the following command: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms"

PowerShell

Execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  {
    "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms/HYPERNYM_ID_1",
    "hypernym": "HYPERNYM_1",
    "hyponyms": "HYPONYM_1",
    "hyponyms": "HYPONYM_2",
  }
  {
    "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms/HYPERNYM_ID_2",
    "hypernym": "HYPERNYM_2",
    "hyponyms": "HYPONYM_3",
    "hyponyms": "HYPONYM_4",
  }
}

Delete a search hypernym

REST & CMD LINE

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

  • REGIONALIZED_ENDPOINT: Endpoint might include a prefix matching the LOCATION_ID such as europe-west4-. See more about regionalized endpoints.
  • PROJECT_NUMBER: Your Google Cloud project number.
  • LOCATION_ID: The region where you are using Vertex AI Vision. For example: us-central1, europe-west4. See available regions.
  • CORPUS_ID: The ID of your target corpus.
  • HYPERNYM_ID: The search hypernym id. If omitted, a random UUID is generated.

HTTP method and URL: 

DELETE https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms/HYPERNYM_ID

To send your request, choose one of these options:

curl

Execute the following command: 

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms/HYPERNYM_ID"

PowerShell

Execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchHypernyms/HYPERNYM_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{ }