WITHIN

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

• zone sections

• field sections

• attribute sections

• special sections (sentence or paragraph)

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.

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'

The above 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

• Visibility: You can make text within a field section invisible.

• Repeatability: WITHIN queries cannot distinguish repeated field sections.

• Nestability: You cannot issue a nested WITHIN query with a field section.

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 AUTOMATIC_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.

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:

• Regular queries on attribute text do not hit the document unless qualified in a within clause. Assume you have an XML document as follows:

  <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.)

• You cannot use attribute sections in a nested WITHIN query.

• Phrases ignore attribute text. For example, if the original document looked like:

  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.

• WITHIN queries can distinguish repeated attribute sections. This behavior is like zone sections but unlike field sections. For example, you have a document as follows:

  <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

Scoring

The WITHIN operator has no effect on score.

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 meta-data 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.

Limitations

The WITHIN operator has the following limitations:

• You cannot embed the WITHIN clause in a phrase. For example, you cannot write: term1 WITHIN section term2

• You cannot combine WITHIN with expansion operators, such as $ ! and *.

• Since WITHIN is a reserved word, you must escape the word with braces to search on it.