ontouml_models_lib.query

The query module provides the Query class, designed to handle the loading, representation, and hashing of SPARQL queries for execution within the OntoUML/UFO catalog.

This module ensures that SPARQL queries are consistently managed, enabling reliable query execution across RDF graphs representing ontology models.

Overview

The Query class encapsulates SPARQL queries, providing methods to load queries from files, compute persistent hashes to ensure the uniqueness and reusability of query results, and facilitate query execution across RDF graphs. This class is crucial for managing the integrity and consistency of queries used within the catalog.

Usage

Example 1: Loading a Query from a File

>>> from ontouml_models_lib import Query
>>> query = Query('/path/to/query.sparql')
>>> print(query.query_content)
# Output: "SELECT ?s WHERE { ?s ?p ?o }"

Example 2: Computing the Hash of a Query

>>> from ontouml_models_lib import Query
>>> query = Query('/path/to/query.sparql')
>>> print(query.hash)
# Output: 12345678901234567890 (example hash value)

Dependencies

hashlib: For computing hashes of the SPARQL queries.
pathlib: For handling file paths in a platform-independent manner.

References

For additional details on the OntoUML/UFO catalog, refer to the official OntoUML repository: https://github.com/OntoUML/ontouml-models

Classes

Query

Represents a SPARQL query for execution within the OntoUML/UFO catalog.

Module Contents

class ontouml_models_lib.query.Query(query_file)

Represents a SPARQL query for execution within the OntoUML/UFO catalog.

The Query class encapsulates a SPARQL query, providing methods for loading the query from a file, computing a persistent hash for the query content, and managing multiple queries through batch loading. This class ensures that queries are handled consistently, facilitating their reuse and reliable execution across RDF graphs representing ontology models.

Variables:

query_file_path (Path) – The path to the file from which the SPARQL query was loaded.
query_content (str) – The content of the SPARQL query as a string.
hash (int) – A persistent hash value computed from the query content, used to ensure consistent result management.

Parameters:

query_file (Union[str, pathlib.Path])

Example:

>>> from ontouml_models_lib import Query
>>> query = Query('/path/to/query.sparql')
>>> print(query.query_content)
# Output: "SELECT ?s WHERE { ?s ?p ?o }"

query_file

query_file_path: pathlib.Path

name: str

query_content: str

hash: int

static load_queries(queries_path)

Load all query_content files from the specified directory catalog_path and return a list of Query instances.

Parameters:: queries_path (Path) – Path to the directory containing query_content files.
Returns:: List of Query instances.
Return type:: list[Query]

execute_on_models(models, results_path=None)

Execute the query on a list of models and consolidate the results into a single file.

This method executes the query across multiple ontology models and saves all results into a single consolidated file.

Parameters:

models (list[Model]) – A list of Model instances on which the query will be executed.
results_path (Optional[Union[str, Path]]) – Optional; Path to the directory where the query results should be saved. If not provided, defaults to “./results”.

Raises:

Exception – For any errors that occur during query execution.

Return type:

None

_save_results(results, results_path, suffix='')

Save the results to a file.

This method is responsible for saving the results of the query execution to a file.

Parameters:

results (list[dict]) – The results to save.
results_path (Path) – The path to save the results file.
suffix (str) – An optional suffix for the filename to distinguish different types of results.

Return type:

None

static _read_query_file(query_file)

Read the content of a SPARQL query file.

This method opens a SPARQL query file, reads its content, and returns it as a string. The file is read using UTF-8 encoding to ensure compatibility with a wide range of characters.

Parameters:

query_file (Path) – The path to the SPARQL query file.

Returns:

The content of the SPARQL query file as a string.

Return type:

str

Raises:

FileNotFoundError – If the specified query file does not exist.
OSError – If an error occurs while reading the query file.

static _compute_persistent_hash(content)

Compute a persistent hash value for the content of a SPARQL query.

This method generates a SHA-256 hash from the content of a SPARQL query string. The hash is computed in a way that ensures consistency across executions, facilitating the identification and management of query results.

Parameters:: content (str) – The content of the SPARQL query to be hashed.
Returns:: The computed hash value for the query content.
Return type:: int