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 Database Semantic Technologies Overview" and Chapter 2, "OWL Concepts".
This chapter provides reference information about the subprograms, listed in alphabetical order.
Format
SEM_APIS.ADD_DATATYPE_INDEX(
datatype IN VARCHAR2,
tablespace_name IN VARCHAR2 default NULL,
parallel IN PLS_INTEGER default NULL,
online IN BOOLEAN default FALSE,
options IN VARCHAR2 default NULL);
Description
Adds a data type index for the specified data type to the semantic network.
Parameters
URI of the data type to index.
Destination tablespace for the index.
Degree of parallelism to use when building the index.
TRUE allows DML operations affecting the index during creation of the index; FALSE (the default) does not allow DML operations affecting the index during creation of the index.
String specifying options for index creation using the form OPTION_NAME=option_value. Supported options are SRID, TOLERANCE, and DIMENSIONS, which are all associated with spatial index creation (see Section 1.6.6.2, "Indexing Spatial Data"). The option name keywords are case sensitive and must be specified in uppercase.
Usage Notes
You must have DBA privileges to call this procedure.
For more information about data type indexing, see Section 1.9.
For information about creating a data type index on RDF spatial data, see Section 1.6.6.2.
Examples
The following example creates an index on xsd:string typed literals and plain literals in the MY_TBS tablespace.
EXECUTE SEM_APIS.ADD_DATATYPE_INDEX('http://www.w3.org/2001/XMLSchema#string', tablespace_name=>'MY_TBS', parallel=>4);
Format
SEM_APIS.ADD_SEM_INDEX(
index_code IN VARCHAR2);
Description
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 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');
Format
SEM_APIS.ALTER_DATATYPE_INDEX(
datatype IN VARCHAR2,
command IN VARCHAR2,
tablespace_name IN VARCHAR2 default NULL,
parallel IN PLS_INTEGER default NULL,
online IN BOOLEAN default FALSE);
Description
Alters a data type index.
Parameters
URI of the data type to index.
String specifying the command to be performed: REBUILD to rebuild the data type index, or UNUSABLE to marks the data type index as unusable. The value for this parameter is not case-sensitive.
Destination tablespace for the index.
Degree of parallelism to use when rebuilding the index.
TRUE allows DML operations affecting the index during rebuilding of the index; FALSE (the default) does not allow DML operations affecting the index during rebuilding of the index.
Usage Notes
You must have DBA privileges to call this procedure.
For an explanation of data type indexes, see Section 1.9.
Examples
The following example rebuilds the index on xsd:string typed literals and plain literals in the MY_TBS tablespace.
EXECUTE SEM_APIS.ALTER_DATATYPE_INDEX('http://www.w3.org/2001/XMLSchema#string', command=>'REBUILD', tablespace_name=>'MY_TBS', parallel=>4);
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
Name of the entailment.
Must be the string MOVE.
Name of the destination tablespace.
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');
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
Name of the model.
Must be the string MOVE.
Name of the destination tablespace.
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".
This procedure is not supported on version-enabled RDF models, as explained in Section 6.5, "Special Considerations When Using Workspace Manager Support for RDF Data".
Examples
The following example moves the model named family to the tablespace named my_tbs.
EEXECUTE SEM_APIS.ALTER_MODEL('family', 'MOVE', 'my_tbs');
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
Name of the entailment.
Index code string.
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.
Name of the destination tablespace for the rebuild operation.
Specifies whether compression should be used when rebuilding the index.
Degree of parallelism to be associated with the operation. For more information about parallel execution, see Oracle Database VLDB and Partitioning Guide.
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');
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
Name of the model.
Index code string.
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.
Name of the destination tablespace for the rebuild operation.
Specifies whether compression should be used when rebuilding the index.
Degree of parallelism to be associated with the operation. For more information about parallel execution, see Oracle Database VLDB and Partitioning Guide.
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');
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
Name of the entailment.
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.
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 columnextension: 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 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.
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.
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.
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');
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
Name of the model.
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.
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 columnextension: 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 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.
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.
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.
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');
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 INTEGER DEFAULT NULL,
start_comment IN VARCHAR2 DEFAULT NULL,
end_comment IN VARCHAR2 DEFAULT NULL);
Description
Loads semantic data from a staging table.
Parameters
Name of the model.
Name of the schema that owns the staging table that holds semantic data to be loaded.
Name of the staging table that holds semantic data to be loaded.
An optional quoted string with one or more of the following keyword specifications:
DEL_BATCH_DUPS=USE_INSERT allows the use of an insertion-based strategy for duplicate elimination that may lead to faster processing if the input data contains many duplicates.
MBV_METHOD=SHADOW allows the use of a different value loading strategy that may lead to faster processing for large loads.
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.
PARSE allows parsing of triples retrieved from the staging table (also parses triples containing graph names).
<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.
(Reserved for future use)
Optional comment about the start of the load operation.
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');
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
Type of the RDF object: RULEBASE for a rulebase or RULES_INDEX for an entailment (rules index).
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');
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. 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.
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.
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 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.
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.
(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>
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,
include_named_g IN SEM_GRAPHS DEFAULT NULL,
include_default_g IN SEM_MODELS DEFAULT NULL,
include_all_g IN SEM_MODELS DEFAULT NULL,
inf_ng_name IN VARCHAR2 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
Name of the entailment to be created.
One or more model names. Its data type is SEM_MODELS, which has the following definition: TABLE OF VARCHAR2(25)
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.
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.
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.
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, LOCAL_NG_INF, OPT_SAMEAS, RAW8, PROOF, and USER_RULES. See the Usage Notes for explanations of each value.
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.)
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.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.2.5.
Causes all triples from the specified named graphs (across all source models) to participate in named graph based global inference (NGGI, explained in Section 2.2.11.1). For example, include_named_g => sem_graphs('<urn:G1>','<urn:G2>') implies that triples from named graphs G1 and G2 will be included in NGGI.
Its data type is SEM_GRAPHS, which has the following definition: TABLE OF VARCHAR2(4000).
Causes all triples with a null graph name in the specified models to participate in named graph based global inference (NGGI, explained in Section 2.2.11.1). For example, include_default_g => sem_models('m1') causes all triples with a null graph name from model M1 to be included in NGGI.
Causes all triples, regardless of their graph name values, in the specified models to participate in named graph based global inference (NGGI, explained in Section 2.2.11.1). For example, include_all_g => sem_models('m2')causes all triples in model M2 to be included in NGGI.
Assigns the specified graph name to all the new triples inferred by the named graph based global inference (NGGI, explained in Section 2.2.11.1).
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 9-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 9-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');
Table 9-1 Inferencing Keywords for inf_components_in Parameter
| Keyword | Explanation |
|---|---|
|
CHAIN |
Captures the property chain semantics defined in OWL 2. Only chains of length 2 are supported. By default, this is included in the |
|
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. |
|
HASKEY |
Covers the semantics behind "keys" defined in OWL 2. In OWL 2, a collection of properties can be treated as a key to a class expression. For efficiency, the size of the collection must not exceed 3. (New as of Release 11.2.) |
|
IFP |
Performs instance-level inference using instances of owl:InverseFunctionalProperty. |
|
IFPH |
Performs inference using instances of owl:InverseFunctionalProperty. |
|
INTERSECT |
Handles the core semantics of owl:intersectionOf. For example, if class C is the intersection of classes C1, C2 and C3, then C is a subclass of C1, C2, and C3. In addition, common instances of all C1, C2, and C3 are also instances of C. (New as of Release 11.2.) |
|
INTERSECTSCOH |
Handles the fact that an intersection is the maximal common subset. For example, if class C is the intersection of classes C1, C2, and C3, then any common subclass of all C1, C2, and C3 is a subclass of C. (New as of Release 11.2.) |
|
INV |
Performs instance-level inference using owl:inverseOf assertions. |
|
INVH |
Performs inference based on owl:inverseOf assertions and their interactions with other language constructs. |
|
MBRLST |
Captures the semantics that for any resource, every item in the list given as the value of the |
|
ONEOF |
Generates classification assertions based on the definition of the enumeration classes. In OWL, class extensions can be enumerated explicitly with the |
|
PROPDISJH |
Captures the interaction between |
|
RANH |
Performs inference based on |
|
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 ( |
|
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. |
|
SKOSAXIOMS |
Captures most of the axioms defined in the SKOS detailed specification. By default, this is included in the |
|
Performs inference based on the semantics of the OWL 2 EL profile, which captures the expressiveness of SNOMED CT (Systematized Nomenclature of Medicine - Clinical Terms), which is one of the most expressive and complex medical terminologies. (New as of Release 11.2.) | |
|
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. |
|
SVFH |
Handles the following semantics that involves the interaction between owl:someValuesFrom and rdfs:subClassOf. Consider two existentia l restriction classes C1 and C2 that both use the same restriction property. Assume further that the owl:someValuesFrom constraint class for C1 is a subclass of that for C2. Then C1 can be inferred as a subclass of C2. (New as of Release 11.2.) |
|
SYMM |
Performs instance-level inference using instances of owl:SymmetricProperty. |
|
SYMH |
Performs inference for properties of type owl:SymmetricProperty. |
|
THINGH |
Handles the semantics that any defined OWL class is a subclass of owl:Thing. The consequence of this rule is that instances of all defined OWL classes will become instances of owl:Thing. The size of the inferred graph will very likely be bigger with this component selected. (New as of Release 11.2.) |
|
THINGSAM |
Handles the semantics that instances of owl:Thing are equal to (owl:sameAs) themselves. This component is provided for the convenience of some applications. Note that an application does not have to select this inference component to figure out an individual is equal to itself; this kind of information can easily be built in the application logic. (New as of Release 11.2.) |
|
TRANS |
Calculates transitive closure for instances of owl:TransitiveProperty. |
|
UNION |
Captures the core semantics of the |
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 creates 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 specifyCOL_COMPRESS=T only on systems that support Hybrid Columnar Compression (HCC). For information about HCC, see Oracle Database Concepts. |
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.
LOCAL_NG_INF=T causes named graph based local inference (NGLI) to be used instead of named graph based global inference (NGGI). For information about NGLI, see Section 2.2.11.2.
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 9-2.
Table 9-2 SEM_RDFSA Package Constants for label_gen Parameter
| Constant | Description |
|---|---|
|
SEM_RDFSA.LABELGEN_SUBJECT |
Label generator that applies the label associated with the inferred triple's subject as the triple's label. |
|
SEM_RDFSA.LABELGEN_PREDICATE |
Label generator that applies the label associated with the inferred triple's subject as the triple's label. |
|
SEM_RDFSA.LABELGEN_OBJECT |
Label generator that applies the label associated with the inferred triple's subject as the triple's label. |
|
SEM_RDFSA.LABELGEN_RULE |
Label generator that applies the label associated with the rule that directly produced the inferred triple as the triple's label. If you specify this option, you must also specify |
|
SEM_RDFSA.LABELGEN_DOMINATING |
Label generator that computes a dominating label of all the available labels for the triple's components (subject, predicate, object, and rule), and applies it as the label for the inferred triple. |
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. --
Format
SEM_APIS.CREATE_RULEBASE(
rulebase_name IN VARCHAR2);
Description
Creates a rulebase.
Parameters
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-43 in Section 1.11.2.)
EXECUTE SEM_APIS.CREATE_RULEBASE('family_rb');
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
Name of the model.
Name of the table to hold references to semantic technology data for this model.
Name of the column of type SDO_RDF_TRIPLE_S in table_name.
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.10.
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-42 in Section 1.11.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);
Format
SEM_APIS.CREATE_SEM_NETWORK(
tablespace_name IN VARCHAR2
Description
Creates structures for persistent storage of semantic data.
Parameters
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');
Format
SEM_APIS.CREATE_SOURCE_EXTERNAL_TABLE(
source_table IN VARCHAR2,
def_directory IN VARCHAR2,
log_directory IN VARCHAR2 DEFAULT NULL,
bad_directory IN VARCHAR2 DEFAULT NULL,
log_file IN VARCHAR2 DEFAULT NULL,
bad_file IN VARCHAR2 DEFAULT NULL,
parallel IN INTEGER DEFAULT NULL,
source_table_owner IN VARCHAR2 DEFAULT NULL,
flags IN VARCHAR2 DEFAULT NULL);
Description
Creates an external table to map an N-Triple or N-Quad format file into a table.
Parameters
Name of the external table to be created.
Database directory where the input files are located. To load from this staging table, you must have READ privilege on this directory.
Database directory where the log files will be generated when loading from the external table. If not specified, the value of the def_directory parameter is used. When loading from the external table, you must have WRITE privilege on this directory.
Database directory where the bad files will be generated when loading from the external table. If not specified, the value of the def_directory parameter is used. When loading from the external table, you must have WRITE privilege on this directory.
Name of the log file. If not specified, the name will be .generated automatically during a load operation.
Name of the bad file. If not specified, the name will be .generated automatically during a load operation.
Degree of parallelism to associate with the external table being created.
Owner for the external table being created. If not specified, the invoker becomes the owner.
(Reserved for future use)
Usage Notes
For more information and an example, see Section 1.7.1.1.2, "Loading N-Quad Format Data into a Staging Table Using an External Table".
Examples
The following example creates a source external table. (This example is an excerpt from Example 1-36 in Section 1.7.1.1.2.)
BEGIN
sem_apis.create_source_external_table(
source_table => 'stage_table_source'
,def_directory => 'DATA_DIR'
,bad_file => 'CLOBrows.bad'
);
END;
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
Name of the virtual model to be created.
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.
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.
(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'));
Format
SEM_APIS.DISABLE_CHANGE_TRACKING(
models_in IN SEM_MODELS);
Description
Disables change tracking for a specified set of models.
Parameters
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'));
Format
SEM_APIS.DISABLE_INC_INFERENCE(
entailment_name IN VARCHAR2);
Description
Disables incremental inference for a specified entailment (rules index).
Parameters
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');
Format
SEM_APIS.DROP_DATATYPE_INDEX(
datatype IN VARCHAR2,
force_drop IN BOOLEAN default FALSE);
De scription
Drops (deletes) an existing data type index.
Parameters
URI of the data type for the index to drop.
TRUE forces the index to be dropped if an error occurs during the processing of the statement; FALSE (the default) does not drop the index if an error occurs during the processing of the statement.
Usage Notes
You must have DBA privileges to call this procedure.
For an explanation of data type indexes, see Section 1.9.
Examples
The following example drops the data type index for xsd:string typed literals and plain literals.
EXECUTE SEM_APIS.DROP_DATATYPE_INDEX('http://www.w3.org/2001/XMLSchema#string');
Format
SEM_APIS.DROP_ENTAILMENT(
entailment_name_in IN VARCHAR2,
named_g_in IN SEM_GRAPHS DEFAULT NULL,
dop IN INT DEFAULT 1);
Description
Drops (deletes) an entailment (rules index).
Parameters
Name of the entailment to be deleted.
Causes only the triples with the specified graph names in the entailment to be deleted. A null value (the default) drops the entire entailment.
For example, named_g_in => sem_graphs('<urn:G1>','<urn:G2>') drops only the triples in entailment with graph names G1 and G2; the rest of the entailment graph is not dropped.
Degree of parallelism for a parallel execution of triple deletion. Applies only if the named_g_in parameter is not null.
Usage Notes
You can use this procedure to delete an entailment that you created using the SEM_APIS.CREATE_ENTAILMENT procedure.
If you drop only a subset of the entailment with specified named graphs (that is, when named_g_in is not null) on an entailment with a VALID or INCOMPLETE status, then the resulting status of the entailment after the drop is set to INCOMPLETE.
Examples
The following example deletes a entailment named OWLTST_IDX.
EXECUTE sem_apis.drop_entailment('owltst_idx');
The following example deletes only inferred triples with graph names G1 and G2 that belong to the entailment named OWLNG_IDX. Any inferred triples in the default graph and other named graphs remain in the entailment.
EXECUTE sem_apis.drop_entailment('owlng_idx',sem_graphs('<urn:G1>','<urn:G2>'));
Format
SEM_APIS.DROP_RULEBASE(
rulebase_name IN VARCHAR2);
Description
Deletes a rulebase.
Parameters
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');
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 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');
Format
SEM_APIS.DROP_SEM_MODEL(
model_name IN VARCHAR2);
Description
Drops (deletes) a semantic technology model.
Parameters
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');
Format
SEM_APIS.DROP_SEM_NETWORK(
cascade IN BOOLEAN DEFAULT FALSE);
Description
Removes structures used for persistent storage of semantic data.
Parameters
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;
Format
SEM_APIS.DROP_USER_INFERENCE_OBJS(
uname IN VARCHAR2);
Description
Drops (deletes) all rulebases and entailments owned by a specified database user.
Parameters
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.
Format
SEM_APIS.DROP_VIRTUAL_MODEL(
vm_name IN VARCHAR2);
Description
Drops (deletes) a virtual model.
Parameters
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');
Format
SEM_APIS.ENABLE_CHANGE_TRACKING(
models_in IN SEM_MODELS);
Description
Enables change tracking for a specified set of models.
Parameters
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'));
Format
SEM_APIS.ENABLE_INC_INFERENCE(
entailment_name IN VARCHAR2);
Description
Enables incremental inference for a specified entailment (rules index).
Parameters
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');
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
Name of the semantic technology model.
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 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;
/
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
Name of the entailment.
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 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
/
Format
SEM_APIS.GET_MODEL_ID(
model_name IN VARCHAR2
) RETURN NUMBER;
Description
Returns the model ID number of a semantic technology model.
Parameters
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-42 in Section 1.11.2.)
SELECT SEM_APIS.GET_MODEL_ID('articles') AS model_id FROM DUAL;
MODEL_ID
----------
1
Format
SEM_APIS.GET_MODEL_NAME(
model_id IN NUMBER
) RETURN VARCHAR2;
Description
Returns the model name of a semantic technology model.
Parameters
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-42 in Section 1.11.2.)
SQL> SELECT SEM_APIS.GET_MODEL_NAME(1) AS model_name FROM DUAL; MODEL_NAME -------------------------------------------------------------------------------- ARTICLES
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
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.
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. Must match a value in the VALUE_NAME column of the MDSYS.RDF_VALUE$ table, which is described in Section 1.3.2.
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. 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-42 in Section 1.11.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
Format
SEM_APIS.GETV$DATETIMETZVAL(
value_type IN VARCHAR2,
vname_prefix IN VARCHAR2,
vname_suffix IN VARCHAR2,
literal_type IN VARCHAR2,
language_type IN VARCHAR2,
) RETURN NUMBER;
Description
Returns a TIMESTAMP WITH TIME ZONE value for xsd:dateTime typed literals, and returns a null value for all other RDF terms. Greenwich Mean Time is used as the default time zone for xsd:dateTime values without time zones.
Parameters
Type of the RDF term.
Prefix value of the RDF term.
Suffix value of the RDF term.
Literal type of the RDF term.
Language type of the RDF term.
Usage Notes
For better performance, consider creating a function-based index on this function. For more information, see Section 1.6.7.2.
Examples
The following example returns TIMESTAMP WITH TIME ZONE values for all xsd:dateTime literals in the MDSYS.RDF_VALUE$ table:
SELECT SEM_APIS.GETV$DATETIMETZVAL(value_type, vname_prefix, vname_suffix, literal_type, language_type) FROM MDSYS.RDF_VALUE$;
Format
SEM_APIS.GETV$DATETZVAL(
value_type IN VARCHAR2,
vname_prefix IN VARCHAR2,
vname_suffix IN VARCHAR2,
literal_type IN VARCHAR2,
language_type IN VARCHAR2,
) RETURN TIMESTAMP WITH TIME ZONE;
Description
Returns a TIMESTAMP WITH TIME ZONE value for xsd:date typed literals, and returns a null value for all other RDF terms. Greenwich Mean Time is used as the default time zone for xsd:date values without time zones.
Parameters
Type of the RDF term.
Prefix value of the RDF term.
Suffix value of the RDF term.
Literal type of the RDF term.
Language type of the RDF term.
Usage Notes
For better performance, consider creating a function-based index on this function. For more information, see Section 1.6.7.2.
Examples
The following example returns TIMESTAMP WITH TIME ZONE values for all xsd:date literals in the MDSYS.RDF_VALUE$ table:
SELECT SEM_APIS.GETV$DATETZVAL(value_type, vname_prefix, vname_suffix, literal_type, language_type) FROM MDSYS.RDF_VALUE$;
Format
SEM_APIS.GETV$NUMERICVAL(
value_type IN VARCHAR2,
vname_prefix IN VARCHAR2,
vname_suffix IN VARCHAR2,
literal_type IN VARCHAR2,
language_type IN VARCHAR2,
) RETURN NUMBER;
Description
Returns a numeric value for XML Schema numeric typed literals, and returns a null value for all other RDF terms.
Parameters
Type of the RDF term.
Prefix value of the RDF term.
Suffix value of the RDF term.
Literal type of the RDF term.
Language type of the RDF term.
Usage Notes
For better performance, consider creating a function-based index on this function. For more information, see Section 1.6.7.2.
Examples
The following example returns numeric values for all numeric literals in the MDSYS.RDF_VALUE$ table:
SELECT SEM_APIS.GETV$NUMERICVAL(value_type, vname_prefix, vname_suffix, literal_type, language_type) FROM MDSYS.RDF_VALUE$;
Format
SEM_APIS.GETV$STRINGVAL(
value_type IN VARCHAR2,
vname_prefix IN VARCHAR2,
vname_suffix IN VARCHAR2,
literal_type IN VARCHAR2,
language_type IN VARCHAR2,
) RETURN TIMESTAMP WITH TIME ZONE;
Description
Returns a VARCHAR2 string of the lexical form of plain literals and xsd:string typed literals, and returns a null value for all other RDF terms. CHR(0) is returned for empty literals.
Parameters
Type of the RDF term.
Prefix value of the RDF term.
Suffix value of the RDF term.
Literal type of the RDF term.
Language type of the RDF term.
Usage Notes
For better performance, consider creating a function-based index on this function. For more information, see Section 1.6.7.2.
Examples
The following example returns lexical values for all plain literals and xsd:string literals in the MDSYS.RDF_VALUE$ table:
SELECT SEM_APIS.GETV$STRINGVAL(value_type, vname_prefix, vname_suffix, literal_type, language_type) FROM MDSYS.RDF_VALUE$;
Format
SEM_APIS.GETV$TIMETZVAL(
value_type IN VARCHAR2,
vname_prefix IN VARCHAR2,
vname_suffix IN VARCHAR2,
literal_type IN VARCHAR2,
language_type IN VARCHAR2,
) RETURN TIMESTAMP WITH TIME ZONE;
Description
Returns a TIMESTAMP WITH TIME ZONE value for xsd:time typed literals, and returns a null value for all other RDF terms. Greenwich Mean Time is used as the default time zone for xsd:time values without time zones. 2009-06-26 is used as the default date in all the generated TIMESTAMP WITH TIME ZONE values.
Parameters
Type of the RDF term.
Prefix value of the RDF term.
Suffix value of the RDF term.
Literal type of the RDF term.
Language type of the RDF term.
Usage Notes
For better performance, consider creating a function-based index on this function. For more information, see Section 1.6.7.2.
Because xsd:time values include only a time but not a date, the returned TIMESTAMP WITH TIME ZONE values (which include a date component) have 2009-06-26 added as the date. This is done so that the returned values can be indexed internally, and so that the date is the same for all of them.
Examples
The following example returns TIMESTAMP WITH TIME ZONE values (using the default 2009-06-26 for the date) for all xsd:time literals in the MDSYS.RDF_VALUE$ table. (
SELECT SEM_APIS.GETV$DATETIMETZVAL(value_type, vname_prefix, vname_suffix, literal_type, language_type) FROM MDSYS.RDF_VALUE$;
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
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.
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. Must match a value in the VALUE_NAME column of the MDSYS.RDF_VALUE$ table, which is described in Section 1.3.2.
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. 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 example 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-42 in Section 1.11.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)
Format
SEM_APIS.LOAD_INTO_STAGING_TABLE(
stagong_table IN VARCHAR2,
source_table IN VARCHAR2,
input_format IN VARCHAR2 DEFAULT NULL,
parallel IN INTEGER DEFAULT NULL,
staging_table_owner IN VARCHAR2 DEFAULT NULL,
source_table_owner IN VARCHAR DEFAULT NULL,
flags IN VARCHAR DEFAULT NULL);
Description
Loads data into a staging table from an external table mapped to an N-Triple or N-Quad format input file.
Parameters
Name of the staging table.
Name of the source external table.
Format of the input file mapped by the source external table: N-TRIPLE or N-QUAD
Degree of parallelism to use during the load.
Owner for the staging table being created. If not specified, the invoker is assumed to be the owner.
Owner for the source table. If not specified, the invoker is assumed to be the owner.
(Reserved for future use)
Usage Notes
For more information and an example, see Section 1.7.1.1.2, "Loading N-Quad Format Data into a Staging Table Using an External Table".
Examples
The following example loads the staging table. (This example is an excerpt from Example 1-36 in Section 1.7.1.1.2.)
BEGIN
sem_apis.load_into_staging_table(
staging_table => 'STAGE_TABLE'
,source_table => 'stage_table_source'
,input_format => 'N-QUAD');
END;
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
One or more model names. Its data type is SEM_MODELS, which has the following definition: TABLE OF VARCHAR2(25)
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-43 in Section 1.11.2.)
SELECT SEM_APIS.LOOKUP_ENTAILMENT(SEM_MODELS('family'),
SEM_RULEBASES('RDFS','family_rb')) AS lookup_entailment FROM DUAL;
LOOKUP_ENTAILMENT
--------------------------------------------------------------------------------
RDFS_RIX_FAMILY
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
Name of the source model.
Name of the destination model.
TRUE causes indexes on the destination application table to be rebuilt after the models are merged; FALSE does not rebuild any indexes.
TRUE causes the source model (source_model) to be deleted after the models are merged; FALSE (the default) does not delete the source model.
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 version-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');
Format
SEM_APIS.REFRESH_SEM_NETWORK_INDEX_INFO(
options IN VARCHAR2 DEFAULT NULL);
Description
Refreshes the information about semantic network indexes.
Parameters
(Reserved for future use)
Usage Notes
This procedure updates the information in the MDSYS.SEM_NETWORK_INDEX_INFO view, which is described in Section 1.8.1.
Examples
The following example refreshes the information about semantic network indexes.
EXECUTE sem_apis.refresh_sem_network_index_info;
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
Name of the model.
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.
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).
This procedure is not supported on version-enabled models (explained in Chapter 6).
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');
Format
SEM_APIS.RENAME_ENTAILMENT(
old_name IN VARCHAR2,
new_name IN VARCHAR2);
Description
Renames an entailment (rules index).
Parameters
Name of the existing entailment to be renamed.
New name for the entailment.
Usage Notes
This procedure is not supported on version-enabled RDF models, as explained in Section 6.5, "Special Considerations When Using Workspace Manager Support for RDF Data".
Examples
The following example renames a entailment named OWLTST_IDX to MY_OWLTST_IDX.
EXECUTE sem_apis.rename_entailment('owltst_idx', 'my_owltst_idx');
Format
SEM_APIS.RENAME_MODEL(
old_name IN VARCHAR2,
new_name IN VARCHAR2);
Description
Renames a model.
Parameters
Name of the existing model to be renamed.
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 version-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');
Format
SEM_APIS.SWAP_NAMES(
model1 IN VARCHAR2,
model2 IN VARCHAR2);
Description
Swaps (exchanges) the names of two existing models.
Parameters
Name of a model.
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.
This procedure is not supported on version-enabled RDF models, as explained in Section 6.5, "Special Considerations When Using Workspace Manager Support for RDF Data".
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');
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
One or more model names. Its data type is SEM_MODELS, which has the following definition: TABLE OF VARCHAR2(25)
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.
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 that 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.
The maximum number of conflicts to find before the validation process stops. The default value is 100.
(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.
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
One or more model names. Its data type is SEM_MODELS, which has the following definition: TABLE OF VARCHAR2(25)
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 that 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.
The maximum number of conflicts to find before the validation process stops. The default value is 100.
(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;
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. 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. Must match a value in the VALUE_TYPE column in the MDSYS.RDF_VALUE$ table, which is described in <a href="sdo_rdf_concepts.htm#CHDEJDCA">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.
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. 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. 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
This document has the following parts:
Part I provides conceptual and usage information about Oracle Semantic Technologies.
Part II provides reference information about Oracle Semantic Technologies subprograms; it also provides supplementary information in appendixes and a glossary.
Part II contains the following chapters with reference and supplementary information:
To understand the examples in the reference chapters, you must understand the conceptual and data type information in Chapter 1, "Oracle Database Semantic Technologies Overview" and Chapter 2, "OWL Concepts".
Semantic Technologies Developer's Guide
11g Release 2 (11.2)
E25609-03
May 2012
Provides usage and reference information about Oracle Database support for semantic technologies, including storage, inference, and query capabilities for data and ontologies based on Resource Description Framework (RDF), RDF Schema (RDFS), and Web Ontology Language (OWL).
Oracle Database Semantic Technologies Developer's Guide, 11g Release 2 (11.2)
E25609-03
Copyright © 2005, 2012, Oracle and/or its affiliates. All rights reserved.
Primary Author: Chuck Murray
Contributors: Eugene Inseok Chong, Souri Das, Vladimir Kolovski, Matt Perry, Jags Srinivasan, Seema Sundara, Zhe (Alan) Wu, Aravind Yalamanchi
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.
This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
The Jena Adapter for Oracle Database (referred to here as the Jena Adapter) provides a Java-based interface to Oracle Database Semantic Technologies by implementing the well-known Jena Graph, Model, and DatasetGraph APIs. (Jena is an open source framework, and its license and copyright conditions are described in http://jena.sourceforge.net/license.html.)
The DatasetGraph APIs are for managing named graph data, also referred to as quads. In addition, the Jena Adapter provides network analytical functions on top of semantic data through integrating with the Oracle Spatial network data model.
This chapter assumes that you are familiar with major concepts explained in Chapter 1, "Oracle Database Semantic Technologies Overview" and Chapter 2, "OWL Concepts". It also assumes that you are familiar with the overall capabilities and use of the Jena Java framework. For information about the Jena framework, see http://jena.sourceforge.net/, especially the Jena Documentation page. If you use the network analytical function, you should also be familiar with the Oracle Spatial network data model, which is documented in Oracle Spatial Topology and Network Data Models Developer's Guide.
The Jena Adapter extends the semantic data management capabilities of Oracle Database Release 11.2 RDF/OWL.
This chapter includes the following major topics:
Section 7.3, "Setting Up the Semantic Technologies Environment"
Section 7.6, "Additions to the SPARQL Syntax to Support Other Features"
Section 7.7, "Functions Supported in SPARQL Queries through the Jena Adapter"
Section 7.13, "JavaScript Object Notation (JSON) Format Support"
|
Disclaimer: The current Jena Adapter release has been tested against Jena 2.6.4, ARQ 2.8.8, and Joseki 3.4.4. Because of the nature of open source projects, you should not use this Jena Adapter with later versions of Jena, ARQ, or Joseki. |
To use the Jena Adapter, you must first ensure that the system environment has the necessary software, including Oracle Database 11g Release 2 with the Spatial and Partitioning options and with Semantic Technologies support enabled, Jena version 2.6.4, the Jena Adapter, and JDK 1.6. You can set up the software environment by performing these actions:
Install Oracle Database Release 11.2 Enterprise Edition with the Oracle Spatial and Partitioning Options.
If you have not yet installed Release 11.2.0.3 or later, install the 11.2.0.2 Patch Set for Oracle Database Server (https://updates.oracle.com/ARULink/PatchDetails/process_form?patch_num=10098816).
Enable the support for Semantic Technologies, as explained in Section A.1.
Install Jena (version 2.6.4): download the .zip file from http://sourceforge.net/projects/jena/files/Jena/Jena-2.6.4/jena-2.6.4.zip/download and unzip it. (The directory or folder into which you unzip it will be referred to as <Jena_DIR>.)
The Java package will be unpacked into <Jena_DIR>.
Note that Jena 2.6.4 comes with ARQ version 2.8.7 (arq-2.8.7.jar); however, this version of the Jena Adapter actually requires a newer ARQ version (arq-2.8.8.jar). You can download arq-2.8.8.jar from http://sourceforge.net/projects/jena/files/ARQ/ARQ-2.8.8/arq-2.8.8.zip/download and unzip it to a temporary directory. Remove the arq-2.8.7.jar file from <Jena_DIR>/Jena-2.6.4/lib/, and copy arq-2.8.8.jar from the temporary directory into <Jena_DIR>/Jena-2.6.4/lib/.
Download the Jena Adapter (jena_adaptor_for_release11.2.0.3.zip) from the Oracle Database Semantic Technologies page (http://www.oracle.com/technetwork/database/options/semantic-tech/and click Downloads), and unzip it into a temporary directory, such as (on a Linux system) /tmp/jena_adapter. (If this temporary directory does not already exist, create it before the unzip operation.)
The Jena Adapter directories and files have the following structure:
examples/
examples/Test10.java
examples/Test11.java
examples/Test12.java
examples/Test13.java
examples/Test14.java
examples/Test15.java
examples/Test16.java
examples/Test17.java
examples/Test18.java
examples/Test19.java
examples/Test20.java
examples/Test6.java
examples/Test7.java
examples/Test8.java
examples/Test9.java
examples/Test.java
jar/
jar/sdordfclient.jar
javadoc/
javadoc/javadoc.zip
joseki/
joseki/index.html
joseki/application.xml
joseki/update.html
joseki/xml-to-html.xsl
joseki/joseki-config.ttl
sparqlgateway/
default.xslt
noop.xslt
qb1.sparql
. . .
browse.jsp
index.html
. . .
application.xml
WEB-INF/
WEB-INF/web.xml
WEB-INF/weblogic.xml
WEB-INF/lib/
StyleSheets/
StyleSheets/paginator.css
StyleSheets/sg.css
StyleSheets/sgmin.css
Scripts/
Scripts/load.js
Scripts/paginator.js
Scripts/tooltip.js
admin/
admin/sparql.jsp
admin/xslt.jsp
web/
web/web.xml
Copy ojdbc6.jar into <Jena_DIR>/lib (Linux) or <Jena_DIR>\lib (Windows). (ojdbc6.jar is in $ORACLE_HOME/jdbc/lib or %ORACLE_HOME%\jdbc\lib.)
Copy sdordf.jar into <Jena_DIR>/lib (Linux) or <Jena_DIR>\lib (Windows). (sdordf.jar is in $ORACLE_HOME/md/jlib or %ORACLE_HOME%\md\jlib.)
If JDK 1.6 is not already installed, install it.
If the JAVA_HOME environment variable does not already refer to the JDK 1.6 installation, define it accordingly. For example:
setenv JAVA_HOME /usr/local/packages/jdk16/
If the SPARQL service to support the SPARQL protocol is not set up, set it up as explained in Section 7.2.
After setting up the software environment, ensure that your Semantic Technologies environment can enable you to use the Jena Adapter to perform queries, as explained in Section 7.3.
Setting up a SPARQL endpoint using the Jena Adapter involves downloading Joseki, an open source HTTP engine that supports the SPARQL protocol and SPARQL queries. This section explains how to set up a SPARQL service using a servlet deployed in WebLogic Server. The number and complexity of the steps reflect the fact that Oracle is not permitted to bundle all the dependent third-party libraries in a .war or .ear file.
Download and Install Oracle WebLogic Server 11g Release 1 (10.3.1). For details, see http://www.oracle.com/technology/products/weblogic/ and http://www.oracle.com/technetwork/middleware/ias/downloads/wls-main-097127.html.
Ensure that you have Java 6 installed, because it is required by Joseki 3.4.4.
Download Joseki 3.4.4 (joseki-3.4.4.zip) from http://sourceforge.net/projects/joseki/files/Joseki-SPARQL/.
Unpack joseki-3.4.4.zip into a temporary directory. For example:
mkdir /tmp/joseki cp joseki-3.4.4.zip /tmp/joseki cd /tmp/joseki unzip joseki-3.4.4.zip
Ensure that you have downloaded and unzipped the Jena Adapter for Oracle Database, as explained in Section 7.1.
Create a directory named joseki.war at the same level as the jena_adapter directory, and go to it. For example:
mkdir /tmp/joseki.war cd /tmp/joseki.war
Copy necessary files into the directory created in the preceding step:
cp /tmp/jena_adapter/joseki/* /tmp/joseki.war cp -rf /tmp/joseki/Joseki-3.4.4/webapps/joseki/StyleSheets /tmp/joseki.war
Create directories and copy necessary files into them, as follows:
mkdir /tmp/joseki.war/WEB-INF cp /tmp/jena_adapter/web/* /tmp/joseki.war/WEB-INF mkdir /tmp/joseki.war/WEB-INF/lib cp /tmp/joseki/Joseki-3.4.4/lib/*.jar /tmp/joseki.war/WEB-INF/lib cp /tmp/jena_adapter/jar/*.jar /tmp/joseki.war/WEB-INF/lib ## ## Assume ORACLE_HOME points to the home directory of a Release 11.2.0.3 Oracle Database. ## cp $ORACLE_HOME/md/jlib/sdordf.jar /tmp/joseki.war/WEB-INF/lib cp $ORACLE_HOME/jdbc/lib/ojdbc6.jar /tmp/joseki.war/WEB-INF/lib
Using the WebLogic Server Administration console, create a J2EE data source named OracleSemDS. During the data source creation, you can specify a user and password for the database schema that contains the relevant semantic data against which SPARQL queries are to be executed.
If you need help in creating this data source, see Section 7.2.1, "Creating the Required Data Source Using WebLogic Server".
Go to the autodeploy directory of WebLogic Server and copy files, as follows. (For information about auto-deploying applications in development domains, see: http://download.oracle.com/docs/cd/E11035_01/wls100/deployment/autodeploy.html)
cd <domain_name>/autodeploy cp -rf /tmp/joseki.war <domain_name>/autodeploy
In the preceding example, <domain_name> is the name of a WebLogic Server domain.
Note that while you can run a WebLogic Server domain in two different modes, development and production, only development mode allows you use the auto-deployment feature.
Check the files and the directory structure to see if they reflect the following:
. |-- META-INF | `-- MANIFEST.MF |-- StyleSheets | `-- joseki.css |-- WEB-INF | |-- lib | | |-- arq-2.8.8-tests.jar | | |-- arq-2.8.8.jar | | |-- icu4j-3.4.4.jar | | |-- iri-0.8.jar | | |-- jena-2.6.4-tests.jar | | |-- jena-2.6.4.jar | | |-- jetty-6.1.25.jar | | |-- jetty-util-6.1.25.jar | | |-- joseki-3.4.4.jar | | |-- junit-4.5.jar | | |-- log4j-1.2.14.jar | | |-- lucene-core-2.3.1.jar | | |-- ojdbc6.jar | | |-- sdb-1.3.4.jar | | |-- sdordf.jar | | |-- sdordfclient.jar | | |-- servlet-api-2.5-20081211.jar | | |-- slf4j-api-1.5.8.jar | | |-- slf4j-log4j12-1.5.8.jar | | |-- stax-api-1.0.1.jar | | |-- tdb-0.8.10.jar | | |-- wstx-asl-3.2.9.jar | | `-- xercesImpl-2.7.1.jar | `-- web.xml |-- application.xml |-- index.html |-- joseki-config.ttl |-- update.html `-- xml-to-html.xsl
If you want to build a .war file from the /tmp/joseki.war directory (note that a .war file is required if you want to deploy Joseki to an OC4J container), enter the following commands:
cd /tmp/joseki.war jar cvf /tmp/joseki_app.war *
Start or restart WebLogic Server.
Verify your deployment by using your Web browser to connect to a URL in the following format (assume that the Web application is deployed at port 7001): http://<hostname>:7001/joseki
You should see a page titled Oracle SPARQL Service Endpoint using Joseki, and the first text box should contain an example SPARQL query.
Click Submit Query.
You should see a page titled Oracle SPARQL Endpoint Query Results. There may or may not be any results, depending on the underlying semantic model against which the query is executed.
By default, the joseki-config.ttl file contains an oracle:Dataset definition using a model named M_NAMED_GRAPHS. The following snippet shows the configuration. The oracle:allGraphs predicate denotes that the SPARQL service endpoint will serve queries using all graphs stored in the M_NAMED_GRAPHS model.
<#oracle> rdf:type oracle:Dataset;
joseki:poolSize 1 ; ## Number of concurrent connections allowed to this dataset.
oracle:connection
[ a oracle:OracleConnection ;
];
oracle:allGraphs [ oracle:firstModel "M_NAMED_GRAPHS" ] .
The M_NAMED_GRAPHS model will be created automatically (if it does not already exist) upon the first SPARQL query request. You can add a few example triples and quads to test the named graph functions; for example:
SQL> CONNECT username/password
SQL> INSERT INTO m_named_graphs_tpl VALUES(sdo_rdf_triple_s('m_named_graphs','<urn:s>','<urn:p>','<urn:o>'));
SQL> INSERT INTO m_named_graphs_tpl VALUES(sdo_rdf_triple_s('m_named_graphs:<urn:G1>','<urn:g1_s>','<urn:g1_p>','<urn:g1_o>'));
SQL> INSERT INTO m_named_graphs_tpl VALUES(sdo_rdf_triple_s('m_named_graphs:<urn:G2>','<urn:g2_s>','<urn:g2_p>','<urn:g2_o>'));
SQL> COMMIT;
After inserting the rows, go to http://<hostname>:7001/joseki, type the following SPARQL query, and click Submit Query:
SELECT ?g ?s ?p ?o
WHERE
{ GRAPH ?g { ?s ?p ?o} }
The result should be an HTML table with four columns and two sets of result bindings.
The http://<hostname>:7001/joseki page also contains a JSON Output option. If this option is selected (enabled), the SPARQL query response is converted to JSON format.
If you need help creating the required J2EE data source using the WebLogic Server admin console, you can follow these steps:
Login to: http://<hostname>:7001/console
In the Domain Structure panel, click Services.
Click JDBC
Click Data Sources.
In the Summary of JDBC Data Sources panel, click New under the Data Sources table.
In the Create a New JDBC Data Source panel, enter or select the following values.
Name: OracleSemDS
JNDI Name: OracleSemDS
Database Type: Oracle
Database Driver: Oracle's Driver (Thin) Versions: 9.0.1,9.2.0,10,11
Click Next twice.
In the Connection Properties panel, enter the appropriate values for the Database Name, Host Name, Port, Database User Name (schema that contains semantic data), Password fields.
Click Next.
Select (check) the target server or servers to which you want to deploy this OracleSemDS data source.
Click Finish.
You should see a message that all changes have been activated and no restart is necessary.
By default, the SPARQL Service endpoint assumes that the queries are to be executed against a semantic model with a pre-set name. This semantic model is owned by the schema specified in the J2EE data source with JNDI name OracleSemDS. Note that you do not need to create this model explicitly using PL/SQL or Java; if the model does not exist in the network, it will be automatically created, along with the necessary application table and index.
|
Note: Effective with the Jena Adapter release in November 2011, the application table index (<model_name>_idx) definition is changed to accommodate named graph data (quads).For existing models created by an older version of the Jena Adapter, you can migrate the application table index name and definition by using the |
However, you must configure the SPARQL service by editing the joseki-config.ttl configuration file, which is in <domain_name>/autodeploy/joseki.war.
The supplied joseki-config.ttl file includes a section similar to the following for the Oracle data set:
#
## Datasets
#
[] ja:loadClass "oracle.spatial.rdf.client.jena.assembler.OracleAssemblerVocab" .
oracle:Dataset rdfs:subClassOf ja:RDFDataset .
<#oracle> rdf:type oracle:Dataset;
joseki:poolSize 1 ; ## Number of concurrent connections allowed to this dataset.
oracle:connection
[ a oracle:OracleConnection ;
];
oracle:defaultModel [ oracle:firstModel "TEST_MODEL" ] .
In this section of the file, you can:
Modify the joseki:poolSize value, which specifies the number of concurrent connections allowed to this Oracle data set (<#oracle> rdf:type oracle:Dataset;), which points to various RDF models in the database.
Modify the name (or the object value of oracle:firstModel predicate) of the defaultModel, to use a different semantic model for queries. You can also specify multiple models, and one or more rulebases for this defaultModel.
For example, the following specifies two models (named ABOX and TBOX) and an OWLPRIME rulebase for the default model. Note that models specified using the oracle:modelName predicate must exist; they will not be created automatically.
<#oracle> rdf:type oracle:Dataset;
joseki:poolSize 1 ; ## Number of concurrent connections allowed to this dataset.
oracle:connection
[ a oracle:OracleConnection ;
];
oracle:defaultModel [ oracle:firstModel "ABOX";
oracle:modelName "TBOX";
oracle:rulebaseName "OWLPRIME" ] .
Specify named graphs in the dataset. For example, you can create a named graph called <http://G1> based on two Oracle models and an entailment, as follows.
<#oracle> rdf:type oracle:Dataset;
joseki:poolSize 1 ; ## Number of concurrent connections allowed to this dataset.
oracle:connection
[ a oracle:OracleConnection ;
];
oracle:namedModel [ oracle:firstModel "ABOX";
oracle:modelName "TBOX";
oracle:rulebaseName "OWLPRIME";
oracle:namedModelURI <http://G1> ] .
The object of namedModel can take the same specifications as defaultModel, so virtual models are supported here as well (see also the next item).
Use a virtual model for queries by adding oracle:useVM "TRUE", as shown in the following example. Note that if the specified virtual model does not exist, it will automatically be created on demand.
<#oracle> rdf:type oracle:Dataset;
joseki:poolSize 1 ; ## Number of concurrent connections allowed to this dataset.
oracle:connection
[ a oracle:OracleConnection ;
];
oracle:defaultModel [ oracle:firstModel "ABOX";
oracle:modelName "TBOX";
oracle:rulebaseName "OWLPRIME";
oracle:useVM "TRUE"
] .
For more information, see Section 7.10.1, "Virtual Models Support".
Specify a virtual model as the default model to answer SPARQL queries by using the predicate oracle:virtualModelName, as shown in the following example with a virtual model named TRIPLE_DATA_VM_0:
oracle:defaultModel [ oracle:virtualModelName "TRIPLE_DATA_VM_0" ] .
If the underlying data consists of quads, you can use oracle:virtualModelName with oracle:allGraphs. The presence of oracle:allGraphs causes an instantiation of DatasetGraphOracleSem objects to answer named graph queries. An example is as follows:
oracle:allGraphs [ oracle:virtualModelName "QUAD_DATA_VM_0" ] .
Note that when a virtual model name is specified as the default graph, the endpoint can serve only query requests; SPARQL Update operations are not supported.
Set the queryOptions and inferenceMaintenance properties to change the query behavior and inference update mode. (See the Javadoc for information about QueryOptions and InferenceMaintenanceMode.)
By default, QueryOptions.ALLOW_QUERY_INVALID_AND_DUP and InferenceMaintenanceMode.NO_UPDATE are set, for maximum query flexibility and efficiency.
For every database connection created or used by the Jena Adapter, a client identifier is associated with the connection. The client identifier can be helpful, especially in a Real Application Cluster (Oracle RAC) environment, for isolating Jena Adapter-related activities from other database activities when you are doing performance analysis and tuning.
By default, the client identifier assigned is JenaAdapter. However, you can specify a different value by setting the Java VM clientIdentifier property using the following format:
-Doracle.spatial.rdf.client.jena.clientIdentifier=<identificationString>
To start the tracing of only Jena Adapter-related activities on the database side, you can use the DBMS_MONITOR.CLIENT_ID_TRACE_ENABLE procedure. For example:
SQL> EXECUTE DBMS_MONITOR.CLIENT_ID_TRACE_ENABLE('JenaAdapter', true, true);
By default, the Jena Adapter creates the application tables and any staging tables (the latter used for bulk loading, as explained in Section 7.11) using basic table compression with the following syntax:
CREATE TABLE .... (... column definitions ...) ... compress;
However, if you are licensed to use the Oracle Advanced Compression option no the database, you can set the following JVM property to turn on OLTP compression, which compresses data during all DML operations against the underlying application tables and staging tables:
-Doracle.spatial.rdf.client.jena.advancedCompression="compress for oltp"
Because some applications need to be able to terminate long-running SPARQL queries, an abort framework has been introduced with the Jena Adapter and the Joseki setup. Basically, for queries that may take a long time to run, you must stamp each with a unique query ID (qid) value.
For example, the following SPARQL query selects out the subject of all triples. A query ID (qid) is set so that this query can be terminated upon request.
PREFIX ORACLE_SEM_FS_NS: <http://example.com/semtech#qid=8761>
SELECT ?subject WHERE {?subject ?property ?object }
The qid attribute value is of long integer type. You can choose a value for the qid for a particular query based on your own application needs.
To terminate a SPARQL query that has been submitted with a qid value, applications can send an abort request to a servlet in the following format and specify a matching QID value
http://<hostname>:7001/joseki/querymgt?abortqid=8761
For any non-ASCII characters in the lexical representation of RDF resources, \uHHHH N-Triples encoding is used when the characters are inserted into the Oracle database. (For details about N-Triples encoding, see http://www.w3.org/TR/rdf-testcases/#ntrip_grammar.) Encoding of the constant resources in a SPARQL query is handled in a similar fashion.
Using \uHHHH N-Triples encoding enables support for international characters, such as a mix of Norwegian and Swedish characters, in the Oracle database even if a supported Unicode character set is not being used.
To use the Jena Adapter to perform queries, you can connec t as any user (with suitable privileges) and use any models in the semantic network. If your Semantic Technologies environment already meets the requirements, you can go directly to compiling and running Java code that uses the Jena Adapter. If your Semantic Technologies environment is not yet set up to be able to use the Jena Adapter, you can perform actions similar to the following example steps:
Connect as SYS with the SYSDBA role:
sqlplus sys/<password-for-sys> as sysdba
Create a tablespace for the system tables. For example:
CREATE TABLESPACE rdf_users datafile 'rdf_users01.dbf'
size 128M reuse autoextend on next 64M
maxsize unlimited segment space management auto;
Create the semantic network. For example:
EXECUTE sem_apis.create_sem_network('RDF_USERS');
Create a database user (for connecting to the database to use the semantic network and the Jena Adapter). For example:
CREATE USER rdfusr IDENTIFIED BY <password-for-udfusr>
DEFAULT TABLESPACE rdf_users;
Grant the necessary privileges to this database user. For example:
GRANT connect, resource TO rdfusr;
To use the Jena Adapter with your own semantic data, perform the appropriate steps to store data, create a model, and create database indexes, as explained in Section 1.10, "Quick Start for Using Semantic Data". Then perform queries by compiling and running Java code; see Section 7.15 for information about example queries.
To use the Jena Adapter with supplied example data, see Section 7.15.
There are two ways to query semantic data stored in Oracle Database: SEM_MATCH-based SQL statements and SPARQL queries through the Jena Adapter. Queries using each approach are similar in appearance, but there are important behavioral differences. To ensure consistent application behavior, you must understand the differences and use care when dealing with query results coming from SEM_MATCH queries and SPARQL queries.
The following simple examples show the two approaches.
Query 1 (SEM_MATCH-based)
select s, p, o
from table(sem_match('{?s ?p ?o}', sem_models('Test_Model'), ....))
Query 2 (SPARQL query through the Jena Adapter)
select ?s ?p ?o
where {?s ?p ?o}
These two queries perform the same kind of functions; however, there are some important differences. Query 1 (SEM_MATCH-based):
Reads all triples out of Test_Model.
Does not differentiate among URI, bNode, plain literals, and typed literals, and it does not handle long literals.
Does not unescape certain characters (such as '\n').
Query 2 (SPARQL query executed through the Jena Adapter) also reads all triples out of Test_Model (assume it executed a call to ModelOracleSem referring to the same underlying Test_Model). However, Query 2:
Reads out additional columns (as opposed to just the s, p, and o columns with the SEM_MATCH table function), to differentiate URI, bNodes, plain literals, typed literals, and long literals. This is to ensure proper creation of Jena Node objects.
Unescapes those characters that are escaped when stored in Oracle Database
Blank node handling is another difference between the two approaches:
In a SEM_MATCH-based query, blank nodes are always treated as constants.
In a SPARQL query, a blank node that is not wrapped inside < and > is treated as a variable when the query is executed through the Jena Adapter. This matches the SPARQL standard semantics. However, a blank node that is wrapped inside < and > is treated as a constant when the query is executed, and the Jena Adapter adds a proper prefix to the blank node label as required by the underlying data modeling.
The maximum length for the name of a semantic model created using the Jena Adapter API is 22 characters.
This section describes some performance-related features of the Jena Adapter that can enhance SPARQL query processing. These features are performed automatically by default.
This section assumes that you are familiar with SPARQL, including the CONSTRUCT feature and property paths.
SPARQL queries involving DISTINCT, OPTIONAL, FILTER, UNION, ORDER BY, and LIMIT are converted to a single Oracle SEM_MATCH table function. If a query cannot be converted directly to SEM_MATCH because it uses SPARQL features not supported by SEM_MATCH (for example, CONSTRUCT), the Jena Adapter employs a hybrid approach and tries to execute the largest portion of the query using a single SEM_MATCH function while executing the rest using the Jena ARQ query engine.
For example, the following SPARQL query is directly translated to a single SEM_MATCH table function:
PREFIX dc: <http://purl.org/dc/elements/1.1/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
SELECT ?person ?name
WHERE {
{?alice foaf:knows ?person . }
UNION {
?person ?p ?name. OPTIONAL { ?person ?x ?name1 }
}
}
However, the following example query is not directly translatable to a single SEM_MATCH table function because of the CONSTRUCT keyword:
PREFIX vcard: <http://www.w3.org/2001/vcard-rdf/3.0#>
CONSTRUCT { <http://example.org/person#Alice> vcard:FN ?obj }
WHERE { { ?x <http://pred/a> ?obj.}
UNION
{ ?x <http://pred/b> ?obj.} }
In this case, the Jena Adapter converts the inner UNION query into a single SEM_MATCH table function, and then passes on the result set to the Jena ARQ query engine for further evaluation.
As defined in Jena, a property path is a possible route through an RDF graph between two graph nodes. Property paths are an extension of SPARQL and are more expressive than basic graph pattern queries, because regular expressions can be used over properties for pattern matching RDF graphs. For more information about property paths, see the documentation for the Jena ARQ query engine.
The Jena Adapter supports all Jena property path types through the integration with the Jena ARQ query engine, but it converts some common path types directly to native SQL hierarchical queries (not based on SEM_MATCH) to improve performance. The following types of property paths are directly converted to SQL by the Jena Adapter when dealing with triple data:
Predicate alternatives: (p1 | p2 | … | pn) where pi is a property URI
Predicate sequences: (p1 / p2 / … / pn) where pi is a property URI
Reverse paths : ( ^ p ) where p is a predicate URI
Complex paths: p+, p*, p{0, n} where p could be an alternative, sequence, reverse path, or property URI
Path expressions that cannot be captured in this grammar are not translated directly to SQL by the Jena Adapter, and they are answered using the Jena query engine.
The following example contains a code snippet using a property path expression with path sequences:
String m = "PROP_PATH";
ModelOracleSem model = ModelOracleSem.createOracleSemModel(oracle, m);
GraphOracleSem graph = new GraphOracleSem(oracle, m);
// populate the RDF Graph
graph.add(Triple.create(Node.createURI("http://a"),
Node.createURI("http://p1"),
Node.createURI("http://b")));
graph.add(Triple.create(Node.createURI("http://b"),
Node.createURI("http://p2"),
Node.createURI("http://c")));
graph.add(Triple.create(Node.createURI("http://c"),
Node.createURI("http://p5"),
Node.createURI("http://d")));
String query =
" SELECT ?s " +
" WHERE {?s (<http://p1>/<http://p2>/<http://p5>)+ <http://d>.}";
QueryExecution qexec =
QueryExecutionFactory.create(QueryFactory.create(query,
Syntax.syntaxARQ), model);
try {
ResultSet results = qexec.execSelect();
ResultSetFormatter.out(System.out, results);
}
finally {
if (qexec != null)
qexec.close();
}
OracleUtils.dropSemanticModel(oracle, m);
model.close();
The Jena Adapter allows you to pass in hints and additional query options. It implements these capabilities by overloading the SPARQL namespace prefix syntax by using Oracle-specific namespaces that contain query options. The namespaces are in the form PREFIX ORACLE_SEM_xx_NS, where xx indicates the type of feature (such as HT for hint or AP for additional predicate)
SQL hints can be passed to a SEM_MATCH query including a line in the following form:
PREFIX ORACLE_SEM_HT_NS: <http://oracle.com/semtech#hint>
Where hint can be any hint supported by SEM_MATCH. For example:
PREFIX ORACLE_SEM_HT_NS: <http://oracle.com/semtech#leading(t0,t1)>
SELECT ?book ?title ?isbn
WHERE { ?book <http://title> ?title. ?book <http://ISBN> ?isbn }
In this example, t0,t1 refers to the first and second patterns in the query.
Note the slight difference in specifying hints when compared to SEM_MATCH. Due to restrictions of namespace value syntax, a comma (,) must be used to separate t0 and t1 (or other hint components) instead of a space.
For more information about using SQL hints, see Section 1.6, "Using the SEM_MATCH Table Function to Query Semantic Data", specifically the material about the HINT0 keyword in the options attribute.
In Oracle Database, using bind variables can reduce query parsing time and increase query efficiency and concurrency. Bind variable support in SPARQL queries is provided through namespace pragma specifications similar to ORACLE_SEM_FS_NS.
Consider a case where an application runs two SPARQL queries, where the second (Query 2) depends on the partial or complete results of the first (Query 1). Some approaches that do not involve bind variables include:
Iterating through results of Query 1 and generating a set of queries. (However, this approach requires as many queries as the number of results of Query 1.)
Constructing a SPARQL filter expression based on results of Query 1.
Treating Query 1 as a subquery.
Another approach in this case is to use bind variables, as in the following sample scenario:
Query 1: SELECT ?x WHERE { ... <some complex query> ... }; Query 2: SELECT ?subject ?x WHERE {?subject <urn:related> ?x .};
The following example shows Query 2 with the syntax for using bind variables with the Jena Adapter:
PREFIX ORACLE_SEM_FS_NS: <http://oracle.com/semtech#no_fall_back,s2s> PREFIX ORACLE_SEM_UEAP_NS: <http://oracle.com/semtech#x$RDFVID%20in(?,?,?)> PREFIX ORACLE_SEM_UEPJ_NS: <http://oracle.com/semtech#x$RDFVID> PREFIX ORACLE_SEM_UEBV_NS: <http://oracle.com/semtech#1,2,3> SELECT ?subject ?x WHERE { ?subject <urn:related> ?x };
This syntax includes using the following namespaces:
ORACLE_SEM_UEAP_NS is like ORACLE_SEM_AP_NS, but the value portion of ORACLE_SEM_UEAP_NS is URL Encoded. Before the value portion is used, it must be URL decoded, and then it will be treated as an additional predicate to the SPARQL query.
In this example, after URL decoding, the value portion (following the # character) of this ORACLE_SEM_UEAP_NS prefix becomes "x$RDFVID in(?,?,?)". The three question marks imply a binding to three values coming from Query 1.
ORACLE_SEM_UEPJ_NS specifies the additional projections involved. In this case, because ORACLE_SEM_UEAP_NS references the x$RDFVID column, which does not appear in the SELECT clause of the query, it must be specified. Multiple projections are separated by commas.
ORACLE_SEM_UEBV_NS specifies the list of bind values that are URL encoded first, and then concatenated and delimited by commas.
Conceptually, the preceding example query is equivalent to the following non-SPARQL syntax query, in which 1, 2, and 3 are treated as bind values:
SELECT ?subject ?x
WHERE {
?subject <urn:related> ?x
}
AND ?x$RDFVID in (1,2,3);
In the preceding SPARQL example of Query 2, the three integers 1, 2, and 3 come from Query 1. You can use the oext:build-uri-for-id function to generate such internal integer IDs for RDF resources. The following example gets the internal integer IDs from Query 1:
PREFIX oext: <http://oracle.com/semtech/jena-adaptor/ext/function#> SELECT ?x (oext:build-uri-for-id(?x) as ?xid) WHERE { ... <some complex query> ... };
The values of ?xid have the form of <rdfvid:integer-value>. The application can strip out the angle brackets and the "rdfvid:" strings to get the integer values and pass them to Query 2.
Consider another case, with a single query structure but potentially many different constants. For example, the following SPARQL query finds the hobby for each user who has a hobby and who logs in to an application. Obviously, different users will provide different <uri> values to this SPARQL query, because users of the application are represented using different URIs.
SELECT ?hobby
WHERE { <uri> <urn:hasHobby> ?hobby };
One approach, which would not use bind variables, is to generate a different SPARQL query for each different <uri> value. For example, user Jane Doe might trigger the execution of the following SPARQL query:
SELECT ?hobby WHERE {
<http://www.example.com/Jane_Doe> <urn:hasHobby> ?hobby };
However, another approach is to use bind variables, as in the following example specifying user Jane Doe:
PREFIX ORACLE_SEM_FS_NS: <http://oracle.com/semtech#no_fall_back,s2s>
PREFIX ORACLE_SEM_UEAP_NS: <http://oracle.com/semtech#subject$RDFVID%20in(ORACLE_ORARDF_RES2VID(?))>
PREFIX ORACLE_SEM_UEPJ_NS: <http://oracle.com/semtech#subject$RDFVID>
PREFIX ORACLE_SEM_UEBV_NS: <http://oracle.com/semtech#http%3a%2f%2fwww.example.com%2fJohn_Doe>
SELECT ?subject ?hobby
WHERE {
?subject <urn:hasHobby> ?hobby
};
Conceptually, the preceding example query is equivalent to the following non-SPARQL syntax query, in which http://www.example.com/Jane_Doe is treated as a bind variable:
SELECT ?subject ?hobby
WHERE {
?subject <urn:hasHobby> ?hobby
}
AND ?subject$RDFVID in (ORACLE_ORARDF_RES2VID('http://www.example.com/Jane_Doe'));
In this example, ORACLE_ORARDF_RES2VID is a function that translates URIs and literals into their internal integer ID representation. This function is created automatically when the Jena Adapter is used to connect to an Oracle database.
The SEM_MATCH filter attribute can specify additional selection criteria as a string in the form of a WHERE clause without the WHERE keyword. Additional WHERE clause predicates can be passed to a SEM_MATCH query including a line in the following form:
PREFIX ORACLE_SEM_AP_NS: <http://oracle.com/semtech#pred>
Where pred reflects the WHERE clause content to be appended to the query. For example:
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX ORACLE_SEM_AP_NS:<http://www.oracle.com/semtech#label$RDFLANG='fr'>
SELECT DISTINCT ?inst ?label
WHERE { ?inst a <http://someCLass>. ?inst rdfs:label ?label . }
ORDER BY (?label) LIMIT 20
In this example, a restriction is added to the query that the language type of the label variable must be 'fr'.
Additional query options can be passed to a SEM_MATCH query including a line in the following form:
PREFIX ORACLE_SEM_FS_NS: <http://oracle.com/semtech#option>
Where option reflects a query option (or multiple query options delimited by commas) to be appended to the query. For example:
PREFIX ORACLE_SEM_FS_NS:
<http://oracle.com/semtech#timeout=3,dop=4,INF_ONLY,ORDERED,ALLOW_DUP=T>
SELECT * WHERE {?subject ?property ?object }
The following query options are supported:
ALLOW_DUP=t chooses a faster way to query multiple semantic models, although duplicate results may occur.
BEST_EFFORT_QUERY=t, when used with the TIMEOUT=n option, returns all matches found in n seconds for the SPARQL query.
DEGREE=n specifies, at the statement level, the degree of parallelism (n) for the query. With multi-core or multi-CPU processors, experimenting with different DOP values (such as 4 or 8) may improve performance.
Contrast DEGREE with DOP, which specifies parallelism at the session level. DEGREE is recommended over DOP for use with the Jena Adapter, because DEGREE involves less processing overhead.
DOP=n specifies, at the session level, the degree of parallelism (n) for the query. With multi-core or multi-CPU processors, experimenting with different DOP values (such as 4 or 8) may improve performance.
INF_ONLY causes only the inferred model to be queried.
JENA_EXECUTOR disables the compilation of SPARQL queries to SEM_MATCH (or native SQL); instead, the Jena native query executor will be used.
JOIN=n specifies how results from a SPARQL SERVICE call to a federated query can be joined with other parts of the query. For information about federated queries and the JOIN option, see Section 7.6.4.1.
NO_FALL_BACK causes the underlying query execution engine not to fall back on the Jena execution mechanism if a SQL exception occurs.
ODS=n specifies, at the statement level, the level of dynamic sampling. (For an explanation of dynamic sampling, see the section about estimating statistics with dynamic sampling in Oracle Database Performance Tuning Guide.) Valid values for n are 1 through 10. For example, you could try ODS=3 for complex queries.
ORDERED is translated to a LEADING SQL hint for the query triple pattern joins, while performing the necessary RDF_VALUE$ joins last.
PLAIN_SQL_OPT=F disables the native compilation of queries directly to SQL.
QID=n specifies a query ID number; this feature can be used to cancel the query if it is not responding.
RESULT_CACHE uses the Oracle RESULT_CACHE directive for the query.
REWRITE=F disables ODCI_Table_Rewrite for the SEM_MATCH table function.
SKIP_CLOB=T causes CLOB values not to be returned for the query.
S2S (SPARQL to pure SQL) causes the underlying SEM_MATCH-based query or queries generated based on the SPARQL query to be further converted into SQL queries without using the SEM_MATCH table function. The resulting SQL queries are executed by the Oracle cost-based optimizer, and the results are processed by the Jena Adapter before being passed on to the client. For more information about the S2S option, including benefits and usage information, see Section 7.6.4.2.
S2S is enabled by default for all SPARQL queries. If you want to disable S2S, set the following JVM system property:
-Doracle.spatial.rdf.client.jena.defaultS2S=false
TIMEOUT=n (query timeout) specifies the number of seconds (n) that the query will run until it is terminated. The underlying SQL generated from a SPARQL query can return many matches and can use features like subqueries and assignments, all of which can take considerable time. The TIMEOUT and BEST_EFFORT_QUERY=t options can be used to prevent what you consider excessive processing time for the query.
A SPARQL federated query, as described in W3C documents, is a query "over distributed data" that entails "querying one source and using the acquired information to constrain queries of the next source." For more information, see SPARQL 1.1 Federation Extensions (http://www.w3.org/2009/sparql/docs/fed/service).
You can use the JOIN option (described in Section 7.6.4) and the SERVICE keyword in a federated query that uses the Jena Adapter. For example, assume the following query:
SELECT ?s ?s1 ?o
WHERE { ?s1 ?p1 ?s .
{
SERVICE <http://sparql.org/books> { ?s ?p ?o }
}
}
If the local query portion (?s1 ?p1 ?s,) is very selective, you can specify join=2, as shown in the following query:
PREFIX ORACLE_SEM_FS_NS: <http://oracle.com/semtech#join=2>
SELECT ?s ?s1 ?o
WHERE { ?s1 ?p1 ?s .
{
SERVICE <http://sparql.org/books> { ?s ?p ?o }
}
}
In this case, the local query portion (?s1 ?p1 ?s,) is executed locally against the Oracle database. Each binding of ?s from the results is then pushed into the SERVICE part (remote query portion), and a call is made to the service endpoint specified. Conceptually, this approach is somewhat like nested loop join.
If the remote query portion (?s ?s1 ?o) is very selective, you can specify join=3, as shown in the following query, so that the remote portion is executed first and results are used to drive the execution of local portion:
PREFIX ORACLE_SEM_FS_NS: <http://oracle.com/semtech#join=3>
SELECT ?s ?s1 ?o
WHERE { ?s1 ?p1 ?s .
{
SERVICE <http://sparql.org/books> { ?s ?p ?o }
}
}
In this case, a single call is made to the remote service endpoint and each binding of ?s triggers a local query. As with join=2, this approach is conceptually a nested loop based join, but the difference is that the order is switched.
If neither the local query portion nor the remote query portion is very selective, then we can choose join=1, as shown in the following query:
PREFIX ORACLE_SEM_FS_NS: <http://oracle.com/semtech#join=1>
SELECT ?s ?s1 ?o
WHERE { ?s1 ?p1 ?s .
{
SERVICE <http://sparql.org/books> { ?s ?p ?o }
}
}
In this case, the remote query portion and the local portion are executed independently, and the results are joined together by Jena. Conceptually, this approach is somewhat like a hash join.
For debugging or tracing federated queries, you can use the HTTP Analyzer in Oracle JDeveloper to see the underlying SERVICE calls.
The S2S option, described in Section 7.6.4, provides the following potential benefits:
It works well with the RESULT_CACHE option to improve query performance. Using the S2S and RESULT_CACHE options is especially helpful for queries that are executed frequently.
It reduces the parsing time of the SEM_MATCH table function, which can be helpful for applications that involve many dynamically generated SPARQL queries.
It eliminates the limit of 4000 bytes for the query body (the first parameter of the SEM_MATCH table function), which means that longer, more complex queries are supported.
The S2S option causes an internal in-memory cache to be used for translated SQL query statements. The default size of this internal cache is 1024 (that is, 1024 SQL queries); however, you can adjust the size by using the following Java VM property:
-Doracle.spatial.rdf.client.jena.queryCacheSize=<size>
When semantic data is stored, all of the resource values are hashed into IDs, which are stored in the triples table. The mappings from value IDs to full resource values are stored in the MDSYS.RDF_VALUE$ table. At query time, for each selected variable, Oracle Database must perform a join with the RDF_VALUE$ table to retrieve the resource.
However, to reduce the number of joins, you can use the midtier cache option, which causes an in-memory cache on the middle tier to be used for storing mappings between value IDs and resource values. To use this feature, include the following PREFIX pragma in the SPARQL query:
PREFIX ORACLE_SEM_FS_NS: <http://oracle.com/semtech#midtier_cache>
To control the maximum size (in bytes) of the in-memory cache, use the oracle.spatial.rdf.client.jena.cacheMaxSize system property. The default cache maximum size is 1GB.
Note that midtier resource caching is most effective for queries using ORDER BY or DISTINCT (or both) constructs, or queries with multiple projection variables. Midtier cache can be combined with the other options specified in Section 7.6.4.
If you want to pre-populate the cache with all of the resources in a model, use the GraphOracleSem.populateCache or DatasetGraphOracleSem.populateCache method. Both methods take a parameter specifying the number of threads used to build the internal midtier cache. Running either method in parallel can significantly increase the cache building performance on a machine with multiple CPUs (cores).
SPARQL queries through the Jena Adapter can use the following kinds of functions:
Functions in the function library of the Jena ARQ query engine
Native Oracle Database functions for projected variables
User-defined functions
SPARQL queries through the Jena Adapter can use functions in the function library of the Jena ARQ query engine. These queries are executed in the middle tier.
The following examples use the upper-case and namespace functions. In these examples, the prefix fn is <http://www.w3.org/2005/xpath-functions#> and the prefix afn is <http://jena.hpl.hp.com/ARQ/function#>.
PREFIX fn: <http://www.w3.org/2005/xpath-functions#>
PREFIX afn: <http://jena.hpl.hp.com/ARQ/function#>
SELECT (fn:upper-case(?object) as ?object1)
WHERE { ?subject dc:title ?object }
PREFIX fn: <http://www.w3.org/2005/xpath-functions#>
PREFIX afn: <http://jena.hpl.hp.com/ARQ/function#>
SELECT ?subject (afn:namespace(?object) as ?object1)
WHERE { ?subject <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> ?object }
SPARQL queries through the Jena Adapter can use native Oracle Database functions for projected variables. These queries and the functions are executed inside the database. Note that the functions described in this section should not be used together with ARQ functions (described in Section 7.7.1).
This section lists the supported native functions and provides some examples. In the examples, the prefix oext is <http://oracle.com/semtech/jena-adaptor/ext/function#>.
|
Note: In the preceding URL, note the spellingjena-adaptor, which is retained for compatibility with existing applications and which must be used in queries. The adapter spelling is used in regular text, to follow Oracle documentation style guidelines. |
oext:upper-literal converts literal values (except for long literals) to uppercase. For example:
PREFIX oext: <http://oracle.com/semtech/jena-adaptor/ext/function#>
SELECT (oext:upper-literal(?object) as ?object1)
WHERE { ?subject dc:title ?object }
oext:lower-literal converts literal values (except for long literals) to lowercase. For example:
PREFIX oext: <http://oracle.com/semtech/jena-adaptor/ext/function#>
SELECT (oext:lower-literal(?object) as ?object1)
WHERE { ?subject dc:title ?object }
oext:build-uri-for-id converts the value ID of a URI, bNode, or literal into a URI form. For example:
PREFIX oext: <http://oracle.com/semtech/jena-adaptor/ext/function#>
SELECT (oext:build-uri-for-id(?object) as ?object1)
WHERE { ?subject dc:title ?object }
An example of the output might be: <rdfvid:1716368199350136353>
One use of this function is to allow Java applications to maintain in memory a mapping of those value IDs to the lexical form of URIs, bNodes, or literals. The MDSYS.RDF_VALUE$ table provides such a mapping in Oracle Database.
For a given variable ?var, if only oext:build-uri-for-id(?var) is projected, the query performance is likely to be faster because fewer internal table join operations are needed to answer the query.
oext:literal-strlen returns the length of literal values (except for long literals). For example:
PREFIX oext: <http://oracle.com/semtech/jena-adaptor/ext/function#>
SELECT (oext:literal-strlen(?object) as ?objlen)
WHERE { ?subject dc:title ?object }
SPARQL queries through the Jena Adapter can use user-defined functions that are stored in the database.
In the following example, assume that you want to define a string length function (my_strlen) that handles long literals (CLOB) as well as short literals. On the SPARQL query side, this function can be referenced under the namespace of ouext, which is http://oracle.com/semtech/jena-adaptor/ext/user-def-function#.
PREFIX ouext: <http://oracle.com/semtech/jena-adaptor/ext/user-def-function#>
SELECT ?subject ?object (ouext:my_strlen(?object) as ?obj1)
WHERE { ?subject dc:title ?object }
Inside the database, functions including my_strlen, my_strlen_cl, my_strlen_la, my_strlen_lt, and my_strlen_vt are defined to implement this capability. Conceptually, the return values of these functions are mapped as shown in Table 7-1.
Table 7-1 Functions and Return Values for my_strlen Example
| Function Name | Return Value |
|---|---|
|
my_strlen |
<VAR> |
|
my_strlen_cl |
<VAR>$RDFCLOB |
|
my_strlen_la |
<VAR>$RDFLANG |
|
my_strlen_lt |
<VAR>$RDFLTYP |
|
my_strlen_vt |
<VAR>$RDFVTYP |
A set of functions (five in all) is used to implement a user-defined function that can be referenced from SPARQL, because this aligns with the internal representation of an RDF resource (in MDSYS.RDF_VALUE$). There are five major columns describing an RDF resource in terms of its value, language, literal type, long value, and value type, and these five columns can be selected out using SEM_MATCH. In this context, a user-defined function simply converts one RDF resource that is represented by five columns to another RDF resource.
These functions are defined as follows:
create or replace function my_strlen(rdfvtyp in varchar2, rdfltyp in varchar2, rdflang in varchar2, rdfclob in clob, value in varchar2 ) return varchar2 as ret_val varchar2(4000); begin -- value if (rdfvtyp = 'LIT') then if (rdfclob is null) then return length(value); else return dbms_lob.getlength(rdfclob); end if; else -- Assign -1 for non-literal values so that application can -- easily differentiate return '-1'; end if; end; / create or replace function my_strlen_cl(rdfvtyp in varchar2, rdfltyp in varchar2, rdflang in varchar2, rdfclob in clob, value in varchar2 ) return clob as begin return null; end; / create or replace function my_strlen_la(rdfvtyp in varchar2, rdfltyp in varchar2, rdflang in varchar2, rdfclob in clob, value in varchar2 ) return varchar2 as begin return null; end; / create or replace function my_strlen_lt(rdfvtyp in varchar2, rdfltyp in varchar2, rdflang in varchar2, rdfclob in clob, value in varchar2 ) return varchar2 as ret_val varchar2(4000); begin -- literal type return 'http://www.w3.org/2001/XMLSchema#integer'; end; / create or replace function my_strlen_vt(rdfvtyp in varchar2, rdfltyp in varchar2, rdflang in varchar2, rdfclob in clob, value in varchar2 ) return varchar2 as ret_val varchar2(3); begin return 'LIT'; end; /
User-defined functions can also accept a parameter of VARCHAR2 type. The following five functions together define a my_shorten_str function that accepts an integer (in VARCHAR2 form) for the substring length and returns the substring. (The substring in this example is 12 characters, and it must not be greater than 4000 bytes.)
-- SPARQL query that returns the first 12 characters of literal values.
--
PREFIX ouext: <http://oracle.com/semtech/jena-adaptor/ext/user-def-function#>
SELECT (ouext:my_shorten_str(?object, "12") as ?obj1) ?subject
WHERE { ?subject dc:title ?object }
create or replace function my_shorten_str(rdfvtyp in varchar2,
rdfltyp in varchar2,
rdflang in varchar2,
rdfclob in clob,
value in varchar2,
arg in varchar2
) return varchar2
as
ret_val varchar2(4000);
begin
-- value
if (rdfvtyp = 'LIT') then
if (rdfclob is null) then
return substr(value, 1, to_number(arg));
else
return dbms_lob.substr(rdfclob, to_number(arg), 1);
end if;
else
return null;
end if;
end;
/
create or replace function my_shorten_str_cl(rdfvtyp in varchar2,
rdfltyp in varchar2,
rdflang in varchar2,
rdfclob in clob,
value in varchar2,
arg in varchar2
) return clob
as
ret_val clob;
begin
-- lob
return null;
end;
/
create or replace function my_shorten_str_la(rdfvtyp in varchar2,
rdfltyp in varchar2,
rdflang in varchar2,
rdfclob in clob,
value in varchar2,
arg in varchar2
) return varchar2
as
ret_val varchar2(4000);
begin
-- lang
if (rdfvtyp = 'LIT') then
return rdflang;
else
return null;
end if;
end;
/
create or replace function my_shorten_str_lt(rdfvtyp in varchar2,
rdfltyp in varchar2,
rdflang in varchar2,
rdfclob in clob,
value in varchar2,
arg in varchar2
) return varchar2
as
ret_val varchar2(4000);
begin
-- literal type
ret_val := rdfltyp;
return ret_val;
end;
/
create or replace function my_shorten_str_vt(rdfvtyp in varchar2,
rdfltyp in varchar2,
rdflang in varchar2,
rdfclob in clob,
value in varchar2,
arg in varchar2
) return varchar2
as
ret_val varchar2(3);
begin
return 'LIT';
end;
/
The Jena Adapter supports SPARQL Update (http://www.w3.org/TR/sparql11-update/), also referred to as SPARUL. The primary programming APIs involve the Jena class UpdateAction (in package com.hp.hpl.jena.update) and the Jena Adapter classes GraphOracleSem and DatasetGraphOracleSem. Example 7-1 shows a SPARQL Update operation removes all triples in named graph <http://example/graph> from the relevant model stored in the database.
Example 7-1 Simple SPARQL Update
GraphOracleSem graphOracleSem = .... ; DatasetGraphOracleSem dsgos = DatasetGraphOracleSem.createFrom(graphOracleSem); // SPARQL Update operation String szUpdateAction = "DROP GRAPH <http://example/graph>"; // Execute the Update against a DatasetGraph instance (can be a Jena Model as well) UpdateAction.parseExecute(szUpdateAction, dsgos);
Note that Oracle Database does not keep any information about an empty named graph. This implies if you invoke CREATE GRAPH <graph_name> without adding any triples into this graph, then no additional rows in the application table or the underlying RDF_LINK$ table will be created. To an Oracle database, you can safely skip the CREATE GRAPH step, as is the case in Example 7-1.
Example 7-2 shows a SPARQL Update operation (from ARQ 2.8.8) involving multiple insert and delete operations.
Example 7-2 SPARQL Update with Insert and Delete Operations
PREFIX : <http://example/>
CREATE GRAPH <http://example/graph> ;
INSERT DATA { :r :p 123 } ;
INSERT DATA { :r :p 1066 } ;
DELETE DATA { :r :p 1066 } ;
INSERT DATA {
GRAPH <http://example/graph> { :r :p 123 . :r :p 1066 }
} ;
DELETE DATA {
GRAPH <http://example/graph> { :r :p 123 }
}
After running the update operation in Example 7-2 against an empty DatasetGraphOracleSem, running the SPARQL query SELECT ?s ?p ?o WHERE {?s ?p ?o} generates the following response:
----------------------------------------------------------------------------------------------- | s | p | o | =============================================================================================== | <http://example/r> | <http://example/p> | "123"^^<http://www.w3.org/2001/XMLSchema#decimal> | -----------------------------------------------------------------------------------------------
Using the same data, running the SPARQL query SELECT ?g ?s ?p ?o where {GRAPH ?g {?s ?p ?o}} generates the following response:
------------------------------------------------------------------------------------------------------------------------- | g | s | p | o | ========================================================================================================================= | <http://example/graph> | <http://example/r> | <http://example/p> | "1066"^^<http://www.w3.org/2001/XMLSchema#decimal> | -------------------------------------------------------------------------------------------------------------------------
In addition to using the Java API for SPARQL Update operations, you can configure Joseki to accept SPARQL Update operations by removing the comment (##) characters at the start of the following lines in the joseki-config.ttl file.
## <#serviceUpdate> ## rdf:type joseki:Service ; ## rdfs:label "SPARQL/Update" ; ## joseki:serviceRef "update/service" ; ## # dataset part ## joseki:dataset <#oracle>; ## # Service part. ## # This processor will not allow either the protocol, ## # nor the query, to specify the dataset. ## joseki:processor joseki:ProcessorSPARQLUpdate ## . ## ## <#serviceRead> ## rdf:type joseki:Service ; ## rdfs:label "SPARQL" ; ## joseki:serviceRef "sparql/read" ; ## # dataset part ## joseki:dataset <#oracle> ; ## Same dataset ## # Service part. ## # This processor will not allow either the protocol, ## # nor the query, to specify the dataset. ## joseki:processor joseki:ProcessorSPARQL_FixedDS ; ## .
After you edit the joseki-config.ttl file, you must restart the Joseki Web application. You can then try a simple update operation, as follows:
In your browser, go to: http://<hostname>:7001/joseki/update.html
Type or paste the following into the text box:
PREFIX : <http://example/>
INSERT DATA {
GRAPH <http://example/g1> { :r :p 455 }
}
Click Perform SPARQL Update.
To verify that the update operation was successful, go to http://<hostname>:7001/joseki and enter the following query:
SELECT *
WHERE
{ GRAPH <http://example/g1> {?s ?p ?o}};
The response should contain the following triple:
<http://example/r> <http://example/p> "455"^^<http://www.w3.org/2001/XMLSchema#decimal>
A SPARQL Update can also be sent using an HTTP POST operation to the http://<hostname>:7001/joseki/update/service. For example, you can use curl (http://en.wikipedia.org/wiki/CURL) to send an HTTP POST request to perform the update operation:
curl --data "request=PREFIX%20%3A%20%3Chttp%3A%2F%2Fexample%2F%3E%20%0AINSERT%20DATA%20%7B%0A%20%20GRAPH%20%3Chttp%3A%2F%2Fexample%2Fg1%3E%20%7B%20%3Ar%20%3Ap%20888%20%7D%0A%7D%0A" http://hostname:7001/joseki/update/service
In the preceding example, the URL encoded string is a simple INSERT operation into a named graph. After decoding, it reads as follows:
PREFIX : <http://example/>
INSERT DATA {
GRAPH <http://example/g1> { :r :p 888 }
You can perform analytical functions on RDF data by using the SemNetworkAnalyst class in the oracle.spatial.rdf.client.jena package. This support integrates the Oracle Spatial network data model (NDM) logic with the underlying RDF data structures. Therefore, to use analytical functions on RDF data, you must be familiar with the Oracle Spatial NDM, which is documented in Oracle Spatial Topology and Network Data Models Developer's Guide.
The required NDM Java libraries, including sdonm.jar and sdoutl.jar, are under the directory $ORACLE_HOME/md/jlib. Note that xmlparserv2.jar (under $ORACLE_HOME/xdk/lib) must be included in the classpath definition.
Example 7-3 uses the SemNetworkAnalyst class, which internally uses the NDM NetworkAnalyst API
Example 7-3 Performing Analytical functions on RDF Data
Oracle oracle = new Oracle(jdbcUrl, user, password);
GraphOracleSem graph = new GraphOracleSem(oracle, modelName);
Node nodeA = Node.createURI("http://A");
Node nodeB = Node.createURI("http://B");
Node nodeC = Node.createURI("http://C");
Node nodeD = Node.createURI("http://D");
Node nodeE = Node.createURI("http://E");
Node nodeF = Node.createURI("http://F");
Node nodeG = Node.createURI("http://G");
Node nodeX = Node.createURI("http://X");
// An anonymous node
Node ano = Node.createAnon(new AnonId("m1"));
Node relL = Node.createURI("http://likes");
Node relD = Node.createURI("http://dislikes");
Node relK = Node.createURI("http://knows");
Node relC = Node.createURI("http://differs");
graph.add(new Triple(nodeA, relL, nodeB));
graph.add(new Triple(nodeA, relC, nodeD));
graph.add(new Triple(nodeB, relL, nodeC));
graph.add(new Triple(nodeA, relD, nodeC));
graph.add(new Triple(nodeB, relD, ano));
graph.add(new Triple(nodeC, relL, nodeD));
graph.add(new Triple(nodeC, relK, nodeE));
graph.add(new Triple(ano, relL, nodeD));
graph.add(new Triple(ano, relL, nodeF));
graph.add(new Triple(ano, relD, nodeB));
// X only likes itself
graph.add(new Triple(nodeX, relL, nodeX));
graph.commitTransaction();
HashMap<Node, Double> costMap = new HashMap<Node, Double>();
costMap.put(relL, Double.valueOf((double)0.5));
costMap.put(relD, Double.valueOf((double)1.5));
costMap.put(relC, Double.valueOf((double)5.5));
graph.setDOP(4); // this allows the underlying LINK/NODE tables
// and indexes to be created in parallel.
SemNetworkAnalyst sna = SemNetworkAnalyst.getInstance(
graph, // network data source
true, // directed graph
true, // cleanup existing NODE and LINK table
costMap
);
psOut.println("From nodeA to nodeC");
Node[] nodeArray = sna.shortestPathDijkstra(nodeA, nodeC);
printNodeArray(nodeArray, psOut);
psOut.println("From nodeA to nodeD");
nodeArray = sna.shortestPathDijkstra( nodeA, nodeD);
printNodeArray(nodeArray, psOut);
psOut.println("From nodeA to nodeF");
nodeArray = sna.shortestPathAStar(nodeA, nodeF);
printNodeArray(nodeArray, psOut);
psOut.println("From ano to nodeC");
nodeArray = sna.shortestPathAStar(ano, nodeC);
printNodeArray(nodeArray, psOut);
psOut.println("From ano to nodeX");
nodeArray = sna.shortestPathAStar(ano, nodeX);
printNodeArray(nodeArray, psOut);
graph.close();
oracle.dispose();
...
...
// A helper function to print out a path
public static void printNodeArray(Node[] nodeArray, PrintStream psOut)
{
if (nodeArray == null) {
psOut.println("Node Array is null");
return;
}
if (nodeArray.length == 0) {psOut.println("Node Array is empty"); }
int iFlag = 0;
psOut.println("printNodeArray: full path starts");
for (int iHops = 0; iHops < nodeArray.length; iHops++) {
psOut.println("printNodeArray: full path item " + iHops + " = "
+ ((iFlag == 0) ? "[n] ":"[e] ") + nodeArray[iHops]);
iFlag = 1 - iFlag;
}
}
In Example 7-3:
A GraphOracleSem object is constructed and a few triples are added to the GraphOracleSem object. These triples describe several individuals and their relationships including likes, dislikes, knows, and differs.
A cost mapping is constructed to assign a numeric cost value to different links/predicates (of the RDF graph). In this case, 0.5, 1.5, and 5.5 are assigned to predicates likes, dislikes, and differs, respectively. This cost mapping is optional. If the mapping is absent, then all predicates will be assigned the same cost 1. When cost mapping is specified, this mapping does not need to be complete; for predicates not included in the cost mapping, a default value of 1 is assigned.
The output of Example 7-3 is as follows. In this output, the shortest paths are listed for the given start and end nodes. Note that the return value of sna.shortestPathAStar(ano, nodeX) is null because there is no path between these two nodes.
From nodeA to nodeC printNodeArray: full path starts printNodeArray: full path item 0 = [n] http://A ## "n" denotes Node printNodeArray: full path item 1 = [e] http://likes ## "e" denotes Edge (Link) printNodeArray: full path item 2 = [n] http://B printNodeArray: full path item 3 = [e] http://likes printNodeArray: full path item 4 = [n] http://C From nodeA to nodeD printNodeArray: full path starts printNodeArray: full path item 0 = [n] http://A printNodeArray: full path item 1 = [e] http://likes printNodeArray: full path item 2 = [n] http://B printNodeArray: full path item 3 = [e] http://likes printNodeArray: full path item 4 = [n] http://C printNodeArray: full path item 5 = [e] http://likes printNodeArray: full path item 6 = [n] http://D From nodeA to nodeF printNodeArray: full path starts printNodeArray: full path item 0 = [n] http://A printNodeArray: full path item 1 = [e] http://likes printNodeArray: full path item 2 = [n] http://B printNodeArray: full path item 3 = [e] http://dislikes printNodeArray: full path item 4 = [n] m1 printNodeArray: full path item 5 = [e] http://likes printNodeArray: full path item 6 = [n] http://F From ano to nodeC printNodeArray: full path starts printNodeArray: full path item 0 = [n] m1 printNodeArray: full path item 1 = [e] http://dislikes printNodeArray: full path item 2 = [n] http://B printNodeArray: full path item 3 = [e] http://likes printNodeArray: full path item 4 = [n] http://C From ano to nodeX Node Array is null
The underlying RDF graph view (SEMM_<model_name> or RDFM_<model_name>) cannot be used directly by NDM functions, and so SemNetworkAnalyst creates necessary tables that contain the nodes and links that are derived from a given RDF graph. These tables are not updated automatically when the RDF graph changes; rather, you can set the cleanup parameter in SemNetworkAnalyst.getInstance to true, to remove old node and link tables and to rebuild updated tables.
Example 7-4 implements the NDM' nearestNeighbors function on top of semantic data. This gets a NetworkAnalyst object from the SemNetworkAnalyst instance, gets the node ID, creates PointOnNet objects, and processes LogicalSubPath objects.
Example 7-4 Implementing NDM nearestNeighbors Function on Top of Semantic Data
%cat TestNearestNeighbor.java
import java.io.*;
import java.util.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import com.hp.hpl.jena.util.iterator.*;
import com.hp.hpl.jena.graph.*;
import com.hp.hpl.jena.update.*;
import com.hp.hpl.jena.sparql.core.DataSourceImpl;
import oracle.spatial.rdf.client.jena.*;
import oracle.spatial.rdf.client.jena.SemNetworkAnalyst;
import oracle.spatial.network.lod.LODGoalNode;
import oracle.spatial.network.lod.LODNetworkConstraint;
import oracle.spatial.network.lod.NetworkAnalyst;
import oracle.spatial.network.lod.PointOnNet;
import oracle.spatial.network.lod.LogicalSubPath;
/**
* This class implements a nearestNeighbors function on top of semantic data
* using public APIs provided in SemNetworkAnalyst and Oracle Spatial NDM
*/
public class TestNearestNeighbor
{
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
PrintStream psOut = System.out;
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
String szModelName = "test_nn";
// First construct a TBox and load a few axioms
ModelOracleSem model = ModelOracleSem.createOracleSemModel(oracle, szModelName);
String insertString =
" PREFIX my: <http://my.com/> " +
" INSERT DATA " +
" { my:A my:likes my:B . " +
" my:A my:likes my:C . " +
" my:A my:knows my:D . " +
" my:A my:dislikes my:X . " +
" my:A my:dislikes my:Y . " +
" my:C my:likes my:E . " +
" my:C my:likes my:F . " +
" my:C my:dislikes my:M . " +
" my:D my:likes my:G . " +
" my:D my:likes my:H . " +
" my:F my:likes my:M . " +
" } ";
UpdateAction.parseExecute(insertString, model);
GraphOracleSem g = model.getGraph();
g.commitTransaction();
g.setDOP(4);
HashMap<Node, Double> costMap = new HashMap<Node, Double>();
costMap.put(Node.createURI("http://my.com/likes"), Double.valueOf(1.0));
costMap.put(Node.createURI("http://my.com/dislikes"), Double.valueOf(4.0));
costMap.put(Node.createURI("http://my.com/knows"), Double.valueOf(2.0));
SemNetworkAnalyst sna = SemNetworkAnalyst.getInstance(
g, // source RDF graph
true, // directed graph
true, // cleanup old Node/Link tables
costMap
);
Node nodeStart = Node.createURI("http://my.com/A");
long origNodeID = sna.getNodeID(nodeStart);
long[] lIDs = {origNodeID};
// translate from the original ID
long nodeID = (sna.mapNodeIDs(lIDs))[0];
NetworkAnalyst networkAnalyst = sna.getEmbeddedNetworkAnalyst();
LogicalSubPath[] lsps = networkAnalyst.nearestNeighbors(
new PointOnNet(nodeID), // startPoint
6, // numberOfNeighbors
1, // searchLinkLevel
1, // targetLinkLevel
(LODNetworkConstraint) null, // constraint
(LODGoalNode) null // goalNodeFilter
);
if (lsps != null) {
for (int idx = 0; idx < lsps.length; idx++) {
LogicalSubPath lsp = lsps[idx];
Node[] nodePath = sna.processLogicalSubPath(lsp, nodeStart);
psOut.println("Path " + idx);
printNodeArray(nodePath, psOut);
}
}
g.close();
sna.close();
oracle.dispose();
}
public static void printNodeArray(Node[] nodeArray, PrintStream psOut)
{
if (nodeArray == null) {
psOut.println("Node Array is null");
return;
}
if (nodeArray.length == 0) {
psOut.println("Node Array is empty");
}
int iFlag = 0;
psOut.println("printNodeArray: full path starts");
for (int iHops = 0; iHops < nodeArray.length; iHops++) {
psOut.println("printNodeArray: full path item " + iHops + " = "
+ ((iFlag == 0) ? "[n] ":"[e] ") + nodeArray[iHops]);
iFlag = 1 - iFlag;
}
}
}
The output of Example 7-4 is as follows.
Path 0 printNodeArray: full path starts printNodeArray: full path item 0 = [n] http://my.com/A printNodeArray: full path item 1 = [e] http://my.com/likes printNodeArray: full path item 2 = [n] http://my.com/C Path 1 printNodeArray: full path starts printNodeArray: full path item 0 = [n] http://my.com/A printNodeArray: full path item 1 = [e] http://my.com/likes printNodeArray: full path item 2 = [n] http://my.com/B Path 2 printNodeArray: full path starts printNodeArray: full path item 0 = [n] http://my.com/A printNodeArray: full path item 1 = [e] http://my.com/knows printNodeArray: full path item 2 = [n] http://my.com/D Path 3 printNodeArray: full path starts printNodeArray: full path item 0 = [n] http://my.com/A printNodeArray: full path item 1 = [e] http://my.com/likes printNodeArray: full path item 2 = [n] http://my.com/C printNodeArray: full path item 3 = [e] http://my.com/likes printNodeArray: full path item 4 = [n] http://my.com/E Path 4 printNodeArray: full path starts printNodeArray: full path item 0 = [n] http://my.com/A printNodeArray: full path item 1 = [e] http://my.com/likes printNodeArray: full path item 2 = [n] http://my.com/C printNodeArray: full path item 3 = [e] http://my.com/likes printNodeArray: full path item 4 = [n] http://my.com/F Path 5 printNodeArray: full path starts printNodeArray: full path item 0 = [n] http://my.com/A printNodeArray: full path item 1 = [e] http://my.com/knows printNodeArray: full path item 2 = [n] http://my.com/D printNodeArray: full path item 3 = [e] http://my.com/likes printNodeArray: full path item 4 = [n] http://my.com/H
It is sometimes useful to see contextual information about a path in a graph, in addition to the path itself. The buildSurroundingSubGraph method in the SemNetworkAnalyst class can output a DOT file (graph description language file, extension .gv) into the specified Writer object. For each node in the path, up to ten direct neighbors are used to produce a surrounding subgraph for the path. Example 7-5 shows the usage, specifically the output from the analytical functions used in Example 7-3, "Performing Analytical functions on RDF Data".
Example 7-5 Generating a DOT File with Contextual Information
nodeArray = sna.shortestPathDijkstra(nodeA, nodeD);
printNodeArray(nodeArray, psOut);
FileWriter dotWriter = new FileWriter("Shortest_Path_A_to_D.gv");
sna.buildSurroundingSubGraph(nodeArray, dotWriter);
The generated output DOT file from Example 7-5 is straightforward, as shown in the following example:
% cat Shortest_Path_A_to_D.gv
digraph { rankdir = LR; charset="utf-8";
"Rhttp://A" [ label="http://A" shape=rectangle,color=red,style = filled, ];
"Rhttp://B" [ label="http://B" shape=rectangle,color=red,style = filled, ];
"Rhttp://A" -> "Rhttp://B" [ label="http://likes" color=red, style=bold, ];
"Rhttp://C" [ label="http://C" shape=rectangle,color=red,style = filled, ];
"Rhttp://A" -> "Rhttp://C" [ label="http://dislikes" ];
"Rhttp://D" [ label="http://D" shape=rectangle,color=red,style = filled, ];
"Rhttp://A" -> "Rhttp://D" [ label="http://differs" ];
"Rhttp://B" -> "Rhttp://C" [ label="http://likes" color=red, style=bold, ];
"Rm1" [ label="m1" shape=ellipse,color=blue, ];
"Rhttp://B" -> "Rm1" [ label="http://dislikes" ];
"Rm1" -> "Rhttp://B" [ label="http://dislikes" ];
"Rhttp://C" -> "Rhttp://D" [ label="http://likes" color=red, style=bold, ];
"Rhttp://E" [ label="http://E" shape=ellipse,color=blue, ];
"Rhttp://C" -> "Rhttp://E" [ label="http://knows" ];
"Rm1" -> "Rhttp://D" [ label="http://likes" ];
}
You can also use methods in the SemNetworkAnalyst and GraphOracleSem classes to produce more sophisticated visualization of the analytical function output.
You can convert the preceding DOT file into a variety of image formats. Figure 7-1 is an image representing the information in the preceding DOT file.
Figure 7-1 Visual Representation of Analytical Function Output
This section describes some of the Oracle Database Semantic Technologies features that are exposed by the Jena Adapter. For comprehensive documentation of the API calls that support the available features, see the Jena Adapter reference information (Javadoc). For additional information about the server-side features exposed by the Jena Adapter, see the relevant chapters in this manual.
Virtual models (explained in Section 1.3.8) are specified in the GraphOracleSem constructor, and they are handled transparently. If a virtual model exists for the model-rulebase combination, it is used in query answering; if such a virtual model does not exist, it is created in the database.
|
Note: Virtual model support through the Jena Adapter is available only with Oracle Database Release 11.2 or later. |
The following example reuses an existing virtual model.
String modelName = "EX";
String m1 = "EX_1";
ModelOracleSem defaultModel =
ModelOracleSem.createOracleSemModel(oracle, modelName);
// create these models in case they don't exist
ModelOracleSem model1 = ModelOracleSem.createOracleSemModel(oracle, m1);
String vmName = "VM_" + modelName;
//create a virtual model containing EX and EX_1
oracle.executeCall(
"begin sem_apis.create_virtual_model(?,sem_models('"+ m1 + "','"+ modelName+"'),null); end;",vmName);
String[] modelNames = {m1};
String[] rulebaseNames = {};
Attachment attachment = Attachment.createInstance(modelNames, rulebaseNames,
InferenceMaintenanceMode.NO_UPDATE, QueryOptions.ALLOW_QUERY_VALID_AND_DUP);
// vmName is passed to the constructor, so GraphOracleSem will use the virtual
// model named vmname (if the current user has read privileges on it)
GraphOracleSem graph = new GraphOracleSem(oracle, modelName, attachment, vmName);
graph.add(Triple.create(Node.createURI("urn:alice"),
Node.createURI("http://xmlns.com/foaf/0.1/mbox"),
Node.createURI("mailto:alice@example")));
ModelOracleSem model = new ModelOracleSem(graph);
String queryString =
" SELECT ?subject ?object WHERE { ?subject ?p ?object } ";
Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
try {
ResultSet results = qexec.execSelect() ;
for ( ; results.hasNext() ; ) {
QuerySolution soln = results.nextSolution() ;
psOut.println("soln " + soln);
}
}
finally {
qexec.close() ;
}
OracleUtils.dropSemanticModel(oracle, modelName);
OracleUtils.dropSemanticModel(oracle, m1);
oracle.dispose();
You can also use the GraphOracleSem constructor to create a virtual model, as in the following example:
GraphOracleSem graph = new GraphOracleSem(oracle, modelName, attachment, true);
In this example, the fourth parameter (true) specifies that a virtual model needs to be created for the specified modelName and attachment.
Oracle Database Connection Pooling is provided through the Jena Adapter OraclePool class. Once this class is initialized, it can return Oracle objects out of its pool of available connections. Oracle objects are essentially database connection wrappers. After dispose is called on the Oracle object, the connection is returned to the pool. More information about using OraclePool can be found in the API reference information (Javadoc).
The following example sets up an OraclePool object with five (5) initial connections.
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
// test with connection properties
java.util.Properties prop = new java.util.Properties();
prop.setProperty("MinLimit", "2"); // the cache size is 2 at least
prop.setProperty("MaxLimit", "10");
prop.setProperty("InitialLimit", "2"); // create 2 connections at startup
prop.setProperty("InactivityTimeout", "1800"); // seconds
prop.setProperty("AbandonedConnectionTimeout", "900"); // seconds
prop.setProperty("MaxStatementsLimit", "10");
prop.setProperty("PropertyCheckInterval", "60"); // seconds
System.out.println("Creating OraclePool");
OraclePool op = new OraclePool(szJdbcURL, szUser, szPasswd, prop,
"OracleSemConnPool");
System.out.println("Done creating OraclePool");
// grab an Oracle and do something with it
System.out.println("Getting an Oracle from OraclePool");
Oracle oracle = op.getOracle();
System.out.println("Done");
System.out.println("Is logical connection:" +
oracle.getConnection().isLogicalConnection());
GraphOracleSem g = new GraphOracleSem(oracle, szModelName);
g.add(Triple.create(Node.createURI("u:John"),
Node.createURI("u:parentOf"),
Node.createURI("u:Mary")));
g.close();
// return the Oracle back to the pool
oracle.dispose();
// grab another Oracle and do something else
System.out.println("Getting an Oracle from OraclePool");
oracle = op.getOracle();
System.out.println("Done");
System.out.println("Is logical connection:" +
oracle.getConnection().isLogicalConnection());
g = new GraphOracleSem(oracle, szModelName);
g.add(Triple.create(Node.createURI("u:John"),
Node.createURI("u:parentOf"),
Node.createURI("u:Jack")));
g.close();
OracleUtils.dropSemanticModel(oracle, szModelName);
// return the Oracle object back to the pool
oracle.dispose();
}
Several semantic PL/SQL subprograms are available through the Jena Adapter. Table 7-2 lists the subprograms and their corresponding Java class and methods.
Table 7-2 PL/SQL Subprograms and Corresponding Jena Adapter Java Class and Methods
| PL/SQL Subprogram | Corresponding Java Class and Methods |
|---|---|
|
|
OracleUtils.dropSemanticModel |
|
|
OracleUtils.mergeModels |
|
|
OracleUtils.swapNames |
|
|
OracleUtils.removeDuplicates |
|
|
OracleUtils.renameModels |
For information about these PL/SQL utility subprograms, see the reference information in Chapter 9. For information about the corresponding Java class and methods, see the Jena Adapter API Reference documentation (Javadoc).
You can add options to entailment calls by using the following methods in the Attachment class (in package oracle.spatial.rdf.client.jena):
public void setUseLocalInference(boolean useLocalInference) public boolean getUseLocalInference() public void setDefGraphForLocalInference(String defaultGraphName) public String getDefGraphForLocalInference() public String getInferenceOption() public void setInferenceOption(String inferenceOption)
For more information about these methods, see the Javadoc.
Example 7-6 enables parallel inference (with a degree of 4) and RAW format when creating an entailment. The example also uses the performInference method to create the entailment (comparable to using the SEM_APIS.CREATE_ENTAILMENT PL/SQL procedure).
Example 7-6 Specifying Inference Options
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import com.hp.hpl.jena.util.iterator.*;
import oracle.spatial.rdf.client.jena.*;
import com.hp.hpl.jena.graph.*;
import com.hp.hpl.jena.update.*;
import com.hp.hpl.jena.sparql.core.DataSourceImpl;
public class TestNewInference
{
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
PrintStream psOut = System.out;
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
String szTBoxName = "test_new_tbox";
{
// First construct a TBox and load a few axioms
ModelOracleSem modelTBox = ModelOracleSem.createOracleSemModel(oracle, szTBoxName);
String insertString =
" PREFIX my: <http://my.com/> " +
" PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> " +
" INSERT DATA " +
" { my:C1 rdfs:subClassOf my:C2 . " +
" my:C2 rdfs:subClassOf my:C3 . " +
" my:C3 rdfs:subClassOf my:C4 . " +
" } ";
UpdateAction.parseExecute(insertString, modelTBox);
modelTBox.close();
}
String szABoxName = "test_new_abox";
{
// Construct an ABox and load a few quads
ModelOracleSem modelABox = ModelOracleSem.createOracleSemModel(oracle, szABoxName);
DatasetGraphOracleSem dataset = DatasetGraphOracleSem.createFrom(modelABox.getGraph());
modelABox.close();
String insertString =
" PREFIX my: <http://my.com/> " +
" PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> " +
" INSERT DATA " +
" { GRAPH my:G1 { my:I1 rdf:type my:C1 . " +
" my:I2 rdf:type my:C2 . " +
" } " +
" }; " +
" INSERT DATA " +
" { GRAPH my:G2 { my:J1 rdf:type my:C3 . " +
" } " +
" } ";
UpdateAction.parseExecute(insertString, dataset);
dataset.close();
}
String[] attachedModels = new String[1];
attachedModels[0] = szTBoxName;
String[] attachedRBs = {"OWL2RL"};
Attachment attachment = Attachment.createInstance(
attachedModels, attachedRBs,
InferenceMaintenanceMode.NO_UPDATE,
QueryOptions.ALLOW_QUERY_INVALID);
// We are going to run named graph based local inference
attachment.setUseLocalInference(true);
// Set the default graph (TBox)
attachment.setDefGraphForLocalInference(szTBoxName);
// Set the inference option to use parallel inference
// with a degree of 4, and RAW format.
attachment.setInferenceOption("DOP=4,RAW8=T");
GraphOracleSem graph = new GraphOracleSem(
oracle,
szABoxName,
attachment
);
DatasetGraphOracleSem dsgos = DatasetGraphOracleSem.createFrom(graph);
graph.close();
// Invoke create_entailment PL/SQL API
dsgos.performInference();
psOut.println("TestNewInference: # of inferred graph " +
Long.toString(dsgos.getInferredGraphSize()));
String queryString =
" SELECT ?g ?s ?p ?o WHERE { GRAPH ?g {?s ?p ?o } } " ;
Query query = QueryFactory.create(queryString, Syntax.syntaxARQ);
QueryExecution qexec = QueryExecutionFactory.create(
query, DataSourceImpl.wrap(dsgos));
ResultSet results = qexec.execSelect();
ResultSetFormatter.out(psOut, results);
dsgos.close();
oracle.dispose();
}
}
The output of Example 7-6 is as follows.
TestNewInference: # of inferred graph 9 -------------------------------------------------------------------------------------------------------------------- | g | s | p | o | ==================================================================================================================== | <http://my.com/G1> | <http://my.com/I2> | <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> | <http://my.com/C3> | | <http://my.com/G1> | <http://my.com/I2> | <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> | <http://my.com/C2> | | <http://my.com/G1> | <http://my.com/I2> | <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> | <http://my.com/C4> | | <http://my.com/G1> | <http://my.com/I1> | <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> | <http://my.com/C3> | | <http://my.com/G1> | <http://my.com/I1> | <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> | <http://my.com/C1> | | <http://my.com/G1> | <http://my.com/I1> | <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> | <http://my.com/C2> | | <http://my.com/G1> | <http://my.com/I1> | <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> | <http://my.com/C4> | | <http://my.com/G2> | <http://my.com/J1> | <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> | <http://my.com/C3> | | <http://my.com/G2> | <http://my.com/J1> | <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> | <http://my.com/C4> | --------------------------------------------------------------------------------------------------------------------
For information about using OWL inferencing, see Section 2.2.
The support for the PelletInfGraph class within the Jena Adapter is deprecated. You should instead use the more optimized Oracle/Pellet integration through the PelletDb OWL 2 reasoner for Oracle Database 11g. (For information about PelletDb, see http://clarkparsia.com/pelletdb/.)
To load thousands to hundreds of thousands of RDF/OWL data files into an Oracle database, you can use the prepareBulk and completeBulk methods in the OracleBulkUpdateHandler Java class to simplify the task.
The addInBulk method in the OracleBulkUpdateHandler class can load triples of a graph or model into an Oracle database in bulk loading style. If the graph or model is a Jena in-memory graph or model, the operation is limited by the size of the physical memory. The prepareBulk method bypasses the Jena in-memory graph or model and takes a direct input stream to an RDF data file, parses the data, and load the triples into an underlying staging table. If the staging table and an accompanying table for storing long literals do not already exist, they are created automatically.
The prepareBulk method can be invoked multiple times to load multiple data files into the same underlying staging table. It can also be invoked concurrently, assuming the hardware system is balanced and there are multiple CPU cores and sufficient I/O capacity.
Once all the data files are processed by the prepareBulk method, you can invoke completeBulk to load all the data into the semantic network.
Example 7-7 shows how to load all data files in directory dir_1 into the underlying staging table. Long literals are supported and will be stored in a separate table. The data files can be compressed using GZIP to save storage space, and the prepareBulk method can detect automatically if a data file is compressed using GZIP or not.
Example 7-7 Loading Data into the Staging Table (prepareBulk)
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
GraphOracleSem graph = new GraphOracleSem(oracle, szModelName);
PrintStream psOut = System.out;
String dirname = "dir_1";
File fileDir = new File(dirname);
String[] szAllFiles = fileDir.list();
// loop through all the files in a directory
for (int idx = 0; idx < szAllFiles.length; idx++) {
String szIndFileName = dirname + File.separator + szAllFiles[idx];
psOut.println("process to [ID = " + idx + " ] file " + szIndFileName);
psOut.flush();
try {
InputStream is = new FileInputStream(szIndFileName);
graph.getBulkUpdateHandler().prepareBulk(
is, // input stream
"http://example.com", // base URI
"RDF/XML", // data file type: can be RDF/XML, N-TRIPLE, etc.
"SEMTS", // tablespace
null, // flags
null, // listener
null // staging table name.
);
is.close();
}
catch (Throwable t) {
psOut.println("Hit exception " + t.getMessage());
}
}
graph.close();
oracle.dispose();
The code in Example 7-7, starting from creating a new Oracle object and ending with disposing of the Oracle object, can be executed in parallel. Assume there is a quad-core CPU and enough I/O capacity on the database hardware system; you can divide up all the data files and save them into four separate directories: dir_1, dir_2, dir_3, and dir_4. Four Java threads of processes can be started to work on those directories separately and concurrently. (For more information, see Section 7.11.1, "Using prepareBulk in Parallel (Multithreaded) Mode".)
After all data files are processed, you can invoke, just once, the completeBulk method to load the data from staging table into the semantic network, as shown in Example 7-8. Triples with long literals will be loaded also.
Example 7-8 Loading Data from the Staging Table into the Semantic Network (completeBulk)
graph.getBulkUpdateHandler().completeBulk( null, // flags for invoking SEM_APIS.bulk_load_from_staging_table null // staging table name );
The prepareBulk method can also take a Jena model as an input data source, in which case triples in that Jena model are loaded into the underlying staging table. For more information, see the Javadoc.
In addition to loading triples from Jena models and data files, the prepareBulk method supports RDFa, as shown in Example 7-9. (RDFa is explained in http://www.w3.org/TR/xhtml-rdfa-primer/.)
Example 7-9 Using prepareBulk with RDFa
graph.getBulkUpdateHandler().prepareBulk( rdfaUrl, // url to a web page using RDFa "SEMTS", // tablespace null, // flags null, // listener null // staging table name );
To parse RDFa, the relevant java-rdfa libraries must be included in the classpath. No additional setup or API calls are required. (For information about java-rdfa, see http://www.rootdev.net/maven/projects/java-rdfa/ and the other topics there under Project Information.)
Note that if the rdfaUrl is located outside a firewall, you may need to set the following HTTP Proxy-related Java VM properties:
-Dhttp.proxyPort=... -Dhttp.proxyHost=...
The preceding examples in this section load triple data into a single graph. Loading quad data that may span across multiple named graphs (such as data in NQUADS format) requires the use of the DatasetGraphOracleSem class. The DatasetGraphOracleSem class does not use the BulkUpdateHandler API, but does provide a similar prepareBulk and completeBulk interface, as shown in Example 7-10.
Example 7-10 Loading Quads into a DatasetGraph
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
// Can only create DatasetGraphOracleSem from an existing GraphOracleSem
GraphOracleSem graph = new GraphOracleSem(oracle, szModelName);
DatasetGraphOracleSem dataset = DatasetGraphOracleSem.createFrom(graph);
// Don't need graph anymore, close it to free resources
graph.close();
try {
InputStream is = new FileInputStream(szFileName);
// load NQUADS file into a staging table. This file can be gzipp'ed.
dataset.prepareBulk(
is, // input stream
"http://my.base/", // base URI
"N-QUADS", // data file type; can be "TRIG"
"SEMTS", // tablespace
null, // flags
null, // listener
null, // staging table name
false // truncate staging table before load
);
// Load quads from staging table into the dataset
dataset.completeBulk(
null, // flags; can be "PARSE PARALLEL_CREATE_INDEX PARALLEL=4
// mbv_method=shadow" on a quad core machine
null // staging table name
);
}
catch (Throwable t) {
System.out.println("Hit exception " + t.getMessage());
}
finally {
dataset.close();
oracle.dispose();
}
Example 7-7, "Loading Data into the Staging Table (prepareBulk)" provided a way to load, sequentially, a set of files under a file system directory to an Oracle Database table (staging table). Example 7-11 loads, concurrently, a set of files to an Oracle table (staging table). The degree of parallelism is controlled by the input parameter iMaxThreads.
On a balanced hardware setup with 4 or more CP U cores, setting iMaxThreads to 8 (or 16) can improve significantly the speed of prepareBulk operation when there are many data files to be processed.
Example 7-11 Using prepareBulk with iMaxThreads
public void testPrepareInParallel(String jdbcUrl, String user,
String password, String modelName,
String lang,
String tbs,
String dirname,
int iMaxThreads,
PrintStream psOut)
throws SQLException, IOException, InterruptedException
{
File dir = new File(dirname);
File[] files = dir.listFiles();
// create a set of physical Oracle connections and graph objects
Oracle[] oracles = new Oracle[iMaxThreads];
GraphOracleSem[] graphs = new GraphOracleSem[iMaxThreads];
for (int idx = 0; idx < iMaxThreads; idx++) {
oracles[idx] = new Oracle(jdbcUrl, user, password);
graphs[idx] = new GraphOracleSem(oracles[idx], modelName);
}
PrepareWorker[] workers = new PrepareWorker[iMaxThreads];
Thread[] threads = new Thread[iMaxThreads];
for (int idx = 0; idx < iMaxThreads; idx++) {
workers[idx] = new PrepareWorker(
graphs[idx],
files,
idx,
iMaxThreads,
lang,
tbs,
psOut
);
threads[idx] = new Thread(workers[idx], workers[idx].getName());
psOut.println("testPrepareInParallel: PrepareWorker " + idx + " running");
threads[idx].start();
}
psOut.println("testPrepareInParallel: all threads started");
for (int idx = 0; idx < iMaxThreads; idx++) {
threads[idx].join();
}
for (int idx = 0; idx < iMaxThreads; idx++) {
graphs[idx].close();
oracles[idx].dispose();
}
}
static class PrepareWorker implements Runnable
{
GraphOracleSem graph = null;
int idx;
int threads;
File[] files = null;
String lang = null;
String tbs = null;
PrintStream psOut;
public void run()
{
long lStartTime = System.currentTimeMillis();
for (int idxFile = idx; idxFile < files.length; idxFile += threads) {
File file = files[idxFile];
try {
FileInputStream fis = new FileInputStream(file);
graph.getBulkUpdateHandler().prepareBulk(
fis,
"http://base.com/",
lang,
tbs,
null, // flags
new MyListener(psOut), // listener
null // table name
);
fis.close();
}
catch (Exception e) {
psOut.println("PrepareWorker: thread ["+getName()+"] error "+ e.getMessage());
}
psOut.println("PrepareWorker: thread ["+getName()+"] done to "
+ idxFile + ", file = " + file.toString()
+ " in (ms) " + (System.currentTimeMillis() - lStartTime));
}
}
public PrepareWorker(GraphOracleSem graph,
File[] files,
int idx,
int threads,
String lang,
String tbs,
PrintStream psOut)
{
this.graph = graph;
this.files = files;
this.psOut = psOut;
this.idx = idx;
this.threads = threads;
this.files = files;
this.lang = lang;
this.tbs = tbs ;
}
public String getName()
{
return "PrepareWorker" + idx;
}
}
static class MyListener implements StatusListener
{
PrintStream m_ps = null;
public MyListener(PrintStream ps) { m_ps = ps; }
long lLastBatch = 0;
public void statusChanged(long count)
{
if (count - lLastBatch >= 10000) {
m_ps.println("process to " + Long.toString(count));
lLastBatch = count;
}
}
public int illegalStmtEncountered(Node graphNode, Triple triple, long count)
{
m_ps.println("hit illegal statement with object " + triple.getObject().toString());
return 0; // skip it
}
}
You can skip illegal triples and quads when using prepareBulk. This feature is useful if the source RDF data may contain syntax errors. In Example 7-12, a customized implementation of the StatusListener interface (defined in package oracle.spatial.rdf.client.jena) is passed as a parameter to prepareBulk. In this example, the illegalStmtEncountered method prints the object field of the illegal triple, and returns 0 so that prepareBulk can skip that illegal triple and move on.
Example 7-12 Skipping Triples with Illegal Syntax
....
Oracle oracle = new Oracle(jdbcUrl, user, password);
GraphOracleSem graph = new GraphOracleSem(oracle, modelName);
PrintStream psOut = System.err;
graph.getBulkUpdateHandler().prepareBulk(
new FileInputStream(rdfDataFilename),
"http://base.com/", // base
lang, // data format, can be "N-TRIPLES" "RDF/XML" ...
tbs, // tablespace name
null, // flags
new MyListener(psOut), // call back to show progress and also process illegal triples/quads
null, // tableName, if null use default names
false // truncate existing staging tables
);
graph.close();
oracle.dispose();
....
// A customized StatusListener interface implementation
public class MyListener implements StatusListener
{
PrintStream m_ps = null;
public MyListener(PrintStream ps) { m_ps = ps; }
public void statusChanged(long count)
{
// m_ps.println("process to " + Long.toString(count));
}
public int illegalStmtEncountered(Node graphNode, Triple triple, long count)
{
m_ps.println("hit illegal statement with object " + triple.getObject().toString());
return 0; // skip it
}
}
Previously, variable names used in SPARQL queries were passed directly on to Oracle Database as a part of a SQL statement. If the variable names included a SQL or PL/SQL reserved keyword, the query failed to execute. For example, the following SPARQL query used to fail because the word date as a special meaning to the Oracle Database SQL processing engine.
select ?date { :event :happenedOn ?date }
Currently, this query does not fail, because a "smart scan" is performed and automatic replacement is done on certain reserved variable names (or variable names that are very long) before the query is sent to Oracle database for execution. The replacement is based on a list of reserved keywords that are stored in the following file embedded in sdordfclient.jar:
oracle/spatial/rdf/client/jena/oracle_sem_reserved_keywords.lst
This file contains over 100 entries, and you can edit the file to add entries if necessary.
The following are examples of SPARQL queries that use SQL or PL/SQL reserved keywords as variables, and that will succeed because of automatic variable renaming:
Query using SELECT as a variable name:
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
select ?SELECT ?z
where
{ ?SELECT foaf:name ?y.
optional {?SELECT foaf:knows ?z.}
}
Query using ARRAY and DATE as variable names:
PREFIX x: <http://example.com#>
construct {
?ARRAY x:date ?date .
}
where {
?ARRAY x:happenedOn ?date .
}
JavaScript Object Notation (JSON) format is supported for SPARQL query responses. JSON data format is simple, compact, and well suited for JavaScript programs.
For example, assume the following Java code snippet, which calls the ResultSetFormatter.outputAsJSON method:
Oracle oracle = new Oracle(jdbcUrl, user, password);
GraphOracleSem graph = new GraphOracleSem(oracle, modelName);
ModelOracleSem model = new ModelOracleSem(graph);
graph.add(new Triple(
Node.createURI("http://ds1"),
Node.createURI("http://dp1"),
Node.createURI("http://do1")
)
);
graph.add(new Triple(
Node.createURI("http://ds2"),
Node.createURI("http://dp2"),
Node.createURI("http://do2")
)
);
graph.commitTransaction();
Query q = QueryFactory.create("select ?s ?p ?o where {?s ?p ?o}",
Syntax.syntaxARQ);
QueryExecution qexec = QueryExecutionFactory.create(q, model);
ResultSet results = qexec.execSelect();
ResultSetFormatter.outputAsJSON(System.out, results);
The JSON output is as follows:
{
"head": {
"vars": [ "s" , "p" , "o" ]
} ,
"results": {
"bindings": [
{
"s": { "type": "uri" , "value": "http://ds1" } ,
"p": { "type": "uri" , "value": "http://dp1" } ,
"o": { "type": "uri" , "value": "http://do1" }
} ,
{
"s": { "type": "uri" , "value": "http://ds2" } ,
"p": { "type": "uri" , "value": "http://dp2" } ,
"o": { "type": "uri" , "value": "http://do2" }
}
]
}
}
The preceding example can be changed as follows to query a remote SPARQL endpoint instead of directly against an Oracle database. (If the remote SPARQL endpoint is outside a firewall, then the HTTP Proxy probably needs to be set.)
Query q = QueryFactory.create("select ?s ?p ?o where {?s ?p ?o}",
Syntax.syntaxARQ);
QueryExecution qe = QueryExecutionFactory.sparqlService(sparqlURL, q);
ResultSet results = qexec.execSelect();
ResultSetFormatter.outputAsJSON(System.out, results);
To extend the first example in this section to named graphs, the following code snippet adds two quads to the same Oracle model, executes a named graph-based SPARQL query, and serializes the query output into JSON format:
DatasetGraphOracleSem dsgos = DatasetGraphOracleSem.createFrom(graph);
graph.close();
dsgos.add(new Quad(Node.createURI("http://g1"),
Node.createURI("http://s1"),
Node.createURI("http://p1"),
Node.createURI("http://o1")
)
);
dsgos.add(new Quad(Node.createURI("http://g2"),
Node.createURI("http://s2"),
Node.createURI("http://p2"),
Node.createURI("http://o2")
)
);
Query q1 = QueryFactory.create(
"select ?g ?s ?p ?o where { GRAPH ?g {?s ?p ?o} }");
QueryExecution qexec1 = QueryExecutionFactory.create(q1,
DataSourceImpl.wrap(dsgos));
ResultSet results1 = qexec1.execSelect();
ResultSetFormatter.outputAsJSON(System.out, results1);
dsgos.close();
oracle.dispose();
The JSON output is as follows:
{
"head": {
"vars": [ "g" , "s" , "p" , "o" ]
} ,
"results": {
"bindings": [
{
"g": { "type": "uri" , "value": "http://g1" } ,
"s": { "type": "uri" , "value": "http://s1" } ,
"p": { "type": "uri" , "value": "http://p1" } ,
"o": { "type": "uri" , "value": "http://o1" }
} ,
{
"g": { "type": "uri" , "value": "http://g2" } ,
"s": { "type": "uri" , "value": "http://s2" } ,
"p": { "type": "uri" , "value": "http://p2" } ,
"o": { "type": "uri" , "value": "http://o2" }
}
]
}
}
You can also get a JSON response through HTTP against a Joseki-based SPARQL endpoint, as in the following example. Normally, when executing a SPARQL query against a SPARQL Web service endpoint, the Accept request-head field is set to be application/sparql-results+xml. For JSON output format, replace the Accept request-head field with application/sparql-results+json.
http://hostname:7001/joseki/oracle?query=<URL_ENCODED_SPARQL_QUERY>&output=json
This section contains various recommendations and other information related to SPARQL queries.
For better performance, use BOUND or !BOUND instead of EXISTS or NOT EXISTS.
You can use SPARQL 1.1 SELECT expressions without any significant performance overhead, even if the function is not currently supported within Oracle Database. Examples include the following:
-- Quyery using MD5 and SHA1 functions
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
PREFIX eg: <http://biometrics.example/ns#>
SELECT ?name (md5(?name) as ?name_in_md5) (sha1(?email) as ?sha1)
WHERE
{
?x foaf:name ?name ; eg:email ?email .
}
-- Quyery using CONCAT function
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
SELECT ( CONCAT(?G, " ", ?S) AS ?name )
WHERE
{
?P foaf:givenName ?G ; foaf:surname ?S
}
Syntax involving bnodes can be used freely in query patterns. For example, the following bnode-related syntax is supported at the parser level, so each is equivalent to its full triple-query-pattern-based version.
:x :q [ :p "v" ] . (1 ?x 3 4) :p "w" . (1 [:p :q] ( 2 ) ) .
When writing a SPARQL 1.1 federated query, you can set a limit on returned rows in the subquery inside the SERVICE clause. This can effectively constrain the amount of data to be transported between the local repository and the remote SPARQL endpoint.
For example, the following query specifies limit 100 in the subquery in the SERVICE clause:
PREFIX : <http://example.com/>
SELECT ?s ?o
WHERE
{
?s :name "CA"
SERVICE <http://REMOTE_SPARQL_ENDPOINT_HERE>
{
select ?s ?o
{?s :info ?o}
limit 100
}
}
The Jena OntModel class lets you create, modify, and analyze an ontology stored in a Jena model. However, the OntModel implementation is not optimized for semantic data stored in a database. This results in suboptimal performance when using OntModel with an Oracle model. Therefore, the class OracleGraphWrapperForOntModel has been created to alleviate this performance issue.
The OracleGraphWrapperForOntModel class implements the Jena Graph interface and represents a graph backed by an Oracle RDF/OWL model that is meant for use with the Jena OntModel API. The OracleGraphWrapperForOntModel class uses two semantic stores in a hybrid approach for persisting changes and responding to queries. Both semantic stores contain the same data, but one resides in memory while the other resides in the Oracle database.
When queried through OntModel, the OracleGraphWrapperForOntModel graph runs the queries against the in-memory store to improve performance. However, the OracleGraphWrapperForOntModel class persists changes made through OntModel, such as adding or removing classes, by applying changes to both stores.
Due to its hybrid approach, an OracleGraphWrapperForOntModel graph requires that sufficient memory be allocated to the JVM to store a copy of the ontology in memory. In internal experiments, it was found that an ontology with approximately 3 million triples requires 6 or more GB of physical memory.
Example 7-13 shows how to use the OntModel APIs with an existing ontology stored in an Oracle model.
Example 7-13 Using OntModel with Ontology Stored in Oracle Database
// Set up connection to Oracle semantic store and the Oracle model
// containing the ontology
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
GraphOracleSem oracleGraph = new GraphOracleSem(oracle, szModelName);
// Create a new hybrid graph using the oracle graph to persist
// changes. This method will copy all the data from the oracle graph
// into an in-memory graph, which may significantly increase JVM memory
// usage.
Graph hybridGraph = OracleGraphWrapperForOntModel.getInstance(oracleGraph);
// Build a model around the hybrid graph and wrap the model with Jena's
// OntModel
Model model = ModelFactory.createModelForGraph(hybridGraph);
OntModel ontModel = ModelFactory.createOntologyModel(ontModelSpec, model);
// Perform operations on the ontology
OntClass personClass = ontModel.createClass("<http://someuri/person>");
ontModel.createIndividual(personClass);
// Close resources (will also close oracleGraph)!
hybridGraph.close();
ontModel.close();
Note that any OntModel object created using OracleGraphWrapperForOntModel will not reflect changes made to the underlying Oracle model by another process, through a separate OntModel, or through a separate Oracle graph referencing the same underlying model. All changes to an ontology should go through a single OntModel object and its underlying OracleGraphWrapperForOntModel graph until the model or graph have been closed.
If the default in-memory semantic store used by OracleGraphWrapperForOntModel is not sufficient for an ontology and system, the class provides an interface for specifying a custom graph to use as the in-memory store. Example 7-14 shows how to create an OracleGraphWrapperForOntModel that uses a custom in-memory graph to answer queries from OntModel.
Example 7-14 Using a Custom In-Memory Graph
// Set up connection to Oracle semantic store and the Oracle model // containing the ontology Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd); GraphOracleSem oracleGraph = new GraphOracleSem(oracle, szModelName); // Create a custom in-memory graph to use instead of the default // Jena in-memory graph for quickly answering OntModel queries. // Note that this graph does not *need* to be in-memory, but in-memory // is preferred. GraphBase queryGraph = new CustomInMemoryGraphImpl(); // Create a new hybrid graph using the oracle graph to persist // changes and the custom in-memory graph to answer queries. // Also set the degree of parallelism to use when copying data from // the oracle graph to the querying graph. int degreeOfParallelism = 4; Graph hybridGraph = OracleGraphWrapperForOntModel.getInstance(oracleGraph, queryGraph, degreeOfParallelism); // Build a model and wrap the model with Jena's OntModel Model model = ModelFactory.createModelForGraph(hybridGraph); OntModel ontModel = ModelFactory.createOntologyModel(ontModelSpec, model); // Perform operations on the ontology // ... // Close resources (will close oracleGraph and queryGraph)! hybridGraph.close(); ontModel.close();
This section includes example queries using the Jena Adapter. Each example is self-contained: it typically creates a model, creates triples, performs a query that may involve inference, displays the result, and drops the model.
This section includes queries that do the following:
Count asserted triples and asserted plus inferred triples in an example "university" ontology, both by referencing the ontology by a URL and by bulk loading the ontology from a local file
Run several SPARQL queries using a "family" ontology, including features such as LIMIT, OFFSET, TIMEOUT, DOP (degree of parallelism), ASK, DESCRIBE, CONSTRUCT, GRAPH, ALLOW_DUP (duplicate triples with multiple models), SPARUL (inserting data)
Use the ARQ built-in function
Use a SELECT cast query
Instantiate Oracle Database using OracleConnection
Use Oracle Database connection pooling
To run a query, you must do the following:
Include the code in a Java source file. The examples used in this section are supplied in files in the examples directory of the Jena Adapter download.
Compile the Java source file. For example:
> javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test.java
|
Note: Thejavac and java commands must each be on a single command line. |
Run the compiled file. For example:
> java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
Example 7-15 specifies that John is the father of Mary, and it selects and displays the subject and object in each fatherOf relationship
Example 7-15 Query Family Relationships
import oracle.spatial.rdf.client.jena.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.graph.*;
import com.hp.hpl.jena.query.*;
public class Test {
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
Model model = ModelOracleSem.createOracleSemModel(
oracle, szModelName);
model.getGraph().add(Triple.create(
Node.createURI("http://example.com/John"),
Node.createURI("http://example.com/fatherOf"),
Node.createURI("http://example.com/Mary")));
Query query = QueryFactory.create(
"select ?f ?k WHERE {?f <http://example.com/fatherOf> ?k .}");
QueryExecution qexec = QueryExecutionFactory.create(query, model);
ResultSet results = qexec.execSelect();
ResultSetFormatter.out(System.out, results, query);
model.close();
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-15, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
---------------------------------------------------------
| f | k |
=========================================================
| <http://example.com/John> | <http://example.com/Mary> |
---------------------------------------------------------
Example 7-16 loads an OWL ontology and performs OWLPrime inference. Note that the OWL ontology is in RDF/XML format, and after it is loaded into Oracle it will be serialized out in N-TRIPLE form. The example also queries for the number of asserted and inferred triples.
The ontology in this example can be retrieved from several locations, including http://owl.cs.manchester.ac.uk/2008/iswc-tones/ontologies/univ-bench.owl, and it describes roles, resources, and relationships in a university environment.
Example 7-16 Load OWL Ontology and Perform OWLPrime inference
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import oracle.spatial.rdf.client.jena.*;
public class Test6 {
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
Model model = ModelOracleSem.createOracleSemModel(oracle, szModelName);
// load UNIV ontology
InputStream in = FileManager.get().open("./univ-bench.owl" );
model.read(in, null);
OutputStream os = new FileOutputStream("./univ-bench.nt");
model.write(os, "N-TRIPLE");
os.close();
String queryString =
" SELECT ?subject ?prop ?object WHERE { ?subject ?prop ?object } ";
Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
try {
int iTriplesCount = 0;
ResultSet results = qexec.execSelect() ;
for ( ; results.hasNext() ; ) {
QuerySolution soln = results.nextSolution() ;
iTriplesCount++;
}
System.out.println("Asserted triples count: " + iTriplesCount);
}
finally {
qexec.close() ;
}
Attachment attachment = Attachment.createInstance(
new String[] {}, "OWLPRIME",
InferenceMaintenanceMode.NO_UPDATE, QueryOptions.DEFAULT);
GraphOracleSem graph = new GraphOracleSem(oracle, szModelName, attachment);
graph.analyze();
graph.performInference();
query = QueryFactory.create(queryString) ;
qexec = QueryExecutionFactory.create(query,new ModelOracleSem(graph)) ;
try {
int iTriplesCount = 0;
ResultSet results = qexec.execSelect() ;
for ( ; results.hasNext() ; ) {
QuerySolution soln = results.nextSolution() ;
iTriplesCount++;
}
System.out.println("Asserted + Infered triples count: " + iTriplesCount);
}
finally {
qexec.close() ;
}
model.close();
OracleUtils.dropSemanticModel(oracle, szModelName);
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-16, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test6.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test6 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
Asserted triples count: 294
Asserted + Infered triples count: 341
Note that this output reflects an older version of the LUBM ontology. The latest version of the ontology has more triples.
Example 7-17 loads the same OWL ontology as in Section 7.15.2, but stored in a local file using Bulk Loader. Ontologies can also be loaded using an incremental and batch loader; these two methods are also listed in the example for completeness.
Example 7-17 Bulk Load OWL Ontology and Perform OWLPrime inference
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.graph.*;
import com.hp.hpl.jena.rdf.model.*;
import com.hp.hpl.jena.util.*;
import oracle.spatial.rdf.client.jena.*;
public class Test7
{
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
// in memory Jena Model
Model model = ModelFactory.createDefaultModel();
InputStream is = FileManager.get().open("./univ-bench.owl");
model.re ad(is, "", "RDF/XML");
is.close();
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
ModelOracleSem modelDest = ModelOracleSem.createOracleSemModel(oracle,
szModelName);
GraphOracleSem g = modelDest.getGraph();
g.dropApplicationTableIndex();
int method = 2; // try bulk loader
String tbs = "SYSAUX"; // can be customized
if (method == 0) {
System.out.println("start incremental");
modelDest.add(model);
System.out.println("end size " + modelDest.size());
}
else if (method == 1) {
System.out.println("start batch load");
g.getBulkUpdateHandler().addInBatch(
GraphUtil.findAll(model.getGraph()), tbs);
System.out.println("end size " + modelDest.size());
}
else {
System.out.println("start bulk load");
g.getBulkUpdateHandler().addInBulk(
GraphUtil.findAll(model.getGraph()), tbs);
System.out.println("end size " + modelDest.size());
}
g.rebuildApplicationTableIndex();
long lCount = g.getCount(Triple.ANY);
System.out.println("Asserted triples count: " + lCount);
model.close();
OracleUtils.dropSemanticModel(oracle, szModelName);
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-17, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test7.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test7 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
start bulk load
end size 293
Asserted triples count: 293
Note that this output reflects an older version of the LUBM ontology. The latest version of the ontology has more triples.
Example 7-18 shows a SPARQL OPTIONAL query. It inserts triples that postulate the following:
John is a parent of Mary.
John is a parent of Jack.
Mary is a parent of Jill.
It then finds parent-child relationships, optionally including any grandchild (gkid) relationships.
Example 7-18 SPARQL OPTIONAL Query
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import oracle.spatial.rdf.client.jena.*;
import com.hp.hpl.jena.graph.*;
public class Test8
{
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
ModelOracleSem model = ModelOracleSem.createOracleSemModel(oracle,
szModelName);
GraphOracleSem g = model.getGraph();
g.add(Triple.create(
Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Mary")));
g.add(Triple.create(
Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Jack")));
g.add(Triple.create(
Node.createURI("u:Mary"), Node.createURI("u:parentOf"),
Node.createURI("u:Jill")));
String queryString =
" SELECT ?s ?o ?gkid " +
" WHERE { ?s <u:parentOf> ?o . OPTIONAL {?o <u:parentOf> ?gkid }} ";
Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
try {
int iMatchCount = 0;
ResultSet results = qexec.execSelect() ;
ResultSetFormatter.out(System.out, results, query);
}
finally {
qexec.close() ;
}
model.close();
OracleUtils.dropSemanticModel(oracle, szModelName);
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-18, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test8.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test8 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
----------------------------------
| s | o | gkid |
==================================
| <u:John> | <u:Mary> | <u:Jill> |
| <u:Mary> | <u:Jill> | |
| <u:John> | <u:Jack> | |
----------------------------------
Example 7-19 shows a SPARQL query with LIMIT and OFFSET. It inserts triples that postulate the following:
John is a parent of Mary.
John is a parent of Jack.
Mary is a parent of Jill.
It then finds one parent-child relationship (LIMIT 1), skipping the first two parent-child relationships encountered (OFFSET 2), and optionally includes any grandchild (gkid) relationships for the one found.
Example 7-19 SPARQL Query with LIMIT and OFFSET
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import oracle.spatial.rdf.client.jena.*;
import com.hp.hpl.jena.graph.*;
public class Test9
{
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
ModelOracleSem model = ModelOracleSem.createOracleSemModel(oracle,
szModelName);
GraphOracleSem g = model.getGraph();
g.add(Triple.create(Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Mary")));
g.add(Triple.create(Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Jack")));
g.add(Triple.create(Node.createURI("u:Mary"), Node.createURI("u:parentOf"),
Node.createURI("u:Jill")));
String queryString =
" SELECT ?s ?o ?gkid " +
" WHERE { ?s <u:parentOf> ?o . OPTIONAL {?o <u:parentOf> ?gkid }} " +
" LIMIT 1 OFFSET 2";
Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
int iMatchCount = 0;
ResultSet results = qexec.execSelect() ;
ResultSetFormatter.out(System.out, results, query);
qexec.close() ;
model.close();
OracleUtils.dropSemanticModel(oracle, szModelName);
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-19, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test9.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test9 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
------------------------------
| s | o | gkid |
==============================
| <u:John> | <u:Jack> | |
------------------------------
Example 7-20 shows the SPARQL query from Section 7.15.5 with additional features, including a timeout setting (TIMEOUT=1, in seconds) and parallel execution setting (DOP=4).
Example 7-20 SPARQL Query with TIMEOUT and DOP
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import oracle.spatial.rdf.client.jena.*;
import com.hp.hpl.jena.graph.*;
public class Test10 {
public static void main(String[] args) throws Exception {
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
ModelOracleSem model = ModelOracleSem.createOracleSemModel(oracle, szModelName);
GraphOracleSem g = model.getGraph();
g.add(Triple.create(Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Mary")));
g.add(Triple.create(Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Jack")));
g.add(Triple.create(Node.createURI("u:Mary"), Node.createURI("u:parentOf"),
Node.createURI("u:Jill")));
String queryString =
" PREFIX ORACLE_SEM_FS_NS: <http://oracle.com/semtech#dop=4,timeout=1> "
+ " SELECT ?s ?o ?gkid WHERE { ?s <u:parentOf> ?o . "
+ " OPTIONAL {?o <u:parentOf> ?gkid }} "
+ " LIMIT 1 OFFSET 2";
Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
int iMatchCount = 0;
ResultSet results = qexec.execSelect() ;
ResultSetFormatter.out(System.out, results, query);
qexec.close() ;
model.close();
OracleUtils.dropSemanticModel(oracle, szModelName);
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-20, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test10.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test10 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
------------------------------
| s | o | gkid |
==============================
| <u:Mary> | <u:Jill> | |
------------------------------
Example 7-21 shows a query involving named graphs. It involves a default graph that has information about named graph URIs and their publishers. The query finds graph names, their publishers, and within each named graph finds the mailbox value using the foaf:mbox predicate.
Example 7-21 Named Graph Based Query
import java.io.*;
import com.hp.hpl.jena.graph.*;
import com.hp.hpl.jena.sparql.core.*;
import com.hp.hpl.jena.query.*;
import oracle.spatial.rdf.client.jena.*;
public class Test11
{
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
GraphOracleSem graph = new GraphOracleSem(oracle, szModelName);
DatasetGraphOracleSem dataset = DatasetGraphOracleSem.createFrom(graph);
// don't need the GraphOracleSem anymore, release resources
graph.close();
// add data to the default graph
dataset.add(new Quad(
Quad.defaultGraphIRI, // specifies default graph
Node.createURI("http://example.org/bob"),
Node.createURI("http://purl.org/dc/elements/1.1/publisher"),
Node.createLiteral("Bob Hacker")));
dataset.add(new Quad(
Quad.defaultGraphIRI, // specifies default graph
Node.createURI("http://example.org/alice"),
Node.createURI("http://purl.org/dc/elements/1.1/publisher"),
Node.createLiteral("alice Hacker")));
// add data to the bob named graph
dataset.add(new Quad(
Node.createURI("http://example.org/bob"), // graph name
Node.createURI("urn:bob"),
Node.createURI("http://xmlns.com/foaf/0.1/name"),
Node.createLiteral("Bob")));
dataset.add(new Quad(
Node.createURI("http://example.org/bob"), // graph name
Node.createURI("urn:bob"),
Node.createURI("http://xmlns.com/foaf/0.1/mbox"),
Node.createURI("mailto:bob@example")));
// add data to the alice named graph
dataset.add(new Quad(
Node.createURI("http://example.org/alice"), // graph name
Node.createURI("urn:alice"),
Node.createURI("http://xmlns.com/foaf/0.1/name"),
Node.createLiteral("Alice")));
dataset.add(new Quad(
Node.createURI("http://example.org/alice"), // graph name
Node.createURI("urn:alice"),
Node.createURI("http://xmlns.com/foaf/0.1/mbox"),
Node.createURI("mailto:alice@example")));
DataSource ds = DatasetFactory.create(dataset);
String queryString =
" PREFIX foaf: <http://xmlns.com/foaf/0.1/> "
+ " PREFIX dc: <http://purl.org/dc/elements/1.1/> "
+ " SELECT ?who ?graph ?mbox "
+ " FROM NAMED <http://example.org/alice> "
+ " FROM NAMED <http://example.org/bob> "
+ " WHERE "
+ " { "
+ " ?graph dc:publisher ?who . "
+ " GRAPH ?graph { ?x foaf:mbox ?mbox } "
+ " } ";
Query query = QueryFactory.create(queryString);
QueryExecution qexec = QueryExecutionFactory.create(query, ds);
ResultSet results = qexec.execSelect();
ResultSetFormatter.out(System.out, results, query);
qexec.close();
dataset.close();
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-21, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test11.java java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test11 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
Example 7-22 shows a SPARQL ASK query. It inserts a triple that postulates that John is a parent of Mary. It then finds whether John is a parent of Mary.
Example 7-22 SPARQL ASK Query
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import oracle.spatial.rdf.client.jena.*;
import com.hp.hpl.jena.graph.*;
public class Test12
{
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
ModelOracleSem model = ModelOracleSem.createOracleSemModel(oracle,
szModelName);
GraphOracleSem g = model.getGraph();
g.add(Triple.create(Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Mary")));
String queryString = " ASK { <u:John> <u:parentOf> <u:Mary> } ";
Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
boolean b = qexec.execAsk();
System.out.println("ask result = " + ((b)?"TRUE":"FALSE"));
qexec.close() ;
model.close();
OracleUtils.dropSemanticModel(oracle, szModelName);
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-22, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test12.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test12 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
ask result = TRUE
Example 7-23 shows a SPARQL DESCRIBE query. It inserts triples that postulate the following:
John is a parent of Mary.
John is a parent of Jack.
Amy is a parent of Jack.
It then finds all relationships that involve any parents of Jack.
Example 7-23 SPARQL DESCRIBE Query
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import oracle.spatial.rdf.client.jena.*;
import com.hp.hpl.jena.graph.*;
public class Test13
{
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
ModelOracleSem model = ModelOracleSem.createOracleSemModel(oracle, szModelName);
GraphOracleSem g = model.getGraph();
g.add(Triple.create(Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Mary")));
g.add(Triple.create(Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Jack")));
g.add(Triple.create(Node.createURI("u:Amy"), Node.createURI("u:parentOf"),
Node.createURI("u:Jack")));
String queryString = " DESCRIBE ?x WHERE {?x <u:parentOf> <u:Jack>}";
Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
Model m = qexec.execDescribe();
System.out.println("describe result = " + m.toString());
qexec.close() ;
model.close();
OracleUtils.dropSemanticModel(oracle, szModelName);
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-23, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test13.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test13 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
describe result = <ModelCom {u:Amy @u:parentOf u:Jack; u:John @u:parentOf u:Jack; u:John @u:parentOf u:Mary} | >
Example 7-24 shows a SPARQL CONSTRUCT query. It inserts triples that postulate the following:
John is a parent of Mary.
John is a parent of Jack.
Amy is a parent of Jack.
Each parent loves all of his or her children.
It then constructs an RDF graph with information about who loves whom.
Example 7-24 SPARQL CONSTRUCT Query
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import oracle.spatial.rdf.client.jena.*;
import com.hp.hpl.jena.graph.*;
public class Test14
{
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
ModelOracleSem model = ModelOracleSem.createOracleSemModel(oracle, szModelName);
GraphOracleSem g = model.getGraph();
g.add(Triple.create(Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Mary")));
g.add(Triple.create(Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Jack")));
g.add(Triple.create(Node.createURI("u:Amy"), Node.createURI("u:parentOf"),
Node.createURI("u:Jack")));
String queryString = " CONSTRUCT { ?s <u:loves> ?o } WHERE {?s <u:parentOf> ?o}";
Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
Model m = qexec.execConstruct();
System.out.println("Construct result = " + m.toString());
qexec.close() ;
model.close();
OracleUtils.dropSemanticModel(oracle, szModelName);
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-24, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test14.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test14 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
Construct result = <ModelCom {u:Amy @u:loves u:Jack; u:John @u:loves u:Jack; u:John @u:loves u:Mary} | >
Example 7-25 queries multiple models and uses the "allow duplicates" option. It inserts triples that postulate the following:
John is a parent of Jack (in Model 1).
Mary is a parent of Jack (in Model 2).
Each parent loves all of his or her children.
It then finds out who loves whom. It searches both models and allows for the possibility of duplicate triples in the models (although there are no duplicates in this example).
Example 7-25 Query Multiple Models and Specify "Allow Duplicates"
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import oracle.spatial.rdf.client.jena.*;
import com.hp.hpl.jena.graph.*;
public class Test15
{
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName1 = args[3];
String szModelName2 = args[4];
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
ModelOracleSem model1 = ModelOracleSem.createOracleSemModel(oracle, szModelName1);
model1.getGraph().add(Triple.create(Node.createURI("u:John"),
Node.createURI("u:parentOf"), Node.createURI("u:Jack")));
model1.close();
ModelOracleSem model2 = ModelOracleSem.createOracleSemModel(oracle, szModelName2);
model2.getGraph().add(Triple.create(Node.createURI("u:Mary"),
Node.createURI("u:parentOf"), Node.createURI("u:Jack")));
model2.close();
String[] modelNamesList = {szModelName2};
String[] rulebasesList = {};
Attachment attachment = Attachment.createInstance(modelNamesList, rulebasesList,
InferenceMaintenanceMode.NO_UPDATE,
QueryOptions.ALLOW_QUERY_VALID_AND_DUP);
GraphOracleSem graph = new GraphOracleSem(oracle, szModelName1, attachment);
ModelOracleSem model = new ModelOracleSem(graph);
String queryString = " CONSTRUCT { ?s <u:loves> ?o } WHERE {?s <u:parentOf> ?o}";
Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
Model m = qexec.execConstruct();
System.out.println("Construct result = " + m.toString());
qexec.close() ;
model.close();
OracleUtils.dropSemanticModel(oracle, szModelName1);
OracleUtils.dropSemanticModel(oracle, szModelName2);
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-25, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test15.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test15 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1 M2
Construct result = <ModelCom {u:Mary @u:loves u:Jack; u:John @u:loves u:Jack} | >
Example 7-26 inserts two triples into a model.
Example 7-26 SPARQL Update
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import com.hp.hpl.jena.util.iterator.*;
import oracle.spatial.rdf.client.jena.*;
import com.hp.hpl.jena.graph.*;
import com.hp.hpl.jena.update.*;
public class Test16
{
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
ModelOracleSem model = ModelOracleSem.createOracleSemModel(oracle, szModelName);
GraphOracleSem g = model.getGraph();
String insertString =
" PREFIX dc: <http://purl.org/dc/elements/1.1/> " +
" INSERT DATA " +
" { <http://example/book3> dc:title \"A new book\" ; " +
" dc:creator \"A.N.Other\" . " +
" } ";
UpdateAction.parseExecute(insertString, model);
ExtendedIterator ei = GraphUtil.findAll(g);
while (ei.hasNext()) {
System.out.println("Triple " + ei.next().toString());
}
model.close();
OracleUtils.dropSemanticModel(oracle, szModelName);
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-26, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test16.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test16 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
Triple http://example/book3 @dc:title "A new book"
Triple http://example/book3 @dc:creator "A.N.Other"
Example 7-27 inserts data about two books, and it displays the book titles in all uppercase characters and the length of each title string.
Example 7-27 SPARQL Query with ARQ Built-In Functions
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import com.hp.hpl.jena.util.iterator.*;
import oracle.spatial.rdf.client.jena.*;
import com.hp.hpl.jena.graph.*;
import com.hp.hpl.jena.update.*;
public class Test17 {
public static void main(String[] args) throws Exception {
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
ModelOracleSem model = ModelOracleSem.createOracleSemModel(oracle, szModelName);
GraphOracleSem g = model.getGraph();
String insertString =
" PREFIX dc: <http:// purl.org/dc/elements/1.1/> " +
" INSERT DATA " +
" { <http://example/book3> dc:title \"A new book\" ; " +
" dc:creator \"A.N.Other\" . " +
" <http://example/book4> dc:title \"Semantic Web Rocks\" ; " +
" dc:creator \"TB\" . " +
" } ";
UpdateAction.parseExecute(insertString, model);
String queryString = "PREFIX dc: <http://purl.org/dc/elements/1.1/> " +
" PREFIX fn: <http://www.w3.org/2005/xpath-functions#> " +
" SELECT ?subject (fn:upper-case(?object) as ?object1) " +
" (fn:string-length(?object) as ?strlen) " +
" WHERE { ?subject dc:title ?object } "
;
Query query = QueryFactory.create(queryString, Syntax.syntaxARQ);
QueryExecution qexec = QueryExecutionFactory.create(query, model);
ResultSet results = qexec.execSelect();
ResultSetFormatter.out(System.out, results, query);
model.close();
OracleUtils.dropSemanticModel(oracle, szModelName);
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-27, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test17.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test17 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
----------------------------------------------------------
| subject | object1 | strlen |
==========================================================
| <http://example/book3> | "A NEW BOOK" | 10 |
| <http://example/book4> | "SEMANTIC WEB ROCKS" | 18 |
----------------------------------------------------------
Example 7-28 "converts" two Fahrenheit temperatures (18.1 and 32.0) to Celsius temperatures.
Example 7-28 SELECT Cast Query
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import com.hp.hpl.jena.util.iterator.*;
import oracle.spatial.rdf.client.jena.*;
import com.hp.hpl.jena.graph.*;
import com.hp.hpl.jena.update.*;
public class Test18 {
public static void main(String[] args) throws Exception {
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
Oracle oracle = new Oracle(szJdbcURL, szUser, szPasswd);
ModelOracleSem model = ModelOracleSem.createOracleSemModel(oracle,
szModelName);
GraphOracleSem g = model.getGraph();
String insertString =
" PREFIX xsd: <http://www.w3.org/2001/XMLSchema#> " +
" INSERT DATA " +
" { <u:Object1> <u:temp> \"18.1\"^^xsd:float ; " +
" <u:name> \"Foo... \" . " +
" <u:Object2> <u:temp> \"32.0\"^^xsd:float ; " +
" <u:name> \"Bar... \" . " +
" } ";
UpdateAction.parseExecute(insertString, model);
String queryString =
" PREFIX fn: <http://www.w3.org/2005/xpath-functions#> " +
" SELECT ?subject ((?temp - 32.0)*5/9 as ?celsius_temp) " +
"WHERE { ?subject <u:temp> ?temp } "
;
Query query = QueryFactory.create(queryString, Syntax.syntaxARQ);
QueryExecution qexec = QueryExecutionFactory.create(query, model);
ResultSet results = qexec.execSelect();
ResultSetFormatter.out(System.out, results, query);
model.close();
OracleUtils.dropSemanticModel(oracle, szModelName);
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-28, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test18.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test18 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
------------------------------------------------------------------------
| subject | celsius_temp |
========================================================================
| <u:Object1> | "-7.7222223"^^<http://www.w3.org/2001/XMLSchema#float> |
| <u:Object2> | "0.0"^^<http://www.w3.org/2001/XMLSchema#float> |
------------------------------------------------------------------------
Example 7-29 shows a different way to instantiate an Oracle object using a given OracleConnection object. (In a J2EE Web application, users can normally get an OracleConnection object from a J2EE data source.)
Example 7-29 Instantiate Oracle Database Using OracleConnection
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import com.hp.hpl.jena.util.iterator.*;
import com.hp.hpl.jena.graph.*;
import com.hp.hpl.jena.update.*;
import oracle.spatial.rdf.client.jena.*;
import oracle.jdbc.pool.*;
import oracle.jdbc.*;
public class Test19 {
public static void main(String[] args) throws Exception {
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
OracleDataSource ds = new OracleDataSource();
ds.setURL(szJdbcURL);
ds.setUser(szUser);
ds.setPassword(szPasswd);
OracleConnection conn = (OracleConnection) ds.getConnection();
Oracle oracle = new Oracle(conn);
ModelOracleSem model = ModelOracleSem.createOracleSemModel(oracle,
szModelName);
GraphOracleSem g = model.getGraph();
g.add(Triple.create(Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Mary")));
g.add(Triple.create(Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Jack")));
g.add(Triple.create(Node.createURI("u:Mary"), Node.createURI("u:parentOf"),
Node.createURI("u:Jill")));
String queryString =
" SELECT ?s ?o WHERE { ?s <u:parentOf> ?o .} ";
Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
ResultSet results = qexec.execSelect() ;
ResultSetFormatter.out(System.out, results, query);
qexec.close() ;
model.close();
OracleUtils.dropSemanticModel(oracle, szModelName);
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-29, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test19.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test19 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
-----------------------
| s | o |
=======================
| <u:John> | <u:Mary> |
| <u:John> | <u:Jack> |
| <u:Mary> | <u:Jill> |
-----------------------
Example 7-30 uses Oracle Database connection pooling.
Example 7-30 Oracle Database Connection Pooling
import java.io.*;
import com.hp.hpl.jena.query.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.util.FileManager;
import com.hp.hpl.jena.util.iterator.*;
import com.hp.hpl.jena.graph.*;
import com.hp.hpl.jena.update.*;
import oracle.spatial.rdf.client.jena.*;
import oracle.jdbc.pool.*;
import oracle.jdbc.*;
public class Test20
{
public static void main(String[] args) throws Exception
{
String szJdbcURL = args[0];
String szUser = args[1];
String szPasswd = args[2];
String szModelName = args[3];
// test with connection properties (taken from some example)
java.util.Properties prop = new java.util.Properties();
prop.setProperty("MinLimit", "2"); // the cache size is 2 at least
prop.setProperty("MaxLimit", "10");
prop.setProperty("InitialLimit", "2"); // create 2 connections at startup
prop.setProperty("InactivityTimeout", "1800"); // seconds
prop.setProperty("AbandonedConnectionTimeout", "900"); // seconds
prop.setProperty("MaxStatementsLimit", "10");
prop.setProperty("PropertyCheckInterval", "60"); // seconds
System.out.println("Creating OraclePool");
OraclePool op = new OraclePool(szJdbcURL, szUser, szPasswd, prop,
"OracleSemConnPool");
System.out.println("Done creating OraclePool");
// grab an Oracle and do something with it
System.out.println("Getting an Oracle from OraclePool");
Oracle oracle = op.getOracle();
System.out.println("Done");
System.out.println("Is logical connection:" +
oracle.getConnection().isLogicalConnection());
GraphOracleSem g = new GraphOracleSem(oracle, szModelName);
g.add(Triple.create(Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Mary")));
g.close();
// return the Oracle back to the pool
oracle.dispose();
// grab another Oracle and do something else
System.out.println("Getting an Oracle from OraclePool");
oracle = op.getOracle();
System.out.println("Done");
System.out.println("Is logical connection:" +
oracle.getConnection().isLogicalConnection());
g = new GraphOracleSem(oracle, szModelName);
g.add(Triple.create(Node.createURI("u:John"), Node.createURI("u:parentOf"),
Node.createURI("u:Jack")));
g.close();
OracleUtils.dropSemanticModel(oracle, szModelName);
// return the Oracle back to the pool
oracle.dispose();
}
}
The following are the commands to compile and run Example 7-30, as well as the expected output of the java command.
javac -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:/slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar Test20.java
java -classpath ./:./jena-2.6.4.jar:./sdordfclient.jar:./ojdbc6.jar:./slf4j-api-1.5.8.jar:./slf4j-log4j12-1.5.8.jar:./arq-2.8.8.jar:./xercesImpl-2.7.1.jar:./iri-0.8.jar:./icu4j-3.4.4.jar:./log4j-1.2.14.jar Test20 jdbc:oracle:thin:@localhost:1521:orcl scott <password-for-scott> M1
Creating OraclePool
Done creating OraclePool
Getting an Oracle from OraclePool
Done
Is logical connection:true
Getting an Oracle from OraclePool
Done
Is logical connection:true
SPARQL Gateway is a J2EE web application that is included with the Jena Adapter for Oracle Database. It is designed to make semantic data (RDF/OWL/SKOS) easily available to applications that operate on relational and XML data, including Oracle Business Intelligence Enterprise Edition (OBIEE) 11g.
This section includes the following major topics:
Section 7.16.1, "SPARQL Gateway Features and Benefits Overview"
Section 7.16.6, "Using the SPARQL Gateway Graphical Web Interface"
Section 7.16.7, "Using SPARQL Gateway as an XML Data Source to OBIEE"
SPQRQL Gateway handles several challenges in exposing semantic data to a non-semantic application:
RDF syntax, SPARQL query syntax and SPARQL protocol must be understood.
The SPARQL query response syntax must be understood.
A transformation must convert a SPARQL query response to something that the application can consume.
To address these challenges, SPARQL Gateway manages SPARQL queries and XSLT operations, executes SPARQL queries against any arbitrary standard-compliant SPARQL endpoints, and performs necessary XSL transformations before passing the response back to applications. Applications can then consume semantic data as if it is coming from an existing data source.
Different triple stores or quad stores often have different capabilities. For example, the SPARQL endpoint supported by Oracle Database, with the Jena Adapter and Joseki, allows parallel execution, query timeout, dynamic sampling, result cache, and other features, in addition to the core function of parsing and answering a given standard-compliant SPARQL query. However, these features may not be available from another given semantic data store.
With the Oracle Semantic Technologies SPARQL Gateway, you get certain highly desirable capabilities, such as the ability to set a timeout on a long running query and the ability to get partial results from a complex query in a given amount of time. Waiting indefinitely for a query to finish is a challenge for end users, as is an application with a response time constraint. SPARQL Gateway provides both timeout and best effort query functions on top of a SPARQL endpoint. This effectively removes some uncertainty from consuming semantic data through SPARQL query executions. (See Section 7.16.3.2, "Specifying a Timeout Value" and Section 7.16.3.3, "Specifying Best Effort Query Execution".)
To install and configure SPARQL Gateway, follow these major steps, which are explained in subsections that follow:
If you have not already done so, download the Jena Adapter (jena_adaptor_for_release11.2.0.3.zip) from the Oracle Database Semantic Technologies page and unzip it into a temporary directory, as explained in Section 7.1.
Note that the SPARQL Gateway Java class implementations are embedded in sdordfclient.jar (see Section 7.16.5, "Using the SPARQL Gateway Java API").
Deploy SPARQL Gateway in Oracle WebLogic Server, as follows:
Create a temporary directory, for example, /tmp/sg.
From the directory into which you unzipped the SPARQL Gateway file that you downloaded, copy the sparqlgateway directory and everything under it (including subdirectories) into the temporary directory you created in step 1. For example:
cd /tmp cp -rf sparqlgateway/* /tmp/sg
(This sample directory structure is assumed in some later steps.)
If you do not already have the ARQ 2.8.8 package, download it from http://sourceforge.net/projects/jena/files/ARQ/ARQ-2.8.8/arq-2.8.8.zip/download.
Copy the following libraries from the ARQ 2.8.8 package to /tmp/sg/WEB-INF/lib:
arq-2.8.8.jar icu4j-3.4.4.jar iri-0.8.jar jena-2.6.4.jar junit-4.5.jar log4j-1.2.14.jar lucene-core-2.3.1.jar slf4j-api-1.5.8.jar slf4j-log4j12-1.5.8.jar stax-api-1.0.1.jar wstx-asl-3.2.9.jar xercesImpl-2.7.1.jar
Copy the following libraries to /tmp/sg/WEB-INF/lib:
ojdbc6.jar (from $ORACLE_HOME/jdbc/lib/ojdbc6.jar ) sdordfclient.jar (from jena_adaptor_for_release11.2.0.3.zip under the jar/ directory) sdordf.jar from $ORACLE_HOME/md/jlib/sdordf.jar )
Customize the /tmp/sg/WEB-INF/web.xml file as needed. Be sure to specify appropriate values for the sparql_gateway_repository_filedir and sparql_gateway_repository_url parameters.
Add XSLT files or SPARQL query files to the /tmp/sg directory, if necessary.
The following files are provided by Oracle in that directory: default.xslt, noop.xslt, and qb1.sparql. The default.xslt file is intended mainly for transforming SPARQL query responses (XML) to a format acceptable to Oracle Business Intelligence Enterprise Edition (OBIEE).
(These files are described in Section 7.16.3.1, "Storing SPARQL Queries and XSL Transformations"; using SPARQL Gateway with OBIEE is explained in Section 7.16.7, "Using SPARQL Gateway as an XML Data Source to OBIEE".)
Go to the autodeploy directory of WebLogic Server, create directory sparqlgateway.war, and copy files, as follows. (For information about auto-deploying applications in development domains, see: http://download.oracle.com/docs/cd/E11035_01/wls100/deployment/autodeploy.html)
cd <domain_name>/autodeploy mkdir sparqlgateway.war cp -rf /tmp/sg/* <domain_name>/autodeploy/sparqgateway.war
In this example, <domain_name> is the name of a WebLogic Server domain.
If you want to build a .war file from the /tmp/sg directory, enter the following commands:
cd /tmp/sg jar cvf /tmp/sparqlgateway.war *
Start or restart WebLogic Server.
Verify your deployment by using your Web browser to connect to a URL in the following format (assume that the Web application is deployed at port 7001):
http://<hostname>:7001/sparqlgateway
If your SPARQL Gateway is behind a firewall and you want SPARQL Gateway to communicate with SPARQL endpoints on the Internet as well as those inside the firewall, you probably need to use the following JVM settings:
-Dhttp.proxyHost=<your_proxy_host> -Dhttp.proxyPort=<your_proxy_port> -Dhttp.nonProxyHosts=127.0.0.1|<hostname_1_for_sparql_endpoint_inside_firewall>|<hostname_2_for_sparql_endpoint_inside_firewall>|...|<hostname_n_for_sparql_endpoint_inside_firewall>
You can specify these settings in the startWebLogic.sh script.
If an Oracle database is used for storage of and access to SPARQL queries and XSL transformations for SPARQL Gateway, then you must configure a data source named OracleSGDS.
To create this data source, follow the instructions in Section 7.2.1, "Creating the Required Data Source Using WebLogic Server"; however, specify OracleSGDS as the data source name instead of OracleSemDS.
If the OracleSGDS data source is configured and available, SPARQL Gateway servlet will automatically create all the necessary tables and indexes upon initialization.
The following JSP files in SPARQL Gateway can help you to view, edit, and update SPARQL queries and XSL transformations that are stored in an Oracle database:
http://<host>:7001/sparqlgateway/admin/sparql.jsp http://<host>:7001/sparqlgateway/admin/xslt.jsp
These files are protected by HTTP Basic Authentication. In WEB-INF/weblogic.xml, a principal named SparqlGatewayAdminGroup is defined.
To be able to log in to either of these JSP pages, you must use the WebLogic Server to add a group named SparqlGatewayAdminGroup, and create a new user or assign an existing user to this group.
The primary interface for an application to interact with SPARQL Gateway is through a URL with the following format:
http://host:port/sparqlgateway/sg?<SPARQL_ENDPOINT>&<SPARQL_QUERY>&<XSLT>
In the preceding format:
<SPARQL_ENDPOINT> specifies the ee parameter, which contains a URL encoded form of a SPARQL endpoint.
For example, ee=http%3A%2F%2Fsparql.org%2Fbooks is the URL encoded string for SPARQL endpoint http://sparql.org/books. It means that SPARQL queries are to be executed against endpoint http://sparql.org/books.
<SPARQL_QUERY> specifies either the SPARQL query, or the location of the SPARQL query.
If it is feasible for an application to accept a very long URL, you can encode the whole SPARQL query and set eq=<encoded_SPARQL_query> in the URL If it is not feasible for an application to accept a very long URL, you can store the SPARQL queries and make them available to SPARQL Gateway using one of the approaches described in Section 7.16.3.1.
<XSLT> specifies either the XSL transformation, or the location of the XSL transformation.
If it is feasible for an application to accept a very long URL, you can encode the whole XSL transformation and set ex=<encoded_XSLT> in the URL If it is not feasible for an application to accept a very long URL, you can store the XSL transformations and make them available to SPARQL Gateway using one of the approaches described in Section 7.16.3.1.
Related topics:
If it is not feasible for an application to accept a very long URL, you can specify the location of the SPARQL query and the XSL transformation in the <SPARQL_QUERY> and <XSLT> portions of the URL format described in Section 7.16.3, using any of the following approaches:
Store the SPARQL queries and XSL transformations in the SPARQL Gateway Web application itself.
To do this, unpack the sparqlgateway.war file, and store the SPARQL queries and XSL transformations in the top-level directory; then pack the sparqlgateway.war file and redeploy it.
The sparqlgateway.war file includes the following example files: qb1.sparql (SPARQL query) and default.xslt (XSL transformation).
|
Tip: Use the file extension.sparql for SPARQL query files, and the file extension .xslt for XSL transformation files. |
The syntax for specifying these files (using the provided example file names) is wq=qb1.sparql for a SPARQL query file and wx=default.xslt for an XSL transformation file.
If you want to customize the default XSL transformations, see the examples in Section 7.16.4, "Customizing the Default XSLT File".
If you specify wx=noop.xslt, XSL transformation is not performed and the SPARQL response is returned "as is" to the client.
Store the SPARQL queries and XSL transformations in a file system directory, and make sure that the directory is accessible for the deployed SPARQL Gateway Web application.
By default, the directory is set to /tmp, as shown in the following <init-param> setting:
<init-param> <param-name>sparql_gateway_repository_filedir</param-name> <param-value>/tmp/</param-value> </init-param>
It is recommended that you customize this directory before deploying the SPARQL Gateway. To change the directory setting, edit the text in between the <param-value> and </param-value> tags.
The follwoing examples specify a SPARQL query file and an XSL transflrmation file that are in the directory specified in the <init-param> element for sparql_gateway_repository_filedir:
fq=qb1.sparql fx=myxslt1.xslt
Make the SPARQL queries and XSL transformations accessible from a website.
By default, the website directory is set to http://127.0.0.1/queries/, as shown in the following <init-param> setting:
<init-param> <param-name>sparql_gateway_repository_url</param-name> <param-value>http://127.0.0.1/queries/</param-value> </init-param>
Customize this directory before deploying the SPARQL Gateway. To change the website setting, edit the text in between the <param-value> and </param-value> tags.
The follwoing example specifies a SPARQL query file and an XSL transflrmation file that are in the URL specified in the <init-param> element for sparql_gateway_repository_url.
uq=qb1.sparql ux=myxslt1.xslt
Internally, SPARQL Gateway computes the appropriate complete URL, fetches the content, starts query execution, and applies the XSL transformation to the query response XML.
Store the SPARQL queries and XSL transformations in an Oracle database.
This approach requires that the J2EE data source OracleSGDS be defined. After SPARQL Gateway retrieves a database connection from the OracleSGDS data source, a SPARQL query is read from the database table ORACLE_ORARDF_SG_QUERY using the integer ID provided.
The syntax for fetching a SPARQL query from an Oracle database is dq=<integer-id>, and the syntax for fetching an XSL transformation from an Oracle database is dx=<integer-id>.
Upon servlet initialization, the following tables are created automatically if they do not already exist (you do not need to create them manually):
ORACLE_ORARDF_SG_QUERY with a primary key of QID (integer type)
ORACLE_ORARDF_SG_XSLT with a primary key of XID (integer type)
When you submit a potentially long-running query using the URL format described in Section 7.16.3, you can limit the execution time by specifying a timeout value in milliseconds. For example, the following shows the URL format and a timeout specification that the SPARQL query execution started from SPARQL Gateway is to be ended after 1000 milliseconds (1 second):
http://host:port/sparqlgateway/sg?<SPARQL_ENDPOINT>&<SPARQL_QUERY>&<XSLT>&t=1000
If a query does not finish when timeout occurs, then an empty SPARQL response is constructed by SPARQL Gateway.
Note that even if SPARQL Gateway times out a query execution at the HTTP connection level, the query may still be running on the server side. The actual behavior will be vendor-dependent.
|
Note: You can specify best effort query execution only if you also specify a timeout value (described in Section 7.16.3.2). |
When you submit a potentially long-running query using the URL format described in Section 7.16.3, if you specify a timeout value, you can also specify a "best effort" limitation on the query. For example, the following shows the URL format with a timeout specification of 1000 milliseconds (1 second) and a best effort specification (&b=t):
http://host:port/sparqlgateway/sg?<SPARQL_ENDPOINT>&<SPARQL_QUERY>&<XSLT>&t=1000&b=t
The web.xml file includes two parameter settings that affect the behavior of the best effort option: sparql_gateway_besteffort_maxrounds and sparql_gateway_besteffort_maxthreads. The following show the default definitions:
<init-param> <param-name>sparql_gateway_besteffort_maxrounds</param-name> <param-value>10</param-value> </init-param> <init-param> <param-name>sparql_gateway_besteffort_maxthreads</param-name> <param-value>3</param-value> </init-param>
When a SPARQL SELECT query is executed in best effort style, a series of queries will be executed with an increasing LIMIT value setting in the SPARQL query body. (The core idea is based on the observation that a SPARQL query runs faster with a smaller LIMIT setting.) SPARQL Gateway starts query execution with a "LIMIT 1" setting. Ideally, this query can finish before the timeout is due. Assume that is the case, the next query will have its LIMIT setting is increased, and subsequent queries have higher limits. The maximum number of query executions is controlled by the sparql_gateway_besteffort_maxrounds parameter.
If it is possible to run the series of queries in parallel, the sparql_gateway_besteffort_maxthreads parameter controls the degree of parallelism.
By default, SPARQL Gateway assumes that XSL transformations generate XML, and so the default content type set for HTTP response is text/xml. However, if your application requires a response format other than XML, you can specify the format in an additional URL parameter (with syntax &rt=), using the following format:
http://host:port/sparqlgateway/sg?<SPARQL_ENDPOINT>&<SPARQL_QUERY>&<XSLT>&rt=<content_type>
Note that <content_type> must be URL encoded.
You can customize the default XSL transformation file (the one referenced using wx=default.xslt). This section presents some examples of customizations.
The following example implements this namespace prefix replacement logic: if a variable binding returns a URI that starts with http://purl.org/goodrelations/v1#, that portion is replaced by gr:; and if a variable binding returns a URI that starts with http://www.w3.org/2000/01/rdf-schema#, that portion is replaced by rdfs:.
<xsl:when test="starts-with(text(),'http://purl.org/goodrelations/v1#')">
<xsl:value-of select="concat('gr:',substring-after(text(),'http://purl.org/goodrelations/v1#'))"/>
</xsl:when>
...
<xsl:when test="starts-with(text(),'http://www.w3.org/2000/01/rdf-schema#')">
<xsl:value-of select="concat('rdfs:',substring-after(text(),'http://www.w3.org/2000/01/rdf-schema#'))"/>
</xsl:when>
The following example implements logic to trim a leading http://localhost/ or a leading http://127.0.0.1/.
<xsl:when test="starts-with(text(),'http://localhost/')"> <xsl:value-of select="substring-after(text(),'http://localhost/')"/> </xsl:when> <xsl:when test="starts-with(text(),'http://127.0.0.1/')"> <xsl:value-of select="substring-after(text(),'http://127.0.0.1/')"/> </xsl:when>
In addition to a Web interface, the SPARQL Gateway administration service provides a convenient Java application programming interface (API) for managing SPARQL queries and their associated XSL transformations. The Java API is included in the Jena Adapter library, sdordfclient.jar.
Java API reference information is available in the javadoc_sparqlgateway.zip file that is included in the SPARQL Gateway .zip file (described in Section 7.16.2.1).
The main entry point for this API is the oracle.spatial.rdf.client.jena.SGDBHandler class (SPARQL Gateway Database Handler), which provides the following static methods for managing queries and transformations:
deleteSparqlQuery(Connection, int)
deleteXslt(Connection, int)
insertSparqlQuery(Connection, int, String, String, boolean)
insertXslt(Connection, int, String, String, boolean)
getSparqlQuery(Connection, int, StringBuilder, StringBuilder)
getXslt(Connection, int, StringBuilder, StringBuilder)
These methods manipulate and retrieve entries in the SPARQL Gateway associated tables that are stored in an Oracle Database instance. To use these methods, the necessary associated tables must already exist. If the tables do not exist, deploy the SPARQL Gateway on a Web server and access a URL in the following format:
http://<host>:<port>/sparqlgateway/sg?
where <host> is the host name of the Web server and <port> is the listening port of the Web server. Accessing this URL will automatically create the necessary tables if they do not already exist.
Any changes made through the Java API affect the SPARQL Gateway Web service in the same way as changes made through the administration Web interface. This provides the flexibility to manage queries and transformations using the interface you find most convenient.
Note that the insert methods provided by the Java API will not replace existing queries or transformations stored in the tables. Attempting to replace an existing query or transformation will fail. To replace a query or transformation, you must remove the existing entry in the table using one of the delete methods, and then insert the new query or transformation using one of the insert methods.
The following examples demonstrate how to perform common management tasks using the Java API. The examples assume a connection has already been established to the underlying Oracle Database instance backing the SPARQL Gateway.
Example 7-31 adds a query and an XSL transformation to the database backing the SPARQL Gateway. After the query and transformation are added, other programs can use the query and transformation through the gateway by specifying the appropriate query ID (qid) and XSL transformation ID (xid) in the request URL.
|
Note: Although Example 7-31 inserts both a query and transformation, the query and transformation are not necessarily related and do not need to be used together when accessing SPARQL Gateway. Any query in the database can be used with any transformation in the database when submitting a request to SPARQL Gateway. |
Example 7-31 Storing a SPARQL Query and an XSL Transformation
String query = "PREFIX ... SELECT ..."; // full SPARQL query text
String xslt = "<?xml ...> ..."; // full XSLT transformation text
String queryDesc = "Conference attendee information"; // description of SPARQL query
String xsltDesc = "BIEE table widget transformation"; // description of XSLT transformation
int queryId = queryIdCounter++; // assign a unique ID to this query
int xsltId = xsltIdCounter++; // assign a unique ID to this transformation
// Inserting a query or transformation will fail if the table already contains
// an entry with the same ID. Setting this boolean to true will ignore these
// exceptions (but the table will remain unchanged). Here we specify that we
// want an exception thrown if we encounter a duplicate ID.
boolean ignoreDupException = false;
// add the query
try {
// Delete query if one already exists with this ID (this will not throw an
// error if no such entry exists)
SGDBHandler.deleteSparqlQuery( connection, queryId );
SGDBHandler.insertSparqlQuery( connection, queryId, query, queryDesc, ignoreDupException );
} catch( SQLException sqle ) {
// Handle exception
} catch( QueryException qe ) {
// Handle query syntax exception
}
// add the XSLT
try {
// Delete xslt if one already exists with this ID (this will not throw an
// error if no such entry exists)
SGDBHandler.deleteXslt( connection, xsltId );
SGDBHandler.insertXslt( connection, xsltId, xslt, xsltDesc, ignoreDupException );
} catch( SQLException sqle ) {
// Handle database exception
} catch( TransformerConfigurationException tce ) {
// Handle XSLT syntax exception
}
Example 7-32 retrieves an existing query from the database, modifies it, then stores the updated version of the query back in the database. These steps simulate editing a query and saving the changes. (Note that if the query does not exist, an exception is thrown.)
Example 7-32 Modifying a Query
StringBuilder query;
StringBuilder description;
// Populate these with the query text and description from the database
query = new StringBuilder( );
description = new StringBuilder( );
// Get the query from the database
try {
SGDBHandler.getSparqlQuery( connection, queryId, query, description );
} catch( SQLException sqle ) {
// Handle exception
// NOTE: exception is thrown if query with specified ID does not exist
}
// The query and description should be populated now
// Modify the query
String updatedQuery = query.toString( ).replaceAll("invite", "attendee");
// Insert the query back into the database
boolean ignoreDup = false;
try {
// First must delete the old query
SGDBHandler.deleteSparqlQuery( connection, queryId );
// Now we can add
SGDBHandler.insertSparqlQuery( connection, queryId, updatedQuery, description.toString( ), ignoreDup );
} catch( SQLException sqle ) {
// Handle exception
} catch( QueryException qe ) {
// Handle query syntax exception
}
Example 7-33 retrieves an existing XSL transformation and prints it to standard output. (Note that if the transformation does not exist, an exception is thrown.)
Example 7-33 Retrieving and Printing an XSL Transformation
StringBuilder xslt;
StringBuilder description;
// Populate these with the XSLT text and description from the database
xslt = new StringBuilder( );
description = new StringBuilder( );
try {
SGDBHandler.getXslt( connection, xsltId, xslt, description );
} catch( SQLException sqle ) {
// Handle exception
// NOTE: exception is thrown if transformation with specified ID does not exist
}
// Print it to standard output
System.out.printf( "XSLT description: %s\n", description.toString( ) );
System.out.printf( "XSLT body:\n%s\n", xslt.toString( ) );
SPARQL Gateway provides several browser-based interfaces to help you test queries, navigate semantic data, and manage SPQARQL query and XSLT files:
http://<host>:<port>/sparqlgateway/index.html provides a simple interface for executing SPARQL queries and then applying the transformations in the default.xslt file to the response. Figure 7-2 shows this interface for executing a query.
Figure 7-2 Graphical Interface Main Page (index.html)
Enter or select a SPARQL Endpoint, specify the SPARQL SELECT Query Body, and press Submit Query.
For example, if you specify http://dbpedia.org/sparql as the SPARQL endpoint and use the SPARQL query body from Figure 7-2, the response will be similar to Figure 7-3. Note that the default transformations (in default.xslt) have been applied to the XML output in this figure.
Figure 7-3 SPARQL Query Main Page Response
http://<host>:<port>/sparqlgateway/browse.jsp provides navigation and browsing capabilities for semantic data. It works against any standard compliant SPARQL endpoint. Figure 7-4 shows this interface for executing a query.
Figure 7-4 Graphical Interface Navigation and Browsing Page (browse.jsp)
Enter or select a SPARQL Endpoint, specify the SPARQL SELECT Query Body, optionally specify a Timeout (ms) value in milliseconds and the Best Effort option, and press Submit Query.
The SPARQL response is parsed and then presented in table form, as shown in Figure 7-5.
Figure 7-5 Browsing and Navigation Page: Response
In Figure 7-5, note that URIs are clickable to allow navigation, and that when users move the cursor over a URI, tool tips are shown for the URIs which have been shortened for readability (as in http://purl.org.dc/elements/1.1/title being displayed as the tool tip for dc:title in the figure).
If you click the URI http://example.org/book/book5 in the output shown in Figure 7-5, a new SPARQL query is automatically generated and executed. This generated SPARQL query has three query patterns that use this particular URI as subject, predicate, and object, as shown in Figure 7-6. Such a query can give you a good idea about how this URI is used and how it is related to other resources in the data set.
Figure 7-6 Query and Response from Clicking URI Link
When there are many matches of a query, the results are organized in pages and you can click on any page. The page size by default is 50 results. To display more (or fewer) than 50 rows per page in a response with the Browsing and Navigation Page (browse.jsp), you can specify the &resultsPerPage parameter in the URL. For example, to allow 100 rows per page, include the following in the URL:
&resultsPerPage=100
http://<host>:<port>/sparqlgateway/admin/xslt.jsp provides a simple XSLT management interface. You can enter an XSLT ID (integer) and click Get XSLT to retrieve both the Description and XSLT Body. You can modify the XSLT Body text and then save the changes by clicking Save XSLT. Note that there is a previewer to help you navigate among available XSLT definitions.
Figure 7-7 shows the XSLT Management Page.
http://<host>:<port>/sparqlgateway/admin/xslt.jsp provides a simple SPARQL management interface. You can enter a SPARQL ID (integer) and click Get SPARQL to retrieve both the Description and SPARQL Body. You can modify the SPARQL Body text and then save the changes by clicking Save SPARQL. Note that there is a previewer to help you navigate among available SPARQL queries.
Figure 7-8 shows the SPARQL Management Page.
This section explains how to create an XML Data source for Oracle Business Intelligence Enterprise Edition (OBIEE), by integrating OBIEE with RDF using SPARQL Gateway as a bridge. (The specific steps and illustrations reflect the Oracle BI Administration Tool Version 11.1.1.3.0.100806.0408.000.)
Start the Oracle BI Administration Tool.
Click File, then Import Metadata. The first page of the Import Metadata wizard is displayed, as shown in Figure 7-9.
Figure 7-9 Import Metadata - Select Data Source
Connection Type: Select XML.
URL: URL for an application to interact with SPARQL Gateway, as explained in Section 7.16.3. You can also include the timeout and best effort options.
Ignore the User Name and Password fields.
Click Next. The second page of the Import Metadata wizard is displayed, as shown in Figure 7-10.
Figure 7-10 Import Metadata - Select Metadata Types
Select the desired metadata types to be imported. Be sure that Tables is included in the selected types.
Click Next. The third page of the Import Metadata wizard is displayed, as shown in Figure 7-11.
Figure 7-11 Import Metadata - Select Metadata Objects
In the Data Source View, expand the node that has the table icon, select the column names (mapped from projected variables defined in the SPARQL SELECT statement), and click the right-arrow (>) button to move the selected columns to the Repository View.
Click Finish.
Complete the remaining steps for the usual BI Business Model work and Mapping and Presentation definition work, which are not specific to SPARQL Gateway or RDF data.
The following are selected terms relevant to the Oracle Database implementation of semantic technologies support. This is not a comprehensive RDF and OWL glossary.
apply pattern
Part of a data access constraint defines additional graph patterns to be applied on the resources that match the match pattern before they can be used to construct the query results. See also: match pattern
basic graph pattern (BGP)
A set of triple patterns. From the W3C SPARQL Query Language for RDF Recommendation: "SPARQL graph pattern matching is defined in terms of combining the results from matching basic graph patterns. A sequence of triple patterns interrupted by a filter comprises a single basic graph pattern. Any graph pattern terminates a basic graph pattern."
clique
A graph in which every node of it is connected to, bidirectionally, every other node in the same graph.
Cytoscape
An open source bioinformatics software platform for visualizing molecular interaction networks and integrating these interactions with gene expression profiles and other state data. (See http://www.cytoscape.org/.) An RDF viewer (available for download) is provided as a Cytoscape plug-in.
entailment
An object containing precomputed triples that can be inferred from applying a specified set of rulebases to a specified set of models. See also: rulebase
extractor policy
A named dictionary entity that determines the characteristics of a semantic index that is created using the policy. Each extractor policy refers, directly or indirectly, to an instance of an extractor type.
graph pattern
A combination of triples constructed by combining triple patterns in various ways, including conjunction of triple patterns into groups, optionally using filter conditions, and then combining such groups via connectors similar to disjunctions, outer-joins, and so on. SPARQL querying is based around graph pattern matching.
inferencing
The ability to make logical deductions based on rules. Inferencing enables you to construct queries that perform semantic matching based on meaningful relationships among pieces of data, as opposed to just syntactic matching based on string or other values. Inferencing involves the use of rules, either supplied by Oracle or user-defined, placed in rulebases.
information extractor
An application that processes unstructured documents and extract meaningful information from them, often using natural-language processing engines with the aid of ontologies.
Jena Adapter for Oracle Database
An Oracle-supplied adapter (available for download) for Jena, which is a Java framework for building Semantic Web applications.
match pattern
Part of a constraint that determines the type of access restriction it enforces and binds one or more variables to the corresponding data instances accessed in the user query. See also: apply pattern
model
A user-created semantic structure that has a model name, and refers to triples stored in a specified table column. Examples in this manual are the Articles and Family models.
ontology
A shared conceptualization of knowledge in a particular domain. It consists of a collection of classes, properties, and optionally instances. Classes are typically related by class hierarchy (subclass/ superclass relationship). Similarly, the properties can be related by property hierarchy (subproperty/ superproperty relationship). Properties can be symmetric or transitive, or both. Properties can also have domain, ranges, and cardinality constraints specified for them.
OWLPrime
An Oracle-defined subset of OWL capabilities; refers to the elements of the OWL standard supported by the Oracle Database semantic technologies native inferencing engine.
semantic index
An index of type MDSYS.SEMCONTEXT, created on textual documents stored in a column of a table, and used with information extractors to locate and extract meaningful information from unstructured documents. See also: information extractor
Sesame Adapter for Oracle Database
An Oracle-supplied adapter (available for download) that integrates the popular Sesame Java APIs with Oracle Semantic Technologies support.
Simple Knowledge Organization System (SKOS)
A data model that is especially useful for representing thesauri, classification schemes, taxonomies, and other types of controlled vocabulary. SKOS is based on standard semantic web technologies including RDF and OWL, which makes it easy to define the formal semantics for those knowledge organization systems and to share the semantics across applications.
triple pattern
Similar to an RDF triple, but allows use of a variable in place of any of the three components (subject, predicate, or object). Triple patterns are basic elements in graph patterns used in SPARQL queries. A triple pattern used in a query against an RDF graph is said to match if, substitution of RDF terms for the variables present in the triple pattern, creates a triple that is present in the RDF graph. See also: graph pattern
This appendix describes the required steps that you must perform before you can use any types, synonyms, or PL/SQL packages related to Oracle semantic technologies support in the current Oracle Database release. You must run one or more scripts, and you must ensure that Spatial is installed and the Partitioning option is enabled. These requirements are explained in Section A.1.
This appendix also describes the steps if, after enabling semantic technologies support, you need to do any of the following:
Downgrade the semantic technologies support to that provided with a previous Oracle Database release, as explained in Section A.2.
Remove all support for semantic technologies from the database, as explained in Section A.3.
Before you can use any types, synonyms, or PL/SQL packages related to Oracle semantic technologies support in the current Oracle Database release, you must either install the capabilities in a new Oracle Database installation or upgrade the capabilities from a previous release, following the steps in whichever of the following sections applies to your situation:
Section A.1.1, "Enabling Semantic Technologies Support in a New Database Installation"
Section A.1.2, "Upgrading Semantic Technologies Support from Release 11.1"
Section A.1.3, "Upgrading Semantic Technologies Support from Release 10.2"
If you upgraded to Release 11.2.0.2.0 and your Semantic Technologies installation is invalid, see Section A.1.4, "Release 11.2.0.2: Required Actions if Semantic Technologies Installation is Invalid"
In addition, you must ensure that Spatial is installed and the Partitioning option is enabled, as explained in Section A.1.5.
To enable semantic technologies support in a new installation of Oracle Database Release 11.2 (or for an upgrade from Release 10.2 if no RDF network exists, as explained in Section A.1.3), follow these steps:
Connect to the database as the SYS user with SYSDBA privileges (SYS AS SYSDBA, and enter the SYS account password when prompted).
Start SQL*Plus, and enter the following statement:
Linux: @$ORACLE_HOME/md/admin/catsem.sql
Windows: @%ORACLE_HOME%\md\admin\catsem.sql
If a semantic network already exists, or if any semantic technologies types, tables, or PL/SQL packages already exist, the catsem.sql script exits with an error.
If the script completes successfully, a row with the following column values is inserted into the MDSYS.RDF_PARAMETER table:
NAMESPACE: MDSYS
ATTRIBUTE: SEM_VERSION
VALUE: (string starting with 112)
DESCRIPTION: VALID
If you use Workspace Manager with RDF data, you must also run the appropriate script after you run catsem.sql, as explained in Section 6.1, "Enabling Workspace Manager Support for RDF Data".
If you are upgrading from Oracle Database Release 11.1 that includes the semantic technologies support for Release 11.1, the semantic technologies support is automatically upgraded to Release 11.2 when the database is upgraded. If you use Workspace Manager with RDF data, you must also run the appropriate script after the upgrade of semantic technologies support, as explained in Section 6.1, "Enabling Workspace Manager Support for RDF Data".
However, you will also need to migrate RDF data if you have an existing Release 11.1 RDF network containing triples that include typed literal values of type xsd:float, xsd:double, xsd:boolean, or xsd:time.
To check if you need to migrate RDF data, connect to the database as a user with DBA privileges and query the MDSYS.RDF_PARAMETER table, as follows:
SELECT namespace, attribute, value FROM mdsys.rdf_parameter
WHERE namespace='MDSYS'
AND attribute IN ('FLOAT_DOUBLE_DECIMAL',
'XSD_TIME', 'XSD_BOOLEAN',
'DATA_CONVERSION_CHECK');
If the FLOAT_DOUBLE_DECIMAL, XSD_TIME, or XSD_BOOLEAN attributes have the string value INVALID or if the DATA_CONVERSION_CHECK attribute has the string value FAILED_UNABLE_TO_LOCK_APPLICATION_TABLES, FAILED_INSUFFICIENT_WORKSPACE_PRIVILEGES, or FAILED_OLS_POLICIES_ARE_ENABLED, you need to migrate RDF data.
However, if the FLOAT_DOUBLE_DECIMAL, XSD_TIME, and XSD_BOOLEAN attributes do not exist or have the string value VALID and if the DATA_CONVERSION_CHECK attribute does not exist, you do not need to migrate RDF data. However, if your semantic network may have any empty RDF literals, see Section A.1.2.1, "Handling of Empty RDF Literals"; and if you choose to migrate existing empty literals to the new format, follow the steps in this section.
To migrate RDF data, follow these steps:
Connect to the database as the SYS user with SYSDBA privileges (SYS AS SYSDBA, and enter the SYS account password when prompted), and enter: SET CURRENT_SCHEMA=MDSYS
Ensure that the user MDSYS has the following privileges:
INSERT privilege on all application tables in the semantic network
ALTER ANY INDEX privilege (optional: only necessary if Semantic Indexing for Documents is being used)
ACCESS privilege for any workspace in which version-enabled application tables have been modified (optional: only necessary if Workspace Manager is being used for RDF data)
Ensure that any OLS policies for RDF data are temporarily disabled (optional: only necessary if OLS for RDF Data is being used). OLS policies can be re-enabled after running convert_old_rdf_data.
Start SQL*Plus. If you want to migrate the RDF data without converting existing empty literals to the new format (see Section A.1.2.1), enter the following statement:
EXECUTE sdo_rdf_internal.convert_old_rdf_data;
If you want to migrate the RDF data and also convert existing empty literals to the new format, call convert_old_rdf_data with the flags parameter set to 'CONVERT_ORARDF_NULL'. In addition, you can use an optional tablespace_name parameter to specify the tablespace to use when creating intermediate tables during data migration. For example, the following statement migrates old semantic data, converts existing "orardf:null " values to "", and uses the MY_TBS tablespace for any intermediate tables:
EXECUTE sdo_rdf_internal.convert_old_rdf_data( flags=>'CONVERT_ORARDF_NULL', tablespace_name=>'MY_TBS');
The sdo_rdf_internal.convert_old_rdf_data procedure may take a significant amount of time to run if the semantic network contains many triples that are using (or affected by use of) xsd:float, xsd:double, xsd:time, or xsd:boolean typed literals.
Enter the following statement:
Linux: @$ORACLE_HOME/md/admin/semrelod.sql
Windows: @%ORACLE_HOME%\md\admin\semrelod.sql
|
Note: You may encounter the ORA-00904 (invalid identifier) error when executing a SEM_MATCH query if thesdo_rdf_internal.convert_old_rdf_data procedure and the semrelod.sql script were not run after the upgrade to Release 11.2. |
The way empty-valued RDF literals are handled has changed in Release 11.2. Before this release, the values of empty-valued literals were converted to "orardf:null ". In Release 11.2, such values are stored without modification (that is, as ""). However, whether you migrate existing "orardf:null " values to "" is optional.
To check if "orardf:null " values exist in your semantic network, connect to the database as a user with DBA privileges and query the MDSYS.RDF_PARAMETER table, as follows:
SELECT namespace, attribute, value FROM mdsys.rdf_parameter WHERE namespace='MDSYS' AND attribute = 'NULL_LITERAL';
If the NULL_LITERAL attribute has the value EXISTS, then "orardf:null " values are present in your semantic network.
If you are upgrading from Oracle Database Release 10.2 that includes the semantic technologies support for Release 10.2, the actions required depend on whether there is an existing RDF network.
If there is not an existing RDF network, skip the rest of this section and follow the instructions in Section A.1.1, "Enabling Semantic Technologies Support in a New Database Installation".
If there is an existing RDF network, perform the following steps after the Oracle Database upgrade:
Connect to the database (Release 11.2) as the SYS user with SYSDBA privileges (SYS AS SYSDBA, and enter the SYS account password when prompted).
Start SQL*Plus, and enter the following statement:
Linux: @$ORACLE_HOME/md/admin/catsem10i.sql
Windows: @%ORACLE_HOME%\md\admin\catsem10i.sql
The catsem10i.sql script enables Release 11.2 semantic technologies support and migrates RDF data from Release 10.2 to Release 11.2 format. The script may take a long time to run if the existing Release 10.2 RDF network contains a large amount of RDF data.
Further action may be required if your Semantic Technologies installation is invalid after upgrading to Release 11.2.0.2.0. (This is not an issue with upgrades to Release 11.2.0.3 and later.) Action is required if either or both of the following are true after upgrading to Release 11.2.0.2.0:
A row exists with the following values in the MDSYS.RDF_PARAMETER table:
MDSYS SEM_VERSION 11202 INVALID
The STATUS column value is INVALID in any row returned by the following query:
SELECT object_name, status FROM all_objects WHERE object_name = 'SEMCONTEXTINDEXMETHODS' or object_name = 'PRLLIDX_CREATE';
In such a case, enter the following sequence of commands as SYSDBA to complete the upgrade of your installation:
SQL> @ $ORACLE_HOME/md/admin/sdordfctx.sql SQL> @ $ORACLE_HOME/md/admin/semrelod.sql SQL> EXECUTE sys.validate_sdo;
For the preceding commands:
When running sdordfctx.sql, you can ignore any ORA-01921, ORA-02303, ORA-00955, and ORA-29809 errors.
Executing sys.validate_sdo is needed only if SDO is invalid, which it could be if Semantic Technologies is invalid; however, there is no harm in executing sys.validate_sdo in any case.
After running the preceding commands, check whether your Semantic Technologies installation is valid by checking if a row exists with the following values in the MDSYS.RDF_PARAMETER table:
MDSYS SEM_VERSION 11202 VALID
Oracle Spatial must be installed before you can use any of the RDF and OWL capabilities. Oracle Locator is not sufficient. For information about Spatial and Locator, see Oracle Spatial Developer's Guide.
The Partitioning option must be enabled before you can use any of the RDF and OWL capabilities. For licensing information about the Partitioning option, see Oracle Database Licensing Information. For usage information about partitioning, see Oracle Database VLDB and Partitioning Guide.
This section explains how to downgrade the semantic technologies support, in conjunction with an Oracle Database downgrade to Release 11.1 or 10.2.
Downgrading is strongly discouraged, except for rare cases where it is necessary. If you downgrade to a previous release, you will not benefit from bug fixes and enhancements that have been made in intervening releases.
If you have enabled Workspace Manager support for RDF data, you must remove that support before you downgrade semantic technologies support in the database, as explained in Section 6.1.1.
If you need to downgrade to Oracle Database Release 11.1, the semantic technologies component will be downgraded automatically when you downgrade the database. However, any RDF or OWL data that is specific to Release 11.2 (that is, Release 11.2 RDF/OWL persistent structures that are not supported in previous versions) must be dropped before you perform the downgrade, so that the database is compatible with Release 11.1.
Any virtual models will not be preserved during a downgrade, because they are only available through a Release 11.1.0.7.0 patch (number 7600122) that was made available on My Oracle Support (MetaLink) in November, 2008. To use virtual models, you must reapply this patch after the downgrade, and then re-create the virtual models. For convenience, you can use the semvmrecreate.sql script to generate a script that you can later use (after the downgrade) to automatically re-create any virtual models that were present in the Release 11.2 semantic network. To do so, follow these steps before you downgrade the database :
Connect to the database (Release 11.2) as the SYS user with SYSDBA privileges (SYS AS SYSDBA, and enter the SYS account password when prompted).
Start SQL*Plus, and enter a statement in the following format:
Linux: @$ORACLE_HOME/md/admin/semvmrecreate.sql /my_dir_path/my_vm_recreate.sql
Windows: @%ORACLE_HOME%\md\admin\semvmrecreate.sql \my_dir_path\my_vm_recreate.sql
where my_dir_path is the path to the location in which to create the my_vm_recreate.sql script file. (You can use another file name for the script, if you want.)
To check if any Release 11.2 RDF data is incompatible with Release 11.1, perform the following steps:
Connect to the database (Release 11.2) as the SYS user with SYSDBA privileges (SYS AS SYSDBA, and enter the SYS account password when prompted).
Start SQL*Plus, and enter the following statements:
SET SERVEROUT ON EXECUTE SDO_SEM_DOWNGRADE.CHECK_111_COMPATIBLE;
If any RDF data is incompatible with Release 11.1, the procedure generates an error and displays a list of the incompatible data. In this case, you must run the semrelod111.sql script after the database downgrade, as follows:
In the Release 11.2 database, save a copy of the semrelod111.sql file, which is in the following location:
Linux: $ORACLE_HOME/md/admin/semrelod111.sql
Windows: %ORACLE_HOME%\md\admin\semrelod111.sql
If you have any virtual models that you want to be able to re-create after the download, run the semvmrecreate.sql script (if you have not already done so), as explained earlier in this section.
Remove any Release 11.2 release-specific RDF or OWL data (including virtual models) if you have not already done so, as explained earlier in this section.
Perform the database downgrade.
In the Release 11.1 database, copy the saved copy of the semrelod111.sql file to the following location:
Linux: $ORACLE_HOME/md/admin/
Windows: %ORACLE_HOME%\md\admin\
Connect to the Release 11.1 database as the SYS user with SYSDBA privileges (SYS AS SYSDBA, and enter the SYS account password when prompted).
Start SQL*Plus, and enter the following statement:
Linux: @$ORACLE_HOME/md/admin/semrelod111.sql
Windows: @%ORACLE_HOME%\md\admin\semrelod111.sql
After the semrelod111.sql script completes successfully, Oracle semantic technologies support for Release 11.1 is enabled and ready to use, and all Release 11.1-compatible data is preserved.
If you want to enable support for virtual models, apply the Release 11.1.0.7 interim patch number 7600122.
If you previously generated a my_vm_recreate.sql script to re-create your virtual models after the downgrade, go to the my_dir_path location, connect to the database as the SYS user with SYSDBA privileges, start SQL*Plus, and run the my_vm_recreate.sql script.
If you need to downgrade to Oracle Database Release 10.2, follow the instructions in Section A.2.1 to downgrade to Release 11.1, and then follow the instructions in the rest of this section (taken from the Release 11.1 manual) to downgrade from Release 11.1 to Release 10.2.
If you need to downgrade to Oracle Database Release 10.2, and if you used Oracle Database Release 11 RDF or OWL features and want to preserve existing semantic data and rulebases, you must execute a statement to prepare for the downgrade, perform the downgrade, and execute another statement to restore the semantic data.
However, the following considerations apply:
Entailed graph data will not be preserved, because the same information can be regenerated using the Oracle Database Release 10.2 RDF inference API.
No rulebases or rules indexes related to OWL are preserved, because Oracle Database Release 10.2 did not support the OWL vocabulary.
Perform the following steps:
Before the database downgrade, connect to the Release 11 database as the SYS user with SYSDBA privileges (SYS AS SYSDBA, and enter the SYS account password when prompted).
Start SQL*Plus and enter the following statement:
EXECUTE SDO_SEM_DOWNGRADE.PREPARE_DOWNGRADE_FROM_11;
When this statement executes successfully, all existing semantic data and rulebases are saved. You will restore the semantic data after the database downgrade.
Perform the database downgrade.
Download the following file from the Semantic Technologies page of the Oracle Technology Network site: sdosemdgu.plb
If (and only if) your Oracle Database Release 10.2 release number is 10.2.0.1, click the Software link, and download and install the RDF-specific patch. (This patch is needed because Release 10.2.0.1 did not have the batch loading feature, which is used to restore the semantic data.)
Connect to the Release 10.2 database as the SYS user with SYSDBA privileges.
Start SQL*Plus and enter a statement in the following statement:
EXECUTE SDO_SEM_DOWNGRADE_UTL.PREPARE_DOWNGRADE_TO_102('<tablespace-name>');
Where <tablespace-name> is the name of the tablespace in which the RDF network will be created.
When this statement executes successfully, all semantic data that had been saved before the downgrade is restored and ready to use.
This section explains how to remove the semantic technologies support from the database. Removing this support is strongly discouraged, unless you have a strong reason for doing it. After you remove this support, no applications or database users will be able to use any types, synonyms, or PL/SQL packages related to Oracle semantic technologies support.
If you have enabled Workspace Manager support for RDF data, you must remove that support before you remove semantic technologies support from the database, as explained in Section 6.1.1.
To remove the semantic technologies support from the database, perform the following steps:
Connect to the database (Release 11.2) as the SYS user with SYSDBA privileges (SYS AS SYSDBA, and enter the SYS account password when prompted).
Start SQL*Plus, and enter the following statement:
Linux: @$ORACLE_HOME/md/admin/semremov.sql
Windows: @%ORACLE_HOME%\md\admin\semremov.sql
The semremov.sql script drops the semantic network and removes any semantic technologies types, tables, and PL/SQL packages:
The default control of access to the Oracle Database semantic data store is at the model level: the owner of a model may grant select, delete, and insert privileges on the model to other users by granting appropriate privileges on the view named RDFM_<model_name>. However, for applications with stringent security requirements, you can enforce a fine-grained access control mechanism by using either the Virtual Private Database feature or the Oracle Label Security option of Oracle Database:
Virtual Private Database (VPD) for RDF data allows security administrators to define policies that conditionally restrict a user's access to triples that involve instances of a specific RDF class or property. Using VPD, the data stored in the RDF models is classified using its metadata and each user query is rewritten to include context-dependent data access constraints that enforce access restrictions.
For information about using VPD, see Oracle Database Security Guide. For information about support for VPD with semantic data, see Section 5.1.
Oracle Label Security (OLS) for RDF data allows sensitivity labels to be associated with individual triples stored in an RDF model. For each query, access to specific triples is granted by comparing their labels with the user's session labels. Furthermore, a minimum sensitivity label for all triple describing a specific resource or all triples defined with a specific predicate can be enforced by assigning a sensitivity label directly to the resource or the predicate, respectively.
For information about using OLS, see Oracle Label Security Administrator's Guide. For information about support for OLS with semantic data, see Section 5.2
Some factors to consider in choosing whether use VPD or OLS with RDF data include the following:
OLS, when enabled for RDF data, is enforced at the network level, while VPD can be enforced for individual RDF models.
You cannot use both VPD and OLS for RDF data at the same time in an Oracle instance.
The application programming interface (API) for implementing VPD or OLS with semantic data is provided in the SEM_RDFSA PL/SQL package. Chapter 13 provides reference information about the programs in the SEM_RDFSA package.
VPD and OLS support for RDF data is included in the semantic technologies support for Release 11.2. (For information about enabling, downgrading, or removing semantic technologies support, see Appendix A.)
This chapter contains the following major sections:
The Virtual Private Database (VPD) feature is a row-level security mechanism that restricts access to specific rows in a relational table or view using a security policy and an application context. The security policy includes a policy function that dynamically generates predicates that are enforced for each row returned for the user query. The security predicates returned by the policy function associated with a table are typically expressed using the columns in the table and are thus dependent on the table metadata. Effectively, the security predicates ensure that the rows returned for a user query satisfy additional conditions that are applied on the contents of the row.
When the relational data is mapped to RDF, the data stored in a specific relational table represent triples describing instances of a specific RDF class. In this representation, the columns in the relational table map to RDF properties that are used to describe a resource. This mapping may be further extended to the application of VPD policies.
A VPD policy applied to RDF data restricts users' access to instances of a specific RDF class or property by applying predicates, in the form of graph patterns and filter conditions, on the instance data. For example, a VPD policy may be defined to restrict access to instances of a Contract RDF class only to the users belonging to a specific department. Furthermore, access to the hasContractValue property for a resource identified as instance of the Contract RDF class may be restricted only to the manager of the contract. VPD support for RDF data allows security conditions or data access constraints to be associated with RDF classes and properties, so that access to corresponding instance data is restricted.
A data access constraint associated with an RDF class or property specifies a graph query pattern that must be enforced for all corresponding data instances that are returned as the query result. For example, a SPARQL query pattern to find the due dates for all instances of a Contract class, {?contract :hasDueDate ?due}, may activate a data access constraint that ensures that the information returned pertains to contracts belonging to a specific department. This is achieved by logically rewriting the user's graph query pattern to include additional graph patterns, as shown in the following example:
{ ?contract :hasDueDate ?due .
?contract :drivenBy dept:Dept1 }
Furthermore, the values bound into the rewritten graph query pattern may make use of session context to enforce dynamic access restrictions. In the following example, the sys_context function in the object position of the triple pattern binds the appropriate department value based on the session context:
{ ?contract :hasDueDate ?due .
?contract :drivenBy
"sys_context('sa$appctx','user_dept'}"^^orardf:instruction }
In a relational data model, the metadata, in the form of table definition, always exists along with the data (the rows stored in the table); thus, the VPD policies defined using the metadata are well formed and the security conditions are generated using a procedural logic in the policy function.
However, the RDF data model allows data with no accompanying metadata, and therefore the class information for instance data may not always be available for a given RDF graph. For example, in an RDF graph a resource known to be a contract might not accompany a triple that asserts that the resource is an instance of Contract class. Usually such triples can be inferred using available domain and range specifications for the properties describing the resource.
Similarly, a VPD policy relies on the properties' domain and range specifications for deriving the class information for the instance data and for enforcing appropriate data access constraints. However, to avoid runtime dependencies on the user data, a VPD policy maintains the minimal metadata required to derive the class information in its dictionary, separate from the asserted and inferred triples. This also ensures that the metadata maintained by a VPD policy is complete even when some necessary information is missing from the asserted triples and that a VPD policy, with its data access constraints and the metadata, is self-contained and portable with no external dependencies.
A VPD policy with specific data access constraints and RDF metadata specifications can be used to enforce access restrictions for the data stored in an RDF model. Each SPARQL query issued on the model is analyzed to deduce the class information for the resources accessed in the query, and appropriate data access constraints are applied. To facilitate the compile-time analysis and derivation of class information for instance data, a graph query pattern with an unbound predicate is restricted when a VPD policy is in effect. For example, a graph pattern of the following form, anywhere in a SPARQL query pattern, raises an exception when any underlying model has a VPD policy:
{ <contract:projectHLS> ?pred ?obj }
VPD policies are only enforced for SEM_MATCH queries expressed in SPARQL syntax. All other forms of data access (such as classic syntax for graph pattern or direct query on the model view) are not permitted.
A VPD policy for RDF data is a named dictionary entity that can be used to enforce access restrictions for the data stored in one or more RDF models. A VPD policy defined for RDF data has unique characteristics, and it cannot be reused to enforce security policies for relational data. An RDF-VPD policy defined in the database includes the following:
The RDF Schema statements or metadata necessary for deriving class information for the data referenced in a SPARQL user query
The data access constraints that enforce access restrictions for the instance data
Application context that allows conditional inclusions of groups of data access constraints based on the runtime environment
An RDF-VPD policy is defined, owned, and maintained by a user with a security administrator role in an organization. This user must have at least EXECUTE privileges on the SYS.DBMS_RLS package. The owner of an RDF-VPD policy can maintain the metadata associated with the policy, define new data access constraints, and apply the policy to one or more RDF models.
A SPARQL query issued on an RDF model with a VPD policy is analyzed, and zero or more data access constraints defined in the policy are enforced such that the data instances that are returned as the query result also satisfy these constraints. The exact data access constraints enforced for a user query vary, based on the resources referenced in the query and the application context. For example, a policy that restricts a manager's access to the hasContractValue property may be relaxed for a user with the Vice President role.
Based on the role of the user, as captured in the application context, specific constraints to be applied are determined at runtime. To facilitate this dynamic inclusion of subsets of constraints defined in a VPD policy, the data access constraints are arranged into named groups that can be activated and deactivated based on the application context. During query analysis, only the constraints defined in the active groups are considered for enforcement.
The constraint groups within a VPD policy are managed using an application context and its package implementation. Each VPD policy can specify the namespace for a context created with the CREATE CONTEXT command. Each attribute associated with the context is treated as the name of a constraint group that can be activated by initializing its value to 1. For example, setting the value for MANAGER attribute of the context associated with a VPD policy to 1 will activate the constraints associated with MANAGER group for the user session. The logic that initializes specific constraint groups based on the user context is typically embedded in the package associated with the context type. The following example shows an excerpt from a sample implementation for one such package:
CREATE CONTEXT contracts_constr_ctx using sec_admin.contracts_ctx_pack;
begin
-- create the VPD policy with a context --
sem_rdfsa.create_vpd_policy(policy_name => 'CONTRACTS_POLICY',
policy_context => 'contracts_constr_ctx');
end;
/
create or replace package sec_admin.contracts_ctx_pack as
procedure init_constr_groups;
end;
/
create or replace package body sec_admin.contracts_ctx_pack as
procedure init_contr_groups is
hrdata EmpRole%rowtype;
begin
-- specific users with FULL access to the data associated with
-- the policy --
if (sys_context('userenv', 'session_user') = 'RDF_ADMIN') then
dbms_session.set_context('contracts_constr_ctx',
sem_rdfsa.VPD_FULL_ACCESS, 1);
return;
end if;
SELECT * into hrdata FROM EmpRole WHERE guid =
sys_context('userenv','session_user');
if (hrdata.emprole = 'VP') then
-- if the user logged in has VP role, activate the constraint
-- group named VP and keep all other groups inactive.
dbms_session.set_context('contracts_constr_ctx','VP', '1');
elsif (hrdata.emprole = 'MANAGER') then
dbms_session.set_context('contracts_constr_ctx', 'MANAGER', '1');
elsif ...
...
else
raise_application_error(-20010, 'unknown user role');
end if;
exception when others then
-- enforce constraints for all groups --
dbms_session.clear_all_context('contracts_constr_ctx');
end init_contr_groups;
end;
/
By default, when a namespace is not associated with an RDF-VPD policy or when a specific constraint group is not activated in a session, all the constraints defined in the policy are active and they are enforced for each user query. However, when a specific constraint group is activated by setting the corresponding namespace-attribute value to 1, only the constraints belonging to the group and any other constraints that are not associated with any group are enforced. For a given session, one or more constraint groups may be activated, in which case all the applicable constraints are enforced conjunctively.
At the time of creation, the data access constraints defined in a RDF-VPD policy may specify the name of a constraint group (explained in Section 5.1.3, "Data Access Constraints"). Within a database session, appropriate groups of constraints are activated based on the session context set by the context package. For all subsequent SPARQL queries in the database session, the constraints belonging to the active groups are consulted for enforcing appropriate security policies.
Maintenance operations on an RDF model with a VPD policy require unconditional access to data in the model. These operations include creation of an entailment using at least one VPD protected model, and load or data manipulation operations. You can grant unconditional access to the data stored in an RDF model by initializing a reserved attribute for the namespace associated with the VPD policy. The reserved attribute is defined by the package constant sem_rdfsa.VPD_FULL_ACCESS, and the context package implementation shown in the preceding example grants FULL access to the RDF_ADMIN user.
DML operations on the application table are not validated for VPD constraint violations, so only a user with FULL access to the corresponding model can add or modify existing triples.
You can use the SEM_MATCH operator to query an RDF model with a VPD policy in a standard SQL query, and to perform a multi-model query on a combination of VPD-enabled models and models with no VPD policy. However, when more than one model in a multi-model query is VPD-enabled, they must all be associated with the same VPD policy. A VPD policy associated with an RDF model is automatically extended to any data inferred from the model. When multiple RDF models are specified during inference, all VPD-enabled models within the set should use the same VPD policy.
The types of RDF metadata used to enforce VPD policies include the following:
Domain and range information for the properties used in the graph
Subclass relationships in the graph
Subproperty relationships in the graph
Equivalent properties in the graph
The RDF metadata associated with a VPD policy is specified as one or more RDF Schema statements using one of the following property URIs:
http://www.w3.org/2000/01/rdf-schema#domain
http://www.w3.org/2000/01/rdf-schema#range
http://www.w3.org/2000/01/rdf-schema#subClassOf
http://www.w3.org/2000/01/rdf-schema#subPropertyOf
http://www.w3.org/2002/07/owl#equivalentProperty
For example, the following RDF Schema statement associated with contracts_policy asserts that the domain of the hasContractValue property is a Contract class. Note that range specification for the predicates can be skipped if they are not relevant or if they are of literal type
begin
sem_rdfsa.maint_vpd_metadata(
policy_name => 'contracts_policy',
t_subject => '<http://www.myorg.com/pred/hasContractValue>',
t_predicate => '<http://www.w3.org/2000/01/rdf-schema#domain>',
t_object => '<http://www.myorg.com/classes/Contract>');
end;
/
An RDF-VPD policy maintains its metadata separate from the asserted and inferred triples. You can derive this metadata programmatically from the RDF models and the corresponding entailments. For example, if the domain and range information for the properties and subclass and subproperty relationships are already established in the asserted or inferred triples, you can use a SQL query on the underlying model views to populate the metadata for an RDF-VPD policy.
The domain and range information for the properties aid the query analysis in determining the RDF class type for the terms and unbound variables referenced in the query. This information is further used to enforce appropriate data access constraints on the data accessed by the query. The metadata relating to the subclass property is used to ensure that a data access constraint defined for a specific class in a class hierarchy is automatically enforced for all its subclasses. Similarly, the subproperty specification in a VPD policy is used to enforce any constraints associated with a property to all its subproperties.
The RDF Schema statements associated with a VPD policy are not used to infer additional statements, and the security administrator should ensure that the metadata captured in a VPD policy is complete by cross checking it with inferred data. For example, a subproperty schema statement does not automatically infer the domain and range information for the property based on the domain and range specified for the super-property.
Certain owl and rdfs properties in the asserted triples, when left unchecked, may be used to infer data that may be used to circumvent the VPD policies. For example, when the new property is defined as a super-property of a property that has a specific data access constraint, the inferred data may duplicate all instances of the subproperty using the super-property. Unless the VPD policy explicitly defines access constraints for the super-property, the inferred data may be used to circumvent the access restrictions.
The ability to infer new data is only granted to users with FULL access, and such users should ensure that the metadata associated with the VPD policy is complete in light of newly inferred data. Specifically, the metadata associated with the VPD policy should be maintained if some new rdfs:subClassOf, rdfs:superClassOf, rdfs:subPropertyOf, rdfs:superPropertyOf, or owl:equivalentProperty assertions are generated during inference. Also, any new properties introduced by the rulebases used for inference may need domain and range specifications, as well as data access constraints, if they are associated with some sensitive information.
In a VPD policy, a property can be declared to be equivalent to another property so that the domain and range information, as well as any constraints defined for the original property, are automatically duplicated for the equivalent property. However, within a VPD policy, additional metadata or data access constraints cannot be directly assigned to the property declared to be an equivalent of another property.
The data access constraints associated with a VPD policy fall into two general categories, based on the types of access restrictions that they enforce:
Those that restrict access to instances of specific RDF classes
Those that restrict to assertions using specific RDF properties
The access restrictions are enforced conditionally, based on the application context and the characteristics of the resources being accessed in a SPARQL query. Data access constraints restrict access to instances of an RDF class or property using some properties associated with the resource. For example, access to a resource that is a member of the Contract class may be restricted only to the users who work on the contract, identified using the hasMember property associated with the resource. Similarly, access to the hasContractValue property for a resource may be restricted to a user identified as the manager of the contract using hasManager property associated with the same resource.
Each data access constraint is expressed using two graph patterns identified as a match pattern and an apply pattern. The match pattern of a constraint determines the type of access restriction it enforces and binds one or more variables to the corresponding data instances accessed in the user query. For example, the following match pattern is defined for instances of the Contract class, and it binds a variable to all such instances accessed through a SPARQL query:
{ ?contract rdf:type <http://www.myorg.com/classes/Contract> }
Similarly, a match pattern for a constraint involving an RDF property matches the instances of the property accessed in a SPARQL query, and binds two variables to the resources in the subject and object position of such instances. For example, the match pattern for a constraint on the hasContractValue property is defined as follows:
{ ?contract <http://www.myorg.com/pred/hasContractValue> ?cvalue }
The apply pattern of a data access constraint defines additional graph patterns to be applied on the resources that match the match pattern before they can be used to construct the query results. One or more variables defined in the match pattern of a data access constraint are used in the corresponding apply pattern to enforce the access restrictions on the identified resources. For example, the following match pattern and apply pattern combination ensures that the hasContractValue of a contract can be accessed only if Andy is the manager of the contract being accessed.:
Match: { ?contract pred:hasContractValue ?cvalue }
Apply: { ?contract pred:hasManager emp:Andy }
A data access constraint with its match and apply patterns expressed in SPARQL syntax can be added to a VPD policy to enforce access restrictions on the data stored in RDF models that are associated with the VPD policy. The following example, which adds a constraint to the VPD policy, assumes that the VPD policy is defined with appropriate namespace map for the pred and emp namespace prefixes. (To associate a namespace map with a VPD policy, use the SEM_RDFSA.CREATE_VPD_POLICY procedure.)
begin
sem_rdfsa.add_vpd_constraint(
policy_name => 'contracts_policy',
constr_name => 'andy_constraint_1',
match_pattern => '{?contract pred:hasContractValue ?cvalue }',
apply_pattern => '{?contract pred:hasManager emp:Andy }',
constr_group => 'andy');
end;
/
The ability to arrange data access constraints into groups could ensure that the previous constraint is applied only for the sessions associated with Andy. However, to avoid proliferation of structurally similar constraints for each user, you can define a common constraint that uses the application context in the object position of the apply graph patterns, as shown in the following example:
begin
sem_rdfsa.add_vpd_constraint(
policy_name => 'contracts_policy',
constr_name => 'manager_constraint_1',
match_pattern => '{?contract pred:hasContractValue ?cvalue }',
apply_pattern => '{?contract pred:hasManager
"sys_context(''sa$appctx'',''app_user_uri''}"^^orardf:instruction }',
constr_group => 'manager');
end;
/
In the preceding example. the data access constraint, defined within the manager constraint group, can be activated for all sessions involving users with a manager role. In this case, the secure application context can be programmed to initialize the attribute app_user_uri of the sa$appctx namespace with the URI for the user logged in. For example, when user Andy logs into the application, the app_user_uri attribute can be initialized to <http://www.myorg.com/employee/Andy>, in which case the constraint will ensure that user Andy can view the value for a contract only if user Andy manages the contract. Generally, the sys_context function can be used in the object position of any graph pattern to allow dynamic URIs or literal values to be bound at the time of query execution. Note that if the context is not initialized properly, the preceding constraint will fail for all data instances and effectively restrict the user from accessing any data.
A SPARQL query issued on an RDF model with a VPD policy is analyzed using the match patterns of all the active data access constraints that are defined in the policy. In the next example, the SPARQL query refers to the hasContractValue property, thereby enforcing the constraint if the group is active. Logically, the enforcement of a constraint is equivalent to rewriting the original SPARQL graph pattern to include the apply patterns for all the relevant constraints, using appropriate variables and terms from the user query. With the previous access restriction on the hasContractValue property, the following SPARQL graph pattern passed to a SEM_MATCH operator is logically rewritten as shown in the following example:
Query:
{ ?contr pred:drivenBy ?dept .
?contr pred:hasContractValue ?val }
Rewritten query:
{ ?contr pred:drivenBy ?dept .
?contr pred:hasContractValue ?val .
?contr pred:hasManager
"sys_context('sa$appctx','app_user_uri'}"^^orardf:instruction }
When the match pattern of a data access constraint on an RDF property matches the pattern being accessed in a user query, the equivalent VPD-enforced query appends the corresponding apply patterns to the SPARQL query using the variables and terms appearing in the matched pattern. When a SPARQL query has nested graph patterns, the data access constraints are applied to appropriate basic query graph pattern block. In the following example, the hasContractValue property is referenced in the OPTIONAL graph pattern, and therefore the corresponding apply pattern is enforced just for this block of the graph pattern.
Query:
{ ?contr pred:drivenBy ?dept .
OPTIONAL { ?contr pred:hasContractValue ?val } }
Rewritten query:
{ ?contr pred:drivenBy ?dept .
OPTIONAL { ?contr pred:hasContractValue ?val .
?contr pred:hasManager
"sys_context('sa$appctx','app_user_uri'}"^^orardf:instruction }
The apply pattern for a data access constraint can be any valid basic graph pattern with multiple triple patterns and a FILTER clause. For example, the access constraint on the hasContractValue property for a user with VP role may stipulate that the user can access the property only if he or she is the Vice President of the department driving the contract. The match and apply patterns for such constraint can be defined as follows:
Match: { ?contract pred:hasContractValue ?cvalue }
Apply: { ?contract pred:drivenBy ?dept .
?dept pred:hasVP
"sys_context('sa$appctx','app_user_uri'}"^^orardf:instruction }
A match pattern defined for a data access constraint associated with an RDF class identifies all variables and terms that are known to be instances of the class. The RDF metadata defined in the VPD policy is used to determine the type for each variable and the term in a SPARQL query, and the appropriate access constraints are applied on these variables and terms. For example, the following VPD constraint ensures that a resource that is a member of the Contract class can only be accessed by a user who has a hasMember relationship with the resource:
Match: { ?contract rdf:type <http://www.myorg.com/classes/Contract> }
Apply: { ?contract pred:hasMember
"sys_context('sa$appctx','app_user_uri'}"^^orardf:instruction }
The class information for a variable or term appearing in a SPARQL query is derived using the domain and range information for the properties appearing in the query. In the SPARQL query in the next example, if the VPD policy has an RDF Schema statement that asserts that the domain of the drivenBy property is the Contract class, the variable ?contr is known to hold instances of the Contract class. Therefore, with the previously defined access restriction for the Contract class, the user query is rewritten to include an appropriate apply pattern, as shown in the following example:
Query:
{ ?contr pred:drivenBy ?dept .
?contr pred:hasDueDate ?due }
Rewritten query:
{ ?contr pred:drivenBy ?dept .
?contr pred:hasDueDate ?due .
?contr pred:hasMember
"sys_context('sa$appctx','app_user_uri'}"^^orardf:instruction }
When a basic graph pattern in a SPARQL query matches multiple data access constraints, the corresponding apply patterns are combined to form a conjunctive graph pattern, which is subsequently enforced for the specific graph pattern by logically rewriting the SPARQL query. While considering the data access constraints to be enforced for a given SPARQL query, the class and property hierarchy associated with the VPD policy is consulted to automatically enforce all applicable constraints.
A variable or term identified as an instance of a specific RDF class enforces constraints associated with the class and all its superclasses.
A constraint associated with a property is enforced when the user query references the property or any property defined as its subproperty or an equivalent property.
You can use the sys_context function in a data access constraint to enforce context-dependent access restrictions with structurally similar graph patterns. You can dynamically activate and deactivate constraint groups, based on the application context, to enforce alternate access restrictions using structurally different graph patterns.
The MDSYS.RDFVPD_POLICIES view contains information about all VPD policies defined in the schema or the policies to which the user has FULL access. If the same policy is associated with multiple models, this view has one entry for each such association. This view exists only after the semantic network and a VPD policy have been created.
The MDSYS.RDFVPD_POLICIES view contains the columns shown in Table 5-1.
Table 5-1 MDSYS.RDFVPD_POLICIES View Columns
| Column Name | Data Type | Description |
|---|---|---|
|
POLICY_OWNER |
VARCHAR2(32) |
Owner of the VPD policy. |
|
POLICY_NAME |
VARCHAR2(32) |
Name of the VPD policy. |
|
NAMESPACE_MAP |
RDF_ALIASES |
Mapping for namespace entries that are used in the VPD constraint definitions. |
|
CONTEXT_NAME |
VARCHAR2(32) |
Name of the context used to manage constraint groups. |
The MDSYS.RDFVPD_MODELS view contains information about RDF models and their associated VPD policies. This view exists only after the semantic network and a VPD policy have been created.
The MDSYS.RDFVPD_MODELS view contains the columns shown in Table 5-2.
Table 5-2 MDSYS.RDFVPD_MODELS View Columns
| Column Name | Data Type | Description |
|---|---|---|
|
MODEL_NAME |
VARCHAR2(25) |
Name of the model. |
|
POLICY_OWNER |
VARCHAR2(32) |
Owner of the VPD policy. |
|
POLICY_NAME |
VARCHAR2(32) |
Name of the VPD policy. |
|
OPERATION_TYPE |
VARCHAR2(9) |
Type of operation for which the VPD policy is enforced: |
The MDSYS.RDFVPD_POLICY_CONSTRAINTS view contains information about the constraints defined in the VPD policy that are accessible to the current user. This view exists only after the semantic network and a VPD policy have been created.
The MDSYS.RDFVPD_POLICY_CONSTRAINTS view contains the columns shown in Table 5-3.
Table 5-3 MDSYS.RDFVPD_POLICY_CONSTRAINTS View Columns
| Column Name | Data Type | Description |
|---|---|---|
|
POLICY_OWNER |
VARCHAR2(32) |
Owner of the VPD policy. |
|
POLICY_NAME |
VARCHAR2(32) |
Name of the VPD policy. |
|
CONSTRAINT_NAME |
VARCHAR2(32) |
Name of the constraint. |
|
MATCH_PATTERN |
VARCHAR2(1000) |
Match pattern for the constraint. |
|
APPLY_PATTERN |
VARCHAR2(4000) |
Apply pattern for the constraint. |
|
CONSTRAINT_GROUP |
VARCHAR2(32) |
Name of the constraint group to which the constraint belongs. (Not case-sensitive.). |
The MDSYS.RDFVPD_PREDICATE_MDATA view contains information about the predicate metadata associated with a VPD policy. This view exists only after the semantic network and a VPD policy have been created.
The MDSYS.RDFVPD_PREDICATE_MDATA view contains the columns shown in Table 5-4.
Table 5-4 MDSYS.RDFVPD_PREDICATE_MDATA View Columns
| Column Name | Data Type | Description |
|---|---|---|
|
POLICY_OWNER |
VARCHAR2(32) |
Owner of the VPD policy. |
|
POLICY_NAME |
VARCHAR2(32) |
Name of the VPD policy. |
|
PREDICATE |
VARCHAR2(4000) |
URI for the predicate for which the domain and range information is defined. |
|
HASDOMAIN |
VARCHAR2(4000) |
URI representing the domain of the predicate. |
|
HASRANGE |
VARCHAR2(4000) |
URI representing the range of the predicate. |
The MDSYS.RDFVPD_RESOURCE_REL view contains information about the subclass, subproperty, and equivalence property relationships that are defined between resources in a VPD policy. This view exists only after the semantic network and a VPD policy have been created.
The MDSYS.RDFVPD_RESOURCE_REL view contains the columns shown in Table 5-5.
Table 5-5 MDSYS.RDFVPD_RESOURCE_REL View Columns
| Column Name | Data Type | Description |
|---|---|---|
|
POLICY_OWNER |
VARCHAR2(32) |
Owner of the VPD policy. |
|
POLICY_NAME |
VARCHAR2(32) |
Name of the VPD policy. |
|
SUBJECT_RESOURCE |
VARCHAR2(4000) |
Subject resource. |
|
OBJECT_RESOURCE |
VARCHAR2(4000) |
Object resource. |
|
RELATIONSHIP_TYPE |
VARCHAR2(4000) |
Relationship that exists between the subject resource and the object resource. |
Oracle Label Security (OLS) for RDF data provides two options for securing semantic data:
Triple-level security (explained in Section 5.2.1), which is highly recommended for its performance and ease of use, but requires that a patch be installed
Resource-level security (explained in Section 5.2.2)
To specify an option, use the SEM_RDFSA.APPLY_OLS_POLICY procedure with the appropriate rdfsa_options parameter value.
To switch from one option to the other, remove the existing policy by using the SEM_RDFSA.REMOVE_OLS_POLICY procedure, and then apply the new policy by using the SEM_RDFSA.APPLY_OLS_POLICY procedure with the appropriate rdfsa_options parameter value.
The triple-level security option provides a thin layer of RDF-specific capabilities on top of the Oracle Database native support for label security. This option provides better performance and is easier to use than the resource-level security (described in Section 5.2.2), especially for performing inference while using OLS. The main difference is that with triple-level security there is no need to assign labels, explicitly or implicitly, to individual triple resources (subjects, properties, objects).
|
Note: To use triple-level security, you must first install Patch 9819833 SEMANTIC TECHNOLOGIES 11G R2 FIX BUNDLE 2 (available from My Oracle Support). |
To use triple-level security, specify SEM_RDFSA.TRIPLE_LEVEL_ONLY as the rdfsa_options parameter value when you execute the SEM_RDFSA.APPLY_OLS_POLICY procedure. For example:
EXECUTE sem_rdfsa.apply_ols_policy('defense', SEM_RDFSA.TRIPLE_LEVEL_ONLY);
Do not specify any of the other available parameters for the SEM_RDFSA.APPLY_OLS_POLICY procedure.
When you use triple-level security, OLS is applied to each semantic model in the network. That is, label security is applied to the relevant internal tables and to all the application tables; there is no need to manually apply policies to the application tables of existing semantic models. However, if you need to create additional models after applying the OLS policy, you must use the SEM_OLS.APPLY_POLICY_TO_APP_TAB procedure to apply OLS to the application table before creating the model. Similarly, if you have dropped a semantic model and you no longer need to protect the application table, you can use the SEM_OLS.REMOVE_POLICY_FROM_APP_TAB procedure. (These procedures are described in Chapter 10.)
With triple-level security, duplicate triples with different labels can be inserted in the semantic model. (Such duplicates are not allowed with resource-level security.) For example, assume that you have a triple with a very sensitive label, such as:
(<urn:X>,<urn:P>,<urn:Y>, "TOPSECRET")
This does not prevent a low-privileged (UNCLASSIFIED) user from inserting the triple (<urn:X>,<urn:P>,<urn:Y>, "UNCLASSIFIED"). Because SPARQL and SEM_MATCH do not return label information, a query will return both rows (assuming the user has appropriate privileges), and it will not be easy to distinguish between the TOPSECRET and UNCLASSIFIED triples.
To filter out such low-security triples when querying the semantic models, you can one or more the following options with SEM_MATCH:
POLICY_NAME specifies the OLS policy name.
MIN_LABEL specifies the minimum label for triples that are included in the query
In other words, every triple that contains a label that is strictly dominated by MIN_LABEL is not included in the query. For example, to filter out the "UNCLASSIFIED" triple, you could use the following query (assuming the OLS policy name is DEFENSE and that the query user has read privileges over UNCLASSIFIED and TOPSECRET triples):
SELECT s,p,y FROM table(sem_match('{?s ?p ?y}' ,
sem_models(TEST'), null, null, null, null,
'MIN_LABEL=TOPSECRET POLICY_NAME=DEFENSE'));
Note that the filtering in the preceding example occurs in addition to the security checks performed by the native OLS software.
After a triple has been inserted, you can view and update the label information can be done through the CTXT1 column in the application table for the semantic model (assuming that you have the WRITEUP and WRITEDOWN privileges to modify the labels).
There are no restrictions on who can perform inference or bulk loading with triple-level security; all of the inferred or bulk loaded triples are inserted with the user's session row label. Note that you can change the session labels by using the SA_UTL package. (For more information, see Oracle Label Security Administrator's Guide.)
The resource-level security option enables you to assign one or more security labels that define a security level for table rows. Conceptually, a table in a relational data model can be mapped to an equivalent RDF graph. Specifically, a row in a relational table can be mapped to a set of triples, each asserting some facts about a specific Subject. In this scenario, the subject represents the primary key for the row and each non-key column-value combination from the row is mapped to a predicate-object value combination for the corresponding triples.
A row in a relational data model is identified by its key, and OLS, as a row-level access control mechanism, effectively restricts access to the values associated with the key. With this conceptual mapping between relational and RDF data models, restricting access to a row in a relational table is equivalent to restricting access to a subgraph involving a specific subject. In a model that supports sensitivity labels for each triple, this is enforced by applying the same label to all the triples involving the given subject. However, you can also achieve greater flexibility by allowing the individual triples to have different labels, while maintaining a minimum bound for all the labels.
OLS support for RDF data employs a multilevel approach in which sensitivity labels associated with the triple components (subject, predicate, object) collectively form a minimum bound for the sensitivity label for the triple. With this approach, a data sensitivity label associated with an RDF resource (used as subject, predicate, or object) restricts unauthorized users from accessing any triples involving the resource and from creating new triples with the resource. For example, projectHLS as a subject may have a minimum sensitivity label, which ensures that all triples describing this subject have a sensitivity label that at least covers the label for projectHLS. Additionally, hasContractValue as a predicate may have a higher sensitivity label; and when this predicate is used with projectHLS to form a triple, that triple minimally has a label that covers both the subject and the predicate labels, as in the following example:
Triple 1: <http://www.myorg.com/contract/projectHLS> :ownedBy <http://www.myorg.com/department/Dept1> Triple 2: <http://www.myorg.com/contract/projectHLS> :hasContractValue "100000"^^xsd:integer
Sensitivity labels are associated with the RDF resources (URIs) based on the position in which they appear in a triple. For example, the same RDF resource may appear in different positions (subject, predicate, or object) in different triples. Three unique labels can be assigned to each resource, so that the appropriate label is used to determine the label for a triple based on the position of the resource in the triple. You can choose the specific resource positions to be secured in a database instance when you apply an OLS policy to the RDF repository. You can secure subjects, objects, predicates, or any combination, as explained in separate sections to follow. The following example applies an OLS policy named defense to the RDF repository and allows sensitivity labels to be associated with RDF subjects and predicates.
begin
sem_rdfsa.apply_ols_policy(
policy_name => 'defense',
rdfsa_options => sem_rdfsa.SECURE_SUBJECT+
sem_rdfsa.SECURE_PREDICATE);
end;
/
The same RDF resource can appear in both the subject and object positions (and sometime even as the predicate), and such a resource can have distinct sensitivity labels based on its position. A triple using the resource at a specific position should have a label that covers the label corresponding to the resource's position. In such cases, the triple can be asserted or accessed only by the users with labels that cover the triple and the resource labels.
In a specific RDF repository, security based on data classification techniques can be turned on for subjects, predicates, objects, or a combination of these. This ensures that all the triples added to the repository automatically conform to the label relationships described above.
An RDF resource (typically a URI) appears in the subject position of a triple when an assertion is made about the resource. In this case, a sensitivity label associated with the resource has following characteristics:
The label represents the minimum sensitivity label for any triple using the resource as a subject. In other words, the sensitivity label for the triple should dominate or cover the label for the subject.
The label for a newly added triple is initialized to the user initial row label or is generated using the label function, if one is specified. Such operations are successful only if the triple's label dominates the label associated with the triple's subject.
Only a user with an access label that dominates the subject's label and the triple's label can read the triple.
By default, the sensitivity label for a subject is derived from the user environment when an RDF resource is used in the subject position of a triple for the first time. The default sensitivity label in this case is set to the user's initial row label (the default that is assigned to all rows inserted by the user).
However, you can categorize an RDF resource as a subject and assign a sensitivity label to it even before it is used in a triple. The following example assigns a sensitivity label named SECRET:HLS:US to the projectHLS resource, thereby restricting the users who are able to define new triples about this resource and who are able to access existing triples with this resource as the subject:
begin
sem_rdfsa.set_resource_label(
model_name => 'contracts',
resource_uri => '<http://www.myorg.com/contract/projectHLS>',
label_string => 'SECRET:HLS:US',
resource_pos => 'S');
end;
An RDF predicate defines the relationship between a subject and an object. You can use sensitivity labels associated with RDF predicates to restrict access to specific types of relationships with all subjects.
RDF predicates are analogous to columns in a relational table, and the ability to restrict access to specific predicates is equivalent to securing relational data at the column level. As in the case of securing the subject, the predicate's sensitivity label creates a minimum bound for any triples using this predicate. It is also the minimum authorization that a user must posses to define a triple with the predicate or to access a triple with the predicate.
The following example assigns the label HSECRET:FIN (in this scenario, a label that is Highly Secret and that also belongs to the Finance department) to triples with the hasContractValue predicate, to ensure that only a user with such clearance can define the triple or access it:
begin
sem_rdfsa.set_predicate_label(
model_name => 'contracts',
predicate => '<http://www.myorg.com/pred/hasContractValue>',
label_string => 'HSECRET:FIN');
end;
/
You can secure predicates in combination with subjects. In such cases, the triples using a subject and a predicate are ensured to have a sensitivity label that at least covers the labels for both the subject and the predicate. Extending the preceding example, if projectHLS as a subject is secured with label SECRET:HLS:US and if hasContractValue as a predicate is secured with label HSECRET:MFIN:, a triple assigning a monetary value for projectHLS should at least have a label HSECRET:HLS,FIN:US. Effectively, a user's label must dominate this triple's label to be able to define or access the triple.
An RDF triple can have an URI or a literal in its object position. The URI in object position of a triple represents some resource. You can secure a resource in the object position by associating a sensitivity label to it, to restrict the ability to use the resource as an object in triples.
Typically, a resource (URI or non-literal) appearing in the object position of a triple may itself be described using additional RDF statements. Effectively, an RDF resource in the object position could appear in the subject position in some other triples. When the RDF resources are secured at the object position without explicit sensitivity labels, the label associated with the same resource in the subject position is used as the default label for the object.
RDF data model allows for specification of declarative rules, enabling it to infer the presence of RDF statements that are not explicitly added to the repository. The following shows some simple declarative rules associated with the logic that projects can be owned by departments and departments have Vice Presidents, and in such cases the project leader is by default the Vice President of the department that owns the project.
RuleID -> projectLedBy Antecedent Expression -> (?proj :ownedBy ?dept) (?dept :hasVP ?person) Consequent Expression -> (?proj :isLedBy ?person)
An RDF rule uses some explicitly asserted triples as well as previously inferred triples as antecedents, and infers one or more consequent triples. Traditionally, the inference process is executed as an offline operation to pregenerate all the inferred triples and to make them available for subsequent query operations.
When the underlying RDF graph is secured using OLS, any additional data inferred from the graph should also be secured to avoid exposing the data to unauthorized users. Additionally, the inference process should run with higher privileges, specifically with full access to data, in order to ensure completeness.
OLS support for RDF data offers techniques to generate sensitivity labels for inferred triples based on labels associated with one or more RDF artifacts. It provides label generation techniques that you can invoke at the time of inference. Additionally, it provides an extensibility framework, which allows an extensible implementation to receive a set of possible labels for a specific triple and determine the most appropriate sensitivity label for the triple based on some application-specific logic. The techniques that you can use for generating the labels for inferred triples include the following (each technique, except for Use Antecedent Labels, is associated with a SEM_RDFSA package constant):
Use Rule Label (SEM_RDFSA.LABELGEN_RULE): An inferred triple is directly generated by a specific rule, and it may be indirectly dependent on other rules through its antecedents. Each rule may have a sensitivity label, which is used as the sensitivity label for all the triples directly inferred by the rule.
Use Subject Label (SEM_RDFSA.LABELGEN_SUBJECT): Derives the label for the inferred triple by considering any sensitivity labels associated with the subject in the new triple. Each inferred triple has a subject, which could in turn be a subject, predicate, or object in any of the triple's antecedents. When such RDF resources are secured, the subject in the newly inferred triple may have one or more labels associated with it. With the Use Subject Label technique, the label for the inferred triple is set to the unique label associated with the RDF resource. When more than one label exists for the resource, you can implement the extensible logic to determine the most relevant label for the new triple.
Use Predicate Label (SEM_RDFSA.LABELGEN_PREDICATE): Derives the label for the inferred triple by considering any sensitivity labels associated with the predicate in the new triple. Each inferred triple has a predicate, which could in turn be a subject, predicate, or object in any of the triple's antecedents. When such RDF resources are secured, the predicate in the newly inferred triple may have one or more labels associated with it. With the Use Predicate Label technique, the label for the inferred triple is set to the unique label associated with the RDF resource. When more than one label exists for the resource, you can implement the extensible logic to determine the most relevant label for the new triple.
Use Object Label (SEM_RDFSA.LABELGEN_OBJECT): Derives the label for the inferred triple by considering any sensitivity labels associated with the object in the new triple. Each inferred triple has an object, which could in turn be a subject, predicate, or object in any of the triple's antecedents. When such RDF resources are secured, the object in the newly inferred triple may have one or more labels associated with it. With the Use Object Label technique, the label for the inferred triple is set to the unique label associated with the RDF resource. When more than one label exists for the resource, you can implement the extensible logic to determine the most relevant label for the new triple.
Use Dominating Label (SEM_RDFSA.LABELGEN_DOMINATING): Each inferred triple minimally has four direct components: subject, predicate, object, and the rule that produced the triple. With the Use Dominating Label technique, at the time of inference the label generator computes the most dominating of the sensitivity labels associated with each of the component and assigns it as the sensitivity label for the inferred triple. Exception labels are assigned when a clear dominating relationship cannot be established between various labels.
Use Antecedent Labels: In addition to the four direct components for each inferred triple (subject, predicate, object, and the rule that produced the triple), a triple may have one or more antecedent triples, which are instrumental in deducing the new triple. With the Use Antecedent Labels technique, the labels for all the antecedent triples are considered, and conflict resolution criteria are implemented to determine the most appropriate label for the new triple. Since an inferred triple may be dependent on other inferred triples, a strict order is followed while generating the labels for all the inferred triples.
The Use Antecedent Labels technique requires that you use a custom label generator. For information about creating and using a custom label generator, see Section 5.2.2.5.
The following example creates an entailment (rules index) for the contracts data using a specific rule base. This operation can only be performed by a user with FULL access privilege with the OLS policy applied to the RDF repository. In this case, the labels generated for the inferred triples are based on the labels associated with their predicates, as indicated by the use of the SEM_RDFSA.LABELGEN_PREDICATE package constant in the label_gen parameter.
begin
sem_rdfsa.create_entailment(
index_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;
When the predefined or extensible label generation implementation cannot compute a unique label to be applied to an inferred triple, an exception label is set for the triple. Such triples are not accessible by any user other than the user with full access to RDF data (also the user initiating the inference process). The triples with exception labels are clearly marked, so that a privileged user can access them and apply meaningful labels manually. After the sensitivity labels are applied to inferred triples, only users with compatible labels can access these triples. The following example updates the sensitivity label for triples for which an exception label was set:
update mdsys.rdfi_contracts_inf
set ctxt1 = char_to_label('defense', 'SECRET:HLS:US')
where ctxt1 = -1;
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 system-defined or custom implementations cannot be guaranteed to be precise. See the information about Fine-Grained Access Control (VPD and OLS) Considerations in the Usage Notes for the SEM_APIS.CREATE_ENTAILMENT procedure in Chapter 9 for details.
The MDSYS.RDFSA_LABELGEN type is used to apply appropriate label generator logic at the time of index creation; however, you can also extend this type to implement a custom label generator and generate labels based on application logic. The label generator is specified using the label_gen parameter with the SEM_APIS.CREATE_ENTAILMENT procedure. To use a system-defined label generator, specify a SEM_RDFSA package constant, as explained in Section 5.2.2.4; to use a custom label generator, you must implement a custom label generator type and specify an instance of that type instead of a SEM_RDFSA package constant.
To create a custom label generator type, you must have the UNDER privilege on the RDFSA_LABELGEN type. In addition, to create an index for RDF data , you must should have the EXECUTE privilege on this type. The following example grants these privileges to a user named RDF_ADMIN:
GRANT under, execute ON mdsys.rdfsa_labelgen TO rdf_admin;
The custom label generator type must implement a constructor, which should set the dependent resources and specify the getNumericLabel method to return the label computed from the information passed in, as shown in the following example:
CREATE OR REPLACE TYPE CustomSPORALabel UNDER mdsys.rdfsa_labelgen (
constructor function CustomSPORALabel return self as result,
overriding member function getNumericLabel (
subject rdfsa_resource,
predicate rdfsa_resource,
object rdfsa_resource,
rule rdfsa_resource,
anteced rdfsa_resource)
return number);
The label generator constructor uses a set of constants defined in the SEM_RDFSA package to indicate the list of resources on which the label generator relies. The dependent resources are identified as an inferred triple's subject, its predicate, its object, the rule that produced the triple, and its antecedents. A custom label generator can rely on any subset of these resources for generating the labels, and you can specify this in its constructor by using the constants defined in SEM_RDFSA package : USE_SUBJECT_LABEL, USE_PREDICATE_LABEL, USE_OBJECT_LABEL, USE_RULE_LABEL, USE_ANTCED_LABEL. The following example creates the type body and specifies the constructor:
Example 5-1 creates the type body, specifying the constructor function and the getNumericLabel member function. (Application-specific logic is not included in this example.)
Example 5-1 Creating a Custom Label Generator Type
CREATE OR REPLACE TYPE BODY CustomSPORALabel AS
constructor function CustomSPORALabel return self as result as
begin
self.setDepResources(sem_rdfsa.USE_SUBJECT_LABEL+
sem_rdfsa.USE_PREDICATE_LABEL+
sem_rdfsa.USE_OBJECT_LABEL+
sem_rdfsa.USE_RULE_LABEL+
sem_rdfsa.USE_ANTECED_LABELS);
return;
end CustomSPORALabel;
overriding member function getNumericLabel (
subject rdfsa_resource,
predicate rdfsa_resource,
object rdfsa_resource,
rule rdfsa_resource,
anteced rdfsa_resource)
return number as
labellst mdsys.int_array := mdsys.int_array();
begin
-- Find dominating label of S P O R A –
–- Application specific logic for computing the triple label –
-- Copy over all labels to labellst --
for li in 1 .. subject.getLabelCount() loop
labellst.extend;
labellst(labellst.COUNT) = subject.getLabel(li);
end loop;
--- Copy over other labels as well ---
--- Find a dominating of all the labels. Generates –1 if no
--- dominating label within the set
return self.findDominatingOf(labellst);
end getNumericLabel;
end CustomSPORALabel;
/
In Example 5-1, the sample label generator implementation uses all the resources contributing to the inferred triple for generating a sensitivity label for the triple. Thus, the constructor uses the setDepResources method defined in the superclass to set all its dependent components. The list of dependent resources set with this step determines the exact list of values passed to the label generating routine.
The getNumericLabel method is the label generation routine that has one argument for each resource that an inferred triple may depend on. Some arguments may be null values if the corresponding dependent resource is not set in the constructor implementation.
The label generator implementation can make use of a general-purpose static routine defined in the RDFSA_LABELGEN type to find a domination label for a given set of labels. A set of labels is passed in an instance of MDSYS.INT_ARRAY type, and the method finds a dominating label among them. If no such label exists, an exception label –1 is returned.
After you have implemented the custom label generator type, you can use the custom label generator for inferred data by assigning an instance of this type to the label_gen parameter in the SEM_APIS.CREATE_ENTAILMENT procedure, as shown in the following example:
begin
sem_apis.create_entailment(
index_name_in => 'contracts_rdfsinf',
models_in => SDO_RDF_Models('contracts'),
rulebases_in => SDO_RDF_Rulebases('RDFS'),
options => '',
label_gen => CustomSPORALabel());
end;
/
The MDSYS.RDFOLS_SECURE_RESOURCE view contains information about resources secured with Oracle Label Security (OLS) policies and the sensitivity labels associated with these resources.
Select privileges on this view can be granted to appropriate users. To view the resources associated with a specific model, you must also have select privileges on the model (or the corresponding RDFM_model-name view).
The MDSYS.RDFOLS_SECURE_RESOURCE view contains the columns shown in Table 5-6.
Table 5-6 MDSYS.RDFOLS_SECURE_RESOURCE View Columns
| Column Name | Data Type | Description |
|---|---|---|
|
MODEL_NAME |
VARCHAR2(25) |
Name of the model. |
|
MODEL_ID |
NUMBER |
Internal identifier for the model. |
|
RESOURCE_ID |
NUMBER |
Internal identifier for the resource; to be joined with MDSYS.RDF_VALUE$.VALUE_ID column for information about the resource. |
|
RESOURCE_TYPE |
VARCHAR2(16) |
One of the following string values to indicate the resource type for which the label is assigned: |
|
CTXT1 |
NUMBER |
Sensitivity label assigned to the resource. |
The SEM_PERF package contains subprograms for examining and enhancing the performance of the Resource Description Framework (RDF) and Web Ontology Language (OWL) support in an Oracle database. To use the subprograms in this chapter, you must understand the conceptual and usage information in Chapter 1, "Oracle Database Semantic Technologies Overview" and Chapter 2, "OWL Concepts".
This chapter provides reference information about the subprograms, listed in alphabetical order.
Format
SEM_PERF.GATHER_STATS();
just_on_values_table IN BOOLEAN DEFAULT FALSE,
degree IN NUMBER(38) DEFAULT NULL);
Description
Gathers statistics about RDF and OWL tables and their indexes.
Parameters
TRUE collects statistics only on the table containing the lexical values of triples; FALSE (the default) collects statistics on all major tables related to the storage of RDF and OWL data.
A value of TRUE reduces the execution time for the procedure; and it may be sufficient if you need only to collect statistics on the values table (for example, if you use other interfaces to collect any other statistics that you might need).
Degree of parallelism. For more information about parallel execution, see Oracle Database VLDB and Partitioning Guide.
Usage Notes
To use this procedure, you must connect as a user with permission to execute it. By default, when Spatial is installed as part of Oracle Database, only the MDSYS user can execute this procedure; however execution permission on this procedure can be granted to users as needed.
This procedure collects statistical information that can help you to improve inferencing performance, as explained in Section 2.2.7. This procedure internally calls the DBMS_STATS.GATHER_TABLE_STATS procedure to collect statistics on RDF- and OWL-related tables and their indexes, and stores the statistics in the Oracle Database data dictionary. For information about using the DBMS_STATS package, see Oracle Database PL/SQL Packages and Types Reference.
Gathering statistics uses significant system resources, so execute this procedure when it cannot adversely affect essential applications and operations.
Examples
The following example gathers statistics about RDF and OWL related tables and their indexes.
EXECUTE SEM_PERF.GATHER_STATS;
You can perform inferencing based on a core subset of the Simple Knowledge Organization System (SKOS) data model, which is especially useful for representing thesauri, classification schemes, taxonomies, and other types of controlled vocabulary. SKOS is based on standard semantic web technologies including RDF and OWL, which makes it easy to define the formal semantics for those knowledge organization systems and to share the semantics across applications.
Support is provided for most, but not all, of the features of SKOS, the detailed specification of which is available at http://www.w3.org/TR/skos-reference/.
Around 40 SKOS-specific terms are included in the Oracle Database semantic technologies support, such as skos:broader, skos:relatedMatch, and skos:Concept. Over 100 SKOS axiomatic triples have been added, providing the basic coverage of SKOS semantics. However, support is not included for the integrity conditions described in the SKOS specification.
To perform SKOS-based inferencing, specify the system-defined SKOSCORE rulebase in the rulebases_in parameter in the call to the SEM_APIS.CREATE_ENTAILMENT procedure, as in the following example:
EXECUTE sem_apis.create_entailment('tstidx',sem_models('tst'), sem_rulebases('skoscore'));
Example 3-1 defines, in Turtle format, a simple electronics scheme and two relevant concepts, cameras and digital cameras. Its meaning is straightforward and its representation is in RDF. It can be managed by Oracle Database in the same way as other RDF and OWL data.
Example 3-1 SKOS Definition of an Electronics Scheme
ex1:electronicsScheme rdf:type skos:ConceptScheme; ex1:cameras rdf:type skos:Concept; skos:prefLabel "cameras"@en; skos:inScheme ex1:electronicsScheme. ex1:digitalCameras rdf:type skos:Concept; skos:prefLabel "digital cameras"@en; skos:inScheme ex1:electronicsScheme. ex1:digitalCameras skos:broader ex1:cameras.
This section describes features of SKOS semantics that are and are not supported by Oracle Database.
All terms defined in SKOS and SKOS extension for labels are recognized. When the SKOSCORE rulebase is chosen for inference, the recognized terms include the following:
skos:altLabel skos:broader skos:broaderTransitive skos:broadMatch skos:changeNote skos:closeMatch skos:Collection skos:Concept skos:ConceptScheme skos:definition skos:editorialNote skos:exactMatch skos:example skos:hasTopConcept skos:hiddenLabel skos:historyNote skos:inScheme skos:mappingRelation skos:member skos:memberList skos:narrower skos:narrowerTransitive skos:narrowMatch skos:notation skos:note skos:OrderedCollection skos:prefLabel skos:related skos:relatedMatch skos:scopeNote skos:semanticRelation skos:topConceptOf skosxl:altLabel skosxl:hiddenLabel skosxl:Label skosxl:labelRelation skosxl:literalForm skosxl:prefLabel
Most SKOS axioms and definitions are supported including the following: S1-S8, S10-S11, S15-S26, S28-S31, S33-S36, S38-S45, S47-S50, and S53-S54. (See the SKOS detailed specification for definitions.)
Most SKOS integrity conditions are supported, including S9, S13, S27, S37, and S46.
S52 is partially supported.
S55, S56, and S57 are not supported by default.
S55, the property chain (skosxl:prefLabel, skosxl:literalForm), is a subproperty of skos:prefLabel.
S56, the property chain (skosxl:altLabel, skosxl:literalForm), is a subproperty of skos:altLabel.
S57, the property chain (skosxl:hiddenLabel, skosxl:literalForm), is a subproperty of skos:hiddenLabel.chains.
However, S55, S56, and S57 can be implemented using the OWL 2 subproperty chain construct. For information about property chain handling, see Section 3.2.2.
The following features of SKOS semantics are not supported:
S12 and S51: The rdfs:range of the relevant predicates is the class of RDF plain literals. There is no check that the object values of these predicates are indeed plain literals; however, applications can perform such a check.
S14: A resource has no more than one value of skos:prefLabel per language tag. This integrity condition is even beyond OWL FULL semantics, and it is not enforced in the current release.
S32: The rdfs:range of skos:member is the union of classes skos:Concept and skos:Collection. This integrity condition is not enforced.
S55, S56, and S57 are not supported by default, but they can be implemented using the OWL 2 subproperty chain construct, as explained in Section 3.1.1.
To create an SKOS model, use the same procedure (SEM_APIS.CREATE_SEM_MODEL) as for creating a semantic model. You can load data into an SKOS model in the same way as for semantic models.
To infer new relationships for one or more SKOS models, use the SEM_APIS.CREATE_ENTAILMENT procedure with the system-defined rulebase SKOSCORE. For example:
EXECUTE sem_apis.create_entailment('tstidx',sem_models('tst'), sem_rulebases('skoscore'));
The inferred data will include many of the axioms defined in the SKOS detailed specification. Like other system-defined rulebases, SKOSCORE has no explicit rules; all the semantics supported are coded into the implementation.
You can use the SEM_APIS.VALIDATE_ENTAILMENT and SEM_APIS.VALIDATE_MODEL procedures to validate the supported integrity conditions. The output will include any inconsistencies caused by the supported integrity conditions, such as OWL 2 propertyDisjointWith and S52.
Example 3-2 validates an SKOS entailment.
Example 3-2 Validating an SKOS Entailment
set serveroutput on
declare
lva mdsys.rdf_longVarcharArray;
idx int;
begin
lva := sem_apis.validate_entailment(sdo_rdf_models('tstskos'), sem_rulebases('skoscore'));
if (lva is null) then
dbms_output.put_line('No conflicts');
else
for idx in 1..lva.count loop
dbms_output.put_line('entry ' || idx || ' ' || lva(idx));
end loop;
end if;
end;
/
The SKOS S55, S56, and S57 semantics are not supported by default. However, you can add support for them by using the OWL 2 subproperty chain construct.
Example 3-3 inserts the necessary chain definition triples for S55 into an SKOS model. After the insertion, an invocation of SEM_APIS.CREATE_ENTAILMENT that specifies the SKOSCORE rulebase will include the semantics defined in S55.
Example 3-3 Property Chain Insertions to Implement S55
INSERT INTO tst VALUES(sdo_rdf_triple_s('tst','<http://www.w3.org/2004/02/skos/core#prefLabel>', '<http://www.w3.org/2002/07/owl#propertyChainAxiom>', '_:jA1'));
INSERT INTO tst VALUES(sdo_rdf_triple_s('tst','_:jA1', '<http://www.w3.org/1999/02/22-rdf-syntax-ns#first>', '<http://www.w3.org/2008/05/skos-xl#prefLabel>'));
INSERT INTO tst VALUES(sdo_rdf_triple_s('tst','_:jA1', '<http://www.w3.org/1999/02/22-rdf-syntax-ns#rest>', '_:jA2'));
INSERT INTO tst VALUES(sdo_rdf_triple_s('tst','_:jA2', '<http://www.w3.org/1999/02/22-rdf-syntax-ns#first>', '<http://www.w3.org/2008/05/skos-xl#literalForm>'));
INSERT INTO tst VALUES(sdo_rdf_triple_s('tst','_:jA2', '<http://www.w3.org/1999/02/22-rdf-syntax-ns#rest>', '<http://www.w3.org/1999/02/22-rdf-syntax-ns#nil>'));
Oracle Database Semantic Technologies Developer's Guide provides usage and reference information about Oracle Database Enterprise Edition support for semantic technologies, including storage, inference, and query capabilities for data and ontologies based on Resource Description Framework (RDF), RDF Schema (RDFS), and Web Ontology Language (OWL). The Semantic Technologies feature is licensed with the Oracle Spatial option to Oracle Database Enterprise Edition, and it requires the Oracle Partitioning option to Oracle Database Enterprise Edition.
|
Note: You must perform certain actions and meet prerequisites before you can use any types, synonyms, or PL/SQL packages related to Oracle semantic technologies support. These actions and prerequisites are explained in Section A.1. |
This guide is intended for those who need to use semantic technology to store, manage, and query semantic data in the database.
You should be familiar with at least the main concepts and techniques for the Resource Description Framework (RDF) and the Web Ontology Language (OWL).
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support
Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.
For an excellent explanation of RDF concepts, see the World Wide Web Consortium (W3C) RDF Primer at http://www.w3.org/TR/rdf-primer/.
For information about OWL, see the OWL Web Ontology Language Reference at http://www.w3.org/TR/owl-ref/.
The following text conventions are used in this document:
| Convention | Meaning |
|---|---|
| boldface | Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary. |
| italic | Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values. |
monospace | Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter. |
This document has the following parts:
Part I provides conceptual and usage information about Oracle Semantic Technologies.
Part II provides reference information about Oracle Semantic Technologies subprograms; it also provides supplementary information in appendixes and a glossary.
Part I contains the following chapters: