pyegeria 5.3.8.8__py3-none-any.whl → 5.3.8.10__py3-none-any.whl

pyegeria/__init__.py

@@ -11,24 +11,10 @@ the server platform and servers.
 
 """
 
-from ._globals import (
-    INTEGRATION_GUIDS,
-    TEMPLATE_GUIDS,
-    default_time_out,
-    disable_ssl_warnings,
-    enable_ssl_check,
-    is_debug,
-    max_paging_size,
-    NO_ELEMENTS_FOUND,
-    NO_ASSETS_FOUND,
-    NO_SERVERS_FOUND,
-    NO_CATALOGS_FOUND,
-    NO_GLOSSARIES_FOUND,
-    NO_TERMS_FOUND,
-    NO_CATEGORIES_FOUND,
-    NO_ELEMENT_FOUND,
-    NO_PROJECTS_FOUND,
-)
+from ._globals import (INTEGRATION_GUIDS, TEMPLATE_GUIDS, default_time_out, disable_ssl_warnings, enable_ssl_check,
+                       is_debug, max_paging_size, NO_ELEMENTS_FOUND, NO_ASSETS_FOUND, NO_SERVERS_FOUND,
+                       NO_CATALOGS_FOUND, NO_GLOSSARIES_FOUND, NO_TERMS_FOUND, NO_CATEGORIES_FOUND, NO_ELEMENT_FOUND,
+                       NO_PROJECTS_FOUND, )
 
 if disable_ssl_warnings:
     from urllib3 import disable_warnings
@@ -38,22 +24,10 @@ if disable_ssl_warnings:
 
 from ._client import Client
 from ._deprecated_gov_engine import GovEng
-from ._exceptions import (
-    InvalidParameterException,
-    PropertyServerException,
-    UserNotAuthorizedException,
-    print_exception_response,
-)
-from ._validators import (
-    is_json,
-    validate_guid,
-    validate_name,
-    validate_public,
-    validate_search_string,
-    validate_server_name,
-    validate_url,
-    validate_user_id,
-)
+from ._exceptions import (InvalidParameterException, PropertyServerException, UserNotAuthorizedException,
+                          print_exception_response, )
+from ._validators import (is_json, validate_guid, validate_name, validate_public, validate_search_string,
+                          validate_server_name, validate_url, validate_user_id, )
 from .asset_catalog_omvs import AssetCatalog
 from .automated_curation_omvs import AutomatedCuration
 from .classification_manager_omvs import ClassificationManager
@@ -69,16 +43,8 @@ from .feedback_manager_omvs import FeedbackManager
 from .full_omag_server_config import FullServerConfig
 from .glossary_browser_omvs import GlossaryBrowser
 from .glossary_manager_omvs import GlossaryManager
-from .mermaid_utilities import (
-    construct_mermaid_web,
-    construct_mermaid_jup,
-    generate_process_graph,
-    load_mermaid,
-    parse_mermaid_code,
-    render_mermaid,
-    save_mermaid_graph,
-    save_mermaid_html,
-)
+from .mermaid_utilities import (construct_mermaid_web, construct_mermaid_jup, generate_process_graph, load_mermaid,
+                                parse_mermaid_code, render_mermaid, save_mermaid_graph, save_mermaid_html, )
 from .metadata_explorer_omvs import MetadataExplorer
 from .my_profile_omvs import MyProfile
 from .platform_services import Platform
@@ -91,12 +57,14 @@ from .utils import body_slimmer, print_response
 from .valid_metadata_omvs import ValidMetadataManager
 from .x_action_author_omvs import ActionAuthor
 from .md_processing_utils import (extract_command, process_glossary_upsert_command, process_term_upsert_command,
-                                  process_category_upsert_command,
-                                  get_current_datetime_string, process_per_proj_upsert_command, command_list,
-                                  render_markdown, process_provenance_command, process_blueprint_upsert_command,
-                                  process_solution_component_upsert_command,
-                                  process_term_list_command, process_glossary_list_command, process_category_list_command,
-                                  process_term_history_command)
+                                  process_category_upsert_command, get_current_datetime_string,
+                                  process_per_proj_upsert_command, command_list, render_markdown,
+                                  process_provenance_command, process_blueprint_upsert_command,
+                                  process_solution_component_upsert_command, process_term_list_command,
+                                  process_glossary_list_command, process_category_list_command,
+                                  process_term_history_command, process_glossary_structure_command,
+                                  process_term_revision_history_command, process_create_term_term_relationship_command,
+                                  )
 
 #
 # The following assignments were generated by the `create_tech_guid_lists.py` utility that uses the pyegeria functions
@@ -482,6 +450,5 @@ INTEGRATION_GUIDS['OpenLineageCataloguer'] = '3347ac71-8dd2-403a-bc16-75a71be64b
 INTEGRATION_GUIDS['ApacheAtlasExchange'] = '5721627a-2dd4-4f95-a274-6cfb128edb97'
 INTEGRATION_GUIDS['HarvestSurveys'] = 'fae162c3-2bfd-467f-9c47-2e3b63a655de'
 
-
 if __name__ == "__main__":
     print("Main-Init")

pyegeria/commands/cat/dr_egeria_md.py

@@ -13,7 +13,9 @@ from pyegeria import (extract_command, process_glossary_upsert_command, process_
                       get_current_datetime_string,
                       process_per_proj_upsert_command, command_list, EgeriaTech, process_blueprint_upsert_command,
                       process_solution_component_upsert_command, dr_egeria_state, process_term_list_command,
-                      process_category_list_command, process_glossary_list_command, process_term_history_command)
+                      process_category_list_command, process_glossary_list_command, process_term_history_command,
+                      process_glossary_structure_command, process_term_revision_history_command,
+                      process_create_term_term_relationship_command)
 
 EGERIA_METADATA_STORE = os.environ.get("EGERIA_METADATA_STORE", "active-metadata-store")
 EGERIA_KAFKA_ENDPOINT = os.environ.get("KAFKA_ENDPOINT", "localhost:9092")
@@ -89,21 +91,22 @@ def process_markdown_file(file_path: str, directive: str, server: str, url: str,
                 result = process_glossary_upsert_command(client, current_block, directive)
             elif potential_command in ["Create Category", "Update Category"]:
                 result = process_category_upsert_command(client, current_block, directive)
-            # elif potential_command in ["Set Parent Category", "UnSet Parent Category"]:
-            #     result = process_set_categories_parent_command(client, dr_egeria_state.get_element_dictionary(),
-            #                                                    current_block, directive)
             elif potential_command in ["Create Term", "Update Term"]:
                 result = process_term_upsert_command(client, current_block, directive)
+            elif potential_command in ["Create Term-Term Relationship", "Update Term-Term Relationship"]:
+                result = process_create_term_term_relationship_command(client, current_block, directive)
             elif potential_command in ["List Term History", "Term History"]:
                 result = process_term_history_command(client, current_block, directive)
+            elif potential_command in ["List Term Update History", "List Term Revision History"]:
+                result = process_term_revision_history_command(client, current_block, directive)
             elif potential_command in ["List Terms", "List Glossary Terms"]:
                 result = process_term_list_command(client, current_block, directive)
             elif potential_command in ["List Categories", "List Glossary Categories"]:
-                result = process_category_list_command(client, dr_egeria_state.get_element_dictionary(), current_block,
-                                                       directive)
+                result = process_category_list_command(client, current_block, directive)
+            elif potential_command in ["List Glossary Structure"]:
+                result = process_glossary_structure_command(client, current_block, directive)
             elif potential_command in ["List Glossaries"]:
-                result = process_glossary_list_command(client, dr_egeria_state.get_element_dictionary(), current_block,
-                                                       directive)
+                result = process_glossary_list_command(client, current_block, directive)
             elif potential_command in ["Create Personal Project", "Update Personal Project"]:
                 result = process_per_proj_upsert_command(client, current_block, directive)
             elif potential_command in ["Create Blueprint", "Update Blueprint", "Create Solution Blueprint",

pyegeria/glossary_browser_omvs.py

@@ -133,8 +133,8 @@ class GlossaryBrowser(Client):
         cat_md_qn = ''
         if type(categories) is list:
             for category in categories:
-                cat_md_display += f"* {category['glossaryCategoryProperties'][('displayName')]}\n"
-                cat_md_qn += f"* {category['glossaryCategoryProperties'][('qualifiedName')]}\n"
+                cat_md_display += f" {category['glossaryCategoryProperties'][('displayName')]},\n"
+                cat_md_qn += f" {category['glossaryCategoryProperties'][('qualifiedName')]},\n"
             cat_md = cat_md_display.strip()
             cat_md_qn = cat_md_qn.strip()
 
@@ -423,9 +423,10 @@ class GlossaryBrowser(Client):
         pub_version = properties.get("publishVersionIdentifier", "") or ""
         qualified_name = properties.get("qualifiedName", "") or ""
         status = element['elementHeader'].get('status', "") or ""
+        aliases = ", ".join(properties.get("aliases", "")) or ""
 
         return {
-            'guid': guid, 'properties': properties, 'display_name': display_name, 'summary': summary,
+            'guid': guid, 'properties': properties, 'display_name': display_name, 'aliases': aliases, 'summary': summary,
             'description': description, 'examples': examples, 'usage': usage, 'version identifier': pub_version,
             'qualified_name': qualified_name, 'status': status
             }
@@ -506,8 +507,8 @@ class GlossaryBrowser(Client):
             str: Markdown table
         """
         columns = [{'name': 'Term Name', 'key': 'display_name'}, {'name': 'Qualified Name', 'key': 'qualified_name'},
-            {'name': 'Summary', 'key': 'summary', 'format': True}, {'name': 'Glossary', 'key': 'glossary'},
-            {'name': 'Categories', 'key': 'categories_str', 'format': True}]
+            {'name': 'Aliases', 'key': 'aliases', 'format': True}, {'name': 'Summary', 'key': 'summary', 'format': True}, 
+            {'name': 'Glossary', 'key': 'glossary'}, {'name': 'Categories', 'key': 'categories_str', 'format': True}]
 
         # Create a wrapper function to pass output_format to _get_term_table_properties
         def get_table_props_with_format(element, term_guid, output_format_param=None):
@@ -640,11 +641,11 @@ class GlossaryBrowser(Client):
             output_format (str): Output format (FORM, REPORT, LIST, etc.)
 
         Returns:
-            str: The parent category name or '---' if no parent
+            str: The parent category name or ' ' if no parent
         """
         parent_cat = self.get_category_parent(category_guid)
         if isinstance(parent_cat, str):
-            return '---'
+            return ' '
 
         # Return qualified name for FORM output, display name for REPORT and LIST output
         if output_format == 'FORM':
@@ -1036,6 +1037,43 @@ class GlossaryBrowser(Client):
         response = loop.run_until_complete(self._async_get_glossary_term_statuses())
         return response
 
+    async def _async_get_term_relationship_types(self) -> [str]:
+        """Return the list of term relationship types enum values. Async version.
+
+        Parameters
+        ----------
+
+
+        Returns
+        -------
+        List[str]
+            A list of glossary term relationships retrieved from the server.
+
+        """
+
+        url = (f"{self.platform_url}/servers/{self.view_server}"
+               f"/api/open-metadata/glossary-manager/glossaries/terms/relationships/type-names")
+
+        response = await self._async_make_request("GET", url)
+        return response.json().get("names", [])
+
+    def get_term_relationship_types(self) -> [str]:
+        """Return the list of term relationship type enum values.
+
+        Parameters
+        ----------
+
+
+        Returns
+        -------
+        list of str
+            A list of term relationship types. Each status is represented as a string.
+
+        """
+        loop = asyncio.get_event_loop()
+        response = loop.run_until_complete(self._async_get_term_relationship_types())
+        return response
+
     #
     #       Glossaries
     #
@@ -2512,10 +2550,10 @@ class GlossaryBrowser(Client):
 
         return response
 
-    async def _async_get_term_relationships(self, term_guid: str, effective_time: str = None, start_from: int = 0,
-            page_size: int = None, ) -> list | str:
+    async def _async_get_related_terms(self, term_guid: str, effective_time: str = None, start_from: int = 0,
+                                       page_size: int = None, output_format:str = "JSON") -> list | str:
         """This call retrieves details of the glossary terms linked to this glossary term.
-        Notice the original org 1 glossary term is linked via the "SourcedFrom" relationship..
+        Notice the original org 1 glossary term is linked via the "SourcedFrom" relationship.
         Parameters
         ----------
             term_guid : str
@@ -2559,10 +2597,21 @@ class GlossaryBrowser(Client):
         else:
             response = await self._async_make_request("POST", url)
 
-        return response.json().get("elementList", "No terms found")
+        term_elements = response.json().get("elementList", NO_TERMS_FOUND)
+        if term_elements == NO_TERMS_FOUND:
+            if output_format == 'JSON':
+                return NO_TERMS_FOUND
+            elif output_format in ['MD', 'FORM', 'REPORT', 'LIST']:
+                return "\n# No Terms found.\n"
+            elif output_format == 'DICT':
+                return None
+        if output_format != "JSON":  # return a simplified markdown representation
+            return self.generate_terms_md(term_elements, term_guid, output_format)
+        return response.json().get("elementList", NO_TERMS_FOUND)
 
-    def get_term_relationships(self, term_guid: str, effective_time: str = None, start_from: int = 0,
-            page_size: int = None, ) -> list | str:
+
+    def get_related_terms(self, term_guid: str, effective_time: str = None, start_from: int = 0,
+                          page_size: int = None, output_format = "JSON") -> list | str:
         """This call retrieves details of the glossary terms linked to this glossary term.
         Notice the original org 1 glossary term is linked via the "SourcedFrom" relationship..
         Parameters
@@ -2595,10 +2644,37 @@ class GlossaryBrowser(Client):
         """
         loop = asyncio.get_event_loop()
         response = loop.run_until_complete(
-            self._async_get_term_relationships(term_guid, effective_time, start_from, page_size))
+            self._async_get_related_terms(term_guid, effective_time, start_from,
+                                          page_size, output_format))
 
         return response
 
+    def get_term_details(self, term_name:str, effective_time: str = None) -> dict | str:
+        """Retrieve the details of a glossary term. Including relationships and feedback
+
+        output_format: str, default = 'JSON'
+            Type of output to produce:
+            JSON - output standard json
+            MD - output standard markdown with no preamble
+            DICT = output a simplified DICT structure
+        """
+
+
+        # Now lets get the term details as a dict
+        core = self.get_terms_by_name(term_name, effective_time, output_format="DICT")
+        if not core:
+            return NO_TERMS_FOUND
+
+        related = self.get_related_terms(core[0]['guid'], effective_time)
+        if not related:
+            return "NO RELATED TERMS FOUND"
+
+        related_term_guid = related[0]["relatedElement"]["relatedElement"]["guid"]
+        related_term_qn = related[0]["relatedElement"]["relatedElement"]["uniquedName"]
+
+
+
+
     async def _async_get_glossary_for_term(self, term_guid: str, effective_time: str = None) -> dict | str:
         """Retrieve the glossary metadata element for the requested term.  The optional request body allows you to
             specify that the glossary element should only be returned if it was effective at a particular time.
@@ -2638,8 +2714,8 @@ class GlossaryBrowser(Client):
         url = (f"{self.platform_url}/servers/{self.view_server}/api/open-metadata/glossary-browser/glossaries/"
                f"for-term/{term_guid}/retrieve")
 
-        response = await self._async_make_request("POST", url, body)
-        return response.json().get("element", "No glossary found")
+        response = await self._async_make_request("POST", url, body_slimmer(body))
+        return response.json().get("element", NO_GLOSSARIES_FOUND)
 
     def get_glossary_for_term(self, term_guid: str, effective_time: str = None) -> dict | str:
         """Retrieve the glossary metadata element for the requested term.  The optional request body allows you to
@@ -2677,7 +2753,7 @@ class GlossaryBrowser(Client):
 
     async def _async_get_terms_by_name(self, term: str, glossary_guid: str = None, status_filter: list = [],
             effective_time: str = None, for_lineage: bool = False, for_duplicate_processing: bool = False,
-            start_from: int = 0, page_size: int = None, ) -> list:
+            start_from: int = 0, page_size: int = None, output_format = "JSON") -> list:
         """Retrieve glossary terms by display name or qualified name. Async Version.
 
         Parameters
@@ -2700,6 +2776,13 @@ class GlossaryBrowser(Client):
             The index of the first term to retrieve. Default is 0.
         page_size : int, optional
             The number of terms to retrieve per page. If not provided, it will use the default page size.
+        output_format: str, default = 'JSON'
+            Type of output to produce:
+            JSON - output standard json
+            MD - output standard markdown with no preamble
+            FORM - output markdown with a preamble for a form
+            REPORT - output markdown with a preamble for a report
+            DICT - output a simplified DICT structure
 
         Returns
         -------
@@ -2735,13 +2818,23 @@ class GlossaryBrowser(Client):
                f"&forLineage={for_lineage_s}&forDuplicateProcessing={for_duplicate_processing_s}")
 
         # print(f"\n\nURL is: \n {url}\n\nBody is: \n{body}")
+        response = await self._async_make_request("POST", url, body_slimmer(body))
+        term_elements = response.json().get("elementList", NO_TERMS_FOUND)
+        if term_elements == NO_TERMS_FOUND:
+            if output_format == 'JSON':
+                return NO_TERMS_FOUND
+            elif output_format in ['MD', 'FORM', 'REPORT', 'LIST']:
+                return "\n# No Terms found.\n"
+            elif output_format == 'DICT':
+                return None
+        if output_format != "JSON":  # return a simplified markdown representation
+            return self.generate_terms_md(term_elements, term, output_format)
+        return response.json().get("elementList", NO_TERMS_FOUND)
 
-        response = await self._async_make_request("POST", url, body)
-        return response.json().get("elementList", "No terms found")
 
     def get_terms_by_name(self, term: str, glossary_guid: str = None, status_filter: list = [],
             effective_time: str = None, for_lineage: bool = False, for_duplicate_processing: bool = False,
-            start_from: int = 0, page_size: int = None, ) -> list:
+            start_from: int = 0, page_size: int = None, output_format = "JSON") -> list:
         """Retrieve glossary terms by display name or qualified name.
 
         Parameters
@@ -2764,6 +2857,13 @@ class GlossaryBrowser(Client):
             The index of the first term to retrieve. Default is 0.
         page_size : int, optional
             The number of terms to retrieve per page. If not provided, it will use the default page size.
+         output_format: str, default = 'JSON'
+            Type of output to produce:
+            JSON - output standard json
+            MD - output standard markdown with no preamble
+            FORM - output markdown with a preamble for a form
+            REPORT - output markdown with a preamble for a report
+            DICT - output a simplified DICT structure
 
         Returns
         -------
@@ -2783,7 +2883,7 @@ class GlossaryBrowser(Client):
         loop = asyncio.get_event_loop()
         response = loop.run_until_complete(
             self._async_get_terms_by_name(term, glossary_guid, status_filter, effective_time, for_lineage,
-                for_duplicate_processing, start_from, page_size, ))
+                for_duplicate_processing, start_from, page_size, output_format))
         return response
 
     async def _async_get_term_by_guid(self, term_guid: str, output_format: str = 'JSON') -> dict | str:
@@ -3107,6 +3207,109 @@ class GlossaryBrowser(Client):
 
         return response
 
+    def list_term_revision_history(self, term_guid: str, output_format: str = "DICT") -> list | str:
+        """
+        Retrieve the revision history for a term.
+
+        This method retrieves the revision logs associated with a term, and for each revision log,
+        retrieves the revision history. The results are formatted according to the specified output format.
+
+        Parameters
+        ----------
+        term_guid : str
+            The GUID of the glossary term to retrieve the revision history for.
+        output_format : str, optional
+            The format in which to return the results. Can be "DICT", "MD", or "LIST".
+            Defaults to "DICT".
+
+        Returns
+        -------
+        list | str
+            If output_format is "DICT", returns a list of dictionaries containing the revision history.
+            If output_format is "MD", returns a markdown representation of the revision history.
+            If output_format is "LIST", returns a markdown table of the revision history.
+            If no revision logs are found, returns a string message "No revision logs found".
+        """
+        import re
+        validate_guid(term_guid)
+
+        # Get revision logs for the term
+        revision_logs = self.get_term_revision_logs(term_guid)
+        if isinstance(revision_logs, str):
+            return "No revision logs found"
+
+        # Process each revision log
+        all_entries = []
+        for log in revision_logs:
+            log_guid = log['elementHeader']['guid']
+            qualified_name = log.get('properties', {}).get('qualifiedName', '---')
+
+            # Get revision history for this log
+            history = self.get_term_revision_history(log_guid)
+            if isinstance(history, str):
+                continue
+
+            # Process each entry in the history
+            for entry in history:
+                # Extract update time from the title
+                title = entry.get('properties', {}).get('title', '---')
+
+                keyword_index = title.index('on')
+                update_time = title[keyword_index + 2:].strip()
+
+                entry_data = {
+                    'qualifiedName': qualified_name,
+                    'title': title,
+                    'text': entry.get('properties', {}).get('text', '---'),
+                    'updateTime': update_time  # Use extracted date/time or fall back to title
+                }
+                all_entries.append(entry_data)
+
+        # Sort entries by update time
+        sorted_entries = sorted(all_entries, key=lambda x: x['updateTime'] if x['updateTime'] != '---' else '', reverse=True)
+
+        # Return in the specified format
+        if output_format == "DICT":
+            return sorted_entries
+        elif output_format == "LIST":
+            # Create markdown table
+            if not sorted_entries:
+                return "No revision entries found"
+
+            # Get headers
+            headers = sorted_entries[0].keys()
+
+            # Create header row
+            header_row = " | ".join(headers)
+            separator_row = " | ".join(["---"] * len(headers))
+
+            # Create rows
+            rows = []
+            for entry in sorted_entries:
+                row = " | ".join(str(entry.get(header, "---")) for header in headers)
+                rows.append(row)
+
+            # Combine into table
+            markdown_table = f"{header_row}\n{separator_row}\n" + "\n".join(rows)
+            return markdown_table
+        elif output_format == "MD":
+            # Create markdown representation
+            if not sorted_entries:
+                return "No revision entries found"
+
+            md_output = "\n"
+
+            for entry in sorted_entries:
+                md_output += f"* Note Log Name: \n{entry['qualifiedName']}\n\n"
+                md_output += f"* Note Log Entry Title: \n{entry['title']}\n\n"
+                md_output += f"* Note Log Entry: \n\t{entry['text']}\n\n"
+                md_output += "---\n\n"
+
+            return md_output
+        else:
+            # Default to DICT format
+            return sorted_entries
+
 
     def list_full_term_history(self, term_guid: str, output_type: str = "DICT") -> list | str:
         """
@@ -3138,19 +3341,19 @@ class GlossaryBrowser(Client):
             return "No History Found"
         version_history = []
         for ver in history:
-            create_time = ver["elementHeader"]["versions"].get("createTime", "---")
-            update_time = ver["elementHeader"]["versions"].get("createTime", "---")
-            created_by = ver["elementHeader"]["versions"].get("createdBy", "---")
+            create_time = ver["elementHeader"]["versions"].get("createTime", " ")
+            update_time = ver["elementHeader"]["versions"].get("createTime", " ")
+            created_by = ver["elementHeader"]["versions"].get("createdBy", " ")
             updated_by = ver["elementHeader"]["versions"].get("updatedBy", "---")
             version = ver["elementHeader"]["versions"].get("version")
 
-            qualified_name = ver["glossaryTermProperties"].get("qualifiedName", '---')
-            display_name = ver["glossaryTermProperties"].get("displayName", '---')
-            summary = ver["glossaryTermProperties"].get("summary", '---')
-            description = ver["glossaryTermProperties"].get("description", '---')
-            examples = ver["glossaryTermProperties"].get("examples", '---')
-            usage = ver["glossaryTermProperties"].get("usage", '---')
-            version_identifier = ver["glossaryTermProperties"].get("versionIdentifier", '---')
+            qualified_name = ver["glossaryTermProperties"].get("qualifiedName", ' ')
+            display_name = ver["glossaryTermProperties"].get("displayName", ' ')
+            summary = ver["glossaryTermProperties"].get("summary", ' ')
+            description = ver["glossaryTermProperties"].get("description", ' ')
+            examples = ver["glossaryTermProperties"].get("examples", ' ')
+            usage = ver["glossaryTermProperties"].get("usage", ' ')
+            version_identifier = ver["glossaryTermProperties"].get("versionIdentifier", ' ')
 
             version_history.append({
                 "version": version, "displayName": display_name, "summary": summary, "created": create_time,
@@ -3178,6 +3381,8 @@ class GlossaryBrowser(Client):
             # Combine everything into a Markdown table string
             markdown_table = f"{header_row}\n{separator_row}\n" + "\n".join(rows)
             return markdown_table
+        else:
+            return None
 
     async def _async_find_glossary_terms(self, search_string: str, glossary_guid: str = None, status_filter: list = [],
             effective_time: str = None, starts_with: bool = False, ends_with: bool = False, ignore_case: bool = False,