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

esgvoc/api/projects.py

@@ -1,91 +1,95 @@
 import re
-from typing import Sequence
+from typing import Iterable, Sequence
+
+from sqlalchemy import text
+from sqlmodel import Session, and_, col, select
 
 import esgvoc.api.universe as universe
-import esgvoc.core.constants
+import esgvoc.core.constants as constants
 import esgvoc.core.service as service
-from esgvoc.api._utils import (get_universe_session, instantiate_pydantic_term,
-                               instantiate_pydantic_terms)
-from esgvoc.api.report import (ProjectTermError, UniverseTermError,
-                               ValidationError, ValidationReport)
-from esgvoc.api.search import MatchingTerm, SearchSettings, _create_str_comparison_expression
+from esgvoc.api.data_descriptors.data_descriptor import DataDescriptor
 from esgvoc.api.project_specs import ProjectSpecs
+from esgvoc.api.report import ProjectTermError, UniverseTermError, ValidationReport
+from esgvoc.api.search import (
+    Item,
+    MatchingTerm,
+    execute_find_item_statements,
+    execute_match_statement,
+    generate_matching_condition,
+    get_universe_session,
+    handle_rank_limit_offset,
+    instantiate_pydantic_term,
+    instantiate_pydantic_terms,
+)
 from esgvoc.core.db.connection import DBConnection
 from esgvoc.core.db.models.mixins import TermKind
-from esgvoc.core.db.models.project import Collection, Project, PTerm
+from esgvoc.core.db.models.project import (
+    Collection,
+    PCollectionFTS5,
+    Project,
+    PTerm,
+    PTermFTS5,
+)
 from esgvoc.core.db.models.universe import UTerm
-from pydantic import BaseModel
-from sqlmodel import Session, and_, select
-
+from esgvoc.core.exceptions import EsgvocDbError, EsgvocNotFoundError, EsgvocNotImplementedError, EsgvocValueError
 
 # [OPTIMIZATION]
 _VALID_TERM_IN_COLLECTION_CACHE: dict[str, list[MatchingTerm]] = dict()
-_VALID_VALUE_AGAINST_GIVEN_TERM_CACHE: dict[str, list[ValidationError]] = dict()
+_VALID_VALUE_AGAINST_GIVEN_TERM_CACHE: dict[str, list[UniverseTermError | ProjectTermError]] = dict()
 
 
-def get_project_specs(project_id: str) -> ProjectSpecs:
-    project_specs = find_project(project_id)
-    if not project_specs:
-        msg = f'Unable to find project {project_id}'
-        raise ValueError(msg)
-    try:
-        result = ProjectSpecs(**project_specs)
-    except Exception as e:
-        msg = f'Unable to read specs in project {project_id}'
-        raise RuntimeError(msg) from e
-    return result
-
+def _get_project_connection(project_id: str) -> DBConnection | None:
+    if project_id in service.current_state.projects:
+        return service.current_state.projects[project_id].db_connection
+    else:
+        return None
 
-def _get_project_connection(project_id: str) -> DBConnection|None:
-    return service.state_service.projects[project_id].db_connection
 
 def _get_project_session_with_exception(project_id: str) -> Session:
-    if connection:=_get_project_connection(project_id):
+    if connection := _get_project_connection(project_id):
         project_session = connection.create_session()
         return project_session
     else:
-        raise ValueError(f'unable to find project {project_id}')
-    
+        raise EsgvocNotFoundError(f"unable to find project '{project_id}'")
 
-def _resolve_term(term_composite_part: dict,
+
+def _resolve_term(composite_term_part: dict,
                   universe_session: Session,
-                  project_session: Session) -> UTerm|PTerm:
+                  project_session: Session) -> UTerm | PTerm:
     # First find the term in the universe than in the current project
-    term_id = term_composite_part[esgvoc.core.constants.TERM_ID_JSON_KEY]
-    term_type = term_composite_part[esgvoc.core.constants.TERM_TYPE_JSON_KEY]
-    uterms = universe._find_terms_in_data_descriptor(data_descriptor_id=term_type,
-                                                     term_id=term_id,
-                                                     session=universe_session,
-                                                     settings=None)
-    if uterms:
-        return uterms[0]
+    term_id = composite_term_part[constants.TERM_ID_JSON_KEY]
+    term_type = composite_term_part[constants.TERM_TYPE_JSON_KEY]
+    uterm = universe._get_term_in_data_descriptor(data_descriptor_id=term_type,
+                                                  term_id=term_id,
+                                                  session=universe_session)
+    if uterm:
+        return uterm
     else:
-        pterms = _find_terms_in_collection(collection_id=term_type,
-                                           term_id=term_id,
-                                           session=project_session,
-                                           settings=None)
-    if pterms:
-        return pterms[0]
+        pterm = _get_term_in_collection(collection_id=term_type,
+                                        term_id=term_id,
+                                        session=project_session)
+    if pterm:
+        return pterm
     else:
-        msg = f'unable to find the term {term_id} in {term_type}'
-        raise RuntimeError(msg)           
+        msg = f"unable to find the term '{term_id}' in '{term_type}'"
+        raise EsgvocNotFoundError(msg)
 
 
-def _get_term_composite_separator_parts(term: UTerm|PTerm) -> tuple[str, list]:
-    separator = term.specs[esgvoc.core.constants.COMPOSITE_SEPARATOR_JSON_KEY]
-    parts = term.specs[esgvoc.core.constants.COMPOSITE_PARTS_JSON_KEY]
+def _get_composite_term_separator_parts(term: UTerm | PTerm) -> tuple[str, list]:
+    separator = term.specs[constants.COMPOSITE_SEPARATOR_JSON_KEY]
+    parts = term.specs[constants.COMPOSITE_PARTS_JSON_KEY]
     return separator, parts
 
 
 # TODO: support optionality of parts of composite.
 # It is backtrack possible for more than one missing parts.
-def _valid_value_term_composite_with_separator(value: str,
-                                               term: UTerm|PTerm,
+def _valid_value_composite_term_with_separator(value: str,
+                                               term: UTerm | PTerm,
                                                universe_session: Session,
                                                project_session: Session)\
-                                                   -> list[ValidationError]:
+                                                   -> list[UniverseTermError | ProjectTermError]:
     result = list()
-    separator, parts = _get_term_composite_separator_parts(term)
+    separator, parts = _get_composite_term_separator_parts(term)
     if separator in value:
         splits = value.split(separator)
         if len(splits) == len(parts):
@@ -106,16 +110,20 @@ def _valid_value_term_composite_with_separator(value: str,
     return result
 
 
-def _transform_to_pattern(term: UTerm|PTerm,
+def _transform_to_pattern(term: UTerm | PTerm,
                           universe_session: Session,
                           project_session: Session) -> str:
     match term.kind:
         case TermKind.PLAIN:
-            result = term.specs[esgvoc.core.constants.DRS_SPECS_JSON_KEY]
+            if constants.DRS_SPECS_JSON_KEY in term.specs:
+                result = term.specs[constants.DRS_SPECS_JSON_KEY]
+            else:
+                raise EsgvocValueError(f"the term '{term.id}' doesn't have drs name. " +
+                                       "Can't validate it.")
         case TermKind.PATTERN:
-            result = term.specs[esgvoc.core.constants.PATTERN_JSON_KEY]
+            result = term.specs[constants.PATTERN_JSON_KEY]
         case TermKind.COMPOSITE:
-            separator, parts =  _get_term_composite_separator_parts(term)
+            separator, parts = _get_composite_term_separator_parts(term)
             result = ""
             for part in parts:
                 resolved_term = _resolve_term(part, universe_session, project_session)
@@ -123,22 +131,22 @@ def _transform_to_pattern(term: UTerm|PTerm,
                 result = f'{result}{pattern}{separator}'
             result = result.rstrip(separator)
         case _:
-            raise NotImplementedError(f'unsupported term kind {term.kind}')
+            raise EsgvocDbError(f"unsupported term kind '{term.kind}'")
     return result
 
 
 # TODO: support optionality of parts of composite.
 # It is backtrack possible for more than one missing parts.
-def _valid_value_term_composite_separator_less(value: str,
-                                               term: UTerm|PTerm,
+def _valid_value_composite_term_separator_less(value: str,
+                                               term: UTerm | PTerm,
                                                universe_session: Session,
                                                project_session: Session)\
-                                                   -> list[ValidationError]:
+                                                   -> list[UniverseTermError | ProjectTermError]:
     result = list()
     try:
         pattern = _transform_to_pattern(term, universe_session, project_session)
         try:
-            # Term patterns are meant to be validated individually.
+            # Patterns terms are meant to be validated individually.
             # So their regex are defined as a whole (begins by a ^, ends by a $).
             # As the pattern is a concatenation of plain or regex, multiple ^ and $ can exist.
             # The later, must be removed.
@@ -146,34 +154,34 @@ def _valid_value_term_composite_separator_less(value: str,
             pattern = f'^{pattern}$'
             regex = re.compile(pattern)
         except Exception as e:
-            msg = f'regex compilation error:\n{e}'
-            raise ValueError(msg) from e    
+            msg = f"regex compilation error while processing term '{term.id}'':\n{e}"
+            raise EsgvocDbError(msg) from e
         match = regex.match(value)
         if match is None:
             result.append(_create_term_error(value, term))
         return result
     except Exception as e:
-        msg = f'cannot validate separator less composite term {term.id}:\n{e}'        
-        raise RuntimeError(msg) from e
+        msg = f"cannot validate separator less composite term '{term.id}':\n{e}"
+        raise EsgvocNotImplementedError(msg) from e
 
 
-def _valid_value_for_term_composite(value: str,
-                                    term: UTerm|PTerm,
+def _valid_value_for_composite_term(value: str,
+                                    term: UTerm | PTerm,
                                     universe_session: Session,
                                     project_session: Session)\
-                                        -> list[ValidationError]:
+                                        -> list[UniverseTermError | ProjectTermError]:
     result = list()
-    separator, _ = _get_term_composite_separator_parts(term)
+    separator, _ = _get_composite_term_separator_parts(term)
     if separator:
-        result = _valid_value_term_composite_with_separator(value, term, universe_session,
+        result = _valid_value_composite_term_with_separator(value, term, universe_session,
                                                             project_session)
     else:
-        result = _valid_value_term_composite_separator_less(value, term, universe_session,
+        result = _valid_value_composite_term_separator_less(value, term, universe_session,
                                                             project_session)
     return result
 
 
-def _create_term_error(value: str, term: UTerm|PTerm) -> ValidationError:
+def _create_term_error(value: str, term: UTerm | PTerm) -> UniverseTermError | ProjectTermError:
     if isinstance(term, UTerm):
         return UniverseTermError(value=value, term=term.specs, term_kind=term.kind,
                                  data_descriptor_id=term.data_descriptor.id)
@@ -183,31 +191,35 @@ def _create_term_error(value: str, term: UTerm|PTerm) -> ValidationError:
 
 
 def _valid_value(value: str,
-                 term: UTerm|PTerm,
+                 term: UTerm | PTerm,
                  universe_session: Session,
-                 project_session: Session) -> list[ValidationError]:
+                 project_session: Session) -> list[UniverseTermError | ProjectTermError]:
     result = list()
     match term.kind:
         case TermKind.PLAIN:
-            if term.specs[esgvoc.core.constants.DRS_SPECS_JSON_KEY] != value:
-                result.append(_create_term_error(value, term))
+            if constants.DRS_SPECS_JSON_KEY in term.specs:
+                if term.specs[constants.DRS_SPECS_JSON_KEY] != value:
+                    result.append(_create_term_error(value, term))
+            else:
+                raise EsgvocValueError(f"the term '{term.id}' doesn't have drs name. " +
+                                       "Can't validate it.")
         case TermKind.PATTERN:
-            # OPTIM: Pattern can be compiled and stored for further matching.
-            pattern_match = re.match(term.specs[esgvoc.core.constants.PATTERN_JSON_KEY], value)
+            # TODO: Pattern can be compiled and stored for further matching.
+            pattern_match = re.match(term.specs[constants.PATTERN_JSON_KEY], value)
             if pattern_match is None:
                 result.append(_create_term_error(value, term))
         case TermKind.COMPOSITE:
-            result.extend(_valid_value_for_term_composite(value, term,
+            result.extend(_valid_value_for_composite_term(value, term,
                                                           universe_session,
                                                           project_session))
         case _:
-            raise NotImplementedError(f'unsupported term kind {term.kind}')
+            raise EsgvocDbError(f"unsupported term kind '{term.kind}'")
     return result
 
 
 def _check_value(value: str) -> str:
     if not value or value.isspace():
-        raise ValueError('value should be set')
+        raise EsgvocValueError('value should be set')
     else:
         return value
 
@@ -215,9 +227,9 @@ def _check_value(value: str) -> str:
 def _search_plain_term_and_valid_value(value: str,
                                        collection_id: str,
                                        project_session: Session) \
-                                        -> str|None:
+                                        -> str | None:
     where_expression = and_(Collection.id == collection_id,
-                            PTerm.specs[esgvoc.core.constants.DRS_SPECS_JSON_KEY] == f'"{value}"')
+                            PTerm.specs[constants.DRS_SPECS_JSON_KEY] == f'"{value}"')
     statement = select(PTerm).join(Collection).where(where_expression)
     term = project_session.exec(statement).one_or_none()
     return term.id if term else None
@@ -238,7 +250,7 @@ def _valid_value_against_all_terms_of_collection(value: str,
                 result.append(pterm.id)
         return result
     else:
-        raise RuntimeError(f'collection {collection.id} has no term')
+        raise EsgvocDbError(f"collection '{collection.id}' has no term")
 
 
 def _valid_value_against_given_term(value: str,
@@ -247,27 +259,20 @@ def _valid_value_against_given_term(value: str,
                                     term_id: str,
                                     universe_session: Session,
                                     project_session: Session)\
-                                        -> list[ValidationError]:
-    # [OPTIMIZATION]
+                                        -> list[UniverseTermError | ProjectTermError]:
+    # [OPTIMIZATION]
     key = value + project_id + collection_id + term_id
     if key in _VALID_VALUE_AGAINST_GIVEN_TERM_CACHE:
         result = _VALID_VALUE_AGAINST_GIVEN_TERM_CACHE[key]
     else:
-        try:
-            terms = _find_terms_in_collection(collection_id,
-                                              term_id,
-                                              project_session,
-                                              None)
-            if terms:
-                term = terms[0]
-                result = _valid_value(value, term, universe_session, project_session)
-            else:
-                raise ValueError(f'unable to find term {term_id} ' +
-                                 f'in collection {collection_id}')
-        except Exception as e:
-            msg = f'unable to valid term {term_id} ' +\
-                  f'in collection {collection_id}'
-            raise RuntimeError(msg) from e
+        term = _get_term_in_collection(collection_id,
+                                       term_id,
+                                       project_session)
+        if term:
+            result = _valid_value(value, term, universe_session, project_session)
+        else:
+            raise EsgvocNotFoundError(f"unable to find term '{term_id}' " +
+                                      f"in collection '{collection_id}'")
         _VALID_VALUE_AGAINST_GIVEN_TERM_CACHE[key] = result
     return result
 
@@ -280,11 +285,11 @@ def valid_term(value: str,
     """
     Check if the given value may or may not represent the given term. The functions returns
     a report that contains the possible errors.
-    
+
     Behavior based on the nature of the term:
         - plain term: the function try to match the value on the drs_name field.
-        - term pattern: the function try to match the value on the pattern field (regex).
-        - term composite: 
+        - pattern term: the function try to match the value on the pattern field (regex).
+        - composite term:
             - if the composite has got a separator, the function splits the value according to the\
               separator of the term then it try to match every part of the composite\
               with every split of the value.
@@ -292,7 +297,7 @@ def valid_term(value: str,
               composite so as to compare it as a regex to the value.
 
     If any of the provided ids (`project_id`, `collection_id` or `term_id`) is not found,
-    the function raises a ValueError.
+    the function raises a EsgvocNotFoundError.
 
     :param value: A value to be validated
     :type value: str
@@ -304,7 +309,7 @@ def valid_term(value: str,
     :type term_id: str
     :returns: A validation report that contains the possible errors
     :rtype: ValidationReport
-    :raises ValueError: If any of the provided ids is not found
+    :raises EsgvocNotFoundError: If any of the provided ids is not found
     """
     value = _check_value(value)
     with get_universe_session() as universe_session, \
@@ -320,18 +325,15 @@ def _valid_term_in_collection(value: str,
                               universe_session: Session,
                               project_session: Session) \
                                 -> list[MatchingTerm]:
-    # [OPTIMIZATION]
+    # [OPTIMIZATION]
     key = value + project_id + collection_id
     if key in _VALID_TERM_IN_COLLECTION_CACHE:
         result = _VALID_TERM_IN_COLLECTION_CACHE[key]
     else:
         value = _check_value(value)
         result = list()
-        collections = _find_collections_in_project(collection_id,
-                                                   project_session,
-                                                   None)
-        if collections:
-            collection = collections[0]
+        collection = _get_collection_in_project(collection_id, project_session)
+        if collection:
             match collection.term_kind:
                 case TermKind.PLAIN:
                     term_id_found = _search_plain_term_and_valid_value(value, collection_id,
@@ -349,8 +351,8 @@ def _valid_term_in_collection(value: str,
                                                    collection_id=collection_id,
                                                    term_id=term_id_found))
         else:
-            msg = f'unable to find collection {collection_id}'
-            raise ValueError(msg)
+            msg = f"unable to find collection '{collection_id}'"
+            raise EsgvocNotFoundError(msg)
         _VALID_TERM_IN_COLLECTION_CACHE[key] = result
     return result
 
@@ -362,11 +364,11 @@ def valid_term_in_collection(value: str,
     """
     Check if the given value may or may not represent a term in the given collection. The function
     returns the terms that the value matches.
-    
+
     Behavior based on the nature of the term:
         - plain term: the function try to match the value on the drs_name field.
-        - term pattern: the function try to match the value on the pattern field (regex).
-        - term composite: 
+        - pattern term: the function try to match the value on the pattern field (regex).
+        - composite term:
             - if the composite has got a separator, the function splits the value according to the \
               separator of the term then it try to match every part of the composite \
               with every split of the value.
@@ -374,7 +376,7 @@ def valid_term_in_collection(value: str,
               composite so as to compare it as a regex to the value.
 
     If any of the provided ids (`project_id` or `collection_id`) is not found,
-    the function raises a ValueError.
+    the function raises a EsgvocNotFoundError.
 
     :param value: A value to be validated
     :type value: str
@@ -384,7 +386,7 @@ def valid_term_in_collection(value: str,
     :type collection_id: str
     :returns: The list of terms that the value matches.
     :rtype: list[MatchingTerm]
-    :raises ValueError: If any of the provided ids is not found
+    :raises EsgvocNotFoundError: If any of the provided ids is not found
     """
     with get_universe_session() as universe_session, \
          _get_project_session_with_exception(project_id) as project_session:
@@ -408,18 +410,18 @@ def valid_term_in_project(value: str, project_id: str) -> list[MatchingTerm]:
     """
     Check if the given value may or may not represent a term in the given project. The function
     returns the terms that the value matches.
-    
+
     Behavior based on the nature of the term:
         - plain term: the function try to match the value on the drs_name field.
-        - term pattern: the function try to match the value on the pattern field (regex).
-        - term composite: 
+        - pattern term: the function try to match the value on the pattern field (regex).
+        - composite term:
             - if the composite has got a separator, the function splits the value according to the \
               separator of the term then it try to match every part of the composite \
               with every split of the value.
             - if the composite hasn't got a separator, the function aggregates the parts of the \
               composite so as to compare it as a regex to the value.
 
-    If the `project_id` is not found, the function raises a ValueError.
+    If the `project_id` is not found, the function raises a EsgvocNotFoundError.
 
     :param value: A value to be validated
     :type value: str
@@ -427,7 +429,7 @@ def valid_term_in_project(value: str, project_id: str) -> list[MatchingTerm]:
     :type project_id: str
     :returns: The list of terms that the value matches.
     :rtype: list[MatchingTerm]
-    :raises ValueError: If the `project_id` is not found
+    :raises EsgvocNotFoundError: If the `project_id` is not found
     """
     with get_universe_session() as universe_session, \
          _get_project_session_with_exception(project_id) as project_session:
@@ -438,11 +440,11 @@ def valid_term_in_all_projects(value: str) -> list[MatchingTerm]:
     """
     Check if the given value may or may not represent a term in all projects. The function
     returns the terms that the value matches.
-    
+
     Behavior based on the nature of the term:
         - plain term: the function try to match the value on the drs_name field.
-        - term pattern: the function try to match the value on the pattern field (regex).
-        - term composite: 
+        - pattern term: the function try to match the value on the pattern field (regex).
+        - composite term:
             - if the composite has got a separator, the function splits the value according to the \
               separator of the term then it try to match every part of the composite \
               with every split of the value.
@@ -463,422 +465,701 @@ def valid_term_in_all_projects(value: str) -> list[MatchingTerm]:
     return result
 
 
-def _find_terms_in_collection(collection_id: str,
-                              term_id: str,
-                              session: Session,
-                              settings: SearchSettings|None = None) -> Sequence[PTerm]:
-    # Settings only apply on the term_id comparison.
-    where_expression = _create_str_comparison_expression(field=PTerm.id,
-                                                         value=term_id,
-                                                         settings=settings)
-    statement = select(PTerm).join(Collection).where(Collection.id==collection_id,
-                                                     where_expression)
-    results = session.exec(statement)
-    result = results.all()    
+def get_all_terms_in_collection(project_id: str,
+                                collection_id: str,
+                                selected_term_fields: Iterable[str] | None = None)\
+                                   -> list[DataDescriptor]:
+    """
+    Gets all terms of the given collection of a project.
+    This function performs an exact match on the `project_id` and `collection_id`,
+    and does not search for similar or related projects and collections.
+    If any of the provided ids (`project_id` or `collection_id`) is not found, the function
+    returns an empty list.
+
+    :param project_id: A project id
+    :type project_id: str
+    :param collection_id: A collection id
+    :type collection_id: str
+    :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
+    fields of the terms are returned. If empty, selects the id and type fields.
+    :type selected_term_fields: Iterable[str] | None
+    :returns: a list of term instances. Returns an empty list if no matches are found.
+    :rtype: list[DataDescriptor]
+    """
+    result = list()
+    if connection := _get_project_connection(project_id):
+        with connection.create_session() as session:
+            collection = _get_collection_in_project(collection_id, session)
+            if collection:
+                result = _get_all_terms_in_collection(collection, selected_term_fields)
     return result
 
 
-def find_terms_in_collection(project_id:str,
-                             collection_id: str,
-                             term_id: str,
-                             settings: SearchSettings|None = None) \
-                                -> list[BaseModel]:
-    """
-    Finds one or more terms, based on the specified search settings, in the given collection of a project.
-    This function performs an exact match on the `project_id` and `collection_id`, 
-    and does **not** search for similar or related projects and collections.
-    The given `term_id` is searched according to the search type specified in the parameter `settings`,
-    which allows a flexible matching (e.g., `LIKE` may return multiple results).
-    If the parameter `settings` is `None`, this function performs an exact match on the `term_id`.
-    If any of the provided ids (`project_id`, `collection_id` or `term_id`) is not found,
-    the function returns an empty list.
-    
-    Behavior based on search type:
-        - `EXACT` and absence of `settings`: returns zero or one Pydantic term instance in the list.
-        - `REGEX`, `LIKE`, `STARTS_WITH` and `ENDS_WITH`: returns zero, one or more \
-          Pydantic term instances in the list.
+def _get_all_collections_in_project(session: Session) -> list[Collection]:
+    project = session.get(Project, constants.SQLITE_FIRST_PK)
+    # Project can't be missing if session exists.
+    return project.collections  # type: ignore
+
+
+def get_all_collections_in_project(project_id: str) -> list[str]:
+    """
+    Gets all collections of the given project.
+    This function performs an exact match on the `project_id` and
+    does not search for similar or related projects.
+    If the provided `project_id` is not found, the function returns an empty list.
 
     :param project_id: A project id
     :type project_id: str
-    :param collection_id: A collection
-    :type collection_id: str
-    :param term_id: A term id to be found
-    :type term_id: str
-    :param settings: The search settings
-    :type settings: SearchSettings|None
-    :returns: A list of Pydantic term instances. Returns an empty list if no matches are found.
-    :rtype: list[BaseModel]
+    :returns: A list of collection ids. Returns an empty list if no matches are found.
+    :rtype: list[str]
     """
-    result: list[BaseModel] = list()
-    if connection:=_get_project_connection(project_id):
+    result = list()
+    if connection := _get_project_connection(project_id):
         with connection.create_session() as session:
-            terms = _find_terms_in_collection(collection_id, term_id, session, settings)
-            instantiate_pydantic_terms(terms, result)
+            collections = _get_all_collections_in_project(session)
+            for collection in collections:
+                result.append(collection.id)
     return result
 
 
-def _find_terms_from_data_descriptor_in_project(data_descriptor_id: str,
-                                                term_id: str,
-                                                session: Session,
-                                                settings: SearchSettings|None = None) \
-                                                   -> Sequence[PTerm]:
-    # Settings only apply on the term_id comparison.
-    where_expression = _create_str_comparison_expression(field=PTerm.id,
-                                                         value=term_id,
-                                                         settings=settings)
-    statement = select(PTerm).join(Collection).where(Collection.data_descriptor_id==data_descriptor_id,
-                                                     where_expression)
-    results = session.exec(statement)
-    result = results.all()    
+def _get_all_terms_in_collection(collection: Collection,
+                                 selected_term_fields: Iterable[str] | None) -> list[DataDescriptor]:
+    result: list[DataDescriptor] = list()
+    instantiate_pydantic_terms(collection.terms, result, selected_term_fields)
     return result
 
 
-def find_terms_from_data_descriptor_in_project(project_id: str,
-                                               data_descriptor_id: str,
-                                               term_id: str,
-                                               settings: SearchSettings|None = None) \
-                                                  -> list[tuple[BaseModel, str]]:
-    """
-    Finds one or more terms in the given project which are instances of the given data descriptor
-    in the universe, based on the specified search settings, in the given collection of a project.
-    This function performs an exact match on the `project_id` and `data_descriptor_id`, 
-    and does **not** search for similar or related projects and data descriptors.
-    The given `term_id` is searched according to the search type specified in the parameter `settings`,
-    which allows a flexible matching (e.g., `LIKE` may return multiple results).
-    If the parameter `settings` is `None`, this function performs an exact match on the `term_id`.
-    If any of the provided ids (`project_id`, `data_descriptor_id` or `term_id`) is not found,
-    the function returns an empty list.
-    
-    Behavior based on search type:
-        - `EXACT` and absence of `settings`: returns zero or one Pydantic term instance and \
-          collection id in the list.
-        - `REGEX`, `LIKE`, `STARTS_WITH` and `ENDS_WITH`: returns zero, one or more \
-          Pydantic term instances and collection ids in the list.
+def get_all_terms_in_project(project_id: str,
+                             selected_term_fields: Iterable[str] | None = None) -> list[DataDescriptor]:
+    """
+    Gets all terms of the given project.
+    This function performs an exact match on the `project_id` and
+    does not search for similar or related projects.
+    Terms are unique within a collection but may have some synonyms in a project.
+    If the provided `project_id` is not found, the function returns an empty list.
 
     :param project_id: A project id
     :type project_id: str
-    :param data_descriptor_id: A data descriptor
-    :type data_descriptor_id: str
-    :param term_id: A term id to be found
-    :type term_id: str
-    :param settings: The search settings
-    :type settings: SearchSettings|None
-    :returns: A list of tuple of Pydantic term instances and related collection ids. \
-    Returns an empty list if no matches are found.
-    :rtype: list[tuple[BaseModel, str]]
+    :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
+    fields of the terms are returned. If empty, selects the id and type fields.
+    :type selected_term_fields: Iterable[str] | None
+    :returns: A list of term instances. Returns an empty list if no matches are found.
+    :rtype: list[DataDescriptor]
     """
     result = list()
-    if connection:=_get_project_connection(project_id):
+    if connection := _get_project_connection(project_id):
         with connection.create_session() as session:
-            terms = _find_terms_from_data_descriptor_in_project(data_descriptor_id,
-                                                                term_id,
-                                                                session,
-                                                                settings)
-            for pterm in terms:
-                collection_id = pterm.collection.id
-                term = instantiate_pydantic_term(pterm)
-                result.append((term, collection_id))
+            collections = _get_all_collections_in_project(session)
+            for collection in collections:
+                # Term may have some synonyms in a project.
+                result.extend(_get_all_terms_in_collection(collection, selected_term_fields))
     return result
 
 
-def find_terms_from_data_descriptor_in_all_projects(data_descriptor_id: str,
-                                                    term_id: str,
-                                                    settings: SearchSettings|None = None) \
-                                                    -> list[tuple[list[tuple[BaseModel, str]], str]]:
+def get_all_terms_in_all_projects(selected_term_fields: Iterable[str] | None = None) \
+                                                          -> list[tuple[str, list[DataDescriptor]]]:
     """
-    Finds one or more terms in all projects which are instances of the given data descriptor
-    in the universe, based on the specified search settings, in the given collection of a project.
-    This function performs an exact match on the `data_descriptor_id`, 
-    and does **not** search for similar or related data descriptors.
-    The given `term_id` is searched according to the search type specified in the parameter `settings`,
-    which allows a flexible matching (e.g., `LIKE` may return multiple results).
-    If the parameter `settings` is `None`, this function performs an exact match on the `term_id`.
-    If any of the provided ids (`data_descriptor_id` or `term_id`) is not found,
-    the function returns an empty list.
-    
-    Behavior based on search type:
-        - `EXACT` and absence of `settings`: returns zero or one Pydantic term instance and \
-          collection id in the list.
-        - `REGEX`, `LIKE`, `STARTS_WITH` and `ENDS_WITH`: returns zero, one or more \
-          Pydantic term instances and collection ids in the list.
-
-    :param data_descriptor_id: A data descriptor
-    :type data_descriptor_id: str
-    :param term_id: A term id to be found
-    :type term_id: str
-    :param settings: The search settings
-    :type settings: SearchSettings|None
-    :returns: A list of tuple of matching terms with their collection id, per project. \
-    Returns an empty list if no matches are found.
-    :rtype: list[tuple[list[tuple[BaseModel, str]], str]]
+    Gets all terms of all projects.
+
+    :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
+    fields of the terms are returned. If empty, selects the id and type fields.
+    :type selected_term_fields: Iterable[str] | None
+    :returns: A list of tuple project_id and term instances of that project.
+    :rtype: list[tuple[str, list[DataDescriptor]]]
     """
     project_ids = get_all_projects()
-    result: list[tuple[list[tuple[BaseModel, str]], str]] = list()
+    result = list()
     for project_id in project_ids:
-        matching_terms = find_terms_from_data_descriptor_in_project(project_id,
-                                                                    data_descriptor_id,
-                                                                    term_id,
-                                                                    settings)
-        result.append((matching_terms, project_id))
+        terms = get_all_terms_in_project(project_id, selected_term_fields)
+        result.append((project_id, terms))
     return result
 
 
-def _find_terms_in_project(term_id: str,
-                           session: Session,
-                           settings: SearchSettings|None) -> Sequence[PTerm]:
-    where_expression = _create_str_comparison_expression(field=PTerm.id,
-                                                         value=term_id,
-                                                         settings=settings)
-    statement = select(PTerm).where(where_expression)
-    results = session.exec(statement).all()
-    return results
-
-
-def find_terms_in_all_projects(term_id: str,
-                               settings: SearchSettings|None = None) \
-                                  -> list[BaseModel]:
-    """
-    Finds one or more terms, based on the specified search settings, in all projects.
-    The given `term_id` is searched according to the search type specified in the parameter `settings`,
-    which allows a flexible matching (e.g., `LIKE` may return multiple results).
-    If the parameter `settings` is `None`, this function performs an exact match on the `term_id`.
-    Terms are unique within a collection but may have some synonyms within a project.
-    If the provided `term_id` is not found, the function returns an empty list.
-
-    :param term_id: A term id to be found
-    :type term_id: str
-    :param settings: The search settings
-    :type settings: SearchSettings|None
-    :returns: A list of Pydantic term instances. Returns an empty list if no matches are found.
-    :rtype: list[BaseModel]
+def get_all_projects() -> list[str]:
     """
-    project_ids = get_all_projects()
-    result = list()
-    for project_id in project_ids:
-        result.extend(find_terms_in_project(project_id, term_id, settings))
+    Gets all projects.
+
+    :returns: A list of project ids.
+    :rtype: list[str]
+    """
+    return list(service.current_state.projects.keys())
+
+
+def _get_term_in_project(term_id: str, session: Session) -> PTerm | None:
+    statement = select(PTerm).where(PTerm.id == term_id)
+    results = session.exec(statement)
+    result = results.first()  # Term ids are not supposed to be unique within a project.
     return result
 
 
-def find_terms_in_project(project_id: str,
-                          term_id: str,
-                          settings: SearchSettings|None = None) \
-                            -> list[BaseModel]:
+def get_term_in_project(project_id: str, term_id: str,
+                        selected_term_fields: Iterable[str] | None = None) -> DataDescriptor | None:
     """
-    Finds one or more terms, based on the specified search settings, in a project.
-    This function performs an exact match on the `project_id` and 
-    does **not** search for similar or related projects.
-    The given `term_id` is searched according to the search type specified in the parameter `settings`,
-    which allows a flexible matching (e.g., `LIKE` may return multiple results).
-    If the parameter `settings` is `None`, this function performs an exact match on the `term_id`.
-    Terms are unique within a collection but may have some synonyms within a project.
-    If any of the provided ids (`project_id` or `term_id`) is not found, the function returns
-    an empty list.
+    Returns the first occurrence of the terms, in the given project, whose id corresponds exactly to
+    the given term id.
+    Terms are unique within a collection but may have some synonyms in a project.
+    This function performs an exact match on the `project_id` and `term_id`, and does not search
+    for similar or related projects and terms.
+    If any of the provided ids (`project_id` or `term_id`) is not found,
+    the function returns `None`.
 
-    :param project_id: A project id
+    :param project_id: The id of the given project.
     :type project_id: str
-    :param term_id: A term id to be found
+    :param term_id: The id of a term to be found.
     :type term_id: str
-    :param settings: The search settings
-    :type settings: SearchSettings|None
-    :returns: A list of Pydantic term instances. Returns an empty list if no matches are found.
-    :rtype: list[BaseModel]
+    :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
+    fields of the terms are returned. If empty, selects the id and type fields.
+    :type selected_term_fields: Iterable[str] | None
+    :returns: A term instance. Returns `None` if no match is found.
+    :rtype: DataDescriptor | None
     """
-    result: list[BaseModel] = list()
-    if connection:=_get_project_connection(project_id):
+    result: DataDescriptor | None = None
+    if connection := _get_project_connection(project_id):
         with connection.create_session() as session:
-            terms = _find_terms_in_project(term_id, session, settings)
-            instantiate_pydantic_terms(terms, result)
+            term_found = _get_term_in_project(term_id, session)
+            if term_found:
+                result = instantiate_pydantic_term(term_found, selected_term_fields)
     return result
 
 
-def get_all_terms_in_collection(project_id: str,
-                                collection_id: str)\
-                                   -> list[BaseModel]:
+def _get_term_in_collection(collection_id: str, term_id: str, session: Session) -> PTerm | None:
+    statement = select(PTerm).join(Collection).where(Collection.id == collection_id,
+                                                     PTerm.id == term_id)
+    results = session.exec(statement)
+    result = results.one_or_none()
+    return result
+
+
+def get_term_in_collection(project_id: str, collection_id: str, term_id: str,
+                           selected_term_fields: Iterable[str] | None = None) -> DataDescriptor | None:
     """
-    Gets all terms of the given collection of a project.
-    This function performs an exact match on the `project_id` and `collection_id`,
-    and does **not** search for similar or related projects and collections.
-    If any of the provided ids (`project_id` or `collection_id`) is not found, the function
-    returns an empty list.
+    Returns the term, in the given project and collection,
+    whose id corresponds exactly to the given term id.
+    This function performs an exact match on the `project_id`, `collection_id` and `term_id`,
+    and does not search for similar or related projects, collections and terms.
+    If any of the provided ids (`project_id`, `collection_id` or `term_id`) is not found,
+    the function returns `None`.
 
-    :param project_id: A project id
+    :param project_id: The id of the given project.
     :type project_id: str
-    :param collection_id: A collection id
+    :param collection_id: The id of the given collection.
     :type collection_id: str
-    :returns: a list of Pydantic term instances. Returns an empty list if no matches are found.
-    :rtype: list[BaseModel]
+    :param term_id: The id of a term to be found.
+    :type term_id: str
+    :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
+    fields of the terms are returned. If empty, selects the id and type fields.
+    :type selected_term_fields: Iterable[str] | None
+    :returns: A term instance. Returns `None` if no match is found.
+    :rtype: DataDescriptor | None
     """
-    result = list()
-    if connection:=_get_project_connection(project_id):
+    result: DataDescriptor | None = None
+    if connection := _get_project_connection(project_id):
         with connection.create_session() as session:
-            collections = _find_collections_in_project(collection_id,
-                                                       session,
-                                                       None)
-            if collections:
-                collection = collections[0]
-                result = _get_all_terms_in_collection(collection)
+            term_found = _get_term_in_collection(collection_id, term_id, session)
+            if term_found:
+                result = instantiate_pydantic_term(term_found, selected_term_fields)
     return result
 
 
-def _find_collections_in_project(collection_id: str,
-                                 session: Session,
-                                 settings: SearchSettings|None) \
-                                    -> Sequence[Collection]:
-    where_exp = _create_str_comparison_expression(field=Collection.id,
-                                                  value=collection_id,
-                                                  settings=settings)
-    statement = select(Collection).where(where_exp)
+def _get_collection_in_project(collection_id: str, session: Session) -> Collection | None:
+    statement = select(Collection).where(Collection.id == collection_id)
     results = session.exec(statement)
-    result = results.all()
+    result = results.one_or_none()
     return result
 
 
-def find_collections_in_project(project_id: str,
-                                collection_id: str,
-                                settings: SearchSettings|None = None) \
-                                    -> list[dict]:
-    """
-    Finds one or more collections of the given project.
-    This function performs an exact match on the `project_id` and 
-    does **not** search for similar or related projects.
-    The given `collection_id` is searched according to the search type specified in 
-    the parameter `settings`,
-    which allows a flexible matching (e.g., `LIKE` may return multiple results).
-    If the parameter `settings` is `None`, this function performs an exact match on the `collection_id`.
-    If any of the provided ids (`project_id` or `collection_id`) is not found, the function returns
-    an empty list.
-        
-    Behavior based on search type:
-        - `EXACT` and absence of `settings`: returns zero or one collection context in the list.
-        - `REGEX`, `LIKE`, `STARTS_WITH` and `ENDS_WITH`: returns zero, one or more \
-          collection contexts in the list.
+def get_collection_in_project(project_id: str, collection_id: str) -> tuple[str, dict] | None:
+    """
+    Returns the collection, in the given project, whose id corresponds exactly to
+    the given collection id.
+    This function performs an exact match on the `project_id` and `collection_id`, and does not search
+    for similar or related projects and collections.
+    If any of the provided ids (`project_id` or `collection_id`) is not found,
+    the function returns `None`.
 
-    :param project_id: A project id
+    :param project_id: The id of the given project.
     :type project_id: str
-    :param collection_id: A collection id to be found
+    :param collection_id: The id of a collection to be found.
     :type collection_id: str
-    :param settings: The search settings
-    :type settings: SearchSettings|None
-    :returns: A list of collection contexts. Returns an empty list if no matches are found.
-    :rtype: list[dict]
+    :returns: A collection id and context. Returns `None` if no match is found.
+    :rtype: tuple[str, dict] | None
     """
-    result = list()
-    if connection:=_get_project_connection(project_id):
+    result: tuple[str, dict] | None = None
+    if connection := _get_project_connection(project_id):
         with connection.create_session() as session:
-            collections = _find_collections_in_project(collection_id,
-                                                       session,
-                                                       settings)
-            for collection in collections:
-                result.append(collection.context)
+            collection_found = _get_collection_in_project(collection_id, session)
+            if collection_found:
+                result = collection_found.id, collection_found.context
     return result
 
 
-def _get_all_collections_in_project(session: Session) -> list[Collection]:
-    project = session.get(Project, esgvoc.core.constants.SQLITE_FIRST_PK)
-    # Project can't be missing if session exists.
-    return project.collections # type: ignore
-
-
-def get_all_collections_in_project(project_id: str) -> list[str]:
+def get_project(project_id: str) -> ProjectSpecs | None:
     """
-    Gets all collections of the given project.
-    This function performs an exact match on the `project_id` and 
-    does **not** search for similar or related projects.
-    If the provided `project_id` is not found, the function returns an empty list.
+    Get a project and returns its specifications.
+    This function performs an exact match on the `project_id` and
+    does not search for similar or related projects.
+    If the provided `project_id` is not found, the function returns `None`.
 
-    :param project_id: A project id
+    :param project_id: A project id to be found
     :type project_id: str
-    :returns: A list of collection ids. Returns an empty list if no matches are found.
-    :rtype: list[str]
+    :returns: The specs of the project found. Returns `None` if no matches are found.
+    :rtype: ProjectSpecs | None
     """
-    result = list()
-    if connection:=_get_project_connection(project_id):
+    result: ProjectSpecs | None = None
+    if connection := _get_project_connection(project_id):
         with connection.create_session() as session:
-            collections = _get_all_collections_in_project(session)
-            for collection in collections:
-                result.append(collection.id)
+            project = session.get(Project, constants.SQLITE_FIRST_PK)
+            try:
+                # Project can't be missing if session exists.
+                result = ProjectSpecs(**project.specs)  # type: ignore
+            except Exception as e:
+                msg = f"unable to read specs in project '{project_id}'"
+                raise EsgvocDbError(msg) from e
     return result
 
 
-def _get_all_terms_in_collection(collection: Collection) -> list[BaseModel]:
-    result: list[BaseModel] = list()
-    instantiate_pydantic_terms(collection.terms, result)
+def _get_collection_from_data_descriptor_in_project(data_descriptor_id: str,
+                                                    session: Session) -> Collection | None:
+    statement = select(Collection).where(Collection.data_descriptor_id == data_descriptor_id)
+    result = session.exec(statement).one_or_none()
     return result
 
 
-def get_all_terms_in_project(project_id: str) -> list[BaseModel]:
+def get_collection_from_data_descriptor_in_project(project_id: str,
+                                                   data_descriptor_id: str) \
+                                                    -> tuple[str, dict] | None:
     """
-    Gets all terms of the given project.
-    This function performs an exact match on the `project_id` and 
-    does **not** search for similar or related projects.
-    Terms are unique within a collection but may have some synonyms in a project.
-    If the provided `project_id` is not found, the function returns an empty list.
-
-    :param project_id: A project id
+    Returns the collection, in the given project, that corresponds to the given data descriptor
+    in the universe.
+    This function performs an exact match on the `project_id` and `data_descriptor_id`,
+    and does not search for similar or related projects and data descriptors.
+    If any of the provided ids (`project_id` or `data_descriptor_id`) is not found, or if
+    there is no collection corresponding to the given data descriptor, the function returns `None`.
+
+    :param project_id: The id of the given project.
     :type project_id: str
-    :returns: A list of Pydantic term instances. Returns an empty list if no matches are found.
-    :rtype: list[BaseModel]
+    :param data_descriptor_id: The id of the given data descriptor.
+    :type data_descriptor_id: str
+    :returns: A collection id and context. Returns `None` if no matches are found.
+    :rtype: tuple[str, dict] | None
+    """
+    result: tuple[str, dict] | None = None
+    if connection := _get_project_connection(project_id):
+        with connection.create_session() as session:
+            collection_found = _get_collection_from_data_descriptor_in_project(data_descriptor_id,
+                                                                               session)
+            if collection_found:
+                result = collection_found.id, collection_found.context
+    return result
+
+
+def get_collection_from_data_descriptor_in_all_projects(data_descriptor_id: str) \
+                                                                     -> list[tuple[str, str, dict]]:
+    """
+    Returns the collections, in all projects, that correspond to the given data descriptor
+    in the universe.
+    This function performs an exact match on `data_descriptor_id`,
+    and does not search for similar or related data descriptors.
+    If the provided `data_descriptor_id` is not found, or if
+    there is no collection corresponding to the given data descriptor, the function returns
+    an empty list.
+
+    :param data_descriptor_id: The id of the given data descriptor.
+    :type data_descriptor_id: str
+    :returns: A list of collection ids, their project_ids and contexts. \
+    Returns an empty list if no matches are found.
+    :rtype: list[tuple[str, str, dict]]
     """
     result = list()
-    if connection:=_get_project_connection(project_id):
+    project_ids = get_all_projects()
+    for project_id in project_ids:
+        collection_found = get_collection_from_data_descriptor_in_project(project_id,
+                                                                          data_descriptor_id)
+        if collection_found:
+            result.append((project_id, collection_found[0], collection_found[1]))
+    return result
+
+
+def _get_term_from_universe_term_id_in_project(data_descriptor_id: str,
+                                               universe_term_id: str,
+                                               project_session: Session) -> PTerm | None:
+    statement = select(PTerm).join(Collection).where(Collection.data_descriptor_id == data_descriptor_id,
+                                                     PTerm.id == universe_term_id)
+    results = project_session.exec(statement)
+    result = results.one_or_none()
+    return result
+
+
+def get_term_from_universe_term_id_in_project(project_id: str,
+                                              data_descriptor_id: str,
+                                              universe_term_id: str,
+                                              selected_term_fields: Iterable[str] | None = None) \
+                                                               -> tuple[str, DataDescriptor] | None:
+    """
+    Returns the term, in the given project, that corresponds to the given term in the universe.
+    This function performs an exact match on the `project_id`, `data_descriptor_id`
+    and `universe_term_id`, and does not search for similar or related projects, data descriptors
+    and terms. If any of the provided ids (`project_id`, `data_descriptor_id` or `universe_term_id`)
+    is not found, or if there is no project term corresponding to the given universe term
+    the function returns `None`.
+
+    :param project_id: The id of the given project.
+    :type project_id: str
+    :param data_descriptor_id: The id of the data descriptor that contains the given universe term.
+    :type data_descriptor_id: str
+    :param universe_term_id: The id of the given universe term.
+    :type universe_term_id: str
+    :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
+    fields of the terms are returned. If empty, selects the id and type fields.
+    :type selected_term_fields: Iterable[str] | None
+    :returns: A collection id and the project term instance. Returns `None` if no matches are found.
+    :rtype: tuple[str, DataDescriptor] | None
+    """
+    result: tuple[str, DataDescriptor] | None = None
+    if connection := _get_project_connection(project_id):
         with connection.create_session() as session:
-            collections = _get_all_collections_in_project(session)
-            for collection in collections:
-                # Term may have some synonyms in a project.
-                result.extend(_get_all_terms_in_collection(collection))
+            term_found = _get_term_from_universe_term_id_in_project(data_descriptor_id,
+                                                                    universe_term_id,
+                                                                    session)
+            if term_found:
+                pydantic_term = instantiate_pydantic_term(term_found, selected_term_fields)
+                result = (term_found.collection.id, pydantic_term)
     return result
 
 
-def get_all_terms_in_all_projects() -> list[BaseModel]:
+def get_term_from_universe_term_id_in_all_projects(data_descriptor_id: str,
+                                                   universe_term_id: str,
+                                                   selected_term_fields: Iterable[str] | None = None) \
+                                                           -> list[tuple[str, str, DataDescriptor]]:
     """
-    Gets all terms of all projects.
+    Returns the terms, in all projects, that correspond to the given term in the universe.
+    This function performs an exact match on the `data_descriptor_id`
+    and `universe_term_id`, and does not search for similar or related data descriptors
+    and terms. If any of the provided ids (`data_descriptor_id` or `universe_term_id`)
+    is not found, or if there is no project term corresponding to the given universe term
+    the function returns an empty list.
 
-    :returns: A list of Pydantic term instances.
-    :rtype: list[BaseModel]
+    :param data_descriptor_id: The id of the data descriptor that contains the given universe term.
+    :type data_descriptor_id: str
+    :param universe_term_id: The id of the given universe term.
+    :type universe_term_id: str
+    :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
+    fields of the terms are returned. If empty, selects the id and type fields.
+    :type selected_term_fields: Iterable[str] | None
+    :returns: A project_id, collection id and the project term instance. \
+    Returns an empty list if no matches are found.
+    :rtype: list[tuple[str, str, DataDescriptor]]
     """
+    result: list[tuple[str, str, DataDescriptor]] = list()
     project_ids = get_all_projects()
-    result = list()
     for project_id in project_ids:
-        result.extend(get_all_terms_in_project(project_id))
+        term_found = get_term_from_universe_term_id_in_project(project_id,
+                                                               data_descriptor_id,
+                                                               universe_term_id,
+                                                               selected_term_fields)
+        if term_found:
+            result.append((project_id, term_found[0], term_found[1]))
     return result
 
 
-def find_project(project_id: str) -> dict|None:
+def _find_collections_in_project(expression: str,
+                                 session: Session,
+                                 only_id: bool = False,
+                                 limit: int | None = None,
+                                 offset: int | None = None) -> Sequence[Collection]:
+    matching_condition = generate_matching_condition(PCollectionFTS5, expression, only_id)
+    tmp_statement = select(PCollectionFTS5).where(matching_condition)
+    statement = select(Collection).from_statement(handle_rank_limit_offset(tmp_statement, limit, offset))
+    return execute_match_statement(expression, statement, session)
+
+
+def find_collections_in_project(expression: str, project_id: str,
+                                only_id: bool = False,
+                                limit: int | None = None,
+                                offset: int | None = None) -> list[tuple[str, dict]]:
     """
-    Finds a project.
-    This function performs an exact match on the `project_id` and 
-    does **not** search for similar or related projects.
-    If the provided `project_id` is not found, the function returns `None`.
-    
-    :param project_id: A project id to be found
+    Find collections in the given project based on a full text search defined by the given `expression`.
+    The `expression` comes from the powerful
+    `SQLite FTS extension <https://sqlite.org/fts5.html#full_text_query_syntax>`_
+    and corresponds to the expression of the `MATCH` operator.
+    It can be composed of one or multiple keywords combined with boolean
+    operators (`NOT`, `AND`, `^`, etc. default is `OR`). Keywords can define prefixes or postfixes
+    with the wildcard `*`.
+    The function returns a list of collection ids and contexts, sorted according to the
+    bm25 ranking metric (list index `0` has the highest rank).
+    This function performs an exact match on the `project_id`,
+    and does not search for similar or related projects.
+    If the provided `expression` does not hit any collection or the given `project_id` does not
+    match exactly to an id of a project, the function returns an empty list.
+    The function searches for the `expression` in the collection specifications.
+    However, if `only_id` is `True` (default is `False`), the search is restricted to the id of the
+    collections. **At the moment, `only_id` is set to `True` as the collections
+    haven't got any description.**
+
+    :param expression: The full text search expression.
+    :type expression: str
+    :param project_id: The id of the given project.
     :type project_id: str
-    :returns: The specs of the project found. Returns `None` if no matches are found.
-    :rtype: dict|None
+    :param only_id: Performs the search only on ids, otherwise on all the specifications.
+    :type only_id: bool
+    :param limit: Limit the number of returned items found. Returns all items found the if \
+    `limit` is either `None`, zero or negative.
+    :type limit: int | None
+    :param offset: Skips `offset` number of items found. Ignored if `offset` is \
+    either `None`, zero or negative.
+    :type offset: int | None
+    :returns: A list of collection ids and contexts. Returns an empty list if no matches are found.
+    :rtype: list[tuple[str, dict]]
+    :raises EsgvocValueError: If the `expression` cannot be interpreted.
     """
-    result = None
-    if connection:=_get_project_connection(project_id):
+    result: list[tuple[str, dict]] = list()
+    if connection := _get_project_connection(project_id):
         with connection.create_session() as session:
-            project = session.get(Project, esgvoc.core.constants.SQLITE_FIRST_PK)
-            # Project can't be missing if session exists.
-            result = project.specs # type: ignore
+            collections_found = _find_collections_in_project(expression, session, only_id,
+                                                             limit, offset)
+            for collection in collections_found:
+                result.append((collection.id, collection.context))
     return result
 
 
-def get_all_projects() -> list[str]:
+def _find_terms_in_collection(expression: str,
+                              collection_id: str,
+                              session: Session,
+                              only_id: bool = False,
+                              limit: int | None = None,
+                              offset: int | None = None) -> Sequence[PTerm]:
+    matching_condition = generate_matching_condition(PTermFTS5, expression, only_id)
+    where_condition = Collection.id == collection_id, matching_condition
+    tmp_statement = select(PTermFTS5).join(Collection).where(*where_condition)
+    statement = select(PTerm).from_statement(handle_rank_limit_offset(tmp_statement, limit, offset))
+    return execute_match_statement(expression, statement, session)
+
+
+def _find_terms_in_project(expression: str,
+                           session: Session,
+                           only_id: bool = False,
+                           limit: int | None = None,
+                           offset: int | None = None) -> Sequence[PTerm]:
+    matching_condition = generate_matching_condition(PTermFTS5, expression, only_id)
+    tmp_statement = select(PTermFTS5).where(matching_condition)
+    statement = select(PTerm).from_statement(handle_rank_limit_offset(tmp_statement, limit, offset))
+    return execute_match_statement(expression, statement, session)
+
+
+def find_terms_in_collection(expression: str, project_id: str,
+                             collection_id: str,
+                             only_id: bool = False,
+                             limit: int | None = None,
+                             offset: int | None = None,
+                             selected_term_fields: Iterable[str] | None = None) \
+                                                                          -> list[DataDescriptor]:
     """
-    Gets all projects.
-    
-    :returns: A list of project ids.
-    :rtype: list[str]
+    Find terms in the given project and collection based on a full text search defined by the given
+    `expression`. The `expression` comes from the powerful
+    `SQLite FTS extension <https://sqlite.org/fts5.html#full_text_query_syntax>`_
+    and corresponds to the expression of the `MATCH` operator.
+    It can be composed of one or multiple keywords combined with boolean
+    operators (`NOT`, `AND`, `^`, etc. default is `OR`). Keywords can define prefixes or postfixes
+    with the wildcard `*`.
+    The function returns a list of term instances, sorted according to the
+    bm25 ranking metric (list index `0` has the highest rank).
+    This function performs an exact match on the `project_id` and `collection_id`,
+    and does not search for similar or related projects and collections.
+    If the provided `expression` does not hit any term or if any of the provided ids
+    (`project_id` or `collection_id`) is not found, the function returns an empty list.
+    The function searches for the `expression` in the term specifications.
+    However, if `only_id` is `True` (default is `False`), the search is restricted to the id of the
+    terms.
+
+    :param expression: The full text search expression.
+    :type expression: str
+    :param project_id: The id of the given project.
+    :type project_id: str
+    :param collection_id: The id of the given collection.
+    :type collection_id: str
+    :param only_id: Performs the search only on ids, otherwise on all the specifications.
+    :type only_id: bool
+    :param limit: Limit the number of returned items found. Returns all items found the if \
+    `limit` is either `None`, zero or negative.
+    :type limit: int | None
+    :param offset: Skips `offset` number of items found. Ignored if `offset` is \
+    either `None`, zero or negative.
+    :type offset: int | None
+    :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
+    fields of the terms are returned. If empty, selects the id and type fields.
+    :type selected_term_fields: Iterable[str] | None
+    :returns: A list of term instances. Returns an empty list if no matches are found.
+    :rtype: list[DataDescriptor]
+    :raises EsgvocValueError: If the `expression` cannot be interpreted.
     """
-    return list(service.state_service.projects.keys())
+    result: list[DataDescriptor] = list()
+    if connection := _get_project_connection(project_id):
+        with connection.create_session() as session:
+            pterms_found = _find_terms_in_collection(expression, collection_id, session,
+                                                     only_id, limit, offset)
+            instantiate_pydantic_terms(pterms_found, result, selected_term_fields)
+    return result
 
 
-if __name__ == "__main__":
-    vr = valid_term('r1i1p1f111', 'cmip6plus', 'member_id', 'ripf')
-    if vr:
-        print('OK')
-    else:
-        print(vr)
-        for error in vr.errors:
-            print(error)
+def find_terms_in_project(expression: str,
+                          project_id: str,
+                          only_id: bool = False,
+                          limit: int | None = None,
+                          offset: int | None = None,
+                          selected_term_fields: Iterable[str] | None = None) \
+                                                                          -> list[DataDescriptor]:
+    """
+    Find terms in the given project on a full text search defined by the given
+    `expression`. The `expression` comes from the powerful
+    `SQLite FTS extension <https://sqlite.org/fts5.html#full_text_query_syntax>`_
+    and corresponds to the expression of the `MATCH` operator.
+    It can be composed of one or multiple keywords combined with boolean
+    operators (`NOT`, `AND`, `^`, etc. default is `OR`). Keywords can define prefixes or postfixes
+    with the wildcard `*`.
+    The function returns a list of term instances, sorted according to the
+    bm25 ranking metric (list index `0` has the highest rank).
+    This function performs an exact match on the `project_id`,
+    and does not search for similar or related projects.
+    If the provided `expression` does not hit any term or if any of the provided `project_id` is
+    not found, the function returns an empty list.
+    The function searches for the `expression` in the term specifications.
+    However, if `only_id` is `True` (default is `False`), the search is restricted to the id of the
+    terms.
+
+    :param expression: The full text search expression.
+    :type expression: str
+    :param project_id: The id of the given project.
+    :type project_id: str
+    :param only_id: Performs the search only on ids, otherwise on all the specifications.
+    :type only_id: bool
+    :param limit: Limit the number of returned items found. Returns all items found the if \
+    `limit` is either `None`, zero or negative.
+    :type limit: int | None
+    :param offset: Skips `offset` number of items found. Ignored if `offset` is \
+    either `None`, zero or negative.
+    :type offset: int | None
+    :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
+    fields of the terms are returned. If empty, selects the id and type fields.
+    :type selected_term_fields: Iterable[str] | None
+    :returns: A list of term instances. Returns an empty list if no matches are found.
+    :rtype: list[DataDescriptor]
+    :raises EsgvocValueError: If the `expression` cannot be interpreted.
+    """
+    result: list[DataDescriptor] = list()
+    if connection := _get_project_connection(project_id):
+        with connection.create_session() as session:
+            pterms_found = _find_terms_in_project(expression, session, only_id, limit, offset)
+            instantiate_pydantic_terms(pterms_found, result, selected_term_fields)
+    return result
+
+
+def find_terms_in_all_projects(expression: str,
+                               only_id: bool = False,
+                               limit: int | None = None,
+                               offset: int | None = None,
+                               selected_term_fields: Iterable[str] | None = None) \
+                                                        -> list[tuple[str, list[DataDescriptor]]]:
+    """
+    Find terms in the all projects on a full text search defined by the given
+    `expression`. The `expression` comes from the powerful
+    `SQLite FTS extension <https://sqlite.org/fts5.html#full_text_query_syntax>`_
+    and corresponds to the expression of the `MATCH` operator.
+    It can be composed of one or multiple keywords combined with boolean
+    operators (`NOT`, `AND`, `^`, etc. default is `OR`). Keywords can define prefixes or postfixes
+    with the wildcard `*`.
+    The function returns a list of project ids and term instances, sorted according to the
+    bm25 ranking metric (list index `0` has the highest rank).
+    If the provided `expression` does not hit any term, the function returns an empty list.
+    The function searches for the `expression` in the term specifications.
+    However, if `only_id` is `True` (default is `False`), the search is restricted to the id of the
+    terms.
+
+    :param expression: The full text search expression.
+    :type expression: str
+    :param only_id: Performs the search only on ids, otherwise on all the specifications.
+    :type only_id: bool
+    :param limit: Limit the number of returned items found. Returns all items found the if \
+    `limit` is either `None`, zero or negative.
+    :type limit: int | None
+    :param offset: Skips `offset` number of items found. Ignored if `offset` is \
+    either `None`, zero or negative.
+    :type offset: int | None
+    :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
+    fields of the terms are returned. If empty, selects the id and type fields.
+    :type selected_term_fields: Iterable[str] | None
+    :returns: A list of project ids and term instances. Returns an empty list if no matches are found.
+    :rtype: list[tuple[str, list[DataDescriptor]]]
+    :raises EsgvocValueError: If the `expression` cannot be interpreted.
+    """
+    result: list[tuple[str, list[DataDescriptor]]] = list()
+    project_ids = get_all_projects()
+    for project_id in project_ids:
+        terms_found = find_terms_in_project(expression, project_id, only_id,
+                                            limit, offset, selected_term_fields)
+        if terms_found:
+            result.append((project_id, terms_found))
+    return result
+
+
+def find_items_in_project(expression: str,
+                          project_id: str,
+                          only_id: bool = False,
+                          limit: int | None = None,
+                          offset: int | None = None) -> list[Item]:
+    """
+    Find items, at the moment terms and collections, in the given project based on a full-text
+    search defined by the given `expression`. The `expression` comes from the powerful
+    `SQLite FTS extension <https://sqlite.org/fts5.html#full_text_query_syntax>`_
+    and corresponds to the expression of the `MATCH` operator.
+    It can be composed of one or multiple keywords combined with boolean
+    operators (`NOT`, `AND`, `^`, etc. default is `OR`). Keywords can define prefixes or postfixes
+    with the wildcard `*`.
+    The function returns a list of item instances sorted according to the
+    bm25 ranking metric (list index `0` has the highest rank).
+    This function performs an exact match on the `project_id`,
+    and does not search for similar or related projects.
+    If the provided `expression` does not hit any item, or the provided `project_id` is not found,
+    the function returns an empty list.
+    The function searches for the `expression` in the term and collection specifications.
+    However, if `only_id` is `True` (default is `False`), the search is restricted to the id of the
+    terms and collections. **At the moment, `only_id` is set to `True` for the collections because
+    they haven't got any description.**
+
+    :param expression: The full text search expression.
+    :type expression: str
+    :param only_id: Performs the search only on ids, otherwise on all the specifications.
+    :type only_id: bool
+    :param limit: Limit the number of returned items found. Returns all items found the if \
+    `limit` is either `None`, zero or negative.
+    :type limit: int | None
+    :param offset: Skips `offset` number of items found. Ignored if `offset` is \
+    either `None`, zero or negative.
+    :type offset: int | None
+    :returns: A list of item instances. Returns an empty list if no matches are found.
+    :rtype: list[Item]
+    :raises EsgvocValueError: If the `expression` cannot be interpreted.
+    """
+    # TODO: execute union query when it will be possible to compute parent of terms and collections.
+    result = list()
+    if connection := _get_project_connection(project_id):
+        with connection.create_session() as session:
+            if only_id:
+                collection_column = col(PCollectionFTS5.id)
+                term_column = col(PTermFTS5.id)
+            else:
+                collection_column = col(PCollectionFTS5.id)  # TODO: use specs when implemented!
+                term_column = col(PTermFTS5.specs)  # type: ignore
+            collection_where_condition = collection_column.match(expression)
+            collection_statement = select(PCollectionFTS5.id,
+                                          text("'collection' AS TYPE"),
+                                          text(f"'{project_id}' AS TYPE"),
+                                          text('rank')).where(collection_where_condition)
+            term_where_condition = term_column.match(expression)
+            term_statement = select(PTermFTS5.id,
+                                    text("'term' AS TYPE"),
+                                    Collection.id,
+                                    text('rank')).join(Collection) \
+                                                 .where(term_where_condition)
+            result = execute_find_item_statements(session, expression, collection_statement,
+                                                  term_statement, limit, offset)
+    return result