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,
)

str

default:"localhost:50051"

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

str

default:"None"

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

float

default:"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

str

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]

list[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

Point | 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]

SearchQuery

default:"None"

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

int

default:"None"

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

List[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.

List[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, ...])

List[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)

ContentType

required

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

str

required

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]

​Python SDK Reference

​Installation

​VortexDB

​Constructor

​Methods

​insert

​batch_insert

​get

​search

​batch_search

​delete

​close

​Context Manager

​DenseVector

​Constructor

​Methods

​to_list

​Properties

​values

​Payload

​Factory Methods

​text

​image

​Constructor

​Properties

​Point

​Properties

​Methods

​pretty

​Similarity

​Values

​ContentType

​Values

​SearchQuery

​Exceptions

​Exception Hierarchy

​Configuration

​VortexDBConfig

​Environment Variables

​Type Hints

​Next Steps

SDK Examples

API Reference

Python SDK Reference

Installation

VortexDB

Constructor

Methods

insert

batch_insert

get

search

batch_search

delete

close

Context Manager

DenseVector

Constructor

Methods

to_list

Properties

values

Payload

Factory Methods

text

image

Constructor

Properties

Point

Properties

Methods

pretty

Similarity

Values

ContentType

Values

SearchQuery

Exceptions

Exception Hierarchy

Configuration

VortexDBConfig

Environment Variables

Type Hints

Next Steps