Proximity Search
-
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.
-
Use the
proximity
method when running a full-text search by the search method. -
In this page:
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
andterm2
:-
Retrieved documents will contain text in which
term1
andterm2
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)
employees = list(
session.advanced.document_query(object_type=Employee)
# Make a full-text search with search terms
.search("Notes", "fluent french")
# Call 'proximity' with 0 distance
.proximity(0)
)
# 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.
from "Employees"
where proximity(search(Notes, "fluent french"), 0)
Proximity search (distance > 0)
employees = list(
session.advanced.document_query(object_type=Employee)
# Make a full-text search with search terms
.search("Notes", "fluent french")
# Call 'proximity' with 0 distance
.proximity(4)
)
# 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).
from "Employees"
where proximity(search(Notes, "fluent french"), 5)
Syntax
def proximity(self, proximity: int) -> DocumentQuery[_T]: ...
Parameter | Type | Description |
---|---|---|
proximity | int |
The maximum number of terms between the search terms. Can be greater or equal to 0 . |