FIELDENG-681 adding api for running raw queries (#523)

adding api for running raw queries

Author: slorello89

README.md

@@ -315,6 +315,44 @@ customers.Where(x => x.LastName == "Bond" && x.FirstName == "James");
 customers.Where(x=>x.NickNames.Contains("Jim"));
 ```
 
+#### Using Raw Queries
+
+For advanced scenarios where you need direct control over the filter syntax, Redis OM provides a Raw extension method that lets you write the query filter using the Redis Search query syntax directly:
+
+```csharp
+// Use raw query to find customers named Bond with exact tag matching
+var results = customers.Raw("@LastName:{Bond}").ToList();
+```
+
+**Important**: The Raw method ONLY sets the filter portion of the query. For all other query parameters such as sorting, pagination, etc., you should continue to use the LINQ methods:
+
+```csharp
+// Raw for filter + OrderBy for sorting
+var results = customers.Raw("@LastName:{Bond}")
+    .OrderBy(c => c.Age)
+    .ToList();
+
+// Raw for filter + Skip/Take for pagination
+var results = customers.Raw("@Age:[30 70]")
+    .Skip(10)
+    .Take(5)
+    .ToList();
+```
+
+This is also true for aggregations, where Raw only sets the initial filter, and you should use the full aggregation API for the rest of the pipeline:
+
+```csharp
+var aggSet = customers.AggregationSet();
+
+// Raw sets ONLY the filter, then use the aggregation API for operations
+var results = aggSet.Raw("@Age:[30 70]")
+    .GroupBy(x => x.RecordShell.LastName)
+    .Average(x => x.RecordShell.Age)
+    .ToList();
+```
+
+For more details on the Redis Search query syntax for filters, refer to the [RediSearch Query Syntax Documentation](https://redis.io/docs/stack/search/reference/query_syntax/).
+
 ### Vectors
 
 Redis OM .NET also supports storing and querying Vectors stored in Redis. 

examples/Redis.OM.RawQueryExample/Program.cs

@@ -0,0 +1,94 @@
+using Redis.OM;
+using Redis.OM.Modeling;
+using Redis.OM.Searching;
+using System;
+
+namespace Redis.OM.RawQueryExample
+{
+    [Document(StorageType = StorageType.Json, IndexName = "person-idx")]
+    public class Person
+    {
+        [RedisIdField]
+        [Indexed]
+        public string Id { get; set; } = Ulid.NewUlid().ToString();
+
+        [Indexed]
+        public string FirstName { get; set; }
+
+        [Indexed]
+        public string LastName { get; set; }
+
+        [Searchable]
+        public string FullText { get; set; }
+        
+        [Indexed(Sortable = true)]
+        public int Age { get; set; }
+
+        [Indexed]
+        public string[] Skills { get; set; }
+    }
+
+    class Program
+    {
+        static void Main(string[] args)
+        {
+            var provider = new RedisConnectionProvider("redis://localhost:6379");
+            var connection = provider.Connection;
+
+            // Create index if it doesn't exist
+            connection.CreateIndex(typeof(Person));
+
+            // Add some sample data
+            var collection = provider.RedisCollection<Person>();
+            
+            if (!collection.Any())
+            {
+                collection.Insert(new Person { FirstName = "John", LastName = "Doe", Age = 30, Skills = new[] { "C#", "Redis" }, FullText = "Hey Now Brown Cow"});
+                collection.Insert(new Person { FirstName = "Jane", LastName = "Smith", Age = 28, Skills = new[] { "Java", "MongoDB", "Redis" } });
+                collection.Insert(new Person { FirstName = "Bob", LastName = "Johnson", Age = 35, Skills = new[] { "Python", "Redis", "AWS" } });
+                collection.Insert(new Person { FirstName = "Alice", LastName = "Williams", Age = 32, Skills = new[] { "JavaScript", "Node.js" } });
+            }
+
+            Console.WriteLine("=== Using standard LINQ expression ===");
+            var linqResult = collection.Where(p => p.Age > 30).ToList();
+            PrintResults(linqResult);
+
+            Console.WriteLine("\n=== Using Raw query expression ===");
+            var rawResult = collection.Raw("@Age:[31 +inf]").ToList();
+            PrintResults(rawResult);
+
+            Console.WriteLine("\n=== Using Raw query for tag search ===");
+            var skillsResult = collection.Raw("@Skills:{Redis}").ToList();
+            PrintResults(skillsResult);
+
+            Console.WriteLine("\n=== Using Raw query with complex conditions ===");
+            var complexResult = collection.Raw("@Age:[30 35] @Skills:{Redis}").ToList();
+            PrintResults(complexResult);
+
+            // Using Raw with AggregationSet properly
+            Console.WriteLine("\n=== Using Raw with AggregationSet ===");
+            
+            // The proper way - Raw only sets the filter part, then use regular aggregation API
+            var aggSet = provider.AggregationSet<Person>();
+            var aggregationResult = aggSet.Raw("*")
+                .GroupBy(x => x.RecordShell.Skills)
+                .CountGroupMembers()
+                .ToList();
+            
+            Console.WriteLine("Skills grouped by count:");
+            foreach (var result in aggregationResult)
+            {
+                Console.WriteLine($"Skill: {result["Skills"]}, Count: {result["COUNT"]}");
+            }
+        }
+
+        static void PrintResults(System.Collections.Generic.IEnumerable<Person> results)
+        {
+            foreach (var person in results)
+            {
+                Console.WriteLine($"{person.FirstName} {person.LastName}, Age: {person.Age}, Skills: {string.Join(", ", person.Skills)}");
+            }
+            Console.WriteLine($"Total results: {results.Count()}");
+        }
+    }
+}

examples/Redis.OM.RawQueryExample/Redis.OM.RawQueryExample.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net6.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Redis.OM\Redis.OM.csproj" />
+    <PackageReference Include="Ulid" Version="1.2.6" />
+  </ItemGroup>
+
+</Project>

src/Redis.OM/Aggregation/RedisAggregation.cs

@@ -43,6 +43,11 @@ public RedisAggregation(string indexName)
         /// </summary>
         public Stack<IAggregationPredicate> Predicates { get; } = new ();
 
+        /// <summary>
+        /// Gets or sets the raw query string for direct execution.
+        /// </summary>
+        public string? RawQuery { get; set; }
+
         /// <summary>
         /// serializes the aggregation into an array of arguments for redis.
         /// </summary>
@@ -51,7 +56,11 @@ public string[] Serialize()
         {
             var queries = new List<string>();
             var ret = new List<string>() { IndexName };
-            if (Queries.Any())
+            if (!string.IsNullOrEmpty(RawQuery))
+            {
+                ret.Add(RawQuery!);
+            }
+            else if (Queries.Any())
             {
                 foreach (var query in Queries)
                 {

src/Redis.OM/Common/ExpressionTranslator.cs

@@ -161,6 +161,10 @@ public static RedisAggregation BuildAggregationFromExpression(Expression express
                     case "LoadAll":
                         aggregation.Predicates.Push(new LoadAll());
                         break;
+                    case "Raw":
+                        var rawQuery = ((ConstantExpression)exp.Arguments[1]).Value.ToString();
+                        aggregation.RawQuery = rawQuery;
+                        break;
                 }
             }
 
@@ -188,6 +192,7 @@ internal static RedisQuery BuildQueryFromExpression(Expression expression, Type
             var indexName = string.IsNullOrEmpty(attr.IndexName) ? $"{type.Name.ToLower()}-idx" : attr.IndexName;
             var query = new RedisQuery(indexName!) { QueryText = "*" };
             var dialect = 1;
+            string? rawQuery = null;  // Store the raw query string if one is encountered
             switch (expression)
             {
                 case MethodCallExpression methodExpression:
@@ -230,12 +235,35 @@ internal static RedisQuery BuildQueryFromExpression(Expression expression, Type
                                 query.GeoFilter = ExpressionParserUtilities.TranslateGeoFilter(exp);
                                 break;
                             case "Where":
-                                query.QueryText = query.QueryText == "*" ? TranslateWhereMethod(exp, parameters, ref dialect) : $"({TranslateWhereMethod(exp, parameters, ref dialect)} {query.QueryText})";
+                                // Combine Where clause with existing query
+                                var whereClause = TranslateWhereMethod(exp, parameters, ref dialect);
+                                query.QueryText = query.QueryText == "*" ?
+                                    whereClause :
+                                    $"({whereClause} {query.QueryText})";
                                 query.Dialect = dialect;
                                 break;
                             case "NearestNeighbors":
                                 query.NearestNeighbors = ParseNearestNeighborsFromExpression(exp);
                                 break;
+                            case "Raw":
+                                // Get the current raw query
+                                var currentRawQuery = ((ConstantExpression)exp.Arguments[1]).Value.ToString();
+
+                                // If we've seen a raw query before, combine them
+                                if (rawQuery != null)
+                                {
+                                    rawQuery = $"({rawQuery} {currentRawQuery})";
+                                }
+                                else
+                                {
+                                    rawQuery = currentRawQuery;
+                                }
+
+                                // Set the query text appropriately
+                                query.QueryText = query.QueryText == "*" ?
+                                    rawQuery :
+                                    $"({query.QueryText} {rawQuery})";
+                                break;
                         }
                     }
 
@@ -251,7 +279,20 @@ internal static RedisQuery BuildQueryFromExpression(Expression expression, Type
             if (mainBooleanExpression != null)
             {
                 parameters = new List<object>();
-                query.QueryText = BuildQueryFromExpression(((LambdaExpression)mainBooleanExpression).Body, parameters, ref dialect);
+                var booleanExpressionQuery = BuildQueryFromExpression(((LambdaExpression)mainBooleanExpression).Body, parameters, ref dialect);
+
+                // If we have a raw query, make sure to preserve it
+                if (rawQuery != null)
+                {
+                    // Combine the boolean expression with the raw query
+                    query.QueryText = $"({booleanExpressionQuery} {rawQuery})";
+                }
+                else
+                {
+                    // No raw query, just use the boolean expression
+                    query.QueryText = booleanExpressionQuery;
+                }
+
                 query.Dialect = dialect;
             }
 

src/Redis.OM/SearchExtensions.cs

@@ -14,6 +14,40 @@ namespace Redis.OM
     /// </summary>
     public static class SearchExtensions
     {
+        /// <summary>
+        /// Executes a raw search query string directly against Redis.
+        /// </summary>
+        /// <param name="source">The source collection.</param>
+        /// <param name="rawQuery">Raw query string to be used directly in Redis search.</param>
+        /// <typeparam name="T">The indexed type.</typeparam>
+        /// <returns>A Redis Collection with the raw query expression applied.</returns>
+        public static IRedisCollection<T> Raw<T>(this IRedisCollection<T> source, string rawQuery)
+            where T : notnull
+        {
+            var collection = (RedisCollection<T>)source;
+            var exp = Expression.Call(
+                null,
+                GetMethodInfo(Raw, source, rawQuery),
+                new[] { source.Expression, Expression.Constant(rawQuery) });
+            return new RedisCollection<T>((RedisQueryProvider)source.Provider, exp, source.StateManager, collection.BooleanExpression, source.SaveState, source.ChunkSize);
+        }
+
+        /// <summary>
+        /// Executes a raw aggregation query string directly against Redis.
+        /// </summary>
+        /// <param name="source">The source aggregation set.</param>
+        /// <param name="rawQuery">Raw query string to be used directly in Redis aggregation.</param>
+        /// <typeparam name="T">The indexed type.</typeparam>
+        /// <returns>A Redis AggregationSet with the raw query expression applied.</returns>
+        public static RedisAggregationSet<T> Raw<T>(this RedisAggregationSet<T> source, string rawQuery)
+        {
+            var exp = Expression.Call(
+                null,
+                GetMethodInfo(Raw, source, rawQuery),
+                new[] { source.Expression, Expression.Constant(rawQuery) });
+            return new RedisAggregationSet<T>(source, exp);
+        }
+
         /// <summary>
         /// Apply the provided expression to data in Redis.
         /// </summary>

test/Redis.OM.Unit.Tests/RediSearchTests/AggregationFunctionalTests.cs

@@ -1,9 +1,11 @@
 using System;
 using System.Collections.Generic;
+using System.Globalization;
 using Redis.OM.Aggregation;
 using Redis.OM.Contracts;
 using System.Threading.Tasks;
 using System.Linq;
+using Redis.OM.Searching;
 using Xunit;
 
 namespace Redis.OM.Unit.Tests.RediSearchTests
@@ -320,5 +322,42 @@ public async Task TestListNotContains()
             Assert.Contains(people, x => x.Hydrate().Name == "Statler");
             Assert.DoesNotContain(people, x => x.Hydrate().Name == "Beaker");
         }
+        
+        [Fact]
+        public void TestRawAggregationQuery()
+        {
+            Setup();
+            var aggSet = new RedisAggregationSet<Person>(_connection);
+            
+            
+            // Test raw query with aggregation operations
+            // Raw sets only the filter part (*), then we use proper aggregation API
+            var result = aggSet.Raw("@DepartmentNumber:[1 2]")
+                .GroupBy(x => x.RecordShell.DepartmentNumber)
+                .Average(x => x.RecordShell.Age)
+                .ToList();
+            
+            // Verify results
+            Assert.Equal(2, result.Count);
+            
+            var dept1 = result.FirstOrDefault(r => r["DepartmentNumber"].ToString() == "1");
+            var dept2 = result.FirstOrDefault(r => r["DepartmentNumber"].ToString() == "2");
+            
+            Assert.NotNull(dept1);
+            Assert.NotNull(dept2);
+            
+            // Check average ages (converting to double for comparison)
+            Assert.True(Math.Abs(52.0 - double.Parse(dept1["Age_AVG"].ToString(CultureInfo.InvariantCulture))) < 0.01);
+            Assert.True(Math.Abs(45.0 - double.Parse(dept2["Age_AVG"].ToString(CultureInfo.InvariantCulture))) < 0.01);
+            
+            // Test complex filter with aggregation operations
+            // Raw sets only the filter part (@Age > 30), then we use proper aggregation API
+            var complexResult = aggSet.Raw("@Age:[30 inf]")
+                .GroupBy(x => x.RecordShell.DepartmentNumber)
+                .CountGroupMembers()
+                .ToList();
+            
+            Assert.Equal(4, complexResult.Count);
+        }
     }
 }