Add .Explain() extension method to IQueryable<T> to explain Linq queries.

The extension method operates on IQueryable<T> and can therefore not operate
on .Max, Min, First, Last or any methods that return a scalar. It can also
not operate on .Distinct queries since they call a specific method on the
collection and don't give us access to any cursor.

Author: Einar Egilsson

DriverUnitTests/Linq/ExplainTests.cs

@@ -0,0 +1,78 @@
+???/* Copyright 2010-2012 10gen Inc.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+using System;
+using System.Linq;
+using NUnit.Framework;
+
+using MongoDB.Bson;
+using MongoDB.Driver;
+using MongoDB.Driver.Builders;
+using MongoDB.Driver.Linq;
+
+namespace MongoDB.DriverUnitTests.Linq
+{
+    [TestFixture]
+    public class ExplainTests
+    {
+        private class C
+        {
+            public ObjectId Id { get; set; }
+            public int X { get; set; }
+            public int Y { get; set; }
+        }
+
+        private MongoServer _server;
+        private MongoCollection _collection;
+
+        [TestFixtureSetUp]
+        public void Setup()
+        {
+            _server = Configuration.TestServer;
+            _server.Connect();
+            _collection = Configuration.TestCollection;
+        }
+
+        [Test]
+        public void TestExplainFromLinqQueryEqualsExplainFromCursor()
+        {
+            var linqExplain = _collection.AsQueryable<C>().Where(c => c.X == 2 && c.Y == 1).Take(1).Explain();
+            var queryExplain =
+                _collection.FindAs<C>(Query.And(Query.EQ("X", 2), Query.EQ("Y", 1))).SetLimit(1).Explain();
+            Assert.AreEqual(linqExplain, queryExplain);
+        }
+
+        [Test]
+        public void TestVerboseExplainFromLinqQueryEqualsVerboseExplainFromCursor()
+        {
+            var linqExplain = _collection.AsQueryable<C>().Where(c => c.X == 2 && c.Y == 1).Take(1).Explain(true);
+            var queryExplain =
+                _collection.FindAs<C>(Query.And(Query.EQ("X", 2), Query.EQ("Y", 1))).SetLimit(1).Explain(true);
+            Assert.AreEqual(linqExplain, queryExplain);
+        }
+
+        [Test]
+        public void TestDistinctQueryCannotBeExplained()
+        {
+            Assert.Throws<NotSupportedException>(()=> _collection.AsQueryable<C>().Select(c=>c.X).Distinct().Explain());
+        }
+
+        [Test]
+        public void TestTakeZeroQueriesCannotBeExplained()
+        {
+            Assert.Throws<NotSupportedException>(() => _collection.AsQueryable<C>().Take(0).Explain());
+        }
+    }
+}

MongoDB.Driver/Linq/LinqToMongo.cs

@@ -1,4 +1,4 @@
-/* Copyright 2010-2013 10gen Inc.
+/* Copyright 2010-2012 10gen Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -16,6 +16,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using MongoDB.Bson;
 
 namespace MongoDB.Driver.Linq
 {
@@ -48,6 +49,7 @@ public static bool ContainsAny<TSource>(this IEnumerable<TSource> source, IEnume
             return source.Any(s => values.Contains(s));
         }
 
+
         /// <summary>
         /// Determines whether a specified value is contained in a sequence.
         /// </summary>
@@ -69,5 +71,38 @@ public static bool Inject(this IMongoQuery query)
         {
             throw new InvalidOperationException("The LinqToMongo.Inject method is only intended to be used in LINQ Where clauses.");
         }
+
+        /// <summary>
+        /// Returns an explanation of how the query was executed (instead of the results).
+        /// </summary>
+        /// <param name="query">The LINQ query to explain</param>
+        /// <returns>An explanation of thow the query was executed.</returns>
+        public static BsonDocument Explain<T>(this IQueryable<T> query)
+        {
+            return Explain(query, false);
+        }
+
+        /// <summary>
+        /// Returns an explanation of how the query was executed (instead of the results).
+        /// </summary>
+        /// <param name="query">The LINQ query to explain</param>
+        /// <param name="verbose">Whether the explanation should contain more details.</param>
+        /// <returns>An explanation of thow the query was executed.</returns>
+        public static BsonDocument Explain<T>(this IQueryable<T> query, bool verbose)
+        {
+            var selectQuery = (SelectQuery)MongoQueryTranslator.Translate(query);
+            if (selectQuery.Take.HasValue && selectQuery.Take.Value == 0)
+            {
+                throw new NotSupportedException("A query that has a .Take(0) expression will not be sent to the server and can't be explained");
+            }
+            var projector = selectQuery.Execute() as IProjector;
+            if (projector == null)
+            {
+                //This is mainly for .Distinct() queries. First, Last, FirstOrDefault, LastOrDefault don't return
+                //IQueryable<T>, so .Explain() can't be called on them anyway.
+                throw new NotSupportedException("Explain can only be called on Linq queries that return an IProjector");
+            }
+            return projector.Cursor.Explain(verbose);
+        }
     }
 }

MongoDB.DriverUnitTests/MongoDB.DriverUnitTests.csproj

@@ -184,6 +184,7 @@
     <Compile Include="Jira\CSharp93Tests.cs" />
     <Compile Include="Jira\CSharp98Tests.cs" />
     <Compile Include="Jira\CSharp100Tests.cs" />
+    <Compile Include="Linq\ExplainTests.cs" />
     <Compile Include="Linq\SelectDictionaryTests.cs" />
     <Compile Include="Linq\SelectNullableTests.cs" />
     <Compile Include="Linq\SelectOfTypeHierarchicalTests.cs" />