Package com.ssgllc.fish.service.util.published

Class AdvancedSearchUtil

java.lang.Object
com.ssgllc.fish.service.util.published.AdvancedSearchUtil
@Component public class AdvancedSearchUtil extends Object

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected com.ssgllc.fish.service.search.EmbeddingService
    embeddingService
     
    protected com.ssgllc.fish.service.search.SemanticSearchService
    semanticSearchService
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    AdvancedSearchUtil()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    <EntityT extends com.ssgllc.fish.domain.CasetivityEntity, DtoT extends com.ssgllc.fish.service.dto.CasetivityEntityDTO>
    List<DtoT>
    customSemanticSearch(String sqlQuery, String searchText, String returnType, Integer topK, Map<String,Object> params, String expand)
    Executes a custom semantic search using a raw SQL template and input text, binding parameters, and returns up to the top K matching DTOs, with optional expansion.
    float[]
    generateEmbeddings(String input)
    Generates a dense vector embedding for the given input text.
    <T> void
    generateEmbeddingsForAllEntities(String entityType, List<Object> entityIds, String fieldName, Function<com.ssgllc.fish.service.dto.CasetivityEntityDTO,String> textExtractor)
    For each entity of the given type and IDs, extracts text via the provided function, generates an embedding vector, and updates the entity’s specified field with that vector.
    <EntityT extends com.ssgllc.fish.domain.CasetivityEntity, DtoT extends com.ssgllc.fish.service.dto.CasetivityEntityDTO>
    List<DtoT>
    semanticSearch(String searchText, String returnEntityType, String vectorFieldName, Integer topK)
    Performs a semantic‐vector search over the specified entity type using the given text, returning up to the top K matching DTOs, without any expansions.
    <EntityT extends com.ssgllc.fish.domain.CasetivityEntity, DtoT extends com.ssgllc.fish.service.dto.CasetivityEntityDTO>
    List<DtoT>
    semanticSearch(String searchText, String returnEntityType, String vectorFieldName, Integer topK, String expand, Float maxDistance)
    Performs a semantic‐vector search over the specified entity type using the given text, returning up to the top K matching DTOs, with optional expansion of nested properties.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • semanticSearchService

      @Autowired protected com.ssgllc.fish.service.search.SemanticSearchService semanticSearchService

    • embeddingService

      @Autowired protected com.ssgllc.fish.service.search.EmbeddingService embeddingService

  • Constructor Details

    • AdvancedSearchUtil

      public AdvancedSearchUtil()

  • Method Details

    • semanticSearch

      public <EntityT extends com.ssgllc.fish.domain.CasetivityEntity, DtoT extends com.ssgllc.fish.service.dto.CasetivityEntityDTO> List<DtoT> semanticSearch(String searchText, String returnEntityType, String vectorFieldName, Integer topK)
      Performs a semantic‐vector search over the specified entity type using the given text, returning up to the top K matching DTOs, without any expansions.
      Parameters:
      searchText - The natural‐language text to search for.
      returnEntityType - The simple name of the CasetivityEntity subclass to return.
      vectorFieldName - The name of the field on the entity that holds its embedding vector.
      topK - The maximum number of results to return.
      Returns:
      A list of DTOs of type CasetivityEntityDTO matching the semantic query, or an empty list if none found.

      Groovy example:
      return advancedSearchUtil.semanticSearch("Origin of the spanning-tree protocol", "Article", "embedding", 5)
      Note: SpEL usage is not supported for this method; use only in Groovy scripts.

    • semanticSearch

      public <EntityT extends com.ssgllc.fish.domain.CasetivityEntity, DtoT extends com.ssgllc.fish.service.dto.CasetivityEntityDTO> List<DtoT> semanticSearch(String searchText, String returnEntityType, String vectorFieldName, Integer topK, String expand, Float maxDistance)
      Performs a semantic‐vector search over the specified entity type using the given text, returning up to the top K matching DTOs, with optional expansion of nested properties.
      Parameters:
      searchText - The natural‐language text to search for.
      returnEntityType - The simple name of the CasetivityEntity subclass to return.
      vectorFieldName - The name of the field on the entity that holds its embedding vector.
      topK - The maximum number of results to return.
      expand - A comma‐delimited list of associations or fields to eagerly expand in the result DTOs.
      maxDistance - The maximum allowed cosine distance(inclusive); only entities with distance invalid input: '<'= this value will be returned
      Returns:
      A list of DTOs of type DtoT matching the semantic query, possibly with expanded fields.

      Groovy example:
      return advancedSearchUtil.semanticSearch("Origin of the spanning-tree protocol", "Article", "embedding", 5, "comments,attachments", 0.3)
      Note: SpEL usage is not supported for this method; use only in Groovy scripts.

    • customSemanticSearch

      public <EntityT extends com.ssgllc.fish.domain.CasetivityEntity, DtoT extends com.ssgllc.fish.service.dto.CasetivityEntityDTO> List<DtoT> customSemanticSearch(String sqlQuery, String searchText, String returnType, Integer topK, Map<String,Object> params, String expand)
      Executes a custom semantic search using a raw SQL template and input text, binding parameters, and returns up to the top K matching DTOs, with optional expansion.
      Parameters:
      sqlQuery - A SQL string (possibly with named parameters) defining how to fetch and score entities. vec parameter will be replaced by embeddings of searchText.
      searchText - The natural‐language text to feed into the semantic scoring function.
      returnType - The simple name of the CasetivityEntity subclass to return.
      topK - The maximum number of results to return.
      params - A map of named parameters to bind into the SQL query.
      expand - A comma‐delimited list of associations or fields to eagerly expand in the result DTOs.
      Returns:
      A list of DTOs of type DtoT matching the custom semantic query.

      Groovy example:
      def searchSql = """ SELECT a.* FROM article a ORDER BY a.embedding invalid input: '<'=> CAST(:vec as vector) """ return advancedSearchUtil.semanticSearch(searchSql, "Origin of spanning tree protocol", "Article", 2, [:], "comments")
      Recommended: Prefer the simpler semanticSearch(...) overloads for most use cases; use this custom‐SQL variant only when those methods cannot satisfy your requirements.
      Note: SpEL usage is not supported for this method; use only in Groovy scripts.

    • generateEmbeddings

      public float[] generateEmbeddings(String input)
      Generates a dense vector embedding for the given input text.
      Parameters:
      input - The source text to embed.
      Returns:
      A float array representing the text’s embedding vector.

      Groovy example:
      return advancedSearchUtil.generateEmbeddings("Summary of Article")
      Note: SpEL usage is not supported for this method; use only in Groovy scripts.

    • generateEmbeddingsForAllEntities

      public <T> void generateEmbeddingsForAllEntities(String entityType, List<Object> entityIds, String fieldName, Function<com.ssgllc.fish.service.dto.CasetivityEntityDTO,String> textExtractor)
      For each entity of the given type and IDs, extracts text via the provided function, generates an embedding vector, and updates the entity’s specified field with that vector.
      Parameters:
      entityType - Name of the entity.
      entityIds - A list of entity identifiers specifying which records to process.
      fieldName - The name of the field on each entity to store the generated embeddings.
      textExtractor - A function that, given a CasetivityEntityDTO, returns the text whose embedding should be generated.

      Groovy example:
      import com.ssgllc.fish.service.dto.CasetivityEntityDTO;
      import java.util.function.Function;

      // Retrieve the batch of IDs and entity type from the execution context
      def batchEntityIds = ['ID1','ID2']
      def entityType = "Article"
      // Define how to extract text from each DTO
      Function<CasetivityEntityDTO,String> extractor =
      { dto -> dto.author + " " + dto.body }

      // Generate embeddings for all entities in the batch
      advancedSearchUtil.generateEmbeddingsForAllEntities(
      entityType,
      batchEntityIds,
      "embedding",
      extractor
      )
      Note: SpEL usage is not supported for this method; use only in Groovy scripts.