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	Semantic search, RAG, embeddings	SQL Server 2025, Azure AI Search, pgvector, OpenSearch
Full-Text Search	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

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

// 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):

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:

// 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:

-- 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

// 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:

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:

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:

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:

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 - EF Core and Dapper

• AI Providers - Generate embeddings for vector search

• Email Providers - Send transactional emails

• Message Providers - SMS and push notifications