Skip to content

Commit bbae371

Browse files
4adex4adex
committed
Update docs with latest feats
1 parent 99eaf37 commit bbae371

16 files changed

Lines changed: 612 additions & 1915 deletions

‎docs/api-reference/grpc.mdx‎

Lines changed: 91 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -39,17 +39,12 @@ syntax = "proto3";
3939
package vectordb;
4040
4141
service VectorDB {
42-
// Insert a vector with a payload and return the assigned PointID
4342
rpc InsertVector(InsertVectorRequest) returns (PointID);
44-
45-
// Delete a vector by its PointID
43+
rpc InsertVectorsBatch(InsertVectorsBatchRequest) returns (InsertVectorsBatchResponse);
4644
rpc DeletePoint(PointID) returns (google.protobuf.Empty);
47-
48-
// Get a vector and its payload by PointID
4945
rpc GetPoint(PointID) returns (Point);
50-
51-
// Search for the k nearest vectors to a target vector
5246
rpc SearchPoints(SearchRequest) returns (SearchResponse);
47+
rpc SearchPointsBatch(SearchPointsBatchRequest) returns (SearchPointsBatchResponse);
5348
}
5449
```
5550

@@ -221,13 +216,18 @@ Search for the k nearest neighbors to a query vector.
221216
Maximum number of results to return.
222217
</ParamField>
223218

219+
<ParamField body="ef" type="uint64">
220+
Search breadth for HNSW. Larger values trade speed for accuracy. Defaults to the server's `HNSW_EF` setting.
221+
</ParamField>
222+
224223
**Request:**
225224

226225
```protobuf
227226
message SearchRequest {
228227
DenseVector query_vector = 1;
229228
Similarity similarity = 2;
230229
uint64 limit = 3;
230+
uint64 ef = 4;
231231
}
232232
```
233233

@@ -247,7 +247,8 @@ grpcurl -plaintext \
247247
-d '{
248248
"query_vector": {"values": [0.1, 0.2, 0.3, 0.4]},
249249
"similarity": 3,
250-
"limit": 5
250+
"limit": 5,
251+
"ef": 200
251252
}' \
252253
localhost:50051 vectordb.VectorDB/SearchPoints
253254
```
@@ -265,6 +266,78 @@ grpcurl -plaintext \
265266

266267
---
267268

269+
### InsertVectorsBatch
270+
271+
Insert multiple vectors in a single request.
272+
273+
**Request:**
274+
275+
```protobuf
276+
message InsertVectorsBatchRequest {
277+
repeated InsertVectorRequest vectors = 1;
278+
}
279+
```
280+
281+
**Response:**
282+
283+
```protobuf
284+
message InsertVectorsBatchResponse {
285+
repeated PointID ids = 1;
286+
}
287+
```
288+
289+
**Example:**
290+
291+
```bash
292+
grpcurl -plaintext \
293+
-H "authorization: secret" \
294+
-d '{
295+
"vectors": [
296+
{"vector": {"values": [0.1, 0.2, 0.3]}, "payload": {"content_type": 1, "content": "doc one"}},
297+
{"vector": {"values": [0.4, 0.5, 0.6]}, "payload": {"content_type": 1, "content": "doc two"}}
298+
]
299+
}' \
300+
localhost:50051 vectordb.VectorDB/InsertVectorsBatch
301+
```
302+
303+
---
304+
305+
### SearchPointsBatch
306+
307+
Search against multiple query vectors in a single request.
308+
309+
**Request:**
310+
311+
```protobuf
312+
message SearchPointsBatchRequest {
313+
repeated SearchRequest queries = 1;
314+
}
315+
```
316+
317+
**Response:**
318+
319+
```protobuf
320+
message SearchPointsBatchResponse {
321+
repeated SearchResponse results = 1;
322+
}
323+
```
324+
325+
**Example:**
326+
327+
```bash
328+
grpcurl -plaintext \
329+
-H "authorization: secret" \
330+
-d '{
331+
"queries": [
332+
{"query_vector": {"values": [0.1, 0.2, 0.3]}, "similarity": 3, "limit": 2},
333+
{"query_vector": {"values": [0.4, 0.5, 0.6]}, "similarity": 0, "limit": 2}
334+
]
335+
}' \
336+
localhost:50051 vectordb.VectorDB/SearchPointsBatch
337+
```
338+
339+
---
340+
268341
## Message Types
269342

270343
### UUID
@@ -361,12 +434,19 @@ with VortexDB(grpc_url="localhost:50051", api_key="secret") as db:
361434
vector=DenseVector([0.1, 0.2, 0.3, 0.4]),
362435
payload=Payload.text("Hello")
363436
)
364-
365-
# Search
437+
438+
# Batch insert
439+
ids = db.batch_insert(items=[
440+
(DenseVector([0.1, 0.2, 0.3]), Payload.text("doc one")),
441+
(DenseVector([0.4, 0.5, 0.6]), Payload.text("doc two")),
442+
])
443+
444+
# Search with ef parameter
366445
results = db.search(
367446
vector=DenseVector([0.1, 0.2, 0.3, 0.4]),
368447
similarity=Similarity.COSINE,
369-
limit=5
448+
limit=5,
449+
ef=200,
370450
)
371451
```
372452

@@ -375,20 +455,11 @@ with VortexDB(grpc_url="localhost:50051", api_key="secret") as db:
375455
Use `protoc` to generate clients in any language:
376456

377457
```bash
378-
# Python
379458
python -m grpc_tools.protoc \
380459
-I./crates/grpc/proto \
381460
--python_out=./client \
382461
--grpc_python_out=./client \
383462
./crates/grpc/proto/vector-db.proto
384-
385-
# Go
386-
protoc --go_out=. --go-grpc_out=. vector-db.proto
387-
388-
# TypeScript
389-
protoc --plugin=protoc-gen-ts \
390-
--ts_out=./client \
391-
vector-db.proto
392463
```
393464

394465
## Next Steps

‎docs/api-reference/http.mdx‎

Lines changed: 89 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,11 @@ VortexDB's HTTP API provides a RESTful interface for vector operations using JSO
1313
http://localhost:3000
1414
```
1515

16-
The port can be configured via the `HTTP_PORT` environment variable.
16+
The port can be configured via the `HTTP_PORT` environment variable. The server binds to `127.0.0.1` by default.
1717

18-
<Note>
19-
The HTTP API does not require authentication and is designed for development and trusted internal networks. For production, use the gRPC API or deploy behind a reverse proxy with authentication.
20-
</Note>
18+
<Warning>
19+
The HTTP API has no authentication. Always deploy behind a reverse proxy or disable it with `DISABLE_HTTP=true` in production.
20+
</Warning>
2121

2222
---
2323

@@ -67,7 +67,7 @@ Vector Database server is running!
6767

6868
<ParamField body="payload" type="object" required>
6969
Metadata object associated with the vector.
70-
70+
7171
<Expandable title="payload properties">
7272
<ParamField body="content_type" type="string" required>
7373
Type of content: `"Text"` or `"Image"`
@@ -79,7 +79,7 @@ Vector Database server is running!
7979
</ParamField>
8080

8181
<ResponseField name="point_id" type="string">
82-
The UUID of the created point.
82+
UUID of the created point.
8383
</ResponseField>
8484

8585
<CodeGroup>
@@ -111,12 +111,61 @@ curl -X POST http://localhost:3000/points \
111111

112112
---
113113

114+
### Batch Insert
115+
116+
Insert multiple vectors in a single request.
117+
118+
<ParamField body="vectors" type="array" required>
119+
Array of insert objects, each with `vector` and `payload` fields (same shape as single insert).
120+
</ParamField>
121+
122+
<ResponseField name="point_ids" type="array">
123+
Array of UUIDs for each created point, in the same order as the input.
124+
</ResponseField>
125+
126+
<CodeGroup>
127+
```bash Request
128+
curl -X POST http://localhost:3000/points/batch \
129+
-H "Content-Type: application/json" \
130+
-d '{
131+
"vectors": [
132+
{
133+
"vector": [0.1, 0.2, 0.3, 0.4],
134+
"payload": {"content_type": "Text", "content": "Document one"}
135+
},
136+
{
137+
"vector": [0.5, 0.6, 0.7, 0.8],
138+
"payload": {"content_type": "Text", "content": "Document two"}
139+
}
140+
]
141+
}'
142+
```
143+
144+
```json Response (201 Created)
145+
{
146+
"point_ids": [
147+
"550e8400-e29b-41d4-a716-446655440000",
148+
"6ba7b810-9dad-11d1-80b4-00c04fd430c8"
149+
]
150+
}
151+
```
152+
</CodeGroup>
153+
154+
**Error Responses:**
155+
156+
| Status | Description |
157+
|--------|-------------|
158+
| `400 Bad Request` | Invalid JSON or missing fields |
159+
| `500 Internal Server Error` | Server error during insertion |
160+
161+
---
162+
114163
### Get Point
115164

116165
Retrieve a point by its ID.
117166

118167
<ParamField path="id" type="string" required>
119-
The UUID of the point to retrieve.
168+
UUID of the point to retrieve.
120169
</ParamField>
121170

122171
<ResponseField name="id" type="string">
@@ -162,7 +211,7 @@ curl http://localhost:3000/points/550e8400-e29b-41d4-a716-446655440000
162211
Delete a point by its ID.
163212

164213
<ParamField path="id" type="string" required>
165-
The UUID of the point to delete.
214+
UUID of the point to delete.
166215
</ParamField>
167216

168217
<CodeGroup>
@@ -234,42 +283,46 @@ curl -X POST http://localhost:3000/points/search \
234283

235284
---
236285

237-
## Data Types
238-
239-
### Vector
286+
### Batch Search
240287

241-
An array of floating-point numbers:
288+
Search against multiple query vectors in a single request.
242289

243-
```json
244-
[0.1, 0.2, 0.3, 0.4]
245-
```
290+
<ParamField body="queries" type="array" required>
291+
Array of search query objects, each with `vector`, `similarity`, and `limit`.
292+
</ParamField>
246293

247-
<Warning>
248-
The vector length must match the `DIMENSION` environment variable configured on the server.
249-
</Warning>
294+
<ResponseField name="results" type="array">
295+
Array of result arrays, one per input query, each ordered by similarity.
296+
</ResponseField>
250297

251-
### Payload
298+
<CodeGroup>
299+
```bash Request
300+
curl -X POST http://localhost:3000/points/search/batch \
301+
-H "Content-Type: application/json" \
302+
-d '{
303+
"queries": [
304+
{"vector": [0.1, 0.2, 0.3, 0.4], "similarity": "Cosine", "limit": 2},
305+
{"vector": [0.5, 0.6, 0.7, 0.8], "similarity": "Euclidean", "limit": 2}
306+
]
307+
}'
308+
```
252309

253-
```json
310+
```json Response (200 OK)
254311
{
255-
"content_type": "Text",
256-
"content": "Your content here"
312+
"results": [
313+
["550e8400-...", "6ba7b810-..."],
314+
["f47ac10b-...", "9a1b2c3d-..."]
315+
]
257316
}
258317
```
318+
</CodeGroup>
259319

260-
| Field | Type | Values |
261-
|-------|------|--------|
262-
| `content_type` | string | `"Text"` or `"Image"` |
263-
| `content` | string | Any string content |
264-
265-
### Similarity
320+
**Error Responses:**
266321

267-
| Value | Description |
268-
|-------|-------------|
269-
| `"Euclidean"` | L2 distance (straight line) |
270-
| `"Manhattan"` | L1 distance (city block) |
271-
| `"Hamming"` | Count of differing elements |
272-
| `"Cosine"` | Angular distance (1 - cosine similarity) |
322+
| Status | Description |
323+
|--------|-------------|
324+
| `400 Bad Request` | Invalid JSON or missing fields |
325+
| `500 Internal Server Error` | Server error during search |
273326

274327
---
275328

@@ -325,19 +378,6 @@ curl -X POST http://localhost:3000/points/search \
325378
curl -X DELETE http://localhost:3000/points/$POINT_ID
326379
```
327380

328-
### Batch Insert (using shell loop)
329-
330-
```bash
331-
for i in {1..10}; do
332-
curl -s -X POST http://localhost:3000/points \
333-
-H "Content-Type: application/json" \
334-
-d "{
335-
\"vector\": [$(echo "scale=2; $i/10" | bc), $(echo "scale=2; $i/10 + 0.1" | bc), 0.3, 0.4],
336-
\"payload\": {\"content_type\": \"Text\", \"content\": \"Document $i\"}
337-
}"
338-
done
339-
```
340-
341381
---
342382

343383
## OpenAPI Specification
@@ -358,7 +398,7 @@ You can import this into tools like Postman or Swagger UI for interactive API ex
358398
<Card title="gRPC API" icon="bolt" href="/api-reference/grpc">
359399
High-performance gRPC API reference
360400
</Card>
361-
<Card title="Python SDK" icon="python" href="/guides/python-sdk">
362-
Build applications with the Python client
401+
<Card title="Python SDK" icon="python" href="/sdk/reference">
402+
Python client documentation
363403
</Card>
364404
</CardGroup>

‎docs/api-reference/overview.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,9 +65,11 @@ Both APIs support the same core operations:
6565
| Operation | gRPC Method | HTTP Endpoint |
6666
|-----------|-------------|---------------|
6767
| Insert vector | `InsertVector` | `POST /points` |
68+
| Batch insert | `InsertVectorsBatch` | `POST /points/batch` |
6869
| Get point | `GetPoint` | `GET /points/:id` |
6970
| Delete point | `DeletePoint` | `DELETE /points/:id` |
7071
| Search vectors | `SearchPoints` | `POST /points/search` |
72+
| Batch search | `SearchPointsBatch` | `POST /points/search/batch` |
7173
| Health check | - | `GET /health` |
7274

7375
## Error Handling

0 commit comments

Comments
 (0)