Distributed Lucene Geo-Spatial API

Note

This feature is available for NCache Enterprise edition only.

Distributed Lucene supports indexing documents with geo-spatial coordinates and later on querying these indexed documents for location-based searching. For this purpose, Distributed Lucene uses the Spatial4n library.

Prerequisites

.NET/.NET Core

Make sure that you have created and started a Lucene cache through the NCache Web Manager or PowerShell.
Install the Lucene.Net.Spatial.NCache NuGet package in your application by executing the following command in the Package Manager Console:

Install-Package Lucene.Net.Spatial.NCache

Make sure that the Cache is already running.
Make sure that your application is not using any native Lucene DLL/Reference.
To ensure the operation is fail-safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Spatial Document

Spatial documents are created using the SpatialDocument class. These documents are later on used for indexing purposes. This class is specific to Distributed Lucene.

The SpatialDocument consists of shapes of the IShape class along with a Document. These shapes will then transform into indexable fields on the server-side via a Strategy. The indexable fields will be added to the Document via IndexWriter.

In the following example, a method for a spatial document is created with the return type of SpatialDocument class, this method is then used in the next example.

.NET/.NET Core

public static SpatialDocument CreateSpatialDocument(int id, SpatialStrategy strategy, params IShape[] shapes)
{
    try
    {
        Document doc = new Document();
        doc.Add(new Int32Field("id", id, Field.Store.YES));

        foreach (IShape shape in shapes)
        {
            IPoint pt = (IPoint)shape;
            doc.Add(new StoredField(strategy.FieldName, pt.X.ToString(CultureInfo.InvariantCulture) + " " + pt.Y.ToString(CultureInfo.InvariantCulture)));
        }

        return new SpatialDocument()
        {
            Document = doc,
            Shapes = shapes
        };
    }
    catch(Exception ex)
    {
        // Handle exceptions
    }
}

Spatial API Example

The SpatialStrategy class encapsulates an approach to indexing and searching documents based on shapes. Distributed Lucene supports all the spatial strategies supported by Lucene. The working of the spatial API is the same in both Distributed Lucene and Lucene, except for the concept of a SpatialDocument class that is present in Distributed Lucene only.

In the following example, spatial documents are defined using the CreateSpatialDocument method created in the earlier example and then added to the IndexWriter with the SpatialStrategy defined. The documents are later searched with the IndexSearcher, and results are verified afterward.

.NET/.NET Core

try
{
    // Pre-Requisite: Lucene cache is already connected
    string index = "normalIndex";

    // Initialize prefix tree with depth level
    var maxLevels = 11;
    var grid = new GeohashPrefixTree(SpatialContext.GEO, maxLevels);

    // Define strategy
    var strategy = new RecursivePrefixTreeStrategy(grid, "myGeoField");

    // Open NCache directory on index
    var directory = NCacheDirectory.Open(cache, index); 

    // Configure and initalize index writer
    var indexWriterConfig = new IndexWriterConfig(LuceneVersion.LUCENE_48, new StandardAnalyzer(LuceneVersion.LUCENE_48));
    IndexWriter writer = new IndexWriter(directory, indexWriterConfig);

    // Add spatial documents to document with index writer
    writer.AddDocument(CreateSpatialDocument(2, strategy, SpatialContext.GEO.MakePoint(-80.93, 33.77)), strategy);
    writer.AddDocument(CreateSpatialDocument(4, strategy, SpatialContext.GEO.ReadShapeFromWkt("POINT(60.9289094 -50.7693246)")), strategy);
    writer.AddDocument(CreateSpatialDocument(20, strategy, SpatialContext.GEO.MakePoint(0.1, 0.1), SpatialContext.GEO.MakePoint(0, 0)), strategy);


    // Open index reader on directory
    IndexReader indexReader = DirectoryReader.Open(directory);

    // Open index searcher on index reader
    IndexSearcher indexSearcher = new IndexSearcher(indexReader);

    // Define sorting strategy
    Sort idSort = new Sort(new SortField("id", SortFieldType.INT32));

    // Define spatial arguments
    SpatialArgs args = new SpatialArgs(SpatialOperation.Intersects, SpatialContext.GEO.MakeCircle(-80.0, 33.0, DistanceUtils.Dist2Degrees(200, DistanceUtils.EARTH_MEAN_RADIUS_KM)));

    // Define the filter with spatial arguments    
    Filter filter = strategy.MakeFilter(args);

    // Search top docs
    TopDocs docs = indexSearcher.Search(new MatchAllDocsQuery(), filter, 10, idSort);

    // Dispose index reader
    indexReader.Dispose();
}
catch(Exception ex)
{
    // Handle exceptions
}

Additional Resources