title	SDK Reference
description	Complete Python SDK API documentation

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

The gRPC server address. Can also be set via `VORTEXDB_GRPC_URL` environment variable. Authentication key for the gRPC API. Can also be set via `VORTEXDB_API_KEY` environment variable. 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

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

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]

A `SearchQuery` object bundling vector, similarity, and limit. Use this or pass individual args. Search breadth for HNSW. Uses server default if not set. 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.

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, ...] | array | tensor)

A list, tuple, 1D NumPy array, or 1D PyTorch, TensorFlow, or JAX tensor. Must be non-empty and contain numeric values.

Raises:

TypeError: If values is not a supported sequence, array, or tensor
ValueError: If values is not one-dimensional
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]

# NumPy arrays and tensors can be passed directly
vec = DenseVector(numpy_array)
vec = DenseVector(torch_tensor)
vec = DenseVector(tensorflow_tensor)
vec = DenseVector(jax_array)

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]

Framework conversions

Convert the vector to an array or tensor from an installed framework.

numpy_array = vec.to_numpy()
torch_tensor = vec.to_torch()
tensorflow_tensor = vec.to_tensorflow()
jax_array = vec.to_jax()

The framework libraries are optional and are imported only when their conversion methods are called.

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)

The type of content (`ContentType.TEXT` or `ContentType.IMAGE`). 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

Working code examples gRPC and HTTP API docs

FilesExpand file tree

reference.mdx

Latest commit

History

reference.mdx

File metadata and controls

Python SDK Reference

Installation

VortexDB

Constructor

Methods

insert

batch_insert

get

search

batch_search

delete

close

Context Manager

DenseVector

Constructor

Methods

to_list

Framework conversions

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