The upstash-vector SDK is a lightweight, HTTP-based Upstash Vector client designed for Python. It seamlessly operates in both serverless and serverful environments, ensuring optimal compatibility across various connection setups.

This SDK simplifies interaction with Upstash Vector through the Upstash Vector API.

It is designed to work with Python versions 3.8 and above.

Explore the source code, contribute, and stay informed through our GitHub Repository.

Install

To begin using upstash-vector, you can install it via PyPI using the following command:

pip install upstash-vector

Usage

Before using upstash-vector, you’ll need to set up a vector database on Upstash. Once created, grab your URL and TOKEN from the Upstash console.

To initialize the index client:

from upstash_vector import Index
index = Index(url="UPSTASH_VECTOR_REST_URL", token="UPSTASH_VECTOR_REST_TOKEN")

Alternatively, you can automatically load the credentials from the environment:

from upstash_vector import Index
index = Index.from_env()

For serverless environments that allow it, it’s recommended to initialize the client outside the request handler to be reused while your function is still “hot.”

Here’s an example of how you can use the SDK in your Python application:

import random
from upstash_vector import Index

# Initialize the index client using environment variables
index = Index.from_env()

def main():
    # Define the dimension based on the index configuration
    dimension = 128
    # Generate a random vector for upsert
    vector_to_upsert = [random.random() for _ in range(dimension)]
    # Additional metadata associated with the vector
    metadata = {"text": "example test for metadata"}

    # Upsert the vector into the index
    index.upsert(vectors=[
        ("id-for-vector", vector_to_upsert, metadata)
    ])

The example above demonstrates how to upsert a vector with metadata using the SDK into the Upstash Vector database.

More SDK Features

For additional functionalities and usage examples, check out the Commands section in the documentation.