Named Entity Repository API Reference

interface NamedEntityDataRepository {
    /**
     * Save a single entity
     * @param entity Entity to save
     * @return Saved entity (may include generated fields)
     */
    fun save(entity: NamedEntityData): NamedEntityData

    /**
     * Save multiple entities in batch
     * @param entities Collection of entities to save
     * @return List of saved entities
     */
    fun saveAll(entities: Collection<NamedEntityData>): List<NamedEntityData>

    /**
     * Update an existing entity
     * @param entity Entity with updated values
     * @return Updated entity
     */
    fun update(entity: NamedEntityData): NamedEntityData
}

interface NamedEntityDataRepository {
    /**
     * Find entity by ID
     * @param id Entity identifier
     * @return Entity or null if not found
     */
    fun findById(id: String): NamedEntityData?

    /**
     * Find entity by ID with specific interfaces
     * @param id Entity identifier
     * @param candidateInterfaces Interfaces to implement
     * @return Entity instance or null
     */
    fun findById(
        id: String,
        vararg candidateInterfaces: Class<out NamedEntity>
    ): NamedEntity?

    /**
     * Find entity by ID, treating it as generic entity
     * @param id Entity identifier
     * @return Generic entity instance or null
     */
    fun findEntityById(id: String): NamedEntity?

    /**
     * Find all entities with a specific label
     * @param label Entity label/type
     * @return List of matching entities
     */
    fun findByLabel(label: String): List<NamedEntityData>
}

interface NamedEntityDataRepository {
    /**
     * Delete entity by ID
     * @param id Entity identifier
     * @return true if entity was deleted, false if not found
     */
    fun delete(id: String): Boolean
}

interface NamedEntityDataRepository {
    /**
     * Check if a type has native (non-proxy) implementation
     * @param type Entity class
     * @return true if type is natively supported
     */
    fun isNativeType(type: Class<*>): Boolean

    /**
     * Find native entity by ID
     * @param id Entity identifier
     * @param type Entity class with native implementation
     * @return Typed entity instance or null
     */
    fun <T : NamedEntity> findNativeById(id: String, type: Class<T>): T?

    /**
     * Find all native entities of a type
     * @param type Entity class with native implementation
     * @return List of typed entities or null if type not supported
     */
    fun <T : NamedEntity> findNativeAll(type: Class<T>): List<T>?
}

interface NamedEntityDataRepository {
    /**
     * ObjectMapper for entity conversion
     */
    val objectMapper: ObjectMapper

    /**
     * Find and convert entity to typed instance
     * @param id Entity identifier
     * @param type Target entity class
     * @return Typed entity instance or null
     */
    fun <T : NamedEntity> findTypedById(id: String, type: Class<T>): T?

    /**
     * Find all entities of a specific type
     * @param type Entity class
     * @return List of typed entities
     */
    fun <T : NamedEntity> findAll(type: Class<T>): List<T>
}

interface NamedEntityDataRepository {
    /**
     * Data dictionary for domain type resolution
     */
    val dataDictionary: DataDictionary

    /**
     * Find entities by domain type
     * @param type Domain type
     * @return List of typed entities
     */
    fun <T : NamedEntity> findByDomainType(type: DomainType): List<T>

    /**
     * Find entity data by domain type
     * @param type Domain type
     * @return List of NamedEntityData instances
     */
    fun findEntityDataByDomainType(type: DomainType): List<NamedEntityData>
}

/**
 * Named relationship that may have properties
 */
data class RelationshipData(
    /**
     * Relationship type name (e.g., "WORKS_WITH", "CONTRIBUTES_TO")
     */
    val name: String,

    /**
     * Optional properties associated with the relationship
     */
    val properties: Map<String, Any> = emptyMap()
)

interface NamedEntityDataRepository {
    /**
     * Create a relationship between two entities
     * @param a Source entity identifier
     * @param b Target entity identifier
     * @param relationship Relationship data with name and properties
     */
    fun createRelationship(
        a: RetrievableIdentifier,
        b: RetrievableIdentifier,
        relationship: RelationshipData
    )
}

interface NamedEntityDataRepository : RelationshipNavigator {
    /**
     * Find related entities
     * @param source Source entity identifier
     * @param relationshipName Relationship type name
     * @param direction Direction of relationship (OUTGOING, INCOMING, BOTH)
     * @return List of related entities
     */
    override fun findRelated(
        source: RetrievableIdentifier,
        relationshipName: String,
        direction: RelationshipDirection
    ): List<NamedEntityData>

    /**
     * Find single related entity
     * @param source Source entity identifier
     * @param relationshipName Relationship type name
     * @param direction Direction of relationship
     * @return Related entity or null if not found
     */
    fun findRelatedSingle(
        source: RetrievableIdentifier,
        relationshipName: String,
        direction: RelationshipDirection
    ): NamedEntityData?
}

interface NamedEntityDataRepository : FilteringVectorSearch {
    /**
     * Vector search for entities
     * @param request Search request with query and parameters
     * @param metadataFilter Optional property filter
     * @param entityFilter Optional entity label filter
     * @return List of similarity results
     */
    fun vectorSearch(
        request: TextSimilaritySearchRequest,
        metadataFilter: PropertyFilter? = null,
        entityFilter: EntityFilter? = null
    ): List<SimilarityResult<NamedEntityData>>

    /**
     * Generic vector search with filtering
     * @param request Search request
     * @param clazz Result class type
     * @param metadataFilter Optional property filter
     * @param entityFilter Optional entity filter
     * @return List of typed similarity results
     */
    override fun <T : Retrievable> vectorSearchWithFilter(
        request: TextSimilaritySearchRequest,
        clazz: Class<T>,
        metadataFilter: PropertyFilter?,
        entityFilter: EntityFilter?
    ): List<SimilarityResult<T>>
}

interface NamedEntityDataRepository : FilteringTextSearch {
    /**
     * Lucene syntax support notes
     */
    override val luceneSyntaxNotes: String

    /**
     * Text search for entities
     * @param request Search request with query text (Lucene syntax)
     * @param metadataFilter Optional property filter
     * @param entityFilter Optional entity label filter
     * @return List of similarity results
     */
    fun textSearch(
        request: TextSimilaritySearchRequest,
        metadataFilter: PropertyFilter? = null,
        entityFilter: EntityFilter? = null
    ): List<SimilarityResult<NamedEntityData>>

    /**
     * Generic text search with filtering
     * @param request Search request
     * @param clazz Result class type
     * @param metadataFilter Optional property filter
     * @param entityFilter Optional entity filter
     * @return List of typed similarity results
     */
    override fun <T : Retrievable> textSearchWithFilter(
        request: TextSimilaritySearchRequest,
        clazz: Class<T>,
        metadataFilter: PropertyFilter?,
        entityFilter: EntityFilter?
    ): List<SimilarityResult<T>>
}

interface NamedEntityDataRepository {
    /**
     * Find entities by label with optional property filter
     * @param label Entity label
     * @param filter Optional property filter
     * @return List of matching entities
     */
    fun find(label: String, filter: PropertyFilter? = null): List<NamedEntityData>

    /**
     * Find entities by label set with optional property filter
     * @param labels Entity label filter
     * @param filter Optional property filter
     * @return List of matching entities
     */
    fun find(
        labels: EntityFilter.HasAnyLabel,
        filter: PropertyFilter? = null
    ): List<NamedEntityData>
}

interface NamedEntityDataRepository : FinderOperations {
    /**
     * Find entity by ID and class
     * @param id Entity identifier
     * @param clazz Expected result class
     * @return Entity or null if not found
     */
    override fun <T> findById(id: String, clazz: Class<T>): T?

    /**
     * Find retrievable by ID and type name
     * @param id Entity identifier
     * @param type Type name (label)
     * @return Retrievable or null if not found
     */
    override fun <T : Retrievable> findById(id: String, type: String): T?

    /**
     * Check if type is supported
     * @param type Type name
     * @return true if type is supported
     */
    override fun supportsType(type: String): Boolean
}