cmem-cmemc 25.3.0__py3-none-any.whl → 25.5.0__py3-none-any.whl

cmem_cmemc/commands/graph_insights.py

@@ -0,0 +1,382 @@
+"""Graph Insights command group"""
+
+import time
+
+import click
+from click import Argument, Context
+from click.shell_completion import CompletionItem
+from cmem.cmempy.api import get_json, request
+from cmem.cmempy.config import get_dp_api_endpoint
+from requests import HTTPError
+
+from cmem_cmemc.command import CmemcCommand
+from cmem_cmemc.command_group import CmemcGroup
+from cmem_cmemc.completion import NOT_SORTED, finalize_completion, graph_uris
+from cmem_cmemc.context import ApplicationContext
+from cmem_cmemc.exceptions import CmemcError
+from cmem_cmemc.object_list import (
+    DirectListPropertyFilter,
+    DirectValuePropertyFilter,
+    ObjectList,
+    transform_lower,
+)
+from cmem_cmemc.string_processor import GraphLink, TimeAgo
+from cmem_cmemc.utils import get_graphs_as_dict, struct_to_table
+
+
+def get_api_url(path: str = "") -> str:
+    """Get URLs of the graph insights API.
+
+    Constructs the full URL for accessing graph insights API endpoints by combining
+    the DataPlatform API endpoint with the semspect extension base path and an
+    optional resource path.
+
+    Args:
+        path: The API resource path to append to the base URL. Defaults to an empty
+            string for the root endpoint.
+
+    Returns:
+        The complete URL for the specified graph insights API endpoint.
+
+    Example:
+        >>> get_api_url()
+        'https://example.com/dataplatform/api/ext/semspect'
+        >>> get_api_url("/snapshot/status")
+        'https://example.com/dataplatform/api/ext/semspect/snapshot/status'
+
+    """
+    base_url = get_dp_api_endpoint() + "/api/ext/semspect"
+    return f"{base_url}{path}"
+
+
+def is_available() -> bool:
+    """Check availability of graph insights endpoints
+
+    {
+     "isActive": true,
+     "isUserAllowed": true
+    }
+    """
+    try:
+        data: dict[str, bool] = get_json(get_api_url())
+    except HTTPError:
+        return False
+    return bool(data["isActive"] is True and data["isUserAllowed"] is True)
+
+
+def check_availability(ctx: click.Context) -> None:
+    """Check availability of graph insights endpoints or raise an exception"""
+    if is_available():
+        return
+    app: ApplicationContext = ctx.obj
+    raise CmemcError(app, "Graph Insights is not available.")
+
+
+def get_snapshots(ctx: click.Context) -> list[dict[str, str | bool | list[str]]]:
+    """Get the snapshot list (all snapshots)"""
+    check_availability(ctx)
+    data: list[dict[str, str | bool | list[str]]] = get_json(
+        get_api_url("/snapshot/status"), params={"includeManagementOnly": True}
+    )
+    return data
+
+
+def complete_snapshot_ids(ctx: Context, param: Argument, incomplete: str) -> list[CompletionItem]:  # noqa: ARG001
+    """Provide auto-completion for snapshot Ids"""
+    ApplicationContext.set_connection_from_params(ctx.find_root().params)
+    if not is_available():
+        return []
+    snapshots = get_snapshots(ctx)
+    snapshots = sorted(
+        snapshots, key=lambda snapshot: snapshot["updateInfoTimestamp"], reverse=True
+    )
+    options = [
+        (
+            snapshot["databaseId"],
+            f"{snapshot['mainGraphSynced']} ({snapshot['updateInfoTimestamp']})",
+        )
+        for snapshot in snapshots
+    ]
+    return finalize_completion(candidates=options, incomplete=incomplete, sort_by=NOT_SORTED)
+
+
+snapshot_list = ObjectList(
+    name="insight snapshots",
+    get_objects=get_snapshots,
+    filters=[
+        DirectValuePropertyFilter(
+            name="id",
+            description="Snapshots with a specific id.",
+            property_key="databaseId",
+            transform=transform_lower,
+        ),
+        DirectValuePropertyFilter(
+            name="main-graph",
+            description="Snapshots with a specific main graph.",
+            property_key="mainGraphSynced",
+        ),
+        DirectValuePropertyFilter(
+            name="status",
+            description="Snapshots with a specific status.",
+            property_key="status",
+        ),
+        DirectListPropertyFilter(
+            name="affected-graph",
+            description="Snapshots with a specific affected graph (main or sub-graphs).",
+            property_key="allGraphsSynced",
+        ),
+        DirectValuePropertyFilter(
+            name="valid",
+            description="Snapshots with a specific validity indicator.",
+            property_key="isValid",
+            transform=transform_lower,
+        ),
+    ],
+)
+
+
+@click.command(cls=CmemcCommand, name="list")
+@click.option(
+    "--filter",
+    "filter_",
+    type=(str, str),
+    help=snapshot_list.get_filter_help_text(),
+    shell_complete=snapshot_list.complete_values,
+    multiple=True,
+)
+@click.option("--raw", is_flag=True, help="Outputs raw JSON response.")
+@click.option(
+    "--id-only",
+    is_flag=True,
+    help="Return the snapshot IDs only. This is useful for piping the IDs into other commands.",
+)
+@click.pass_context
+def list_command(ctx: Context, filter_: tuple[tuple[str, str]], id_only: bool, raw: bool) -> None:
+    """List graph insight snapshots.
+
+    Graph Insights Snapshots are identified by an ID.
+    """
+    check_availability(ctx)
+    app: ApplicationContext = ctx.obj
+    snapshots = snapshot_list.apply_filters(ctx=ctx, filter_=filter_)
+
+    if id_only:
+        for _ in snapshots:
+            click.echo(_["databaseId"])
+        return
+
+    if raw:
+        app.echo_info_json(snapshots)
+        return
+
+    graphs = get_graphs_as_dict()
+    table = []
+    for _ in snapshots:
+        id_ = _["databaseId"]
+        main_graph = _["mainGraphSynced"]
+        updated = _["updateInfoTimestamp"]
+        status = _["status"]
+        is_valid = _["isValid"]
+        if main_graph not in graphs:
+            main_graph = rf"\[missing: {main_graph}]"
+        table.append([id_, main_graph, updated, status, is_valid])
+
+    app.echo_info_table(
+        table,
+        headers=["ID", "Main Graph", "Updated", "Status", "Valid"],
+        sort_column=0,
+        cell_processing={1: GraphLink(), 2: TimeAgo()},
+        empty_table_message="No graph insight snapshots found.",
+    )
+
+
+@click.command(cls=CmemcCommand, name="delete")
+@click.argument("SNAPSHOT_ID", type=str, shell_complete=complete_snapshot_ids, required=False)
+@click.option(
+    "--filter",
+    "filter_",
+    type=(str, str),
+    help=snapshot_list.get_filter_help_text(),
+    shell_complete=snapshot_list.complete_values,
+    multiple=True,
+)
+@click.option("-a", "--all", "all_", is_flag=True, help="Delete all snapshots.")
+@click.pass_context
+def delete_command(
+    ctx: Context, snapshot_id: str | None, filter_: tuple[tuple[str, str]], all_: bool
+) -> None:
+    """Delete a graph insight snapshot.
+
+    Graph Insight Snapshots are identified by an ID.
+    To get a list of existing snapshots,
+    execute the `graph insights list` command or use tab-completion.
+    """
+    check_availability(ctx)
+    app: ApplicationContext = ctx.obj
+    if snapshot_id is None and not filter_ and not all_:
+        raise click.UsageError("Either provide a snapshot ID or a filter, or use the --all flag.")
+
+    if all_:
+        app.echo_info("Deleting all snapshots ... ", nl=False)
+        request(method="DELETE", uri=get_api_url("/snapshot"))
+        app.echo_success("done")
+        return
+
+    filter_to_apply = list(filter_) if filter_ else []
+    if snapshot_id:
+        filter_to_apply.append(("id", snapshot_id))
+    snapshots_to_delete = snapshot_list.apply_filters(ctx=ctx, filter_=filter_to_apply)
+
+    if not snapshots_to_delete and snapshot_id:
+        raise click.ClickException(f"Snapshot ID '{snapshot_id}' does not exist.")
+
+    if not snapshots_to_delete and not snapshot_id:
+        raise click.ClickException("No snapshots found to delete.")
+
+    for _ in snapshots_to_delete:
+        id_to_delete = _["databaseId"]
+        app.echo_info(f"Deleting snapshot {id_to_delete} ... ", nl=False)
+        request(method="DELETE", uri=get_api_url(f"/snapshot/{id_to_delete}"))
+        app.echo_success("done")
+
+
+def wait_for_snapshot(snapshot_id: str, polling_interval: int) -> None:
+    """Poll until the snapshot reaches 'DONE' status."""
+    while True:
+        snapshot: dict[str, str | bool | list[str]] = get_json(
+            get_api_url(f"/snapshot/status/{snapshot_id}")
+        )
+        if snapshot.get("status") == "DONE":
+            break
+        time.sleep(polling_interval)
+
+
+@click.command(cls=CmemcCommand, name="create")
+@click.argument("iri", type=click.STRING, shell_complete=graph_uris)
+@click.option("--wait", is_flag=True, help="Wait until snapshot creation is done.")
+@click.option(
+    "--polling-interval",
+    type=click.IntRange(min=0, max=60),
+    show_default=True,
+    default=1,
+    help="How many seconds to wait between status polls. Status polls are"
+    " cheap, so a higher polling interval is most likely not needed.",
+)
+@click.pass_context
+def create_command(ctx: Context, iri: str, wait: bool, polling_interval: int) -> None:
+    """Create or update a graph insight snapshot.
+
+    Create a graph insight snapshot for a given graph.
+    If the snapshot already exists, it is hot-swapped after re-creation.
+    The snapshot contains only the (imported) graphs the requesting user can read.
+    """
+    check_availability(ctx)
+    app: ApplicationContext = ctx.obj
+    app.echo_info(f"Create / Update graph snapshot for graph {iri} ... ", nl=False)
+    snapshot_id = request(
+        method="POST", uri=get_api_url("/snapshot"), params={"contextGraph": iri}
+    ).text
+    app.echo_success("started", nl=not wait)
+    if wait:
+        app.echo_info(" ... ", nl=False)
+        wait_for_snapshot(snapshot_id, polling_interval)
+        app.echo_success("created")
+
+
+@click.command(cls=CmemcCommand, name="update")
+@click.argument("SNAPSHOT_ID", type=str, shell_complete=complete_snapshot_ids, required=False)
+@click.option(
+    "--filter",
+    "filter_",
+    type=(str, str),
+    help=snapshot_list.get_filter_help_text(),
+    shell_complete=snapshot_list.complete_values,
+    multiple=True,
+)
+@click.option("-a", "--all", "all_", is_flag=True, help="Delete all snapshots.")
+@click.option("--wait", is_flag=True, help="Wait until snapshot creation is done.")
+@click.option(
+    "--polling-interval",
+    type=click.IntRange(min=0, max=60),
+    show_default=True,
+    default=1,
+    help="How many seconds to wait between status polls. Status polls are"
+    " cheap, so a higher polling interval is most likely not needed.",
+)
+@click.pass_context
+def update_command(  # noqa: PLR0913
+    ctx: Context,
+    snapshot_id: str | None,
+    filter_: tuple[tuple[str, str]],
+    all_: bool,
+    wait: bool,
+    polling_interval: int,
+) -> None:
+    """Update a graph insight snapshot.
+
+    Update a graph insight snapshot.
+    After the update, the snapshot is hot-swapped.
+    """
+    check_availability(ctx)
+    app: ApplicationContext = ctx.obj
+    if snapshot_id is None and not filter_ and not all_:
+        raise click.UsageError("Either provide a snapshot ID or a filter, or use the --all flag.")
+
+    filter_to_apply = list(filter_) if filter_ else []
+    if snapshot_id:
+        filter_to_apply.append(("id", snapshot_id))
+    snapshots_to_update = snapshot_list.apply_filters(ctx=ctx, filter_=filter_to_apply)
+
+    if all_:
+        snapshots_to_update = get_snapshots(ctx)
+
+    if not snapshots_to_update and snapshot_id:
+        raise click.ClickException(f"Snapshot ID '{snapshot_id}' does not exist.")
+
+    if not snapshots_to_update and not snapshot_id:
+        raise click.ClickException("No snapshots found to update.")
+
+    for _ in snapshots_to_update:
+        id_to_update = _["databaseId"]
+        app.echo_info(f"Update snapshot {id_to_update} ... ", nl=False)
+        request(method="PUT", uri=get_api_url(f"/snapshot/{id_to_update}"))
+        app.echo_success("started", nl=not wait)
+        if wait:
+            app.echo_info(" ... ", nl=False)
+            wait_for_snapshot(id_to_update, polling_interval)
+            app.echo_success("updated")
+
+
+@click.command(cls=CmemcCommand, name="inspect")
+@click.argument("SNAPSHOT_ID", type=str, shell_complete=complete_snapshot_ids)
+@click.option("--raw", is_flag=True, help="Outputs raw JSON.")
+@click.pass_context
+def inspect_command(ctx: Context, snapshot_id: str, raw: bool) -> None:
+    """Inspect the metadata of a graph insight snapshot."""
+    check_availability(ctx)
+    app: ApplicationContext = ctx.obj
+    snapshot: dict[str, str | bool | list[str]] = get_json(
+        get_api_url(f"/snapshot/status/{snapshot_id}")
+    )
+    if raw:
+        app.echo_info_json(snapshot)
+    else:
+        table = struct_to_table(snapshot)
+        app.echo_info_table(table, headers=["Key", "Value"], sort_column=0)
+
+
+@click.group(cls=CmemcGroup, name="insights")
+def insights_group() -> CmemcGroup:  # type: ignore[empty-body]
+    """List, create, delete and inspect graph insight snapshots.
+
+    Graph Insight Snapshots are identified by an ID.
+    To get a list of existing snapshots,
+    execute the `graph insights list` command or use tab-completion.
+    """
+
+
+insights_group.add_command(list_command)
+insights_group.add_command(delete_command)
+insights_group.add_command(create_command)
+insights_group.add_command(update_command)
+insights_group.add_command(inspect_command)

cmem_cmemc/commands/project.py

@@ -138,7 +138,7 @@ def list_command(app: ApplicationContext, raw: bool, id_only: bool) -> None:
     for _ in projects:
         row = [
             _["name"],
-            _["metaData"]["label"],
+            _["metaData"].get("label", ""),
         ]
         table.append(row)
     app.echo_info_table(

cmem_cmemc/commands/query.py

@@ -10,8 +10,8 @@ from time import sleep, time
 from uuid import uuid4
 
 import click
-from click import ClickException, UsageError
 from click.shell_completion import CompletionItem
+from cmem.cmempy.config import get_cmem_base_uri
 from cmem.cmempy.queries import (
     QueryCatalog,
     SparqlQuery,
@@ -91,12 +91,12 @@ class ReplayStatistics:
                 iri = query_["iri"]
                 catalog_entry = self.catalog.get_query(iri)
                 if catalog_entry is None:
-                    raise ClickException(f"measure_query - query {iri} is not in catalog.")
+                    raise click.ClickException(f"measure_query - query {iri} is not in catalog.")
                 return catalog_entry
             query_string = query_["queryString"]
             return SparqlQuery(text=query_string)
         except KeyError as error:
-            raise ClickException(
+            raise click.ClickException(
                 "measure_query - given input dict has no queryString key."
             ) from error
 
@@ -289,15 +289,15 @@ query_status_list = ObjectList(
             compare=compare_regex,
             fixed_completion=[
                 CompletionItem(
-                    r"http\:\/\/schema.org",
+                    r"http://schema.org",
                     help="List only queries which somehow use the schema.org namespace.",
                 ),
                 CompletionItem(
-                    r"http\:\/\/www.w3.org\/2000\/01\/rdf-schema\#",
+                    r"http://www.w3.org/2000/01/rdf-schema#",
                     help="List only queries which somehow use the RDF schema namespace.",
                 ),
                 CompletionItem(
-                    r"\\\?value",
+                    r"?value",
                     help="List only queries which are using the ?value projection variable.",
                 ),
                 CompletionItem(
@@ -330,6 +330,13 @@ def _output_query_status_details(app: ApplicationContext, status_dict: dict) ->
 
 
 @click.command(cls=CmemcCommand, name="list")
+@click.option(
+    "--catalog-graph",
+    default="https://ns.eccenca.com/data/queries/",
+    show_default=True,
+    shell_complete=completion.graph_uris,
+    help="The used query catalog graph.",
+)
 @click.option(
     "--id-only",
     is_flag=True,
@@ -337,13 +344,13 @@ def _output_query_status_details(app: ApplicationContext, status_dict: dict) ->
     "This is useful for piping the ids into other cmemc commands.",
 )
 @click.pass_obj
-def list_command(app: ApplicationContext, id_only: bool) -> None:
+def list_command(app: ApplicationContext, catalog_graph: str, id_only: bool) -> None:
     """List available queries from the catalog.
 
     Outputs a list of query URIs which can be used as reference for
     the query execute command.
     """
-    queries = QueryCatalog().get_queries().items()
+    queries = QueryCatalog(graph=catalog_graph).get_queries().items()
     if id_only:
         # sort dict by short_url - https://docs.python.org/3/howto/sorting.html
         for _, sparql_query in sorted(queries, key=lambda k: k[1].short_url.lower()):
@@ -359,7 +366,12 @@ def list_command(app: ApplicationContext, id_only: bool) -> None:
             ]
             table.append(row)
         app.echo_info_table(
-            table, headers=["Query URI", "Type", "Placeholder", "Label"], sort_column=3
+            table,
+            headers=["Query URI", "Type", "Placeholder", "Label"],
+            sort_column=3,
+            empty_table_message="There are no query available in the "
+            f"selected catalog ({catalog_graph}).",
+            caption=f"Queries from {catalog_graph} ({get_cmem_base_uri()})",
         )
 
 
@@ -367,6 +379,13 @@ def list_command(app: ApplicationContext, id_only: bool) -> None:
 @click.argument(
     "QUERIES", nargs=-1, required=True, shell_complete=completion.remote_queries_and_sparql_files
 )
+@click.option(
+    "--catalog-graph",
+    default="https://ns.eccenca.com/data/queries/",
+    show_default=True,
+    shell_complete=completion.graph_uris,
+    help="The used query catalog graph.",
+)
 @click.option(
     "--accept",
     default="default",
@@ -420,6 +439,7 @@ def list_command(app: ApplicationContext, id_only: bool) -> None:
 def execute_command(  # noqa: PLR0913
     app: ApplicationContext,
     queries: tuple[str, ...],
+    catalog_graph: str,
     accept: str,
     no_imports: bool,
     base64: bool,
@@ -453,9 +473,14 @@ def execute_command(  # noqa: PLR0913
     app.echo_debug("Parameter: " + str(placeholder))
     for file_or_uri in queries:
         app.echo_debug(f"Start of execution: {file_or_uri} with " f"placeholder {placeholder}")
-        executed_query: SparqlQuery = QueryCatalog().get_query(file_or_uri, placeholder=placeholder)
+        executed_query: SparqlQuery = QueryCatalog(graph=catalog_graph).get_query(
+            file_or_uri, placeholder=placeholder
+        )
         if executed_query is None:
-            raise ClickException(f"{file_or_uri} is neither a (readable) file nor a query URI.")
+            raise click.UsageError(
+                f"{file_or_uri} is neither a (readable) file nor "
+                f"a query URI in the catalog graph {catalog_graph}"
+            )
         app.echo_debug(
             f"Execute ({executed_query.query_type}): "
             f"{executed_query.label} < {executed_query.url}"
@@ -499,8 +524,15 @@ def execute_command(  # noqa: PLR0913
 @click.argument(
     "QUERIES", nargs=-1, required=True, shell_complete=completion.remote_queries_and_sparql_files
 )
+@click.option(
+    "--catalog-graph",
+    default="https://ns.eccenca.com/data/queries/",
+    show_default=True,
+    shell_complete=completion.graph_uris,
+    help="The used query catalog graph.",
+)
 @click.pass_obj
-def open_command(app: ApplicationContext, queries: tuple[str, ...]) -> None:
+def open_command(app: ApplicationContext, queries: tuple[str, ...], catalog_graph: str) -> None:
     """Open queries in the editor of the query catalog in your browser.
 
     With this command, you can open (remote) queries from the query catalog in
@@ -512,10 +544,13 @@ def open_command(app: ApplicationContext, queries: tuple[str, ...]) -> None:
     opening multiple browser tabs.
     """
     for file_or_uri in queries:
-        opened_query = QueryCatalog().get_query(file_or_uri)
+        opened_query = QueryCatalog(graph=catalog_graph).get_query(file_or_uri)
         if opened_query is None:
-            raise ClickException(f"{file_or_uri} is neither a (readable) file nor a query URI.")
-        open_query_uri = opened_query.get_editor_url()
+            raise click.UsageError(
+                f"{file_or_uri} is neither a (readable) file nor "
+                f"a query URI in the catalog graph {catalog_graph}"
+            )
+        open_query_uri = opened_query.get_editor_url(graph=catalog_graph)
         app.echo_debug(f"Open {file_or_uri}: {open_query_uri}")
         click.launch(open_query_uri)
 
@@ -571,7 +606,7 @@ def status_command(
         queries = query_status_list.apply_filters(ctx=ctx, filter_=filter_)
 
     if query_id and len(queries) == 0:
-        raise UsageError(f"Query with ID '{query_id}' does not exist (anymore).")
+        raise click.UsageError(f"Query with ID '{query_id}' does not exist (anymore).")
 
     if raw:
         app.echo_info_json(queries)
@@ -666,14 +701,14 @@ def replay_command(  # noqa: PLR0913
     other data.
     """
     if loops <= 0:
-        raise UsageError("Please set a positive loops integer value (>=1).")
+        raise click.UsageError("Please set a positive loops integer value (>=1).")
     try:
         with Path(replay_file).open(encoding="utf8") as _:
             input_queries = load(_)
     except JSONDecodeError as error:
-        raise ClickException(f"File {replay_file} is not a valid JSON document.") from error
+        raise click.ClickException(f"File {replay_file} is not a valid JSON document.") from error
     if len(input_queries) == 0:
-        raise ClickException(f"File {replay_file} contains no queries.")
+        raise click.ClickException(f"File {replay_file} contains no queries.")
     app.echo_debug(f"File {replay_file} contains {len(input_queries)} queries.")
 
     statistic = ReplayStatistics(app=app, label=run_label)

cmem_cmemc/commands/store.py

@@ -10,6 +10,7 @@ from cmem.cmempy.dp.admin import create_showcase_data, delete_bootstrap_data, im
 from cmem.cmempy.dp.admin.backup import get_zip, post_zip
 from cmem.cmempy.dp.workspace import migrate_workspaces
 from cmem.cmempy.health import get_dp_info
+from cmem.cmempy.workspace import reload_workspace
 from jinja2 import Template
 
 from cmem_cmemc.command import CmemcCommand
@@ -53,7 +54,7 @@ def bootstrap_command(app: ApplicationContext, import_: bool, remove: bool) -> N
 
     Note: The import part of this command is equivalent to the 'bootstrap-data' migration recipe
     """
-    if import_ and remove or not import_ and not remove:
+    if (import_ and remove) or (not import_ and not remove):
         raise UsageError("Either use the --import or the --remove option.")
     if import_:
         app.echo_info("Update or import bootstrap data ... ", nl=False)
@@ -99,12 +100,15 @@ def showcase_command(app: ApplicationContext, scale: int, create: bool, delete:
         raise UsageError("Either use the --create or the --delete flag.")
     if delete:
         raise NotImplementedError(
-            "This feature is not implemented yet. " "Please delete the graphs manually."
+            "This feature is not implemented yet. Please delete the graphs manually."
         )
     if create:
         app.echo_info(f"Create showcase data with scale factor {scale} ... ", nl=False)
         create_showcase_data(scale_factor=scale)
         app.echo_success("done")
+        app.echo_info("Reload workspace  ... ", nl=False)
+        reload_workspace()
+        app.echo_success("done")
 
 
 @click.command(cls=CmemcCommand, name="export")

cmem_cmemc/commands/validation.py

@@ -766,11 +766,13 @@ def export_command(
         f" to {output_file} ... ",
         nl=False,
     )
-    with Path(output_file, mode="w", encoding="utf-8") as file:
+    output_path = Path(output_file)
+
+    with output_path.open("w", encoding="utf-8") as file:
         if format_ == "XML":
-            file.write_text(_reports_to_junit(reports))
+            file.write(_reports_to_junit(reports))
         if format_ == "JSON":
-            file.write_text(json.dumps(reports, indent=2))
+            json.dump(reports, file, indent=2)
     app.echo_success("done")
     if exit_1 == "error" and overall_violations > 0:
         app.echo_error(

cmem_cmemc/commands/vocabulary.py

@@ -69,7 +69,9 @@ WHERE {{}}
 """
 
 
-def _validate_vocabs_to_process(iris: tuple[str], filter_: str, all_flag: bool) -> list[str]:
+def _validate_vocabs_to_process(
+    iris: tuple[str], filter_: str, all_flag: bool, replace: bool = False
+) -> list[str]:
     """Return a list of vocabulary IRTs which will be processed.
 
     list is without duplicates, and validated if they exist
@@ -85,6 +87,8 @@ def _validate_vocabs_to_process(iris: tuple[str], filter_: str, all_flag: bool)
         if filter_ == "installed":  # uninstall command
             return [_ for _ in all_vocabs if all_vocabs[_]["installed"]]
         # install command
+        if replace:
+            return list(all_vocabs)
         return [_ for _ in all_vocabs if not all_vocabs[_]["installed"]]
 
     vocabs_to_process = list(set(iris))  # avoid double removal / installation
@@ -96,7 +100,7 @@ def _validate_vocabs_to_process(iris: tuple[str], filter_: str, all_flag: bool)
         if filter_ == "installable":  # install command
             if _ not in all_vocabs:
                 raise click.UsageError(f"Vocabulary {_} does not exist.")
-            if all_vocabs[_]["installed"]:
+            if all_vocabs[_]["installed"] and not replace:
                 raise click.UsageError(f"Vocabulary {_} already installed.")
     return vocabs_to_process
 
@@ -290,15 +294,20 @@ def list_command(app: ApplicationContext, id_only: bool, filter_: str, raw: bool
 @click.option(
     "-a", "--all", "all_", is_flag=True, help="Install all vocabularies from the catalog."
 )
+@click.option(
+    "--replace", is_flag=True, help="Replace (overwrite) existing vocabulary, if present."
+)
 @click.pass_obj
-def install_command(app: ApplicationContext, iris: tuple[str], all_: bool) -> None:
+def install_command(app: ApplicationContext, iris: tuple[str], all_: bool, replace: bool) -> None:
     """Install one or more vocabularies from the catalog.
 
     Vocabularies are identified by their graph IRI.
     Installable vocabularies can be listed with the
     vocabulary list command.
     """
-    vocabs_to_install = _validate_vocabs_to_process(iris=iris, filter_="installable", all_flag=all_)
+    vocabs_to_install = _validate_vocabs_to_process(
+        iris=iris, filter_="installable", all_flag=all_, replace=replace
+    )
     count: int = len(vocabs_to_install)
     for current, vocab in enumerate(vocabs_to_install, start=1):
         app.echo_info(f"Install vocabulary {current}/{count}: {vocab} ... ", nl=False)