repository·main·Indexed 20 days ago
https://github.com/jina-ai/vectordbA Pythonic vector database designed for simplicity and scalability. It leverages DocArray for vector search logic and schema definition via BaseDoc, and Jina for scalable index serving. vectordb supports local development with engines like InMemoryExactNNVectorDB and HNSWVectorDB, as well as production deployment as a service via gRPC, HTTP, or WebSocket, including deployment to Jina AI Cloud.
The vectordb architecture leverages two core technologies:
This allows developers to use DocArray's dataclass syntax for schema definition while benefiting from Jina's ability to scale the database in production environments.
Both local library usage and client-server interactions support the following CRUD operations:
index: Accepts a DocList to add documents to the index.search: Takes a DocList of batched queries or a single BaseDoc. Returns results with matches and scores attributes, sorted by relevance.update: Accepts a DocList to replace existing documents with new attributes and payloads based on matching indices.delete: Accepts a DocList of documents to remove. Only the id attribute is required for deletion.Once your database is deployed to Jina AI Cloud, you can manage its lifecycle (list, pause, resume, or delete) using the jcloud command line tool.
# List all deployed DBs
jcloud list ID
# Pause a DB
jcloud pause ID
# Resume a DB
jcloud resume ID
# Remove a DB
jcloud remove IDYou can deploy your vectordb instance to Jina AI Cloud to ensure global access.
__main__ guard and the .serve() method.jc CLI to log in to your Jina AI Cloud account.vectordb deploy command, specifying your database instance using the module:instance syntax.To connect from a client after deployment, use the vectordb.Client with the assigned grpcs:// endpoint.
# example.py
from docarray import BaseDoc
from vectordb import InMemoryExactNNVectorDB
class ToyDoc(BaseDoc):
text: str
db = InMemoryExactNNVectorDB[ToyDoc](workspace='./vectordb')
if __name__ == '__main__':
# IMPORTANT: use __main__ guard
with db.serve() as service:
service.block()# Login to Jina AI Cloud
jc login
# Deploy the instance (example:db refers to example.py:db)
vectordb deploy --db example:dbfrom vectordb import Client
# Connect using the deployed endpoint
c = Client(address='grpcs://ID.wolf.jina.ai')Install the vectordb package using pip to get started with Pythonic vector database operations.
pip install vectordbYou can deploy vectordb as a remote service supporting grpc, http, or websocket protocols.
Server Side: Use the .serve() method on your database instance to start the service. You can configure the protocol, port, replicas, and shards.
Client Side: Use the Client class to connect to the remote address using the appropriate protocol prefix (e.g., grpc://).
# --- Server Side ---
# Assuming 'db' is an initialized database instance
with db.serve(protocol='grpc', port=12345, replicas=1, shards=1) as service:
service.block()
# --- Client Side ---
from vectordb import Client
from docarray import DocList
# Connect to the server
client = Client[ToyDoc](address='grpc://0.0.0.0:12345')
# Perform remote search
query = ToyDoc(text='query', embedding=np.random.rand(128))
results = client.search(inputs=DocList[ToyDoc]([query]), limit=10)To use vectordb locally, define your document schema using DocArray's BaseDoc syntax, instantiate a database engine (such as InMemoryExactNNVectorDB or HNSWVectorDB), and provide a workspace path for storage. You can then index DocList objects and perform searches.
from docarray import BaseDoc, DocList
from docarray.typing import NdArray
import numpy as np
from vectordb import InMemoryExactNNVectorDB
# 1. Define schema
class ToyDoc(BaseDoc):
text: str = ''
embedding: NdArray[128]
# 2. Initialize DB with workspace
db = InMemoryExactNNVectorDB[ToyDoc](workspace='./workspace_path')
# 3. Index documents
doc_list = [ToyDoc(text=f'toy doc {i}', embedding=np.random.rand(128)) for i in range(1000)]
db.index(inputs=DocList[ToyDoc](doc_list))
# 4. Search
query = ToyDoc(text='query', embedding=np.random.rand(128))
results = db.search(inputs=DocList[ToyDoc]([query]), limit=10)
# 5. Access matches
for m in results[0].matches:
print(m)When serving vectordb, you can configure the following parameters:
Service Configuration:
protocol: The serving protocol (e.g., gRPC, HTTP, websocket, or a list of them). Default is gRPC.port: The service access port (or list of ports). Default is 8081.workspace: The path where data persists. Default is '.'.Scaling Parameters:
Shards: Increases latency performance by indexing documents in specific shards. Search requests are sent to all shards and results are merged.Replicas: Increases availability and throughput using the RAFT algorithm to sync indices. Note: In JCloud deployments, replicas are currently set to 1.The HNSWVectorDB uses the HNSWLib algorithm for Approximate Nearest Neighbor search. In addition to the workspace parameter, you can tune the following:
space: Similarity metric (`The Client class supports generic type hinting using docarray.BaseDoc subclasses. By using the bracket notation Client[YourDocType], you can specify the schema for input and output documents, which enables better IDE support and static type checking for the data being indexed and searched.
from docarray import BaseDoc
from vectordb.client.client import Client
class MyDoc(BaseDoc):
text: str
embedding: list[float]
# Create a typed client for MyDoc
typed_client = Client[MyDoc]The search method performs a similarity search. It automatically sorts matches by their scores and returns results as a DocList typed to the client's output schema. It accepts arguments and keyword arguments passed to the underlying client.
# Perform a search query
results = client.search(query_embedding)Use the index method (or its alias post) to add documents to the vector database. This method accepts arguments and keyword arguments that are passed through to the underlying client.
# Using index
client.index(docs)
# Using post (alias for index)
client.post(docs)