feat: add FSharp.Azure.Cosmos.Sql, a syntax tree, printer, validator and function catalog for Cosmos DB SQL

[xperiandri]

Proposed Changes

Depends on #48. The project FSharp.Azure.Cosmos.Sql with EquatableArray and the ImmutableArray patterns is split off into #48, as asked in the review, and this branch is built on it. Until #48 is merged, this pull request also shows its commit; the model is the six commits after it. It targets main and not the branch of #48, because the build workflow runs only for pull requests into main.

Queries in this library are SQL strings today (QueryDefinition) or go through the SDK's LINQ provider. A string is only checked when the service runs it. A reserved word used as a property name (c.value), a parameter where the service accepts none, TOP inside a subquery or an unknown function all fail at run time, and text built by concatenation cannot be inspected, rewritten or compared. The SDK has a typed model of the query language (its SqlObjects classes, the sql.g4 grammar and its text printer), but all of it is internal. The query translator for F# quotations planned in ADR 0001 (#34) needs a model this repository owns: a query is built as data, checked, and then printed the same way every time.

This pull request adds that model as a new package, FSharp.Azure.Cosmos.Sql. It targets net10.0 and depends on FSharp.Core only (System.Text.Json is in-box).

• Syntax tree. The query is F# records and unions instead of text, one case per construct of the SDK grammar, named after the SDK's classes (SqlQuery, ScalarExpression, CollectionExpression, …). There is no case for raw SQL text. Child lists are EquatableArray<'T> (feat: add FSharp.Azure.Cosmos.Sql with EquatableArray and the ImmutableArray patterns #48), an immutable array that compares its elements. Plain ImmutableArray<'T> compares array references, which would break the equality of whole trees that tests and a query cache rely on.
• Printer. It writes a tree as query text following the SDK's printer rules: every property access as c["name"] (safe for reserved words), every operator in parentheses, the SDK's string escaping, and numbers in the invariant culture. It has two modes. The parameterized mode keeps parameters as @name. The inline mode writes each parameter's value as a literal, for APIs that take query text without parameters, such as the filter predicate of a patch.
• Validator. SqlQuery.validate reports the rules the grammar cannot express, as error codes with English messages. Examples: SELECT * over a JOIN, TOP in a subquery, an ORDER BY key that is neither a property path nor VectorDistance or a scoring function, a reserved word as an alias, an empty IN list, a wrong number of function arguments.
• Function catalog. The built-in functions are data (Catalog.all, and the case-insensitive Catalog.byName): every name the SDK knows plus the documented names it lacks, 174 in all. 52 are specified from their Microsoft Learn pages (argument count, result type, index use, where they may appear); the others are marked unsupported with a reason. Catalog.call builds a call after checking the function and the number of arguments.

open FSharp.Azure.Cosmos.Sql

let c = ScalarExpression.PropertyRef (Identifier "c")
let field name = ScalarExpression.MemberIndexer (c, ScalarExpression.Literal (Literal.String name))
let param name = ScalarExpression.ParameterRef (ParameterName name)

let query = {
    Select = SelectSpec.Value c
    Distinct = false
    Top = ValueSome (SpecValue.Parameter (ParameterName "@take"))
    From = ValueSome (CollectionExpression.Aliased (Collection.InputPath (Identifier "c", ValueNone), ValueNone))
    Where = ValueSome (ScalarExpression.Binary (BinaryOperator.GreaterThanOrEqual, field "age", param "@minAge"))
    GroupBy = EquatableArray.empty
    OrderBy = EquatableArray.singleton { Expression = field "name"; Order = ValueNone }
    OrderByRank = false
    OffsetLimit = ValueNone
}

SqlQuery.validate query                    // empty: the query breaks no rule
Printer.print PropertyStyle.Brackets query
// SELECT TOP @take VALUE c FROM c WHERE (c["age"] >= @minAge) ORDER BY c["name"]

Nobody is expected to write trees by hand like this; the quotation translator will build them. The package stands on its own so that the translator, its tests and later tools share one model.

Not in this pull request (later steps of ADR 0001):

• translating F# quotations;
• parsing SQL text into the tree;
• rewriting passes such as simplification;
• the validator rules that need emulator checks first (ORDER BY and OFFSET LIMIT inside subqueries, GROUP BY projections);
• conformance tests against the SDK's ANTLR grammar;
• property-based tests.

Catalog entries stay unsupported until a translator needs them.

Deliberate differences from the SDK or the ADR text

• The printer writes single spaces where the SDK writes NOT LIKE and a space after GROUP BY. The text equals the SDK baselines after whitespace normalization.
• / in strings is not escaped. The ADR lists \/, but the SDK never writes it: it escapes only the control characters, " and \, and its parser baseline prints "\/solidus" as "/solidus".
• Object keys are escaped like other strings. The SDK writes them raw, which gives the same text for every key that needs no escaping.
• The validator refuses a parameter as an ORDER BY key, but accepts parameters as arguments of VectorDistance and the scoring functions. Microsoft Learn and the SDK's query-plan baseline pass the query vector that way: ORDER BY VectorDistance(c.embedding, @embedding).

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

• Build and tests pass locally
• I have added tests that prove my fix is effective or that my feature works (if appropriate)
• I have added necessary documentation (if appropriate)

Further comments

Six commits on top of #48: syntax tree, printer, catalog, validator, packaging and the solution tree of the agent instructions. Each builds and passes its tests on its own. The changelog lists the package under Unreleased, and the packaging commit removes the IsPackable=false that #48 sets.

tests/Cosmos.Sql.Tests has 75 tests, 15 of them from #48, and needs no emulator:

• the equality of whole syntax trees: separately built trees are equal, hash alike and find each other as dictionary keys;
• printer output for every kind of node, mostly with expected strings taken from the SDK's own baseline files (cited in the tests);
• escaping of every control character;
• printing under fr-FR and under a culture with unusual number symbols;
• validator accept and reject cases, one rule at a time;
• argument counts in the catalog;
• a comparison of the catalog with the function names of the SDK version in use, so that the test fails when an SDK update adds or removes a function.

Verification:

• dotnet build FSharp.Azure.Cosmos.slnx in Debug and Release: 0 errors and the same warnings as main. With -p:WarnOn=3390, which reports malformed documentation comments, the two new projects give no warning.
• New tests: 75 passed in Debug and in Release, and every commit passes the tests it has (17, 53, 61, 75, 75, 75).
• Strict documentation build (fsdocs build --strict with the arguments of build.cmd BuildDocs): passed. Fantomas check: clean.
• dotnet pack: the package depends on FSharp.Core only and contains the XML documentation and THIRD-PARTY-NOTICES.md, which attributes the material taken from the Azure Cosmos DB .NET SDK (MIT).
• The example above was compiled and run against the built package; it prints exactly the line shown.

Changes after the review

The branch was rebuilt on #48 with every change folded into the commit it belongs to; the review threads are answered one by one.

• Split: EquatableArray.fs, ImmutableArrayPatterns.fs, the two projects and their tests (15 by now) are feat: add FSharp.Azure.Cosmos.Sql with EquatableArray and the ImmutableArray patterns #48. The two tests that compare whole syntax trees stay here as SyntaxTests, because they need the tree.
• Plain documentation comments: a comment whose <summary> holds no tag is plain /// lines, 35 comments in 8 files. The generated XML documentation is the same before and after, member by member.
• One-line summaries in Syntax.fs only: the summary of a union case is on one line when the line is at most 60 characters long, 33 cases: the operators, the sort orders and the other cases with a very short text.
• ValidationError is a struct, and ValidationOptions.Default is one instance held in a static let.
• CatalogData.functions is a seq { } piped into ImmutableArray.CreateRange, and Keywords.reserved is built with |> _.ToFrozenSet(...).
• The members of the validator have documentation comments.
• The test categories are sorted by name.
• Numbers in Inline.ofJsonElement (Copilot's remark on test: add Cosmos.Sql.Hedgehog with the generator helpers #54): the comment promised a constant that writes the same JSON, which does not hold for a number with more digits than a double has, such as 0.123456789012345678901. The conversion stays: Azure Cosmos DB keeps every number as an IEEE 754 double, so the nearest double is the value the service reads from those digits too. The comment now says that, and a test fixes the rounding.
• One value per parameter in the inline mode (Copilot's remark on test(benchmarks): measure what a quotation query costs on the client #56): the inline pass asked its encoder once for every use of a parameter, so an encoder that reads a clock or serializes a value could put two different literals for one parameter into a query. It now asks once for every parameter name and uses that answer everywhere, as a named parameter of a QueryDefinition has one value.
• Arrays in the tests (review of 2026-10-11): the tree builders of the tests, call, udf, arrayOf and objectOf in Ast.fs, take an array and wrap it with EquatableArray.unsafeOfArray, and the test bodies pass array literals where they passed lists.

🤖 Generated with Claude Code

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Note

This error may be related to your runner configuration. You can now configure runners for Copilot code review separately from Copilot cloud agent by creating a copilot-code-review.yml file with your setup steps. Read the docs for details.

[xperiandri]

Details

[xperiandri]

use unsafeOfArray in tests to create instances

[xperiandri]

use unsafeOfArray in tests to create instances

Done, in the commits that introduce the tests (c6fd556, 8786bbf, 2464182) and in #48 (2cc6691):

• The tree builders of Ast.fs – call, udf, arrayOf and objectOf – take an array and wrap it with EquatableArray.unsafeOfArray, and so does orderedBy in ValidatorTests.fs. Their call sites pass array literals: call "ARRAY_CONTAINS" [| c |> prop "tags"; param "@p0" |].
• Every EquatableArray.ofSeq [ … ] in a test body is EquatableArray.unsafeOfArray [| … |] now.
• The tests of EquatableArray itself (feat: add FSharp.Azure.Cosmos.Sql with EquatableArray and the ImmutableArray patterns #48) wrap their array literals too. ofArray and ofSeq are left only in the test that checks that they copy.
• EquatableArray.singleton and EquatableArray.empty stay as they are: neither copies anything.

The generators of #55 wrap the arrays they generate in the same way.

The branch is also rebased onto main with #53.