VectorService
Vector search operations.
Proto source
Transport
All methods are available via:
- gRPC on port 7080 — native high-performance API
- REST/JSON on port 7081 — HTTP/JSON transcoding via embedded structured-proxy
Methods
VectorSearch
Search for nearest neighbors by vector similarity.
HTTP: POST /v1/query/vector/search
Request: VectorSearchRequest
| Field | Type | Description |
|---|---|---|
label | string | Label to search within. |
property | string | Property name containing vectors. |
query_vector | Vector | Query vector. |
top_k | uint32 | Number of nearest neighbors to return. |
metric | DistanceMetric | Distance metric (cosine, l2, dot, l1). |
Response: VectorSearchResponse
| Field | Type | Description |
|---|---|---|
results | VectorResult[] | — |
index_health | VectorIndexHealth | Serving health + freshness of the HNSW index that answered this query. Set server-side from the index registry's health signal. Absent (field unset) when the query did not run against a managed HNSW index (for example a brute-force fallback on a tiny dataset). A client implements read-your-writes by comparing index_health.indexed_hlc against the HLC of its own prior write (the Pinecone LSN-header pattern). |
HybridSearch
Hybrid search combining graph traversal and vector similarity.
HTTP: POST /v1/query/vector/hybrid
Request: HybridSearchRequest
| Field | Type | Description |
|---|---|---|
start_node_id | uint64 | Starting node for graph traversal. |
edge_type | string | Edge type to traverse. |
max_depth | uint32 | Max traversal depth. |
vector_property | string | Vector search parameters applied after traversal. |
query_vector | Vector | — |
top_k | uint32 | — |
metric | DistanceMetric | — |
Response: HybridSearchResponse
| Field | Type | Description |
|---|---|---|
results | VectorResult[] | — |
index_health | VectorIndexHealth | Serving health + freshness of the HNSW index that answered the vector phase of this hybrid query. Same semantics as VectorSearchResponse.index_health; unset when the vector phase did not run against a managed HNSW index. |
Types
HybridSearchRequest
| Field | Type | Description |
|---|---|---|
start_node_id | uint64 | Starting node for graph traversal. |
edge_type | string | Edge type to traverse. |
max_depth | uint32 | Max traversal depth. |
vector_property | string | Vector search parameters applied after traversal. |
query_vector | Vector | — |
top_k | uint32 | — |
metric | DistanceMetric | — |
HybridSearchResponse
| Field | Type | Description |
|---|---|---|
results | VectorResult[] | — |
index_health | VectorIndexHealth | Serving health + freshness of the HNSW index that answered the vector phase of this hybrid query. Same semantics as VectorSearchResponse.index_health; unset when the vector phase did not run against a managed HNSW index. |
VectorIndexHealth
Serving health of a vector index: whether it can answer queries at full recall right now, plus the freshness watermark of writes it has applied. Computed server-side; clients never send this. This is the live serving lifecycle (ready / rebuilding / offline), distinct from the durable backfill state persisted with the index definition.
ServingState enum:
| Value | Number | Description |
|---|---|---|
SERVING_STATE_UNSPECIFIED | 0 | Unset / unknown — treat as a degenerate case, not a guarantee. |
SERVING_STATE_READY | 1 | Fully built and serving at the documented recall. |
SERVING_STATE_REBUILDING | 2 | Being (re)built after segment migration or reconfiguration; results may be partial-recall depending on the label's VECTOR_REBUILD_POLICY. |
SERVING_STATE_OFFLINE | 3 | Unavailable; see offline_reason. |
| Field | Type | Description |
|---|---|---|
serving_state | ServingState | Current serving lifecycle. |
rebuild_progress | float | Rebuild progress in [0.0, 1.0]. 0 unless serving_state == SERVING_STATE_REBUILDING. |
eta_ms | uint64 | Best-effort estimate of remaining rebuild time, in milliseconds. 0 unless serving_state == SERVING_STATE_REBUILDING. |
indexed_hlc | uint64 | Freshness watermark: an HLC commit timestamp (wall-clock microseconds) such that every write committed at or below it is in the index serving this member, whatever order those commits applied in. This is the read-your-writes fence: a client that wrote at HLC W has been served a fully-current index iff indexed_hlc >= W. 0 when nothing is claimed yet or serving_state == SERVING_STATE_OFFLINE. |
offline_reason | string | Human-readable reason when serving_state == SERVING_STATE_OFFLINE (for example "segment_lost", "disk_io", "manual_disable"); empty otherwise. |
VectorResult
| Field | Type | Description |
|---|---|---|
node | Node | — |
distance | float | — |
VectorSearchRequest
| Field | Type | Description |
|---|---|---|
label | string | Label to search within. |
property | string | Property name containing vectors. |
query_vector | Vector | Query vector. |
top_k | uint32 | Number of nearest neighbors to return. |
metric | DistanceMetric | Distance metric (cosine, l2, dot, l1). |
VectorSearchResponse
| Field | Type | Description |
|---|---|---|
results | VectorResult[] | — |
index_health | VectorIndexHealth | Serving health + freshness of the HNSW index that answered this query. Set server-side from the index registry's health signal. Absent (field unset) when the query did not run against a managed HNSW index (for example a brute-force fallback on a tiny dataset). A client implements read-your-writes by comparing index_health.indexed_hlc against the HLC of its own prior write (the Pinecone LSN-header pattern). |
Enums
DistanceMetric
| Value | Number | Description |
|---|---|---|
DISTANCE_METRIC_UNSPECIFIED | 0 | — |
DISTANCE_METRIC_COSINE | 1 | — |
DISTANCE_METRIC_L2 | 2 | — |
DISTANCE_METRIC_DOT | 3 | — |
DISTANCE_METRIC_L1 | 4 | — |