### Configure and Start OasysDB via CLI

Source: https://context7.com/oasysai/oasysdb/llms.txt

Use the CLI to define database parameters like dimension and distance metric, then start the server.

```bash
# Configure database with 128-dimensional vectors using Euclidean distance
oasysdb configure --dim 128 --metric euclidean --density 256

# Configure with cosine distance for normalized embeddings
oasysdb configure --dim 1536 --metric cosine --density 512

# Start the database server on default port 2505
oasysdb start

# Start on a custom port
oasysdb start --port 3000
```

--------------------------------

### Run Benchmarks

Source: https://github.com/oasysai/oasysdb/blob/main/docs/changelog.md

Execute this command to measure the performance of saving and getting collections. This helps in identifying performance bottlenecks.

```sh
cargo bench
```

--------------------------------

### OasysDB Filter Syntax Examples

Source: https://context7.com/oasysai/oasysdb/llms.txt

Demonstrates various filter syntaxes supported by OasysDB for metadata filtering, including text, numeric, and boolean operators.

```bash
# Text filters
# Equal: exact match
"name = Alice"

# Not equal
"name != Bob"

# Contains: substring match
"title CONTAINS machine"

# Numeric filters
# Equal
"year = 2024"

# Comparisons
"score > 85"
"rating >= 4.5"
"age < 30"
"price <= 100.0"

# Boolean filters
"published = true"
"archived != false"

# Combined filters with AND (all conditions must match)
"category = AI AND year >= 2020 AND published = true"

# Combined filters with OR (any condition must match)
"category = AI OR category = ML OR category = Data Science"

# Note: Mixing AND and OR in the same filter is not supported
```

--------------------------------

### Get Record

Source: https://context7.com/oasysai/oasysdb/llms.txt

Retrieve an existing record by its UUID.

```APIDOC
## gRPC Get

### Description
Retrieve an existing record by its UUID, returning the vector data and metadata.

### Method
gRPC rpc

### Endpoint
database.Database/Get

### Request Body
- **id** (string) - The UUID of the record to retrieve.

### Request Example
{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

### Response
#### Success Response (200)
- **record** (Record) - The record object containing vector data and metadata.

#### Response Example
{
  "record": {
    "vector": {
      "data": [0.1, 0.2, 0.3, 0.4]
    },
    "metadata": {
      "title": {"text": "Introduction to Machine Learning"},
      "category": {"text": "AI"},
      "year": {"number": 2024},
      "published": {"boolean": true}
    }
  }
}
```

--------------------------------

### Configure Distance Metrics in OasysDB

Source: https://context7.com/oasysai/oasysdb/llms.txt

Select the distance metric based on your embedding model and use case. Euclidean is suitable for general purposes where absolute distances matter, while Cosine is best for normalized embeddings and text similarity. Examples show calculating distances between vectors.

```rust
use oasysdb::types::Metric;

// Euclidean distance (squared) - default
// Best for: general purpose, absolute distances matter
// Lower values = more similar
let euclidean = Metric::Euclidean;

// Cosine distance
// Best for: normalized embeddings, text similarity
// Lower values = more similar (0 = identical direction)
let cosine = Metric::Cosine;

// Calculate distance between two vectors
let a = Vector::from(vec![1.0, 2.0, 3.0]);
let b = Vector::from(vec![4.0, 5.0, 6.0]);

let euclidean_dist = Metric::Euclidean.distance(&a, &b); // Some(27.0)
let cosine_dist = Metric::Cosine.distance(&a, &b);       // Some(~0.025)
```

--------------------------------

### Create Manual Database Snapshot

Source: https://context7.com/oasysai/oasysdb/llms.txt

Triggers a manual database snapshot using grpcurl and displays the expected response containing the number of records.

```bash
# Create a manual snapshot
grpcurl -plaintext localhost:2505 database.Database/Snapshot

# Expected response:
# {
#   "count": 15000
# }
```

--------------------------------

### Replace Database::create_collection with Database::save_collection

Source: https://github.com/oasysai/oasysdb/blob/main/docs/changelog.md

The `Database::create_collection` method has been removed. Use `Collection::build` to create a collection and then `db.save_collection` to save it.

```rust
// Before: this creates a new empty collection.
db.create_collection("vectors", None, Some(records))?;

// After: create new or build a collection then save it.
// let collection = Collection::new(&config)?;
let collection = Collection::build(&config, &records)?;
db.save_collection("vectors", &collection)?;
```

--------------------------------

### Set OasysDB Environment Variables

Source: https://context7.com/oasysai/oasysdb/llms.txt

Configure the storage directory path before launching the server.

```bash
# Set custom database directory (defaults to ./oasysdb)
export ODB_DIR=/var/lib/oasysdb

# Start the server
oasysdb start --port 2505
```

--------------------------------

### POST database.Database/Snapshot

Source: https://context7.com/oasysai/oasysdb/llms.txt

Manually trigger a database snapshot to persist current state to disk.

```APIDOC
## POST database.Database/Snapshot

### Description
Manually trigger a database snapshot to persist current state to disk.

### Method
POST

### Endpoint
database.Database/Snapshot

### Response
#### Success Response (200)
- **count** (int32) - Number of records in the snapshot.

#### Response Example
{
  "count": 15000
}
```

--------------------------------

### OasysDB Rust Library Integration

Source: https://context7.com/oasysai/oasysdb/llms.txt

Demonstrates integrating OasysDB as an embedded library in Rust, including configuring parameters, opening the database, and creating records.

```rust
use oasysdb::types::{Vector, Record, Value, Metric};
use oasysdb::cores::{Database, Parameters, QueryParameters};
use std::collections::HashMap;
use std::sync::Arc;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure database parameters
    let params = Parameters {
        dimension: 128,
        metric: Metric::Euclidean,
        density: 256,
    };

    // Initialize and configure the database
    Database::configure(&params);

    // Open the database
    let db = Arc::new(Database::open()?);

    // Create a vector from f32 values
    let embedding: Vec<f32> = vec![0.1; 128];
    let vector = Vector::from(embedding);

    // Create metadata
    let mut metadata = HashMap::new();
    metadata.insert("title".to_string(), Value::Text("Document Title".to_string()));
    metadata.insert("score".to_string(), Value::Number(0.95));
    metadata.insert("active".to_string(), Value::Boolean(true));

    // Create a record
    let record = Record {
        vector,
        metadata,
    };

    // Create a snapshot to persist data
    let stats = db.create_snapshot()?;
    println!("Snapshot created with {} records", stats.count);

    Ok(())
}
```

--------------------------------

### Nearest Neighbor Query with Custom Parameters

Source: https://context7.com/oasysai/oasysdb/llms.txt

Runs a nearest neighbor query with custom parameters for improved recall using grpcurl.

```bash
# Query with custom parameters for better recall
grpcurl -plaintext -d '{
  "vector": {
    "data": [0.15, 0.25, 0.35, 0.45]
  },
  "k": 10,
  "filter": "year > 2022",
  "params": {
    "probes": 64,
    "radius": 5.0
  }
}' localhost:2505 database.Database/Query
```

--------------------------------

### Import Commonly Used Types with Prelude

Source: https://github.com/oasysai/oasysdb/blob/main/docs/changelog.md

Simplify library usage by importing the prelude module, which re-exports the most commonly used types and traits.

```rust
use oasysdb::prelude::*;
```

--------------------------------

### Basic Nearest Neighbor Query

Source: https://context7.com/oasysai/oasysdb/llms.txt

Performs a basic nearest neighbor query for the top 5 results using grpcurl.

```bash
# Basic nearest neighbor query for top 5 results
grpcurl -plaintext -d '{
  "vector": {
    "data": [0.15, 0.25, 0.35, 0.45]
  },
  "k": 5
}' localhost:2505 database.Database/Query
```

--------------------------------

### Tune OasysDB Query Parameters

Source: https://context7.com/oasysai/oasysdb/llms.txt

Adjust query parameters to balance search accuracy and performance. Default parameters use 32 probes and infinite radius. High recall increases probes for accuracy, while fast search reduces probes and sets a radius for quicker results.

```rust
use oasysdb::cores::QueryParameters;

// Default parameters: probes=32, radius=infinity
let default_params = QueryParameters::default();

// High recall configuration (slower, more accurate)
let high_recall = QueryParameters {
    probes: 64,           // Visit more clusters
    radius: f32::INFINITY, // No distance limit
};

// Fast search with distance threshold
let fast_search = QueryParameters {
    probes: 16,    // Visit fewer clusters
    radius: 10.0,  // Only return results within distance 10
};

// Precision-focused with tight radius
let precision_search = QueryParameters {
    probes: 48,
    radius: 2.5,  // Only very close matches
};
```

--------------------------------

### Check OasysDB Heartbeat

Source: https://context7.com/oasysai/oasysdb/llms.txt

Verify server connectivity and version using gRPC or grpcurl.

```protobuf
// Proto definition
service Database {
    rpc Heartbeat(google.protobuf.Empty) returns (HeartbeatResponse);
}

message HeartbeatResponse {
    string version = 1;
}
```

```bash
# Using grpcurl to check heartbeat
grpcurl -plaintext localhost:2505 database.Database/Heartbeat

# Expected response:
# {
#   "version": "0.8.0"
# }
```

--------------------------------

### Nearest Neighbor Query with AND Filter

Source: https://context7.com/oasysai/oasysdb/llms.txt

Performs a nearest neighbor query with combined AND filter conditions using grpcurl.

```bash
# Query with AND filter conditions
grpcurl -plaintext -d '{
  "vector": {
    "data": [0.15, 0.25, 0.35, 0.45]
  },
  "k": 10,
  "filter": "year >= 2020 AND published = true"
}' localhost:2505 database.Database/Query
```

--------------------------------

### Nearest Neighbor Query with OR Filter

Source: https://context7.com/oasysai/oasysdb/llms.txt

Executes a nearest neighbor query with combined OR filter conditions using grpcurl.

```bash
# Query with OR filter conditions
grpcurl -plaintext -d '{
  "vector": {
    "data": [0.15, 0.25, 0.35, 0.45]
  },
  "k": 10,
  "filter": "category = AI OR category = ML"
}' localhost:2505 database.Database/Query
```

--------------------------------

### Insert Records into OasysDB

Source: https://context7.com/oasysai/oasysdb/llms.txt

Define the Insert gRPC service and perform a record insertion with vector data and metadata.

```protobuf
// Proto definition
rpc Insert(InsertRequest) returns (InsertResponse);

message InsertRequest {
    Record record = 1;
}

message InsertResponse {
    string id = 1;
}

message Record {
    Vector vector = 1;
    map<string, Value> metadata = 2;
}

message Vector {
    repeated float data = 1;
}

message Value {
    oneof value {
        string text = 1;
        double number = 2;
        bool boolean = 4;
    }
}
```

```bash
# Insert a record with a 4-dimensional vector and metadata
grpcurl -plaintext -d '{
  "record": {
    "vector": {
      "data": [0.1, 0.2, 0.3, 0.4]
    },
    "metadata": {
      "title": {"text": "Introduction to Machine Learning"},
      "category": {"text": "AI"},
      "year": {"number": 2024},
      "published": {"boolean": true}
    }
  }
}' localhost:2505 database.Database/Insert

# Expected response:
# {
#   "id": "550e8400-e29b-41d4-a716-446655440000"
# }
```

--------------------------------

### OasysDB Snapshot Persistence

Source: https://context7.com/oasysai/oasysdb/llms.txt

Defines the protobuf messages for manually triggering a database snapshot to persist the current state to disk.

```protobuf
// Proto definition
rpc Snapshot(google.protobuf.Empty) returns (SnapshotResponse);

message SnapshotResponse {
    int32 count = 1;  // Number of records in the snapshot
}
```

--------------------------------

### Nearest Neighbor Query with Metadata Filter

Source: https://context7.com/oasysai/oasysdb/llms.txt

Executes a nearest neighbor query with a single metadata filter condition using grpcurl.

```bash
# Query with metadata filter (single condition)
grpcurl -plaintext -d '{
  "vector": {
    "data": [0.15, 0.25, 0.35, 0.45]
  },
  "k": 10,
  "filter": "category = AI"
}' localhost:2505 database.Database/Query
```

--------------------------------

### gRPC Heartbeat

Source: https://context7.com/oasysai/oasysdb/llms.txt

Check the database connection status and retrieve the server version.

```APIDOC
## gRPC Heartbeat

### Description
Check database connection status and retrieve server version information.

### Method
gRPC rpc

### Endpoint
database.Database/Heartbeat

### Response
#### Success Response (200)
- **version** (string) - The version of the OasysDB server.

#### Response Example
{
  "version": "0.8.0"
}
```

--------------------------------

### Expected Query Response Structure

Source: https://context7.com/oasysai/oasysdb/llms.txt

Illustrates the expected JSON response structure for a nearest neighbor query, including result IDs, metadata, and distances.

```json
# Expected response:
# {
#   "results": [
#     {
#       "id": "550e8400-e29b-41d4-a716-446655440000",
#       "metadata": {
#         "title": {"text": "Introduction to Machine Learning"},
#         "category": {"text": "AI"}
#       },
#       "distance": 0.125
#     },
#     {
#       "id": "660e8400-e29b-41d4-a716-446655440001",
#       "metadata": {
#         "title": {"text": "Deep Learning Fundamentals"},
#         "category": {"text": "AI"}
#       },
#       "distance": 0.342
#     }
#   ]
# }
```

--------------------------------

### Query Nearest Neighbors with OasysDB

Source: https://context7.com/oasysai/oasysdb/llms.txt

Defines the protobuf messages for querying nearest neighbors, including vector, k, filter, and query parameters.

```protobuf
// Proto definition
rpc Query(QueryRequest) returns (QueryResponse);

message QueryRequest {
    Vector vector = 1;
    int32 k = 2;
    string filter = 3;
    QueryParameters params = 4;
}

message QueryParameters {
    int32 probes = 1;  // Number of clusters to visit (default: 32)
    float radius = 2;   // Maximum distance threshold (default: infinity)
}

message QueryResponse {
    repeated QueryResult results = 1;
}

message QueryResult {
    string id = 1;
    map<string, Value> metadata = 2;
    float distance = 3;
}
```

--------------------------------

### Retrieve Records by ID

Source: https://context7.com/oasysai/oasysdb/llms.txt

Fetch stored vector data and metadata using the record's UUID.

```protobuf
// Proto definition
rpc Get(GetRequest) returns (GetResponse);

message GetRequest {
    string id = 1;
}

message GetResponse {
    Record record = 1;
}
```

```bash
# Retrieve a record by ID
grpcurl -plaintext -d '{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}' localhost:2505 database.Database/Get

# Expected response:
# {
#   "record": {
#     "vector": {
#       "data": [0.1, 0.2, 0.3, 0.4]
#     },
#     "metadata": {
#       "title": {"text": "Introduction to Machine Learning"},
#       "category": {"text": "AI"},
#       "year": {"number": 2024},
#       "published": {"boolean": true}
#     }
#   }
# }
```

--------------------------------

### POST database.Database/Query

Source: https://context7.com/oasysai/oasysdb/llms.txt

Search for the k nearest neighbors to a query vector with optional metadata filtering and query parameters.

```APIDOC
## POST database.Database/Query

### Description
Search for the k nearest neighbors to a query vector with optional metadata filtering and query parameters.

### Method
POST

### Endpoint
database.Database/Query

### Request Body
- **vector** (Vector) - Required - The query vector data.
- **k** (int32) - Required - Number of nearest neighbors to return.
- **filter** (string) - Optional - Metadata filter string.
- **params** (QueryParameters) - Optional - Custom query parameters.

### Response
#### Success Response (200)
- **results** (repeated QueryResult) - List of nearest neighbor results.

#### Response Example
{
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "metadata": {
        "title": {"text": "Introduction to Machine Learning"},
        "category": {"text": "AI"}
      },
      "distance": 0.125
    }
  ]
}
```

--------------------------------

### Insert Record

Source: https://context7.com/oasysai/oasysdb/llms.txt

Insert a new vector record with metadata into the database.

```APIDOC
## gRPC Insert

### Description
Insert a new vector record with metadata into the database. Returns the generated UUID for the record.

### Method
gRPC rpc

### Endpoint
database.Database/Insert

### Request Body
- **record** (Record) - The record object containing vector data and metadata.

### Request Example
{
  "record": {
    "vector": {
      "data": [0.1, 0.2, 0.3, 0.4]
    },
    "metadata": {
      "title": {"text": "Introduction to Machine Learning"},
      "category": {"text": "AI"},
      "year": {"number": 2024},
      "published": {"boolean": true}
    }
  }
}

### Response
#### Success Response (200)
- **id** (string) - The generated UUID for the inserted record.

#### Response Example
{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

--------------------------------

### Measure Recall Rate

Source: https://github.com/oasysai/oasysdb/blob/main/docs/changelog.md

Use this command to measure the recall rate of the collection search functionality. This is useful for evaluating search performance.

```sh
cargo run --example measure-recall
```

--------------------------------

### Configure Collection Distance Metric

Source: https://github.com/oasysai/oasysdb/blob/main/docs/changelog.md

Set the distance metric for a vector collection using the Config struct. Defaults to Euclidean if not specified.

```rust
let config = Config {
  ...
  distance: Distance::Cosine,
};
```

--------------------------------

### Delete Records

Source: https://context7.com/oasysai/oasysdb/llms.txt

Remove a record from the database permanently using its UUID.

```protobuf
// Proto definition
rpc Delete(DeleteRequest) returns (google.protobuf.Empty);

message DeleteRequest {
    string id = 1;
}
```

```bash
# Delete a record by ID
grpcurl -plaintext -d '{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}' localhost:2505 database.Database/Delete

# Returns empty response on success
```

--------------------------------

### Update Record Metadata

Source: https://context7.com/oasysai/oasysdb/llms.txt

Modify existing record metadata without altering the associated vector.

```protobuf
// Proto definition
rpc Update(UpdateRequest) returns (google.protobuf.Empty);

message UpdateRequest {
    string id = 1;
    map<string, Value> metadata = 2;
}
```

```bash
# Update metadata for an existing record
grpcurl -plaintext -d '{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {
    "title": {"text": "Advanced Machine Learning"},
    "category": {"text": "AI"},
    "year": {"number": 2024},
    "published": {"boolean": true},
    "views": {"number": 1500}
  }
}' localhost:2505 database.Database/Update

# Returns empty response on success
```

--------------------------------

### Enable 'gen' feature for EmbeddingModel

Source: https://github.com/oasysai/oasysdb/blob/main/docs/changelog.md

To use the EmbeddingModel trait and OpenAI's embedding models for generating vectors, enable the 'gen' feature in your Cargo.toml. This feature is optional.

```toml
[dependencies]
oasysdb = { version = "0.5.0", features = ["gen"] }
```

--------------------------------

### Set Relevancy Threshold for Search Results

Source: https://github.com/oasysai/oasysdb/blob/main/docs/changelog.md

Enable filtering of search results based on a relevancy threshold. This feature is disabled by default (-1.0) and can be enabled by setting the `relevancy` field in the Collection struct.

```rust
...
let mut collection = Collection::new(&config)?;
collection.relevancy = 3.0;
```

--------------------------------

### Update Record Metadata

Source: https://context7.com/oasysai/oasysdb/llms.txt

Update the metadata of an existing record.

```APIDOC
## gRPC Update

### Description
Update the metadata of an existing record without modifying the vector data.

### Method
gRPC rpc

### Endpoint
database.Database/Update

### Request Body
- **id** (string) - The UUID of the record to update.
- **metadata** (map) - The new metadata to apply to the record.

### Request Example
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {
    "title": {"text": "Advanced Machine Learning"},
    "category": {"text": "AI"},
    "year": {"number": 2024},
    "published": {"boolean": true},
    "views": {"number": 1500}
  }
}
```

--------------------------------

### Delete Record

Source: https://context7.com/oasysai/oasysdb/llms.txt

Remove a record from the database by its UUID.

```APIDOC
## gRPC Delete

### Description
Remove a record from the database by its UUID.

### Method
gRPC rpc

### Endpoint
database.Database/Delete

### Request Body
- **id** (string) - The UUID of the record to delete.

### Request Example
{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.