Skip to main content

Proximity Search

C#JavaPythonPHPNode.js

  • A proximity search retrieves documents containing search terms that are located within a specified distance from each other. The distance is measured by the number of intermediate terms.

  • Proximity search is available only via DocumentQuery or RQL.

  • Use the Proximity method when running a full-text search by the Search method.

  • The queried index must use the Lucene search engine.
    Corax does not support proximity over the Search method,
    and running such a query against a Corax index throws an InvalidQueryException.

  • In this article:

Why use proximity search​

  • A basic linguistic assumption is that the proximity of words implies a relationship between them.

  • Proximity search helps match phrases while avoiding scattered or spread-out terms in the text.

  • By limiting the search to only include matches where the terms are within the specified maximum proximity,
    the search results can be more relevant than those with scattered terms.

How proximity works​

  • When searching with some specified distance between search terms term1 and term2:

    • Retrieved documents will contain text in which term1 and term2 are separated by
      the maximum number of terms specified or less.

    • The search terms can be separated by fewer terms, but not more than the specified distance.

    • Only the terms generated by the search analyzer are considered towards the count of the maximum distance.
      Words or tokens that are Not part of the generated terms are Not included in the proximity calculation.

  • Note:

    • Search criteria should contain at least 2 search terms.

    • Search terms must be simple string terms without wildcards.

Proximity search examples​

Proximity search (0 distance)​

List<Employee> employees = session.Advanced
    .DocumentQuery<Employee>()
     // Make a full-text search with search terms
    .Search(x => x.Notes,"fluent french")
     // Call 'Proximity' with 0 distance
    .Proximity(0)
    .ToList();

// Running the above query on the Northwind sample data returns the following Employee documents:
// * employees/2-A
// * employees/5-A
// * employees/9-A

// Each resulting document has the text 'fluent in French' in its 'Notes' field.
//
// The word "in" is not taken into account as it is Not part of the terms list generated
// by the analyzer. (Search is case-insensitive in this case).
//
// Note:
// A document containing text with the search terms appearing with no words in between them
// (e.g. "fluent french") would have also been returned.

  • Proximity 0 and analyzer-generated phrases
    A proximity distance of 0 requires matching terms to occupy consecutive positions in the analyzed index field.
    In the example above, the default search analyzer does not emit "in" as a term, so fluent in French still matches.

  • Analyzer-generated phrase matching
    The same order-and-adjacency rule applies when the analyzer produces multiple tokens from a single non-wildcard search term. For example, the analyzer splits fluent%french into fluent and french.

    RavenDB searches those tokens as a phrase; you do not call Proximity.
    Unlike proximity search, analyzer-generated phrase matching is supported by both Lucene and Corax.
    Learn more in Search with analyzer-generated phrases.

Proximity search (distance > 0)​

List<Employee> employees = session.Advanced
    .DocumentQuery<Employee>()
     // Make a full-text search with search terms
    .Search(x => x.Notes,"fluent french")
     // Call 'Proximity' with distance 4
    .Proximity(4)
    .ToList();

// Running the above query on the Northwind sample data returns the following Employee documents:
// * employees/2-A
// * employees/5-A
// * employees/6-A
// * employees/9-A

// This time document 'employees/6-A' was added to the previous results since it contains the phrase:
// "fluent in Japanese and can read and write French"
// where the search terms are separated by a count of 4 terms.
//
// "in" & "and" are not taken into account as they are not part of the terms list generated
// by the analyzer.(Search is case-insensitive in this case).

Syntax​

IDocumentQuery<T> Proximity(int proximity);

ParameterTypeDescription
proximityintThe maximum number of terms between the search terms.
Can be greater or equal to 0.

In this article