NEAR (;)

Use the NEAR operator to return a score based on the proximity of two or more query terms.

Oracle Text returns higher scores for terms closer together and lower scores for terms farther apart in a document. If a word or term appears more than once in a NEAR query, then the word must appear more than once in the document in order to match.

Note: The NEAR operator works with only word queries. You cannot use NEAR in ABOUT queries.

Syntax

NEAR((word1,word2,...,wordn) [, max_span [, order [, minreqd]]])

Backward compatibility syntax:

word1;word2

word1-n

Specify the terms in the query separated by commas. The query terms can be single words or phrases and may make use of other query operators (see “NEAR with Other Operators”).

max_span

Optionally specify the number of words separating the start and end words of a clump. The default is

1. Oracle Text returns an error if you specify a number greater than 100.

A clump is the smallest group of words in which all query terms occur. All clumps begin and end with a query term.

For near queries with two terms, max_span is the maximum distance allowed between the two terms. For example, if the document contains “The cat sat on the dog” then you can find cat within 3 words of dog by using the following query:

'near((dog, cat, 3)'

If the document contains “The cat and the rabbit sat on the dog” then you can find cat, dog, and rabbit within 6 words by using the following query:

'near((cat, dog, rabbit), 6)'

Note: The search term rabbit is still included in the max_span calculation. If you specify a max_span of 5 then you cannot find rabbit. Stopwords are also included in the span calculation.

order

Specify TRUE for Oracle Text to search for terms in the order you specify. The default is FALSE.

For example, to search for the words monday, tuesday, and wednesday in that order with a maximum clump size of 20, enter the following query:

'near((monday, tuesday, wednesday), 20, TRUE)'

Note: To specify order, then you must always specify a number for max_span.

Oracle Text might return different scores for the same document when you use identical query expressions that have the order flag set differently. For example, Oracle Text might return different scores for the same document when you enter the following queries:

'near((dog, cat), 50, FALSE)'
'near((dog, cat), 50, TRUE)'

minreqd

Specify the minimum number of query terms that must be present near each other within a given span, for a document to qualify as a match. You must specify a number greater than 1. If the number of terms that must be near each other for a match is not specified, all terms must match. For example, the following query matches documents that contain clusters of words pertaining to fish:

'near((fish, shark, ocean, scales, fishing), 10, FALSE, 3)'

Here, only three of the query terms must be within a distance of 10 from each other for a match.

NEAR Scoring

The scoring for the NEAR operator combines frequency of the terms with proximity of terms. For each document that satisfies the query, Oracle Text returns a score between 1 and 100 that is proportional to the number of clumps in the document and inversely proportional to the average size of the clumps. This means many small clumps in a document result in higher scores, because small clumps imply closeness of terms.

The number of terms in a query also affects score. Queries with many terms, such as seven, generally need fewer clumps in a document to score 100 than do queries with few terms, such as two.

A clump is the smallest group of words in which all query terms occur. All clumps begin and end with a query term. Define clump size with the max_span parameter, as described in this section.

The size of a clump does not include the query terms themselves. So for the query NEAR((DOG, CAT), 1), dog cat will be a match, and dog ate cat will be a match, but dog sat on cat will not be a match.

NEAR with Other Operators

You can use the NEAR operator with other operators such as AND and OR. Scores are calculated in the regular way.

For example, to find all documents that contain the terms tiger, lion, and cheetah where the terms lion and tiger are within 10 words of each other, enter the following query:

'near((lion, tiger), 10) AND cheetah'

The score returned for each document is the lower score of the near operator and the term cheetah.

You can also use the equivalence operator to substitute a single term in a near query:

'near((stock crash, Japan=Korea), 20)'

This query asks for all documents that contain the phrase stock crash within twenty words of Japan orKorea.

The following NEAR syntax is now valid:

SELECT * FROM docs WHERE CONTAINS(txt, 'near((aterm1 aterm2 ... atermI
OR bterm1 bterm2 ... btermJ
OR cterm1 cterm2 ... ctermK, dterm))') >0

There can be any number of ORs in a given NEAR child, and the OR can appear in any of the NEAR children.

The NEAR within NEAR feature allows users to use nested proximity queries. Starting with Oracle Database 12c Release 2 ( 12.2), the distance between phrases is measured from the closest words in the phrases. For example, if the document contains the phrases ` Lorem ipsum dolor sit amet and Sed ut perspiciatis unde omnis, rather than measuring the distance of these two phrases as the distance between Lorem and Sed, the first two words in the phrases, the distance is measured from amet and Sed`. The distance between phrases is the so-called Hausdorff measure.

SELECT * FROM docs
WHERE CONTAINS(txt, 'near((near((term1, term2),5), term3), 100)')>0

This query returns documents where term1 and term2 are near within a 5 token window, and the phrase containing term1 and term2 is within a 100 token window from term3. The distance between term3 and the phrase containing term1 and term2 is computed based on the Hausdorff measure.

Mixing the semicolon and NEAR syntax is not supported and throws an error. That is, the queries "near((a;b,c),3)" or "near((a,b));c" will be disallowed.

The following operators also work with NEAR and ; :

• EQUIV

• All expansion operators that produce words, phrases, or EQUIV. These include:

  • soundex

  • fuzzy

  • wildcards

  • stem

Backward Compatibility NEAR Syntax

You can write near queries using the syntax of previous Oracle Text releases. However, in a nested NEAR query, the semicolon operator cannot be used as the inner NEAR. That is, the query 'near(((a;d),f),3)' produces a syntax error. The semicolon operator can be used as the outermost NEAR in a nested NEAR query.

For example, to find all documents where lion occurs near tiger, write:

'lion near tiger'

or with the semi-colon as follows:

'lion;tiger'

This query is equivalent to the following query:

'near((lion, tiger), 100, FALSE)'

Note: Only the syntax of the NEAR operator is backward compatible. In the example, the score returned is calculated using the clump method as described in this section.

Highlighting with the NEAR Operator

When you use highlighting and your query contains the near operator, all occurrences of all terms in the query that satisfy the proximity requirements are highlighted. Highlighted terms can be single words or phrases.

For example, assume a document contains the following text:

Chocolate and vanilla are my favorite ice cream flavors.  I like chocolate served
in a waffle cone, and vanilla served in a cup with caramel syrup.

If the query is near((chocolate, vanilla)), 100, FALSE), the following is highlighted:

<<Chocolate>> and <<vanilla>> are my favorite ice cream flavors.  I like
<<chocolate>> served in a waffle cone, and <<vanilla>> served in a cup with
caramel syrup.

However, if the query is near((chocolate, vanilla)), 4, FALSE), only the following is highlighted:

<<Chocolate>> and <<vanilla>> are my favorite ice cream flavors.  I like
chocolate served in a waffle cone, and vanilla served in a cup with caramel syrup.

See Also: CTX_DOC Package for more information about the procedures for highlighting

Section Searching and NEAR

Use the NEAR operator with the WITHIN operator for section searching as follows:

'near((dog, cat), 10) WITHIN Headings'

When evaluating expressions such as these, Oracle Text looks for clumps that lie entirely within the given section.

In this example, only those clumps that contain dog and cat that lie entirely within the section Headings are counted. That is, if the term dog lies within Headings and the term cat lies five words from dog, but outside of Headings, this pair of words does not satisfy the expression and is not counted.