Cosmos Repository — LINQ Queries & Data Access

Core Principles

• One repository per container (not per entity type)
• Point reads (ReadItemAsync) are the most efficient operation
• LINQ queries via GetItemLinqQueryable<T>() with discriminator filtering
• FeedIterator for paginating large result sets
• Monitor Request Unit (RU) charges from response headers
• Cross-partition queries are expensive — avoid when possible

Key Patterns

Generic Cosmos Repository

namespace {Company}.{Domain}.Cosmos.Infrastructure;

public sealed class CosmosRepository<T>(
    Container container,
    ILogger<CosmosRepository<T>> logger) where T : IContainerDocument
{
    public async Task<T?> GetByIdAsync(
        string id, PartitionKey pk, CancellationToken ct)
    {
        try
        {
            var response = await container.ReadItemAsync<T>(
                id, pk, cancellationToken: ct);

            logger.LogDebug("Point read: {RU} RUs", response.RequestCharge);
            return response.Resource;
        }
        catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
        {
            return default;
        }
    }

    public async Task<List<T>> QueryAsync(
        Expression<Func<T, bool>> predicate,
        PartitionKey? pk = null,
        CancellationToken ct = default)
    {
        var options = new QueryRequestOptions();
        if (pk.HasValue)
            options.PartitionKey = pk.Value;

        var queryable = container.GetItemLinqQueryable<T>(
            requestOptions: options)
            .Where(d => d.Discriminator == typeof(T).Name)
            .Where(predicate);

        using var iterator = queryable.ToFeedIterator();
        var results = new List<T>();
        double totalRU = 0;

        while (iterator.HasMoreResults)
        {
            var response = await iterator.ReadNextAsync(ct);
            results.AddRange(response);
            totalRU += response.RequestCharge;
        }

        logger.LogDebug("Query returned {Count} items, {RU} RUs",
            results.Count, totalRU);
        return results;
    }

    public async Task UpsertAsync(T document, CancellationToken ct)
    {
        var response = await container.UpsertItemAsync(
            document, document.PartitionKeys,
            new ItemRequestOptions { IfMatchEtag = document.ETag },
            ct);

        document.ETag = response.ETag;
        logger.LogDebug("Upsert: {RU} RUs", response.RequestCharge);
    }

    public async Task CreateAsync(T document, CancellationToken ct)
    {
        var response = await container.CreateItemAsync(
            document, document.PartitionKeys, cancellationToken: ct);

        document.ETag = response.ETag;
        logger.LogDebug("Create: {RU} RUs", response.RequestCharge);
    }

    public async Task DeleteAsync(
        string id, PartitionKey pk, CancellationToken ct)
    {
        await container.DeleteItemAsync<T>(id, pk, cancellationToken: ct);
    }
}

Paginated Query with FeedIterator

public async Task<(List<T> Items, string? ContinuationToken)> QueryPagedAsync(
    Expression<Func<T, bool>> predicate,
    int pageSize,
    string? continuationToken = null,
    CancellationToken ct = default)
{
    var queryable = container.GetItemLinqQueryable<T>(
        continuationToken: continuationToken,
        requestOptions: new QueryRequestOptions { MaxItemCount = pageSize })
        .Where(d => d.Discriminator == typeof(T).Name)
        .Where(predicate);

    using var iterator = queryable.ToFeedIterator();
    var results = new List<T>();
    string? nextToken = null;

    if (iterator.HasMoreResults)
    {
        var response = await iterator.ReadNextAsync(ct);
        results.AddRange(response);
        nextToken = response.ContinuationToken;
    }

    return (results, nextToken);
}

SQL Query (For Complex Queries)

public async Task<List<T>> QuerySqlAsync(
    string sql, Dictionary<string, object> parameters, CancellationToken ct)
{
    var queryDef = new QueryDefinition(sql);
    foreach (var param in parameters)
        queryDef = queryDef.WithParameter($"@{param.Key}", param.Value);

    using var iterator = container.GetItemQueryIterator<T>(queryDef);
    var results = new List<T>();

    while (iterator.HasMoreResults)
    {
        var response = await iterator.ReadNextAsync(ct);
        results.AddRange(response);
    }

    return results;
}

Anti-Patterns

Anti-Pattern	Correct Approach
Missing discriminator filter	Always filter by Discriminator in queries
Cross-partition queries for known PK	Provide partition key when available
Not tracking RU charges	Log RU charges for monitoring and optimization
Using ReadItemAsync without ETag	Set ETag from read for subsequent updates
Large unbounded queries	Use FeedIterator with MaxItemCount for pagination

Detect Existing Patterns

# Find Cosmos repositories
grep -r "CosmosRepository\|Container container" --include="*.cs" src/

# Find LINQ queries
grep -r "GetItemLinqQueryable" --include="*.cs" src/

# Find FeedIterator usage
grep -r "FeedIterator\|ToFeedIterator" --include="*.cs" src/

# Find RU logging
grep -r "RequestCharge" --include="*.cs" src/

Adding to Existing Project

1. Check if a generic CosmosRepository<T> exists or if repos are per-entity
2. Match the discriminator filtering pattern used in existing queries
3. Follow RU logging conventions — check existing log levels
4. Use point reads (ReadItemAsync) wherever possible over queries
5. Provide partition key to avoid expensive cross-partition queries