CosmosDB.OData.Sql 4.2.0

Microsoft.Azure.Cosmos.OData

Translates OData V4 queries into Azure Cosmos DB SQL queries.

v3 — complete rewrite. This version replaces the legacy Microsoft.Azure.Documents.OData.Sql package. See MIGRATION.md for upgrade instructions from v1/v2.

Key features

Quick start

using Microsoft.Azure.Cosmos.OData;

// 1. Create the translator (reuse it — it's thread-safe)
var translator = new ODataToCosmosSqlTranslator();

// 2. Build clauses from an OData URI (or from ASP.NET's ODataQueryOptions via an adapter)
var clauses = new ODataQueryClauses
{
    Filter = parser.ParseFilter(),
    OrderBy = parser.ParseOrderBy(),
    Select = parser.ParseSelectAndExpand(),
    Top = parser.ParseTop(),
    Skip = parser.ParseSkip(),
    Count = parser.ParseCount(),
};

// 3. Translate
TranslatedQuery result = translator.Translate(clauses);

Console.WriteLine(result.Sql);
// SELECT * FROM c WHERE c.revenue > @p0 ORDER BY c.name ASC OFFSET 0 LIMIT 10

Console.WriteLine(result.Parameters);
// { "@p0": 1000 }

// 4. Use with Cosmos SDK
var queryDef = new QueryDefinition(result.Sql);
foreach (var (key, value) in result.Parameters)
    queryDef = queryDef.WithParameter(key, value);

Translation options

var options = new TranslationOptions
{
    Clauses = TranslationClauses.All,                    // which clauses to translate
    Parameterization = ParameterizationMode.Parameters,  // default: parameterized SQL
    Pagination = PaginationMode.OffsetLimit,              // default: OFFSET/LIMIT (not TOP)
    DocumentAlias = "c",                                  // the FROM alias
    AdditionalWhereClause = "c.isActive = true",          // extra raw WHERE fragment
};

var result = translator.Translate(clauses, options);

Inline mode (for debugging)

var options = new TranslationOptions { Parameterization = ParameterizationMode.Inline };
// Produces: SELECT * FROM c WHERE c.name = 'Microsoft'

Legacy TOP mode

var options = new TranslationOptions { Pagination = PaginationMode.Top };
// Produces: SELECT TOP 10 * FROM c ...

Architecture

The engine is designed around SOLID principles:

• IFieldNameResolver — maps OData property names to Cosmos document paths (englishName → c.englishName). Default: DefaultFieldNameResolver.
• ISqlFunctionMapper — maps OData functions to Cosmos SQL functions (contains → CONTAINS, trim → LTRIM(RTRIM(…))). Built-in mappers:
  • DefaultFunctionMapper — string, math, date, type-check functions.
  • GeospatialFunctionMapper — geo.distance → ST_DISTANCE, etc.
  • VectorSearchFunctionMapper — vectordistance → VectorDistance.
  • FullTextSearchFunctionMapper — fulltextcontains → FullTextContains, etc.
  • CompositeFunctionMapper — composes multiple mappers in priority order.
• ISqlExpressionRenderer — renders the SQL expression tree to a string with parameter substitution. Default: CosmosSqlRenderer.
• ODataToCosmosSqlTranslator — the orchestrator. Accepts ODataQueryClauses (a framework-agnostic DTO) and TranslationOptions, delegates to the above.

SQL expression AST

Instead of concatenating strings, the visitor builds an immutable SqlExpression tree:

SqlExpression
├── SqlLiteral(value)
├── SqlMember(path)
├── SqlBinary(op, left, right)
├── SqlUnary(op, operand)
├── SqlFunctionCall(name, args)
├── SqlExists(rangeVar, source, predicate)
├── SqlRaw(text)
└── SqlNull

This makes the engine testable, extensible, and free of leaky abstractions.

Supported OData → Cosmos SQL mappings

System query options

Built-in functions

String functions

Mathematical functions

Date/Time functions

Type checking functions

Array functions

Geospatial functions

Vector & Full-text search

Project structure

src/
  Microsoft.Azure.Cosmos.OData/        ← engine (netstandard2.0 + net8/9/10)
    Abstractions/                       ← IFieldNameResolver, ISqlFunctionMapper, ISqlExpressionRenderer
    Ast/                                ← SqlExpression record hierarchy
    Errors/                             ← ODataTranslationException hierarchy
    Functions/                          ← Default, Geospatial, Vector, FullText function mappers
    Naming/                             ← DefaultFieldNameResolver
    Options/                            ← TranslationOptions, TranslationClauses, ParameterizationMode, PaginationMode
    Rendering/                          ← CosmosSqlRenderer
    Translation/                        ← ODataExpressionVisitor, ODataToCosmosSqlTranslator
    ODataQueryClauses.cs                ← Framework-agnostic input DTO
    TranslatedQuery.cs                  ← Result (SQL + parameters)
tests/
  Microsoft.Azure.Cosmos.OData.Tests/   ← xUnit tests

Contributing

See CONTRIBUTING.md (coming soon).

License

MIT

Authors

• Ziyou Zheng — original author
• Contributors welcome!