Skip to content

cmem_client.components.explore.component¤

Corporate Memory Explore (DataPlatform) component.

The Explore component bundles the operations of the Explore service which are not collections of items: the SPARQL endpoint, administrative status, bootstrap and showcase data, full backup and restore, and information about the graph store instance. Each of these lives in its own module of this package; this class only delegates to them.

Classes:

  • Explore – High-level interface for the Corporate Memory Explore (DataPlatform) service.

Attributes:

  • AUTHORIZATION_GRAPH_URI – The URI of the access conditions graph. Deleting or importing this graph requires an authorization refresh.

AUTHORIZATION_GRAPH_URI¤

AUTHORIZATION_GRAPH_URI = 'https://ns.eccenca.com/data/ac/'

The URI of the access conditions graph. Deleting or importing this graph requires an authorization refresh.

Explore¤

Explore(client)

High-level interface for the Corporate Memory Explore (DataPlatform) service.

The Explore component provides administrative and operational methods for managing the Corporate Memory DataPlatform graph store. It handles store-level operations including bootstrap data management, full backup and restoration, and system information retrieval.

This component abstracts the complexities of the DataPlatform API and provides a convenient interface for common graph store management tasks. It is designed for administrative operations rather than individual graph manipulation (use repositories for graph-level operations).

Attributes:

  • _client (Client) – The Corporate Memory client instance used for API communication.
  • _sparql_wrapper (SPARQLWrapper) – SPARQLWrapper instance for rdflib SPARQL queries.
Administrative Operations
  • Full store backup and restoration
  • Bootstrap data management (system vocabularies, etc.)
See Also

For individual graph operations, use the repositories.graphs module which provides CRUD operations for specific RDF graphs.

Functions:

Parameters:

  • client (Client) – A configured Corporate Memory client instance with authentication and endpoint configuration.
Note

This constructor is typically called automatically by the Client class when accessing the store property. Direct instantiation is rarely needed in normal usage.

create_showcase_data¤

create_showcase_data(scale_factor=None)

Create showcase data in the graph store.

Inserts a showcase scenario of multiple graphs including integration graphs, shapes, statement annotations, etc. Useful for demonstration and testing environments.

Parameters:

  • scale_factor (int | None) – Multiplies the default showcase dataset by this factor. A value of 10 results in around 40k triples, a value of

50 in around 350k triples. Defaults to the server default when None.

Raises:

  • HTTPError – If the showcase creation request fails due to network issues or server errors.

delete_bootstrap_data¤

delete_bootstrap_data()

Delete bootstrap data from the graph store.

Warning: This operation removes system vocabularies and foundational RDF data required for proper Corporate Memory operation. Use with extreme caution.

Removes all bootstrap data including system vocabularies, ontologies, and other foundational RDF graphs. This is typically used for cleanup during testing, or system reset.

Raises:

  • HTTPError – If the bootstrap deletion request fails due to network issues or server errors.
Caution

After deleting bootstrap data, the Corporate Memory system may not function correctly until new bootstrap data is imported. This operation should typically be followed by import_bootstrap_data().

Use Cases
  • System reset during testing
  • Troubleshooting corrupted system vocabularies
  • Development environment reset

export_to_zip¤

export_to_zip(path)

Export a complete backup of the graph store as a ZIP archive.

Creates a full backup of the entire Corporate Memory DataPlatform graph store, including all RDF graphs, system vocabularies, and metadata. The backup is streamed directly to the specified file path as a compressed ZIP archive.

This operation creates a point-in-time snapshot that can be used for:

  • Disaster recovery and backup strategies
  • Environment migration and cloning
  • System maintenance and testing
  • Data archival and compliance requirements

Parameters:

  • path (Path) – The file system path where the ZIP backup archive will be saved. The path should include the .zip extension and the parent directory

must exist and be writable.

Raises:

  • HTTPError – If the backup request fails due to network issues, server errors, or insufficient permissions.
  • OSError – If the specified path cannot be written to due to file system permissions or disk space issues.
Performance Notes
  • The backup is streamed directly to disk to minimize memory usage
  • Large stores may take significant time to back up completely
  • Network bandwidth and storage I/O will impact backup duration
  • The operation blocks until the entire backup is complete
Security Considerations
  • Backup files contain all graph data and should be stored securely
  • Consider encryption for sensitive data in backup archives
  • Ensure appropriate access controls on backup storage locations
  • Backup files may contain authentication tokens or sensitive metadata
See Also

Use import_from_zip() to restore from backup archives created by this method.

get_health¤

get_health()

Report version and health of the Explore (DataPlatform) service.

Reads the service’s /actuator/info and /actuator/health. Both answers are kept in the result: info also carries the store block (type and version of the graph store), and is only set when both requests succeed.

Returns:

  • ExploreStatus – The status of Explore. An unreachable or failing service is reported DOWN with
  • ExploreStatus – the error, instead of raising.

get_shapes_health¤

get_shapes_health()

Report version and health of the shapes catalog served by Explore.

Reads the version the shapes catalog graph declares, with a SPARQL query.

Returns:

  • ComponentStatus – The status of the shapes catalog: UP with its version, DOWN without a version
  • ComponentStatus – or with the error of a failing query, instead of raising.

import_bootstrap_data¤

import_bootstrap_data()

Import or update bootstrap data in the graph store.

Bootstrap data includes system vocabularies, ontologies, and other foundational RDF data required for proper Corporate Memory operation. This operation ensures the store contains all necessary system-level graphs and vocabularies.

Raises:

  • HTTPError – If the bootstrap import request fails due to network issues or server errors.
Note

This operation may take some time. It is typically performed during system initialization or when updating to new Corporate Memory versions that include new system vocabularies.

Use Cases
  • Initial system setup
  • System updates with new vocabularies
  • Recovery after bootstrap data corruption

import_from_zip¤

import_from_zip(path)

Import and restore a complete graph store backup from a ZIP archive.

Warning: This operation replaces ALL existing data in the graph store. All current graphs, vocabularies, and metadata will be permanently deleted and replaced with the contents of the backup archive.

Restores a Corporate Memory DataPlatform graph store from a ZIP backup archive created by export_to_zip(). The restoration process completely replaces the current store contents with the archived data, effectively rolling back the store to the state captured in the backup.

Parameters:

  • path (Path) – The file system path to the ZIP backup archive to import. The file must be a valid backup archive created by export_to_zip()

or compatible with the Corporate Memory backup format.

Raises:

  • HTTPError – If the restore request fails due to network issues, server errors, insufficient permissions, or invalid backup format.
  • OSError – If the specified backup file cannot be read due to file system permissions or if the file does not exist.
  • ValidationError – If the backup archive format is invalid or corrupted.
Important Warnings
  • Data Loss: All existing graphs and data will be permanently deleted
  • Downtime: The store may be unavailable during the restoration process
  • Irreversible: This operation cannot be undone without another backup
  • Compatibility: Ensure backup compatibility with current store version
Performance Notes
  • Large backup archives may take significant time to restore
  • The store will be unavailable during the restoration process
  • Network bandwidth and storage I/O will impact restoration duration
  • Memory usage is optimized through streaming file upload
Use Cases
  • Disaster recovery from catastrophic data loss
  • Environment synchronization and cloning
  • Rolling back to known good state after issues
  • Migrating data between Corporate Memory instances
  • Testing and development environment setup
See Also

Use export_to_zip() to create backup archives for import with this method.

logger¤

logger = logging.getLogger(f'{self._client.logger.name}.{self.__class__.__name__}')

logs¤

logs: ExploreLogs = ExploreLogs(client=client)

The in-memory log buffer of Explore: the most recent lines and the state of the buffer.

self_information¤

self_information: StoreInformation

Get metadata and version information about the graph store instance.

Retrieves information about the Corporate Memory DataPlatform graph store, including the store implementation type and version.

The information is fetched from the store’s actuator endpoint, which provides real-time metadata about the running graph store instance.

Returns:

  • StoreInformation (StoreInformation) – A model containing store type and version information. The returned object includes the store implementation name

(e.g., “GRAPHDB”, “TENTRIS”) and its version string.

Raises:

  • HTTPError – If the information request fails due to network issues, server errors, or insufficient permissions to access actuator endpoints.
  • ValidationError – If the response cannot be parsed as valid store information due to unexpected response format.
Performance Notes
  • This property makes a live HTTP request on each access
  • Consider caching the result if accessed frequently
  • The actuator endpoint is typically lightweight and fast-responding
  • Network latency will impact response time for this property
Security Notes
  • Actuator endpoints may reveal system information
  • Ensure appropriate access controls on actuator endpoints
  • Store version information should be treated as potentially sensitive

sparql¤

sparql: SPARQLWrapper

Get a SPARQLWrapper instance for rdflib-based SPARQL queries.

Returns a SPARQLWrapper component configured with authentication for executing SPARQL queries using rdflib. The wrapper provides access to the Corporate Memory SPARQL endpoint with automatic authentication handling.

Returns:

  • SPARQLWrapper – The SPARQLWrapper component instance, created lazily on first access.

Examples:

>>> from cmem_client.client import Client
>>> client = Client.from_env()
>>> sparql_wrapper = client.explore.sparql

titles¤

titles: ExploreTitles = ExploreTitles(client=client)

Human-readable titles of IRIs, resolved in batches and cached.

wait_for_admin_idle¤

wait_for_admin_idle(timeout=60.0, poll_interval=1.0)

Poll the administrative status until no administrative operation is in progress.

Administrative operations such as import_bootstrap_data() or create_showcase_data() are asynchronous on the server: the method call returns as soon as the operation has been accepted, not once it has finished. Call this method afterward to wait until the operation has actually completed before relying on its effects, for example before reading the graphs it wrote.

Parameters:

  • timeout (float) – Maximum seconds to wait before raising TimeoutError.
  • poll_interval (float) – Seconds to wait between status checks.

Raises:

  • TimeoutError – If an administrative operation is still in progress after timeout seconds.
  • HTTPError – If a status request fails.

Comments