esgvoc 0.2.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

esgvoc/cli/get.py

@@ -1,7 +1,10 @@
 
 from typing import Any
-from esgvoc.api.projects import find_terms_in_collection, find_terms_in_project, get_all_collections_in_project, get_all_projects, get_all_terms_in_collection
-from esgvoc.api.universe import find_terms_in_data_descriptor, find_terms_in_universe, get_all_data_descriptors_in_universe, get_all_terms_in_data_descriptor
+from esgvoc.api.projects import get_all_collections_in_project, get_all_projects, \
+    get_all_terms_in_collection, get_term_in_project, get_term_in_collection
+from esgvoc.api.universe import find_terms_in_data_descriptor, find_terms_in_universe, \
+    get_all_data_descriptors_in_universe, get_all_terms_in_data_descriptor, get_term_in_data_descriptor, \
+    get_term_in_universe
 from pydantic import BaseModel
 from requests import logging
 from rich.table import Table
@@ -19,7 +22,7 @@ def validate_key_format(key: str):
     """
     Validate if the key matches the XXXX:YYYY:ZZZZ format.
     """
-    if not re.match(r"^[a-zA-Z0-9\/_]*:[a-zA-Z0-9\/_]*:[a-zA-Z0-9\/_]*$", key):
+    if not re.match(r"^[a-zA-Z0-9\/_]*:[a-zA-Z0-9\/_]*:[a-zA-Z0-9\/_.]*$", key):
         raise typer.BadParameter(f"Invalid key format: {key}. Must be XXXX:YYYY:ZZZZ.")
     return key.split(":")
 
@@ -28,11 +31,11 @@ def handle_universe(data_descriptor_id:str|None,term_id:str|None, options=None):
     _LOGGER.debug(f"Handling universe with data_descriptor_id={data_descriptor_id}, term_id={term_id}") 
 
     if data_descriptor_id and term_id:
-        return find_terms_in_data_descriptor(data_descriptor_id,term_id,options)
+        return get_term_in_data_descriptor(data_descriptor_id, term_id, options)
         # BaseModel|dict[str: BaseModel]|None:
 
     elif term_id:
-        return find_terms_in_universe(term_id,options)
+        return get_term_in_universe(term_id, options)
         # dict[str, BaseModel] | dict[str, dict[str, BaseModel]] | None:
 
 
@@ -48,11 +51,11 @@ def handle_project(project_id:str,collection_id:str|None,term_id:str|None,option
     _LOGGER.debug(f"Handling project {project_id} with Y={collection_id}, Z={term_id}, options = {options}")
     
     if project_id and collection_id and term_id:
-        return find_terms_in_collection(project_id,collection_id,term_id)
+        return get_term_in_collection(project_id, collection_id, term_id, options)
         # BaseModel|dict[str: BaseModel]|None:
 
     elif term_id:
-        return find_terms_in_project(project_id, term_id,options)
+        return get_term_in_project(project_id, term_id,options)
         # dict[str, BaseModel] | dict[str, dict[str, BaseModel]] | None:
 
 
@@ -96,30 +99,31 @@ def display(data:Any):
 @app.command()
 def get(keys: list[str] = typer.Argument(..., help="List of keys in XXXX:YYYY:ZZZZ format")):
     """
-    Retrieve a specific value from the database system.
-    This command allows you to fetch a value by specifying the universe/project, data_descriptor/collection, 
-    and term in a structured format.
-
-    Usage:
-        `get <project>:<collection>:<term>`
-
-    Arguments:
-        <project>        The name of the project to query. like `cmip6plus`
-        <collection>     The name of the collection in the specified database.
-        <term>           The name or term within the specified collection.
-
+    Retrieve a specific value from the database system.\n
+    This command allows you to fetch a value by specifying the universe/project, data_descriptor/collection,
+    and term in a structured format.\n
+    \n
+
+    Usage:\n
+        `get <project>:<collection>:<term>`\n
+    \n
+    Arguments:\n
+        <project>\tThe project id to query. like `cmip6plus`\n
+        <collection>\tThe collection id in the specified database.\n
+        <term>\t\tThe term id within the specified collection.\n
+    \n
     Example:
-        To retrieve the value from the "cmip6plus" project, under the "institution_id" column, 
-        in the term with the identifier "ipsl", you would use:
-            `get cmip6plus:institution_id:ipsl`
-        The default project is the universe CV : the argument would be like `universe:institution:ipsl` or `:institution:ipsl`
-        - to get list of available term from universe institution `:institution:` 
-
-    Notes:
-        - Ensure data exist in your system before using this command (use status command to see whats available).
-        - Use a colon (`:`) to separate the parts of the argument.  
-        - if more than one argument is given i.e get X:Y:Z A:B:C the 2 results are appended. 
-
+        To retrieve the value from the "cmip6plus" project, under the "institution_id" column, the term with the identifier "ipsl", you would use: \n 
+            `get cmip6plus:institution_id:ipsl`\n
+        The default project is the universe CV : the argument would be like `universe:institution:ipsl` or `:institution:ipsl` \n
+        - to get list of available term from universe institution `:institution:` \n
+        \n
+    \n
+    Notes:\n
+        - Ensure data exist in your system before using this command (use `esgvoc status` command to see whats available).\n
+        - Use a colon (`:`) to separate the parts of the argument.  \n
+        - if more than one argument is given i.e get X:Y:Z A:B:C the 2 results are appended. \n
+    \n
     """ 
     known_projects = get_all_projects()
 
@@ -133,7 +137,7 @@ def get(keys: list[str] = typer.Argument(..., help="List of keys in XXXX:YYYY:ZZ
         if where == "" or where=="universe": 
             res = handle_universe(what,who)
         elif where in known_projects:
-            res = handle_project(where,what,who,{})
+            res = handle_project(where,what,who,None)
         else:
             res = handle_unknown(where,what,who)
         

esgvoc/cli/install.py

@@ -1,14 +1,17 @@
 import typer
-from esgvoc.core.service import esg_voc
+from esgvoc.core.service import current_state
 
 app = typer.Typer()
 
 @app.command()
 def install():
-    """
-    Command to clone and build necessary db with the latest available version
-    
-    """
-    esg_voc.install()
-    
-    
+    """Initialize default config and apply settings"""
+    try:
+        typer.echo("Initialized default configuration")
+        current_state.synchronize_all()
+    except Exception as e:
+        typer.echo(f"Error during installation: {str(e)}", err=True)
+        raise typer.Exit(1)
+
+if __name__ == "__main__":
+    app()

esgvoc/cli/main.py

@@ -1,5 +1,4 @@
 import typer
-from esgvoc.cli.config import app as config_app
 from esgvoc.cli.get import app as get_app
 from esgvoc.cli.status import app as status_app
 from esgvoc.cli.valid import app as valid_app
@@ -8,7 +7,6 @@ from esgvoc.cli.drs import app as drs_app
 app = typer.Typer()
 
 # Register the subcommands
-app.add_typer(config_app)
 app.add_typer(get_app)
 app.add_typer(status_app)
 app.add_typer(valid_app)

esgvoc/cli/status.py

@@ -20,17 +20,17 @@ def status():
     i.e summary of version of usable ressources (between remote/cached)  
     
     """
-
-    service.state_service.get_state_summary()
+    assert(service.current_state is not None)
+    service.current_state.get_state_summary()
     #display(service.state_service.table())
 
 
     table = Table(show_header=False, show_lines=True)
 
     table.add_row("","Remote github repo","Local repository","Cache Database", style = "bright_green")
-    table.add_row("Universe path",service.state_service.universe.github_repo,service.state_service.universe.local_path,service.state_service.universe.db_path, style = "white")
-    table.add_row("Version",service.state_service.universe.github_version,service.state_service.universe.local_version,service.state_service.universe.db_version, style="bright_blue")
-    for proj_name,proj in service.state_service.projects.items():
+    table.add_row("Universe path",service.current_state.universe.github_repo,service.current_state.universe.local_path,service.current_state.universe.db_path, style = "white")
+    table.add_row("Version",service.current_state.universe.github_version,service.current_state.universe.local_version,service.current_state.universe.db_version, style="bright_blue")
+    for proj_name,proj in service.current_state.projects.items():
         table.add_row(f"{proj_name} path",proj.github_repo,proj.local_path,proj.db_path, style="white")
         table.add_row("Version",proj.github_version,proj.local_version,proj.db_version,style ="bright_blue")
     display(table)

esgvoc/cli/valid.py

@@ -38,52 +38,52 @@ def valid(
     verbose: bool = typer.Option(False, "-v", "--verbose", help="Provide detailed validation results")
 ):
     """
-    Validates one or more strings against specified Project:Collection:Term configurations.
-
-    Depending on the provided key structure, the function performs different validation operations:
-    - If all are None (e.g., "::"), validates the term across all projects (`valid_term_in_all_projects`).
-    - If Term is None (e.g., "Project:Collection:"), validates the term in the specified collection (`valid_term_in_collection`).
-    - If Term and Collection are None (e.g., "Project::"), validates the term in the specified project (`valid_term_in_project`).
-    - If all are specified (e.g., "Project:Collection:Term"), validates the term exactly (`valid_term`).
-
-    Parameters:
-        strings_targets (List[str]): A list of validation pairs, where each pair consists of:
-            - A string to validate.
-            - A key in the form '<Project:Collection:Term>'.
-    Usage :
-        Valid one: 
-        esgvocab valid IPSL cmip6plus:institution_id:ipsl
-        esgvocab valid IPSL cmip6plus:institution_id:
-        esgvocab valid IPSL cmip6plus::
-        esgvocab valid IPSL ::
-        
-        Unvalid one:
-        esgvocab valid IPSL_invalid cmip6plus:institution_id:ipsl
-        esgvocab valid IPSL cmip6plus:institution_id:isl <= term cant be found
-        esgvocab valid IPSL cmip6plus:institutin_id:ispl <= collection cant be found
-        esgvocab valid IPSL cmip6pls:institution_id:ispl <= project cant be found
-
-        Multiple validation for all known projects: 
-        esgvocab valid IPSL :: IPS :: 
-            result will be [True, False]
-        
-        esgvocab valid --verbose IPS :: IPSL :: 
-            result will be 
-            ┏━━━━━━━━┳━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-            ┃ String ┃ Key ┃ Result     ┃ Errors                      ┃
-            ┡━━━━━━━━╇━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
-            │ IPS    │ ::  │ ❌ Invalid │ did not found matching term │
-            │ IPSL   │ ::  │ ✅ Valid   │ None                        │
-            └────────┴─────┴────────────┴─────────────────────────────┘
-    Returns:
-        List[bool]: Validation results for each pair in the input.
+    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)

esgvoc/core/constants.py

@@ -10,4 +10,4 @@ PATTERN_JSON_KEY = 'regex'
 TERM_TYPE_JSON_KEY = 'type'
 DRS_SPECS_JSON_KEY = 'drs_name'
 SQLITE_FIRST_PK = 1
-DATA_DESCRIPTOR_JSON_KEY = "@base"
+DATA_DESCRIPTOR_JSON_KEY = "@base"

esgvoc/core/db/__init__.py

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

esgvoc/core/db/connection.py

@@ -1,11 +1,13 @@
-from pathlib import Path
 import json
+from pathlib import Path
+
 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
@@ -20,7 +22,7 @@ class DBConnection:
     def create_session(self) -> Session:
         return Session(self.engine)
 
-    def get_name(self) -> str|None:
+    def get_name(self) -> str | None:
         return self.name
 
     def get_file_path(self) -> Path:
@@ -28,4 +30,4 @@ class DBConnection:
 
 
 def read_json_file(json_file_path: Path) -> dict:
-    return json.loads(json_file_path.read_text())
+    return json.loads(json_file_path.read_text())

esgvoc/core/db/models/project.py

@@ -2,11 +2,14 @@ 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("project_db_creation")
 
 
@@ -27,34 +30,73 @@ class Collection(SQLModel, PkMixin, IdMixin, table=True):
     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="collections.pk")
     collection: Collection = Relationship(back_populates="terms")
-    __table_args__ = (sa.Index(
-             "drs_name_index", specs.sa_column["drs_name"]
+    __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="collections.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}. Abort.'
+        msg = f'unable to create SQlite file at {db_file_path}'
         _LOGGER.fatal(msg)
-        raise RuntimeError(msg) from e
+        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['collections'],
                                 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}. Abort.'
+        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);'
+            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=collections, content_rowid=pk);'
+            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 RuntimeError(msg) from e
+        raise EsgvocDbError(msg) from e
 
 
 if __name__ == "__main__":
-    pass
+    pass

esgvoc/core/db/models/universe.py

@@ -2,11 +2,13 @@ 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("universe_db_creation")
 
@@ -14,11 +16,11 @@ _LOGGER = logging.getLogger("universe_db_creation")
 class Universe(SQLModel, PkMixin, table=True):
     __tablename__ = "universes"
     git_hash: str
-    data_descriptors: list["DataDescriptor"] = Relationship(back_populates="universe")
+    data_descriptors: list["UDataDescriptor"] = Relationship(back_populates="universe")
 
 
-class DataDescriptor(SQLModel, PkMixin, IdMixin, table=True):
-    __tablename__ = "data_descriptors"
+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")
@@ -26,33 +28,70 @@ class DataDescriptor(SQLModel, PkMixin, IdMixin, table=True):
     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="data_descriptors.pk"
-    )
-    data_descriptor: DataDescriptor = Relationship(back_populates="terms")
+    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}. Abort.'
+        msg = f'unable to create SQLite file at {db_file_path}'
         _LOGGER.fatal(msg)
-        raise RuntimeError(msg) from e
+        raise EsgvocDbError(msg) from e
     try:
         # Avoid creating project tables.
         tables_to_be_created = [SQLModel.metadata.tables['uterms'],
-                                SQLModel.metadata.tables['data_descriptors'],
+                                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}. Abort.'
+        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);'
+            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);'
+            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 RuntimeError(msg) from e
+        raise EsgvocDbError(msg) from e
 
 
 if __name__ == "__main__":