### Install Build5Nines.SharpVector NuGet Packages

Source: https://context7.com/build5nines/sharpvector/llms.txt

Install the core package for local embeddings or integration packages for OpenAI/Azure OpenAI and Ollama embeddings.

```bash
# .NET CLI
dotnet add package Build5Nines.SharpVector

# OpenAI / Azure OpenAI embeddings (includes core package)
dotnet add package Build5Nines.SharpVector.OpenAI

# Ollama embeddings (includes core package)
dotnet add package Build5Nines.SharpVector.Ollama
```

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

### Install SharpVector using Package Manager

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/index.md

Use the Nuget Package Manager console to install the Build5Nines.SharpVector package.

```powershell
Nuget\Install-Package Build5Nines.SharpVector
```

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

### Install SharpVector OpenAI Package

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/embeddings/openai/index.md

Install the necessary NuGet package for OpenAI integration using either .NET CLI or Package Manager.

```bash
dotnet add package Build5Nines.SharpVector.OpenAI
```

```powershell
Nuget\Install-Package Build5Nines.SharpVector.OpenAI
```

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

### Add Ollama Package via .NET CLI

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/embeddings/ollama/index.md

Install the Build5Nines.SharpVector.Ollama NuGet package using the .NET CLI.

```bash
dotnet add package Build5Nines.SharpVector.Ollama
```

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

### Basic In-Memory Vector Database Example

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/index.md

Demonstrates creating an in-memory vector database, adding text data with metadata, and performing a semantic search. The metadata type is generic and can be customized. Supports local text vector generation by default.

```csharp
using Build5Nines.SharpVector;

// Create a Vector Database with metadata of type string
var vdb = new BasicMemoryVectorDatabase();
// The Metadata is declared using generics, so you can store whatever data you need there.

// Load Vector Database with some sample text data
// Text is the movie description, and Metadata is the movie title with release year in this example
vdb.AddText("Iron Man (2008) is a Marvel Studios action, adventure, and sci-fi movie about Tony Stark (Robert Downey Jr.), a billionaire inventor and weapons developer who is kidnapped by terrorists and forced to build a weapon. Instead, Tony uses his ingenuity to build a high-tech suit of armor and escape, becoming the superhero Iron Man. He then returns to the United States to refine the suit and use it to fight crime and terrorism.", "Iron Man (2008)");
vdb.AddText("The Lion King is a 1994 Disney animated film about a young lion cub named Simba who is the heir to the throne of an African savanna.", "The Lion King (1994)");
vdb.AddText("Aladdin is a 2019 live-action Disney adaptation of the 1992 animated classic of the same name about a street urchin who finds a magic lamp and uses a genie's wishes to become a prince so he can marry Princess Jasmine.", "Alladin (2019)");
vdb.AddText("The Little Mermaid is a 2023 live-action adaptation of Disney's 1989 animated film of the same name. The movie is about Ariel, the youngest of King Triton's daughters, who is fascinated by the human world and falls in love with Prince Eric.", "The Little Mermaid");
vdb.AddText("Frozen is a 2013 Disney movie about a fearless optimist named Anna who sets off on a journey to find her sister Elsa, whose icy powers have trapped their kingdom in eternal winter.", "Frozen (2013)");

// Perform a Vector Search
var result = vdb.Search(newPrompt, pageCount: 5); // return the first 5 results

if (!result.IsEmpty)
{
    Console.WriteLine("Similar Text Found:");
    foreach (var item in result.Texts)
    {
        Console.WriteLine(item.Metadata);
        Console.WriteLine(item.Text);
    }
} else {
    Console.WriteLine("No results found.");
}
```

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

### Setup OpenAI Embedding Client

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/embeddings/openai/index.md

Initialize an OpenAI embedding client using your API key and the desired model name.

```csharp
using OpenAI;

var openAIKey = "your-api-key";
var modelName = "text-embedding-ada-002";

var openAIClient = new OpenAIClient(openAIKey);
var embeddingClient = openAIClient.GetEmbeddingClient(modelName);
```

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

### Add Ollama Package via Package Manager

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/embeddings/ollama/index.md

Install the Build5Nines.SharpVector.Ollama NuGet package using the Package Manager console.

```powershell
Nuget\Install-Package Build5Nines.SharpVector.Ollama
```

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

### Instantiate BasicMemoryVectorDatabase

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/text-chunking/index.md

Create an instance of the vector database that will store the chunked text. This example uses BasicMemoryVectorDatabase with default TId and TMetadata types.

```csharp
using Build5Nines.SharpVector;

var vdb = new BasicMemoryVectorDatabase();
```

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

### Setup Azure OpenAI Embedding Client

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/embeddings/openai/index.md

Initialize an Azure OpenAI embedding client using your resource URI, API key, and model name.

```csharp
using Azure;
using Azure.AI.OpenAI;

var openAIUri = new Uri("https://your-resource-name.openai.azure.com/");
var openAIKey = "your-api-key";
var modelName = "text-embedding-ada-002";

var openAIClient = new AzureOpenAIClient(openAIUri, new AzureKeyCredential(openAIKey));
var embeddingClient = openAIClient.GetEmbeddingClient(modelName);
```

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

### BasicOpenAIMemoryVectorDatabase with Azure OpenAI

Source: https://context7.com/build5nines/sharpvector/llms.txt

Initializes a vector database using Azure OpenAI embeddings. Requires Azure OpenAI setup and an API key. Adds text documents and performs semantic search with a threshold and paging.

```csharp
using Azure;
using Azure.AI.OpenAI;
using Build5Nines.SharpVector.OpenAI;

// Azure OpenAI setup
var openAIClient = new AzureOpenAIClient(
    new Uri("https://your-resource.openai.azure.com/"),
    new AzureKeyCredential(Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY")!)
);
var embeddingClient = openAIClient.GetEmbeddingClient("text-embedding-ada-002");

// Initialize SharpVector with the OpenAI embedding client
var vdb = new BasicOpenAIMemoryVectorDatabase(embeddingClient);

// Add documents (calls OpenAI Embeddings API to vectorize)
await vdb.AddTextAsync("SharpVector integrates with Azure OpenAI for high-quality embeddings.", "sharpvector-azure");
await vdb.AddTextAsync("Cosine similarity measures the angle between two vectors in high-dimensional space.", "cosine-sim");

// Semantic search with threshold and paging
var results = await vdb.SearchAsync(
    "embedding models for text similarity",
    threshold: 0.75f,
    pageIndex: 0,
    pageCount: 5
);

foreach (var item in results.Texts)
{
    Console.WriteLine($"[{item.Similarity:F4}] {item.Metadata}");
}

// OpenAI embeddings also support generic metadata
var typedVdb = new OpenAIMemoryVectorDatabase<ArticleMetadata>(embeddingClient);
```

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

### Manage Text Items (Get, Update, Delete) in Vector Database

Source: https://context7.com/build5nines/sharpvector/llms.txt

Demonstrates how to retrieve, update, and delete text items by their unique integer ID, and enumerate all stored items.

```csharp
using Build5Nines.SharpVector;

var vdb = new BasicMemoryVectorDatabase();

// AddText returns the assigned ID
int id = vdb.AddText("Original text about cloud computing.", "doc-001");

// Get by ID
var item = vdb.GetText(id);
Console.WriteLine($"Retrieved: {item?.Text}");

// Update the text (re-vectorizes automatically)
vdb.UpdateText(id, "Updated text about cloud computing platforms.");

// Update only metadata (no re-vectorization)
vdb.UpdateTextMetadata(id, "doc-001-updated");

// Update both text and metadata
vdb.UpdateTextAndMetadata(id, "Final text about hybrid cloud.", "doc-001-final");

// Enumerate all items
foreach (var entry in vdb)
{
    Console.WriteLine($"ID={entry.Id} | Meta={entry.Metadata} | Text={entry.Text}");
}

// Delete by ID
vdb.DeleteText(id);
Console.WriteLine($"Total items after delete: {vdb.Count()}");
```

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

### Deserialize BasicMemoryVectorDatabase from Stream

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/persistence/index.md

Load a BasicMemoryVectorDatabase from a binary stream asynchronously or synchronously. Ensure the stream position is at the start before deserializing. Available in v2.0.2 and later.

```csharp
// Be sure Stream position is at the start
stream.Position = 0;

// deserialize from JSON stream
vdb.DeserializeFromBinaryStream(stream);

// -- or ---

// deserialize asynchronously from JSON stream
await vdb.DeserializeFromBinaryStreamAsync(stream);
```

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

### Customize Chunk Metadata with JSON

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/text-chunking/index.md

Use the `RetrieveMetadata` delegate to generate custom metadata for each text chunk. This example stores the document filename and indexing timestamp as a JSON string.

```csharp
string filename = "document.txt";
string document = LoadDocumentText(filename);
loader.AddDocument(document, new TextChunkingOptions<string>
{
    Method = TextChunkingMethod.Paragraph,
    RetrieveMetadata = (chunk) => {
        var json = JsonSerializer.Serialize(new {
            documentFileName = filename,
            timeIndexed = DataTime.UtcNow.ToString("o")
        });
        return json;
    }
});
```

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

### Get Text By Id

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/data-management/index.md

Retrieves a specific text item from the database using its unique ID.

```APIDOC
## Get Text By Id

### Description
Retrieves a specific text item from the vector database directly using its unique identifier.

### Method
```csharp
vdb.GetText(id);
```
```

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

### Get Text Item by ID

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/data-management/index.md

Retrieve a specific text item directly from the vector database using its unique ID with the `.GetText` method.

```csharp
vdb.GetText(id);
```

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

### Add Text Item and Get ID

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/data-management/index.md

When adding an individual text item to the vector database, the ID value will be returned. Use the asynchronous version for non-blocking operations.

```csharp
var id = vdb.AddText(txt, metadata);
```

```csharp
var id = await vdb.AddTextAsync(txt, metadata);
```

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

### Load and Search Vector Database in C#

Source: https://github.com/build5nines/sharpvector/blob/main/src/Build5Nines.SharpVector/docs/README.md

Demonstrates how to create a `BasicMemoryVectorDatabase`, add text data with metadata, and perform a similarity search. The metadata can be of any type, specified using generics.

```csharp
    // Create a Vector Database with metadata of type string
    var vdb = new BasicMemoryVectorDatabase();
    // The Metadata is declared using generics, so you can store whatever data you need there.

    // Load Vector Database with some sample text data
    // Text is the movie description, and Metadata is the movie title with release year in this example
    vdb.AddText("Iron Man (2008) is a Marvel Studios action, adventure, and sci-fi movie about Tony Stark (Robert Downey Jr.), a billionaire inventor and weapons developer who is kidnapped by terrorists and forced to build a weapon. Instead, Tony uses his ingenuity to build a high-tech suit of armor and escape, becoming the superhero Iron Man. He then returns to the United States to refine the suit and use it to fight crime and terrorism.", "Iron Man (2008)");
    vdb.AddText("The Lion King is a 1994 Disney animated film about a young lion cub named Simba who is the heir to the throne of an African savanna.", "The Lion King (1994)");
    vdb.AddText("Aladdin is a 2019 live-action Disney adaptation of the 1992 animated classic of the same name about a street urchin who finds a magic lamp and uses a genie's wishes to become a prince so he can marry Princess Jasmine.", "Alladin (2019)");
    vdb.AddText("The Little Mermaid is a 2023 live-action adaptation of Disney's 1989 animated film of the same name. The movie is about Ariel, the youngest of King Triton's daughters, who is fascinated by the human world and falls in love with Prince Eric.", "The Little Mermaid");
    vdb.AddText("Frozen is a 2013 Disney movie about a fearless optimist named Anna who sets off on a journey to find her sister Elsa, whose icy powers have trapped their kingdom in eternal winter.", "Frozen (2013)");

    // Perform a Vector Search
    var result = vdb.Search(newPrompt, pageCount: 5); // return the first 5 results

    if (result.HasResults)
    {
        Console.WriteLine("Similar Text Found:");
        foreach (var item in result.Texts)
        {
            Console.WriteLine(item.Metadata);
            Console.WriteLine(item.Text);
        }
    }
```

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

### Basic Usage of Build5Nines.SharpVector

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/index.md

Demonstrates how to create an in-memory vector database, add text with metadata, and perform a semantic search. Ensure you have the necessary using statements and a method to load texts.

```csharp
using Build5Nines.SharpVector;

// Create new vector database
var vdb = new BasicMemoryVectorDatabase();

// Get text to vectorize
string[] texts = LoadMultipleTexts();
// Define metadata to store alongside the text vectors
var metadata = "custom metadata";

// Add multiple texts with metadata to vector database
foreach(var t in texts)
{
    // vectorize the text
    vdb.AddText(t, metadata);
}

// Perform semantic search using Cosine Similarity search on the text vectors in the database
var result = vdb.Search("Build5Nines.SharpVector is awesome!");

// Loop through search results
foreach(var item in results.Texts)
{
    var itemText = item.Text;
    var itemMetadata = item.Metadata;

    // do something with the semantic search results
}
```

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

### Use BasicDiskVectorDatabase

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/persistence/index.md

Initialize and use BasicDiskVectorDatabase, specifying a folder path for automatic persistence. Add text and perform searches.

```csharp
// specify the folder where to persist the database data on disk
var vdb = new BasicDiskVectorDatabase("C:/data/content-db");
foreach (var doc in documents)
{
    vdb.AddText(doc.Id, doc.Text);
}

var results = vdb.Search("some text");

```

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

### Initialize BasicOpenAIMemoryVectorDatabase

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/embeddings/openai/index.md

Initialize the in-memory vector database using the configured OpenAI embedding client.

```csharp
using Build5Nines.SharpVector.OpenAI;

var vectorDatabase = new BasicOpenAIMemoryVectorDatabase(embeddingClient);
```

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

### BasicDiskVectorDatabase Initialization

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/persistence/index.md

Initialize `BasicDiskVectorDatabase` to automatically persist the vector and vocabulary stores to disk in the specified folder.

```APIDOC
## BasicDiskVectorDatabase Initialization

### Description
Initialize a `BasicDiskVectorDatabase` which automatically persists data to disk.

### Method
`new BasicDiskVectorDatabase(string folderPath)`

### Parameters
- **folderPath** (string) - Required - The folder path where the database data will be persisted.

### Request Example
```csharp
// specify the folder where to persist the database data on disk
var vdb = new BasicDiskVectorDatabase("C:/data/content-db");

// Example usage:
foreach (var doc in documents)
{
    vdb.AddText(doc.Id, doc.Text);
}

var results = vdb.Search("some text");
```

### Tips
- Prefer absolute paths for the storage folder in production services.
- Place the folder on fast storage (SSD) for best indexing/query performance.
- Avoid sharing the same folder across multiple processes concurrently.
- Back up the folder regularly to preserve your vector store and vocabulary.
```

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

### BasicMemoryVectorDatabase - Create and Query

Source: https://context7.com/build5nines/sharpvector/llms.txt

Demonstrates how to create an in-memory vector database using `BasicMemoryVectorDatabase`, add text documents with metadata, and perform semantic searches.

```APIDOC
## BasicMemoryVectorDatabase — Create and Query an In-Memory Vector Database

`BasicMemoryVectorDatabase` is the primary entry point for local-embedding use cases. It stores text and string metadata entirely in memory using the built-in Bag-of-Words vectorizer with cosine similarity, requires zero configuration, and exposes the full SharpVector API surface.

```csharp
using Build5Nines.SharpVector;

// Create the in-memory vector database (string metadata)
var vdb = new BasicMemoryVectorDatabase();

// Add text documents with associated string metadata
vdb.AddText("Iron Man (2008) is a Marvel Studios action, adventure, and sci-fi movie about Tony Stark, a billionaire inventor who builds a high-tech suit of armor.", "Iron Man (2008)");
vdb.AddText("The Lion King is a 1994 Disney animated film about a young lion cub named Simba who is heir to the throne of an African savanna.", "The Lion King (1994)");
vdb.AddText("Frozen is a 2013 Disney movie about Anna who sets off on a journey to find her sister Elsa, whose icy powers have trapped their kingdom in eternal winter.", "Frozen (2013)");
vdb.AddText("Aladdin is a 2019 live-action Disney adaptation about a street urchin who finds a magic lamp and uses a genie's wishes to become a prince.", "Aladdin (2019)");

// Perform semantic search — returns results ranked by cosine similarity
var results = vdb.Search("superhero with high-tech armor", pageCount: 3);

if (!results.IsEmpty)
{
    foreach (var item in results.Texts)
    {
        Console.WriteLine($"Title: {item.Metadata}");
        Console.WriteLine($"Similarity: {item.Similarity}");
        Console.WriteLine($"Text: {item.Text}");
        Console.WriteLine();
    }
}
// Output:
// Title: Iron Man (2008)
// Similarity: 0.312...
// Text: Iron Man (2008) is a Marvel Studios action...
```
```

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

### Load from File

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/persistence/index.md

Load a previously saved vector database from disk using `LoadFromFile` or `LoadFromFileAsync` methods.

```APIDOC
## Load from File

### Description
Load a previously saved vector database from disk.

### Method
`LoadFromFile` or `LoadFromFileAsync`

### Parameters
- **filePath** (string) - Required - The path to the file from which the vector database will be loaded.

### Request Example
```csharp
var vdb = new BasicMemoryVectorDatabase();
var filePath = "vectordata.b59vdb";

// load vector database from file
vdb.LoadFromFile(filePath);

// -- or --

// load vector database from file asynchronously
await vdb.LoadFromFileAsync(filePath);
```
```

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

### Initialize Vector Database with Ollama

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/embeddings/ollama/index.md

Initialize the SharpVector vector database using a specified Ollama embedding model. Supports connecting to a local or custom Ollama endpoint.

```csharp
using Build5Nines.SharpVector.Ollama;

var modelName = "nomic-embed-text";

// For connecting to Locally running ('localhost') Ollama
var vectorDatabase = new BasicOllamaMemoryVectorDatabase(modelName)

// For connecting to a different Ollama endpoint URL
var ollamaEndpoint = "http:/localhost:11434/api/embeddings";
var vactorDatabase = new BasicOllamaMemoryVectorDatabase(ollamaEndpoint, modelName);
```

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

### Load BasicMemoryVectorDatabase from File

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/persistence/index.md

Load a previously saved BasicMemoryVectorDatabase from a file asynchronously or synchronously.

```csharp
var vdb = new BasicMemoryVectorDatabase();

var filePath = "vectordata.b59vdb";

// load vector database from file
vdb.LoadFromFile(filePath);

// -- or --

// load vector database from file asynchronously
await vdb.LoadFromFileAsync(filePath);
```

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

### BasicOllamaMemoryVectorDatabase for Local Embeddings

Source: https://context7.com/build5nines/sharpvector/llms.txt

Initializes a vector database using locally hosted Ollama embeddings. Connects to the default Ollama endpoint or a custom one. Adds text documents and performs semantic search.

```csharp
using Build5Nines.SharpVector.Ollama;

// Connect to locally running Ollama (default endpoint: http://localhost:11434/api/embeddings)
var vdb = new BasicOllamaMemoryVectorDatabase("nomic-embed-text");

// Or specify a custom Ollama endpoint
var vdbCustom = new BasicOllamaMemoryVectorDatabase(
    "http://ollama-server:11434/api/embeddings",
    "nomic-embed-text"
);

// Add documents (calls Ollama API to vectorize)
await vdb.AddTextAsync("Ollama runs large language models locally on your machine.", "ollama-info");
await vdb.AddTextAsync("nomic-embed-text is an open-source embedding model optimized for retrieval.", "nomic-info");

// Search
var results = await vdb.SearchAsync(
    "local AI model inference",
    threshold: 0.001f,
    pageCount: 5
);

foreach (var item in results.Texts)
{
    Console.WriteLine($"[{item.Similarity:F4}] {item.Metadata}: {item.Text}");
}

// Generic metadata also supported
var typedVdb = new OllamaMemoryVectorDatabase<ArticleMetadata>("nomic-embed-text");
```

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

### Semantic Search with Paging (Sync)

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/search/index.md

Implement paging for semantic search results using `pageIndex` and `pageCount`. Paging is applied after similarity search and metadata filtering.

```csharp
var vdb = new BasicMemoryVectorDatabase();

// load text and metadata into database

var query = "some text to search";
var results = vdb.Search(
    query,
    pageIndex: 0, // return first page of results (default: 0)
    pageCount: 6  // limit length of this page of results (default: unlimited)
);
```

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

### Instantiate TextDataLoader

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/text-chunking/index.md

Initialize the TextDataLoader with a specific vector database instance. This prepares the loader for processing documents with specified ID and Metadata types.

```csharp
var loader = new TextDataLoader<int, string>(vdb);
```

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

### RAG Pattern with SharpVector and Local Documents

Source: https://context7.com/build5nines/sharpvector/llms.txt

Implements a Retrieval Augmented Generation (RAG) pattern. It builds a vector database from local markdown files, retrieves relevant chunks based on a user query, and constructs a prompt for an LLM.

```csharp
using Build5Nines.SharpVector;
using Build5Nines.SharpVector.Data;

// 1. Build the vector database from a directory of markdown / text files
var vdb = new BasicMemoryVectorDatabase();
var loader = new TextDataLoader<int, string>(vdb);

var files = Directory.GetFiles("C:/docs", "*.md", SearchOption.AllDirectories);
await Parallel.ForEachAsync(files, async (file, _) =>
{
    var text = await File.ReadAllTextAsync(file);
    await loader.AddDocumentAsync(text, new TextChunkingOptions<string>
    {
        Method = TextChunkingMethod.Paragraph,
        RetrieveMetadata = (chunk) => file
    });
});

Console.WriteLine($"Indexed {files.Length} documents.");

// 2. At query time, retrieve the most relevant chunks
string userQuery = "How do I configure a Terraform remote backend?";

var ragResults = await vdb.SearchAsync(userQuery, pageCount: 8, threshold: 0.3f);

// 3. Build RAG context string from top results
var ragContext = string.Join("\n\n", ragResults.Texts.Select(r => r.Text));

// 4. Inject context into the LLM prompt
var fullPrompt = $"""
    <|system|>You are a helpful assistant. Use the context below to answer the question.<|end|>
    <|user|>
    Context:
    {ragContext}

    Question: {userQuery}<|end|>
    <|assistant|>
    """;

// 5. Pass fullPrompt to your LLM (ONNX, Azure OpenAI, Ollama, etc.)
Console.WriteLine("Prompt ready for LLM:");
Console.WriteLine(fullPrompt[..Math.Min(500, fullPrompt.Length)] + "...");
```

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

### Add Build5Nines.SharpVector Nuget Package

Source: https://github.com/build5nines/sharpvector/blob/main/README.md

Use the dotnet CLI to add the Build5Nines.SharpVector package to your .NET project. This package provides the core functionality for the in-memory vector database.

```bash
dotnet add package Build5Nines.SharpVector
```

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

### Perform Basic Semantic Search

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/search/index.md

Use the `.Search` or `.SearchAsync` methods to find text items matching a query. These methods are available on `BasicMemoryVectorDatabase` and `MemoryVectorDatabase<>` classes.

```csharp
var query = "some text to search";
var results = vdb.Search(query);
```

```csharp
var query = "some text to search";
var results = await vdb.SearchAsync(query);
```

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

### Use BasicDiskVectorDatabase for Automatic Disk Persistence

Source: https://context7.com/build5nines/sharpvector/llms.txt

Employ BasicDiskVectorDatabase for automatic, background persistence of the vector store and vocabulary to a specified folder. Survives process restarts without explicit save calls.

```csharp
using Build5Nines.SharpVector;

// Specify the folder where the database files are stored
var vdb = new BasicDiskVectorDatabase("C:/data/my-vector-db");

vdb.AddText("HashiCorp Terraform enables infrastructure as code.", "terraform");
vdb.AddText("Ansible automates IT infrastructure provisioning.", "ansible");
vdb.AddText("Pulumi lets you define infrastructure using real programming languages.", "pulumi");

var results = vdb.Search("infrastructure automation tools", pageCount: 3);
foreach (var item in results.Texts)
{
    Console.WriteLine($"[{item.Similarity:F4}] {item.Metadata}: {item.Text}");
}
// The data in C:/data/my-vector-db is persisted automatically.
// On next startup, create the same BasicDiskVectorDatabase pointing to the same folder
// and existing data is loaded transparently.
```

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

### Store and Retrieve JSON Metadata

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/metadata/index.md

Demonstrates storing JSON-serialized data as metadata with BasicMemoryVectorDatabase and deserializing it upon retrieval. Ensure System.Text.Json is imported.

```csharp
// create vector database
var vdb = new BasicMemoryVectorDatabase();

// some text to store in the vector database
var text = "some text value";
// serialize an object to json to store as metadata
var json = JsonSerializer.Serialize(new MyMetadata{
    Url = "https://build5nines.com",
    Author = "Chris Pietschmann"
});

// Add text with metadata to vector database
vdb.AddText(text, json);

// perform semantic search
var results = vdb.Search("something to search", pageCount: 5);

// Loop through search results
foreach(var item in results.Texts) {
    var text = item.Text;
    var json = item.Metadata;
    var metadata = JsonSerializer.Deserialize<MyMetadata>(json);

    // do something with results and metadata
}
```

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

### Store and Retrieve String Metadata

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/metadata/index.md

Shows how to store a simple string value as metadata with BasicMemoryVectorDatabase and access it directly from search results.

```csharp
// create vector database
var vdb = new BasicMemoryVectorDatabase();

// some text to store in the vector database
var text = "some text value";
// some metadata to store
var metadata = "https://build5nines.com";

// Add text with metadata to vector database
vdb.AddText(text, metadata);

// perform semantic search
var results = vdb.Search("something to search", pageCount: 5);

// Loop through search results
foreach(var item in results.Texts) {
    var text = item.Text;
    var metadata = item.Metadata;

    // do something with results and metadata
}
```

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

### Create and Query BasicMemoryVectorDatabase

Source: https://context7.com/build5nines/sharpvector/llms.txt

Use BasicMemoryVectorDatabase for in-memory vector storage with the built-in Bag-of-Words vectorizer and cosine similarity. Add text documents with string metadata and perform semantic searches.

```csharp
using Build5Nines.SharpVector;

// Create the in-memory vector database (string metadata)
var vdb = new BasicMemoryVectorDatabase();

// Add text documents with associated string metadata
vdb.AddText("Iron Man (2008) is a Marvel Studios action, adventure, and sci-fi movie about Tony Stark, a billionaire inventor who builds a high-tech suit of armor.", "Iron Man (2008)");
vdb.AddText("The Lion King is a 1994 Disney animated film about a young lion cub named Simba who is heir to the throne of an African savanna.", "The Lion King (1994)");
vdb.AddText("Frozen is a 2013 Disney movie about Anna who sets off on a journey to find her sister Elsa, whose icy powers have trapped their kingdom in eternal winter.", "Frozen (2013)");
vdb.AddText("Aladdin is a 2019 live-action Disney adaptation about a street urchin who finds a magic lamp and uses a genie's wishes to become a prince.", "Aladdin (2019)");

// Perform semantic search — returns results ranked by cosine similarity
var results = vdb.Search("superhero with high-tech armor", pageCount: 3);

if (!results.IsEmpty)
{
    foreach (var item in results.Texts)
    {
        Console.WriteLine($"Title: {item.Metadata}");
        Console.WriteLine($"Similarity: {item.Similarity}");
        Console.WriteLine($"Text: {item.Text}");
        Console.WriteLine();
    }
}
// Output:
// Title: Iron Man (2008)
// Similarity: 0.312...
// Text: Iron Man (2008) is a Marvel Studios action...
```

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

### Save BasicMemoryVectorDatabase to File

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/persistence/index.md

Persist a BasicMemoryVectorDatabase to a file asynchronously or synchronously. The file format is ZIP, and the extension is arbitrary.

```csharp
var vdb = new BasicMemoryVectorDatabase();

var filePath = "vectordata.b59vdb";

// persist vector database to file asynchronously
await vdb.SaveToFileAsync(filePath);

// -- or --

// persist vector database to file
vdb.SaveToFile(filePath);
```

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

### Add Text Items to the Database (Sync and Async)

Source: https://context7.com/build5nines/sharpvector/llms.txt

Add text documents and their metadata to the vector database using either synchronous or asynchronous methods. The text is automatically vectorized, and a unique ID is returned for each item.

```csharp
using Build5Nines.SharpVector;

var vdb = new BasicMemoryVectorDatabase();

// Sync — returns assigned ID
int id1 = vdb.AddText("The quick brown fox jumps over the lazy dog.", "proverb-001");

// Async — returns assigned ID
int id2 = await vdb.AddTextAsync("To be or not to be, that is the question.", "shakespeare-hamlet");

Console.WriteLine($"Stored with IDs: {id1}, {id2}");
```

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

### Save to File

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/persistence/index.md

Persist your vector database to a file using `SaveToFile` or `SaveToFileAsync` methods. The underlying format is ZIP, and the file extension is arbitrary.

```APIDOC
## Save to File

### Description
Persist your vector database to a file.

### Method
`SaveToFile` or `SaveToFileAsync`

### Parameters
- **filePath** (string) - Required - The path to the file where the vector database will be saved.

### Request Example
```csharp
var vdb = new BasicMemoryVectorDatabase();
var filePath = "vectordata.b59vdb";

// persist vector database to file asynchronously
await vdb.SaveToFileAsync(filePath);

// -- or --

// persist vector database to file
vdb.SaveToFile(filePath);
```

### Notes
The file extension is arbitrary; the library reads the binary content, which is in ZIP format.
```

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

### Persist and Load Vector Databases with File and Stream Operations

Source: https://context7.com/build5nines/sharpvector/llms.txt

Serialize and deserialize SharpVector databases to disk or streams for caching or distribution. Supports both asynchronous and synchronous operations.

```csharp
using Build5Nines.SharpVector;

var vdb = new BasicMemoryVectorDatabase();
vdb.AddText("Kubernetes orchestrates containerized workloads.", "k8s");
vdb.AddText("Docker packages applications into portable containers.", "docker");

string filePath = "vectordata.b59vdb";

// Save to file (async or sync)
await vdb.SaveToFileAsync(filePath);
// vdb.SaveToFile(filePath);

// Load into a new instance
var vdb2 = new BasicMemoryVectorDatabase();
await vdb2.LoadFromFileAsync(filePath);
// vdb2.LoadFromFile(filePath);

// Alternatively, use streams (e.g., for Azure Blob Storage upload/download)
var memStream = new MemoryStream();
await vdb.SerializeToBinaryStreamAsync(memStream);

memStream.Position = 0;
var vdb3 = new BasicMemoryVectorDatabase();
await vdb3.DeserializeFromBinaryStreamAsync(memStream);

var result = vdb3.Search("container orchestration", pageCount: 2);
Console.WriteLine(result.Texts.First().Metadata); // k8s
```

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

### Semantic Search with Paging (Async)

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/search/index.md

Perform an asynchronous semantic search with paging. The `pageIndex` and `pageCount` parameters control which subset of results is returned, applied after filtering.

```csharp
var vdb = new MemoryVectorDatabase<Person>();

// load text and metadata into database

var query = "some text to search";
var results = vdb.SearchAsync(
    query,
    pageIndex: 0, // return first page of results (default: 0)
    pageCount: 6  // limit length of this page of results (default: unlimited)
);
```

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

### Semantic Search with Paging

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/search/index.md

Perform a semantic search and paginate the results.

```APIDOC
## Semantic Search with Paging

### Description
Performs a semantic search and applies paging to the results after similarity search and filtering. Uses `pageIndex` and `pageCount` parameters.

### Method
C#

### Code
```csharp
// Sync example
var results = vdb.Search(
    query,
    pageIndex: 0, // return first page of results (default: 0)
    pageCount: 6  // limit length of this page of results (default: unlimited)
);

// Async example
var results = await vdb.SearchAsync(
    query,
    pageIndex: 0, // return first page of results (default: 0)
    pageCount: 6  // limit length of this page of results (default: unlimited)
);
```
```

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

### Add Text with Metadata

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/metadata/index.md

Use the AddText and AddTextAsync methods to store text along with associated metadata in the vector database.

```csharp
vdb.AddText(text, metadata);

await vdb.AddText(text, metadata);
```

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

### Read from Stream

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/persistence/index.md

Deserialize the vector database from a stream using `DeserializeFromBinaryStream` and `DeserializeFromBinaryStreamAsync` methods.

```APIDOC
## Read from Stream

### Description
Load your vector database from a stream.

### Method
`DeserializeFromBinaryStream` or `DeserializeFromBinaryStreamAsync`

### Parameters
- **stream** (Stream) - Required - The stream from which the vector database will be deserialized. Ensure the stream position is at the start.

### Request Example
```csharp
// Be sure Stream position is at the start
stream.Position = 0;

// deserialize from JSON stream
vdb.DeserializeFromBinaryStream(stream);

// -- or ---

// deserialize asynchronously from JSON stream
await vdb.DeserializeFromBinaryStreamAsync(stream);
```

### Notes
Available in v2.0.2 and later.
```

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

### Serialize BasicMemoryVectorDatabase to Stream

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/persistence/index.md

Persist a BasicMemoryVectorDatabase to a binary stream (e.g., MemoryStream) asynchronously or synchronously. Available in v2.0.2 and later.

```csharp
var vdb = new BasicMemoryVectorDatabase();

var stream = new MemoryStream();

// serialize to JSON stream
vdb.SerializeToBinaryStream(stream);

// -- or --

// serialize asynchronously to JSON stream
await vdb.SerializeToBinaryStreamAsync(stream);
```

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

### Basic Semantic Search

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/search/index.md

Perform a basic semantic search using the .Search or .SearchAsync methods.

```APIDOC
## Basic Semantic Search

### Description
Performs a semantic search on the vector database to find matching text items for a given query.

### Method
C#

### Code
```csharp
var query = "some text to search";
var results = vdb.Search(query);
// or for async
var results = await vdb.SearchAsync(query);
```
```

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

### Chunk Text by Sentence

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/text-chunking/index.md

Divides a document into individual sentences using punctuation as boundaries. Each sentence chunk includes its length in the metadata.

```csharp
string document = LoadDocumentText();
loader.AddDocument(document, new TextChunkingOptions<string>
{
    Method = TextChunkingMethod.Sentence,
    RetrieveMetadata = (chunk) => {
        return "{ \"chunkSize\": \"" + chunk.Length + "\" }";
    }
});
```

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

### Chunk Text by Paragraph

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/text-chunking/index.md

Splits a document into chunks based on logical paragraphs. Metadata is generated for each chunk, including its size.

```csharp
string document = LoadDocumentText();
loader.AddDocument(document, new TextChunkingOptions<string>
{
    Method = TextChunkingMethod.Paragraph,
    RetrieveMetadata = (chunk) => {
        return "{ \"chunkSize\": \"" + chunk.Length + "\" }";
    }
});
```

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

### Write to Stream

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/persistence/index.md

Serialize the vector database to a stream using `SerializeToBinaryStream` or `SerializeToBinaryStreamAsync` methods. This is useful for `MemoryStream` or other stream-based persistence.

```APIDOC
## Write to Stream

### Description
Persist your vector database to a stream.

### Method
`SerializeToBinaryStream` or `SerializeToBinaryStreamAsync`

### Parameters
- **stream** (Stream) - Required - The stream to which the vector database will be serialized.

### Request Example
```csharp
var vdb = new BasicMemoryVectorDatabase();
var stream = new MemoryStream();

// serialize to JSON stream
vdb.SerializeToBinaryStream(stream);

// -- or --

// serialize asynchronously to JSON stream
await vdb.SerializeToBinaryStreamAsync(stream);
```

### Notes
Available in v2.0.2 and later.
```

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

### Semantic Search with Metadata Filtering (Async)

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/search/index.md

Perform an asynchronous semantic search with metadata filtering. The filter is an asynchronous boolean evaluation of the text item's metadata, which can be useful for complex checks.

```csharp
var vdb = new MemoryVectorDatabase<Person>();

// load text and metadata into database

var query = "some text to search";
var results = vdb.SearchAsync(
    query,
    filter: async (metadata) => {
        // perform some operation to check metadata
        // return true or false
        return metadata.LastName == "Pietschmann";
    }
);
```

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

### Add Text

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/data-management/index.md

Adds an individual text item to the vector database and returns its unique ID.

```APIDOC
## Add Text

### Description
Adds an individual text item to the vector database. The unique ID assigned to the text item is returned upon successful addition.

### Method
```csharp
var id = vdb.AddText(txt, metadata);
var id = await vdb.AddTextAsync(txt, metadata);
```
```

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

### Perform Semantic Search with SharpVector

Source: https://context7.com/build5nines/sharpvector/llms.txt

Searches the database for text items semantically similar to the query string. Supports an optional similarity threshold, paging, and a pre-filter delegate on metadata.

```csharp
using Build5Nines.SharpVector;

var vdb = new BasicMemoryVectorDatabase();
vdb.AddText("Azure is Microsoft's cloud computing platform.", "azure-docs");
vdb.AddText("AWS is Amazon's cloud computing platform.", "aws-docs");
vdb.AddText("Chocolate cake recipe with frosting.", "recipe-001");

// Basic search
var results = await vdb.SearchAsync("cloud hosting services");

// Search with threshold, paging, and metadata filter
var filtered = await vdb.SearchAsync(
    "cloud hosting services",
    threshold: 0.1f,           // minimum cosine similarity score
    pageIndex: 0,              // first page
    pageCount: 5,              // up to 5 results per page
    filter: async (metadata) =>
        metadata.StartsWith("azure") || metadata.StartsWith("aws")
);

foreach (var item in filtered.Texts)
{
    Console.WriteLine($"[{item.Similarity:F4}] ({item.Metadata}) {item.Text}");
}
```

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

### Perform Similarity Search

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/embeddings/ollama/index.md

Perform a similarity search using a query text. Supports specifying a similarity threshold, page index, and page count for results.

```csharp
var query = "your search query";
var results = await vectorDatabase.SearchAsync(query);
```

```csharp
var results = await vectorDatabase.SearchAsync(queryText,
  threshold: 0.001f // 0.2f - Cosine Similarity
  pageIndex: 0, // page index of search results (default: 0)
  pageCount: 10 // Number of results per page to return (default: no limit)
);
```

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

### Semantic Search with Metadata Filtering (Sync)

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/search/index.md

Pre-filter search results based on metadata before performing the vector similarity search. This can improve performance on large datasets. The filter is a boolean evaluation of the text item's metadata.

```csharp
var vdb = new BasicMemoryVectorDatabase();

// load text and metadata into database

var query = "some text to search";
var results = vdb.Search(
    query,
    filter: (metadata) => {
        // perform some operation to check metadata
        // return true or false
        return metadata.Contains("B59");
    }
);
```

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

### Load and Chunk Text Documents with TextDataLoader

Source: https://context7.com/build5nines/sharpvector/llms.txt

Use TextDataLoader to break large documents into smaller chunks for semantic search. Supports various chunking methods and custom metadata retrieval.

```csharp
using Build5Nines.SharpVector;
using Build5Nines.SharpVector.Data;
using System.Text.Json;

var vdb = new BasicMemoryVectorDatabase();
var loader = new TextDataLoader<int, string>(vdb);

string filename = "terraform-docs.md";
string document = File.ReadAllText(filename);

// Paragraph chunking with JSON metadata per chunk
await loader.AddDocumentAsync(document, new TextChunkingOptions<string>
{
    Method = TextChunkingMethod.Paragraph,
    RetrieveMetadata = (chunk) => JsonSerializer.Serialize(new
    {
        fileName = filename,
        chunkLength = chunk.Length,
        indexedAt = DateTime.UtcNow.ToString("o")
    })
});

// Fixed-length chunking with overlap
await loader.AddDocumentAsync(document, new TextChunkingOptions<string>
{
    Method = TextChunkingMethod.OverlappingWindow,
    ChunkSize = 300,
    OverlapSize = 75,
    RetrieveMetadata = (chunk) => filename
});

var results = await vdb.SearchAsync("resource group configuration", pageCount: 5);
foreach (var item in results.Texts)
{
    Console.WriteLine($"Source: {item.Metadata}  Score: {item.Similarity:F4}");
    Console.WriteLine(item.Text[..Math.Min(120, item.Text.Length)]);
    Console.WriteLine();
}
```

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

### Iterate Through All Text Items

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/data-management/index.md

The IVectorDatabase classes implement IEnumerable, allowing you to easily loop through all text items in the database. Access the ID, text, metadata, and vector for each item.

```csharp
foreach(var item in vdb) {
    var id = item.Id;
    var text = item.Text;
    var metadata = item.Metadata;
    var vector = item.Vector;

    // do something here
}
```

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

### Add TextDataLoader Namespace

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/text-chunking/index.md

Include the necessary namespace to use the TextDataLoader class for document processing.

```csharp
using Build5Nines.SharpVector.Data;
```

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

### Load Document with Paragraph Chunking in C#

Source: https://github.com/build5nines/sharpvector/blob/main/src/Build5Nines.SharpVector/docs/README.md

Utilizes the `TextDataLoader` to load a document into the Vector Database using paragraph chunking. Custom metadata can be generated for each chunk based on its content.

```csharp
/// Paragraph Chunking
var loader = new TextDataLoader<int, string>(vdb);
loader.AddDocument(document, new TextChunkingOptions<string>
{
    Method = TextChunkingMethod.Paragraph,
    RetrieveMetadata = (chunk) => {
        // add some basic metadata since this can't be null
        return "{ chuckSize: " + chunk.Length + " }";
    }
});
```

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

### Chunk Text with Overlapping Window

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/text-chunking/index.md

Creates text chunks using an overlapping window approach, allowing for context continuity between adjacent chunks. Specifies chunk size and overlap size in words.

```csharp
string document = LoadDocumentText();
loader.AddDocument(document, new TextChunkingOptions<string>
{
    Method = TextChunkingMethod.OverlappingWindow,
    ChunkSize = 150,
    // Number of words to overlap text chunks
    OverlapSize = 50,
    RetrieveMetadata = (chunk) => {
        return "{ \"chunkSize\": \"" + chunk.Length + "\" }";
    }
}

```

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

### Update Text and Metadata

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/data-management/index.md

Simultaneously update both the 'Text' and 'Metadata' for a text item in the database using its 'Id' with the `.UpdateTextAndMetadata` method.

```csharp
vdb.UpdateTextAndMetadata(id, newTxt, newMetadata);
```

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

### Chunk Text by Fixed-Length

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/text-chunking/index.md

Segments a document into fixed-size character chunks. This method is suitable for very large documents or when uniform chunk sizes are required. Metadata includes the chunk size.

```csharp
string document = LoadDocumentText();
loader.AddDocument(document, new TextChunkingOptions<string>
{
    Method = TextChunkingMethod.FixedLength,
    ChunkSize = 150,
    RetrieveMetadata = (chunk) => {
        return "{ \"chunkSize\": \"" + chunk.Length + "\" }";
    }
});
```

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

### MemoryVectorDatabase<TMetadata>

Source: https://context7.com/build5nines/sharpvector/llms.txt

A strongly-typed vector database that allows storing custom .NET classes as metadata, optimizing performance by avoiding JSON serialization.

```APIDOC
## MemoryVectorDatabase<TMetadata>

### Description
Use the generic `MemoryVectorDatabase<TMetadata>` to store any .NET class as metadata alongside each text item, eliminating JSON serialization overhead when string metadata is insufficient.

### Method
`MemoryVectorDatabase<TMetadata>()`

### Parameters
#### Type Parameters
- **TMetadata** - The .NET class to be used as custom metadata.

### Usage Example
```csharp
public record ArticleMetadata(string Title, string Author, string Url);

var vdb = new MemoryVectorDatabase<ArticleMetadata>();

vdb.AddText(
    "Build5Nines.SharpVector makes it easy to add semantic search to any .NET app.",
    new ArticleMetadata("SharpVector Intro", "Chris Pietschmann", "https://build5nines.com/sharpvector")
);

var results = await vdb.SearchAsync("vector database .NET", pageCount: 5);

foreach (var item in results.Texts)
{
    Console.WriteLine($"Title:  {item.Metadata.Title}");
    Console.WriteLine($"Author: {item.Metadata.Author}");
    Console.WriteLine($"URL:    {item.Metadata.Url}");
    Console.WriteLine($"Score:  {item.Similarity:F4}");
    Console.WriteLine();
}
```
```

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

### Enumerate Text Items

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/get-started/data-management/index.md

Iterates through all text items in the database, providing access to their ID, text, metadata, and vector.

```APIDOC
## Enumerate Text Items

### Description
Allows iteration through all text items stored in the vector database. Each item provides access to its ID, text content, metadata, and vector representation.

### Method
```csharp
foreach(var item in vdb) {
    var id = item.Id;
    var text = item.Text;
    var metadata = item.Metadata;
    var vector = item.Vector;

    // do something here
}
```
```

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

### Add Text Data to Vector Database

Source: https://github.com/build5nines/sharpvector/blob/main/docs/docs/embeddings/ollama/index.md

Add textual content and associated metadata to the vector database. Metadata is stored for retrieval but not vectorized.

```csharp
// sync
vectorDatabase.AddText(documentText, metadataText);

// async
await vectorDatabase.AddTextAsync(documentText, metadataText);
```