# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flexbase.in/data-and-providers/data-stores.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.