MCP Tools Reference: vectorsearch.googleapis.com

工具：search_data_objects

对集合执行 Vector Search。

以下代码示例展示了如何使用 curl 调用 search_data_objects MCP 工具。

Curl 请求 
curl --location 'https://vectorsearch.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_data_objects",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

对 search_data_objects 的请求。

SearchDataObjectsRequest

JSON 表示法 
{
  "projectId": string,
  "location": string,
  "collectionId": string,
  "pageSize": integer,
  "pageToken": string,

  // Union field search_type can be only one of the following:
  "vectorSearch": {
    object (VectorSearch)
  },
  "semanticSearch": {
    object (SemanticSearch)
  },
  "textSearch": {
    object (TextSearch)
  }
  // End of list of possible types for union field search_type.
}
字段
projectId

string

必需。项目 ID 或编号。
location

string

必需。集合所在的区域，例如 us-central1。
collectionId

string

必需。要搜索的集合的 ID。
pageSize

integer

可选。标准列表页面大小。仅支持 KNN。如果未设置，系统最多会返回 search_type.top_k 个结果。最大值为 1,000；大于 1,000 的值将被强制转换为 1,000。
pageToken

string

可选。上一个 search_data_objects 调用中的标准列表页面令牌。
联合字段 search_type。要搜索的查询。search_type 只能是下列其中一项：
vectorSearch

object (VectorSearch)

向量搜索操作。
semanticSearch

object (SemanticSearch)

语义搜索操作。
textSearch

object (TextSearch)

可选。文本搜索操作。

VectorSearch

JSON 表示法 
{
  "searchField": string,
  "filter": {
    object
  },
  "outputFields": {
    object (OutputFields)
  },
  "searchHint": {
    object (SearchHint)
  },
  "distanceMetric": enum (DistanceMetric),

  // Union field vector_type can be only one of the following:
  "vector": {
    object (DenseVector)
  },
  "sparseVector": {
    object (SparseVector)
  }
  // End of list of possible types for union field vector_type.

  // Union field _top_k can be only one of the following:
  "topK": integer
  // End of list of possible types for union field _top_k.
}
字段
searchField

string

必需。要搜索的向量字段。
filter

object (Struct format)

可选。JSON 过滤表达式，例如 {"genre": {"$eq": "sci-fi"}}，表示为 google.protobuf.Struct。

空过滤条件 ({}) 会匹配所有数据对象。否则，过滤条件中的每个 JSON 对象都必须恰好有一个键：映射到一个运算符 ({"price": {"$lt": 100}}) 的字段名称，或逻辑运算符：$and 或 $or（后跟过滤条件列表），或 $not（后跟一个过滤条件）。字段运算符及其值：$eq 和 $ne 接受字符串、数字或布尔值；$lt、$lte、$gt 和 $gte 接受数字；$in、$nin 和 $all 接受字符串列表；$exists 接受布尔值。一个对象中的多个键（隐式 AND）和隐式等式 ({"genre": "sci-fi"}) 会被拒绝；请改用 $and 和 $eq。

逻辑运算符最多可以嵌套 2 层，例如 {"$and": [{"$or": [{"a": {"$eq": 1}}, {"b": {"$eq": 2}}]}]}。更深层的过滤条件会被拒绝，并显示 INVALID_ARGUMENT。

系统接受哪些过滤条件取决于搜索结果的提供方式。如果由近似最近邻 (ANN) 索引提供服务（默认情况下，当 search_field 上存在就绪索引时，或者通过 search_hint.index_hint 选择索引时），则每个过滤字段都必须在创建索引时列在 Index.filter_fields 中，$or 和 $all 仅在过滤条件的顶层接受，并且不支持 $not 和 $exists。并非每个不受支持的过滤条件都会被拒绝：大多数过滤条件都会生成 INVALID_ARGUMENT，但有些过滤条件会被静默忽略，因此请勿依赖该错误。如果 search_field 上没有就绪的索引，或者设置了 search_hint.knn_hint，则搜索由 K 最近邻 (KNN) 搜索提供，该搜索没有任何过滤条件限制。
outputFields

object (OutputFields)

可选。用于指定要返回哪些字段的掩码。
searchHint

object (SearchHint)

可选。设置搜索提示。如果未指定策略，服务将使用索引（如果有），否则会回退到默认的 KNN 搜索。
distanceMetric

enum (DistanceMetric)

可选。用于 KNN 搜索的距离指标。如果未指定，系统将默认使用 DOT_PRODUCT。
联合字段 vector_type。指定要用于查询的向量类型。vector_type 只能是下列其中一项：
vector

object (DenseVector)

查询的密集向量。
sparseVector

object (SparseVector)

查询的稀疏向量。

联合字段 _top_k。

_top_k 只能是下列其中一项：
topK

integer

可选。要返回的最近邻数量。

DenseVector

JSON 表示法 
{
  "values": [
    number
  ]
}
字段
values[]

number

必需。向量的值。

SparseVector

JSON 表示法 
{
  "values": [
    number
  ],
  "indices": [
    integer
  ]
}
字段
values[]

number

必需。向量的值。
indices[]

integer

必需。值的对应索引。

结构体

JSON 表示法 
{
  "fields": {
    string: value,
    ...
  }
}
字段
fields

map (key: string, value: value (Value format))

动态类型值的无序映射。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

FieldsEntry

JSON 表示法 
{
  "key": string,
  "value": value
}
字段
key

string
value

value (Value format)

值

JSON 表示法 
{

  // Union field kind can be only one of the following:
  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
  // End of list of possible types for union field kind.
}
字段
联合字段 kind。值的类型。kind 只能是下列其中一项：
nullValue

null

表示 JSON null。
numberValue

number

表示 JSON 数字。不得为 NaN、Infinity 或 -Infinity，因为 JSON 不支持这些值。这也无法表示较大的 Int64 值，因为 JSON 格式通常不支持在其数字类型中使用这些值。
stringValue

string

表示 JSON 字符串。
boolValue

boolean

表示 JSON 布尔值（JSON 中的 true 或 false 字面量）。
structValue

object (Struct format)

表示一个 JSON 对象。
listValue

array (ListValue format)

表示 JSON 数组。

ListValue

JSON 表示法 
{
  "values": [
    value
  ]
}
字段
values[]

value (Value format)

动态类型值的重复字段。

OutputFields

JSON 表示法 
{
  "dataFields": [
    string
  ],
  "vectorFields": [
    string
  ],
  "metadataFields": [
    string
  ]
}
字段
dataFields[]

string

可选。要包含在输出中的数据字段。使用 "*" 可以包含所有数据字段。如果为空，则结果中会省略 data。
vectorFields[]

string

可选。要包含在输出中的向量字段中的字段。使用 "*" 可包含所有向量字段。如果为空，则结果中会省略 vectors。
metadataFields[]

string

可选。要包含在输出中的 DataObject 元数据字段：create_time、update_time 和 etag。使用 "*" 可以包含所有元数据字段。如果为空，则这些字段会从结果中省略。

SearchHint

JSON 表示法 
{

  // Union field index_type can be only one of the following:
  "knnHint": {
    object (KnnHint)
  },
  "indexHint": {
    object (IndexHint)
  }
  // End of list of possible types for union field index_type.
}
字段
联合字段 index_type。要使用的索引类型。index_type 只能是下列其中一项：
knnHint

object (KnnHint)

可选。如果设置，搜索将使用系统的默认 K 最近邻 (KNN) 索引引擎。
indexHint

object (IndexHint)

可选。指定搜索应使用特定索引。

IndexHint

JSON 表示法 
{
  "name": string,

  // Union field params can be only one of the following:
  "denseScannParams": {
    object (DenseScannParams)
  }
  // End of list of possible types for union field params.
}
字段
name

string

必需。要用于搜索的索引的资源名称。索引必须位于同一项目、位置和集合中。格式：projects/{project}/locations/{location}/collections/{collection}/indexes/{index}
联合字段 params。索引的参数。params 只能是下列其中一项：
denseScannParams

object (DenseScannParams)

可选。密集 ScaNN 参数。

DenseScannParams

JSON 表示法 
{

  // Union field _target_recall can be only one of the following:
  "targetRecall": number
  // End of list of possible types for union field _target_recall.
}
字段

联合字段 _target_recall。

_target_recall 只能是下列其中一项：
targetRecall

number

可选。搜索的目标召回率。必须是 [0, 1] 范围内的双精度值。虽然搜索旨在达到此召回率水平，但无法保证。

SemanticSearch

JSON 表示法 
{
  "searchText": string,
  "searchField": string,
  "taskType": enum (EmbeddingTaskType),
  "outputFields": {
    object (OutputFields)
  },
  "filter": {
    object
  },
  "searchHint": {
    object (SearchHint)
  },

  // Union field _top_k can be only one of the following:
  "topK": integer
  // End of list of possible types for union field _top_k.
}
字段
searchText

string

可选。查询文本，用于根据集合配置中指定的嵌入模型生成嵌入。

使用文本搜索模式时，此参数为必填项。
searchField

string

必需。要搜索的向量字段。
taskType

enum (EmbeddingTaskType)

可选。查询嵌入的任务类型。对于纯文本嵌入模型，必须指定此参数，请参阅 https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/embeddings/task-types。对于多模态嵌入模型，不需要指定此参数，请参阅 https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/embeddings/get-multimodal-embeddings#specify-task-instructions
outputFields

object (OutputFields)

可选。要在搜索结果中返回的字段。
filter

object (Struct format)

可选。JSON 过滤表达式，例如 {"genre": {"$eq": "sci-fi"}}，表示为 google.protobuf.Struct。

空过滤条件 ({}) 会匹配所有数据对象。否则，过滤条件中的每个 JSON 对象都必须恰好有一个键：映射到一个运算符 ({"price": {"$lt": 100}}) 的字段名称，或逻辑运算符：$and 或 $or（后跟过滤条件列表），或 $not（后跟一个过滤条件）。字段运算符及其值：$eq 和 $ne 接受字符串、数字或布尔值；$lt、$lte、$gt 和 $gte 接受数字；$in、$nin 和 $all 接受字符串列表；$exists 接受布尔值。一个对象中的多个键（隐式 AND）和隐式等式 ({"genre": "sci-fi"}) 会被拒绝；请改用 $and 和 $eq。

逻辑运算符最多可以嵌套 2 层，例如 {"$and": [{"$or": [{"a": {"$eq": 1}}, {"b": {"$eq": 2}}]}]}。更深层的过滤条件会被拒绝，并显示 INVALID_ARGUMENT。

系统接受哪些过滤条件取决于搜索结果的提供方式。如果由近似最近邻 (ANN) 索引提供服务（默认情况下，当 search_field 上存在就绪索引时，或者通过 search_hint.index_hint 选择索引时），则每个过滤字段都必须在创建索引时列在 Index.filter_fields 中，$or 和 $all 仅在过滤条件的顶层接受，并且不支持 $not 和 $exists。并非每个不受支持的过滤条件都会被拒绝：大多数过滤条件都会生成 INVALID_ARGUMENT，但有些过滤条件会被静默忽略，因此请勿依赖该错误。如果 search_field 上没有就绪的索引，或者设置了 search_hint.knn_hint，则搜索由 K 最近邻 (KNN) 搜索提供，该搜索没有任何过滤条件限制。
searchHint

object (SearchHint)

可选。设置搜索提示。如果未指定策略，服务将使用索引（如果有），否则会回退到 KNN 搜索。

联合字段 _top_k。

_top_k 只能是下列其中一项：
topK

integer

可选。要返回的数据对象数量。

TextSearch

JSON 表示法 
{
  "searchText": string,
  "dataFieldNames": [
    string
  ],
  "outputFields": {
    object (OutputFields)
  },
  "filter": {
    object
  },

  // Union field _top_k can be only one of the following:
  "topK": integer
  // End of list of possible types for union field _top_k.
}
字段
searchText

string

可选。查询文本。
dataFieldNames[]

string

可选。要搜索的数据字段名称。
outputFields

object (OutputFields)

可选。要在搜索结果中返回的字段。
filter

object (Struct format)

可选。JSON 过滤表达式，例如 {"genre": {"$eq": "sci-fi"}}，表示为 google.protobuf.Struct。

空过滤条件 ({}) 会匹配所有数据对象。否则，过滤条件中的每个 JSON 对象都必须恰好有一个键：映射到一个运算符 ({"price": {"$lt": 100}}) 的字段名称，或逻辑运算符：$and 或 $or（后跟过滤条件列表），或 $not（后跟一个过滤条件）。字段运算符及其值：$eq 和 $ne 接受字符串、数字或布尔值；$lt、$lte、$gt 和 $gte 接受数字；$in、$nin 和 $all 接受字符串列表；$exists 接受布尔值。一个对象中的多个键（隐式 AND）和隐式等式 ({"genre": "sci-fi"}) 会被拒绝；请改用 $and 和 $eq。

逻辑运算符最多可以嵌套 2 层，例如 {"$and": [{"$or": [{"a": {"$eq": 1}}, {"b": {"$eq": 2}}]}]}。更深层的过滤条件会被拒绝，并显示 INVALID_ARGUMENT。

联合字段 _top_k。

_top_k 只能是下列其中一项：
topK

integer

可选。要返回的结果的数量。

NullValue

表示 JSON null。

NullValue 是一个哨兵，使用仅有一个值的枚举来表示 Value 类型联合的 null 值。

NullValue 类型的字段如果包含 0 以外的任何值，则会被视为无效。大多数 ProtoJSON 序列化器都会发出一个 Value，其中 null_value 设置为 JSON null，而不管整数值如何，因此会往返于 0 值。

枚举
NULL_VALUE Null 值。

DistanceMetric

向量搜索的距离指标。

枚举
DISTANCE_METRIC_UNSPECIFIED 默认值，未指定距离指标。
DOT_PRODUCT 点积距离指标。
COSINE_DISTANCE 余弦距离指标。

EmbeddingTaskType

表示嵌入将用于的任务。

枚举
EMBEDDING_TASK_TYPE_UNSPECIFIED 未指定的任务类型。
RETRIEVAL_QUERY 在搜索/检索设置中指定给定文本是查询。
RETRIEVAL_DOCUMENT 指定给定文本是来自正在搜索的语料库的文档。
SEMANTIC_SIMILARITY 指定给定文本用于 STS。
CLASSIFICATION 指定将对给定文本进行分类。
CLUSTERING 指定嵌入用于聚类。
QUESTION_ANSWERING 指定嵌入用于问答。
FACT_VERIFICATION 指定嵌入用于事实验证。
CODE_RETRIEVAL_QUERY 指定嵌入用于代码检索。

输出架构

对搜索请求的响应。

SearchDataObjectsResponse

JSON 表示法 
{
  "results": [
    {
      object (SearchResult)
    }
  ],
  "nextPageToken": string
}
字段
results[]

object (SearchResult)

仅限输出。与搜索条件匹配的 dataObject 的列表。
nextPageToken

string

仅限输出。用于检索下一页结果的令牌。 传递给 pageToken 以获取该页面。

SearchResult

JSON 表示法 
{
  "dataObject": {
    object (DataObject)
  },

  // Union field _distance can be only one of the following:
  "distance": number
  // End of list of possible types for union field _distance.
}
字段
dataObject

object (DataObject)

仅限输出。匹配的数据对象。

联合字段 _distance。

_distance 只能是下列其中一项：
distance

number

仅限输出。BatchSearchDataObjects 返回的相似度距离或排名得分。

DataObject

JSON 表示法 
{
  "name": string,
  "dataObjectId": string,
  "createTime": string,
  "updateTime": string,
  "data": {
    object
  },
  "vectors": {
    string: {
      object (Vector)
    },
    ...
  },
  "etag": string
}
字段
name

string

标识符。dataObject 的完全限定资源名称。

格式：projects/{project}/locations/{location}/collections/{collection}/dataObjects/{data_object_id}。data_object_id 的长度必须为 1-63 个字符，并且符合 RFC1035 的要求。
dataObjectId

string

仅限输出。dataObject 的 ID。
createTime

string (Timestamp format)

仅限输出。dataObject 创建时的时间戳。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
updateTime

string (Timestamp format)

仅限输出。上次更新 dataObject 时的时间戳。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
data

object (Struct format)

可选。dataObject 的数据。
vectors

map (key: string, value: object (Vector))

可选。dataObject 的向量。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
etag

string

可选。dataObject 的 etag。

时间戳

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

表示世界协调时间 (UTC) 的秒数（从 Unix 纪元 1970-01-01T00:00:00Z 开始算起）。必须介于 -62135596800 到 253402300799 之间（含边界值，对应于 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59Z）。
nanos

integer

秒数的非负小数部分（以纳秒为单位）。此字段是时长的纳秒部分，而不是秒的替代。对于含小数部分的负秒数，仍必须包含按时间递升的非负纳秒值。必须在 0 到 999,999,999 之间（含边界值）。

结构体

JSON 表示法 
{
  "fields": {
    string: value,
    ...
  }
}
字段
fields

map (key: string, value: value (Value format))

动态类型值的无序映射。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

FieldsEntry

JSON 表示法 
{
  "key": string,
  "value": value
}
字段
key

string
value

value (Value format)

值

JSON 表示法 
{

  // Union field kind can be only one of the following:
  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
  // End of list of possible types for union field kind.
}
字段
联合字段 kind。值的类型。kind 只能是下列其中一项：
nullValue

null

表示 JSON null。
numberValue

number

表示 JSON 数字。不得为 NaN、Infinity 或 -Infinity，因为 JSON 不支持这些值。这也无法表示较大的 Int64 值，因为 JSON 格式通常不支持在其数字类型中使用这些值。
stringValue

string

表示 JSON 字符串。
boolValue

boolean

表示 JSON 布尔值（JSON 中的 true 或 false 字面量）。
structValue

object (Struct format)

表示一个 JSON 对象。
listValue

array (ListValue format)

表示 JSON 数组。

ListValue

JSON 表示法 
{
  "values": [
    value
  ]
}
字段
values[]

value (Value format)

动态类型值的重复字段。

VectorsEntry

JSON 表示法 
{
  "key": string,
  "value": {
    object (Vector)
  }
}
字段
key

string
value

object (Vector)

向量

JSON 表示法 
{

  // Union field vector_type can be only one of the following:
  "dense": {
    object (DenseVector)
  },
  "sparse": {
    object (SparseVector)
  }
  // End of list of possible types for union field vector_type.
}
字段
联合字段 vector_type。向量的类型。vector_type 只能是下列其中一项：
dense

object (DenseVector)

密集向量。
sparse

object (SparseVector)

稀疏向量。

DenseVector

JSON 表示法 
{
  "values": [
    number
  ]
}
字段
values[]

number

必需。向量的值。

SparseVector

JSON 表示法 
{
  "values": [
    number
  ],
  "indices": [
    integer
  ]
}
字段
values[]

number

必需。向量的值。
indices[]

integer

必需。值的对应索引。

NullValue

表示 JSON null。

NullValue 是一个哨兵，使用仅有一个值的枚举来表示 Value 类型联合的 null 值。

NullValue 类型的字段如果包含 0 以外的任何值，则会被视为无效。大多数 ProtoJSON 序列化器都会发出一个 Value，其中 null_value 设置为 JSON null，而不管整数值如何，因此会往返于 0 值。

枚举
NULL_VALUE Null 值。

工具注释

工具注解会发送到 MCP 客户端，用于描述给定工具的基本风险。大多数客户端会将这些提示视为不可信，但可用于决定何时向用户发送确认提示。

除了标题字符串之外，还定义了以下布尔值提示：

  • readOnlyHint：如果为 true，则该工具不会修改其环境。默认值：false。
  • destructiveHint：如果为 true，则该工具可以执行破坏性操作。如果为 false，则该工具只能执行添加操作。默认值：true。
  • idempotentHint：如果为 true，则使用相同参数重复调用该工具不会对其环境产生额外影响。默认值：false。
  • openWorldHint：如果为 true，则该工具可以与外部实体的“开放世界”进行交互。如果为 false，则该工具只能与内部实体交互。例如，网页搜索工具是开放世界，而记忆工具不是开放世界。

破坏性提示：❌ | 等幂性提示：✅ | 只读提示：✅ | 开放世界提示：❌