esgvoc 2.0.2__py3-none-any.whl

esgvoc/cli/valid.py

@@ -0,0 +1,147 @@
+
+import re
+from typing import List
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from esgvoc.api.projects import valid_term, valid_term_in_all_projects, valid_term_in_collection, valid_term_in_project
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command()
+def valid(
+    strings_targets: List[str] = typer.Argument(
+        ...,
+        help=(
+            "Pairs of strings to validate against a key in the form '<StringToValidate> <Project:Collection:Term>'.\n"
+            "Multiple pairs can be provided. The key '<Project:Collection:Term>' consists of three parts:\n"
+            "- 'Project' (optional)\n"
+            "- 'Collection' (optional)\n"
+            "- 'Term' (optional)\n"
+            "Only the ':' separators are mandatory. For example:\n"
+            "  - 'my_string ::'\n"
+            "  - 'my_string Project::'\n"
+            "  - 'my_string Project:Collection:'\n"
+            "  - 'my_string Project:Collection:Term'\n"
+            "The function validates based on the provided parts."
+        )
+    ),
+    verbose: bool = typer.Option(False, "-v", "--verbose", help="Provide detailed validation results")
+):
+    """
+    Validates one or more strings against specified Project:Collection:Term configurations.\n
+     \n
+    Depending on the provided key structure, the function performs different validation operations:\n
+    - If all are None (e.g., "::"), validates the term across all projects (`valid_term_in_all_projects`).\n
+    - If Term is None (e.g., "Project:Collection:"), validates the term in the specified collection (`valid_term_in_collection`).\n
+    - If Term and Collection are None (e.g., "Project::"), validates the term in the specified project (`valid_term_in_project`).\n
+    - If all are specified (e.g., "Project:Collection:Term"), validates the term exactly (`valid_term`).\n
+\n
+    Parameters:\n
+        \tstrings_targets (List[str]): A list of validation pairs, where each pair consists of:\n
+            \t\t- A string to validate.\n
+            \t\t- A key in the form '<Project:Collection:Term>'.\n
+    Usage :\n
+        \tValid one:\n
+        \tesgvocab valid IPSL cmip6plus:institution_id:ipsl\n
+        \tesgvocab valid IPSL cmip6plus:institution_id:\n
+        \tesgvocab valid IPSL cmip6plus::\n
+        \tesgvocab valid IPSL ::\n
+        \n
+        \tUnvalid one:\n
+        \tesgvocab valid IPSL_invalid cmip6plus:institution_id:ipsl\n
+        \tesgvocab valid IPSL cmip6plus:institution_id:isl <= term cant be found\n
+        \tesgvocab valid IPSL cmip6plus:institutin_id:ispl <= collection cant be found\n
+        \tesgvocab valid IPSL cmip6pls:institution_id:ispl <= project cant be found\n
+        \n
+        \tMultiple validation for all known projects: \n
+        \tesgvocab valid IPSL :: IPS :: \n
+        \t\tresult will be [True, False]\n
+        \n
+        \tesgvocab valid --verbose IPS :: IPSL ::\n
+        \tresult will be \n
+        \t\t┏━━━━━━━━┳━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓\n
+        \t\t┃ String ┃ Key ┃ Result     ┃ Errors                      ┃\n
+        \t\t┡━━━━━━━━╇━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩\n
+        \t\t│ IPS    │ ::  │ ❌ Invalid │ did not found matching term │\n
+        \t\t│ IPSL   │ ::  │ ✅ Valid   │ None                        │\n
+        \t\t└────────┴─────┴────────────┴─────────────────────────────┘\n
+    Returns:\n
+        \tList[bool]: Validation results for each pair in the input.\n
+    """
+    results = []
+    detailed_results = []
+
+    # Combine string and target into pairs
+    pairs = [strings_targets[i] + " " + strings_targets[i + 1] for i in range(0, len(strings_targets), 2)]
+
+    # Validate each string against each target
+    for validation in pairs:
+        match = re.match(r"(.+)\s+([^:]*):([^:]*):([^:]*)", validation)
+        if not match:
+            console.print(f"[red]Invalid input format: {validation}[/red]")
+            results.append(False)
+            detailed_results.append({"validation": validation, "errors": ["Invalid input format"]})
+            continue
+
+        string_to_validate, project, collection, term = match.groups()
+        exception_message= None
+        try:
+            # Perform the appropriate validation
+            if project and collection and term:
+                validation_result = valid_term(string_to_validate, project, collection, term)
+            elif project and collection:
+                validation_result = valid_term_in_collection(string_to_validate, project, collection)
+            elif project:
+                validation_result = valid_term_in_project(string_to_validate, project)
+            else:
+                validation_result = valid_term_in_all_projects(string_to_validate)
+
+        except Exception as e:
+            validation_result=False
+            exception_message = repr(e)
+
+        # Handle validation result
+
+        if validation_result:
+            results.append(True)
+            detailed_results.append({"validation": validation, "errors": []})
+        else:
+            # Parse and collect errors for verbose mode
+            if validation_result == []:
+                detailed_results.append({"validation":validation, "errors":["did not found matching term"]})
+            results.append(False)
+            if project and collection and term and exception_message is None:
+                errors = [str(error) for error in validation_result.errors]
+                detailed_results.append({"validation": validation, "errors": errors})
+            if exception_message is not None:
+                detailed_results.append({"validation": validation, "errors": [exception_message]})
+
+
+    # Output results
+    if verbose:
+        table = Table(title="Validation Results")
+        table.add_column("String", style="cyan")
+        table.add_column("Key", style="magenta")
+        table.add_column("Result", style="green" if all(results) else "red")
+        table.add_column("Errors", style="red")
+
+        for detail in detailed_results:
+            validation = detail["validation"]
+            validation_parts = validation.split()
+            string = validation_parts[0]
+            key = validation_parts[1] if len(validation_parts) > 1 else "::"
+            result = "✅ Valid" if detail["errors"] == [] else "❌ Invalid"
+            print(detail)
+            errors = "\n".join(detail["errors"]) if detail["errors"] else "None"
+            table.add_row(string, key, result, errors)
+
+        console.print(table)
+    else:
+        console.print(results)
+
+    return results

esgvoc/core/constants.py

@@ -0,0 +1,17 @@
+DIRNAME_AND_FILENAME_SEPARATOR = "_"
+PROJECT_SPECS_FILENAME = "project_specs.yaml"
+DRS_SPECS_FILENAME = "drs_specs.yaml"
+CATALOG_SPECS_FILENAME = "catalog_specs.yaml"
+ATTRIBUTES_SPECS_FILENAME = "attr_specs.yaml"
+PROJECT_ID_JSON_KEY = "project_id"
+CONTEXT_FILENAME = "000_context.jsonld"
+CONTEXT_JSON_KEY = "@context"
+TERM_ID_JSON_KEY = "id"
+COMPOSITE_PARTS_JSON_KEY = "parts"
+COMPOSITE_SEPARATOR_JSON_KEY = "separator"
+COMPOSITE_REQUIRED_KEY = "is_required"
+PATTERN_JSON_KEY = "regex"
+TERM_TYPE_JSON_KEY = "type"
+DRS_SPECS_JSON_KEY = "drs_name"
+SQLITE_FIRST_PK = 1
+DATA_DESCRIPTOR_JSON_KEY = "@base"

esgvoc/core/data_handler.py

@@ -0,0 +1,206 @@
+import os
+import json
+import logging
+from functools import cached_property
+from typing import Any, Optional, Dict
+import requests
+from pyld import jsonld
+from pydantic import BaseModel, model_validator, ConfigDict
+
+# Configure logging
+_LOGGER = logging.getLogger(__name__)
+
+
+def unified_document_loader(uri: str) -> Dict:
+    """Load a document from a local file or a remote URI."""
+    if uri.startswith(("http://", "https://")):
+        response = requests.get(uri, headers={"accept": "application/json"}, verify=False)
+        if response.status_code == 200:
+            return response.json()
+        else:
+            _LOGGER.error(f"Failed to fetch remote document: {response.status_code} - {response.text}")
+            return {}
+    else:
+        with open(uri, "r") as f:
+            return json.load(f)
+
+
+class JsonLdResource(BaseModel):
+    uri: str
+    local_path: Optional[str] = None
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    @model_validator(mode="before")
+    @classmethod
+    def set_local_path(cls, values: Dict[str, Any]) -> Dict[str, Any]:
+        """Set the local path to an absolute path if provided."""
+        local_path = values.get("local_path")
+        if local_path:
+            values["local_path"] = os.path.abspath(local_path) + "/"
+        jsonld.set_document_loader(
+            lambda uri, options: {
+                "contextUrl": None,  # No special context URL
+                "documentUrl": uri,  # The document's actual URL
+                # The parsed JSON-LD document
+                "document": unified_document_loader(uri),
+            }
+        )
+        return values
+
+    @cached_property
+    def json_dict(self) -> Dict:
+        """Fetch the original JSON data."""
+        _LOGGER.debug(f"Fetching JSON data from {self.uri}")
+        return unified_document_loader(self.uri)
+
+    def _preprocess_nested_contexts(self, data: dict, context: dict) -> dict:
+        """
+        Pre-process data to resolve @base in nested @context definitions.
+        This works around pyld's limitation with scoped contexts.
+
+        Args:
+            data: The JSON-LD data to preprocess
+            context: The @context dictionary
+
+        Returns:
+            Preprocessed data with resolved nested contexts
+        """
+        if not isinstance(data, dict):
+            return data
+
+        result = {}
+
+        for key, value in data.items():
+            if key == "@context":
+                result[key] = value
+                continue
+
+            # Check if this term has a nested @context with @base
+            term_def = context.get(key, {})
+            if isinstance(term_def, dict) and "@context" in term_def:
+                nested_context = term_def["@context"]
+                base_url = nested_context.get("@base", "")
+
+                # If the value is a string and we have a @base, prepend it
+                if isinstance(value, str) and base_url and term_def.get("@type") == "@id":
+                    # Don't prepend if it's already an absolute URL
+                    if not value.startswith("http://") and not value.startswith("https://"):
+                        # Return as {"@id": "full_url"} to preserve @id semantics
+                        result[key] = {"@id": base_url + value}
+                    else:
+                        result[key] = {"@id": value}
+                elif isinstance(value, list):
+                    # Process each item in the list
+                    result[key] = []
+                    for item in value:
+                        if isinstance(item, dict):
+                            result[key].append(self._preprocess_nested_contexts(item, context))
+                        elif isinstance(item, str) and base_url and term_def.get("@type") == "@id":
+                            # Convert string items to {"@id": "..."} when @type is @id
+                            if not item.startswith("http://") and not item.startswith("https://"):
+                                result[key].append({"@id": base_url + item})
+                            else:
+                                result[key].append({"@id": item})
+                        else:
+                            result[key].append(item)
+                elif isinstance(value, dict):
+                    result[key] = self._preprocess_nested_contexts(value, context)
+                else:
+                    result[key] = value
+            elif isinstance(value, list):
+                # Process each item in the list
+                result[key] = []
+                for item in value:
+                    if isinstance(item, dict):
+                        result[key].append(self._preprocess_nested_contexts(item, context))
+                    else:
+                        result[key].append(item)
+            elif isinstance(value, dict):
+                result[key] = self._preprocess_nested_contexts(value, context)
+            else:
+                result[key] = value
+
+        return result
+
+    @cached_property
+    def expanded(self) -> Any:
+        """Expand the JSON-LD data with preprocessing for nested contexts."""
+        _LOGGER.debug(f"Expanding JSON-LD data for {self.uri}")
+
+        # Get the data and context
+        data = self.json_dict
+
+        # Get the context - it should already be the inner dictionary
+        context_dict = self.context
+        if isinstance(context_dict, dict) and "@context" in context_dict:
+            context_dict = context_dict["@context"]
+
+        # Preprocess to handle nested contexts with @base
+        preprocessed = self._preprocess_nested_contexts(data, context_dict)
+
+        # Add the context back if it was in the original data
+        if "@context" in data:
+            preprocessed["@context"] = data["@context"]
+
+        # Expand the preprocessed data
+        return jsonld.expand(preprocessed, options={"base": self.uri})
+
+    @cached_property
+    def context(self) -> Dict:
+        """Fetch and return the JSON content of the '@context'."""
+
+        context_data = JsonLdResource(uri="/".join(self.uri.split("/")[:-1]) + "/" + self.json_dict["@context"])
+        # Works only in relative path declaration
+
+        context_value = context_data.json_dict
+        if isinstance(context_value, str):
+            # It's a URI, fetch it
+            _LOGGER.info(f"Fetching context from URI: {context_value}")
+            return unified_document_loader(context_value)
+        elif isinstance(context_value, dict):
+            # Embedded context
+            _LOGGER.info("Using embedded context.")
+            return context_value
+        else:
+            _LOGGER.warning("No valid '@context' found.")
+            return {}
+
+    @cached_property
+    def normalized(self) -> str:
+        """Normalize the JSON-LD data."""
+        _LOGGER.info(f"Normalizing JSON-LD data for {self.uri}")
+        return jsonld.normalize(self.uri, options={"algorithm": "URDNA2015", "format": "application/n-quads"})
+
+    def _extract_model_key(self, uri: str) -> Optional[str]:
+        """Extract a model key from the URI."""
+        parts = uri.strip("/").split("/")
+        if len(parts) >= 2:
+            return parts[-2]
+        return None
+
+    @property
+    def info(self) -> str:
+        """Return a detailed summary of the data."""
+        res = f"{'#' * 100}\n"
+        res += f"###   {self.uri.split('/')[-1]}   ###\n"
+        res += f"JSON Version:\n {json.dumps(self.json_dict, indent=2)}\n"
+        res += f"URI: {self.uri}\n"
+        res += f"JSON Version:\n {json.dumps(self.json_dict, indent=2)}\n"
+        res += f"Expanded Version:\n {json.dumps(self.expanded, indent=2)}\n"
+        res += f"Normalized Version:\n {self.normalized}\n"
+        return res
+
+
+if __name__ == "__main__":
+    # For Universe
+    # online
+    # d = Data(uri = "https://espri-mod.github.io/mip-cmor-tables/activity/cmip.json")
+    # print(d.info)
+    # offline
+    # print(Data(uri = ".cache/repos/mip-cmor-tables/activity/cmip.json").info)
+    # for Project
+    # d = Data(uri = "https://espri-mod.github.io/CMIP6Plus_CVs/activity_id/cmip.json")
+    # print(d.info)
+    # offline
+    print(JsonLdResource(uri=".cache/repos/CMIP6Plus_CVs/activity_id/cmip.json").info)

esgvoc/core/db/__init__.py

@@ -0,0 +1,3 @@
+from esgvoc.core.db.connection import DBConnection, read_json_file
+
+__all__ = ["DBConnection", "read_json_file"]

esgvoc/core/db/connection.py

@@ -0,0 +1,40 @@
+import json
+from pathlib import Path
+
+import yaml
+from sqlalchemy import Engine
+from sqlmodel import Session, create_engine
+
+
+class DBConnection:
+    SQLITE_URL_PREFIX = 'sqlite://'
+
+    def __init__(self, db_file_path: Path, echo: bool = False) -> None:
+        self.engine = create_engine(f'{DBConnection.SQLITE_URL_PREFIX}/{db_file_path}', echo=echo)
+        self.name = db_file_path.stem
+        self.file_path = db_file_path.absolute()
+
+    def set_echo(self, echo: bool) -> None:
+        self.engine.echo = echo
+
+    def get_engine(self) -> Engine:
+        return self.engine
+
+    def create_session(self) -> Session:
+        return Session(self.engine)
+
+    def get_name(self) -> str | None:
+        return self.name
+
+    def get_file_path(self) -> Path:
+        return self.file_path
+
+
+def read_json_file(json_file_path: Path) -> dict:
+    return json.loads(json_file_path.read_text())
+
+
+def read_yaml_file(yaml_file_path: Path) -> dict:
+    with open(yaml_file_path, 'r') as file:
+        result = yaml.safe_load(file)
+    return result

esgvoc/core/db/models/mixins.py

@@ -0,0 +1,25 @@
+from enum import Enum
+
+from sqlmodel import Field
+
+
+class TermKind(Enum):
+    """
+    The kinds of term.
+    """
+    PLAIN = "plain"
+    """End written term."""
+    PATTERN = "pattern"
+    """Regex based terms"""
+    COMPOSITE = "composite"
+    """Term composed of terms."""
+    MIXED = 'mixed'
+    """To be defined."""
+
+
+class PkMixin:
+    pk: int | None = Field(default=None, primary_key=True)
+
+
+class IdMixin:
+    id: str = Field(index=True)

esgvoc/core/db/models/project.py

@@ -0,0 +1,102 @@
+import logging
+from pathlib import Path
+
+import sqlalchemy as sa
+from sqlalchemy import text
+from sqlalchemy.dialects.sqlite import JSON
+from sqlmodel import Column, Field, Relationship, SQLModel
+
+import esgvoc.core.db.connection as db
+from esgvoc.core.db.models.mixins import IdMixin, PkMixin, TermKind
+from esgvoc.core.exceptions import EsgvocDbError
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class Project(SQLModel, PkMixin, IdMixin, table=True):
+    __tablename__ = "projects"
+    specs: dict = Field(sa_column=sa.Column(JSON))
+    git_hash: str
+    collections: list["PCollection"] = Relationship(back_populates="project")
+
+
+class PCollection(SQLModel, PkMixin, IdMixin, table=True):
+    __tablename__ = "pcollections"
+    data_descriptor_id: str = Field(index=True)
+    context: dict = Field(sa_column=sa.Column(JSON))
+    project_pk: int | None = Field(default=None, foreign_key="projects.pk")
+    project: Project = Relationship(back_populates="collections")
+    terms: list["PTerm"] = Relationship(back_populates="collection")
+    term_kind: TermKind = Field(sa_column=Column(sa.Enum(TermKind)))
+
+
+# Well, the following instructions are not data duplication. It is more building an index.
+# Read: https://sqlite.org/fts5.html
+class PCollectionFTS5(SQLModel, PkMixin, IdMixin, table=True):
+    __tablename__ = "pcollections_fts5"
+    data_descriptor_id: str
+    context: dict = Field(sa_column=sa.Column(JSON))
+    project_pk: int | None = Field(default=None, foreign_key="projects.pk")
+    term_kind: TermKind = Field(sa_column=Column(sa.Enum(TermKind)))
+
+
+class PTerm(SQLModel, PkMixin, IdMixin, table=True):
+    __tablename__ = "pterms"
+    specs: dict = Field(sa_column=sa.Column(JSON))
+    kind: TermKind = Field(sa_column=Column(sa.Enum(TermKind)))
+    collection_pk: int | None = Field(default=None, foreign_key="pcollections.pk")
+    collection: PCollection = Relationship(back_populates="terms")
+    __table_args__ = (sa.Index("drs_name_index", specs.sa_column["drs_name"]), )  # type: ignore
+
+
+# Well, the following instructions are not data duplication. It is more building an index.
+# Read: https://sqlite.org/fts5.html
+class PTermFTS5(SQLModel, PkMixin, IdMixin, table=True):
+    __tablename__ = "pterms_fts5"
+    specs: dict = Field(sa_column=sa.Column(JSON))
+    kind: TermKind = Field(sa_column=Column(sa.Enum(TermKind)))
+    collection_pk: int | None = Field(default=None, foreign_key="pcollections.pk")
+
+
+def project_create_db(db_file_path: Path):
+    try:
+        connection = db.DBConnection(db_file_path)
+    except Exception as e:
+        msg = f'unable to create SQlite file at {db_file_path}'
+        _LOGGER.fatal(msg)
+        raise EsgvocDbError(msg) from e
+    try:
+        # Do not include pterms_fts5 table: it is build from a raw SQL query.
+        tables_to_be_created = [SQLModel.metadata.tables['projects'],
+                                SQLModel.metadata.tables['pcollections'],
+                                SQLModel.metadata.tables['pterms']]
+        SQLModel.metadata.create_all(connection.get_engine(), tables=tables_to_be_created)
+    except Exception as e:
+        msg = f'unable to create tables in SQLite database at {db_file_path}'
+        _LOGGER.fatal(msg)
+        raise EsgvocDbError(msg) from e
+    try:
+        with connection.create_session() as session:
+            sql_query = "CREATE VIRTUAL TABLE IF NOT EXISTS pterms_fts5 USING " + \
+                        "fts5(pk, id, specs, kind, collection_pk, content=pterms, content_rowid=pk, prefix=3);"
+            session.exec(text(sql_query))  # type: ignore
+            session.commit()
+    except Exception as e:
+        msg = f'unable to create table pterms_fts5 for {db_file_path}'
+        _LOGGER.fatal(msg)
+        raise EsgvocDbError(msg) from e
+    try:
+        with connection.create_session() as session:
+            sql_query = 'CREATE VIRTUAL TABLE IF NOT EXISTS pcollections_fts5 USING ' + \
+                        'fts5(pk, id, data_descriptor_id, context, project_pk, ' + \
+                        'term_kind, content=pcollections, content_rowid=pk, prefix=3);'
+            session.exec(text(sql_query))  # type: ignore
+            session.commit()
+    except Exception as e:
+        msg = f'unable to create table pcollections_fts5 for {db_file_path}'
+        _LOGGER.fatal(msg)
+        raise EsgvocDbError(msg) from e
+
+
+if __name__ == "__main__":
+    pass

esgvoc/core/db/models/universe.py

@@ -0,0 +1,98 @@
+import logging
+from pathlib import Path
+
+import sqlalchemy as sa
+from sqlalchemy import text
+from sqlalchemy.dialects.sqlite import JSON
+from sqlmodel import Column, Field, Relationship, SQLModel
+
+import esgvoc.core.db.connection as db
+from esgvoc.core.db.models.mixins import IdMixin, PkMixin, TermKind
+from esgvoc.core.exceptions import EsgvocDbError
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class Universe(SQLModel, PkMixin, table=True):
+    __tablename__ = "universes"
+    git_hash: str
+    data_descriptors: list["UDataDescriptor"] = Relationship(back_populates="universe")
+
+
+class UDataDescriptor(SQLModel, PkMixin, IdMixin, table=True):
+    __tablename__ = "udata_descriptors"
+    context: dict = Field(sa_column=sa.Column(JSON))
+    universe_pk: int | None = Field(default=None, foreign_key="universes.pk")
+    universe: Universe = Relationship(back_populates="data_descriptors")
+    terms: list["UTerm"] = Relationship(back_populates="data_descriptor")
+    term_kind: TermKind = Field(sa_column=Column(sa.Enum(TermKind)))
+
+
+# Well, the following instructions are not data duplication. It is more building an index.
+# Read: https://sqlite.org/fts5.html
+class UDataDescriptorFTS5(SQLModel, PkMixin, IdMixin, table=True):
+    __tablename__ = "udata_descriptors_fts5"
+    context: dict = Field(sa_column=sa.Column(JSON))
+    universe_pk: int | None = Field(default=None, foreign_key="universes.pk")
+    term_kind: TermKind = Field(sa_column=Column(sa.Enum(TermKind)))
+
+
+class UTerm(SQLModel, PkMixin, IdMixin, table=True):
+    __tablename__ = "uterms"
+    specs: dict = Field(sa_column=sa.Column(JSON))
+    kind: TermKind = Field(sa_column=Column(sa.Enum(TermKind)))
+    data_descriptor_pk: int | None = Field(default=None, foreign_key="udata_descriptors.pk")
+    data_descriptor: UDataDescriptor = Relationship(back_populates="terms")
+
+
+# Well, the following instructions are not data duplication. It is more building an index.
+# Read: https://sqlite.org/fts5.html
+class UTermFTS5(SQLModel, PkMixin, IdMixin, table=True):
+    __tablename__ = "uterms_fts5"
+    specs: dict = Field(sa_column=sa.Column(JSON))
+    kind: TermKind = Field(sa_column=Column(sa.Enum(TermKind)))
+    data_descriptor_pk: int | None = Field(default=None, foreign_key="udata_descriptors.pk")
+
+
+def universe_create_db(db_file_path: Path) -> None:
+    try:
+        connection = db.DBConnection(db_file_path)
+    except Exception as e:
+        msg = f'unable to create SQLite file at {db_file_path}'
+        _LOGGER.fatal(msg)
+        raise EsgvocDbError(msg) from e
+    try:
+        # Avoid creating project tables.
+        tables_to_be_created = [SQLModel.metadata.tables['uterms'],
+                                SQLModel.metadata.tables['udata_descriptors'],
+                                SQLModel.metadata.tables['universes']]
+        SQLModel.metadata.create_all(connection.get_engine(), tables=tables_to_be_created)
+    except Exception as e:
+        msg = f'unable to create tables in SQLite database at {db_file_path}'
+        _LOGGER.fatal(msg)
+        raise EsgvocDbError(msg) from e
+    try:
+        with connection.create_session() as session:
+            sql_query = 'CREATE VIRTUAL TABLE IF NOT EXISTS uterms_fts5 USING ' + \
+                        'fts5(pk, id, specs, kind, data_descriptor_pk, content=uterms, content_rowid=pk, prefix=3);'
+            session.exec(text(sql_query))  # type: ignore
+            session.commit()
+    except Exception as e:
+        msg = f'unable to create table uterms_fts5 for {db_file_path}'
+        _LOGGER.fatal(msg)
+        raise EsgvocDbError(msg) from e
+    try:
+        with connection.create_session() as session:
+            sql_query = 'CREATE VIRTUAL TABLE IF NOT EXISTS udata_descriptors_fts5 USING ' + \
+                        'fts5(pk, id, universe_pk, context, ' + \
+                        'term_kind, content=udata_descriptors, content_rowid=pk, prefix=3);'
+            session.exec(text(sql_query))  # type: ignore
+            session.commit()
+    except Exception as e:
+        msg = f'unable to create table udata_descriptors_fts5 for {db_file_path}'
+        _LOGGER.fatal(msg)
+        raise EsgvocDbError(msg) from e
+
+
+if __name__ == "__main__":
+    pass