Skip Headers
Oracle® Database Semantic Technologies Developer's Guide
11g Release 1 (11.1)

B28397-05
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

3 SEM_APIS Package Subprograms

The SEM_APIS package contains subprograms (functions and procedures) for working with the Resource Description Framework (RDF) and Web Ontology Language (OWL) in an Oracle database. To use the subprograms in this chapter, you must understand the conceptual and usage information in Chapter 1, "Oracle Semantic Technologies Overview" and Chapter 2, "OWL Concepts".

This chapter provides reference information about the subprograms, listed in alphabetical order.


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 rules indexes 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 rules indexes of the semantic network.

EXECUTE SEM_APIS.ADD_SEM_INDEX('pscm');

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

Description

Alters a semantic network index on a model.

Parameters

model_name

Name of the model.

index_code

Index code string.

command

A command that is valid for the Oracle SQL ALTER INDEX statement (for example, REBUILD or UNUSABLE). For information about the ALTER INDEX statement, see Oracle Database SQL Language Reference.

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

Format

SEM_APIS.ALTER_SEM_INDEX_ON_RULES_INDEX(

     rules_index_name IN VARCHAR2,

     index_code IN VARCHAR2,

     command IN VARCHAR2);

Description

Alters a semantic network index on a rules index.

Parameters

rules_index_name

Name of the rules index.

index_code

Index code string.

command

A command that is valid for the Oracle SQL ALTER INDEX statement (for example, REBUILD or UNUSABLE). For information about the ALTER INDEX statement, see Oracle Database SQL Language Reference.

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 rules index named rdfs_rix_family.

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

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

Format

SEM_APIS.ANALYZE_RULES_INDEX(

     index_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 rules index (entailment).

Parameters

index_name

Name of the rules index.

estimate_percent

Percentage of rows to estimate in the internal table partition containing information about the rules index (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 rules index:

  • 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 rules index. 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 rules index. 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 rules index is locked; FALSE (the default) does not gather statistics if the rules index 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 rules index. The DBMS_STATS.GATHER_TABLE_STATS procedure is documented in Oracle Database PL/SQL Packages and Types Reference.

For information about rules indexes, see Section 1.3.7.

Examples

The following example collects statistics for the rules index named rdfs_rix_family.

EXECUTE SEM_APIS.ANALYZE_RULES_INDEX('rdfs_rix_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);

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.

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

Usage Notes

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

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 rules index if it is in a failed state.

Parameters

rdf_object_type

Type of the RDF object: RULEBASE for a rulebase or RULES_INDEX for a 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 rules index is in a failed state if a system failure occurred during the creation of that object. You can check if a rulebase or rules index 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 rules index 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.CREATE_ENTAILMENT

Format

SEM_APIS.CREATE_ENTAILMENT(

     index_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);

Description

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

Parameters

index_name_in

Name of the rules index (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 rules index 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. Is 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 PROOF, DISTANCE, ENTAIL_ANYWAY, and USER_RULES. See the Usage Notes for explanations of each value.

Usage Notes

For the inf_components_in parameter, you can specify any combination of the following keywords: SCOH, COMPH, DISJH, SYMMH, INVH, SPIH, SPOH, DOMH, RANH, EQCH, EQPH, FPH, IFPH, SAMH, DOM, RAN, SCO, DISJ, INV, SPO, FP, IFP, SYMM, TRANS, DIF, SAM, RDFS2, RDFS3, RDFS4a, RDFS4b, RDFS5, RDFS6, RDFS7, RDFS8, RDFS9, RDFS10, RDFS11, RDFS12, RDFS13, RDFP1, RDFP2, RDFP3, RDFP4, RDFP6, RDFP7, RDFP8AX, RDFP8BX, RDFP9, RDFP10, RDFP11, RDFP12A, RDFP12B, RDFP12C, RDFP13A, RDFP13B, RDFP13C, RDFP14A, RDFP14BX, RDFP15, RDFP16. For an explanation of the meaning of these keywords, see Table 3-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. Note that component SAM is not in this default list, because it tends to generate many new triples for some ontologies.

Table 3-1 Inferencing Keywords for inf_components_in Parameter

Keyword Explanation

COMPH

Performs inference based on owl:complementOf assertions and the interaction of owl:complementOf with other language constructs.

DIF

Generates owl:differentFrom assertions based on the symmetricity of owl:differentFrom.

DISJ

Infers owl:differentFrom relationships at instance level using owl:disjointWith assertions.

DISJH

Performs inference based on owl:disjointWith assertions and their interactions with other language constructs.

DOM

Performs inference based on RDFS2.

DOMH

Performs inference based on rdfs:domain assertions and their interactions with other language constructs.

EQCH

Performs inference that are relevant to owl:equivalentClass.

EQPH

Performs inference that are relevant to owl:equivalentProperty.

FP

Performs instance-level inference using instances of owl:FunctionalProperty.

FPH

Performs inference using instances of owl:FunctionalProperty.

IFP

Performs instance-level inference using instances of owl:InverseFunctionalProperty.

IFPH

Performs inference using instances of owl:InverseFunctionalProperty.

INV

Performs instance-level inference using owl:inverseOf assertions.

INVH

Performs inference based on owl:inverseOf assertions and their interactions with other language constructs.

RANH

Performs inference based on rdfs:range assertions and their interactions with other language constructs.

RDFP*

(The rules corresponding to components with a prefix of RDFP can be found in Completeness, decidability and complexity of entailment for RDF Schema and a semantic extension involving the OWL vocabulary, by H.J. Horst.)

RDFS2, ... RDFS13

RDFS2, RDFS3, RDFS4a, RDFS4b, RDFS5, RDFS6, RDFS7, RDFS8, RDFS9, RDFS10, RDFS11, RDFS12, and RDFS13 are described in Section 7.3 of RDF Semantics (http://www.w3.org/TR/rdf-mt/). Note that many of the RDFS components are not relevant for OWL inference.

SAM

Performs inference about individuals based on existing assertions for those individuals and owl:sameAs.

SAMH

Infers owl:sameAs assertions using transitivity and symmetricity of owl:sameAs.

SCO

Performs inference based on RDFS9.

SCOH

Generates the subClassOf hierarchy based on existing rdfs:subClassOf assertions. Basically, C1 rdfs:subClassOf C2 and C2 rdfs:subClassOf C3 will infer C1 rdfs:subClassOf C3 based on transitivity. SCOH is also an alias of RDFS11.

SPIH

Performs inference based on interactions between rdfs:subPropertyOf and owl:inverseOf assertions.

SPO

Performs inference based on RDFS7.

SPOH

Generates rdfs:subPropertyOf hierarchy based on transitivity of rdfs:subPropertyOf. It is an alias of RDFS5.

SYMM

Performs instance-level inference using instances of owl:SymmetricProperty.

SYMH

Performs inference for properties of type owl:SymmetricProperty.

TRANS

Calculates transitive closure for instances of owl:TransitiveProperty.


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:

Examples

The following example creates a rules index 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');

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-14 in Section 1.10.2.)

EXECUTE SEM_APIS.CREATE_RULEBASE('family_rb');

SEM_APIS.CREATE_RULES_INDEX

Format

SEM_APIS.CREATE_RULES_INDEX(

     index_name_in IN VARCHAR2,

     models_in IN SEM_MODELS,

     rulebases_in IN SEM_RULEBASES);

Description

Creates a rules index based on data in one or more models and one or more rulebases.

Parameters

index_name_in

Name of the rules index.

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.

Usage Notes

This procedure creates a rules index. For information about rules indexes, see Section 1.3.7.

Examples

The following example creates a rules index named family_rb_rix_family, using the family model and the RDFS and family_rb rulebases. (This example is an excerpt from Example 1-14 in Section 1.10.2.)

BEGIN
  SEM_APIS.CREATE_RULES_INDEX(
    'rdfs_rix_family',
    SEM_Models('family'),
    SEM_Rulebases('RDFS','family_rb'));
END;
/

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-13 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

Adds semantic technology support to the database.

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 remove semantic technology support from the database, 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 adds semantic technology support to the database.

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.

A rules index 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 rules indexes, or (B) a user with DBA privileges.

This procedure creates views with names in the following format:

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

Format

SEM_APIS.DROP_ENTAILMENT(

     index_name_in IN VARCHAR2);

Description

Drops (deletes) a rules index (entailment).

Parameters

index_name_in

Name of the rules index (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 rules index 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_RULES_INDEX

Format

SEM_APIS.DROP_RULES_INDEX(

     index_name IN VARCHAR2);

Description

Deletes a rules index.

Parameters

index_name

Name of the rules index.

Usage Notes

This procedure deletes the specified rules index, making it no longer available for use with queries against RDF data. For information about rules indexes, see Section 1.3.7.

Only the owner of a rulebase can call this procedure to drop the rules index. However, a rules index can be dropped implicitly if an authorized user drops any model or rulebase on which the rules index is based; in such a case, the rules index is dropped automatically.

Examples

The following example drops the rules index named rdfs_rix_family.

EXECUTE SEM_APIS.DROP_RULES_INDEX ('rdfs_rix_family');

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 rules indexes 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 rules indexes 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();

Description

Removes semantic technology support from the database.

Parameters

None.

Usage Notes

To remove semantic technology support from the database, you must connect as a user with DBA privileges and call this procedure.

Before you call this procedure, be sure to delete all semantic technology models and rulebases.

Examples

The following example removes semantic technology support from the database.

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 rules index 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 rules indexes owned by that user.

Examples

The following example deletes all rulebases and rules indexes 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 rules index 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.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-13 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-13 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-13 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):

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-13 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_RULES_INDEX

Format

SEM_APIS.LOOKUP_RULES_INDEX (

     models IN SEM_MODELS,

     rulebases IN SEM_RULEBASES

     ) RETURN VARCHAR2;

Description

Returns the name of the 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 rules index that is based on the family model and the RDFS and family_rb rulebases. (It is an excerpt from Example 1-14 in Section 1.10.2.)

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

LOOKUP_RULES_INDEX
--------------------------------------------------------------------------------
RDFS_RIX_FAMILY

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 rules indexes (entailment) 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