tinyvecdb


Nametinyvecdb JSON
Version 0.1.2 PyPI version JSON
download
home_pageNone
SummaryTinyVecDB is a high performance, lightweight, embedded vector database for similarity search.
upload_time2025-02-27 00:09:54
maintainerNone
docs_urlNone
authortylerpuig
requires_python>=3.9
licenseMIT
keywords vector database similarity search vector database tinyvec vector search similarity search
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.71209s