> For the complete documentation index, see [llms.txt](https://docs.flexbase.in/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flexbase.in/data-and-providers/data-stores.md).

# Data Stores

FlexBase provides a comprehensive set of data store abstractions for modern application development. Each store type is designed for specific use cases and provides a unified interface across multiple provider implementations.

## Available Data Stores

### Core Data Stores

| Store Type                                                                        | Description                      | Providers                                              |
| --------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------ |
| [**Vector Store**](/data-and-providers/data-stores/vector-store.md)               | Semantic search, RAG, embeddings | SQL Server 2025, Azure AI Search, pgvector, OpenSearch |
| [**Full-Text Search**](/data-and-providers/data-stores/search-store-full-text.md) | Keyword search with ranking      | SQL Server, PostgreSQL, MySQL, Elasticsearch           |
| **Document Store**                                                                | JSON document storage            | MongoDB, CosmosDB, DynamoDB, RavenDB                   |
| **File Store**                                                                    | Binary file storage              | AWS S3, Azure Blob, GCP Storage, Disk                  |
| **Graph Store**                                                                   | Relationship networks            | Neo4j, Cosmos Gremlin                                  |
| **Time Series Store**                                                             | Time-based metrics               | InfluxDB, TimescaleDB, Azure Data Explorer             |

### When to Use Each Store

| Use Case                | Recommended Store                                     |
| ----------------------- | ----------------------------------------------------- |
| **Semantic search**     | Vector Store                                          |
| **Keyword search**      | Full-Text Search                                      |
| **Document management** | Document Store                                        |
| **File uploads**        | File Store                                            |
| **Social networks**     | Graph Store                                           |
| **IoT/Metrics**         | Time Series Store                                     |
| **Structured data**     | [Relational DB](/data-and-providers/relational-db.md) |

## Quick Start

### Automatic Setup via Flex Studio

Data Store providers are automatically added to your application through **Flex Studio**. When you add a data store provider:

1. **Provider files are created** in `Infrastructure/Providers/{YourApplication}.DataStoreProviders/{Category}/{Provider}/`
2. **NuGet package is referenced** automatically
3. **Default configuration** is added to `Application/EndPoints/{YourApplication}.EndPoint.CommonConfigs/AppSettings/DataStores/{Category}/{Provider}.json`
4. **README documentation** is included in the provider folder

You can find all provider files, configuration examples, and documentation in the generated infrastructure folder.

### 1. Choose Your Store

Select the appropriate store type based on your use case. Each store has specific strengths:

* **Vector Store** - When you need AI-powered semantic search or RAG
* **Full-Text Search** - When you need fast keyword search with ranking
* **Document Store** - When you need flexible schema and JSON storage
* **File Store** - When you need to store and serve binary files

### 2. Add Provider via Flex Studio

In Flex Studio, select the data store category and provider you want to use. Flex Studio will:

* Create the provider infrastructure folder
* Reference the appropriate NuGet package
* Generate default configuration files
* Include provider-specific documentation

### 3. Configure and Use

After adding via Flex Studio:

1. **Update configuration** in the generated `AppSettings/DataStores/{Category}/{Provider}.json` file
2. **Review registration examples** in the provider folder's README
3. **Register in DI** using the extension methods shown in the README
4. **Inject and use** in your services

```csharp
// Example: After adding Vector Store provider via Flex Studio
public class MyService
{
    private readonly IFlexVectorStore _vectorStore;
    
    public MyService(IFlexVectorStore vectorStore)
    {
        _vectorStore = vectorStore;  // Automatically available after Flex Studio setup
    }
    
    public async Task IndexDocumentAsync(string id, string content)
    {
        // Use the store - configuration already set up
        await _vectorStore.UpsertAsync(id, embedding, content: content);
    }
}
```

## Featured: Vector Store + AI

The **Vector Store** is particularly powerful when combined with **AI Providers** for implementing RAG (Retrieval-Augmented Generation):

```csharp
public class RAGService
{
    private readonly IFlexVectorStore _vectorStore;
    private readonly IFlexAIProvider _aiProvider;

    public async Task<string> AskQuestionAsync(string question)
    {
        // 1. Generate query embedding
        var queryEmbedding = await _aiProvider.EmbedAsync(question);

        // 2. Search for relevant context
        var results = await _vectorStore.SearchAsync(
            queryVector: queryEmbedding,
            topK: 5,
            minScore: 0.75f);

        // 3. Build context
        var context = string.Join("\n\n", results.Select(r => r.Content));

        // 4. Get AI response with context
        var prompt = $"""
            Answer based on this context:
            {context}
            
            Question: {question}
            """;

        return await _aiProvider.ChatAsync(prompt);
    }
}
```

## Hybrid Approaches

### Vector + Full-Text Search

Combine semantic and keyword search for best results:

```csharp
// 1. Full-text for keyword matches
var keywordResults = await _fullTextSearch.SearchAsync(query);

// 2. Vector search for semantic matches
var semanticResults = await _vectorStore.SearchAsync(queryEmbedding);

// 3. Merge and rank
var combined = MergeAndRankResults(keywordResults, semanticResults);
```

### SQL Server 2025: All-in-One

SQL Server 2025 supports both relational data AND vector search in one database:

```sql
-- Store business data + embeddings together
CREATE TABLE Products (
    Id INT PRIMARY KEY,
    Name NVARCHAR(200),
    Description NVARCHAR(MAX),
    Price DECIMAL(10,2),
    -- Vector column for semantic search
    DescriptionEmbedding VECTOR(1536)
);

-- Combine relational queries with vector search
SELECT TOP 10 p.*
FROM Products p
WHERE p.Category = 'Electronics'
  AND p.Price BETWEEN 100 AND 500
ORDER BY VECTOR_DISTANCE('cosine', p.DescriptionEmbedding, @queryVector);
```

## Provider-Agnostic Design

All FlexBase data stores follow a consistent pattern:

1. **Unified Interface** - Same API across all providers
2. **Provider-Specific Features** - Access advanced features when needed
3. **Easy Migration** - Switch providers with configuration changes
4. **Testing Support** - Mock implementations for unit tests

```csharp
// Works with ANY vector store provider
public class DocumentService
{
    private readonly IFlexVectorStore _vectorStore;  // Could be SQL Server, pgvector, etc.
    
    public async Task IndexAsync(string id, string content)
    {
        var embedding = await _aiProvider.EmbedAsync(content);
        await _vectorStore.UpsertAsync(id, embedding, content: content);
    }
}
```

## Integration with FlexBase Features

All data stores integrate seamlessly with FlexBase features:

* **Dependency Injection** - Standard IOptions pattern
* **Logging** - Structured logging built-in
* **Health Checks** - Test connectivity on startup
* **Configuration** - appsettings.json support
* **Multi-tenancy** - Tenant isolation support
* **Caching** - Integration with FlexCache

## Best Practices

1. **Start Simple** - Use what you need, add complexity later
2. **Test Locally** - Use in-memory or local providers for development
3. **Monitor Performance** - Track query times and costs
4. **Implement Caching** - Cache frequently accessed data
5. **Plan for Scale** - Consider growth from the start
6. **Use Hybrid** - Combine stores for optimal results

## Advanced Usage Examples

### Vector Store

Vector stores are used for semantic search and retrieval-augmented generation (RAG). Below is an example:

```csharp
public class SemanticSearchService
{
    private readonly IFlexVectorStore _vectorStore;

    public SemanticSearchService(IFlexVectorStore vectorStore)
    {
        _vectorStore = vectorStore;
    }

    public async Task<IEnumerable<SearchResult>> SearchAsync(string query)
    {
        return await _vectorStore.SearchAsync(query, topK: 10);
    }
}
```

### Full-Text Search

Full-text search stores are optimized for keyword-based search. Below is an example:

```csharp
public class KeywordSearchService
{
    private readonly IFlexSearchStore _searchStore;

    public KeywordSearchService(IFlexSearchStore searchStore)
    {
        _searchStore = searchStore;
    }

    public async Task<IEnumerable<SearchResult>> SearchAsync(string keyword)
    {
        return await _searchStore.SearchAsync(keyword);
    }
}
```

### Document Store

Document stores are ideal for JSON-based storage. Below is an example:

```csharp
public class DocumentService
{
    private readonly IFlexDocumentStore _documentStore;

    public DocumentService(IFlexDocumentStore documentStore)
    {
        _documentStore = documentStore;
    }

    public async Task SaveDocumentAsync(string id, object document)
    {
        await _documentStore.SaveAsync(id, document);
    }

    public async Task<object> GetDocumentAsync(string id)
    {
        return await _documentStore.GetAsync(id);
    }
}
```

### File Store

File stores are used for binary file storage. Below is an example:

```csharp
public class FileStorageService
{
    private readonly IFlexFileStore _fileStore;

    public FileStorageService(IFlexFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task UploadFileAsync(string path, Stream fileStream)
    {
        await _fileStore.UploadAsync(path, fileStream);
    }

    public async Task<Stream> DownloadFileAsync(string path)
    {
        return await _fileStore.DownloadAsync(path);
    }
}
```

## See Also

* [Relational Databases](/data-and-providers/relational-db.md) - EF Core and Dapper
* [AI Providers](/data-and-providers/providers/ai-providers.md) - Generate embeddings for vector search
* [Email Providers](/data-and-providers/providers/e-mail.md) - Send transactional emails
* [Message Providers](/data-and-providers/providers/text-message.md) - SMS and push notifications