tinyvector Documentation

tinyvector is a tiny embedding database written in pure Rust. It is designed as an Axum server, making it extremely easy to customize (approximately 600 lines of code).

Key Characteristics:

• Fast: Provides comparable speed to advanced vector databases for small to medium datasets.
• Vertical Scaling: Stores all indexes in memory for high-speed querying, capable of scaling to 100 million+ vector dimensions.
• Open Source: Distributed under the MIT license.

You can install tinyvector directly via Cargo or build it from the repository source.

Install via Cargo

To install the latest tagged release, use:

cargo install tinyvector

After installation, you can start the server by running tinyvector.

Build from latest commit

To build from the current repository state:

1. Clone the repository.
2. Run cargo build --release.
3. Execute the binary located at ./target/release/tinyvector.

You can run a lightweight Docker container to get tinyvector up and running immediately. By default, the container handles persistence automatically.

Important for Persistence: If you are using Docker Compose or Kubernetes, you must manually bind a volume to /tinyvector/storage to ensure your data is not lost when the container stops.

docker run \
  -p 8000:8000 \
  ghcr.io/m1guelpf/tinyvector:edge

The tinyvector server is the primary entrypoint for the application. It initializes logging via tracing-subscriber and starts the server using the internal server::start() routine.

By default, the server uses the tinyvector=info log level unless the RUST_LOG environment variable is set. You can control the verbosity of the server logs by setting this environment variable before execution.

# Run with default info logging
./tinyvector

# Run with debug logging
RUST_LOG=tinyvector=debug ./tinyvector

The Tinyvector server uses the PORT environment variable to determine which network port to bind to. If the PORT variable is not provided, the server defaults to port 8000.

Environment Variable:

• PORT: The port number on which the server should listen (e.g., PORT=9000).

# Example: Running the server on port 9000
PORT=9000 ./tinyvector_binary

The ScoreIndex struct is used to associate a similarity score with a vector's index.

Crucial Behavior: The PartialOrd and Ord implementations are intentionally reversed. This means that when ScoreIndex objects are used in a standard Rust BinaryHeap, the heap will act as a min-heap based on the score. This is typically used to maintain a collection of the

The tinyvector API provides a set of endpoints under the /collections prefix to manage vector collections. You can create, query, inspect, and delete collections using standard HTTP methods.

### API Endpoints Summary

| Method | Endpoint | Description |
|--------|----------|-------------|
| `PUT` | `/collections/:collection_name` | Create a new collection |
| `POST` | `/collections/:collection_name` | Query a collection for similar vectors |
| `GET` | `/collections/:collection_name` | Get metadata/info about a collection |
| `DELETE` | `/collections/:collection_name` | Delete a collection |
| `POST` | `/collections/:collection_name/insert` | Insert a new vector embedding into a collection |

Perform a POST request to /shutdown to initiate the system's shutdown process. This endpoint interacts with the Shutdown::Agent to start the graceful exit sequence. The response is a simple JSON string: "Shutting down...".

curl -X POST http://<host>/shutdown

Perform a similarity search by sending a POST request to /collections/:collection_name. The API will return the most similar vectors based on the collection's distance metric.

Request Body Schema (QueryCollectionQuery):

• query (Vec<f32>): The vector to use for the search.
• k (Option<usize>): The number of results to return (defaults to 1 if not provided).

Responses:

• 200 OK: Returns a JSON array of SimilarityResult objects.
• 400 Bad Request: The dimension of the query vector does not match the collection's dimension.
• 404 Not Found: The specified collection does not exist.

POST /collections/my-vectors HTTP/1.1
Content-Type: application/json

{
  "query": [0.1, 0.2, 0.3, ...],
  "k": 5
}

The HTTPError struct is used to represent and return structured error responses in an Axum-based web service. It allows you to specify a JSON error detail and an associated HTTP status code.

By default, creating an error via HTTPError::new(detail) sets the status code to StatusCode::UNPROCESSABLE_ENTITY. You can chain the .with_status(status_code) method to override this with a different status code.

When converted into a response, it returns a JSON object with the format: {"error": <detail>}.

// Create a default error (422 Unprocessable Entity)
let err = HTTPError::new("invalid input");

// Create an error with a specific status code
let err = HTTPError::new("not found").with_status(StatusCode::NOT_FOUND);

The normalize function scales a vector so that its magnitude is 1.0. If the vector's magnitude is near zero (less than std::f32::EPSILON), it returns the original vector to avoid division by zero.

Use this when preparing vectors for Cosine similarity, as the internal implementation of Cosine similarity in tinyvector relies on pre-normalized vectors.

let vec = vec![3.0, 4.0];
let normalized = normalize(&vec);
// normalized will be [0.6, 0.8]

Retrieve metadata about a specific collection using a GET request to /collections/:collection_name.

Response Body Schema (CollectionInfo):

• name (string): The name of the collection.
• dimension (usize): The dimensionality of embeddings.
• distance (Distance): The distance function used.
• embedding_count (usize): The total number of vectors currently stored in the collection.

Responses:

• 200 OK: Returns the CollectionInfo JSON.
• 404 Not Found: The collection was not found.

GET /collections/my-vectors HTTP/1.1