Skip Headers

Oracle® Text Reference
10g Release 1 (10.1)

Part Number B10730-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

3 CONTAINS Query Operators

This chapter describes operator precedence and provides description, syntax, and examples for every CONTAINS operator. The following topics are covered:

3.1 Operator Precedence

Operator precedence determines the order in which the components of a query expression are evaluated. Text query operators can be divided into two sets of operators that have their own order of evaluation. These two groups are described later as Group 1 and Group 2.

In all cases, query expressions are evaluated in order from left to right according to the precedence of their operators. Operators with higher precedence are applied first. Operators of equal precedence are applied in order of their appearance in the expression from left to right.

3.1.1 Group 1 Operators

Within query expressions, the Group 1 operators have the following order of evaluation from highest precedence to lowest:

  1. EQUIValence (=)

  2. NEAR (;)

  3. weight (*), threshold (>)

  4. MINUS (-)

  5. NOT (~)

  6. WITHIN

  7. AND (&)

  8. OR (|)

  9. ACCUMulate ( , )

3.1.2 Group 2 Operators and Characters

Within query expressions, the Group 2 operators have the following order of evaluation from highest to lowest:

  1. Wildcard Characters

  2. stem ($)

  3. Fuzzy

  4. soundex (!)

3.1.3 Procedural Operators

Other operators not listed under Group 1 or Group 2 are procedural. These operators have no sense of precedence attached to them. They include the SQE and thesaurus operators.

3.1.4 Precedence Examples

Query Expression Order of Evaluation
w1 | w2 & w3 (w1) | (w2 & w3)
w1 & w2 | w3 (w1 & w2) | w3
?w1, w2 | w3 & w4 (?w1), (w2 | (w3 & w4))
abc = def ghi & jkl = mno ((abc = def) ghi) & (jkl=mno)
dog and cat WITHIN body dog and (cat WITHIN body)

In the first example, because AND has a higher precedence than OR, the query returns all documents that contain w1 and all documents that contain both w2 and w3.

In the second example, the query returns all documents that contain both w1 and w2 and all documents that contain w3.

In the third example, the fuzzy operator is first applied to w1, then the AND operator is applied to arguments w3 and w4, then the OR operator is applied to term w2 and the results of the AND operation, and finally, the score from the fuzzy operation on w1 is added to the score from the OR operation.

The fourth example shows that the equivalence operator has higher precedence than the AND operator.

The fifth example shows that the AND operator has lower precedence than the WITHIN operator.

3.1.5 Altering Precedence

Precedence is altered by grouping characters as follows:

  • Within parentheses, expansion or execution of operations is resolved before other expansions regardless of operator precedence.

  • Within parentheses, precedence of operators is maintained during evaluation of expressions.

  • Within parentheses, expansion operators are not applied to expressions unless the operators are also within the parentheses.


ABOUT

General Behavior

In all languages, an ABOUT query increases the number of relevant documents returned from the same query without this operator. Oracle Text scores results for an ABOUT query with the most relevant document receiving the highest score.

English and French Behavior

In English and French, use the ABOUT operator to query on concepts. The system looks up concept information in the theme component of the index. You create a theme component to your index by setting the INDEX_THEMES BASIC_LEXER attribute to YES.


Note:

You need not have a theme component in the index to issue ABOUT queries in English and French. However, having a theme component in the index yields the best results for ABOUT queries.

Oracle Text retrieves documents that contain concepts that are related to your query word or phrase. For example, if you issue an ABOUT query on California, the system might return documents that contain the terms Los Angeles and San Francisco, which are cities in California.The document need not contain the term California to be returned in this ABOUT query.

The word or phrase specified in your ABOUT query need not exactly match the themes stored in the index. Oracle Text normalizes the word or phrase before performing lookup in the index.

You can use the ABOUT operator with the CONTAINS and CATSEARCH SQL operators. In the case of CATSEARCH, you must use query templating with the CONTEXT grammar to query on the indexed themes. See ABOUT Query with CATSEARCH in the Examples section.

Syntax

Syntax Description
about(phrase) In all languages, increases the number of relevant documents returned for the same query without the ABOUT operator.The phrase parameter can be a single word or a phrase, or a string of words in free text format.

In English and French, returns documents that contain concepts related to phrase, provided the BASIC_LEXER INDEX_THEMES attribute is set to YES at index time.

The score returned is a relevance score.

Oracle Text ignores any query operators that are included in phrase.

If your index contains only theme information, an ABOUT operator and operand must be included in your query on the text column or else Oracle Text returns an error.

The phrase you specify cannot be more than 4000 characters.


Case-Sensitivity

ABOUT queries give the best results when your query is formulated with proper case. This is because the normalization of your query is based on the knowledge catalog which is case-sensitive.

However, you need not type your query in exact case to obtain results from an ABOUT query. The system does its best to interpret your query. For example, if you enter a query of CISCO and the system does not find this in the knowledge catalog, the system might use Cisco as a related concept for look-up.

Improving ABOUT Results

The ABOUT operator uses the supplied knowledge base in English and French to interpret the phrase you enter. Your ABOUT query therefore is limited to knowing and interpreting the concepts in the knowledge base.

You can improve the results of your ABOUT queries by adding your application-specific terminology to the knowledge base.

Limitations

Examples


Single Words

To search for documents that are about soccer, use the following syntax:

'about(soccer)'

Phrases

You can further refine the query to include documents about soccer rules in international competition by entering the phrase as the query term:

'about(soccer rules in international competition)'

In this English example, Oracle Text returns all documents that have themes of soccer, rules, or international competition.

In terms of scoring, documents which have all three themes will generally score higher than documents that have only one or two of the themes.


Unstructured Phrases

You can also query on unstructured phrases, such as the following:

'about(japanese banking investments in indonesia)'

Combined Queries

You can use other operators, such as AND or NOT, to combine ABOUT queries with word queries.

For example, you can issue the following combined ABOUT and word query:

'about(dogs) and cat'

You can combine an ABOUT query with another ABOUT query as follows:

'about(dogs) not about(labradors)'

Note:

You cannot combine ABOUT with the WITHIN operator, as for example 'ABOUT (xyz) WITHIN abc'.


ABOUT Query with CATSEARCH

You can issue ABOUT queries with CATSEARCH using the query template method with grammar set to CONTEXT as follows:

select pk||' ==> '||text from test
where catsearch(text,
'<query> 
  <textquery grammar="context">
     about(California)
  </textquery>
  <score datatype="integer"/>
</query>','')>0
order by pk; 


ACCUMulate ( , )

Use the ACCUM operator to search for documents that contain at least one occurrence of any of the query terms. The accumulate operator ranks documents according to the total term weight of a document.

Syntax

Syntax Description
term1,term2

term1 accum term2

Returns documents that contain term1 or term2. Ranks documents according to document term weight, with the highest scores assigned to documents that have the highest total term weight.

Examples

The following example returns documents that contain either soccer, Brazil, or cup and assigns the highest scores to the documents that contain all three terms:

'soccer, Brazil, cup'

The following example also returns documents that contain either soccer, Brazil, or cup. However, the weight operator ensures that documents with Brazil score higher than documents that contain only soccer and cup.

'soccer, Brazil*3, cup'

Notes


Accumulate Scoring

ACCUM scores documents based on two criteria:

Term weight refers to the weight you place on a query term. A query such as x,y,z has term weights of 1 for each term. A query of x, 3*y, z, has term weights of 1, 3, and 1 for the individual terms.

Accumulate scoring guarantees that if a document A matches p terms with a total term weight of m, and document B matches q terms with a total term weight of m+1, document B is guaranteed to have a higher relevance score than document A, regardless of the numbers p and q.

If two documents have the same weight M, the higher relevance score goes to the document with the higher weighted average term score.

This following table illustrates accumulate scoring:

Document query Score(x) Score(y) Score(z) Total Term Weight Score(query)
A x,y,z 10 0 0 1 3
B x,y,z 10 20 0 2 38
C x,y,z 10 20 30 3 73
D x,y,z 50 50 0 2 50
E x, y*3, z 100 0 100 2 40
F x, y*3, z 0 1 0 3 41

Each row in the table shows the score for an accumulate query. The first four rows show the scores for query x,y,z for documents A, B, C, D. The next two rows show the scores for query x, y*3,z for documents E and F. Assume that x, y and z stand for three different words. The query for document E and F has a weight of 3 on the second query term to arbitrarily make it the most important query term.

The total document term weight is shown for each document. For example, document A has a matching weight of one since only one query term matches the document. Similarly document C has a weight of 3 since all query terms with weight 1 match the document.

The table shows that documents that have higher query term weights are always scored higher than those that contain lower query term weights. For example, document C always scores higher than documents A, B, and D, since document C has the highest query term weight. Similarly, document F scores higher than document E, since F has a higher matching weight.

For documents that have equal term weights, such as document B and D, the higher score goes to the document with the higher weighted average term score, which is document D.


AND (&)

Use the AND operator to search for documents that contain at least one occurrence of each of the query terms.

Syntax

Syntax Description
term1&term2

term1 and term2

Returns documents that contain term1 and term2. Returns the minimum score of its operands. All query terms must occur; lower score taken.

Examples

To obtain all the documents that contain the terms blue and black and red, issue the following query:

'blue & black & red'

In an AND query, the score returned is the score of the lowest query term. In this example, if the three individual scores for the terms blue, black, and red is 10, 20 and 30 within a document, the document scores 10.


Broader Term (BT, BTG, BTP, BTI)

Use the broader term operators (BT, BTG, BTP, BTI) to expand a query to include the term that has been defined in a thesaurus as the broader or higher level term for a specified term. They can also expand the query to include the broader term for the broader term and the broader term for that broader term, and so on up through the thesaurus hierarchy.

Syntax

Syntax Description
BT(term[(qualifier)][,level][,thes]) Expands a query to include the term defined in the thesaurus as a broader term for term.
BTG(term[(qualifier)][,level][,thes]) Expands a query to include all terms defined in the thesaurus as broader generic terms for term.
BTP(term[(qualifier)][,level][,thes]) Expands a query to include all the terms defined in the thesaurus as broader partitive terms for term.
BTI(term[(qualifier)][,level][,thes]) Expands a query to include all the terms defined in the thesaurus as broader instance terms for term.

term

Specify the operand for the broader term operator. Oracle Text expands term to include the broader term entries defined for the term in the thesaurus specified by thes. For example, if you specify BTG(dog), the expansion includes only those terms that are defined as broader term generic for dog. You cannot specify expansion operators in the term argument.

The number of broader terms included in the expansion is determined by the value for level.

qualifier

Specify a qualifier for term, if term is a homograph (word or phrase with multiple meanings, but the same spelling) that appears in two or more nodes in the same hierarchy branch of thes.

If a qualifier is not specified for a homograph in a broader term query, the query expands to include the broader terms of all the homographic terms.

level

Specify the number of levels traversed in the thesaurus hierarchy to return the broader terms for the specified term. For example, a level of 1 in a BT query returns the broader term entry, if one exists, for the specified term. A level of 2 returns the broader term entry for the specified term, as well as the broader term entry, if one exists, for the broader term.

The level argument is optional and has a default value of one (1). Zero or negative values for the level argument return only the original query term.

thes

Specify the name of the thesaurus used to return the expansions for the specified term. The thes argument is optional and has a default value of DEFAULT. A thesaurus named DEFAULT must exist in the thesaurus tables if you use this default value.


Note:

If you specify thes, you must also specify level.

Examples

The following query returns all documents that contain the term tutorial or the BT term defined for tutorial in the DEFAULT thesaurus:

'BT(tutorial)'

When you specify a thesaurus name, you must also specify level as in:

'BT(tutorial, 2, mythes)'

Broader Term Operator on Homographs

If machine is a broader term for crane (building equipment) and bird is a broader term for crane (waterfowl) and no qualifier is specified for a broader term query, the query

BT(crane) 

expands to:

'{crane} or {machine} or {bird}'

If waterfowl is specified as a qualifier for crane in a broader term query, the query

BT(crane{(waterfowl)}) 

expands to the query:

'{crane} or {bird}' 

Note:

When specifying a qualifier in a broader or narrower term query, the qualifier and its notation (parentheses) must be escaped, as is shown in this example.

Related Topics

You can browse a thesaurus using procedures in the CTX_THES package.


See Also:

For more information on browsing the broader terms in your thesaurus, see CTX_THES.BT in Chapter 12, " CTX_THES Package ".


EQUIValence (=)

Use the EQUIV operator to specify an acceptable substitution for a word in a query.

Syntax

Syntax Description
term1=term2

term1 equiv term2

Specifies that term2 is an acceptable substitution for term1. Score calculated as the sum of all occurrences of both terms.

Examples

The following example returns all documents that contain either the phrase alsatians are big dogs or labradors are big dogs:

'labradors=alsatians are big dogs'

Operator Precedence

The EQUIV operator has higher precedence than all other operators except the expansion operators (fuzzy, soundex, stem).


Fuzzy

Use the fuzzy operator to expand queries to include words that are spelled similarly to the specified term. This type of expansion is helpful for finding more accurate results when there are frequent misspellings in your document set.

The new fuzzy syntax enables you to rank the result set so that documents that contain words with high similarity to the query word are scored higher than documents with lower similarity. You can also limit the number of expanded terms.

Unlike stem expansion, the number of words generated by a fuzzy expansion depends on what is in the index. Results can vary significantly according to the contents of the index.

Supported Languages

Oracle Text supports fuzzy definitions for English, German, Italian, Dutch, Spanish, Japanese, and OCR.

Stopwords

If the fuzzy expansion returns a stopword, the stopword is not included in the query or highlighted by CTX_DOC.HIGHLIGHT or CTX_DOC.MARKUP.

Base-Letter Conversion

If base-letter conversion is enabled for a text column and the query expression contains a fuzzy operator, Oracle Text operates on the base-letter form of the query.

Syntax

fuzzy(term, score, numresults, weight)
Parameter Description
term Specify the word on which to perform the fuzzy expansion. Oracle Text expands term to include words only in the index.
score Specify a similarity score. Terms in the expansion that score below this number are discarded. Use a number between 1 and 80. The default is 60.
numresults Specify the maximum number of terms to use in the expansion of term. Use a number between 1 and 5000. The default is 100.
weight Specify WEIGHT or W for the results to be weighted according to their similarity scores.

Specify NOWEIGHT or N for no weighting of results.


Examples

Consider the CONTAINS query:

...CONTAINS(TEXT, 'fuzzy(government, 70, 6, weight)', 1) > 0;

This query expands to the first six fuzzy variations of government in the index that have a similarity score over 70.

In addition, documents in the result set are weighted according to their similarity to government. Documents containing words most similar to government receive the highest score.

You can skip unnecessary parameters using the appropriate number of commas. For example:

'fuzzy(government,,,weight)'

Backward Compatibility Syntax

The old fuzzy syntax from previous releases is still supported. This syntax is as follows:

Parameter Description
?term Expands term to include all terms with similar spellings as the specified term.


HASPATH

Use this operator to find all XML documents that contain a specified section path. You can also use this operator to do section equality testing.

Your index must be created with the PATH_SECTION_GROUP for this operator to work.

Syntax

Syntax Description
HASPATH(path) Searches an XML document set and returns a score of 100 for all documents where path exists. Separate parent and child paths with the / character. For example, you can specify A/B/C.

See example.

HASPATH(A="value") Searches an XML document set and returns a score of 100 for all documents that have the element A with content value and only value.

See example.


Example


Path Testing

The query

HASPATH(A/B/C)

finds and returns a score of 100 for the document

<A><B><C>dog</C></B></A>

without the query having to reference dog at all.


Section Equality Testing

The query

dog INPATH A

finds

<A>dog</A>

but it also finds

<A>dog park</A>

To limit the query to the term dog and nothing else, you can use a section equality test with the HASPATH operator. For example,

HASPATH(A="dog")

finds and returns a score of 100 only for the first document, and not the second.

Limitations

Because of how XML section data is recorded, false matches might occur with XML sections that are completely empty as follows:

<A><B><C></C></B><D><E></E></D></A>

A query of HASPATH(A/B/E) or HASPATH(A/D/C) falsely matches this document. This type of false matching can be avoided by inserting text between empty tags.


INPATH

Use this operator to do path searching in XML documents. This operator is like the WITHIN operator except that the right-hand side is a parentheses enclosed path, rather than a single section name.

Your index must be created with the PATH_SECTION_GROUP for the INPATH operator to work.

Syntax

The INPATH operator has the following syntax:


Top-Level Tag Searching
Syntax Description
term INPATH (/A)

term INPATH (A)

Returns documents that have term within the <A> and </A> tags.


Any-Level Tag Searching
Syntax Description
term INPATH (//A) Returns documents that have term in the <A> tag at any level. This query is the same as 'term WITHIN A'


Direct Parentage Path Searching
Syntax Description
term INPATH (A/B) Returns documents where term appears in a B element which is a direct child of a top-level A element.

For example, a document containing

<A><B>term</B></A>

is returned.



Single-Level Wildcard Searching
Syntax Description
term INPATH (A/*/B) Returns documents where term appears in a B element which is a grandchild (two levels down) of a top-level A element.

For example a document containing

<A><D><B>term</B></D></A>

is returned.



Multi-level Wildcard Searching
Syntax Description
term INPATH (A/*/B/*/*/C) Returns documents where term appears in a C element which is 3 levels down from a B element which is two levels down (grandchild) of a top-level A element.


Any-Level Descendant Searching
Syntax Description
term INPATH(A//B) Returns documents where term appears in a B element which is some descendant (any level) of a top-level A element.


Attribute Searching
Syntax Description
term INPATH (//A/@B) Returns documents where term appears in the B attribute of an A element at any level. Attributes must be bound to a direct parent.


Descendant/Attribute Existence Testing
Syntax Description
term INPATH (A[B]) Returns documents where term appears in a top-level A element which has a B element as a direct child.
term INPATH (A[.//B]) Returns documents where term appears in a top-level A element which has a B element as a descendant at any level.
term INPATH (//A[@B]) Finds documents where term appears in an A element at any level which has a B attribute. Attributes must be tied to a direct parent.


Attribute Value Testing
Syntax Description
term INPATH (A[@B = "value"]) Finds all documents where term appears in a top-level A element which has a B attribute whose value is value.
term INPATH (A[@B != "value"]) Finds all documents where term appears in a top-level A element which has a B attribute whose value is not value.


Tag Value Testing
Syntax Description
term INPATH (A[B = "value"])) Returns documents where term appears in an A tag which has a B tag whose value is value.


Not
Syntax Description
term INPATH (A[NOT(B)]) Finds documents where term appears in a top-level A element which does not have a B element as an immediate child.


AND and OR Testing
Syntax Description
term INPATH (A[B and C]) Finds documents where term appears in a top-level A element which has a B and a C element as an immediate child.
term INPATH (A[B and @C="value"]]) Finds documents where term appears in a top-level A element which has a B element and a C attribute whose value is value.
term INPATH (A [B OR C]) Finds documents where term appears in a top-level A element which has a B element or a C element.


Combining Path and Node Tests
Syntax Description
term INPATH (A[@B = "value"]/C/D) Returns documents where term appears in aD element which is the child of a C element, which is the child of a top-level A element with a B attribute whose value is value.

Nested INPATH

You can nest the entire INPATH expression in another INPATH expression as follows:

(dog INPATH (//A/B/C)) INPATH (D)

When you do so, the two INPATH paths are completely independent. The outer INPATH path does not change the context node of the inner INPATH path. For example:

(dog INPATH (A)) INPATH (D)

never finds any documents, because the inner INPATH is looking for dog within the top-level tag A, and the outer INPATH constrains that to document with top-level tag D. A document can have only one top-level tag, so this expression never finds any documents.

Case-Sensitivity

Tags and attribute names in path searching are case-sensitive. That is,

dog INPATH (A)

finds <A>dog</A> but does not find <a>dog</a>. Instead use

dog INPATH (a)

Examples


Top-Level Tag Searching

To find all documents that contain the term dog in the top-level tag <A>:

dog INPATH (/A)

or

dog INPATH(A)

Any-Level Tag Searching

To find all documents that contain the term dog in the <A> tag at any level:

dog INPATH(//A)

This query finds the following documents:

<A>dog</A>

and

<C><B><A>dog</A></B></C>

Direct Parentage Searching

To find all documents that contain the term dog in a B element that is a direct child of a top-level A element:

dog INPATH(A/B)

This query finds the following XML document:

<A><B>My dog is friendly.</B><A>

but does not find:

<C><B>My dog is friendly.</B></C>

Tag Value Testing

You can test the value of tags. For example, the query:

dog INPATH(A[B="dog"])

Finds the following document:

<A><B>dog</B></A>

But does not find:

<A><B>My dog is friendly.</B></A>

Attribute Searching

You can search the content of attributes. For example, the query:

dog INPATH(//A/@B)

Finds the document

<C><A  B="snoop dog"> </A> </C>

Attribute Value Testing

You can test the value of attributes. For example, the query

California INPATH (//A[@B = "home address"])

Finds the document:

<A B="home address">San Francisco, California, USA</A>

But does not find:

<A B="work address">San Francisco, California, USA</A>

Path Testing

You can test if a path exists with the HASPATH operator. For example, the query:

HASPATH(A/B/C)

finds and returns a score of 100 for the document

<A><B><C>dog</C></B></A>

without the query having to reference dog at all.

Limitations


Testing for Equality

The following is an example of an INPATH equality test.

dog INPATH (A[@B = "foo"])

The following limitations apply for these expressions:


MDATA

Use the MDATA operator to query documents that contain MDATA sections. MDATA sections are metadata that have been added to documents to speed up mixed querying.

MDATA queries are treated exactly as literals. For example, with the query

MDATA(price, $1.24)

the $ is not interpreted as a stem operator, nor is the . (period) transformed into whitespace. A right (close) parenthesis terminates the MDATA operator, so that MDATA values that have close parentheses cannot be searched.

Syntax

Syntax
MDATA(sectionname, value)

sectionname

The name of the MDATA section(s) to search.

value

The value of the MDATA section. For example, if an MDATA section called Booktype has been created, it might have a value of paperback.

Example

Suppose you want to query for books written by the writer Nigella Lawson that contain the word summer. Assuming that an MDATA section called AUTHOR has been declared, you can query as follows:

SELECT id FROM idx_docs
  WHERE CONTAINS(text, 'summer AND MDATA(author, Nigella Lawson)')>0

This query will only be successful if an AUTHOR tag has the exact value Nigella Lawson (after simplified tokenization). Nigella or Ms. Nigella Lawson will not work.

Notes

MDATA query values ignore stopwords.

The MDATA operator returns 100 or 0, depending on whether the document is a match.

The MDATA operator is not supported for CTXCAT, CTXRULE, or CTXXPATH indexes.

Table 3-1 shows how MDATA interacts with some other query operators:

Table 3-1 MDATA and Other Query Operators

Operator Example Allowed?
AND dog & MDATA(a, b) yes
OR dog | MDATA(a, b) yes
NOT dog ~ MDATA(a, b) yes
MINUS dog - MDATA(a, b) yes
ACCUM dog , MDATA(a, b) yes
PHRASE MDATA(a, b) dog no
NEAR MDATA(a, b) ; dog no
WITHIN, HASPATH, INPATH MDATA(a, b) WITHIN c no
Thesaurus MDATA(a, SYN(b)) no
expansion MDATA(a, $b)

MDATA(a, b%)

MDATA(a, !b)

MDATA(a, ?b)

no (syntactically allowed, but the inner operator is treated as literal text)
ABOUT ABOUT(MDATA(a,b))

MDATA(ABOUT(a))

no (syntactically allowed, but the inner operator is treated as literal text)

When MDATA sections repeat, each instance is a separate and independent value. For instance, the document

<AUTHOR>Terry Pratchett</AUTHOR><AUTHOR>Douglas Adams</AUTHOR>

can be found with any of the following queries:

MDATA(author, Terry Pratchett)
MDATA(author, Douglas Adams)
MDATA(author, Terry Pratchett) and MDATA(author, Douglas Adams)

but not any of the following:

MDATA(author, Terry Pratchett Douglas Adams)
MDATA(author, Terry Pratchett & Douglas Adams)
MDATA(author, Pratchett Douglas)

Related Topics

See also "ADD_MDATA" and "ADD_MDATA_SECTION", as well as the Section Searching chapter of the Oracle Text Application Developer's Guide.


MINUS (-)

Use the MINUS operator to search for documents that contain one query term and you want the presence of a second query term to cause the document to be ranked lower. The MINUS operator is useful for lowering the score of documents that contain unwanted noise terms.

Syntax

Syntax Description
term1-term2

term1 minus term2

Returns documents that contain term1. Calculates score by subtracting the score of term2 from the score of term1. Only documents with positive score are returned.

Examples

Suppose a query on the term cars always returned high scoring documents about Ford cars. You can lower the scoring of the Ford documents by using the expression:

'cars - Ford'

In essence, this expression returns documents that contain the term cars and possibly Ford. However, the score for a returned document is the score of cars minus the score of Ford.


Narrower Term (NT, NTG, NTP, NTI)

Use the narrower term operators (NT, NTG, NTP, NTI) to expand a query to include all the terms that have been defined in a thesaurus as the narrower or lower level terms for a specified term. They can also expand the query to include all of the narrower terms for each narrower term, and so on down through the thesaurus hierarchy.

Syntax

Syntax Description
NT(term[(qualifier)][,level][,thes]) Expands a query to include all the lower level terms defined in the thesaurus as narrower terms for term.
NTG(term[(qualifier)][,level][,thes]) Expands a query to include all the lower level terms defined in the thesaurus as narrower generic terms for term.
NTP(term[(qualifier)][,level][,thes]) Expands a query to include all the lower level terms defined in the thesaurus as narrower partitive terms for term.
NTI(term[(qualifier)][,level][,thes]) Expands a query to include all the lower level terms defined in the thesaurus as narrower instance terms for term.

term

Specify the operand for the narrower term operator. term is expanded to include the narrower term entries defined for the term in the thesaurus specified by thes. The number of narrower terms included in the expansion is determined by the value for level. You cannot specify expansion operators in the term argument.

qualifier

Specify a qualifier for term, if term is a homograph (word or phrase with multiple meanings, but the same spelling) that appears in two or more nodes in the same hierarchy branch of thes.

If a qualifier is not specified for a homograph in a narrower term query, the query expands to include all of the narrower terms of all homographic terms.

level

Specify the number of levels traversed in the thesaurus hierarchy to return the narrower terms for the specified term. For example, a level of 1 in an NT query returns all the narrower term entries, if any exist, for the specified term. A level of 2 returns all the narrower term entries for the specified term, as well as all the narrower term entries, if any exist, for each narrower term.

The level argument is optional and has a default value of one (1). Zero or negative values for the level argument return only the original query term.

thes

Specify the name of the thesaurus used to return the expansions for the specified term. The thes argument is optional and has a default value of DEFAULT. A thesaurus named DEFAULT must exist in the thesaurus tables if you use this default value.


Note:

If you specify thes, you must also specify level.

Examples

The following query returns all documents that contain either the term cat or any of the NT terms defined for cat in the DEFAULT thesaurus:

'NT(cat)'

If you specify a thesaurus name, you must also specify level as in:

'NT(cat, 2, mythes)'

The following query returns all documents that contain either fairy tale or any of the narrower instance terms for fairy tale as defined in the DEFAULT thesaurus:

'NTI(fairy tale)'

That is, if the terms cinderella and snow white are defined as narrower term instances for fairy tale, Oracle Text returns documents that contain fairy tale, cinderella, or snow white.

Notes

Each hierarchy in a thesaurus represents a distinct, separate branch, corresponding to the four narrower term operators. In a narrower term query, Oracle Text only expands the query using the branch corresponding to the specified narrower term operator.

Related Topics

You can browse a thesaurus using procedures in the CTX_THES package.


See Also:

For more information on browsing the narrower terms in your thesaurus, see CTX_THES.NT in Chapter 12, " CTX_THES Package ".


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.


Note:

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

Syntax

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

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 size of the biggest clump. The default is 100. 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, to query on dog and cat where dog is within 6 words of cat, issue the following query:

'near((dog, cat), 6)'
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, issue the following query:

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

Note:

To specify order, you must always specify a number for the max_span parameter.

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 issue the following queries:

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

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, since 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. You can 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, issue 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 or Korea.

The following operators also work with NEAR:

Backward Compatibility NEAR Syntax

You can write near queries using the syntax of previous Oracle Text releases. For example, to find all documents where lion occurs near tiger, you can 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 carmel 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 carmel syrup.

See Also:

For more information about the procedures you can use for highlighting, see Chapter 8, " CTX_DOC Package ".

Section Searching and NEAR

You can 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.


NOT (~)

Use the NOT operator to search for documents that contain one query term and not another.

Syntax

Syntax Description
term1~term2

term1 not term2

Returns documents that contain term1 and not term2.

Examples

To obtain the documents that contain the term animals but not dogs, use the following expression:

'animals ~ dogs'

Similarly, to obtain the documents that contain the term transportation but not automobiles or trains, use the following expression:

'transportation not (automobiles or trains)'

Note:

The NOT operator does not affect the scoring produced by the other logical operators.


OR (|)

Use the OR operator to search for documents that contain at least one occurrence of any of the query terms.

Syntax

Syntax Description
term1|term2

term1 or term2

Returns documents that contain term1 or term2. Returns the maximum score of its operands. At least one term must exist; higher score taken.

Examples

For example, to obtain the documents that contain the term cats or the term dogs, use either of the following expressions:

'cats | dogs'
'cats OR dogs'

Scoring

In an OR query, the score returned is the score for the highest query term. In the example, if the scores for cats and dogs is 30 and 40 within a document, the document scores 40.


Preferred Term (PT)

Use the preferred term operator (PT) to replace a term in a query with the preferred term that has been defined in a thesaurus for the term.

Syntax

Syntax Description
PT(term[,thes]) Replaces the specified word in a query with the preferred term for term.

term

Specify the operand for the preferred term operator. term is replaced by the preferred term defined for the term in the specified thesaurus. However, if no PT entries are defined for the term, term is not replaced in the query expression and term is the result of the expansion.

You cannot specify expansion operators in the term argument.

thes

Specify the name of the thesaurus used to return the expansions for the specified term. The thes argument is optional and has a default value of DEFAULT. As a result, a thesaurus named DEFAULT must exist in the thesaurus tables before using any of the thesaurus operators.

Examples

The term automobile has a preferred term of car in a thesaurus. A PT query for automobile returns all documents that contain the word car. Documents that contain the word automobile are not returned.

Related Topics

You can browse a thesaurus using procedures in the CTX_THES package.


See Also:

For more information on browsing the preferred terms in your thesaurus, see CTX_THES.PT in Chapter 12, " CTX_THES Package ".


Related Term (RT)

Use the related term operator (RT) to expand a query to include all related terms that have been defined in a thesaurus for the term.

Syntax

Syntax Description
RT(term[,thes]) Expands a query to include all the terms defined in the thesaurus as a related term for term.

term

Specify the operand for the related term operator. term is expanded to include term and all the related entries defined for term in thes.

You cannot specify expansion operators in the term argument.

thes

Specify the name of the thesaurus used to return the expansions for the specified term. The thes argument is optional and has a default value of DEFAULT. As a result, a thesaurus named DEFAULT must exist in the thesaurus tables before using any of the thesaurus operators.

Examples

The term dog has a related term of wolf. A RT query for dog returns all documents that contain the word dog and wolf.

Related Topics

You can browse a thesaurus using procedures in the CTX_THES package


See Also:

For more information on browsing the related terms in your thesaurus, see CTX_THES.RT in Chapter 12, " CTX_THES Package ".


soundex (!)

Use the soundex (!) operator to expand queries to include words that have similar sounds; that is, words that sound like other words. This function enables comparison of words that are spelled differently, but sound alike in English.

Syntax

Syntax Description
!term Expands a query to include all terms that sound the same as the specified term (English-language text only).

Examples

SELECT ID, COMMENT FROM EMP_RESUME
WHERE CONTAINS (COMMENT, '!SMYTHE') > 0 ;

ID COMMENT 
-- ------------
23 Smith is a hard worker who..

Language

Soundex works best for languages that use a 7-bit character set, such as English. It can be used, with lesser effectiveness, for languages that use an 8-bit character set, such as many Western European languages.

If you have base-letter conversion specified for a text column and the query expression contains a soundex operator, Oracle Text operates on the base-letter form of the query.


stem ($)

Use the stem ($) operator to search for terms that have the same linguistic root as the query term.

If you use the BASIC_LEXER to index your language, stemming performance can be improved by using the index_stems attribute.

The Oracle Text stemmer, licensed from Xerox Corporation's XSoft Division, supports the following languages with the BASIC_LEXER: English, French, Spanish, Italian, German, and Dutch.

Japanese stemming is supported with the JAPANESE_LEXER.

You can specify your stemming language with the BASIC_WORDLIST wordlist preference.

Syntax

Syntax Description
$term Expands a query to include all terms having the same stem or root word as the specified term.

Examples

Input Expands To
$scream scream screaming screamed
$distinguish distinguish distinguished distinguishes
$guitars guitars guitar
$commit commit committed
$cat cat cats
$sing sang sung sing

Behavior with Stopwords

If stem returns a word designated as a stopword, the stopword is not included in the query or highlighted by CTX_QUERY.HIGHLIGHT or CTX_QUERY.MARKUP.

Related Topics


See Also:

For more information about enabling the stem operator with BASIC_LEXER, see BASIC_LEXER in Chapter 2, " Oracle Text Indexing Elements".


Stored Query Expression (SQE)

Use the SQE operator to call a stored query expression created with the CTX_QUERY.STORE_SQE procedure.

Stored query expressions can be used for creating predefined bins for organizing and categorizing documents or to perform iterative queries, in which an initial query is refined using one or more additional queries.

Syntax

Syntax Description
SQE(SQE_name) Returns the results for the stored query expression SQE_name.

Examples

To create an SQE named disasters, use CTX_QUERY.STORE_SQE as follows:

begin
ctx_query.store_sqe('disasters', 'hurricane or earthquake or blizzard');
end;

This stored query expression returns all documents that contain either hurricane, earthquake or blizzard.

This SQE can then be called within a query expression as follows:

SELECT SCORE(1), docid FROM news
WHERE CONTAINS(resume, 'sqe(disasters)', 1)> 0 
ORDER BY SCORE(1);

SYNonym (SYN)

Use the synonym operator (SYN) to expand a query to include all the terms that have been defined in a thesaurus as synonyms for the specified term.

Syntax

Syntax Description
SYN(term[,thes]) Expands a query to include all the terms defined in the thesaurus as synonyms for term.

term

Specify the operand for the synonym operator. term is expanded to include term and all the synonyms defined for term in thes.

You cannot specify expansion operators in the term argument.

thes

Specify the name of the thesaurus used to return the expansions for the specified term. The thes argument is optional and has a default value of DEFAULT. A thesaurus named DEFAULT must exist in the thesaurus tables if you use this default value.

Examples

The following query expression returns all documents that contain the term dog or any of the synonyms defined for dog in the DEFAULT thesaurus:

'SYN(dog)'

Compound Phrases in Synonym Operator

Expansion of compound phrases for a term in a synonym query are returned as AND conjunctives.

For example, the compound phrase temperature + measurement + instruments is defined in a thesaurus as a synonym for the term thermometer. In a synonym query for thermometer, the query is expanded to:

{thermometer} OR ({temperature}&{measurement}&{instruments})

Related Topics

You can browse your thesaurus using procedures in the CTX_THES package.


See Also:

For more information on browsing the synonym terms in your thesaurus, see CTX_THES.SYN in Chapter 12, " CTX_THES Package ".


threshold (>)

Use the threshold operator (>) in two ways:

The threshold operator at the expression level eliminates documents in the result set that score below a threshold number.

The threshold operator at the query term level selects a document based on how a term scores in the document.

Syntax

Syntax Description
expression>n

term>n

Returns only those documents in the result set that score above the threshold n.

Within an expression, returns documents that contain the query term with score of at least n.


Examples

At the expression level, to search for documents that contain relational databases and to return only documents that score greater than 75, use the following expression:

'relational databases > 75'

At the query term level, to select documents that have at least a score of 30 for lion and contain tiger, use the following expression:

'(lion > 30) and tiger'

Translation Term (TR)

Use the translation term operator (TR) to expand a query to include all defined foreign language equivalent terms.

Syntax

Syntax Description
TR(term[, lang, [thes]]) Expands term to include all the foreign equivalents that are defined for term.

term

Specify the operand for the translation term operator. term is expanded to include all the foreign language entries defined for term in thes.You cannot specify expansion operators in the term argument.

lang

Optionally, specify which foreign language equivalents to return in the expansion. The language you specify must match the language as defined in thes. (You may specify only one language at a time.) If you omit this parameter or specify it as ALL, the system expands to use all defined foreign language terms.

thes

Optionally, specify the name of the thesaurus used to return the expansions for the specified term. The thes argument has a default value of DEFAULT. As a result, a thesaurus named DEFAULT must exist in the thesaurus tables before you can use any of the thesaurus operators.


Note:

If you specify thes, you must also specify lang.

Examples

Consider a thesaurus MY_THES with the following entries for cat:

cat 
  SPANISH: gato 
  FRENCH:  chat 

To search for all documents that contain cat and the spanish translation of cat, issue the following query:

'tr(cat, spanish, my_thes)'

This query expands to:

'{cat}|{gato}'

Related Topics

You can browse a thesaurus using procedures in the CTX_THES package.


See Also:

For more information on browsing the related terms in your thesaurus, see CTX_THES.TR in Chapter 12, " CTX_THES Package ".


Translation Term Synonym (TRSYN)

Use the translation term operator (TR) to expand a query to include all the defined foreign equivalents of the query term, the synonyms of query term, and the foreign equivalents of the synonyms.

Syntax

Syntax Description
TRSYN(term[, lang, [thes]]) Expands term to include foreign equivalents of term, the synonyms of term, and the foreign equivalents of the synonyms.

term

Specify the operand for this operator. term is expanded to include all the foreign language entries and synonyms defined for term in thes.You cannot specify expansion operators in the term argument.

lang

Optionally, specify which foreign language equivalents to return in the expansion. The language you specify must match the language as defined in thes. If you omit this parameter, the system expands to use all defined foreign language terms.

thes

Optionally, specify the name of the thesaurus used to return the expansions for the specified term. The thes argument has a default value of DEFAULT. As a result, a thesaurus named DEFAULT must exist in the thesaurus tables before you can use any of the thesaurus operators.


Note:

If you specify thes, you must also specify lang.

Examples

Consider a thesaurus MY_THES with the following entries for cat:

cat 
  SPANISH: gato 
  FRENCH:  chat 
  SYN lion 
    SPANISH: leon 

To search for all documents that contain cat, the spanish equivalent of cat, the synonym of cat, and the spanish equivalent of lion, issue the following query:

'trsyn(cat, spanish, my_thes)'

This query expands to:

'{cat}|{gato}|{lion}|{leon}'

Related Topics

You can browse a thesaurus using procedures in the CTX_THES package.


See Also:

For more information on browsing the translation and synonym terms in your thesaurus, see CTX_THES.TRSYN in Chapter 12, " CTX_THES Package ".


Top Term (TT)

Use the top term operator (TT) to replace a term in a query with the top term that has been defined for the term in the standard hierarchy (BT, NT) in a thesaurus. Top terms in the generic (BTG, NTG), partitive (BTP, NTP), and instance (BTI, NTI) hierarchies are not returned.

Syntax

Syntax Description
TT(term[,thes]) Replaces the specified word in a query with the top term in the standard hierarchy (BT, NT) for term.

term

Specify the operand for the top term operator. term is replaced by the top term defined for the term in the specified thesaurus. However, if no TT entries are defined for term, term is not replaced in the query expression and term is the result of the expansion.

You cannot specify expansion operators in the term argument.

thes

Specify the name of the thesaurus used to return the expansions for the specified term. The thes argument is optional and has a default value of DEFAULT. A thesaurus named DEFAULT must exist in the thesaurus tables if you use this default value.

Examples

The term dog has a top term of animal in the standard hierarchy of a thesaurus. A TT query for dog returns all documents that contain the phrase animal. Documents that contain the word dog are not returned.

Related Topics

You can browse your thesaurus using procedures in the CTX_THES package.


See Also:

For more information on browsing the top terms in your thesaurus, see CTX_THES.PT in Chapter 12, " CTX_THES Package ".


weight (*)

The weight operator multiplies the score by the given factor, topping out at 100 when the score exceeds 100. For example, the query cat, dog*2 sums the score of cat with twice the score of dog, topping out at 100 when the score is greater than 100.

In expressions that contain more than one query term, use the weight operator to adjust the relative scoring of the query terms. You can reduce the score of a query term by using the weight operator with a number less than 1; you can increase the score of a query term by using the weight operator with a number greater than 1 and less than 10.

The weight operator is useful in accumulate, OR, or AND queries when the expression has more than one query term. With no weighting on individual terms, the score cannot tell you which of the query terms occurs the most. With term weighting, you can alter the scores of individual terms and hence make the overall document ranking reflect the terms you are interested in.

Syntax

Syntax Description
term*n Returns documents that contain term. Calculates score by multiplying the raw score of term by n, where n is a number from 0.1 to 10.

Examples

You have a collection of sports articles. You are interested in the articles about soccer, in particular Brazilian soccer. It turns out that a regular query on soccer or Brazil returns many high ranking articles on US soccer. To raise the ranking of the articles on Brazilian soccer, you can issue the following query:

'soccer or Brazil*3'

Table 3-2 illustrates how the weight operator can change the ranking of three hypothetical documents A, B, and C, which all contain information about soccer. The columns in the table show the total score of four different query expressions on the three documents.

Table 3-2 Score Samples


soccer Brazil soccer or Brazil soccer or Brazil*3
A 20 10 20 30
B 10 30 30 90
C 50 20 50 60

The score in the third column containing the query soccer or Brazil is the score of the highest scoring term. The score in the fourth column containing the query soccer or Brazil*3 is the larger of the score of the first column soccer and of the score Brazil multiplied by three, Brazil*3.

With the initial query of soccer or Brazil, the documents are ranked in the order C B A. With the query of soccer or Brazil*3, the documents are ranked B C A, which is the preferred ranking.


wildcards (% _)

Wildcard characters can be used in query expressions to expand word searches into pattern searches. The wildcard characters are:

Wildcard Character Description
% The percent wildcard can appear any number of times at any part of the search term. The search term will be expanded into an equivalence list of terms. The list consists of all terms in the index that match the wildcarded term, with zero or more characters in place of the percent character.
_ The underscore wildcard specifies a single position in which any character can occur.


Note:

When a wildcard expression translates to a stopword, the stopword is not included in the query and not highlighted by CTX_DOC.HIGHLIGHT or CTX_DOC.MARKUP .

Right-Truncated Queries

Right truncation involves placing the wildcard on the right-hand-side of the search string.

For example, the following query expression finds all terms beginning with the pattern scal:

'scal%'

Left- and Double-Truncated Queries

Left truncation involves placing the wildcard on the left-hand-side of the search string.

To find words such as king, wing or sing, you can write your query as follows:

'_ing'

For all words that end with ing, you can issue:

'%ing'

You can also combine left-truncated and right-truncated searches to create double-truncated searches. The following query finds all documents that contain words that contain the substring %benz%

'%benz%'

Improving Wildcard Query Performance

You can improve wildcard query performance by adding a substring or prefix index.

When your wildcard queries are left- and double-truncated, you can improve query performance by creating a substring index. Substring indexes improve query performance for all types of left-truncated wildcard searches such as %ed, _ing, or %benz%.

When your wildcard queries are right-truncated, you can improve performance by creating a prefix index. A prefix index improves query performance for wildcard searches such as to%.


See Also:

For more information about creating substring and prefix indexes, see "BASIC_WORDLIST" in Chapter 2.


WITHIN

You can use the WITHIN operator to narrow a query down into document sections. Document sections can be one of the following:

Syntax

Syntax Description
expression WITHIN section Searches for expression within the pre-defined zone, field, or attribute section.

If section is a zone, expression can contain one or more WITHIN operators (nested WITHIN) whose section is a zone or special section.

If section is a field or attribute section, expression cannot contain another WITHIN operator.

expression WITHIN SENTENCE Searches for documents that contain expression within a sentence. Specify an AND or NOT query for expression.

The expression can contain one or more WITHIN operators (nested WITHIN) whose section is a zone or special section.

expression WITHIN PARAGRAPH Searches for documents that contain expression within a paragraph. Specify an AND or NOT query for expression.

The expression can contain one or more WITHIN operators (nested WITHIN) whose section is a zone or special section.


WITHIN Limitations

The WITHIN operator has the following limitations:

WITHIN Operator Examples


Querying Within Zone Sections

To find all the documents that contain the term San Francisco within the section Headings, write your query as follows:

'San Francisco WITHIN Headings'

To find all the documents that contain the term sailing and contain the term San Francisco within the section Headings, write your query in one of two ways:

'(San Francisco WITHIN Headings) and sailing'

'sailing and San Francisco WITHIN Headings'


Compound Expressions with WITHIN

To find all documents that contain the terms dog and cat within the same section Headings, write your query as follows:

'(dog and cat) WITHIN Headings'

This query is logically different from:

'dog WITHIN Headings and cat WITHIN Headings'

This query finds all documents that contain dog and cat where the terms dog and cat are in Headings sections, regardless of whether they occur in the same Headings section or different sections.


Near with WITHIN

To find all documents in which dog is near cat within the section Headings, write your query as follows:

'dog near cat WITHIN Headings'

Note:

The near operator has higher precedence than the WITHIN operator so braces are not necessary in this example. This query is equivalent to (dog near cat) WITHIN Headings.


Nested WITHIN Queries

You can nest the within operator to search zone sections within zone sections.

For example, assume that a document set had the zone section AUTHOR nested within the zone BOOK section. You write a nested WITHIN query to find all occurrences of scott within the AUTHOR section of the BOOK section as follows:

'(scott WITHIN AUTHOR) WITHIN BOOK'

Querying Within Field Sections

The syntax for querying within a field section is the same as querying within a zone section. The syntax for most of the examples given in the previous section, "Querying Within Zone Sections", apply to field sections.

However, field sections behave differently from zone sections in terms of

The following sections describe these differences.


Visible Flag in Field Sections

When a field section is created with the visible flag set to FALSE in CTX_DDL.ADD_FIELD_SECTION, the text within a field section can only be queried using the WITHIN operator.

For example, assume that TITLE is a field section defined with visible flag set to FALSE. Then the query dog without the WITHIN operator will not find a document containing:

<TITLE>The dog</TITLE> I like my pet.

To find such a document, you can use the WITHIN operator as follows:

'dog WITHIN TITLE'

Alternatively, you can set the visible flag to TRUE when you define TITLE as a field section with CTX_DDL.ADD_FIELD_SECTION.


See Also:

For more information about creating field sections, see ADD_FIELD_SECTION in Chapter 7, " CTX_DDL Package".


Repeated Field Sections

WITHIN queries cannot distinguish repeated field sections in a document. For example, consider the document with the repeated section <author>:

<author> Charles Dickens </author>
<author> Martin Luther King </author>

Assuming that <author> is defined as a field section, a query such as (charles and martin) within author returns the document, even though these words occur in separate tags.

To have WITHIN queries distinguish repeated sections, define the sections as zone sections.


Nested Field Sections

You cannot issue a nested WITHIN query with field sections. Doing so raises an error.


Querying Within Sentence or Paragraphs

Querying within sentence or paragraph boundaries is useful to find combinations of words that occur in the same sentence or paragraph. To query sentence or paragraphs, you must first add the special section to your section group before you index. You do so with CTX_DDL.ADD_SPECIAL_SECTION.

To find documents that contain dog and cat within the same sentence:

'(dog and cat) WITHIN SENTENCE'

To find documents that contain dog and cat within the same paragraph:

'(dog and cat) WITHIN PARAGRAPH'

To find documents that contain sentences with the word dog but not cat:

'(dog not cat) WITHIN SENTENCE'

Querying Within Attribute Sections

You can query within attribute sections when you index with either XML_SECTION_GROUP or AUTO_SECTION_GROUP as your section group type.

Assume you have an XML document as follows:

<book title="Tale of Two Cities">It was the best of times.</book>

You can define the section title@book to be the attribute section title. You can do so with the CTX_DLL.ADD_ATTR_SECTION procedure or dynamically after indexing with ALTER INDEX.


Note:

When you use the AUTO_SECTION_GROUP to index XML documents, the system automatically creates attribute sections and names them in the form attribute@tag.

If you use the XML_SECTION_GROUP, you can name attribute sections anything with CTX_DDL.ADD_ATTR_SECTION.


To search on Tale within the attribute section title, you issue the following query:

'Tale WITHIN title'

Constraints for Querying Attribute Sections

The following constraints apply to querying within attribute sections:

<book title="Tale of Two Cities">It was the best of times.</book>

A query on Tale by itself does not produce a hit on the document unless qualified with WITHIN title@book. (This behavior is like field sections when you set the visible flag set to false.)

Now is the time for all good <word type="noun"> men </word> to come to the aid.

Then this document would hit on the regular query good men, ignoring the intervening attribute text.

<book title="Tale of Two Cities">It was the best of times.</book>
<book title="Of Human Bondage">The sky broke dull and gray.</book>

Assume that book is a zone section and book@author is an attribute section. Consider the query:

'(Tale and Bondage) WITHIN book@author'

This query does not hit the document, because tale and bondage are in different occurrences of the attribute section book@author.

Notes


Section Names

The WITHIN operator requires you to know the name of the section you search. A list of defined sections can be obtained using the CTX_SECTIONS or CTX_USER_SECTIONS views.


Section Boundaries

For special and zone sections, the terms of the query must be fully enclosed in a particular occurrence of the section for the document to satisfy the query. This is not a requirement for field sections.

For example, consider the query where bold is a zone section:

'(dog and cat) WITHIN bold'

This query finds:

<B>dog cat</B>

but it does not find:

<B>dog</B><B>cat</B>

This is because dog and cat must be in the same bold section.

This behavior is especially useful for special sections, where

'(dog and cat) WITHIN sentence'

means find dog and cat within the same sentence.

Field sections on the other hand are meant for non-repeating, embedded metadata such as a title section. Queries within field sections cannot distinguish between occurrences. All occurrences of a field section are considered to be parts of a single section. For example, the query:

(dog and cat) WITHIN title

can find a document like this:

<TITLE>dog</TITLE><TITLE>cat</TITLE>

In return for this field section limitation and for the overlap and nesting limitations, field section queries are generally faster than zone section queries, especially if the section occurs in every document, or if the search term is common.