# TinyVecDB Python API Documentation
This document provides a comprehensive overview of the TinyVecDB Python API.
## Table of Contents
- [Installation](#installation)
- [Core Concepts](#core-concepts)
- [Basic Usage](#basic-usage)
- [API Reference](#api-reference)
- [TinyVecClient](#tinyvecclient)
## Installation
```bash
pip install tinyvecdb
```
## Core Concepts
TinyVecDB is an embedded vector database that emphasizes speed, low memory usage, and simplicity. The core of TinyVecDB is written in C, and this library provides a Python binding to that engine. The key concepts are:
- **Embeddings**: Fixed-dimension float vectors (e.g., 512 dimensions)
- **Metadata**: JSON-serializable data associated with each vector
- **Similarity Search**: Finding the nearest neighbors to a query vector using cosine similarity
## Basic Usage
```python
import asyncio
import random
import numpy as np
from tinyvec import TinyVecClient, TinyVecConfig, TinyVecInsertion
async def example():
# Connect to database (will create the file if it doesn't exist)
client = TinyVecClient()
config = TinyVecConfig(dimensions=512)
client.connect("./vectors.db", config)
# Create a sample vector
vector = np.random.rand(512).astype(np.float32)
insertions = []
for i in range(50):
# Using NumPy (more efficient)
vec = np.random.rand(512).astype(np.float32)
# Or using standard Python lists
# vec = [random.random() for _ in range(512)]
insertions.append(TinyVecInsertion(
vector=vec,
metadata={"id": i}
))
# Insert vectors
inserted = await client.insert(insertions)
print("Inserted:", inserted)
# Search for similar vectors
results = await client.search(vector, 5)
# Example output of search results:
"""
[TinyVecResult(similarity=0.801587700843811, index=8, metadata={'id': 8}),
TinyVecResult(similarity=0.7834401726722717, index=16, metadata={'id': 16}),
TinyVecResult(similarity=0.7815409898757935, index=5, metadata={'id': 5}),
...]
"""
if __name__ == "__main__":
asyncio.run(example())
```
## API Reference
### TinyVecClient
The main class you'll interact with is `TinyVecClient`. It provides all methods for managing the vector database.
#### Constructor and Connection
##### `TinyVecClient()`
Creates a new TinyVecDB client instance.
**Example:**
```python
client = TinyVecClient()
```
##### `connect(path, config)`
Connects to a TinyVecDB database.
**Parameters:**
- `path`: `str` - Path to the database file
- `config`: `TinyVecConfig` - Configuration options
**Example:**
```python
config = TinyVecConfig(dimensions=512)
client.connect("./vectors.db", config)
```
#### Instance Methods
##### `async insert(vectors)`
Inserts vectors with metadata into the database. Each metadata item must be a JSON-serializable object.
**Parameters:**
- `vectors`: `List[TinyVecInsertion]` - List of vectors to insert
**Returns:**
- `int` - The number of vectors successfully inserted
**Example:**
```python
vector = np.zeros(512, dtype=np.float32) + 0.1
count = await client.insert([
TinyVecInsertion(
vector=vector,
metadata={"id": "doc1", "title": "Example Document"}
)
])
```
##### `async search(query_vector, top_k)`
Searches for the most similar vectors to the query vector.
**Parameters:**
- `query_vector`: `Union[List[float], np.ndarray]`
A query vector to search for, which can be any of the following types:
- Python list of numbers
- NumPy array (any numeric dtype)
Internally, it will be converted to a float32 array for similarity calculations.
- `top_k`: `int` - Number of results to return
**Returns:**
- `List[TinyVecResult]` - List of search results
**Example:**
```python
results = await client.search(query_vector, 10)
```
##### `async get_index_stats()`
Retrieves statistics about the database.
**Parameters:**
- None
**Returns:**
- `TinyVecStats` - Database statistics
**Example:**
```python
stats = await client.get_index_stats()
print(
f"Database has {stats.vector_count} vectors with {stats.dimensions} dimensions"
)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "tinyvecdb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "vector, database, similarity, search, vector database, tinyvec, vector search, similarity search",
"author": "tylerpuig",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e9/69/03c47f9daf00673ac6dfb6961787e04b732fa87f4977710c580a4f107562/tinyvecdb-0.1.2.tar.gz",
"platform": null,
"description": "# TinyVecDB Python API Documentation\r\n\r\nThis document provides a comprehensive overview of the TinyVecDB Python API.\r\n\r\n## Table of Contents\r\n\r\n- [Installation](#installation)\r\n- [Core Concepts](#core-concepts)\r\n- [Basic Usage](#basic-usage)\r\n- [API Reference](#api-reference)\r\n - [TinyVecClient](#tinyvecclient)\r\n\r\n## Installation\r\n\r\n```bash\r\npip install tinyvecdb\r\n```\r\n\r\n## Core Concepts\r\n\r\nTinyVecDB is an embedded vector database that emphasizes speed, low memory usage, and simplicity. The core of TinyVecDB is written in C, and this library provides a Python binding to that engine. The key concepts are:\r\n\r\n- **Embeddings**: Fixed-dimension float vectors (e.g., 512 dimensions)\r\n- **Metadata**: JSON-serializable data associated with each vector\r\n- **Similarity Search**: Finding the nearest neighbors to a query vector using cosine similarity\r\n\r\n## Basic Usage\r\n\r\n```python\r\nimport asyncio\r\nimport random\r\nimport numpy as np\r\nfrom tinyvec import TinyVecClient, TinyVecConfig, TinyVecInsertion\r\n\r\nasync def example():\r\n # Connect to database (will create the file if it doesn't exist)\r\n client = TinyVecClient()\r\n config = TinyVecConfig(dimensions=512)\r\n client.connect(\"./vectors.db\", config)\r\n\r\n # Create a sample vector\r\n vector = np.random.rand(512).astype(np.float32)\r\n\r\n insertions = []\r\n for i in range(50):\r\n # Using NumPy (more efficient)\r\n vec = np.random.rand(512).astype(np.float32)\r\n # Or using standard Python lists\r\n # vec = [random.random() for _ in range(512)]\r\n\r\n insertions.append(TinyVecInsertion(\r\n vector=vec,\r\n metadata={\"id\": i}\r\n ))\r\n\r\n # Insert vectors\r\n inserted = await client.insert(insertions)\r\n print(\"Inserted:\", inserted)\r\n\r\n # Search for similar vectors\r\n results = await client.search(vector, 5)\r\n\r\n # Example output of search results:\r\n \"\"\"\r\n [TinyVecResult(similarity=0.801587700843811, index=8, metadata={'id': 8}),\r\n TinyVecResult(similarity=0.7834401726722717, index=16, metadata={'id': 16}),\r\n TinyVecResult(similarity=0.7815409898757935, index=5, metadata={'id': 5}),\r\n ...]\r\n \"\"\"\r\n\r\nif __name__ == \"__main__\":\r\n asyncio.run(example())\r\n```\r\n\r\n## API Reference\r\n\r\n### TinyVecClient\r\n\r\nThe main class you'll interact with is `TinyVecClient`. It provides all methods for managing the vector database.\r\n\r\n#### Constructor and Connection\r\n\r\n##### `TinyVecClient()`\r\n\r\nCreates a new TinyVecDB client instance.\r\n\r\n**Example:**\r\n\r\n```python\r\nclient = TinyVecClient()\r\n```\r\n\r\n##### `connect(path, config)`\r\n\r\nConnects to a TinyVecDB database.\r\n\r\n**Parameters:**\r\n\r\n- `path`: `str` - Path to the database file\r\n- `config`: `TinyVecConfig` - Configuration options\r\n\r\n**Example:**\r\n\r\n```python\r\nconfig = TinyVecConfig(dimensions=512)\r\nclient.connect(\"./vectors.db\", config)\r\n```\r\n\r\n#### Instance Methods\r\n\r\n##### `async insert(vectors)`\r\n\r\nInserts vectors with metadata into the database. Each metadata item must be a JSON-serializable object.\r\n\r\n**Parameters:**\r\n\r\n- `vectors`: `List[TinyVecInsertion]` - List of vectors to insert\r\n\r\n**Returns:**\r\n\r\n- `int` - The number of vectors successfully inserted\r\n\r\n**Example:**\r\n\r\n```python\r\nvector = np.zeros(512, dtype=np.float32) + 0.1\r\ncount = await client.insert([\r\n TinyVecInsertion(\r\n vector=vector,\r\n metadata={\"id\": \"doc1\", \"title\": \"Example Document\"}\r\n )\r\n])\r\n```\r\n\r\n##### `async search(query_vector, top_k)`\r\n\r\nSearches for the most similar vectors to the query vector.\r\n\r\n**Parameters:**\r\n\r\n- `query_vector`: `Union[List[float], np.ndarray]` \r\n A query vector to search for, which can be any of the following types:\r\n\r\n - Python list of numbers\r\n - NumPy array (any numeric dtype)\r\n\r\n Internally, it will be converted to a float32 array for similarity calculations.\r\n\r\n- `top_k`: `int` - Number of results to return\r\n\r\n**Returns:**\r\n\r\n- `List[TinyVecResult]` - List of search results\r\n\r\n**Example:**\r\n\r\n```python\r\nresults = await client.search(query_vector, 10)\r\n```\r\n\r\n##### `async get_index_stats()`\r\n\r\nRetrieves statistics about the database.\r\n\r\n**Parameters:**\r\n\r\n- None\r\n\r\n**Returns:**\r\n\r\n- `TinyVecStats` - Database statistics\r\n\r\n**Example:**\r\n\r\n```python\r\nstats = await client.get_index_stats()\r\nprint(\r\n f\"Database has {stats.vector_count} vectors with {stats.dimensions} dimensions\"\r\n)\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "TinyVecDB is a high performance, lightweight, embedded vector database for similarity search.",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/tylerpuig/tinyvec"
},
"split_keywords": [
"vector",
" database",
" similarity",
" search",
" vector database",
" tinyvec",
" vector search",
" similarity search"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "201dc5c32ad63179a00caee33f09b60bb480fc5a49b6895f9eebcb44c649a259",
"md5": "891ad0ac638b496d2f5aa326b528be16",
"sha256": "80e79dd0121bd14f3acae6d4c948bf893a5a3a1a82d6c2518d7964efeadc24fa"
},
"downloads": -1,
"filename": "tinyvecdb-0.1.2-py3-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "891ad0ac638b496d2f5aa326b528be16",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 45766,
"upload_time": "2025-02-27T00:09:51",
"upload_time_iso_8601": "2025-02-27T00:09:51.137787Z",
"url": "https://files.pythonhosted.org/packages/20/1d/c5c32ad63179a00caee33f09b60bb480fc5a49b6895f9eebcb44c649a259/tinyvecdb-0.1.2-py3-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e96903c47f9daf00673ac6dfb6961787e04b732fa87f4977710c580a4f107562",
"md5": "422e67dc24d2c0031c305e177c185234",
"sha256": "cc09fd7eacb32389da66d557262b9fe6e811b895e4677074000aa1d5c88e6ebd"
},
"downloads": -1,
"filename": "tinyvecdb-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "422e67dc24d2c0031c305e177c185234",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 46266,
"upload_time": "2025-02-27T00:09:54",
"upload_time_iso_8601": "2025-02-27T00:09:54.427105Z",
"url": "https://files.pythonhosted.org/packages/e9/69/03c47f9daf00673ac6dfb6961787e04b732fa87f4977710c580a4f107562/tinyvecdb-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-27 00:09:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tylerpuig",
"github_project": "tinyvec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tinyvecdb"
}
JSON
