V4.0 Filter Support

docs/articles/filtering.md

@@ -0,0 +1,215 @@
+---
+title: Filtering
+permalink: /filtering
+uid: filtering
+order: 3
+---
+Filtering
+===
+
+_**Tip**: There are many examples of filtering in the [`FluentApiTests` source code](https://github.com/Shazwazza/Examine/blob/release/3.0/src/Examine.Test/Examine.Lucene/Search/FluentApiTests.cs) to use as examples/reference._
+
+## Common
+
+Obtain an instance of [`ISearcher`](xref:Examine.ISearcher) for the index to be searched from [`IExamineManager`](xref:Examine.IExamineManager).
+
+### Terms and Phrases
+
+When filtering on fields like in the example above you might want to search on more than one word/term. In Examine this can be done by simply adding more terms to the term filter.
+
+### Term Filter
+
+```csharp
+var searcher = myIndex.Searcher;
+var results = searcher.CreateQuery()
+  // Look for any addresses that has "Hills" or "Rockyroad" or "Hollywood"
+   .WithFilter(
+     filter =>
+     {
+         filter.TermFilter(new FilterTerm("Address", "Hills Rockyroad Hollywood"));
+     })
+     .All()
+ .Execute();
+```
+
+### Terms Filter
+
+```csharp
+var searcher = myIndex.Searcher;
+var results = searcher.CreateQuery()
+  // Look for any addresses that has "Hills" or "Rockyroad" or "Hollywood"
+   .WithFilter(
+     filter =>
+     {
+         filter.TermsFilter(new[] {new FilterTerm("Address", "Hills"), new FilterTerm("Address", "Rockyroad"), new FilterTerm("Address", "Hollywood") });
+     })
+     .All()
+ .Execute();
+```
+
+### Term Prefix Filter
+
+```csharp
+var searcher = myIndex.Searcher;
+var results = searcher.CreateQuery()
+  // Look for any addresses that starts with "Hills"
+   .WithFilter(
+     filter =>
+     {
+         filter.TermPrefixFilter(new FilterTerm("Address", "Hills"));
+     })
+     .All()
+ .Execute();
+```
+
+## Range Filters
+
+Range Filters allow one to match documents whose field(s) values are between the lower and upper bound specified by the Range Filter
+
+### Int Range
+
+Example:
+
+```csharp
+var searcher = myIndex.Searcher;
+var query = searcher.CreateQuery();
+ query.WithFilter(
+     filter =>
+     {
+         filter.IntRangeFilter("SomeInt", 0, 100, minInclusive: true, maxInclusive: true);
+     }).All();
+var results = query.Execute(QueryOptions.Default);
+```
+
+This will return results where the field `SomeInt` is within the range 0 - 100 (min value and max value included).
+
+### Long Range
+
+Example:
+
+```csharp
+var searcher = myIndex.Searcher;
+var query = searcher.CreateQuery();
+ query.WithFilter(
+     filter =>
+     {
+         filter.LongRangeFilter("SomeLong", 0, 100, minInclusive: true, maxInclusive: true);
+     }).All();
+var results = query.Execute(QueryOptions.Default);
+```
+
+This will return results where the field `SomeLong` is within the range 0 - 100 (min value and max value included).
+
+### Float Range
+
+Example:
+
+```csharp
+var searcher = myIndex.Searcher;
+var query = searcher.CreateQuery();
+ query.WithFilter(
+     filter =>
+     {
+         filter.FloatRangeFilter("SomeFloat", 0f, 100f, minInclusive: true, maxInclusive: true);
+     }).All();
+var results = query.Execute(QueryOptions.Default);
+```
+
+This will return results where the field `SomeFloat` is within the range 0 - 100 (min value and max value included).
+
+### Double Range
+
+Example:
+
+```csharp
+var searcher = myIndex.Searcher;
+var query = searcher.CreateQuery();
+ query.WithFilter(
+     filter =>
+     {
+         filter.FloatRangeFilter("SomeDouble", 0.0, 100.0, minInclusive: true, maxInclusive: true);
+     }).All();
+var results = query.Execute(QueryOptions.Default);
+```
+
+This will return results where the field `SomeDouble` is within the range 0 - 100 (min value and max value included).
+
+## Booleans
+
+### Or
+
+```csharp
+var searcher = myIndex.Searcher;
+var results = searcher.CreateQuery()
+  // Look for any addresses that start with "Hills" or "Valleys"
+   .WithFilter(
+     filter =>
+     {
+         filter.TermPrefixFilter(new FilterTerm("Address", "Hills"))
+         .OrFilter()
+         filter.TermPrefixFilter(new FilterTerm("Address", "Valleys"));
+     })
+     .All()
+ .Execute();
+```
+
+### And
+
+```csharp
+var searcher = myIndex.Searcher;
+var results = searcher.CreateQuery()
+  // Look for any addresses that has "Hills" and keyword "Examine"
+   .WithFilter(
+     filter =>
+     {
+         filter.TermFilter(new FilterTerm("Address", "Hills"))
+         .AndFilter()
+         filter.TermFilter(new FilterTerm("Keyword", "Examine"));
+     })
+     .All()
+ .Execute();
+```
+
+### Not
+
+```csharp
+var searcher = myIndex.Searcher;
+var results = searcher.CreateQuery()
+  // Look for any addresses that has "Hills" and keyword "Examine"
+   .WithFilter(
+     filter =>
+     {
+         filter.TermFilter(new FilterTerm("Address", "Hills"))
+         .NotFilter()
+         filter.TermFilter(new FilterTerm("Keyword", "Examine"));
+     })
+     .All()
+ .Execute();
+```
+
+### And Not
+
+```csharp
+var searcher = myIndex.Searcher;
+var results = searcher.CreateQuery()
+  // Look for any addresses that has "Hills" and not keyword "Examine"
+   .WithFilter(
+     filter =>
+     {
+         filter.TermFilter(new FilterTerm("Address", "Hills"))
+         .AndNotFilter(innerFilter => innerFilter.TermFilter(new FilterTerm("Keyword", "Examine")));
+     })
+     .All()
+ .Execute();
+```
+
+### Custom lucene filter
+
+```csharp
+var searcher = indexer.Searcher;
+var query = searcher.CreateQuery();
+
+var query = (LuceneSearchQuery)query.NativeQuery("hello:world").And(); // Make query ready for extending
+query.LuceneFilter(new TermFilter(new Term("nodeTypeAlias", "CWS_Home"))); // Add the raw lucene query
+var results = query.Execute();
+```

docs/articles/toc.yml

@@ -4,6 +4,8 @@
   href: indexing.md
 - name: Searching
   href: searching.md
+- name: Filtering
+  href: filtering.md
 - name: Sorting
   href: sorting.md
 - name: Paging

src/Examine.Core/FieldDefinitionTypes.cs

@@ -13,10 +13,16 @@
         public const string Integer = "int";
 
         /// <summary>
-        /// Will be indexed as a float
+        /// Will be indexed as a single
         /// </summary>
         public const string Float = "float";
 
+        /// <summary>
+        /// Will be indexed as a single
+        /// </summary>
+        [Obsolete("To remove in Examine V5. Use Float")]
+        public const string Single = "single";
+
         /// <summary>
         /// Will be indexed as a double
         /// </summary>

src/Examine.Core/Search/FilterTerm.cs

@@ -0,0 +1,30 @@
+namespace Examine.Search
+{
+    /// <summary>
+    /// Term
+    /// </summary>
+    public struct FilterTerm
+    {
+        /// <summary>
+        /// Name of the Field
+        /// </summary>
+        public string FieldName { get; }
+
+        /// <summary>
+        /// Value of the Term
+        /// </summary>
+        public string FieldValue { get; }
+
+        /// <summary>
+        /// Constructor
+        /// </summary>
+        /// <param name="fieldName">Name of the Field</param>
+        /// <param name="fieldValue">Value of the Term</param>
+        public FilterTerm(string fieldName, string fieldValue)
+        {
+            FieldName = fieldName;
+            FieldValue = fieldValue;
+        }
+
+    }
+}

src/Examine.Core/Search/IBooleanFilterOperation.cs

@@ -0,0 +1,49 @@
+using System;
+
+namespace Examine.Search
+{
+    public interface IBooleanFilterOperation
+    {
+        /// <summary>
+        /// Sets the next operation to be AND
+        /// </summary>
+        /// <returns></returns>
+        IFilter AndFilter();
+
+        /// <summary>
+        /// Adds the nested filter
+        /// </summary>
+        /// <param name="inner"></param>
+        /// <param name="defaultOp"></param>
+        /// <returns></returns>
+        IBooleanFilterOperation AndFilter(Func<INestedFilter, INestedBooleanFilterOperation> inner, BooleanOperation defaultOp = BooleanOperation.And);
+
+        /// <summary>
+        /// Sets the next operation to be OR
+        /// </summary>
+        /// <returns></returns>
+        IFilter OrFilter();
+
+        /// <summary>
+        /// Adds the nested filter
+        /// </summary>
+        /// <param name="inner"></param>
+        /// <param name="defaultOp"></param>
+        /// <returns></returns>
+        IBooleanFilterOperation OrFilter(Func<INestedFilter, INestedBooleanFilterOperation> inner, BooleanOperation defaultOp = BooleanOperation.And);
+
+        /// <summary>
+        /// Sets the next operation to be NOT
+        /// </summary>
+        /// <returns></returns>
+        IFilter NotFilter();
+
+        /// <summary>
+        /// Adds the nested filter
+        /// </summary>
+        /// <param name="inner"></param>
+        /// <param name="defaultOp"></param>
+        /// <returns></returns>
+        IBooleanFilterOperation AndNotFilter(Func<INestedFilter, INestedBooleanFilterOperation> inner, BooleanOperation defaultOp = BooleanOperation.And);
+    }
+}