Package: vectordb
A Python vector database you just need - no more, no less.vectordbis a Pythonic vector database offers a comprehensive suite ofCRUD(Create, Read, Update, Delete) operations and robustscalability options, including sharding and replication. It's readily deployable in a variety of environments, fromlocaltoon-premiseandcloud.vectordbdelivers exactly what you need - no more, no less. It's a testament to effective Pythonic design without over-engineering, making it a lean yet powerful solution for all your needs.vectordbcapitalizes on the powerful retrieval prowess ofDocArrayand the scalability, reliability, and serving capabilities ofJina. Here's the magic: DocArray serves as the engine driving vector search logic, while Jina guarantees efficient and scalable index serving. This synergy culminates in a robust, yet user-friendly vector database experience - that'svectordbfor you.InstallpipinstallvectordbGetting started withvectordblocallyKick things off by defining a Document schema with theDocArraydataclass syntax:fromdocarrayimportBaseDocfromdocarray.typingimportNdArrayclassToyDoc(BaseDoc):text:str=''embedding:NdArray[128]Opt for a pre-built database (likeInMemoryExactNNVectorDBorHNSWVectorDB), and apply the schema:fromdocarrayimportDocListimportnumpyasnpfromvectordbimportInMemoryExactNNVectorDB,HNSWVectorDB# Specify your workspace pathdb=InMemoryExactNNVectorDB[ToyDoc](workspace='./workspace_path')# Index a list of documents with random embeddingsdoc_list=[ToyDoc(text=f'toy doc{i}',embedding=np.random.rand(128))foriinrange(1000)]db.index(inputs=DocList[ToyDoc](doc_list))# Perform a search queryquery=ToyDoc(text='query',embedding=np.random.rand(128))results=db.search(inputs=DocList[ToyDoc]([query]),limit=10)# Print out the matchesforminresults[0].matches:print(m)Since we issued a single query,resultscontains only one element. The nearest neighbour search results are conveniently stored in the.matchesattribute.Getting started withvectordbas a servicevectordbis designed to be easily served as a service, supportinggRPC,HTTP, andWebsocketcommunication protocols.Server SideOn the server side, you would start the service as follows:withdb.serve(protocol='grpc',port=12345,replicas=1,shards=1)asservice:service.block()This command startsvectordbas a service on port12345, using thegRPCprotocol with1replica and1shard.Client SideOn the client side, you can access the service with the following commands:fromvectordbimportClient# Instantiate a client connected to the server. In practice, replace 0.0.0.0 to the server IP address.client=Client[ToyDoc](address='grpc://0.0.0.0:12345')# Perform a search queryresults=client.search(inputs=DocList[ToyDoc]([query]),limit=10)This allows you to perform a search query, receiving the results directly from the remotevectordbservice.Hostingvectordbon Jina AI CloudYou can seamlessly deploy yourvectordbinstance to Jina AI Cloud, which ensures access to your database from any location.Start by embedding your database instance or class into a Python file:# example.pyfromdocarrayimportBaseDocfromvectordbimportInMemoryExactNNVectorDBdb=InMemoryExactNNVectorDB[ToyDoc](workspace='./vectordb')# notice how `db` is the instance that we want to serveif__name__=='__main__':# IMPORTANT: make sure to protect this part of the code using __main__ guardwithdb.serve()asservice:service.block()Next, follow these steps to deploy your instance:If you haven't already, sign up for aJina AI Cloudaccount.Use thejccommand line to login to your Jina AI Cloud account:jcloginDeploy your instance:vectordbdeploy--dbexample:dbConnect from the clientAfter deployment, use thevectordbClient to access the assigned endpoint:fromvectordbimportClient# replace the ID with the ID of your deployed DB as shown in the screenshot abovec=Client(address='grpcs://ID.wolf.jina.ai')Manage your deployed instances usingjcloudYou can then list, pause, resume or delete your deployed DBs withjccommand:jcloud list IDjcloud pause IDorjcloud resume IDjcloud remove IDAdvanced TopicsWhat is a vector database?Vector databases serve as sophisticated repositories for embeddings, capturing the essence of semantic similarity among disparate objects. These databases facilitate similarity searches across a myriad of multimodal data types, paving the way for a new era of information retrieval. By providing contextual understanding and enriching generation results, vector databases greatly enhance the performance and utility of Language Learning Models (LLM). This underscores their pivotal role in the evolution of data science and machine learning applications.CRUD supportBoth the local library usage and the client-server interactions invectordbshare the same API. This providesindex,search,update, anddeletefunctionalities:index: Accepts aDocListto index.search: Takes aDocListof batched queries or a singleBaseDocas a single query. It returns either single or multiple results, each withmatchesandscoresattributes sorted byrelevance.delete: Accepts aDocListof documents to remove from the index. Only theidattribute is necessary, so make sure to track theindexedIDsif you need to delete documents.update: Accepts aDocListof documents to update in the index. Theupdateoperation will replace theindexeddocument with the same index with the attributes and payload from the input documents.Service endpoint configurationYou can servevectordband access it from a client with the following parameters:protocol: The serving protocol. It can begRPC,HTTP,websocketor a combination of them, provided as a list. Default isgRPC.port: The service access port. Can be a list of ports for each provided protocol. Default is 8081.workspace: The path where the VectorDB persists required data. Default is '.' (current directory).Scaling your DBYou can set two scaling parameters when serving or deploying your Vector Databases withvectordb:Shards: The number of data shards. This improves latency, asvectordbensures Documents are indexed in only one of the shards. Search requests are sent to all shards and results are merged.Replicas: The number of DB replicas.vectordbuses theRAFTalgorithm to sync the index between replicas of each shard. This increases service availability and search throughput, as multiple replicas can respond in parallel to more search requests while allowing CRUD operations. Note: In JCloud deployments, the number of replicas is set to 1. We're working on enabling replication in the cloud.Vector search configurationHere are the parameters for eachVectorDBtype:InMemoryExactNNVectorDBThis database performs exhaustive search on embeddings and has limited configuration settings:workspace: The folder where required data is persisted.InMemoryExactNNVectorDB[MyDoc](workspace='./vectordb')InMemoryExactNNVectorDB[MyDoc].serve(workspace='./vectordb')HNSWVectorDBThis database employs the HNSW (Hierarchical Navigable Small World) algorithm fromHNSWLibfor Approximate Nearest Neighbor search. It provides several configuration options:workspace: Specifies the directory where required data is stored and persisted.Additionally, HNSWVectorDB offers a set of configurations that allow tuning the performance and accuracy of the Nearest Neighbor search algorithm. Detailed descriptions of these configurations can be found in theHNSWLib README:space: Specifies the similarity metric used for the space (options are "l2", "ip", or "cosine"). The default is "l2".max_elements: Sets the initial capacity of the index, which can be increased dynamically. The default is 1024.ef_construction: This parameter controls the speed/accuracy trade-off during index construction. The default is 200.ef: This parameter controls the query time/accuracy trade-off. The default is 10.M: This parameter defines the maximum number of outgoing connections in the graph. The default is 16.allow_replace_deleted: If set toTrue, this allows replacement of deleted elements with newly added ones. The default isFalse.num_threads: This sets the default number of threads to be used duringindexandsearchoperations. The default is 1.Command line interfacevectordbincludes a simple CLI for serving and deploying your database:DescriptionCommandServe your DB locallyvectordb serve --db example:dbDeploy your DB on Jina AI Cloudvectordb deploy --db example:dbFeaturesUser-friendly Interface:Withvectordb, simplicity is key. Its intuitive interface is designed to accommodate users across varying levels of expertise.Minimalistic Design:vectordbpacks all the essentials, with no unnecessary complexity. It ensures a seamless transition from local to server and cloud deployment.Full CRUD Support:From indexing and searching to updating and deleting,vectordbcovers the entire spectrum of CRUD operations.DB as a Service:Harness the power of gRPC, HTTP, and Websocket protocols withvectordb. It enables you to serve your databases and conduct insertion or searching operations efficiently.Scalability:Experience the raw power ofvectordb's deployment capabilities, including robust scalability features like sharding and replication. Improve your service latency with sharding, while replication enhances availability and throughput.Cloud Deployment:Deploying your service in the cloud is a breeze withJina AI Cloud. More deployment options are coming soon!Serverless Capability:vectordbcan be deployed in a serverless mode in the cloud, ensuring optimal resource utilization and data availability as per your needs.Multiple ANN Algorithms:vectordboffers diverse implementations of Approximate Nearest Neighbors (ANN) algorithms. Here are the current offerings, with more integrations on the horizon:InMemoryExactNNVectorDB (Exact NN Search): Implements Simple Nearest Neighbor Algorithm.HNSWVectorDB (based on HNSW): UtilizesHNSWLibRoadmapThe future of Vector Database looks bright, and we have ambitious plans! Here's a sneak peek into the features we're currently developing:More ANN Search Algorithms: Our goal is to support an even wider range of ANN search algorithms.Enhanced Filtering Capabilities: We're working on enhancing our ANN Search solutions to support advanced filtering.Customizability: We aim to makevectordbhighly customizable, allowing Python developers to tailor its behavior to their specific needs with ease.Expanding Serverless Capacity: We're striving to enhance the serverless capacity ofvectordbin the cloud. While we currently support scaling between 0 and 1 replica, our goal is to extend this to 0 to N replicas.Expanded Deployment Options: We're actively working on facilitating the deployment ofvectordbacross various cloud platforms, with a broad range of options.Need help withvectordb? Interested in using it but require certain features to meet your unique needs? Don't hesitate to reach out to us. Join ourDiscord communityto chat with us and other community members.ContributingThe VectorDB project is backed byJina AIand licensed under Apache-2.0. Contributions from the community are greatly appreciated! If you have an idea for a new feature or an improvement, we would love to hear from you. We're always looking for ways to makevectordbmore user-friendly and effective.