ADD_EXTRACT_RULE

The ADD_EXTRACT_RULE procedure adds a single extraction rule to extract policy. Invokers add rules into their own extraction policy.

Extraction rules have sentence-wide scopes. Extraction rules have to be case-sensitive except for entity types and rule operators in the rule expression. Order of rule addition is not important. Addition of a rule will not be effective until CTX_ENTITY.COMPILE is executed. This procedure issues a commit.

Syntax

CTX_ENTITY.ADD_EXTRACT_RULE(
  policy_name                 IN VARCHAR2,
  rule_id                     IN INTEGER,
  extraction_rule             IN VARCHAR2);

policy_name

Specify the policy name.

rule_id

Specify a unique rule ID within an extraction policy. The rule ID must be greater than 0.

extraction_rule

The rule text in XML format specifies the language, expression, and entities to be extracted. The rule text follows the XML schema as follows:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="rule">
  <xsd:sequence>
    <xsd:element name="expression" type="xsd:string"/>
    <xsd:complexType>
    </xsd:complexType>
    <xsd:element name="comments type="xsd:string" default="\0"/>
  </xsd:sequence>
  </xsd:attribute name="language" type="xsd:string" default="ALL"/>
</xsd:element>
</xsd:schema>

Where:

The language attribute of the rule tag specifies the applied language for the rule. The rule will only be applied to documents that are of the specified languages. The language attribute can be left out, or set to “ALL” if the rule is to match on all documents.
The expression tag contains the posix regular expression that will be used in the matching.
The comments tag allows users to associate any comments with this user rule.
The type tag assigns the extracted entity text to a given entity type. The entity type can be one of the Oracle supplied rule types, listed inTable 10-1, or it can be a user-defined type.

Note:

Starting with Oracle Database Release 21c, the extraction rule’s XML format has the following changes: The refid attribute of the type tag is not supported. User-defined types do not need to be prefixed with the letter “x”. '\c(<type>)' must be used for using user-defined type and Oracle supplied types in the rules.

Table 1 Supplied Entity Types

Supplied Entity Type	Type	Explanation	Examples
`building`	Oracle supplied dictionary	Name of a building	Gallery House
`city`	Oracle supplied dictionary	Name of a city	New York
`company`	Oracle supplied dictionary	Name of a company	Oracle Corporation
`country`	Oracle supplied dictionary	Name of a country	United States
`currency`	Oracle supplied rule	Currency	Dollar
`date`	Oracle supplied rule	Date	July 4
`day`	Oracle supplied dictionary	Day	Monday, Tuesday
`email_address`	Oracle supplied rule	Email address	person@example.com
`geo_political`	Oracle supplied dictionary	A political or strategic organization	United Nations
`holiday`	Oracle supplied dictionary	Name of a country holiday	Labor Day
`location_other`	Oracle supplied dictionary	Other types of locations	Atlantic Ocean
`month`	Oracle supplied rule	Month	June, July
`non_profit`	Oracle supplied dictionary	Non-profit organization	Red Cross
`organization_other`	Oracle supplied dictionary	Other types of organizations	Supreme Court
`percent`	Oracle supplied rule	Expressed as number and %	10%
`person_jobtitle`	Oracle supplied dictionary	Person referred to by title	President, Professor
`person_name`	Oracle supplied rule	Person referred to by name	John Doe
`person_other`	Oracle supplied dictionary	Other types of persons	Other types of persons (for example, criminal)
`phone_number`	Oracle supplied rule	Phone number	(123)-456-7890
`postal_address`	Oracle supplied rule	Postal address	Redwood Shores, CA
`product`	Oracle supplied dictionary	Name of a product	Oracle Text
`region`	Oracle supplied dictionary	Name of a region	North America
`ssn`	Oracle supplied rule	Social Security Number	123-45-6789
`state`	Oracle supplied dictionary	A state or province	California
`time_duration`	Oracle supplied rule	A length of time	10 seconds
`tod`	Oracle supplied rule	Time of day	8:00 AM
`url`	Oracle supplied rule	Web address	www.example.com
`zip_code`	Oracle supplied rule	Zip Code	CA 94065

Example 10-1 Defining an extraction rule to find email addresses in documents

The following example shows how to define an extraction rule and associate it with an entity extraction policy. The following rule defines a simple extraction rule for finding email addresses in documents.

begin
  ctx_entity.add_extract_rule('pol1', 1,
  '<rule>
    <expression>email is (\w+@\w+\.\w+)</expression>
    <type>email_address</type>
   </rule>');
end;
/

Where:

Given the sentence: “My email address is jdoe@example.com”, this extraction rule will extract “jdoe@example.com” as an entity of type email_address.
The rule is added to the extraction policy called pol1.
The rule is added with rule ID of 1.
This XML description of the rule is as follows:
- The language attribute of the rule tag is left empty, so the rule will apply to all languages.
- The expression tag contains the regular expression to use in the extraction.

Example 10-2 Defining an extraction rule to find phone numbers in documents

The following rule defines a simple extraction rule for finding phone numbers in documents:

begin
  ctx_entity.add_extract_rule('pol1', 2,
  '<rule language="english">
     <expression>((d{3}) \d{3}-\d{3}-\d{4})</expression>
     <comments>Rule for phone numbers</comments>
     <type>email_address</type>
   </rule>');
end;
/

Where:

Given the sentence: “I can be contacted at (123) 456-7890”, this extraction rule will extract “(123) 456-7890” as an entity of type phone_number.
The rule is added to the extraction policy called pol1.
The rule is added with rule ID of 2.
The XML description of the rule is as follows:
- The language attribute of the rule tag is set to english, so the rule will only apply to English documents.
- The expression tag contains the regular expression to use in the extraction.
- Explanatory comments are associated with this rule.

Example 10-3 Defining an extraction rule using user-defined type

The following example shows how to define an extraction rule using an user-defined type to search for entities in a document:

begin
  ctx_entity.add_extract_rule('pol1', 1,
  '<rule>
     <expression>([a-z]+)</expression>
     <type>my_type</type>
   </rule>');
end;
/

begin
  ctx_entity.add_extract_rule('pol1', 2,
  '<rule>
     <expression>(\d\c(my_type)?\s^\c(my_type))</expression>
     <type>type_comp</type>
     <comments>Rule with nested type</comments>
  </rule>');
end;
/