SDK Reference

Python SDK Reference

Complete API documentation for the VortexDB Python client.

Installation

pip install vortexdb

---

VortexDB

The main client class for interacting with VortexDB.

from vortexdb import VortexDB

Constructor

VortexDB(
    *,
    grpc_url: str | None = None,
    api_key: str | None = None,
    timeout: float | None = None,
)

grpc_urlstrdefault: localhost:50051

The gRPC server address. Can also be set via VORTEXDB_GRPC_URL environment variable.

api_keystrdefault: None

Authentication key for the gRPC API. Can also be set via VORTEXDB_API_KEY environment variable.

timeoutfloatdefault: 30.0

Request timeout in seconds. Can also be set via VORTEXDB_TIMEOUT environment variable.

Example:

# Explicit configuration
db = VortexDB(
    grpc_url="localhost:50051",
    api_key="secret",
    timeout=60.0,
)

# Using environment variables
import os
os.environ["VORTEXDB_GRPC_URL"] = "localhost:50051"
os.environ["VORTEXDB_API_KEY"] = "secret"
db = VortexDB()

---

Methods

insert

Insert a vector with its payload into the database.

def insert(
    self,
    *,
    vector: DenseVector,
    payload: Payload,
) -> str

returnstr

UUID of the created point.

Example:

point_id = db.insert(
    vector=DenseVector([0.1, 0.2, 0.3, 0.4]),
    payload=Payload.text("My document"),
)

---

batch_insert

Insert multiple vectors in a single request.

def batch_insert(
    self,
    *,
    items: list[tuple[DenseVector, Payload]],
) -> list[str]

returnlist[str]

List of UUIDs for the created points, in input order.

Example:

ids = db.batch_insert(items=[
    (DenseVector([0.1, 0.2, 0.3]), Payload.text("doc one")),
    (DenseVector([0.4, 0.5, 0.6]), Payload.text("doc two")),
])

---

get

Retrieve a point by its ID.

def get(
    self,
    *,
    point_id: str,
) -> Point | None

returnPoint | None

The point if found, None otherwise.

Example:

point = db.get(point_id="550e8400-e29b-41d4-a716-446655440000")
if point:
    print(f"Vector: {point.vector.to_list()}")
    print(f"Payload: {point.payload.content}")

---

search

Search for the k nearest neighbors to a query vector.

def search(
    self,
    *,
    vector: DenseVector | None = None,
    similarity: Similarity | None = None,
    limit: int | None = None,
    query: SearchQuery | None = None,
    ef: int | None = None,
) -> List[str]

querySearchQuerydefault: None

A SearchQuery object bundling vector, similarity, and limit. Use this or pass individual args.

efintdefault: None

Search breadth for HNSW. Uses server default if not set.

returnList[str]

List of point IDs ordered by similarity (closest first).

Example:

# Using a SearchQuery
query = SearchQuery(DenseVector([0.1, 0.2, 0.3, 0.4]), Similarity.COSINE, 10)
results = db.search(query=query)

# Using individual args with ef
results = db.search(
    vector=DenseVector([0.1, 0.2, 0.3, 0.4]),
    similarity=Similarity.COSINE,
    limit=10,
    ef=200,
)

---

batch_search

Search against multiple query vectors in a single request.

def batch_search(
    self,
    *,
    queries,
    similarity: Similarity | None = None,
    limit: int | None = None,
    ef: int | None = None,
) -> List[List[str]]

Accepts List[SearchQuery], List[(DenseVector, Similarity, int)], or bare List[DenseVector] with global similarity and limit.

returnList[List[str]]

One result list per input query.

Example:

results = db.batch_search(queries=[
    SearchQuery(DenseVector([0.1, 0.2, 0.3]), Similarity.COSINE, 5),
    (DenseVector([0.4, 0.5, 0.6]), Similarity.EUCLIDEAN, 3),
])

---

delete

Delete a point by its ID.

def delete(
    self,
    *,
    point_id: str,
) -> None

Example:

db.delete(point_id="550e8400-e29b-41d4-a716-446655440000")

---

close

Close the gRPC connection.

def close(self) -> None

Example:

db = VortexDB(grpc_url="localhost:50051", api_key="secret")
# ... use the client ...
db.close()

---

Context Manager

The client supports the context manager protocol for automatic cleanup:

with VortexDB(grpc_url="localhost:50051", api_key="secret") as db:
    point_id = db.insert(
        vector=DenseVector([0.1, 0.2, 0.3]),
        payload=Payload.text("Hello"),
    )
# Connection automatically closed

---

DenseVector

An immutable dense vector of floating-point values.

from vortexdb import DenseVector

Constructor

DenseVector(values: List[float] | Tuple[float, ...])

valuesList[float] | Tuple[float, ...]required

The vector components. Must be non-empty and contain numeric values.

Raises:

• TypeError: If values is not a list or tuple
• ValueError: If values is empty
• TypeError: If any value is not numeric

Example:

# From list
vec = DenseVector([0.1, 0.2, 0.3, 0.4])

# From tuple
vec = DenseVector((0.1, 0.2, 0.3, 0.4))

# Integers are converted to floats
vec = DenseVector([1, 2, 3, 4])  # -> [1.0, 2.0, 3.0, 4.0]

Methods

to_list

Convert the vector to a Python list.

def to_list(self) -> list[float]

Example:

vec = DenseVector([0.1, 0.2, 0.3])
values = vec.to_list()  # [0.1, 0.2, 0.3]

Properties

values

Access the vector values (read-only).

vec = DenseVector([0.1, 0.2, 0.3])
print(vec.values)  # (0.1, 0.2, 0.3)

---

Payload

Metadata associated with a vector.

from vortexdb import Payload

Factory Methods

text

Create a text payload.

@staticmethod
def text(content: str) -> Payload

Example:

payload = Payload.text("This is my document content")

image

Create an image payload.

@staticmethod
def image(content: str) -> Payload

Example:

payload = Payload.image("path/to/image.jpg")

Constructor

Payload(content_type: ContentType, content: str)

content_typeContentTyperequired

The type of content (ContentType.TEXT or ContentType.IMAGE).

contentstrrequired

The content string.

Properties

Property	Type	Description
content_type	ContentType	Type of payload
content	str	Content string

---

Point

A point returned from the database (vector + payload + ID).

from vortexdb.models import Point

Properties

Property	Type	Description
id	str	Point UUID
vector	DenseVector	The vector values
payload	Payload	Associated metadata

Methods

pretty

Return a formatted string representation.

def pretty(self) -> str

Example:

point = db.get(point_id="...")
print(point.pretty())
# Output:
# Point ID: 550e8400-e29b-41d4-a716-446655440000
# Vector: [0.1, 0.2, 0.3, 0.4]
# Payload Type: Text
# Payload Content: My document

---

Similarity

Enum for distance/similarity metrics.

from vortexdb import Similarity

Values

Value	Description
Similarity.EUCLIDEAN	L2 distance (straight line)
Similarity.MANHATTAN	L1 distance (city block)
Similarity.HAMMING	Count of differing elements
Similarity.COSINE	Angular distance

Example:

from vortexdb import Similarity

# Use in search
results = db.search(
    vector=DenseVector([0.1, 0.2, 0.3]),
    similarity=Similarity.COSINE,
    limit=5,
)

---

ContentType

Enum for payload content types.

from vortexdb.models import ContentType

Values

Value	Description
ContentType.TEXT	Text content
ContentType.IMAGE	Image reference

---

SearchQuery

Bundles a search’s parameters into a single object.

from vortexdb import SearchQuery

query = SearchQuery(DenseVector([0.1, 0.2, 0.3]), Similarity.COSINE, 10)
results = db.search(query=query)

Param	Type	Description
vector	DenseVector	Query vector
similarity	Similarity	Distance metric
limit	int	Max results

---

Exceptions

All exceptions inherit from VortexDBError.

from vortexdb import (
    VortexDBError,
    AuthenticationError,
    NotFoundError,
    InvalidArgumentError,
    TimeoutError,
    ServiceUnavailableError,
    InternalServerError,
)

Exception Hierarchy

Exception	Description
VortexDBError	Base exception for all errors
AuthenticationError	Invalid or missing API key
NotFoundError	Requested resource not found
InvalidArgumentError	Invalid input parameters
TimeoutError	Request timed out
ServiceUnavailableError	Server is unavailable
InternalServerError	Server-side error

Example:

from vortexdb.exceptions import (
    AuthenticationError,
    NotFoundError,
    VortexDBError,
)

try:
    point = db.get(point_id="nonexistent")
except NotFoundError:
    print("Point does not exist")
except AuthenticationError:
    print("Check your API key")
except VortexDBError as e:
    print(f"Unexpected error: {e}")

---

Configuration

VortexDBConfig

Internal configuration class (usually not used directly).

from vortexdb.config import VortexDBConfig

config = VortexDBConfig.from_env(
    grpc_url="localhost:50051",
    api_key="secret",
    timeout=30.0,
)

Environment Variables

Variable	Description	Default
VORTEXDB_GRPC_URL	Server address	localhost:50051
VORTEXDB_API_KEY	Authentication key	None
VORTEXDB_TIMEOUT	Request timeout (seconds)	30.0

---

Type Hints

The SDK is fully typed. Import types for type hints:

from typing import List, Optional
from vortexdb import VortexDB, DenseVector, Payload, Similarity
from vortexdb.models import Point, ContentType

def search_documents(
    db: VortexDB,
    query_vector: List[float],
    limit: int = 10,
) -> List[Optional[Point]]:
    results = db.search(
        vector=DenseVector(query_vector),
        similarity=Similarity.COSINE,
        limit=limit,
    )
    return [db.get(point_id=pid) for pid in results]

Next Steps

SDK Examples

Working code examples

API Reference

gRPC and HTTP API docs