7 SEM_APIS Package Subprograms

SEM_APIS.ADD_SEM_INDEX

Format

SEM_APIS.ADD_SEM_INDEX(

     index_code IN VARCHAR2);

Description

Creates creates a semantic network index that results in creation of a nonunique B-tree index in UNUSABLE status for each of the existing models and entailments of the semantic network.

Parameters

index_code

Index code string.

Usage Notes

You must have DBA privileges to call this procedure.

For an explanation of semantic network indexes, see Section 1.8.

Examples

The following example creates a semantic network index with the index code string pcsm on the models and entailments of the semantic network.

EXECUTE SEM_APIS.ADD_SEM_INDEX('pscm');

SEM_APIS.ALTER_ENTAILMENT

Format

SEM_APIS.ALTER_ENTAILMENT(

     entailment_name IN VARCHAR2,

     command IN VARCHAR2,

     tablespace_name IN VARCHAR2,

     parallel IN NUMBER(38) DEFAULT NULL);

Description

Alters an entailment (rules index). Currently, the only action supported is to move the entailment to a specified tablespace.

Parameters

entailment_name

Name of the entailment.

command

Must be the string MOVE.

tablespace_name

Name of the destination tablespace.

parallel

Degree of parallelism to be associated with the operation. For more information about parallel execution, see Oracle Database VLDB and Partitioning Guide.

Usage Notes

For an explanation of entailments, see Section 1.3.7.

Examples

The following example moves the entailment named rdfs_rix_family to the tablespace named my_tbs.

EEXECUTE SEM_APIS.ALTER_ENTAILMENT('rdfs_rix_family', 'MOVE',  'my_tbs');

SEM_APIS.ALTER_MODEL

Format

SEM_APIS.ALTER_MODEL(

     model_name IN VARCHAR2,

     command IN VARCHAR2,

     tablespace_name IN VARCHAR2,

     parallel IN NUMBER(38) DEFAULT NULL);

Description

Alters a model. Currently, the only action supported is to move the model to a specified tablespace.

Parameters

model_name

Name of the model.

command

Must be the string MOVE.

tablespace_name

Name of the destination tablespace.

parallel

Degree of parallelism to be associated with the operation. For more information about parallel execution, see Oracle Database VLDB and Partitioning Guide.

Usage Notes

For an explanation of models, see Section 1.2, "Semantic Data Modeling" and Section 1.3, "Semantic Data in the Database".

Examples

The following example moves the model named family to the tablespace named my_tbs.

EEXECUTE SEM_APIS.ALTER_MODEL('family', 'MOVE',  'my_tbs');

SEM_APIS.ALTER_SEM_INDEX_ON_ENTAILMENT

Format

SEM_APIS.ALTER_SEM_INDEX_ON_ENTAILMENT(

     entailment_name IN VARCHAR2,

     index_code IN VARCHAR2,

     command IN VARCHAR2,

     tablespace_name IN VARCHAR2 DEFAULT NULL,

     use_compression IN BOOLEAN DEFAULT NULL,

     parallel IN NUMBER(38) DEFAULT NULL,

     online IN BOOLEAN DEFAULT FALSE);

Description

Alters a semantic network index on an entailment.

Parameters

entailment_name

Name of the entailment.

index_code

Index code string.

command

String value containing one of the following commands: REBUILD rebuilds the semantic network index on the entailment, or UNUSABLE marks as unusable the semantic network index on the entailment. The value for this parameter is not case sensitive.

tablespace_name

Name of the destination tablespace for the rebuild operation.

use_compression

Specifies whether compression should be used when rebuilding the index.

parallel

Degree of parallelism to be associated with the operation. For more information about parallel execution, see Oracle Database VLDB and Partitioning Guide.

online

TRUE allows DML operations affecting the index during the rebuilding of the index; FALSE (the default) does not allow DML operations affecting the index during the rebuilding of the index.

Usage Notes

For an explanation of semantic network indexes, see Section 1.8.

Examples

The following example rebuilds (and makes usable if it is unusable) the semantic network index on the entailment named rdfs_rix_family.

EXECUTE SEM_APIS.ALTER_SEM_INDEX_ON_ENTAILMENT('rdfs_rix_family', 'pscm', 'rebuild');

SEM_APIS.ALTER_SEM_INDEX_ON_MODEL

Format

SEM_APIS.ALTER_SEM_INDEX_ON_MODEL(

     model_name IN VARCHAR2,

     index_code IN VARCHAR2,

     command IN VARCHAR2,

     tablespace_name IN VARCHAR2 DEFAULT NULL,

     use_compression IN BOOLEAN DEFAULT NULL,

     parallel IN NUMBER(38) DEFAULT NULL,

     online IN BOOLEAN DEFAULT FALSE);

Description

Alters a semantic network index on a model.

Parameters

model_name

Name of the model.

index_code

Index code string.

command

String value containing one of the following commands: REBUILD rebuilds the semantic network index on the model, or UNUSABLE marks as unusable the semantic network index on the model. The value for this parameter is not case sensitive.

tablespace_name

Name of the destination tablespace for the rebuild operation.

use_compression

Specifies whether compression should be used when rebuilding the index.

parallel

Degree of parallelism to be associated with the operation. For more information about parallel execution, see Oracle Database VLDB and Partitioning Guide.

online

TRUE allows DML operations affecting the index during the rebuilding of the index; FALSE (the default) does not allow DML operations affecting the index during the rebuilding of the index.

Usage Notes

For an explanation of semantic network indexes, see Section 1.8.

Examples

The following example rebuilds (and makes usable if it is unusable) the semantic network index on the model named family.

EXECUTE SEM_APIS.ALTER_SEM_INDEX_ON_MODEL('family', 'pscm', 'rebuild');

SEM_APIS.ANALYZE_ENTAILMENT

Format

SEM_APIS.ANALYZE_ENTAILMENT(

     entailment_name IN VARCHAR2,

     estimate_percent IN NUMBER DEFAULT to_estimate_percent_type (get_param('ESTIMATE_PERCENT')),

     method_opt IN VARCHAR2 DEFAULT get_param('METHOD_OPT'),

     degree IN NUMBER DEFAULT to_degree_type(get_param('DEGREE')),

     cascade IN BOOLEAN DEFAULT to_cascade_type(get_param('CASCADE')),

     no_invalidate IN BOOLEAN DEFAULT to_no_invalidate_type (get_param('NO_INVALIDATE')),

     force IN BOOLEAN DEFAULT FALSE);

Description

Collects statistics for a specified entailment (rules index).

Parameters

entailment_name

Name of the entailment.

estimate_percent

Percentage of rows to estimate in the internal table partition containing information about the entailment (NULL means compute). The valid range is [0.000001,100]. Use the constant DBMS_STATS.AUTO_SAMPLE_SIZE to have Oracle determine the appropriate sample size for good statistics. This is the usual default.

method_opt

Accepts either of the following options, or both in combination, for the internal table partition containing information about the entailment:

• FOR ALL [INDEXED | HIDDEN] COLUMNS [size_clause]

• FOR COLUMNS [size clause] column|attribute [size_clause] [,column|attribute [size_clause]...]

size_clause is defined as size_clause := SIZE {integer | REPEAT | AUTO | SKEWONLY}

column is defined as column := column_name | (extension)

- integer : Number of histogram buckets. Must be in the range [1,254].
- REPEAT : Collects histograms only on the columns that already have histograms.
- AUTO : Oracle determines the columns to collect histograms based on data distribution and the workload of the columns.
- SKEWONLY : Oracle determines the columns to collect histograms based on the data distribution of the columns.
- column_name : name of a column
- extension: Can be either a column group in the format of (column_name, column_name [, ...]) or an expression.

The usual default is FOR ALL COLUMNS SIZE AUTO.

degree

Degree of parallelism for the internal table partition containing information about the entailment. The usual default for degree is NULL, which means use the table default value specified by the DEGREE clause in the CREATE TABLE or ALTER TABLE statement. Use the constant DBMS_STATS.DEFAULT_DEGREE to specify the default value based on the initialization parameters. The AUTO_DEGREE value determines the degree of parallelism automatically. This is either 1 (serial execution) or DEFAULT_DEGREE (the system default value based on number of CPUs and initialization parameters) according to size of the object.

cascade

Gathers statistics on the indexes for the internal table partition containing information about the entailment. Use the constant DBMS_STATS.AUTO_CASCADE to have Oracle determine whether index statistics are to be collected or not. This is the usual default.

no_invalidate

Does not invalidate the dependent cursors if set to TRUE. The procedure invalidates the dependent cursors immediately if set to FALSE. Use DBMS_STATS.AUTO_INVALIDATE. to have Oracle decide when to invalidate dependent cursors. This is the usual default.

force

TRUE gathers statistics even if the entailment is locked; FALSE (the default) does not gather statistics if the entailment is locked.

Usage Notes

Index statistics collection can be parellelized except for cluster, domain, and join indexes.

This procedure internally calls the DBMS_STATS.GATHER_TABLE_STATS procedure, which collects statistics for the internal table partition that contains information about the entailment. The DBMS_STATS.GATHER_TABLE_STATS procedure is documented in Oracle Database PL/SQL Packages and Types Reference.

For information about entailments, see Section 1.3.7.

Examples

The following example collects statistics for the entailment named rdfs_rix_family.

EXECUTE SEM_APIS.ANALYZE_ENTAILMENT('rdfs_rix_family');

SEM_APIS.ANALYZE_MODEL

Format

SEM_APIS.ANALYZE_MODEL(

     model_name IN VARCHAR2,

     estimate_percent IN NUMBER DEFAULT to_estimate_percent_type (get_param('ESTIMATE_PERCENT')),

     method_opt IN VARCHAR2 DEFAULT get_param('METHOD_OPT'),

     degree IN NUMBER DEFAULT to_degree_type(get_param('DEGREE')),

     cascade IN BOOLEAN DEFAULT to_cascade_type(get_param('CASCADE')),

     no_invalidate IN BOOLEAN DEFAULT to_no_invalidate_type (get_param('NO_INVALIDATE')),

     force IN BOOLEAN DEFAULT FALSE);

Description

Collects optimizer statistics for a specified model.

Parameters

model_name

Name of the model.

estimate_percent

Percentage of rows to estimate in the internal table partition containing information about the model (NULL means compute). The valid range is [0.000001,100]. Use the constant DBMS_STATS.AUTO_SAMPLE_SIZE to have Oracle determine the appropriate sample size for good statistics. This is the usual default.

method_opt

Accepts either of the following options, or both in combination, for the internal table partition containing information about the model:

• FOR ALL [INDEXED | HIDDEN] COLUMNS [size_clause]

• FOR COLUMNS [size clause] column|attribute [size_clause] [,column|attribute [size_clause]...]

size_clause is defined as size_clause := SIZE {integer | REPEAT | AUTO | SKEWONLY}

column is defined as column := column_name | (extension)

- integer : Number of histogram buckets. Must be in the range [1,254].
- REPEAT : Collects histograms only on the columns that already have histograms.
- AUTO : Oracle determines the columns to collect histograms based on data distribution and the workload of the columns.
- SKEWONLY : Oracle determines the columns to collect histograms based on the data distribution of the columns.
- column_name : name of a column
- extension: Can be either a column group in the format of (column_name, column_name [, ...]) or an expression.

The usual default is FOR ALL COLUMNS SIZE AUTO.

degree

Degree of parallelism for the internal table partition containing information about the model. The usual default for degree is NULL, which means use the table default value specified by the DEGREE clause in the CREATE TABLE or ALTER TABLE statement. Use the constant DBMS_STATS.DEFAULT_DEGREE to specify the default value based on the initialization parameters. The AUTO_DEGREE value determines the degree of parallelism automatically. This is either 1 (serial execution) or DEFAULT_DEGREE (the system default value based on number of CPUs and initialization parameters) according to size of the object.

cascade

Gathers statistics on the indexes for the internal table partition containing information about the model. Use the constant DBMS_STATS.AUTO_CASCADE to have Oracle determine whether index statistics are to be collected or not. This is the usual default.

no_invalidate

Does not invalidate the dependent cursors if set to TRUE. The procedure invalidates the dependent cursors immediately if set to FALSE. Use DBMS_STATS.AUTO_INVALIDATE. to have Oracle decide when to invalidate dependent cursors. This is the usual default.

force

TRUE gathers statistics even if the model is locked; FALSE (the default) does not gather statistics if the model is locked.

Usage Notes

Index statistics collection can be parellelized except for cluster, domain, and join indexes.

This procedure internally calls the DBMS_STATS.GATHER_TABLE_STATS procedure, which collects optimizer statistics for the internal table partition that contains information about the model. The DBMS_STATS.GATHER_TABLE_STATS procedure is documented in Oracle Database PL/SQL Packages and Types Reference.

Examples

The following example collects statistics for the semantic model named family.

EXECUTE SEM_APIS.ANALYZE_MODEL('family');

SEM_APIS.BULK_LOAD_FROM_STAGING_TABLE

Format

SEM_APIS.BULK_LOAD_FROM_STAGING_TABLE(

     model_name IN VARCHAR2,

     table_owner IN VARCHAR2,

     table_name IN VARCHAR2,

     flags IN VARCHAR2 DEFAULT NULL,

     debug IN BINARY_INTEGER DEFAULT NULL,

     start_comment IN VARCHAR2 DEFAULT NULL,

     end_comment IN VARCHAR2 DEFAULT NULL);

Description

Loads semantic data from a staging table.

Parameters

model_name

Name of the model.

table_owner

Name of the schema that owns the staging table that holds semantic data to be loaded.

table_name

Name of the staging table that holds semantic data to be loaded.

flags

An optional quoted string with one or more of the following keyword specifications:

• PARALLEL_CREATE_INDEX allows internal indexes to be created in parallel, which may improve the performance of the bulk load processing.

• PARALLEL=<integer> allows much of the processing used during bulk load to be done in parallel using the specified degree of parallelism to be associated with the operation.

• <task>_JOIN_HINT=<join_type>, where <task> can be any of the following internal tasks performed during bulk load: IZC (is zero collisions), MBV (merge batch values), or MBT (merge batch triples, used when adding triples to a non-empty model), and where <join_type> can be USE_NL and USE_HASH.

debug

(Reserved for future use)

start_comment

Optional comment about the start of the load operation.

end_comment

Optional comment about the end of the load operation.

Usage Notes

You must first load semantic data into a staging table before calling this procedure. See Section 1.7.1 for more information.

Using BULK_LOAD_FROM_STAGING_TABLE with Fine Grained Access Control (VPD and OLS)

When fine-grained access control (explained in Chapter 5) is enabled for a specific model using VPD or for the entire network using OLS, only a user with FULL access privileges to the associated policy may perform the bulk load operation. Full access privileges to a VPD policy are granted by setting the context attribute defined by the package constant sem_rdfsa.VPD_FULL_ACCESS to 1 for the namespace associated with the VPD policy (see Section 5.1.1). When OLS is enabled, full access privileges to the OLS policy are granted using the SA_USER_ADMIN.SET_USER_PRIVS procedure.

The data loaded into a model with VPD enabled is immediately available for access and does not need any maintenance operations. However, when the OLS is used, the label column in the tables storing the RDF triples must be maintained. By default, with OLS enabled, the label column in the tables storing the RDF triples is set to null. If you have FULL access, you can reset the labels for the newly inserted triples as well as any resources introduced by the new batch of triples by using appropriate subprograms (SEM_RDFSA.SET_RESOURCE_LABEL and SEM_RDFSA.SET_PREDICATE_LABEL).

Optionally, you can define a numeric column named RDF$STC_CTXT1 in the staging table and the application table, to assign the sensitivity label of the triple before the data is loaded into the desired model. Such labels are automatically applied to the corresponding triples stored in the MDSYS.RDF_LINK$ table. The labels for the newly introduced resources may still have to be applied separately before or after the load, and the system does not validate the labels assigned during bulk load operation.

The RDF$STC_CTXT1 column in the application table has no significance, and it may be dropped after the bulk load operation.

Examples

The following example loads semantic data stored in the staging table named STAGE_TABLE in schema SCOTT into the semantic model named family. The example includes some join hints.

EXECUTE SEM_APIS.BULK_LOAD_FROM_STAGING_TABLE('family', 'scott', 'stage_table', flags => 'IZC_JOIN_HINT=USE_HASH MBV_JOIN_HINT=USE_HASH');

SEM_APIS.CLEANUP_FAILED

Format

SEM_APIS.CLEANUP_FAILED(

     rdf_object_type IN VARCHAR2,

     rdf_object_name IN VARCHAR2);

Description

Drops (deletes) a specified rulebase or entailment if it is in a failed state.

Parameters

rdf_object_type

Type of the RDF object: RULEBASE for a rulebase or RULES_INDEX for an entailment (rules index).

rdf_object_name

Name of the RDF object of type rdf_object_type.

Usage Notes

This procedure checks to see if the specified RDF object is in a failed state; and if the object is in a failed state, the procedure deletes the object.

A rulebase or entailment is in a failed state if a system failure occurred during the creation of that object. You can check if a rulebase or entailment is in a failed state by checking to see if the value of the STATUS column is FAILED in the SDO_RULEBASE_INFO view (described in Section 1.3.6) or the SDO_RULES_INDEX_INFO view (described in Section 1.3.7), respectively.

If the rulebase or entailment is not in a failed state, this procedure performs no action and returns a successful status.

An exception is generated if the RDF object is currently being used.

Examples

The following example deletes the rulebase named family_rb if (and only if) that rulebase is in a failed state.

EXECUTE SEM_APIS.CLEANUP_FAILED('RULEBASE', 'family_rb');

SEM_APIS.COMPOSE_RDF_TERM

Format

SEM_APIS.COMPOSE_RDF_TERM(

     value_name IN VARCHAR2,

     value_type IN VARCHAR2,

     literal_type IN VARCHAR2,

     language_type IN VARCHAR2

     ) RETURN VARCHAR2;

or

SEM_APIS.COMPOSE_RDF_TERM(

     value_name IN VARCHAR2,

     value_type IN VARCHAR2,

     literal_type IN VARCHAR2,

     language_type IN VARCHAR2,

     long_value IN CLOB,

     options IN VARCHAR2 DEFAULT NULL,

     ) RETURN CLOB;

Description

Creates and returns an RDF term using the specified parameters.

Parameters

value_name

Value name. Must match a value in the VALUE_NAME column in the MDSYS.RDF_VALUE$ table (described in Section 1.3.2) or in the var attribute returned from SEM_MATCH table function.

value_type

The type of text information. Must match a value in the VALUE_TYPE column in the MDSYS.RDF_VALUE$ table (described in Section 1.3.2) or in the var$RDFVTYP attribute returned from SEM_MATCH table function.

literal_type

For typed literals, the type information; otherwise, null. Must either be a null value or match a value in the LITERAL_TYPE column in the MDSYS.RDF_VALUE$ table (described in Section 1.3.2) or in the var$RDFLTYP attribute returned from SEM_MATCH table function.

language_type

Language tag. Must match a value in the LANGUAGE_TYPE column in the MDSYS.RDF_VALUE$ table (described in Section 1.3.2) or in the var$RDFLANG attribute returned from SEM_MATCH table function.

long_value

The character string if the length of the lexical value is greater than 4000 bytes. Must match a value in the LONG_VALUE column in the MDSYS.RDF_VALUE$ table (described in Section 1.3.2) or in the var$RDFCLOB attribute returned from SEM_MATCH table function.

options

(Reserved for future use.)

Usage Notes

If you specify an inconsistent combination of values for the parameters, this function returns a null value. If a null value is returned but you believe that the values for the parameters are appropriate (reflecting columns from the same row in the MDSYS.RDF_VALUE$ table or from a SEM_MATCH query for the same variable), contact Oracle Support.

Examples

The following example returns, for each member of the family whose height is known, the RDF term for the height and also just the value portion of the height.

SELECT x, SEM_APIS.COMPOSE_RDF_TERM(h, h$RDFVTYP, h$RDFLTYP, h$RDFLANG)
       h_rdf_term, h
  FROM TABLE(SEM_MATCH(
    '{?x :height ?h}',
    SEM_Models('family'),
    null, 
    SEM_ALIASES(SEM_ALIAS('','http://www.example.org/family/')),
    null))
ORDER BY x;
X
--------------------------------------------------------------------------------
H_RDF_TERM
--------------------------------------------------------------------------------
H
--------------------------------------------------------------------------------
http://www.example.org/family/Cathy
"5.8"^^<http://www.w3.org/2001/XMLSchema#decimal>
5.8
 
http://www.example.org/family/Cindy
"6"^^<http://www.w3.org/2001/XMLSchema#decimal>
6
 
http://www.example.org/family/Jack
"6"^^<http://www.w3.org/2001/XMLSchema#decimal>
6
 
http://www.example.org/family/Tom
"5.75"^^<http://www.w3.org/2001/XMLSchema#decimal>
5.75
 
4 rows selected.

The following example returns the RDF terms for a few of the values stored in the MDSYS.RDF_VALUE$ table.

SELECT SEM_APIS.COMPOSE_RDF_TERM(value_name, value_type, literal_type,
     language_type)
  FROM MDSYS.RDF_VALUE$ WHERE ROWNUM < 5;

SEM_APIS.COMPOSE_RDF_TERM(VALUE_NAME,VALUE_TYPE,LITERAL_TYPE,LANGUAGE_TYPE)
--------------------------------------------------------------------------------
<http://www.w3.org/1999/02/22-rdf-syntax-ns#object>
<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>
<http://www.w3.org/1999/02/22-rdf-syntax-ns#subject>
<http://www.w3.org/1999/02/22-rdf-syntax-ns#Property>

SEM_APIS.CREATE_ENTAILMENT

Format

SEM_APIS.CREATE_ENTAILMENT(

     entailment_name_in IN VARCHAR2,

     models_in IN SEM_MODELS,

     rulebases_in IN SEM_RULEBASES,

     passes IN NUMBER DEFAULT SEM_APIS.REACH_CLOSURE,

     inf_components_in IN VARCHAR2 DEFAULT NULL,

     options IN VARCHAR2 DEFAULT NULL,

     delta_in IN SEM_MODELS DEFAULT NULL,

     label_gen IN RDFSA_LABELGEN DEFAULT NULL);

Description

Creates an entailment (rules index) that can be used to perform OWL or RDFS inferencing, and optionally use user-defined rules.

Parameters

entailment_name_in

Name of the entailment to be created.

models_in

One or more model names. Its data type is SEM_MODELS, which has the following definition: TABLE OF VARCHAR2(25)

rulebases_in

One or more rulebase names. Its data type is SEM_RULEBASES, which has the following definition: TABLE OF VARCHAR2(25). Rules and rulebases are explained in Section 1.3.6.

passes

The number of rounds that the inference engine should run. The default value is SEM_APIS.REACH_CLOSURE, which means the inference engine will run till a closure is reached. If the number of rounds specified is less than the number of actual rounds needed to reach a closure, the status of the entailment will then be set to INCOMPLETE.

inf_components_in

A comma-delimited string of keywords representing inference components, for performing selective or component-based inferencing. If this parameter is null, the default set of inference components is used. See the Usage Notes for more information about inference components.

options

A comma-delimited string of options to control the inference process by overriding the default inference behavior. To enable an option, specify option-name=T; to disable an option, you can specify option-name=F (the default). The available option-name values are COL_COMPRESS, DISTANCE,DOP, ENTAIL_ANYWAY, HASH_PART, INC, OPT_SAMEAS, RAW8, PROOF, and USER_RULES. See the Usage Notes for explanations of each value.

delta_in

If incremental inference is in effect, specifies one or more models on which to perform incremental inference. Its data type is SEM_MODELS, which has the following definition: TABLE OF VARCHAR2(25)

The triples in the first model in delta_in are copied to the first model in models_in, and the entailment (rules index) in rules_index_in is updated; then the triples in the second model (if any) in delta_in are copied to the second model (if any) in models_in, and the entailment in rules_index_in is updated; and so on until all triples are copied and the entailment is updated. (The delta_in parameter has no effect if incremental inference is not enabled for the entailment.)

label_gen

An instance of MDSYS.RDFSA_LABELGEN or a subtype of it, defining the logic for generating Oracle Label Security (OLS) labels for inferred triples. What you specify for this parameter depends on whether you use the default label generator or a custom label generator:

• If you use the default label generator, specify one of the following constants: SEM_RDFSA.LABELGEN_RULE for Use Rule Label, SEM_RDFSA.LABELGEN_SUBJECT for Use Subject Label, SEM_RDFSA.LABELGEN_PREDICATE for Use Predicate Label, SEM_RDFSA.LABELGEN_OBJECT for Use Object Label, SEM_RDFSA.LABELGEN_DOMINATING for Use Dominating Label, SEM_RDFSA.LABELGEN_ANTECED for Use Antecedent Labels. For a detailed explanation of each constant, see Section 5.2.4.

• If you use a custom label generator, specify the custom label generator type. For information about creating and implementing a custom label generator, see Section 5.2.5.

Usage Notes

For the inf_components_in parameter, you can specify any combination of the following keywords: SCOH, COMPH, DISJH, SYMMH, INVH, SPIH, MBRH, SPOH, DOMH, RANH, EQCH, EQPH, FPH, IFPH, DOM, RAN, SCO, DISJ, COMP, INV, SPO, FP, IFP, SYMM, TRANS, DIF, SAM, CHAIN, HASKEY, ONEOF, INTERSECT, INTERSECTSCOH, MBRLST, PROPDISJH, SKOSAXIOMS, SNOMED, SVFH, THINGH, THINGSAM, UNION, RDFP1, RDFP2, RDFP3, RDFP4, RDFP6, RDFP7, RDFP8AX, RDFP8BX, RDFP9, RDFP10, RDFP11, RDFP12A, RDFP12B, RDFP12C, RDFP13A, RDFP13B, RDFP13C, RDFP14A, RDFP14BX, RDFP15, RDFP16, RDFS2, RDFS3, RDFS4a, RDFS4b, RDFS5, RDFS6, RDFS7, RDFS8, RDFS9, RDFS10, RDFS11, RDFS12, RDFS13. For an explanation of the meaning of these keywords, see Table 7-1, where the keywords are listed in alphabetical order.

The default set of inference components for the OWLPrime vocabulary includes the following: SCOH, COMPH, DISJH, SYMMH, INVH, SPIH, SPOH, DOMH, RANH, EQCH, EQPH, FPH, IFPH, SAMH, DOM, RAN, SCO, DISJ, COMP, INV, SPO, FP, IFP, SYMM, TRANS, DIF, RDFP14A, RDFP14BX, RDFP15, RDFP16. However, note the following:

• Component SAM is not in this default OWLPrime list, because it tends to generate many new triples for some ontologies.

• Effective with Release 11.2, the native OWL inference engine supports the following new inference components: CHAIN, HASKEY, INTERSECT, INTERSECTSCOH, MBRLST, ONEOF, PROPDISJH, SKOSAXIOMS, SNOMED, SVFH, THINGH, THINGSAM, UNION. However, for backward compatibility, the OWLPrime rulebase and any existing rulebases do not include these new components by default; instead, to use these new inference components, you must specify them explicitly, and they are included in Table 7-1. The following example creates an OWLPrime entailment for two OWL ontologies named LUBM and UNIV. Because of the additional inference components specified, this entailment will include the new semantics introduced in those inference components.

  EXECUTE sem_apis.create_entailment('lubm1000_idx',sem_models('lubm','univ'),
      sem_rulebases('owlprime'), SEM_APIS.REACH_CLOSURE, 
      'INTERSECT,INTERSECTSCOH,SVFH,THINGH,THINGSAM,UNION');
  

To deselect a component, use the component name followed by a minus (-) sign. For example, SCOH- deselects inference of the subClassOf hierarchy.

For the options parameter, you can enable the following options to override the default inferencing behavior:

• COL_COMPRESS=T uses hybrid columnar compression to create temporary, intermediate working tables. This option can reduce the space required for such tables, and can improve the performance of the CREATE_ENTAILMENT operation with large data sets.

  Note:

  You can specify COL_COMPRESS=T only if the storage is on Exadata Storage Server.

• DISTANCE=T generates ancillary distance information that is useful for semantic operators.

• DOP=n specifies the degree of parallelism for parallel inference, which can improve inference performance. For information about parallel inference, see Section 2.2.10.

• ENTAIL_ANYWAY=T forces OWL inferencing to proceed and reuse existing inferred data (entailment) when the entailment has a valid status. By default, SEM_APIS.CREATE_ENTAILMENT quits immediately if there is already a valid entailment for the combination of models and rulebases.

• HASH_PART=n creates the specified number of hash partitions for internal working tables. (The number must be a power of 2: 2, 4, 8, 16, 32, and so on.) You may want to specify a value if there are many distinct predicates in the semantic data model. In Oracle internal testing on benchmark ontologies, HASH_PART=32 worked well.

• INC=T enables incremental inference for the entailment. For information about incremental inference, see Section 2.2.9.

• OPT_SAMEAS=T uses consolidated owl:sameAs entailment for the entailment. If you specify this option, you cannot specify PROOF=T. For information about optimizing owl:sameAs inference, see Section 2.2.8.

• RAW8=T uses RAW8 datatypes for the auxiliary inference tables. This option can improve entailment performance by up to 30% in some cases.

• PROOF=T generates proof for inferred triples. Do not specify this option unless you need to; it slows inference performance because it causes more data to be generated. If you specify this option, you cannot specify OPT_SAMEAS=T.

• USER_RULES=T causes any user-defined rules to be applied. If you specify this option, you cannot specify PROOF=T or DISTANCE=T, and you must accept the default value for the passes parameter.

For the delta_in parameter, inference performance is best if the value is small compared to the overall size of those models. In a typical scenario, the best results might be achieved when the delta contains fewer than 10,000 triples; however, some tests have shown significant inference performance improvements with deltas as large as 100,000 triples.

For the label_gen parameter, if you want to use the default OLS label generator, specify the appropriate SEM_RDFSA package constant value from Table 7-2.

Fine-Grained Access Control (VPD and OLS) Considerations

When fine-grained access control is enabled for a specific model using VPD or for the entire network using OLS, only a user with FULL access privileges to the associated policy may create an entailment. Full access privileges to a VPD policy are granted by setting the context attribute defined by the package constant sem_rdfsa.VPD_FULL_ACCESS to 1 for the namespace associated with the VPD policy (see Section 5.1.1, "VPD Policy for RDF Data"). When OLS is enabled, full access privileges to the OLS policy are granted using the SA_USER_ADMIN.SET_USER_PRIVS procedure. VPD policy is automatically enforced for any entailment created using at least one VPD enabled RDF model. As discussed in Section 5.1.1, the RDF metadata associated with the VPD policy may need to be maintained using the newly inferred data to ensure that the predefined VPD policies are not circumvented using inferred data.

Inferred triples accessed through generated labels might not be same as conceptual triples inferred directly from the user accessible triples and rules. The labels generated using a subset of triple components may be weaker than intended. For example, one of the antecedents for the inferred triple may have a higher label than any of the components of the triple. When the label is generated based on just the triple components, end users with no access to one of the antecedents may still have access to the inferred triple. Even when the antecedents are used for custom label generation, the generated label may be stronger than intended. The inference process is not exhaustive, and information pertaining to any alternate ways of inferring the same triple is not available. So, the label generated using a given set of antecedents may be too strong, because the user with access to all the triples in the alternate path could infer the triple with lower access.

Even when generating a label that dominates all its components and antecedents, the label may not be precise. This is the case when labels considered for dominating relationship have non-overlapping group information. For example, consider two labels L:C:NY and L:C:NH where L is a level, C is a component and NY and NH are two groups. A simple label that dominates these two labels is L:C:NY,NH, and a true supremum for the two labels is L:C:US, where US is parent group for both NY and NH. Unfortunately, neither of these two dominating labels is precise for the triple inferred from the triples with first two labels. If L:C:NY,NH is used for the inferred triple, a user with membership in either of these groups has access to the inferred triple, whereas the same user does not have access to one of its antecedents. On the other hand, if L:C:US is used for the inferred triple, a user with membership in both the groups and not in the US group will not be able to access the inferred triple, whereas that user could infer the triple by directly accessing its components and antecedents.

Because of these unique challenges with inferred triples, extra caution must be taken when choosing or implementing the label generator.

See also the OLS example in the Examples section.

Examples

The following example creates an entailment named OWLTST_IDX using the OWLPrime rulebase, and it causes proof to be generated for inferred triples.

EXECUTE sem_apis.create_entailment('owltst_idx', sem_models('owltst'), sem_rulebases('OWLPRIME'), SEM_APIS.REACH_CLOSURE, null, 'PROOF=T');

The following example assumes an OLS environment. It creates a rulebase with a rule, and it creates an entailment.

-- Create an entailment with a rule. -- 
exec sdo_rdf_inference.create_entailment('contracts_rb');
 
insert into mdsys.rdfr_contracts_rb values (
  'projectLedBy', '(?x :drivenBy ?y) (?y :hasVP ?z)',  NULL,
  '(?x :isLedBy ?z)',
  SDO_RDF_Aliases(SDO_RDF_Alias('','http://www.myorg.com/pred/')));
 
-- Assign sensitivity label for the predicate to be inferred. -- 
-- Yhe predicate label may be set globally or it can be assign to --
-- the one or the models used to infer the data – e.g: CONTRACTS. 
begin
  sem_rdfsa.set_predicate_label(
         model_name   => 'rdf$global',
         predicate    => 'http://www.myorg.com/pred/isLedBy',
         label_string => 'TS:US_SPCL');
end;
/
 
-- Create index with a specific label generator. -- 
begin
  sem_apis.create_entailment(
         entailment_name_in => 'contracts_inf',
         models_in          => SDO_RDF_Models('contracts'),
         rulebases_in       => SDO_RDF_Rulebases('contracts_rb'),
         options            => 'USER_RULES=T',
         label_gen          => sem_rdfsa.LABELGEN_PREDICATE);
end;
/
 
-- Check for any label exceptions and update them accordingly. -- 
update mdsys.rdfi_contracts_inf set ctxt1 = 1100 where ctxt1 = -1;
 
-- The new entailment is now ready for use in SEM_MATCH queries. --

SEM_APIS.CREATE_RULEBASE

Format

SEM_APIS.CREATE_RULEBASE(

     rulebase_name IN VARCHAR2);

Description

Creates a rulebase.

Parameters

rulebase_name

Name of the rulebase.

Usage Notes

This procedure creates a user-defined rulebase. After creating the rulebase, you can add rules to it. To cause the rules in the rulebase to be applied in a query of RDF data, you can specify the rulebase in the call to the SEM_MATCH table function.

Rules and rulebases are explained in Section 1.3.6. The SEM_MATCH table function is described in Section 1.6,

Examples

The following example creates a rulebase named family_rb. (It is an excerpt from Example 1-20 in Section 1.10.2.)

EXECUTE SEM_APIS.CREATE_RULEBASE('family_rb');

SEM_APIS.CREATE_SEM_MODEL

Format

SEM_APIS.CREATE_SEM_MODEL(

     model_name IN VARCHAR2,

     table_name IN VARCHAR2,

     column_name IN VARCHAR2,

     model_tablespace IN VARCHAR2 DEFAULT NULL);

Description

Creates a semantic technology model.

Parameters

model_name

Name of the model.

table_name

Name of the table to hold references to semantic technology data for this model.

column_name

Name of the column of type SDO_RDF_TRIPLE_S in table_name.

model_tablespace

Name of the tablespace for the tables and other database objects used by Oracle to support this model. The default value is the tablespace that was specified in the call to the SEM_APIS.CREATE_SEM_NETWORK procedure.

Usage Notes

You must create the table to hold references to semantic technology data before calling this procedure to create the semantic technology model. For more information, see Section 1.9.

This procedure adds the model to the MDSYS.SEM_MODEL$ view, which is described in Section 1.3.1.

This procedure is the only supported way to create a model. Do not use SQL INSERT statements with the MDSYS.SEM_MODEL$ view.

To delete a model, use the SEM_APIS.DROP_SEM_MODEL procedure.

Examples

The following example creates a semantic technology model named articles. References to the triple data for the model will be stored in the TRIPLE column of the ARTICLES_RDF_DATA table. (This example is an excerpt from Example 1-19 in Section 1.10.2.)

EXECUTE SEM_APIS.CREATE_SEM_MODEL('articles', 'articles_rdf_data', 'triple');

The definition of the ARTICLES_RDF_DATA table is as follows:

CREATE TABLE articles_rdf_data (id NUMBER, triple SDO_RDF_TRIPLE_S);

SEM_APIS.CREATE_SEM_NETWORK

Format

SEM_APIS.CREATE_SEM_NETWORK(

     tablespace_name IN VARCHAR2

Description

Creates structures for persistent storage of semantic data.

Parameters

tablespace_name

Name of the tablespace to be used for tables created by this procedure. This tablespace will be the default for all models that you create, although you can override the default when you create a model by specifying the model_tablespace parameter in the call to the SEM_APIS.CREATE_SEM_MODEL procedure.

Usage Notes

This procedure creates system tables and other database objects used for semantic technology support.

You should create a tablespace for the semantic technology system tables and specify the tablespace name in the call to this procedure. (You should not specify the SYSTEM tablespace.) The size needed for the tablespace that you create will depend on the amount of semantic technology data you plan to store.

You must connect to the database as a user with DBA privileges in order to call this procedure, and you should call the procedure only once for the database.

To drop these structures for persistent storage of semantic data, you must connect as a user with DBA privileges and call the SEM_APIS.DROP_SEM_NETWORK procedure.

Examples

The following example creates a tablespace for semantic technology system tables and creates structures for persistent storage of semantic data in this tablespace.

CREATE TABLESPACE rdf_tblspace
 DATAFILE '/oradata/orcl/rdf_tblspace.dat' SIZE 1024M REUSE
 AUTOEXTEND ON NEXT 256M MAXSIZE UNLIMITED
 SEGMENT SPACE MANAGEMENT AUTO;
. . .
EXECUTE SEM_APIS.CREATE_SEM_NETWORK('rdf_tblspace');

SEM_APIS.CREATE_VIRTUAL_MODEL

Format

SEM_APIS.CREATE_VIRTUAL_MODEL(

     vm_name IN VARCHAR2,

     models IN SEM_MODELS,

     rulebases IN SEM_RULEBASES DEFAULT NULL,

     options IN VARCHAR2 DEFAULT NULL);

Description

Creates a virtual model containing the specified semantic models and rulebases.

Parameters

vm_name

Name of the virtual model to be created.

models

One or more semantic model names. Its data type is SEM_MODELS, which has the following definition: TABLE OF VARCHAR2(25). At least one semantic model must be specified.

rulebases

One or more rulebase names. Its data type is SEM_RULEBASES, which has the following definition: TABLE OF VARCHAR2(25). If this parameter is null, no rulebases are included in the virtual model definition. Rules and rulebases are explained in Section 1.3.6.

options

(Reserved for future use.)

Usage Notes

For an explanation of virtual models, including usage information, see Section 1.3.8.

An entailment must exist for each specified combination of semantic model and rulebase.

To create a virtual model, you must either be (A) the owner of each specified model and any corresponding entailments, or (B) a user with DBA privileges.

This procedure creates views with names in the following format:

• SEMV_vm_name, which corresponds to a UNION ALL of the triples in each model and entailment. This view may contain duplicates.

• SEMU_vm_name, which corresponds to a UNION of the triples in each model and entailment. This view will not contain duplicates (thus, the U in SEMU indicates unique).

  However, the SEMU_vm_name view is not created if the virtual model contains only one semantic model and no entailment.

To use the example in Section 1.3.8 of a virtual model vm1 created from models m1, m2, m3, and with an entailment created for m1, m2 ,and m3 using the OWLPrime rulebase, this procedure will create the following two views (assuming that m1, m2, and m3, and the OWLPRIME entailment have internal model_id values 1, 2, 3, 4):

CREATE VIEW MDSYS.SEMV_VM1 AS
  SELECT start_node_id, p_value_id, canon_end_node_id, end_node_id
  FROM MDSYS.rdf_link$
  WHERE model_id IN (1, 2, 3, 4);
 
CREATE VIEW MDSYS.SEMU_VM1 AS
  SELECT start_node_id, p_value_id, canon_end_node_id, MAX(end_node_id)
  FROM MDSYS.rdf_link$
  WHERE model_id IN (1, 2, 3, 4)
  GROUP BY start_node_id, p_value_id, canon_end_node_id;

The user that invokes this procedure will be the owner of the virtual model and will have SELECT WITH GRANT privileges on the SEMU_vm_name and SEMV_vm_name views. To query the corresponding virtual model, a user must have select privileges on these views.

Examples

The following example creates a virtual model named VM1.

EXECUTE sem_apis.create_virtual_model('VM1', sem_models('model_1', 'model_2'), sem_rulebases('OWLPRIME'));

SEM_APIS.DISABLE_CHANGE_TRACKING

Format

SEM_APIS.DISABLE_CHANGE_TRACKING(

     models_in IN SEM_MODELS);

Description

Disables change tracking for a specified set of models.

Parameters

models_in

One or more model names. Its data type is SEM_MODELS, which has the following definition: TABLE OF VARCHAR2(25)

Usage Notes

Disabling change tracking on a model automatically disables incremental inference on all entailment that use the model.

To use this procedure, you must be the owner of the specified model, and incremental inference must have been previously enabled.

For an explanation of incremental inference, including usage information, see Section 2.2.9.

Examples

The following example disables change tracking for the family model.

EXECUTE sem_apis.disable_change_tracking(sem_models('family'));

SEM_APIS.DISABLE_INC_INFERENCE

Format

SEM_APIS.DISABLE_INC_INFERENCE(

     entailment_name IN VARCHAR2);

Description

Disables incremental inference for a specified entailment (rules index).

Parameters

entailment_name

Name of the entailment for which to disable incremental inference.

Usage Notes

To use this procedure, you must be the owner of the specified entailment, and incremental inference must have been previously enabled by the SEM_APIS.ENABLE_INC_INFERENCE procedure.

Calling this procedure automatically disables change tracking for all models owned by the invoking user that were having changes tracked only because of this particular inference.

For an explanation of incremental inference, including usage information, see Section 2.2.9.

Examples

The following example enables incremental inference for the entailment named RDFS_RIX_FAMILY.

EXECUTE sem_apis.disable_inc_inference('rdfs_rix_family');

SEM_APIS.DROP_ENTAILMENT

Format

SEM_APIS.DROP_ENTAILMENT(

     entailment_name_in IN VARCHAR2);

Description

Drops (deletes) an entailment (rules index).

Parameters

entailment_name_in

Name of the entailment to be deleted.

Usage Notes

You can use this procedure to delete an entailment that you created using the SEM_APIS.CREATE_ENTAILMENT procedure.

Examples

The following example deletes a entailment named OWLTST_IDX.

EXECUTE sem_apis.drop_entailment('owltst_idx');

SEM_APIS.DROP_RULEBASE

Format

SEM_APIS.DROP_RULEBASE(

     rulebase_name IN VARCHAR2);

Description

Deletes a rulebase.

Parameters

rulebase_name

Name of the rulebase.

Usage Notes

This procedure deletes the specified rulebase, making it no longer available for use in calls to the SEM_MATCH table function. For information about rulebases, see Section 1.3.6.

Only the creator of a rulebase can delete the rulebase.

Examples

The following example drops the rulebase named family_rb.

EXECUTE SEM_APIS.DROP_RULEBASE('family_rb');

SEM_APIS.DROP_SEM_INDEX

Format

SEM_APIS.DROP_SEM_INDEX(

     index_code IN VARCHAR2);

Description

Drops a semantic network index on the models and entailments of the semantic network.

Parameters

index_code

Index code string. Must match the index_code value that was specified in an earlier call to the SEM_APIS.ADD_SEM_INDEX procedure.

Usage Notes

For an explanation of semantic network indexes, see Section 1.8.

Examples

The following example drops a semantic network index with the index code string pcsm on the models and entailments of the semantic network.

EXECUTE SEM_APIS.DROP_SEM_INDEX('pscm');

SEM_APIS.DROP_SEM_MODEL

Format

SEM_APIS.DROP_SEM_MODEL(

     model_name IN VARCHAR2);

Description

Drops (deletes) a semantic technology model.

Parameters

model_name

Name of the model.

Usage Notes

This procedure deletes the model from the MDSYS.SEM_MODEL$ view, which is described in Section 1.3.1.

This procedure is the only supported way to delete a model. Do not use SQL DELETE statements with the MDSYS.SEM_MODEL$ view.

Only the creator of a model can delete the model.

Examples

The following example drops the semantic technology model named articles.

EXECUTE SEM_APIS.DROP_SEM_MODEL('articles');

SEM_APIS.DROP_SEM_NETWORK

Format

SEM_APIS.DROP_SEM_NETWORK(

     cascade IN BOOLEAN DEFAULT FALSE);

Description

Removes structures used for persistent storage of semantic data.

Parameters

cascade

TRUE drops any existing semantic technology models and rulebases, and removes structures used for persistent storage of semantic data; FALSE (the default) causes the operation to fail if any semantic technology models or rulebases exist.

Usage Notes

To remove structures used for persistent storage of semantic data, you must connect as a user with DBA privileges and call this procedure.

If any version-enabled models exist, this procedure will fail regardless of the value of the cascade parameter.

Examples

The following example removes structures used for persistent storage of semantic data.

EXECUTE SEM_APIS.DROP_SEM_NETWORK;

SEM_APIS.DROP_USER_INFERENCE_OBJS

Format

SEM_APIS.DROP_USER_INFERENCE_OBJS(

     uname IN VARCHAR2);

Description

Drops (deletes) all rulebases and entailments owned by a specified database user.

Parameters

uname

Name of a database user. (This value is case-sensitive; for example, HERMAN and herman are considered different users.)

Usage Notes

You must have sufficient privileges to delete rules and rulebases for the specified user.

This procedure does not delete the database user. It deletes only RDF rulebases and entailments owned by that user.

Examples

The following example deletes all rulebases and entailments owned by user SCOTT.

EXECUTE SEM_APIS.DROP_USER_INFERENCE_OBJS('SCOTT');
 
PL/SQL procedure successfully completed.

SEM_APIS.DROP_VIRTUAL_MODEL

Format

SEM_APIS.DROP_VIRTUAL_MODEL(

     vm_name IN VARCHAR2);

Description

Drops (deletes) a virtual model.

Parameters

vm_name

Name of the virtual model to be deleted.

Usage Notes

You can use this procedure to delete a virtual model that you created using the SEM_APIS.CREATE_VIRTUAL_MODEL procedure. A virtual model is deleted automatically if any of its component models, rulebases, or entailment are deleted.

To use this procedure, you must be the owner of the specified virtual model.

For an explanation of virtual models, including usage information, see Section 1.3.8.

Examples

The following example deletes a virtual model named VM1.

EXECUTE sem_apis.drop_virtual_model('VM1');

SEM_APIS.ENABLE_CHANGE_TRACKING

Format

SEM_APIS.ENABLE_CHANGE_TRACKING(

     models_in IN SEM_MODELS);

Description

Enables change tracking for a specified set of models.

Parameters

models_in

One or more model names. Its data type is SEM_MODELS, which has the following definition: TABLE OF VARCHAR2(25)

Usage Notes

Change tracking must be enabled on a model before incremental inference can be enabled on any entailments that use the model.

To use this procedure, you must be the owner of the specified model or models.

If the owner of an entailment is also an owner of any underlying models, then enabling incremental inference on the entailment (by calling the SEM_APIS.ENABLE_INC_INFERENCE procedure) automatically enables change tracking on those models owned by that user.

To disable change tracking for a set of models, use the SEM_APIS.DISABLE_CHANGE_TRACKING procedure.

For an explanation of incremental inference, including usage information, see Section 2.2.9.

Examples

The following example enables change tracking for the family model.

EXECUTE sem_apis.enable_change_tracking(sem_models('family'));

SEM_APIS.ENABLE_INC_INFERENCE

Format

SEM_APIS.ENABLE_INC_INFERENCE(

     entailment_name IN VARCHAR2);

Description

Enables incremental inference for a specified entailment (rules index).

Parameters

entailment_name

Name of the entailment for which to enable incremental inference.

Usage Notes

To use this procedure, you must be the owner of the specified entailment.

Before this procedure is executed, all underlying models involved in the entailment must have change tracking enabled. If the owner of the entailment is also an owner of any underlying models, calling this procedure automatically enables change tracking on those models. However, if some underlying model are not owned by the owner of the entailment, the appropriate model owners must first call the SEM_APIS.ENABLE_CHANGE_TRACKING procedure to enable change tracking on those models.

To disable incremental inference for an entailment, use the SEM_APIS.DISABLE_INC_INFERENCE procedure.

For an explanation of incremental inference, including usage information, see Section 2.2.9.

Examples

The following example enables incremental inference for the entailment named RDFS_RIX_FAMILY.

EXECUTE sem_apis.enable_inc_inference('rdfs_rix_family');

SEM_APIS.GET_CHANGE_TRACKING_INFO

Format

SEM_APIS.GET_CHANGE_TRACKING_INFO(

     model_name IN VARCHAR2,

     enabled OUT BOOLEAN,

     tracking_start_time OUT TIMESTAMP);

Description

Returns change tracking information for a model.

Parameters

model_name

Name of the semantic technology model.

enabled

Boolean value returned by the procedure: TRUE if change tracking is enabled for the model, or FALSE if change tacking is not enabled for the model.

timestamp

Timestamp indicating when change tracking was enabled for the model (if it is enabled).

Usage Notes

The model_name value must match a value in the MODEL_NAME column in the MDSYS.SEM_MODEL$ view, which is described in Section 1.3.1.

To enable change tracking for a set of models, use the SEM_APIS.ENABLE_CHANGE_TRACKING procedure.

For an explanation of incremental inference, including usage information, see Section 2.2.9.

Examples

The following example displays change tracking information for a model.

DECLARE 
  bEnabled  boolean;
  tsEnabled  timestamp;
  
BEGIN
  EXECUTE IMMEDIATE 'create table m1 (t SDO_RDF_TRIPLE_S)';
  sem_apis.create_sem_model('m1','m1','t');
 
  sem_apis.enable_change_tracking(sem_models('m1'));
 
  sem_apis.get_change_tracking_info('m1', bEnabled,  tsEnabled);
  dbms_output.put_line('is enabled:' || case when bEnabled then 'true' else 'false' end);
  dbms_output.put_line('enabled at:' || tsEnabled);
END;
/

SEM_APIS.GET_INC_INF_INFO

Format

SEM_APIS.GET_INC_INF_INFO(

     entailment_name IN VARCHAR2,

     enabled OUT BOOLEAN,

     prev_inf_start_time OUT TIMESTAMP);

Description

Returns incremental inference information for an entailment.

Parameters

entailment_name

Name of the entailment.

enabled

Boolean value returned by the procedure: TRUE if incremental inference is enabled for the entailment, or FALSE if incremental inference is not enabled for the entailment.

timestamp

Timestamp indicating when the entailment was most recently updated (if incremental inference is enabled).

Usage Notes

To enable incremental inference for an entailment, use the SEM_APIS.ENABLE_INC_INFERENCE procedure.

For an explanation of incremental inference, including usage information, see Section 2.2.9.

Examples

The following example displays incremental inference information for an entailment.

DECLARE 
  bEnabled boolean;
  tsEnabled timestamp;
  
DECLARE 
  EXECUTE IMMEDIATE 'create table m1 (t SDO_RDF_TRIPLE_S)';
  sem_apis.create_sem_model('m1','m1','t');
 
  sem_apis.create_entailment('m1_inf',sem_models('m1'), 
sem_rulebases('owlprime'),null,null,'INC=T');
 
  sem_apis.get_inc_inf_info('m1_inf', bEnabled,  tsEnabled);
  dbms_output.put_line('is enabled:' || case when bEnabled then 'true' else 'false' 
  end);
  dbms_output.put_line('enabled at:' || tsEnabled);
END
/

SEM_APIS.GET_MODEL_ID

Format

SEM_APIS.GET_MODEL_ID(

     model_name IN VARCHAR2

     ) RETURN NUMBER;

Description

Returns the model ID number of a semantic technology model.

Parameters

model_name

Name of the semantic technology model.

Usage Notes

The model_name value must match a value in the MODEL_NAME column in the MDSYS.SEM_MODEL$ view, which is described in Section 1.3.1.

Examples

The following example returns the model ID number for the model named articles. (This example is an excerpt from Example 1-19 in Section 1.10.2.)

SELECT SEM_APIS.GET_MODEL_ID('articles') AS model_id FROM DUAL;
 
  MODEL_ID
----------
         1

SEM_APIS.GET_MODEL_NAME

Format

SEM_APIS.GET_MODEL_NAME(

     model_id IN NUMBER

     ) RETURN VARCHAR2;

Description

Returns the model name of a semantic technology model.

Parameters

model_id

ID number of the semantic technology model.

Usage Notes

The model_id value must match a value in the MODEL_ID column in the MDSYS.SEM_MODEL$ view, which is described in Section 1.3.1.

Examples

The following example returns the model ID number for the model with the ID value of 1. This example is an excerpt from Example 1-19 in Section 1.10.2.)

SQL> SELECT SEM_APIS.GET_MODEL_NAME(1) AS model_name FROM DUAL;
 
MODEL_NAME                                                       
--------------------------------------------------------------------------------
ARTICLES                                                           

SEM_APIS.GET_TRIPLE_ID

Format

SEM_APIS.GET_TRIPLE_ID(

     model_id IN NUMBER,

     subject IN VARCHAR2,

     property IN VARCHAR2,

     object IN VARCHAR2

     ) RETURN VARCHAR2;

or

SEM_APIS.GET_TRIPLE_ID(

     model_name IN VARCHAR2,

     subject IN VARCHAR2,

     property IN VARCHAR2,

     object IN VARCHAR2

     ) RETURN VARCHAR2;

Description

Returns the ID of a triple in the specified semantic technology model, or a null value if the triple does not exist.

Parameters

model_id

ID number of the semantic technology model. Must match a value in the MODEL_ID column of the MDSYS.SEM_MODEL$ view, which is described in Section 1.3.1.

model_name

Name of the semantic technology model. Must match a value in the MODEL_NAME column of the MDSYS.SEM_MODEL$ view, which is described in Section 1.3.1.

subject

Subject. Must match a value in the VALUE_NAME column of the MDSYS.RDF_VALUE$ table, which is described in Section 1.3.2.

property

Property. Must match a value in the VALUE_NAME column of the MDSYS.RDF_VALUE$ table, which is described in Section 1.3.2.

object

Object. Must match a value in the VALUE_NAME column of the MDSYS.RDF_VALUE$ table, which is described in Section 1.3.2.

Usage Notes

This function has two formats, enabling you to specify the semantic technology model by its model number or its name.

Examples

The following example returns the ID number of a triple. (This example is an excerpt from Example 1-19 in Section 1.10.2.)

SELECT SEM_APIS.GET_TRIPLE_ID(
  'articles',
  'http://nature.example.com/Article2',
  'http://purl.org/dc/terms/references',
  'http://nature.example.com/Article3') AS RDF_triple_id FROM DUAL;
 
RDF_TRIPLE_ID
--------------------------------------------------------------------------------
2_9F2BFF05DA0672E_90D25A8B08C653A_46854582F25E8AC5

SEM_APIS.IS_TRIPLE

Format

SEM_APIS.IS_TRIPLE(

     model_id IN NUMBER,

     subject IN VARCHAR2,

     property IN VARCHAR2,

     object IN VARCHAR2) RETURN VARCHAR2;

or

SEM_APIS.IS_TRIPLE(

     model_name IN VARCHAR2,

     subject IN VARCHAR2,

     property IN VARCHAR2,

     object IN VARCHAR2) RETURN VARCHAR2;

Description

Checks if a statement is an existing triple in the specified model in the database.

Parameters

model_id

ID number of the semantic technology model. Must match a value in the MODEL_ID column of the MDSYS.SEM_MODEL$ view, which is described in Section 1.3.1.

model_name

Name of the semantic technology model. Must match a value in the MODEL_NAME column of the MDSYS.SEM_MODEL$ view, which is described in Section 1.3.1.

subject

Subject. Must match a value in the VALUE_NAME column of the MDSYS.RDF_VALUE$ table, which is described in Section 1.3.2.

property

Property. Must match a value in the VALUE_NAME column of the MDSYS.RDF_VALUE$ table, which is described in Section 1.3.2.

object

Object. Must match a value in the VALUE_NAME column of the MDSYS.RDF_VALUE$ table, which is described in Section 1.3.2.

Usage Notes

This function returns the string value FALSE, TRUE, or TRUE (EXACT):

• FALSE means that the statement is not a triple in the specified model the database.

• TRUE means that the statement matches the value of a triple or is the canonical representation of the value of a triple in the specified model the database.

• TRUE (EXACT) means that the specified subject, property, and object values have exact matches in a triple in the specified model in the database.

Examples

The following checks if a statement is a triple in the database. In this case, there is an exact match. (This example is an excerpt from Example 1-19 in Section 1.10.2.)

SELECT SEM_APIS.IS_TRIPLE(
  'articles',
  'http://nature.example.com/Article2',
  'http://purl.org/dc/terms/references',
  'http://nature.example.com/Article3') AS is_triple FROM DUAL;
 
IS_TRIPLE                                                                       
--------------------------------------------------------------------------------
TRUE (EXACT)

SEM_APIS.LOOKUP_ENTAILMENT

Format

SEM_APIS.LOOKUP_ENTAILMENT (

     models IN SEM_MODELS,

     rulebases IN SEM_RULEBASES

     ) RETURN VARCHAR2;

Description

Returns the name of the entailment (rules index) based on the specified models and rulebases.

Parameters

models

One or more model names. Its data type is SEM_MODELS, which has the following definition: TABLE OF VARCHAR2(25)

rulebases

One or more rulebase names. Its data type is SEM_RULEBASES, which has the following definition: TABLE OF VARCHAR2(25)Rules and rulebases are explained in Section 1.3.6.

Usage Notes

For a rulebase index to be returned, it must be based on all specified models and rulebases.

Examples

The following example finds the entailment that is based on the family model and the RDFS and family_rb rulebases. (It is an excerpt from Example 1-20 in Section 1.10.2.)

SELECT SEM_APIS.LOOKUP_ENTAILMENT(SEM_MODELS('family'),
  SEM_RULEBASES('RDFS','family_rb')) AS lookup_entailment FROM DUAL;

LOOKUP_ENTAILMENT
--------------------------------------------------------------------------------
RDFS_RIX_FAMILY

SEM_APIS.MERGE_MODELS

Format

SEM_APIS.MERGE_MODELS(

     source_model IN VARCHAR2,

     destination_model IN VARCHAR2,

     rebuild_apptab_index IN BOOLEAN DEFAULT TRUE,

     drop_source_model IN BOOLEAN DEFAULT FALSE,

     options IN VARCHAR2 DEFAULT NULL);

Description

Inserts the content from a source model into a destination model, and updates the destination application table.

Parameters

source_model

Name of the source model.

destination_model

Name of the destination model.

rebuild_apptab_index

TRUE causes indexes on the destination application table to be rebuilt after the models are merged; FALSE does not rebuild any indexes.

drop_source_model

TRUE causes the source model (source_model) to be deleted after the models are merged; FALSE (the default) does not delete the source model.

options

A comma-delimited string of options that overrides the default behavior of the procedure. Currently, only the DOP (degree of parallelism) option is supported, to enable parallel execution of this procedure and to specify the degree of parallelism to be associated with the operation.

Usage Notes

Before you merge any models, if you are using positional parameters, check to be sure that you are specifying the correct models for the first and second parameters (source model for the first, destination model for the second). This is especially important if you plan to specify drop_source_model=TRUE.

If appropriate, make copies of the destination model or both models before performing the merge. To make a copy of a model, use SEM_APIS.CREATE_SEM_MODEL to create an empty model with the desired name for the copy, and use SEM_APIS.MERGE_MODELS to populate the newly created copy as the destination model.

Some common uses for this procedure include the following:

• If you have read-only access to a model that you want to modify, you can clone that model into an empty model on which you have full access, and then modify this latter model.

• If you want to consolidate multiple models, you can use this procedure as often as necessary to merge the necessary models. Merging all models beforehand and using only the merged model simplifies entailment and can improve entailment performance.

On a multi-core or multi-cpu machine, the DOP (degree of parallelism) option can be beneficial. See Examples for an example that uses the DOP option.

If the source model is large, you may want to update the optimizer statistics on the destination after the merge operation by calling the SEM_APIS.ANALYZE_MODEL procedure.

The following considerations apply to the use of this procedure:

• You must be the owner of the destination model and have SELECT privilege on the source model. If drop_second_model=TRUE, you must also be owner of the source model.

• This procedure cannot be used on VPD-enabled or versioning-enabled semantic models.

• This procedure is not supported on virtual models (explained in Section 1.3.8).

• No table constraints are allowed on the destination application table.

Examples

The following example inserts the contents of model M1 into M2.

EXECUTE SEM_APIS.MERGE_MODELS('M1', 'M2');

The following example inserts the contents of model M1 into M2, and it specifies a degree of parallelism of 4 (up to four parallel threads for execution of the merge operation).

EXECUTE SEM_APIS.MERGE_MODELS('M1', 'M2', null, null, 'DOP=4');

SEM_APIS.REMOVE_DUPLICATES

Format

SEM_APIS.REMOVE_DUPLICATES(

     model_name IN VARCHAR2,

     threshold IN FLOAT DEFAULT 0.3,

     rebuild_apptab_index IN BOOLEAN DEFAULT TRUE);

Description

Removes duplicate triples from a model.

Parameters

model_name

Name of the model.

threshold

A value to determine how numerous triples must be in order for the removal operation to be performed. This procedure removes triples only if the number of triples in the model exceeds the following formula: (total-triples - total-unique-triples + 0.01) / (total-unique-triples + 0.01). For the default value of 0.3 and a model containing 1000 total triples (including duplicates), duplicate triples would be removed only if the number of duplicates exceeds approximately 230.

The lower the threshold value, the fewer duplicates are needed for the procedure to remove duplicates; the higher the threshold value, the more duplicates are needed for the procedure to remove duplicates.

rebuild_apptab_index

TRUE (the default) causes all usable indexes on tables that were affected by this operation to be rebuilt after the duplicate triples are removed; FALSE does not rebuild any indexes.

Usage Notes

When duplicate triples are removed, all information in the removed rows is lost, including information in columns other than the triple column.

This procedure is not supported on virtual models (explained in Section 1.3.8).

If the model is empty, or if it contains no duplicate triples or not enough duplicate triples (as computed using the threshold value), this procedure does not perform any removal operations.

If there are not enough duplicates (as computed using the threshold value) to perform the operation, an informational message is displayed.

Examples

The following example removes duplicate triples in the model named family. It accepts the default threshold value of 0.3 and (by default) rebuilds indexes after the duplicates are removed.

EXECUTE SEM_APIS.REMOVE_DUPLICATES('family');

SEM_APIS.RENAME_ENTAILMENT

Format

SEM_APIS.RENAME_ENTAILMENT(

     old_name IN VARCHAR2,

     new_name IN VARCHAR2);

Description

Renames an entailment (rules index).

Parameters

old_name

Name of the existing entailment to be renamed.

new_name

New name for the entailment.

Usage Notes

(None.)

Examples

The following example renames a entailment named OWLTST_IDX to MY_OWLTST_IDX.

EXECUTE sem_apis.rename_entailment('owltst_idx', 'my_owltst_idx');

SEM_APIS.RENAME_MODEL

Format

SEM_APIS.RENAME_MODEL(

     old_name IN VARCHAR2,

     new_name IN VARCHAR2);

Description

Renames a model.

Parameters

old_name

Name of the existing model to be renamed.

new_name

New name for the model.

Usage Notes

The following considerations apply to the use of this procedure:

• You must be the owner of the existing model.

• This procedure cannot be used on VPD-enabled or versioning-enabled semantic models.

• This procedure is not supported on virtual models (explained in Section 1.3.8).

Contrast this procedure with SEM_APIS.SWAP_NAMES, which swaps (exchanges) the names of two existing models.

Examples

The following example renames a model named MODEL1 to MODEL2.

EXECUTE sem_apis.rename_model('model1', 'model2');

SEM_APIS.SWAP_NAMES

Format

SEM_APIS.SWAP_NAMES(

     model1 IN VARCHAR2,

     model2 IN VARCHAR2);

Description

Swaps (exchanges) the names of two existing models.

Parameters

model1

Name of a model.

model2

Name of another model.

Usage Notes

As a result of this procedure, the name of model model1 is changed to the (old) name of model2, and the name of model model2 is changed to the (old) name of model1.

The order of the names does not affect the result. For example, you could specify TEST for model1 and PRODUCTION for model2, or PRODUCTION for model1 and TEST for model2, and the result will be the same.

Contrast this procedure with SEM_APIS.RENAME_MODEL, which renames an existing model.

Examples

The following example changes the name of the (old) TEST model to PRODUCTION, and the name of the (old) PRODUCTION model to TEST.

EXECUTE sem_apis.swap_names('test', 'production');

SEM_APIS.VALIDATE_ENTAILMENT

Format

SEM_APIS.VALIDATE_ENTAILMENT(

     models_in IN SEM_MODELS,

     rulebases_in IN SEM_RULEBASES,

     criteria_in IN VARCHAR2 DEFAULT NULL,

     max_conflict IN NUMBER DEFAULT 100,

     options IN VARCHAR2 DEFAULT NULL

     ) RETURN RDF_LONGVARCHARARRAY;

Description

Validates entailments (rules indexes) that can be used to perform OWL or RDFS inferencing for one or more models.

Parameters

models_in

One or more model names. Its data type is SEM_MODELS, which has the following definition: TABLE OF VARCHAR2(25)

rulebases_in

One or more rulebase names. Its data type is SEM_RULEBASES, which has the following definition: TABLE OF VARCHAR2(25). Rules and rulebases are explained in Section 1.3.6.

criteria_in

A comma-delimited string of validation checks to run. If you do not specify this parameter, by default all of the following checks are run:

• UNSAT: Find unsatisfiable classes.

• EMPTY: Find instances belong to unsatisfiable classes

• SYNTAX_S: Find triples whose subject is neither URI nor blank node.

• SYNTAX_P: Find triples whose predicate is not URI.

• SELF_DIF: Find individuals that are different from themselves.

• INST: Find individuals that simultaneously belong to two disjoint classes.

• SAM_DIF: Find pairs of individuals that are same (owl:sameAs) and different (owl:differentFrom) at the same time.

To specify fewer checks, specify a string with only the checks to be performed. For example, criteria_in => 'UNSAT' causes the validation process to search only for unsatisfiable classes.

max_conflict

The maximum number of conflicts to find before the validation process stops. The default value is 100.

options

(Not currently used. Reserved for Oracle use.).

Usage Notes

This procedure can be used to detect inconsistencies in the original entailment. For more information, see Section 2.2.5.

This procedure returns a null value if no errors are detected or (if errors are detected) an object of type RDF_LONGVARCHARARRAY, which has the following definition: VARRAY(32767) OF VARCHAR2(4000)

To create an entailment, use the SEM_APIS.CREATE_ENTAILMENT procedure.

Examples

For an example of this procedure, see Example 2-5 in Section 2.2.5.

SEM_APIS.VALIDATE_MODEL

Format

SEM_APIS.VALIDATE_MODEL(

     models_in IN SEM_MODELS,

     criteria_in IN VARCHAR2 DEFAULT NULL,

     max_conflict IN NUMBER DEFAULT 100,

     options IN VARCHAR2 DEFAULT NULL

     ) RETURN RDF_LONGVARCHARARRAY;

Description

Validates one or more models.

Parameters

models_in

One or more model names. Its data type is SEM_MODELS, which has the following definition: TABLE OF VARCHAR2(25)

criteria_in

A comma-delimited string of validation checks to run. If you do not specify this parameter, by default all of the following checks are run:

• UNSAT: Find unsatisfiable classes.

• EMPTY: Find instances belong to unsatisfiable classes

• SYNTAX_S: Find triples whose subject is neither URI nor blank node.

• SYNTAX_P: Find triples whose predicate is not URI.

• SELF_DIF: Find individuals that are different from themselves.

• INST: Find individuals that simultaneously belong to two disjoint classes.

• SAM_DIF: Find pairs of individuals that are same (owl:sameAs) and different (owl:differentFrom) at the same time.

To specify fewer checks, specify a string with only the checks to be performed. For example, criteria_in => 'UNSAT' causes the validation process to search only for unsatisfiable classes.

max_conflict

The maximum number of conflicts to find before the validation process stops. The default value is 100.

options

(Not currently used. Reserved for Oracle use.).

Usage Notes

This procedure can be used to detect inconsistencies in the original data model. For more information, see Section 2.2.5.

This procedure returns a null value if no errors are detected or (if errors are detected) an object of type RDF_LONGVARCHARARRAY, which has the following definition: VARRAY(32767) OF VARCHAR2(4000)

Examples

The following example validates the model named family.

SELECT SEM_APIS.VALIDATE_MODEL(SEM_MODELS('family')) FROM DUAL;

SEM_APIS.VALUE_NAME_PREFIX

Format

SEM_APIS.VALUE_NAME_PREFIX (

     value_name IN VARCHAR2,

     value_type IN VARCHAR2

     ) RETURN VARCHAR2;

Description

Returns the value in the VNAME_PREFIX column for the specified value name and value type pair in the MDSYS.RDF_VALUE$ table.

Parameters

value_name

Value name. Must match a value in the VALUE_NAME column in the MDSYS.RDF_VALUE$ table, which is described in Section 1.3.2.

value_type

Value type. Must match a value in the VALUE_TYPE column in the MDSYS.RDF_VALUE$ table, which is described in Section 1.3.2.

Usage Notes

This function usually causes an index on the MDSYS.RDF_VALUE$ table to be used for processing a lookup for values, and thus can make a query run faster.

Examples

The following query returns value name portions of all the lexical values in MDSYS.RDF_VALUE$ table with a prefix value same as that returned by the VALUE_NAME_PREFIX function. This query uses an index on the MDSYS.RDF_VALUE$ table, thereby providing efficient lookup.

SELECT value_name FROM MDSYS.RDF_VALUE$
  WHERE vname_prefix = SEM_APIS.VALUE_NAME_PREFIX(
    'http://www.w3.org/1999/02/22-rdf-syntax-ns#type','UR');
 
VALUE_NAME
--------------------------------------------------------------------------------
http://www.w3.org/1999/02/22-rdf-syntax-ns#Alt
http://www.w3.org/1999/02/22-rdf-syntax-ns#Bag
http://www.w3.org/1999/02/22-rdf-syntax-ns#List
http://www.w3.org/1999/02/22-rdf-syntax-ns#Property
http://www.w3.org/1999/02/22-rdf-syntax-ns#Seq
http://www.w3.org/1999/02/22-rdf-syntax-ns#Statement
http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral
http://www.w3.org/1999/02/22-rdf-syntax-ns#first
http://www.w3.org/1999/02/22-rdf-syntax-ns#nil
http://www.w3.org/1999/02/22-rdf-syntax-ns#object
http://www.w3.org/1999/02/22-rdf-syntax-ns#predicate
http://www.w3.org/1999/02/22-rdf-syntax-ns#rest
http://www.w3.org/1999/02/22-rdf-syntax-ns#subject
http://www.w3.org/1999/02/22-rdf-syntax-ns#type
http://www.w3.org/1999/02/22-rdf-syntax-ns#value
 
15 rows selected.

SEM_APIS.VALUE_NAME_SUFFIX

Format

SEM_APIS.VALUE_NAME_SUFFIX (

     value_name IN VARCHAR2,

     value_type IN VARCHAR2

     ) RETURN VARCHAR2;

Description

Returns the value in the VNAME_SUFFIX column for the specified value name and value type pair in the MDSYS.RDF_VALUE$ table.

Parameters

value_name

Value name. Must match a value in the VALUE_NAME column in the MDSYS.RDF_VALUE$ table, which is described in Section 1.3.2.

value_type

Value type. Must match a value in the VALUE_TYPE column in the MDSYS.RDF_VALUE$ table, which is described in Section 1.3.2.

Usage Notes

This function usually causes an index on the MDSYS.RDF_VALUE$ table to be used for processing a lookup for values, and thus can make a query run faster.

Examples

The following query returns value name portions of all the lexical values in MDSYS.RDF_VALUE$ table with a suffix value same as that returned by the VALUE_NAME_SUFFIX function. This query uses an index on the MDSYS.RDF_VALUE$ table, thereby providing efficient lookup.

SELECT value_name FROM MDSYS.RDF_VALUE$
  WHERE vname_suffix = SEM_APIS.VALUE_NAME_SUFFIX(
    'http://www.w3.org/1999/02/22-rdf-syntax-ns#type','UR');
 
VALUE_NAME
--------------------------------------------------------------------------------
http://www.w3.org/1999/02/22-rdf-syntax-ns#type