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:attribute name="refid" type="xsd:positiveInteger"/>
    </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 refid attribute of the type tag specifies which backreference in the regular expression corresponds to the actual entity. The entity type can be one of the Oracle supplied types, listed in Table 10-1, or it can be a user-defined type, which must be prefixed with the letter "x".

Table 10-1 Supplied Entity Types

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

Example 1

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 refid = "1">email_address</type>
   </rule>');
end;
/

Where:

• Given the sentence: "My email address is jdoe@company.com", this extraction rule will extract "jdoe@company.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.

  • The value of the type element and the refid attribute of the type tag specify that the first backreference corresponds to the text of the entity.

Example 2

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 refid="1">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.

  • The value of the type element and the refid attribute of the type tag specify that the first backreference corresponds to the text of the entity.

  • Explanatory comments are associated with this rule.