V4.0 Geo Spatial Search Support

docs/articles/filtering.md

@@ -0,0 +1,245 @@
+---
+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();
+```
+
+## Spatial
+
+Examine supports Spatial Filtering.
+The Examine.Lucene.Spatial package needs to be installed.
+
+### Spatial Operations
+
+Below are the available Spatial Operations in Examine that are supported by the Examine.Lucene.Spatial package. Available operations may vary by provider.
+
+- ExamineSpatialOperation.Intersects
+- ExamineSpatialOperation.Overlaps
+- ExamineSpatialOperation.IsWithin
+- ExamineSpatialOperation.BoundingBoxIntersects
+- ExamineSpatialOperation.BoundingBoxWithin
+- ExamineSpatialOperation.Contains
+- ExamineSpatialOperation.IsDisjointTo
+- ExamineSpatialOperation.IsEqualTo
+
+### Spatial Filtering
+
+The `.SpatialOperationFilter()` method adds a filter to the query results to remove any results that do not pass the filter.
+The example below demonstrates filtering results where the shape stored in the "spatialWKT" field must intersect the rectangle defined.
+
+```csharp
+var query = searcher.CreateQuery()
+                .WithFilter(
+                        filter => filter.SpatialOperationFilter("spatialWKT", ExamineSpatialOperation.Intersects, (shapeFactory) => shapeFactory.CreateRectangle(0.0, 1.0, 0.0, 1.0))
+                );
+```
+
+## 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/indexing.md

@@ -137,6 +137,34 @@ Data is easily deleted from the index by the unique identifier you provided in y
  indexer.DeleteFromIndex("SKU987");
 ```
 
+### Indexing Spatial Shapes
+
+For the Lucene Provider, the package Examine.Lucene.Spatial must be installed.
+
+As you can see, the values being passed into the ValueSet are type `IExamineSpatialShape` created using the `IExamineSpatialShapeFactory` retrieved from the ValueType of the field. A [field definition](configuration#custom-field-definitions) must be set.
+
+Example for Geo Spatial field storing WKT:
+
+```cs
+{FieldDefinitionTypes.GeoSpatialWKT, name => new WKTSpatialIndexFieldValueType(name, loggerFactory, SpatialIndexFieldValueTypeBase.GeoSpatialPrefixTreeStrategyFactory(),true)},
+```
+Indexing example:
+
+```cs
+var geoSpatialFieldType = myIndex.FieldValueTypeCollection.ValueTypes.First(f
+                    => f.FieldName.Equals("spatialWKT", StringComparison.InvariantCultureIgnoreCase)) as ISpatialIndexFieldValueTypeShapesBase;
+
+var fieldShapeFactory = geoSpatialFieldType.ExamineSpatialShapeFactory;
+
+  myIndex.IndexItem(
+    ValueSet.FromObject(1.ToString(), "content",
+      new { 
+        nodeName = "my name 1", 
+      updateDate = now.AddDays(2).ToString("yyyy-MM-dd"), 
+      spatialWKT = fieldShapeFactory.CreatePoint(0.0,0.0) })
+    );
+```
+
 ## Events
 
 #### [IIndex.IndexOperationComplete](xref:Examine.IIndex#Examine_IIndex_IndexOperationComplete)

docs/articles/sorting.md

@@ -42,3 +42,24 @@ var orderedDescendingResults = searcher
    .OrderByDescending(new SortableField("name", SortType.String))
    .Execute();
 ```
+
+## Spatial Sorting
+
+Example order by distance from a Point.
+
+```cs
+ // Retrieve the Shape Factory from the field
+ var geoSpatialFieldType = myIndex.FieldValueTypeCollection.ValueTypes.First(f
+                    => f.FieldName.Equals("spatialWKT", StringComparison.InvariantCultureIgnoreCase)) as ISpatialIndexFieldValueTypeBase;
+
+var fieldShapeFactory = geoSpatialFieldType.ExamineSpatialShapeFactory;
+
+// Define the location to compare against
+var searchLocation = fieldShapeFactory.CreatePoint(0.0, 0.0);
+
+// Order by the distance between the center of the Shape in the "spatialWKT" vs the search location, Ascending.
+var orderedDescendingResults = searcher
+   .CreateQuery("content")
+   .OrderBy(new SortableField("spatialWKT", searchLocation))
+   ).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

docs/docs-v1-v2/searching.md

@@ -248,4 +248,4 @@ var query = searcher.CreateQuery();
 var query = (LuceneSearchQuery)query.NativeQuery("hello:world").And(); // Make query ready for extending
 query.LuceneQuery(NumericRangeQuery.NewInt64Range("numTest", 4, 5, true, true)); // Add the raw lucene query
 var results = query.Execute();
-```
+```

docs/docs-v1-v2/sorting.md

@@ -41,8 +41,17 @@ var orderedDescendingResults = searcher
    .Field("writerName", "administrator")
    .OrderByDescending(new SortableField("name", SortType.String))
    .Execute();
+
+// Mixing ascending and descending
+var orderedDescendingResults = searcher
+   .CreateQuery("content")
+   .Field("writerName", "administrator")
+      .OrderByDescending(new SortableField("name", SortType.String)),
+      .OrderBy(new SortableField("date", SortType.String))
+      .Execute();
 ```
 
+
 ## Limiting results
 
 To limit results we can use the `QueryOptions` class when executing a search query. The `QueryOptions` class provides the ability to skip and take.

src/Examine.Core/FieldDefinitionTypes.cs

@@ -13,10 +13,16 @@ public static class FieldDefinitionTypes
         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>
@@ -203,5 +209,11 @@ public static class FieldDefinitionTypes
         public const string FacetTaxonomyFullTextSortable = "facettaxonomyfulltextsortable";
 
 
+
+        /// <summary>
+        /// GEO Spatial Shape. Index as WKT
+        /// </summary>
+        public const string GeoSpatialWKT = "spatial.geo.wkt";
+
     }
 }

src/Examine.Core/ISpatialIndexFieldValueTypeShapesBase.cs

@@ -0,0 +1,15 @@
+using Examine.Search;
+
+namespace Examine
+{
+    /// <summary>
+    /// Spatial Index Field Value Type Shape Factory
+    /// </summary>
+    public interface ISpatialIndexFieldValueTypeShapesBase
+    {
+        /// <summary>
+        /// Gets the Shape Factory for the fields spatial strategy
+        /// </summary>
+        IExamineSpatialShapeFactory ExamineSpatialShapeFactory { get; }
+    }
+}