Method: projects.locations.indexes.upsertDatapoints

Add/update Datapoints into an Index.

HTTP request

POST https://{service-endpoint}/v1/{index}:upsertDatapoints

Where {service-endpoint} is one of the supported service endpoints.

Path parameters

Parameters
index

string

Required. The name of the Index resource to be updated. Format: projects/{project}/locations/{location}/indexes/{index}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "datapoints": [
    {
      object (IndexDatapoint)
    }
  ],
  "updateMask": string
}
Fields
datapoints[]

object (IndexDatapoint)

A list of datapoints to be created/updated.
updateMask

string (FieldMask format)

Optional. Update mask is used to specify the fields to be overwritten in the datapoints by the update. The fields specified in the updateMask are relative to each IndexDatapoint inside datapoints, not the full request.

Updatable fields:

  • Use all_restricts to update both restricts and numericRestricts.

This is a comma-separated list of fully qualified names of fields. Example: "user.displayName,photo".

Response body

If successful, the response body is empty.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the index resource:

  • aiplatform.indexes.update

For more information, see the IAM documentation.

IndexDatapoint

A datapoint of Index.

JSON representation 
{
  "datapointId": string,
  "featureVector": [
    number
  ],
  "restricts": [
    {
      object (Restriction)
    }
  ],
  "numericRestricts": [
    {
      object (NumericRestriction)
    }
  ],
  "crowdingTag": {
    object (CrowdingTag)
  }
}
Fields
datapointId

string

Required. Unique identifier of the datapoint.
featureVector[]

number

Required. feature embedding vector for dense index. An array of numbers with the length of [NearestNeighborSearchConfig.dimensions].
restricts[]

object (Restriction)

Optional. List of Restrict of the datapoint, used to perform "restricted searches" where boolean rule are used to filter the subset of the database eligible for matching. This uses categorical tokens. See: https://cloud.google.com/vertex-ai/docs/matching-engine/filtering
numericRestricts[]

object (NumericRestriction)

Optional. List of Restrict of the datapoint, used to perform "restricted searches" where boolean rule are used to filter the subset of the database eligible for matching. This uses numeric comparisons.
crowdingTag

object (CrowdingTag)

Optional. CrowdingTag of the datapoint, the number of neighbors to return in each crowding can be configured during query.

Restriction

Restriction of a datapoint which describe its attributes(tokens) from each of several attribute categories(namespaces).

JSON representation 
{
  "namespace": string,
  "allowList": [
    string
  ],
  "denyList": [
    string
  ]
}
Fields
namespace

string

The namespace of this restriction. e.g.: color.
allowList[]

string

The attributes to allow in this namespace. e.g.: 'red'
denyList[]

string

The attributes to deny in this namespace. e.g.: 'blue'

NumericRestriction

This field allows restricts to be based on numeric comparisons rather than categorical tokens.

JSON representation 
{
  "namespace": string,
  "op": enum (Operator),

  // Union field Value can be only one of the following:
  "valueInt": string,
  "valueFloat": number,
  "valueDouble": number
  // End of list of possible types for union field Value.
}
Fields
namespace

string

The namespace of this restriction. e.g.: cost.
op

enum (Operator)

This MUST be specified for queries and must NOT be specified for datapoints.
Union field Value. The type of Value must be consistent for all datapoints with a given namespace name. This is verified at runtime. Value can be only one of the following:
valueInt

string (int64 format)

Represents 64 bit integer.
valueFloat

number

Represents 32 bit float.
valueDouble

number

Represents 64 bit float.

Operator

Which comparison operator to use. Should be specified for queries only; specifying this for a datapoint is an error.

Datapoints for which Operator is true relative to the query's value field will be allowlisted.

Enums
OPERATOR_UNSPECIFIED Default value of the enum.
LESS Datapoints are eligible iff their value is < the query's.
LESS_EQUAL Datapoints are eligible iff their value is <= the query's.
EQUAL Datapoints are eligible iff their value is == the query's.
GREATER_EQUAL Datapoints are eligible iff their value is >= the query's.
GREATER Datapoints are eligible iff their value is > the query's.
NOT_EQUAL Datapoints are eligible iff their value is != the query's.

CrowdingTag

Crowding tag is a constraint on a neighbor list produced by nearest neighbor search requiring that no more than some value k' of the k neighbors returned have the same value of crowdingAttribute.

JSON representation 
{
  "crowdingAttribute": string
}
Fields
crowdingAttribute

string

The attribute value used for crowding. The maximum number of neighbors to return per crowding attribute value (perCrowdingAttributeNumNeighbors) is configured per-query. This field is ignored if perCrowdingAttributeNumNeighbors is larger than the total number of neighbors to return for a given query.