Skip to content

Query: Adds ArrayContains to CosmosLinqExtensions to allow partial matching on array fields in queries #4992

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Query: Adds ArrayContains to CosmosLinqExtensions to allow partial matching on array fields in queries #4992

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
786db81
Added ArrayContains to CosmosLinqExtensions to allow partial matching
Jan 31, 2025
d2e3e99
Merge branch 'master' into feature/array_contains_builtin_function
bcrobinson Feb 5, 2025
9d99782
Merge branch 'master' into feature/array_contains_builtin_function
bcrobinson Feb 11, 2025
c981452
Added overload for ArrayContains with no 3rd paritalMatch parameter
Feb 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 28 additions & 1 deletion Microsoft.Azure.Cosmos/src/Linq/BuiltinFunctions/ArrayBuiltinFunctions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,13 @@ public ArrayContainsVisitor()
{
}

public bool UsePartialMatchParameter { get; set; }
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

public bool UsePartialMatchParameter { get; set; }

not sure if this is necessary


protected override SqlScalarExpression VisitImplicit(MethodCallExpression methodCallExpression, TranslationContext context)
{
Expression searchList = null;
Expression searchExpression = null;
Expression partialMatchExpression = null;

// If non static Contains
if (methodCallExpression.Arguments.Count == 1)
Expand All @@ -59,6 +62,13 @@ protected override SqlScalarExpression VisitImplicit(MethodCallExpression method
searchList = methodCallExpression.Arguments[0];
searchExpression = methodCallExpression.Arguments[1];
}
// if CosmosLinqExtensions.ArrayContains extension method which includes partial match parameter
else if (this.UsePartialMatchParameter && methodCallExpression.Arguments.Count == 3)
{
searchList = methodCallExpression.Arguments[0];
searchExpression = methodCallExpression.Arguments[1];
partialMatchExpression = methodCallExpression.Arguments[2];
}

if (searchList == null || searchExpression == null)
{
Expand All @@ -72,7 +82,20 @@ protected override SqlScalarExpression VisitImplicit(MethodCallExpression method

SqlScalarExpression array = ExpressionToSql.VisitScalarExpression(searchList, context);
SqlScalarExpression expression = ExpressionToSql.VisitScalarExpression(searchExpression, context);
return SqlFunctionCallScalarExpression.CreateBuiltin("ARRAY_CONTAINS", array, expression);

SqlScalarExpression[] arrayContainsArgs;

if (partialMatchExpression is null)
{
arrayContainsArgs = new[] { array, expression };
}
else
{
SqlScalarExpression partialMatch = ExpressionToSql.VisitScalarExpression(partialMatchExpression, context);
arrayContainsArgs = new[] { array, expression, partialMatch };
}

return SqlFunctionCallScalarExpression.CreateBuiltin("ARRAY_CONTAINS", arrayContainsArgs);
}

private SqlScalarExpression VisitIN(Expression expression, ConstantExpression constantExpressionList, TranslationContext context)
Expand Down Expand Up @@ -177,6 +200,10 @@ static ArrayBuiltinFunctions()
{
"ToList",
new ArrayToArrayVisitor()
},
{
nameof(CosmosLinqExtensions.ArrayContains),
new ArrayContainsVisitor() { UsePartialMatchParameter = true }
}
};
}
Expand Down
7 changes: 6 additions & 1 deletion Microsoft.Azure.Cosmos/src/Linq/BuiltinFunctions/BuiltinFunctionVisitor.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,12 @@ public static SqlScalarExpression VisitBuiltinFunctionCall(MethodCallExpression
if (methodCallExpression.Method.Name == nameof(CosmosLinqExtensions.DocumentId))
{
return OtherBuiltinSystemFunctions.Visit(methodCallExpression, context);
}
}

if (methodCallExpression.Method.Name == nameof(CosmosLinqExtensions.ArrayContains))
{
return ArrayBuiltinFunctions.Visit(methodCallExpression, context);
}

return TypeCheckFunctions.Visit(methodCallExpression, context);
}
Expand Down
57 changes: 57 additions & 0 deletions Microsoft.Azure.Cosmos/src/Linq/CosmosLinqExtensions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
namespace Microsoft.Azure.Cosmos.Linq
{
using System;
using System.Collections;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
Expand Down Expand Up @@ -237,6 +238,62 @@ public static bool RegexMatch(this object obj, string regularExpression, string
throw new NotImplementedException(ClientResources.TypeCheckExtensionFunctionsNotImplemented);
}

/// <summary>
/// Returns a boolean indicating whether the array contains the specified value.
/// You can check for a partial or full match of an object by using a boolean expression within the function.
/// For more information, see https://learn.microsoft.com/en-gb/azure/cosmos-db/nosql/query/array-contains.
/// This method is to be used in LINQ expressions only and will be evaluated on server.
/// There's no implementation provided in the client library.
/// </summary>
/// <param name="obj"></param>
/// <param name="itemToMatch">The value to search within the array.</param>
/// <returns>Returns true if the array array contains the specified value; otherwise, false.</returns>
/// <example>
/// <code>
/// <![CDATA[
/// var matched = documents.Where(document => document.Namess.ArrayContains(<itemToMatch>, <partialMatch>));
/// // To do a partial match on an array of objects, pass in an anonymous object set partialMatch to true
/// var matched = documents.Where(document => document.ObjectArray.ArrayContains(new { Name = <name> }, true));
/// ]]>
/// </code>
/// </example>
public static bool ArrayContains(this IEnumerable obj, object itemToMatch)
{
// The signature for this is not generic so the user can pass in anonymous type for the item to match
// e.g documents.Where(document => document.FooItems.ArrayContains(new { Name = "Bar" }, true)
throw new NotImplementedException(ClientResources.TypeCheckExtensionFunctionsNotImplemented);
}

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this Array_contains is functionally the same as IEnumerable.Contains(), so please remove this and rename the other extension method to Contains instead

/// <summary>
/// Returns a boolean indicating whether the array contains the specified value.
/// You can check for a partial or full match of an object by using a boolean expression within the function.
/// For more information, see https://learn.microsoft.com/en-gb/azure/cosmos-db/nosql/query/array-contains.
/// This method is to be used in LINQ expressions only and will be evaluated on server.
/// There's no implementation provided in the client library.
/// </summary>
/// <param name="obj"></param>
/// <param name="itemToMatch">The value to search within the array.</param>
/// <param name="partialMatch">Indicating whether the search should check for a partial match (true) or a full match (false).</param>
/// <returns>Returns true if the array array contains the specified value; otherwise, false.</returns>
/// <example>
/// <code>
/// <![CDATA[
/// var matched = documents.Where(document => document.Namess.ArrayContains(<itemToMatch>, <partialMatch>));
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Namess

typo

/// // To do a partial match on an array of objects, pass in an anonymous object set partialMatch to true
/// var matched = documents.Where(document => document.ObjectArray.ArrayContains(new { Name = <name> }, true));
/// ]]>
/// </code>
/// </example>
public static bool ArrayContains(this IEnumerable obj, object itemToMatch, bool partialMatch)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ArrayContains

renamed to Contains

{
// The signature for this is not generic so the user can pass in anonymous type for the item to match
// e.g documents.Where(document => document.FooItems.ArrayContains(new { Name = "Bar" }, true)
//
// Has 2 overloads instead of partialMatch with default value (i.e `bool partialMatch = false`) as
// default values cannot be used in expressions (error CS0854), and this method will only be used in expressions
throw new NotImplementedException(ClientResources.TypeCheckExtensionFunctionsNotImplemented);
}

/// <summary>
/// This method generate query definition from LINQ query.
/// </summary>
Expand Down
139 changes: 139 additions & 0 deletions ...selineTest/TestBaseline/LinqTranslationBaselineTests.TestArrayContainsBuiltinFunction.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
<Results>
<Result>
<Input>
<Description><![CDATA[ArrayContains in Select clause with int value]]></Description>
<Expression><![CDATA[query.Select(doc => doc.ArrayField.ArrayContains(Convert(1, Object)))]]></Expression>
</Input>
<Output>
<SqlQuery><![CDATA[
SELECT VALUE ARRAY_CONTAINS(root["ArrayField"], 1)
FROM root]]></SqlQuery> </Output>
</Result>
<Result>
<Input>
<Description><![CDATA[ArrayContains in Filter clause with int value]]></Description>
<Expression><![CDATA[query.Where(doc => doc.ArrayField.ArrayContains(Convert(1, Object)))]]></Expression>
</Input>
<Output>
<SqlQuery><![CDATA[
SELECT VALUE root
FROM root
WHERE ARRAY_CONTAINS(root["ArrayField"], 1)]]></SqlQuery>
</Output>
</Result>
<Result>
<Input>
<Description><![CDATA[ArrayContains in Select clause with object value]]></Description>
<Expression><![CDATA[query.Select(doc => doc.ObjectArrayField.ArrayContains(new AnonymousType(Field = "abc")))]]></Expression>
</Input>
<Output>
<SqlQuery><![CDATA[
SELECT VALUE ARRAY_CONTAINS(root["ObjectArrayField"], {"Field": "abc"})
FROM root]]></SqlQuery>
</Output>
</Result>
<Result>
<Input>
<Description><![CDATA[ArrayContains in Filter clause with object value]]></Description>
<Expression><![CDATA[query.Where(doc => doc.ObjectArrayField.ArrayContains(new AnonymousType(Field = "abc")))]]></Expression>
</Input>
<Output>
<SqlQuery><![CDATA[
SELECT VALUE root
FROM root
WHERE ARRAY_CONTAINS(root["ObjectArrayField"], {"Field": "abc"})]]></SqlQuery>
</Output>
</Result>
<Result>
<Input>
<Description><![CDATA[ArrayContains in Select clause with int value and match partial true]]></Description>
<Expression><![CDATA[query.Select(doc => doc.ArrayField.ArrayContains(Convert(1, Object), True))]]></Expression>
</Input>
<Output>
<SqlQuery><![CDATA[
SELECT VALUE ARRAY_CONTAINS(root["ArrayField"], 1, true)
FROM root]]></SqlQuery>
</Output>
</Result>
<Result>
<Input>
<Description><![CDATA[ArrayContains in Filter clause with int value and match partial true]]></Description>
<Expression><![CDATA[query.Where(doc => doc.ArrayField.ArrayContains(Convert(1, Object), True))]]></Expression>
</Input>
<Output>
<SqlQuery><![CDATA[
SELECT VALUE root
FROM root
WHERE ARRAY_CONTAINS(root["ArrayField"], 1, true)]]></SqlQuery>
</Output>
</Result>
<Result>
<Input>
<Description><![CDATA[ArrayContains in Select clause with object value and match partial true]]></Description>
<Expression><![CDATA[query.Select(doc => doc.ObjectArrayField.ArrayContains(new AnonymousType(Field = "abc"), True))]]></Expression>
</Input>
<Output>
<SqlQuery><![CDATA[
SELECT VALUE ARRAY_CONTAINS(root["ObjectArrayField"], {"Field": "abc"}, true)
FROM root]]></SqlQuery>
</Output>
</Result>
<Result>
<Input>
<Description><![CDATA[ArrayContains in Filter clause with object value and match partial true]]></Description>
<Expression><![CDATA[query.Where(doc => doc.ObjectArrayField.ArrayContains(new AnonymousType(Field = "abc"), True))]]></Expression>
</Input>
<Output>
<SqlQuery><![CDATA[
SELECT VALUE root
FROM root
WHERE ARRAY_CONTAINS(root["ObjectArrayField"], {"Field": "abc"}, true)]]></SqlQuery>
</Output>
</Result>
<Result>
<Input>
<Description><![CDATA[ArrayContains in Select clause with int value and match partial false]]></Description>
<Expression><![CDATA[query.Select(doc => doc.ArrayField.ArrayContains(Convert(1, Object), False))]]></Expression>
</Input>
<Output>
<SqlQuery><![CDATA[
SELECT VALUE ARRAY_CONTAINS(root["ArrayField"], 1, false)
FROM root]]></SqlQuery>
</Output>
</Result>
<Result>
<Input>
<Description><![CDATA[ArrayContains in Filter clause with int value and match partial false]]></Description>
<Expression><![CDATA[query.Where(doc => doc.ArrayField.ArrayContains(Convert(1, Object), False))]]></Expression>
</Input>
<Output>
<SqlQuery><![CDATA[
SELECT VALUE root
FROM root
WHERE ARRAY_CONTAINS(root["ArrayField"], 1, false)]]></SqlQuery>
</Output>
</Result>
<Result>
<Input>
<Description><![CDATA[ArrayContains in Select clause with object value and match partial false]]></Description>
<Expression><![CDATA[query.Select(doc => doc.ObjectArrayField.ArrayContains(new AnonymousType(Field = "abc"), False))]]></Expression>
</Input>
<Output>
<SqlQuery><![CDATA[
SELECT VALUE ARRAY_CONTAINS(root["ObjectArrayField"], {"Field": "abc"}, false)
FROM root]]></SqlQuery>
</Output>
</Result>
<Result>
<Input>
<Description><![CDATA[ArrayContains in Filter clause with object value and match partial false]]></Description>
<Expression><![CDATA[query.Where(doc => doc.ObjectArrayField.ArrayContains(new AnonymousType(Field = "abc"), False))]]></Expression>
</Input>
<Output>
<SqlQuery><![CDATA[
SELECT VALUE root
FROM root
WHERE ARRAY_CONTAINS(root["ObjectArrayField"], {"Field": "abc"}, false)]]></SqlQuery>
</Output>
</Result>
</Results>
34 changes: 34 additions & 0 deletions ...re.Cosmos/tests/Microsoft.Azure.Cosmos.EmulatorTests/Linq/LinqTranslationBaselineTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,7 @@ internal class DataObject : LinqTestObject
#pragma warning disable CS0649 // Field is never assigned to, and will always have its default value false
public bool BooleanField;
public SimpleObject ObjectField = new SimpleObject();
public SimpleObject[] ObjectArrayField = new SimpleObject[0];
public Guid GuidField;
#pragma warning restore // Field is never assigned to, and will always have its default value false

Expand Down Expand Up @@ -346,6 +347,39 @@ public void TestRegexMatchFunction()
this.ExecuteTestSuite(inputs);
}

[TestMethod]
public void TestArrayContainsBuiltinFunction()
{
// Similar to the type checking function, Array_Contains are not supported client side.
// Therefore these methods are verified with baseline only.
List<DataObject> data = new List<DataObject>();
IOrderedQueryable<DataObject> query = testContainer.GetItemLinqQueryable<DataObject>(allowSynchronousQueryExecution: true);
Func<bool, IQueryable<DataObject>> getQuery = useQuery => useQuery ? query : data.AsQueryable();

List<LinqTestInput> inputs = new List<LinqTestInput>
{

new LinqTestInput("ArrayContains in Select clause with int value", b => getQuery(b).Select(doc => doc.ArrayField.ArrayContains(1))),
new LinqTestInput("ArrayContains in Filter clause with int value", b => getQuery(b).Where(doc => doc.ArrayField.ArrayContains(1))),
new LinqTestInput("ArrayContains in Select clause with object value", b => getQuery(b).Select(doc => doc.ObjectArrayField.ArrayContains(new { Field = "abc" }))),
new LinqTestInput("ArrayContains in Filter clause with object value", b => getQuery(b).Where(doc => doc.ObjectArrayField.ArrayContains(new { Field = "abc" }))),

// Same tests, but with 3rd `partialMatch` parameter being true
new LinqTestInput("ArrayContains in Select clause with int value and match partial true", b => getQuery(b).Select(doc => doc.ArrayField.ArrayContains(1, true))),
new LinqTestInput("ArrayContains in Filter clause with int value and match partial true", b => getQuery(b).Where(doc => doc.ArrayField.ArrayContains(1, true))),
new LinqTestInput("ArrayContains in Select clause with object value and match partial true", b => getQuery(b).Select(doc => doc.ObjectArrayField.ArrayContains(new { Field = "abc" }, true))),
new LinqTestInput("ArrayContains in Filter clause with object value and match partial true", b => getQuery(b).Where(doc => doc.ObjectArrayField.ArrayContains(new { Field = "abc" }, true))),

// Same tests, but with 3rd `partialMatch` parameter being false
new LinqTestInput("ArrayContains in Select clause with int value and match partial false", b => getQuery(b).Select(doc => doc.ArrayField.ArrayContains(1, false))),
new LinqTestInput("ArrayContains in Filter clause with int value and match partial false", b => getQuery(b).Where(doc => doc.ArrayField.ArrayContains(1, false))),
new LinqTestInput("ArrayContains in Select clause with object value and match partial false", b => getQuery(b).Select(doc => doc.ObjectArrayField.ArrayContains(new { Field = "abc" }, false))),
new LinqTestInput("ArrayContains in Filter clause with object value and match partial false", b => getQuery(b).Where(doc => doc.ObjectArrayField.ArrayContains(new { Field = "abc" }, false))),
};

this.ExecuteTestSuite(inputs);
}

[TestMethod]
public void TestMemberInitializer()
{
Expand Down
3 changes: 3 additions & 0 deletions ...os/tests/Microsoft.Azure.Cosmos.EmulatorTests/Microsoft.Azure.Cosmos.EmulatorTests.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,9 @@
<Content Include="BaselineTest\TestBaseline\IndexMetricsParserBaselineTest.IndexUtilizationHeaderLengthTest.xml">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</Content>
<Content Include="BaselineTest\TestBaseline\LinqTranslationBaselineTests.TestArrayContainsBuiltinFunction.xml">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</Content>
<Content Include="BaselineTest\TestBaseline\QueryAdvisorBaselineTest.QueryAdviceParse.xml">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</Content>
Expand Down
14 changes: 14 additions & 0 deletions Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/Contracts/DotNetSDKAPI.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6009,6 +6009,20 @@
"Microsoft.Azure.Cosmos.Linq.CosmosLinqExtensions;System.Object;IsAbstract:True;IsSealed:True;IsInterface:False;IsEnum:False;IsClass:True;IsValueType:False;IsNested:False;IsGenericType:False;IsSerializable:False": {
"Subclasses": {},
"Members": {
"Boolean ArrayContains(System.Collections.IEnumerable, System.Object, Boolean)[System.Runtime.CompilerServices.ExtensionAttribute()]": {
"Type": "Method",
"Attributes": [
"ExtensionAttribute"
],
"MethodInfo": "Boolean ArrayContains(System.Collections.IEnumerable, System.Object, Boolean);IsAbstract:False;IsStatic:True;IsVirtual:False;IsGenericMethod:False;IsConstructor:False;IsFinal:False;"
},
"Boolean ArrayContains(System.Collections.IEnumerable, System.Object)[System.Runtime.CompilerServices.ExtensionAttribute()]": {
"Type": "Method",
"Attributes": [
"ExtensionAttribute"
],
"MethodInfo": "Boolean ArrayContains(System.Collections.IEnumerable, System.Object);IsAbstract:False;IsStatic:True;IsVirtual:False;IsGenericMethod:False;IsConstructor:False;IsFinal:False;"
},
"Boolean IsArray(System.Object)[System.Runtime.CompilerServices.ExtensionAttribute()]": {
"Type": "Method",
"Attributes": [
Expand Down