Skip to content

Commit f0e6fd9

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: add SearchHint to SemanticSearch requests
feat: Allow requesting search metadata in SearchDataObjects feat: add filter param for TextSearch requests feat: add ExportDataObjects API PiperOrigin-RevId: 863352956
1 parent 8d0579f commit f0e6fd9

File tree

7 files changed

+135
-26
lines changed

7 files changed

+135
-26
lines changed

‎google/cloud/vectorsearch/v1beta/data_object.proto‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2025 Google LLC
1+
// Copyright 2026 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -31,16 +31,17 @@ message DataObject {
3131
option (google.api.resource) = {
3232
type: "vectorsearch.googleapis.com/DataObject"
3333
pattern: "projects/{project}/locations/{location}/collections/{collection}/dataObjects/{dataObject}"
34+
plural: "dataObjects"
35+
singular: "dataObject"
3436
};
3537

36-
// Immutable. The fully qualified resource name of the dataObject.
38+
// Identifier. The fully qualified resource name of the dataObject.
3739
//
3840
// Format:
3941
// `projects/{project}/locations/{location}/collections/{collection}/dataObjects/{data_object_id}`
4042
// The data_object_id must be 1-63 characters
41-
// long, and comply with
42-
// <a href="https://www.ietf.org/rfc/rfc1035.txt" target="_blank">RFC1035</a>.
43-
string name = 1 [(google.api.field_behavior) = IMMUTABLE];
43+
// long, and comply with [RFC1035](https://www.ietf.org/rfc/rfc1035.txt).
44+
string name = 1 [(google.api.field_behavior) = IDENTIFIER];
4445

4546
// Output only. The id of the dataObject.
4647
string data_object_id = 2

‎google/cloud/vectorsearch/v1beta/data_object_search_service.proto‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2025 Google LLC
1+
// Copyright 2026 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -107,12 +107,12 @@ message SearchHint {
107107

108108
// The type of index to use.
109109
oneof index_type {
110-
// Specifies that the search should use a particular index.
111-
IndexHint use_index = 1;
110+
// Optional. Specifies that the search should use a particular index.
111+
IndexHint use_index = 1 [(google.api.field_behavior) = OPTIONAL];
112112

113-
// If set to true, the search will use the system's default
113+
// Optional. If set to true, the search will use the system's default
114114
// K-Nearest Neighbor (KNN) index engine.
115-
bool use_knn = 2;
115+
bool use_knn = 2 [(google.api.field_behavior) = OPTIONAL];
116116
}
117117
}
118118

@@ -161,7 +161,8 @@ message VectorSearch {
161161

162162
// Optional. The distance metric to use for the KNN search. If not specified,
163163
// DOT_PRODUCT will be used as the default.
164-
DistanceMetric distance_metric = 11 [(google.api.field_behavior) = OPTIONAL];
164+
google.cloud.vectorsearch.v1beta.DistanceMetric distance_metric = 11
165+
[(google.api.field_behavior) = OPTIONAL];
165166
}
166167

167168
// Defines a semantic search operation.
@@ -185,6 +186,11 @@ message SemanticSearch {
185186

186187
// Optional. The number of data objects to return.
187188
optional int32 top_k = 4 [(google.api.field_behavior) = OPTIONAL];
189+
190+
// Optional. Sets the search hint. If no strategy is specified, the service
191+
// will use an index if one is available, and fall back to KNN search
192+
// otherwise.
193+
SearchHint search_hint = 7 [(google.api.field_behavior) = OPTIONAL];
188194
}
189195

190196
// Defines a text search operation.
@@ -200,6 +206,10 @@ message TextSearch {
200206

201207
// Optional. The number of results to return.
202208
optional int32 top_k = 4 [(google.api.field_behavior) = OPTIONAL];
209+
210+
// Optional. A JSON filter expression, e.g. `{"genre": {"$eq": "sci-fi"}}`,
211+
// represented as a `google.protobuf.Struct`.
212+
google.protobuf.Struct filter = 5 [(google.api.field_behavior) = OPTIONAL];
203213
}
204214

205215
// Request for performing a single search.

‎google/cloud/vectorsearch/v1beta/data_object_service.proto‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2025 Google LLC
1+
// Copyright 2026 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -114,7 +114,7 @@ message CreateDataObjectRequest {
114114

115115
// Required. The id of the dataObject to create.
116116
// The id must be 1-63 characters long, and comply with
117-
// <a href="https://www.ietf.org/rfc/rfc1035.txt" target="_blank">RFC1035</a>.
117+
// [RFC1035](https://www.ietf.org/rfc/rfc1035.txt).
118118
// Specifically, it must be 1-63 characters long and match the regular
119119
// expression `[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?`.
120120
string data_object_id = 2 [(google.api.field_behavior) = REQUIRED];

‎google/cloud/vectorsearch/v1beta/embedding_config.proto‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2025 Google LLC
1+
// Copyright 2026 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -63,7 +63,7 @@ message VertexEmbeddingConfig {
6363

6464
// Required. Required: Text template for the input to the model. The template
6565
// must contain one or more references to fields in the DataObject, e.g.:
66-
// "Movie Title: {title} ---- Movie Plot: {plot}"".
66+
// "Movie Title: {title} ---- Movie Plot: {plot}".
6767
string text_template = 2 [(google.api.field_behavior) = REQUIRED];
6868

6969
// Required. Required: Task type for the embeddings.

‎google/cloud/vectorsearch/v1beta/vectorsearch_service.proto‎

Lines changed: 84 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2025 Google LLC
1+
// Copyright 2026 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -156,6 +156,19 @@ service VectorSearchService {
156156
metadata_type: "ImportDataObjectsMetadata"
157157
};
158158
}
159+
160+
// Initiates a Long-Running Operation to export DataObjects from a Collection.
161+
rpc ExportDataObjects(ExportDataObjectsRequest)
162+
returns (google.longrunning.Operation) {
163+
option (google.api.http) = {
164+
post: "/v1beta/{name=projects/*/locations/*/collections/*}:exportDataObjects"
165+
body: "*"
166+
};
167+
option (google.longrunning.operation_info) = {
168+
response_type: "ExportDataObjectsResponse"
169+
metadata_type: "ExportDataObjectsMetadata"
170+
};
171+
}
159172
}
160173

161174
// Message describing Collection object
@@ -290,7 +303,7 @@ message CreateCollectionRequest {
290303

291304
// Required. ID of the Collection to create.
292305
// The id must be 1-63 characters long, and comply with
293-
// <a href="https://www.ietf.org/rfc/rfc1035.txt" target="_blank">RFC1035</a>.
306+
// [RFC1035](https://www.ietf.org/rfc/rfc1035.txt).
294307
// Specifically, it must be 1-63 characters long and match the regular
295308
// expression `[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?`.
296309
string collection_id = 2 [(google.api.field_behavior) = REQUIRED];
@@ -329,7 +342,8 @@ message UpdateCollectionRequest {
329342
// The following fields support update: `display_name`, `description`,
330343
// `labels`, `data_schema`, `vector_schema`.
331344
// For `data_schema` and `vector_schema`, fields can only be added, not
332-
// modified or deleted.
345+
// deleted, but `vertex_embedding_config` in `vector_schema` can be added or
346+
// removed.
333347
// Partial updates for `data_schema` and `vector_schema` are also supported
334348
// by using sub-field paths in `update_mask`, e.g.
335349
// `data_schema.properties.foo` or `vector_schema.my_vector_field`.
@@ -420,7 +434,8 @@ message Index {
420434

421435
// Optional. Distance metric used for indexing. If not specified, will default
422436
// to DOT_PRODUCT.
423-
DistanceMetric distance_metric = 4 [(google.api.field_behavior) = OPTIONAL];
437+
google.cloud.vectorsearch.v1beta.DistanceMetric distance_metric = 4
438+
[(google.api.field_behavior) = OPTIONAL];
424439

425440
// Required. The collection schema field to index.
426441
string index_field = 5 [(google.api.field_behavior) = REQUIRED];
@@ -448,7 +463,7 @@ message CreateIndexRequest {
448463

449464
// Required. ID of the Index to create.
450465
// The id must be 1-63 characters long, and comply with
451-
// <a href="https://www.ietf.org/rfc/rfc1035.txt" target="_blank">RFC1035</a>.
466+
// [RFC1035](https://www.ietf.org/rfc/rfc1035.txt).
452467
// Specifically, it must be 1-63 characters long and match the regular
453468
// expression `[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?`.
454469
string index_id = 2 [(google.api.field_behavior) = REQUIRED];
@@ -581,7 +596,8 @@ message OperationMetadata {
581596
string api_version = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
582597
}
583598

584-
// Request message for [DataObjectService.ImportDataObjects][].
599+
// Request message for
600+
// [VectorSearchService.ImportDataObjects][google.cloud.vectorsearch.v1beta.VectorSearchService.ImportDataObjects].
585601
message ImportDataObjectsRequest {
586602
// Google Cloud Storage configuration for the import.
587603
message GcsImportConfig {
@@ -591,6 +607,12 @@ message ImportDataObjectsRequest {
591607
// Required. URI prefix of the Cloud Storage location to write any errors
592608
// encountered during the import.
593609
string error_uri = 2 [(google.api.field_behavior) = REQUIRED];
610+
611+
// Optional. URI prefix of the Cloud Storage location to write DataObject
612+
// `IDs` and `etags` of DataObjects that were successfully imported. The
613+
// service will write the successfully imported DataObjects to sharded files
614+
// under this prefix. If this field is empty, no output will be written.
615+
string output_uri = 3 [(google.api.field_behavior) = OPTIONAL];
594616
}
595617

596618
// The configuration for the import data and error results.
@@ -609,7 +631,8 @@ message ImportDataObjectsRequest {
609631
];
610632
}
611633

612-
// Metadata for [DataObjectService.ImportDataObjects][].
634+
// Metadata for
635+
// [VectorSearchService.ImportDataObjects][google.cloud.vectorsearch.v1beta.VectorSearchService.ImportDataObjects].
613636
message ImportDataObjectsMetadata {
614637
// The time the operation was created.
615638
google.protobuf.Timestamp create_time = 1;
@@ -624,8 +647,61 @@ message ImportDataObjectsMetadata {
624647
int64 failure_count = 4;
625648
}
626649

627-
// Response for [DataObjectService.ImportDataObjects][].
650+
// Response for
651+
// [VectorSearchService.ImportDataObjects][google.cloud.vectorsearch.v1beta.VectorSearchService.ImportDataObjects].
628652
message ImportDataObjectsResponse {
629653
// Status of the LRO
630654
google.rpc.Status status = 1;
631655
}
656+
657+
// Request message for
658+
// [VectorSearchService.ExportDataObjects][google.cloud.vectorsearch.v1beta.VectorSearchService.ExportDataObjects].
659+
message ExportDataObjectsRequest {
660+
// Google Cloud Storage configuration for the export.
661+
message GcsExportDestination {
662+
// Options for the format of the exported Data Objects.
663+
// New formats may be added in the future.
664+
enum Format {
665+
// Unspecified format.
666+
FORMAT_UNSPECIFIED = 0;
667+
668+
// The exported Data Objects will be in JSON format.
669+
JSON = 1;
670+
}
671+
672+
// Required. URI prefix of the Cloud Storage where to export Data Objects.
673+
// The bucket is required to be in the same region as the collection.
674+
string export_uri = 1 [(google.api.field_behavior) = REQUIRED];
675+
676+
// Required. The format of the exported Data Objects.
677+
Format format = 2 [(google.api.field_behavior) = REQUIRED];
678+
}
679+
680+
// The configuration for the export data.
681+
oneof destination {
682+
// The Cloud Storage location where user wants to export Data Objects.
683+
GcsExportDestination gcs_destination = 2;
684+
}
685+
686+
// Required. The resource name of the Collection from which we want to export
687+
// Data Objects. Format:
688+
// `projects/{project}/locations/{location}/collections/{collection}`.
689+
string name = 1 [
690+
(google.api.field_behavior) = REQUIRED,
691+
(google.api.resource_reference) = {
692+
type: "vectorsearch.googleapis.com/Collection"
693+
}
694+
];
695+
}
696+
697+
// Metadata for the ExportDataObjects LRO.
698+
message ExportDataObjectsMetadata {
699+
// The time the operation was created.
700+
google.protobuf.Timestamp create_time = 1;
701+
702+
// The time the operation finished.
703+
google.protobuf.Timestamp finish_time = 2;
704+
}
705+
706+
// Response for the ExportDataObjects LRO.
707+
message ExportDataObjectsResponse {}

‎google/cloud/vectorsearch/v1beta/vectorsearch_v1beta.yaml‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,15 @@ documentation:
2929
description: Gets information about a location.
3030

3131
- selector: google.cloud.location.Locations.ListLocations
32-
description: Lists information about the supported locations for this service.
32+
description: |-
33+
Lists information about the supported locations for this service.
34+
This method can be called in two ways:
35+
36+
* **List all public locations:** Use the path `GET /v1/locations`.
37+
* **List project-visible locations:** Use the path
38+
`GET /v1/projects/{project_id}/locations`. This may include public
39+
locations as well as private or other locations specifically visible
40+
to the project.
3341
3442
http:
3543
rules:

‎google/cloud/vectorsearch/v1beta/vectorsearch_v1beta_grpc_service_config.json‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,13 +47,27 @@
4747
{ "service": "google.cloud.vectorsearch.v1beta.DataObjectService", "method": "BatchUpdateDataObjects" },
4848
{ "service": "google.cloud.vectorsearch.v1beta.DataObjectService", "method": "BatchDeleteDataObjects" }
4949
],
50-
"timeout": "60s"
50+
"timeout": "60s",
51+
"retryPolicy": {
52+
"maxAttempts": 5,
53+
"initialBackoff": "1s",
54+
"maxBackoff": "10s",
55+
"backoffMultiplier": 1.3,
56+
"retryableStatusCodes": ["UNAVAILABLE"]
57+
}
5158
},
5259
{
5360
"name": [
5461
{ "service": "google.cloud.vectorsearch.v1beta.DataObjectService", "method": "BatchCreateDataObjects" }
5562
],
56-
"timeout": "300s"
63+
"timeout": "300s",
64+
"retryPolicy": {
65+
"maxAttempts": 5,
66+
"initialBackoff": "1s",
67+
"maxBackoff": "10s",
68+
"backoffMultiplier": 1.3,
69+
"retryableStatusCodes": ["UNAVAILABLE"]
70+
}
5771
}
5872
]
5973
}

0 commit comments

Comments
 (0)