Hibernate 애플리케이션 개발

서비스 자체 외에도 중앙 서비스 API는 org.hibernate.service.ServiceRegistry 인터페이스입니다. 서비스 레지스트리의 주요 목적은 서비스에 대한 액세스를 보유, 관리 및 제공하는 것입니다.

서비스 레지스트리는 계층 구조입니다. 한 레지스트리의 서비스는 해당 레지스트리와 상위 레지스트리의 서비스를 활용하고 활용할 수 있습니다.

org.hibernate.service.ServiceRegistryBuilder를 사용하여 org.hibernate.service.ServiceRegistry 인스턴스를 빌드합니다.

ServiceRegistryBuilder registryBuilder =
    new ServiceRegistryBuilder( bootstrapServiceRegistry );
    ServiceRegistry serviceRegistry = registryBuilder.buildServiceRegistry();

org.hibernate.service.ServiceRegistry 가 구축되면 변경 불가능한 것으로 간주됩니다. 서비스 자체에서 재구성을 수락할 수 있지만, 여기에서 불변성은 서비스 추가 또는 교체를 의미합니다. 따라서 org.hibernate.service.ServiceRegistryBuilder 에서 제공하는 또 다른 역할은 생성된 org.hibernate.service.ServiceRegistry 에 포함될 서비스를 수정할 수 있습니다.

org.hibernate.service.ServiceRegistryBuilder 에 사용자 지정 서비스에 대해 알리는 두 가지 방법이 있습니다.

두 방법 중 하나는 새 서비스 역할 추가 등의 레지스트리 확장 및 서비스 구현 대체와 같은 서비스 재정의에 유효합니다.

ServiceRegistryBuilder registryBuilder =
    new ServiceRegistryBuilder(bootstrapServiceRegistry);
registryBuilder.addService(JdbcServices.class, new MyCustomJdbcService());
ServiceRegistry serviceRegistry = registryBuilder.buildServiceRegistry();

public class MyCustomJdbcService implements JdbcServices{

   @Override
   public ConnectionProvider getConnectionProvider() {
       return null;
   }

   @Override
   public Dialect getDialect() {
       return null;
   }

   @Override
   public SqlStatementLogger getSqlStatementLogger() {
       return null;
   }

   @Override
   public SqlExceptionHelper getSqlExceptionHelper() {
       return null;
   }

   @Override
   public ExtractedDatabaseMetaData getExtractedMetaDataSupport() {
       return null;
   }

   @Override
   public LobCreator getLobCreator(LobCreationContext lobCreationContext) {
       return null;
   }

   @Override
   public ResultSetWrapper getResultSetWrapper() {
       return null;
   }
}

boot-strap 레지스트리에는 대부분의 작업이 작동하려면 반드시 사용할 수 있는 서비스가 있습니다. 여기에 있는 주요 서비스는 완벽한 예인 ClassLoaderService 입니다. 구성 파일을 해결하더라도 리소스 조회 등 클래스 로드 서비스에 액세스할 수 있어야 합니다. 이는 일반적으로 상위 레지스트리가 아닌 루트 레지스트리입니다.

boot-strap 레지스트리 인스턴스는 org.hibernate.service.BootstrapServiceRegistryBuilder 클래스를 사용하여 빌드됩니다.

Using BootstrapServiceRegistryBuilder

BootstrapServiceRegistry bootstrapServiceRegistry =
    new BootstrapServiceRegistryBuilder()
    // pass in org.hibernate.integrator.spi.Integrator instances which are not
    // auto-discovered (for whatever reason) but which should be included
    .with(anExplicitIntegrator)
    // pass in a class loader that Hibernate should use to load application classes
    .with(anExplicitClassLoaderForApplicationClasses)
    // pass in a class loader that Hibernate should use to load resources
    .with(anExplicitClassLoaderForResources)
    // see BootstrapServiceRegistryBuilder for rest of available methods
    ...
    // finally, build the bootstrap registry with all the above options
    .build();

org.hibernate.event.service.spi.EventListenerRegistry

org.hibernate.integrator.spi.Integrator 의 주요 사용 사례는 이벤트 리스너를 등록하고 서비스를 제공하고 org.hibernate.integrator.spi.ServiceContributingIntegrator 를 참조하십시오.

public class MyIntegrator implements org.hibernate.integrator.spi.Integrator {

    public void integrate(
            Configuration configuration,
            SessionFactoryImplementor sessionFactory,
            SessionFactoryServiceRegistry serviceRegistry) {
        // As you might expect, an EventListenerRegistry is the thing with which event listeners are registered  It is a
        // service so we look it up using the service registry
        final EventListenerRegistry eventListenerRegistry = serviceRegistry.getService(EventListenerRegistry.class);

        // If you wish to have custom determination and handling of "duplicate" listeners, you would have to add an
        // implementation of the org.hibernate.event.service.spi.DuplicationStrategy contract like this
        eventListenerRegistry.addDuplicationStrategy(myDuplicationStrategy);

        // EventListenerRegistry defines 3 ways to register listeners:
        //     1) This form overrides any existing registrations with
        eventListenerRegistry.setListeners(EventType.AUTO_FLUSH, myCompleteSetOfListeners);
        //     2) This form adds the specified listener(s) to the beginning of the listener chain
        eventListenerRegistry.prependListeners(EventType.AUTO_FLUSH, myListenersToBeCalledFirst);
        //     3) This form adds the specified listener(s) to the end of the listener chain
        eventListenerRegistry.appendListeners(EventType.AUTO_FLUSH, myListenersToBeCalledLast);
    }
}

Hibernate Search는 다양한 백엔드를 사용하여 작업 배치를 처리합니다. 백엔드는 구성 옵션 default.worker.backend 로 국한되지 않습니다. 이 속성은 백엔드 구성의 일부인 백엔드QueueProcessor 인터페이스의 구현을 지정합니다. 백엔드(예: Jakarta Messaging 백엔드)를 설정하려면 추가 설정이 필요합니다.

Lucene 모드에서는 노드의 모든 인덱스 업데이트가 디렉터리 공급업체를 사용하여 Lucene 디렉터리에 동일한 노드에서 실행됩니다. 비클러스터형 환경이나 공유 디렉터리 저장소가 있는 클러스터형 환경에서 이 모드를 사용합니다.

그림 7.1. Lucene 백엔드 구성

Lucene 모드는 디렉터리가 잠금 전략을 관리하는 비클러스터형 또는 클러스터된 애플리케이션을 대상으로 합니다. Lucene 모드의 주요 장점은 단순하고 Lucene 쿼리의 변경 사항을 즉시 확인하는 것입니다. NRT(Non-Real Time) 백엔드는 비클러스터형 인덱스 구성 및 비공유 인덱스 구성의 대체 백엔드입니다.

노드의 인덱스 업데이트가 자카르타 메시징 큐로 전송됩니다. 고유한 리더는 대기열을 처리하고 마스터 인덱스를 업데이트합니다. 이후 마스터 인덱스는 마스터 및 슬레이브 패턴을 설정하기 위해 슬레이브 복사본에 정기적으로 복제됩니다. 마스터는 Lucene 인덱스 업데이트를 담당합니다. 슬레이브는 읽기 및 쓰기 작업을 허용하지만 로컬 인덱스 복사본에 대한 읽기 작업을 처리합니다. 마스터는 Lucene 인덱스를 업데이트하는 데만 책임이 있습니다. 마스터만 업데이트 작업에 로컬 변경 사항을 적용합니다.

그림 7.2. 자카르타 메시징 서비스 백엔드 구성

이 모드는 처리량이 중요하고 인덱스 업데이트 지연이 경제적인 클러스터형 환경을 대상으로 합니다. 자카르타 메시징 공급자는 안정성을 보장하고 슬레이브를 사용하여 로컬 인덱스 복사본을 변경합니다.

Hibernate Search는 공유 전략을 사용하여 IndexReader 가 계속해서 업데이트되는 제공된 여러 쿼리와 스레드에서 주어진 Lucene 인덱스에 대해 동일한 IndexReader 를 공유합니다. IndexReader 가 업데이트되지 않으면 새 항목이 열리고 제공됩니다. 각 IndexReader 는 여러 SegmentReaders 로 구성됩니다. 공유 전략은 마지막 열기 후에 수정되거나 생성된 세그먼트를 다시 열고 이전 인스턴스에서 이미 로드된 세그먼트를 공유합니다. 기본 전략입니다.

비공유 전략을 사용하면 쿼리가 실행될 때마다 Lucene IndexReader 가 열립니다. IndexReader 열기 및 시작은 비용이 많이 드는 작업입니다. 따라서 각 쿼리 실행에 대해 IndexReader 를 여는 것은 효율적인 전략이 아닙니다.

org.hibernate.search.reader.ReaderProvider 구현을 사용하여 사용자 정의 리더 전략을 작성할 수 있습니다. 구현은 안전한 스레드여야 합니다.

디렉터리 기반 구현은 기본 IndexManager 구현입니다. 구성 가능하며 reader 전략, 백엔드 및 디렉터리 공급업체에 대해 별도의 구성을 허용합니다.

NRTIndexManager 는 기본 IndexManager 의 확장이며 짧은 대기 시간 색인 쓰기 기능을 위한 Lucene NRT, near Real Time을 활용합니다. 하지만 lucene 이 아닌 대체 백엔드에 대한 구성 설정을 무시하고 Directory 에서 독점적인 쓰기 잠금을 갖게 됩니다.

IndexWriter 는 짧은 대기 시간을 제공하기 위해 디스크의 모든 변경을 플러시하지 않습니다. 쿼리는 플러시되지 않은 인덱스 작성기 버퍼에서 업데이트된 상태를 읽을 수 있습니다. 그러나 IndexWriter 가 종료되거나 애플리케이션 충돌이 발생하면 업데이트가 손실되어 인덱스를 다시 빌드해야 합니다.

언급한 단점으로 인해 데이터가 제한된 클러스터되지 않은 웹 사이트에는 실시간 구성이 권장되며 성능 향상을 위해 마스터 노드를 개별적으로 구성할 수 있기 때문입니다.

사용자 정의 구현에 대해 정규화된 클래스 이름을 지정하여 사용자 지정 IndexManager 를 설정합니다. 다음과 같이 구현에 대한 인수 없는 생성자를 설정합니다.

[default|<indexname>].indexmanager = my.corp.myapp.CustomIndexManager

사용자 정의 인덱스 관리자 구현에는 기본 구현과 동일한 구성 요소가 필요하지 않습니다. 예를 들어 디렉터리 인터페이스를 노출하지 않는 원격 인덱싱 서비스에 위임합니다.

이 섹션에서는 마스터/슬레이브 Hibernate Search 아키텍처를 구성하는 방법을 자세히 설명합니다.

그림 7.3. 자카르타 메시징 백엔드 구성

모든 인덱스 업데이트 작업은 자카르타 메시징 큐로 전송됩니다. 인덱스 쿼리 작업은 로컬 인덱스 사본에서 실행됩니다.

### slave configuration

## DirectoryProvider
# (remote) master location
hibernate.search.default.sourceBase = /mnt/mastervolume/lucenedirs/mastercopy

# local copy location
hibernate.search.default.indexBase = /Users/prod/lucenedirs

# refresh every half hour
hibernate.search.default.refresh = 1800

# appropriate directory provider
hibernate.search.default.directory_provider = filesystem-slave

## Back-end configuration
hibernate.search.default.worker.backend = jms
hibernate.search.default.worker.jms.connection_factory = /ConnectionFactory
hibernate.search.default.worker.jms.queue = queue/hibernatesearch
#optional jndi configuration (check your Jakarta Messaging provider for more information)

## Optional asynchronous execution strategy
# hibernate.search.default.worker.execution = async
# hibernate.search.default.worker.thread_pool.size = 2
# hibernate.search.default.worker.buffer_queue.max = 50

모든 인덱스 업데이트 작업은 자카르타 메시징 큐에서 가져온 후 실행됩니다. 마스터 인덱스는 정기적으로 복사됩니다.

Jakarta Messaging 큐의 인덱스 업데이트 작업이 실행되고 마스터 인덱스가 정기적으로 복사됩니다.

### master configuration

## DirectoryProvider
# (remote) master location where information is copied to
hibernate.search.default.sourceBase = /mnt/mastervolume/lucenedirs/mastercopy

# local master location
hibernate.search.default.indexBase = /Users/prod/lucenedirs

# refresh every half hour
hibernate.search.default.refresh = 1800

# appropriate directory provider
hibernate.search.default.directory_provider = filesystem-master

## Back-end configuration
#Back-end is the default for Lucene

Hibernate Search 프레임워크 구성 외에도 메시지 기반 빈을 작성하고 자카르타 메시징을 통해 인덱스 작동 대기열을 처리하도록 설정해야 합니다.

@MessageDriven(activationConfig = {
      @ActivationConfigProperty(propertyName="destinationType",
                                propertyValue="javax.jms.Queue"),
      @ActivationConfigProperty(propertyName="destination",
                                propertyValue="queue/hibernatesearch"),
      @ActivationConfigProperty(propertyName="DLQMaxResent", propertyValue="1")
   } )
public class MDBSearchController extends AbstractJMSHibernateSearchController
                                 implements MessageListener {
    @PersistenceContext EntityManager em;

    //method retrieving the appropriate session
    protected Session getSession() {
        return (Session) em.getDelegate();
    }

    //potentially close the session opened in #getSession(), not needed here
    protected void cleanSessionIfNeeded(Session session)
    }
}

이 예제는 Hibernate Search 소스 코드에서 사용할 수 있는 추상적인 Jakarta Messaging 컨트롤러 클래스를 상속하고 Jakarta EE MDB를 구현합니다. 이 구현은 예제로 제공되며 자카르타 EE 메시지 기반 빈을 사용하도록 조정할 수 있습니다.

Hibernate Search는 mergeFactor, maxMergeDocs, maxBufferedDocs 와 같은 기본 Lucene IndexWriter 로 전달되는 매개변수 세트를 지정하여 Lucene 색인 성능을 조정하는 데 사용됩니다. 이러한 매개변수를 모든 인덱스에 적용되는 기본값으로, 인덱스별로 또는 shard별로 지정합니다.

다양한 사용 사례에 맞게 조정할 수 있는 몇 가지 낮은 수준의 IndexWriter 설정이 있습니다. 이러한 매개변수는 indexwriter 키워드로 그룹화됩니다.

hibernate.search.[default|<indexname>].indexwriter.<parameter_name>

특정 shard 구성의 인덱스 라이터 값에 대한 값이 설정되지 않은 경우 Hibernate Search는 인덱스 섹션을 확인한 다음 default 섹션에서 확인합니다.

다음 테이블의 구성으로 이러한 설정이 적용되므로 두 번째 shard는 인덱스 의 두 번째 shard에 적용됩니다.

다른 모든 값은 Lucene에 정의된 기본값을 사용합니다.

모든 값의 기본값은 Lucene의 자체 기본값으로 두는 것입니다. 성능 색인 및 동작 속성에 나열된 값은 사용 중인 Lucene 버전에 따라 다릅니다. 표시된 값은 버전 2.4 에 상대적입니다.

다양한 사용 사례에 맞게 조정할 수 있는 몇 가지 낮은 수준의 IndexWriter 설정이 있습니다. 이러한 매개변수는 indexwriter 키워드로 그룹화됩니다.

default.<indexname>.indexwriter.<parameter_name>

shard 구성의 indexwriter 에 대한 값이 설정되지 않은 경우 Hibernate Search는 인덱스 섹션을 확인한 다음 default 섹션에서 확인합니다.

다음 구성으로 이러한 설정이 적용되며, 두 번째 shard는 index index 의 두 번째 shard에 적용됩니다.

default.Animals.2.indexwriter.max_merge_docs = 10
default.Animals.2.indexwriter.merge_factor = 20
default.Animals.2.indexwriter.term_index_interval = default
default.indexwriter.max_merge_docs = 100
default.indexwriter.ram_buffer_size = 64

다른 모든 값은 Lucene에 정의된 기본값을 사용합니다.

Lucene 기본값은 Hibernate Search의 기본 설정입니다. 따라서 다음 표에 나열된 값은 사용 중인 Lucene 버전에 따라 다릅니다. 표시된 값은 버전 2.4 에 상대적입니다. Lucene 색인 성능에 대한 자세한 내용은 Lucene 문서를 참조하십시오.

아키텍처에서 이를 허용하는 경우 인덱스 쓰기 효율성을 높이기 위해 default.exclusive_index_use=true 를 유지합니다.

인덱싱 속도를 튜닝할 때 권장되는 접근 방식은 오브젝트 로드를 최적화하는 데 먼저 집중한 다음 달성한 타이밍을 기준으로 사용하여 인덱싱 프로세스를 조정하는 것입니다. 차단을 작업자 백엔드 로 설정하고 인덱싱 루틴을 시작합니다. 이 백엔드는 Hibernate 검색을 비활성화하지 않습니다. 필요한 변경 집합을 인덱스에 생성하지만 인덱스에 플러시하는 대신 폐기합니다. hibernate.search.indexing_strategy 를 manual 로 설정하는 것과 반대로, 연결된 엔터티도 다시 인덱싱 되므로 블랙 라인을 사용하면 데이터베이스에서 더 많은 데이터를 로드할 수 있습니다.

hibernate.search.[default|<indexname>].worker.backend blackhole

다음 옵션은 생성된 세그먼트의 최대 크기를 구성합니다.

//to be fairly confident no files grow above 15MB, use:
hibernate.search.default.indexwriter.ram_buffer_size = 10
hibernate.search.default.indexwriter.merge_max_optimize_size = 7
hibernate.search.default.indexwriter.merge_max_size = 7

병합 세그먼트가 두 세그먼트를 하나의 큰 세그먼트로 결합하므로 병합 작업의 max_size 를 하드 제한 세그먼트 크기의 절반 미만으로 설정합니다.

새 세그먼트는 처음에 예상보다 큰 크기일 수 있지만 세그먼트는 ram_buffer_size 보다 크게 만들어지지 않습니다. 이 임계값은 추정치로 확인됩니다.

엔터티 매핑에 가장 일반적으로 사용되는 주석으로 시작하겠습니다.

Lucene 기반 쿼리 API는 다음과 같은 일반적인 주석을 사용하여 엔터티를 매핑합니다.

무엇보다도 지속 클래스를 인덱스 가능으로 선언해야 합니다. 이는 @Indexed로 클래스에 주석을 달아 수행됩니다(Indexed 로 주석 처리되지 않은 모든 엔터티는 인덱싱 프로세스에서 무시 됩니다 ).

@Entity
@Indexed
public class Essay {
...
}

선택적으로 @Indexed 주석의 index 속성을 지정하여 인덱스의 기본 이름을 변경할 수 있습니다.

엔터티의 각 속성(또는 속성)에 대해 인덱싱 방법을 설명할 수 있습니다. 기본(주석 없음)은 인덱싱 프로세스에서 속성을 무시함을 나타냅니다.

@field 는 속성을 인덱싱으로 선언하고 다음 특성 중 하나 이상을 설정하여 인덱싱 프로세스의 여러 측면을 구성할 수 있습니다.

@Field 또는 @DocumentId와 동일한 범위에서 지정할 수 있는 @NumericField라는 @Field에 병행 주석이 있습니다. Integer, Long, Float 및¢ 속성에 대해 지정할 수 있습니다. 인덱스 시 트리 구조를 사용하여 값이 인덱싱됩니다. 속성이 숫자 필드로 인덱싱되면 표준 @Field 속성에서 동일한 쿼리를 수행하는 것보다 효율적인 범위 쿼리 및 정렬을 가능하게 합니다. @NumericField 주석은 다음 매개변수를 허용합니다.

@NumericField는 main, Long, Integer 및 Float만 지원합니다. 다른 숫자 유형에 대해 Lucene의 유사한 기능을 활용할 수 없으므로 나머지 유형은 기본값 또는 사용자 지정 TwoWayFieldBridge를 통해 문자열 인코딩을 사용해야 합니다.

유형 변환 중에 예상을 처리할 수 있다고 가정하여 사용자 정의 NumericFieldBridge를 사용할 수 있습니다.

public class BigDecimalNumericFieldBridge extends NumericFieldBridge {
   private static final BigDecimal storeFactor = BigDecimal.valueOf(100);

   @Override
   public void set(String name, Object value, Document document, LuceneOptions luceneOptions) {
      if ( value != null ) {
         BigDecimal decimalValue = (BigDecimal) value;
         Long indexedValue = Long.valueOf( decimalValue.multiply( storeFactor ).longValue() );
         luceneOptions.addNumericFieldToDocument( name, indexedValue, document );
      }
   }

    @Override
    public Object get(String name, Document document) {
        String fromLucene = document.get( name );
        BigDecimal storedBigDecimal = new BigDecimal( fromLucene );
        return storedBigDecimal.divide( storeFactor );
    }

}

마지막으로 엔터티의 id (ID) 속성은 지정된 엔터티의 인덱스 고유성을 보장하기 위해 Hibernate Search에서 사용하는 특수 속성입니다. 기본적으로 ID 를 저장해야 하며 토큰화해서는 안 됩니다. 속성을 인덱스 식별자로 표시하려면 @DocumentId 주석을 사용합니다. Jakarta Persistence를 사용 중이고 @Id를 지정한 경우 @DocumentId를 생략할 수 있습니다. 선택한 엔터티 식별자도 문서 식별자로 사용됩니다.

Infinispan 쿼리에서는 엔터티의 id 속성을 사용하여 인덱스가 고유하게 식별되는지 확인합니다. 기본적으로 ID가 저장되며 토큰으로 변환해서는 안 됩니다. 속성을 인덱스 ID로 표시하려면 @DocumentId 주석을 사용합니다.

@Entity
@Indexed
public class Essay {
    ...
    @Id
    @DocumentId
    public Long getId() { return id; }

    @Field(name="Abstract", store=Store.YES)
    public String getSummary() { return summary; }

    @Lob
    @Field
    public String getText() { return text; }

    @Field @NumericField( precisionStep = 6)
    public float getGrade() { return grade; }
}

위의 예제에서는 id , Abstract,text, grade 의 네 개의 필드가 있는 인덱스를 정의합니다. 기본적으로 JavaBean 사양에 따라 필드 이름은 대문자화되지 않습니다. grade 필드에는 기본값보다 약간 큰 정확도 단계가 있는 숫자로 주석이 추가됩니다.

때로는 약간 다른 인덱싱 전략을 통해 인덱스당 속성을 여러 번 매핑해야 합니다. 예를 들어, 쿼리를 필드별로 정렬하려면 필드를 분석하지 않아야 합니다. 이 속성에서 단어로 검색하고 정렬하려면 인덱싱해야 합니다. 한 번 분석되지 않은 경우 분석되지 않습니다. @Fields를 사용하면 이러한 목표를 달성할 수 있습니다.

@Entity
@Indexed(index = "Book" )
public class Book {
    @Fields( {
            @Field,
            @Field(name = "summary_forSort", analyze = Analyze.NO, store = Store.YES)
            } )
    public String getSummary() {
        return summary;
    }
    ...
}

이 예제에서 필드 요약 은 토큰화된 방식으로 요약 으로 한 번, 한 번은 토큰화되지 않은 방식으로 summary_forSort 로 두 번 인덱싱됩니다.

연결된 개체와 포함된 오브젝트는 루트 엔터티 인덱스의 일부로 인덱싱할 수 있습니다. 이는 연결된 개체의 속성을 기반으로 지정된 엔터티를 검색해야 하는 경우에 유용합니다. 목표는 연결된 도시가 애틀랜타인 장소를 반환하는 것입니다( Lucene 쿼리 구문 분석기 언어에서는 address. city:Atlanta로 변환됩니다). Place 필드가 Place 인덱스로 인덱싱됩니다. Place 인덱스 문서에는 address .id, address. street, address. treet 필드도 포함되어 있으며 쿼리할 수 있습니다.

@Entity
@Indexed
public class Place {
    @Id
    @GeneratedValue
    @DocumentId
    private Long id;

    @Field
    private String name;

    @OneToOne( cascade = { CascadeType.PERSIST, CascadeType.REMOVE } )
    @IndexedEmbedded
    private Address address;
    ....
}

@Entity
public class Address {
    @Id
    @GeneratedValue
    private Long id;

    @Field
    private String street;

    @Field
    private String city;

    @ContainedIn
    @OneToMany(mappedBy="address")
    private Set<Place> places;
    ...
}

@IndexedEmbedded 기술을 사용할 때 Lucene 인덱스에서 데이터가 비정상화되므로 Hibernate Search는 Place 오브젝트의 모든 변경 사항과 인덱스를 최신 상태로 유지하기 위해 Address 오브젝트의 변경 사항을 알고 있어야 합니다. Lucene 문서가 주소 변경 시 업데이트되도록 하려면 @ContainedIn 과 양방향 관계의 다른 측면을 표시합니다.

이를 확장하기 위해 다음 예제에서는 @IndexedEmbeded 중첩을 보여줍니다.

@Entity
@Indexed
public class Place {
    @Id
    @GeneratedValue
    @DocumentId
    private Long id;

    @Field
    private String name;

    @OneToOne( cascade = { CascadeType.PERSIST, CascadeType.REMOVE } )
    @IndexedEmbedded
    private Address address;
    ....
}

@Entity
public class Address {
    @Id
    @GeneratedValue
    private Long id;

    @Field
    private String street;

    @Field
    private String city;

    @IndexedEmbedded(depth = 1, prefix = "ownedBy_")
    private Owner ownedBy;

    @ContainedIn
    @OneToMany(mappedBy="address")
    private Set<Place> places;
    ...
}

@Embeddable
public class Owner {
    @Field
    private String name;
   ...
}

@*ToMany,@*ToOne 및 @ Embeded 속성에는 @ IndexedEmbeded가 주석을 달 수 있습니다. 그러면 연결된 클래스의 속성이 기본 엔터티 인덱스에 추가됩니다. 인덱스에는 다음 필드가 포함됩니다.

기본 접두사는 기존 오브젝트 탐색 규칙에 따라 propertyName. 입니다. ownedBy 속성에 표시되는 접두사 특성을 사용하여 재정의할 수 있습니다.

depth 속성은 오브젝트 그래프에 클래스의 재활용 종속성(인스턴스가 아님)이 포함된 경우 필요합니다. 예를 들어 소유자가 Place(위치)를 가리키는 경우. Hibernate Search는 예상 깊이에 도달한 후 인덱싱된 임베디드 속성을 포함하여 중지되거나 개체 그래프 경계에 도달합니다. 자체 참조가 있는 클래스는 재활용 종속성의 예입니다. 이 예제에서는depth 가 1로 설정되어 있으므로 소유자의 @IndexedEmbedded 속성이 무시됩니다.

개체 연결에 @IndexedEmbedded 를 사용하면 다음과 같은 쿼리( Lucene의 쿼리 구문 사용)를 표현할 수 있습니다.

이 동작은 데이터 복제 비용에 따라 보다 효율적인 방식으로 관계형 조인 작업을 모방합니다. 기본적으로 Lucene 인덱스에는 연관 개념이 없으며 조인 작업이 존재하지 않습니다. 전체 텍스트 인덱스 속도 및 기능 풍부성을 활용하면서 관계형 모델을 정규화하는 데 도움이 될 수 있습니다.

@IndexedEmbeded 가 엔터티를 가리키는 경우 연결은 방향이어야 하며 다른 쪽에는 주석 @ContainedIn (이전 예와 같이)이 추가되어야 합니다. 그렇지 않은 경우 관련 엔터티를 업데이트할 때 Hibernate Search에서 루트 인덱스를 업데이트할 수 없습니다(이 예제에서는 연결된 Address 인스턴스를 업데이트할 때 Place 인덱스 문서를 업데이트해야 함).

@IndexedEmbeded의 주석이 추가된 개체 유형은 Hibernate 및 Hibernate Search의 대상 개체 유형이 아닌 경우도 있습니다. 이는 특히 인터페이스를 구현 대신 사용하는 경우에 해당합니다. 이러한 이유로 targetElement 매개변수를 사용하여 Hibernate Search에서 대상으로 하는 개체 유형을 재정의할 수 있습니다.

@Entity
@Indexed
public class Address {
    @Id
    @GeneratedValue
    @DocumentId
    private Long id;

    @Field
    private String street;

    @IndexedEmbedded(depth = 1, prefix = "ownedBy_", )
    @Target(Owner.class)
    private Person ownedBy;
    ...
}

@Embeddable
public class Owner implements Person { ... }

@IndexedEmbedded 주석은 깊이에 대한 대안으로 사용하거나 결합할 수 있는 includePaths 속성을 제공합니다.

임베드 유형의 모든 인덱싱된 필드만 사용하면 동일한 깊이에 반복적으로 추가됩니다. 이렇게 하면 다른 모든 필드도 추가하지 않고 특정 경로만 선택하기 어려울 수 있습니다. 이 방법은 필요하지 않을 수 있습니다.

불필요하게 로드 및 인덱싱 엔터티를 방지하려면 필요한 경로를 정확하게 지정할 수 있습니다. 일반적인 애플리케이션에는 다른 경로에 대해 서로 다른 깊이가 필요할 수 있습니다. 즉, 아래 예제와 같이 경로를 명시적으로 지정해야 할 수 있습니다.

@Entity
@Indexed
public class Person {

   @Id
   public int getId() {
      return id;
   }

   @Field
   public String getName() {
      return name;
   }

   @Field
   public String getSurname() {
      return surname;
   }

   @OneToMany
   @IndexedEmbedded(includePaths = { "name" })
   public Set<Person> getParents() {
      return parents;
   }

   @ContainedIn
   @ManyToOne
   public Human getChild() {
      return child;
   }

    ...//other fields omitted

위 예제와 마찬가지로 매핑을 사용하면 Person에서 이름 및/또는 성 이름 및/또는 상위 이름을 기준으로 검색할 수 있습니다. 상위의 성 을 인덱싱하지 않으므로 부모의 성에서 검색할 수는 없지만 색인화 속도를 높이고 공간을 절약하고 전반적인 성능을 개선합니다.

@IndexedEmbeddedincludePaths에는 일반적으로 인덱싱하는 항목 외에도 지정된 경로가 포함됩니다. includePaths를 사용하고 깊이 정의되지 않은 상태로 유지되는 동작은depth=0 설정과 동일합니다. 포함된 경로만 인덱싱됩니다.

@Entity
@Indexed
public class Human {

   @Id
   public int getId() {
      return id;
   }

   @Field
   public String getName() {
      return name;
   }

   @Field
   public String getSurname() {
      return surname;
   }

   @OneToMany
   @IndexedEmbedded(depth = 2, includePaths = { "parents.parents.name" })
   public Set<Human> getParents() {
      return parents;
   }

   @ContainedIn
   @ManyToOne
   public Human getChild() {
      return child;
   }

    ...//other fields omitted

위의 예에서 모든 사람은 이름 및 성 속성을 인덱싱합니다. 심도 특성으로 인해 부모의 이름과 성도도 두 번째 행까지 인덱싱됩니다. 이름 또는 성, 직접 사람, 부모 또는 부모로 검색할 수 있습니다. 두 번째 수준을 넘어, 우리는 색인을 하나 더 추가하지만 성이 아닌 이름만 추가할 것입니다.

이렇게 하면 인덱스에 다음 필드가 생성됩니다.

필요한 쿼리를 먼저 정의하여 애플리케이션을 설계하는 경우, 필요한 필드와 사용 사례를 구현하기 위해 불필요한 필드를 정확하게 알 수 있으므로 인덱싱된 경로를 명시적으로 제어할 수 있습니다.

색인화된 클래스 또는 속성에 대한 정적 boost 값을 정의하려면 @Boost 주석을 사용할 수 있습니다. @Field 내에서 이 주석을 사용하거나 메서드 또는 클래스 수준에서 직접 지정할 수 있습니다.

@Entity
@Indexed

public class Essay {
    ...

    @Id
    @DocumentId
    public Long getId() { return id; }

    @Field(name="Abstract", store=Store.YES, boost=@Boost(2f))
    @Boost(1.5f)
    public String getSummary() { return summary; }

    @Lob
    @Field(boost=@Boost(1.2f))
    public String getText() { return text; }

    @Field
    public String getISBN() { return isbn; }
}

위의 예에서 검색 목록 맨 위에 도달하는 Essay의 가능성은 1.7을 곱합니다. 요약 필드는 isbn 필드보다 @Field.boost 및 @Boost가 누적되므로 3.0(2 * 1.5)입니다. 텍스트 필드는 isbn 필드보다 1.2배 더 중요합니다. 이 설명은 가장 엄격한 용어로 잘못되어 있지만 모든 실제 목적에 대해 단순하고 현실에 근접합니다.

Static Index Time Boosting 에 사용된 @Boost 주석은 런타임 시 인덱싱된 엔터티의 상태와는 별개입니다. 그러나 boost 요인이 엔터티의 실제 상태에 따라 달라질 수 있는 사용 사례가 있습니다. 이 경우 @DynamicBoost 주석을 사용자 정의 BoostStrategy와 함께 사용할 수 있습니다.

public enum PersonType {
    NORMAL,
    VIP
}

@Entity
@Indexed
@DynamicBoost(impl = VIPBoostStrategy.class)
public class Person {
    private PersonType type;

    // ....
}

public class VIPBoostStrategy implements BoostStrategy {
    public float defineBoost(Object value) {
        Person person = ( Person ) value;
        if ( person.getType().equals( PersonType.VIP ) ) {
            return 2.0f;
        }
        else {
            return 1.0f;
        }
    }
}

위 예제에서 동적 확장은 인덱스링 시 사용할 BoostStrategy 인터페이스의 구현으로 VIPBoostStrategy를 지정하는 클래스 수준에서 정의됩니다. @DynamicBoost 를 클래스 또는 필드 수준에서 배치할 수 있습니다. 주석 배치에 따라 전체 엔터티가 defineBoost 메서드 또는 주석이 지정된 필드/property 값에만 전달됩니다. 전달된 오브젝트를 올바른 유형으로 적용할 수 있습니다. 예에서 VIP 사람의 모든 인덱싱된 값은 일반 사용자의 값보다 두 배가 중요합니다.

물론 엔터티에서 @Boost 및 @DynamicBoost 주석을 혼합하고 일치시킬 수 있습니다. 정의된 모든 주요 요인은 누적됩니다.

토큰화된 필드를 색인화하는 데 사용되는 기본 analyzer 클래스는 hibernate.search.analyzer 속성을 통해 구성할 수 있습니다. 이 속성의 기본값은 org.apache.lucene.ana bash.standard.StandardAnalyzer 입니다.

엔터티, 속성, 심지어 @Field별로 analyzer 클래스를 정의할 수도 있습니다(여러 필드가 단일 속성에서 인덱싱될 때 유용함).

@Entity
@Indexed
@Analyzer(impl = EntityAnalyzer.class)
public class MyEntity {
    @Id
    @GeneratedValue
    @DocumentId
    private Integer id;

    @Field
    private String name;

    @Field
    @Analyzer(impl = PropertyAnalyzer.class)
    private String summary;

    @Field(analyzer = @Analyzer(impl = FieldAnalyzer.class)
    private String body;
    ...
}

이 예에서 EntityAnalyzer는 각각 PropertiesAnalyzer 및 FieldAnalyzer로 인덱싱된 요약 및 본문 을 제외하고 토큰화된 속성(이름)을 색인화하는 데 사용됩니다.

분석자는 처리하기에 매우 복잡해질 수 있습니다. 이러한 이유로 Hibernate Search를 통해 분석기 정의의 개념을 소개합니다. 분석기 정의는 많은 @Analyzer 선언에서 재사용할 수 있으며 다음으로 구성됩니다.

이러한 작업 분리, 즉 문자 필터 목록과 필터 목록이 뒤에 오는 토큰화자는 각 개별 구성 요소를 쉽게 재사용할 수 있으며, 매우 유연한 방식으로 사용자 지정 분석기를 구축할 수 있습니다(예: Lego). 일반적으로 characters 필터는 문자 입력에서 일부 사전 처리를 수행한 다음, Tokenizer는 문자 입력을 토큰으로 전환한 다음 TokenFilters에서 추가로 처리하는 토큰화 프로세스를 시작합니다. Hibernate Search는 이 인프라를 지원하는데 사용됩니다. 이 프레임워크는 검색 도구 프레임워크를 활용하여 지원합니다.

아래에 명시된 구체적인 예를 검토해 보겠습니다. 먼저 이 필터는 해당 팩토리에 의해 정의됩니다. 이 예제에서는 매핑 문자 필터가 사용되며 매핑 파일에 지정된 규칙에 따라 입력에서 문자를 바꿉니다. 그런 다음 토큰라이저가 정의됩니다. 이 예에서는 표준 토큰 생성기를 사용합니다. 마지막으로, 해당 팩토리에 의해 필터 목록이 정의됩니다. 이 예제에서 StopFilter 필터는 전용 words 속성 파일을 읽습니다. 또한 필터는 대소문자를 무시해야 합니다.

@AnalyzerDef(name="customanalyzer",
  charFilters = {
    @CharFilterDef(factory = MappingCharFilterFactory.class, params = {
      @Parameter(name = "mapping",
        value = "org/hibernate/search/test/analyzer/solr/mapping-chars.properties")
    })
  },
  tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class),
  filters = {
    @TokenFilterDef(factory = ISOLatin1AccentFilterFactory.class),
    @TokenFilterDef(factory = LowerCaseFilterFactory.class),
    @TokenFilterDef(factory = StopFilterFactory.class, params = {
      @Parameter(name="words",
        value= "org/hibernate/search/test/analyzer/solr/stoplist.properties" ),
      @Parameter(name="ignoreCase", value="true")
    })
})
public class Team {
    ...
}

일부 토큰 생성자, 토큰 필터 또는 문자 필터는 구성 또는 메타데이터 파일과 같은 리소스를 로드합니다. stop 필터와 동의어 필터의 사례입니다. resource charset이 VM 기본값을 사용하지 않는 경우 resource_charset 매개변수를 추가하여 명시적으로 지정할 수 있습니다.

@AnalyzerDef(name="customanalyzer",
  charFilters = {
    @CharFilterDef(factory = MappingCharFilterFactory.class, params = {
      @Parameter(name = "mapping",
        value = "org/hibernate/search/test/analyzer/solr/mapping-chars.properties")
    })
  },
  tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class),
  filters = {
    @TokenFilterDef(factory = ISOLatin1AccentFilterFactory.class),
    @TokenFilterDef(factory = LowerCaseFilterFactory.class),
    @TokenFilterDef(factory = StopFilterFactory.class, params = {
      @Parameter(name="words",
        value= "org/hibernate/search/test/analyzer/solr/stoplist.properties" ),
      @Parameter(name="resource_charset", value = "UTF-16BE"),
      @Parameter(name="ignoreCase", value="true")
  })
})
public class Team {
    ...
}

정의되고 나면 다음 예제와 같이 @Analyzer 선언에서 분석기 정의를 재사용할 수 있습니다.

@Entity
@Indexed
@AnalyzerDef(name="customanalyzer", ... )
public class Team {
    @Id
    @DocumentId
    @GeneratedValue
    private Integer id;

    @Field
    private String name;

    @Field
    private String location;

    @Field
    @Analyzer(definition = "customanalyzer")
    private String description;
}

@AnalyzerDef에서 선언한 분석기 인스턴스는 쿼리를 작성할 때 매우 유용한 SearchFactory의 이름으로도 사용할 수 있습니다.

Analyzer analyzer = fullTextSession.getSearchFactory().getAnalyzer("customanalyzer");

쿼리의 필드는 공통 "언어"를 표시하도록 필드를 인덱싱하는 데 사용되는 것과 동일한 분석기를 사용하여 분석해야 합니다. 동일한 토큰은 쿼리와 인덱싱 프로세스 간에 재사용됩니다. 이 규칙에는 몇 가지 예외가 있지만 대부분의 경우 적용됩니다. 자신이 무엇을 하는지 모르는 경우라도 주의하십시오.

솔러 및 Lucene에는 많은 유용한 기본 문자 필터, 토큰화기 및 필터가 포함되어 있습니다. 에서 작은 필터 팩토리, 토큰 화 기 팩터 및 필터 팩토리의 전체 목록을 확인할 수 있습니다. 이 중 몇 가지를 확인하겠습니다.

IDE에서 org.apache.lucene.anaviv.TokenizerFactory 및 org. apache.lucene.anaoperation.TokenFilterFactory 의 모든 구현을 확인하여 사용 가능한 구현을 확인하는 것이 좋습니다.

지금까지 분석기를 지정하는 모든 방법이 정적이었습니다. 그러나 색인화할 엔터티의 현재 상태에 따라 분석기를 선택하는 것이 유용한 사용 사례가 있습니다(예: 다국어 애플리케이션). 예를 들어, 블로그Entry 클래스의 경우 분석기가 항목의 language 속성에 따라 달라질 수 있습니다. 이 속성에 따라 실제 텍스트를 색인화하도록 올바른 언어별 정형기를 선택해야 합니다.

이 동적 분석기 선택을 활성화하기 위해 Hibernate Search에는 AnalyzerDiscriminator 주석이 도입되었습니다. 다음 예제에서는 이 주석의 사용을 보여줍니다.

@Entity
@Indexed
@AnalyzerDefs({
  @AnalyzerDef(name = "en",
    tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class),
    filters = {
      @TokenFilterDef(factory = LowerCaseFilterFactory.class),
      @TokenFilterDef(factory = EnglishPorterFilterFactory.class
      )
    }),
  @AnalyzerDef(name = "de",
    tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class),
    filters = {
      @TokenFilterDef(factory = LowerCaseFilterFactory.class),
      @TokenFilterDef(factory = GermanStemFilterFactory.class)
    })
})
public class BlogEntry {

    @Id
    @GeneratedValue
    @DocumentId
    private Integer id;

    @Field
    @AnalyzerDiscriminator(impl = LanguageDiscriminator.class)
    private String language;

    @Field
    private String text;

    private Set<BlogEntry> references;

    // standard getter/setter
    ...
}

public class LanguageDiscriminator implements Discriminator {

    public String getAnalyzerDefinitionName(Object value, Object entity, String field) {
        if ( value == null || !( entity instanceof BlogEntry ) ) {
            return null;
        }
        return (String) value;

    }
}

@AnalyzerDiscriminator 를 사용하기 위한 전제 조건은 동적으로 사용할 모든 분석기가 @AnalyzerDef 정의를 통해 사전 정의되어 있다는 것입니다. 이 경우 클래스 또는 분석기를 동적으로 선택할 엔터티의 특정 속성에 @AnalyzerDiscriminator 주석을 배치할 수 있습니다. AnalyzerDiscriminator 의 단순 매개 변수를 통해 디스크리미네이터 인터페이스의 구체적인 구현을 지정합니다. 이 인터페이스에 대한 구현을 제공해야 합니다. 구현해야 하는 유일한 메서드는 Lucene 문서에 추가된 각 필드에 대해 호출되는 getAnalyzerDefinitionName() 입니다. 인덱싱되는 엔터티도 interface 메서드로 전달됩니다. value 매개 변수는 AnalyzerDiscriminator 가 클래스 레벨이 아닌 속성 수준에 배치된 경우에만 설정됩니다. 이 경우 값은 이 속성의 현재 값을 나타냅니다.

기본 분석기를 재정의하지 않아야 하는 경우 디스크리미레이터 인터페이스 구현에서 기존 분석기 정의의 이름을 반환해야 합니다. 위의 예제에서는 language 매개변수가 @AnalyzerDefs 의 지정된 이름과 일치하는 'de' 또는 'en'이라고 가정합니다.

분석기 검색은 도메인 모델에서 여러 분석기를 사용했을 때 사용할 수 있습니다. 이 경우 동일한 분석기를 사용하여 쿼리를 빌드합니다. 또는 올바른 분석기를 자동으로 선택하는 Hibernate Search 쿼리 DSL을 사용합니다. 보기

Lucene 프로그래밍 방식 API 또는 Lucene 쿼리 구문 분석기를 사용하든 주어진 엔터티에 대한 범위 분석기를 검색할 수 있습니다. 범위가 지정된 분석기는 인덱싱된 필드에 따라 올바른 분석기를 적용하는 분석기입니다. 개별 필드에서 작업하는 지정된 엔터티에 여러 분석기를 정의할 수 있습니다. 범위가 지정된 분석기는 이러한 모든 분석기를 컨텍스트 인식 분석기에 통합합니다. 이론은 조금 복잡해 보이지만 쿼리에서 올바른 분석기를 사용하는 것은 매우 쉽습니다.

org.apache.lucene.queryParser.QueryParser parser = new QueryParser(
    "title",
    fullTextSession.getSearchFactory().getAnalyzer( Song.class )
);

org.apache.lucene.search.Query luceneQuery =
    parser.parse( "title:sky Or title_stemmed:diamond" );

org.hibernate.Query fullTextQuery =
    fullTextSession.createFullTextQuery( luceneQuery, Song.class );

List result = fullTextQuery.list(); //return a list of managed objects

위의 예에서 회색 제목은 두 가지 필드로 인덱싱됩니다. 표준 Analyzer는 필드 제목 에서 사용되며, 스트라이밍 분석기가 Title_stemmed 필드에 사용됩니다. 쿼리는 검색 팩토리에서 제공하는 Analyzer를 사용하여 대상 필드에 따라 적절한 분석기를 사용합니다.

Hibernate Search는 Java 속성 유형과 전체 텍스트 표현 사이에 기본 제공 브리지 세트와 함께 제공됩니다.

@Entity
@Indexed
public class Meeting {
    @Field(analyze=Analyze.NO)

    private Date date;
    ...

경우에 따라 Hibernate Search의 기본 제공 브리지가 일부 속성 유형을 다루지 않거나 브리지에서 사용하는 문자열 표시가 요구 사항을 충족하지 않는 경우가 있습니다. 다음 단락에서는 이 문제에 대한 여러 솔루션을 설명합니다.

/**
 * Padding Integer bridge.
 * All numbers will be padded with 0 to match 5 digits
 *
 * @author Emmanuel Bernard
 */
public class PaddedIntegerBridge implements StringBridge {

    private int PADDING = 5;

    public String objectToString(Object object) {
        String rawInteger = ( (Integer) object ).toString();
        if (rawInteger.length() > PADDING)
            throw new IllegalArgumentException( "Try to pad on a number too big" );
        StringBuilder paddedInteger = new StringBuilder( );
        for ( int padIndex = rawInteger.length() ; padIndex < PADDING ; padIndex++ ) {
            paddedInteger.append('0');
        }
        return paddedInteger.append( rawInteger ).toString();
    }
}

@FieldBridge(impl = PaddedIntegerBridge.class)
private Integer length;

public class PaddedIntegerBridge implements StringBridge, ParameterizedBridge {

    public static String PADDING_PROPERTY = "padding";
    private int padding = 5; //default

    public void setParameterValues(Map<String,String> parameters) {
        String padding = parameters.get( PADDING_PROPERTY );
        if (padding != null) this.padding = Integer.parseInt( padding );
    }

    public String objectToString(Object object) {
        String rawInteger = ( (Integer) object ).toString();
        if (rawInteger.length() > padding)
            throw new IllegalArgumentException( "Try to pad on a number too big" );
        StringBuilder paddedInteger = new StringBuilder( );
        for ( int padIndex = rawInteger.length() ; padIndex < padding ; padIndex++ ) {
            paddedInteger.append('0');
        }
        return paddedInteger.append( rawInteger ).toString();
    }
}


//property
@FieldBridge(impl = PaddedIntegerBridge.class,
             params = @Parameter(name="padding", value="10")
            )
private Integer length;

public class PaddedIntegerBridge implements TwoWayStringBridge, ParameterizedBridge {

    public static String PADDING_PROPERTY = "padding";
    private int padding = 5; //default

    public void setParameterValues(Map parameters) {
        Object padding = parameters.get( PADDING_PROPERTY );
        if (padding != null) this.padding = (Integer) padding;
    }

    public String objectToString(Object object) {
        String rawInteger = ( (Integer) object ).toString();
        if (rawInteger.length() > padding)
            throw new IllegalArgumentException( "Try to pad on a number too big" );
        StringBuilder paddedInteger = new StringBuilder( );
        for ( int padIndex = rawInteger.length() ; padIndex < padding ; padIndex++ ) {
            paddedInteger.append('0');
        }
        return paddedInteger.append( rawInteger ).toString();
    }

    public Object stringToObject(String stringValue) {
        return new Integer(stringValue);
    }
}

//id property
@DocumentId
@FieldBridge(impl = PaddedIntegerBridge.class,
             params = @Parameter(name="padding", value="10")
private Integer id;

/**
 * Store the date in 3 different fields - year, month, day - to ease Range Query per
 * year, month or day (eg get all the elements of December for the last 5 years).
 * @author Emmanuel Bernard
 */
public class DateSplitBridge implements FieldBridge {
    private final static TimeZone GMT = TimeZone.getTimeZone("GMT");

    public void set(String name, Object value, Document document, LuceneOptions luceneOptions) {
        Date date = (Date) value;
        Calendar cal = GregorianCalendar.getInstance(GMT);
        cal.setTime(date);
        int year = cal.get(Calendar.YEAR);
        int month = cal.get(Calendar.MONTH) + 1;
        int day = cal.get(Calendar.DAY_OF_MONTH);

        // set year
        luceneOptions.addFieldToDocument(
            name + ".year",
            String.valueOf( year ),
            document );

        // set month and pad it if needed
        luceneOptions.addFieldToDocument(
            name + ".month",
            month < 10 ? "0" : "" + String.valueOf( month ),
            document );

        // set day and pad it if needed
        luceneOptions.addFieldToDocument(
            name + ".day",
            day < 10 ? "0" : "" + String.valueOf( day ),
            document );
    }
}

//property
@FieldBridge(impl = DateSplitBridge.class)
private Date date;

@Entity
@Indexed
(name="branchnetwork",
             store=Store.YES,
             impl = CatFieldsClassBridge.class,
             params = @Parameter( name="sepChar", value=" " ) )
public class Department {
    private int id;
    private String network;
    private String branchHead;
    private String branch;
    private Integer maxEmployees
    ...
}

public class CatFieldsClassBridge implements FieldBridge, ParameterizedBridge {
    private String sepChar;

    public void setParameterValues(Map parameters) {
        this.sepChar = (String) parameters.get( "sepChar" );
    }

    public void set( String name, Object value, Document document, LuceneOptions luceneOptions) {
        // In this particular class the name of the new field was passed
        // from the name field of the ClassBridge Annotation. This is not
        // a requirement. It just works that way in this instance. The
        // actual name could be supplied by hard coding it below.
        Department dep = (Department) value;
        String fieldValue1 = dep.getBranch();
        if ( fieldValue1 == null ) {
            fieldValue1 = "";
        }
        String fieldValue2 = dep.getNetwork();
        if ( fieldValue2 == null ) {
            fieldValue2 = "";
        }
        String fieldValue = fieldValue1 + sepChar + fieldValue2;
        Field field = new Field( name, fieldValue, luceneOptions.getStore(),
            luceneOptions.getIndex(), luceneOptions.getTermVector() );
        field.setBoost( luceneOptions.getBoost() );
        document.add( field );
   }
}

Lucene API에서는 쿼리 구문 분석기(단순 쿼리) 또는 Lucene 프로그래밍 방식 API(복합 쿼리)를 사용합니다. Lucene 쿼리 빌드는 Hibernate Search 문서의 범위를 벗어납니다. 자세한 내용은 온라인 Lucene 문서 또는 Lucene in Action 또는 Hibernate Search in Action 을 참조하십시오.

Lucene 프로그래밍 방식 API를 사용하면 전체 텍스트 쿼리가 가능합니다. 그러나 Lucene 프로그래밍 방식 API를 사용하는 경우 매개 변수를 해당 문자열로 변환해야 하며 올바른 분석기도 올바른 필드에 적용해야 합니다. 예를 들어 ngram 분석기에서는 지정된 단어의 토큰으로 여러 ngrams를 사용하므로 다음과 같이 검색해야 합니다. 이 작업에 QueryBuilder를 사용하는 것이 좋습니다.

Hibernate Search 쿼리 API는 다음과 같은 주요 특성을 갖추고 있습니다.

API를 사용하려면 먼저 지정된 indexedentitytype 에 연결된 쿼리 빌더를 생성합니다. 이 QueryBuilder는 사용할 분석기 및 적용할 필드 브리지를 알고 있습니다. 여러 QueryBuilders(쿼터 루트와 관련된 각 엔터티 유형)를 생성할 수 있습니다. QueryBuilder는 SearchFactory에서 파생됩니다.

QueryBuilder mythQB = searchFactory.buildQueryBuilder().forEntity( Myth.class ).get();

지정된 필드 또는 필드에 사용된 분석기를 재정의할 수도 있습니다.

QueryBuilder mythQB = searchFactory.buildQueryBuilder()
    .forEntity( Myth.class )
        .overridesForField("history","stem_analyzer_definition")
    .get();

이제 쿼리 빌더를 사용하여 Lucene 쿼리를 빌드합니다. Lucene 프로그래밍 방식 API를 사용하여 조합한 Lucene의 쿼리 구문 분석기 또는 쿼리 개체를 Hibernate Search DSL과 함께 사용하여 생성한 사용자 정의 쿼리가 사용됩니다.

다음 예는 특정 단어를 검색하는 방법을 보여줍니다.

Query luceneQuery = mythQB.keyword().onField("history").matching("storm").createQuery();

유형 문자열이 아닌 속성을 검색합니다.

@Indexed
public class Myth {
  @Field(analyze = Analyze.NO)
  @DateBridge(resolution = Resolution.YEAR)
  public Date getCreationDate() { return creationDate; }
  public Date setCreationDate(Date creationDate) { this.creationDate = creationDate; }
  private Date creationDate;

  ...
}

Date birthdate = ...;
Query luceneQuery = mythQb.keyword().onField("creationDate").matching(birthdate).createQuery();

FieldBridge에 objectToString 메서드(및 모든 기본 제공 FieldBridge 구현)가 있는 경우 이 변환은 모든 오브젝트에 대해 작동합니다.

다음 예제에서는 ngram 분석기를 사용하는 필드를 검색합니다. ngram 분석기 색인의 ngram 단어의 연속으로, 사용자 오타를 방지하는 데 도움이 됩니다. 예를 들어 hibernate라는 단어의 3ms는 hib, ibe, ber, ern, rna, nat, ate입니다.

@AnalyzerDef(name = "ngram",
  tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class ),
  filters = {
    @TokenFilterDef(factory = StandardFilterFactory.class),
    @TokenFilterDef(factory = LowerCaseFilterFactory.class),
    @TokenFilterDef(factory = StopFilterFactory.class),
    @TokenFilterDef(factory = NGramFilterFactory.class,
      params = {
        @Parameter(name = "minGramSize", value = "3"),
        @Parameter(name = "maxGramSize", value = "3") } )
  }
)

public class Myth {
  @Field(analyzer=@Analyzer(definition="ngram")
  public String getName() { return name; }
  public String setName(String name) { this.name = name; }
  private String name;

  ...
}

Date birthdate = ...;
Query luceneQuery = mythQb.keyword().onField("name").matching("Sisiphus")
   .createQuery();

일치하는 단어 "Sphus"는 소문자가 지정된 후 sis, isi, sip, iph, phu, hus와 같은 3그램으로 나뉩니다. 각각의 ngram은 쿼리의 일부가 됩니다. 그런 다음 사용자는 Sysiphus myth(y 사용)를 찾을 수 있습니다. 사용자에게 투명하게 수행되는 모든 작업.

동일한 필드에서 가능한 여러 단어를 검색하려면 일치하는 절에 모두 추가합니다.

//search document with storm or lightning in their history
Query luceneQuery =
    mythQB.keyword().onField("history").matching("storm lightning").createQuery();

여러 필드에서 동일한 단어를 검색하려면 onFields 메서드를 사용합니다.

Query luceneQuery = mythQB
    .keyword()
    .onFields("history","description","name")
    .matching("storm")
    .createQuery();

경우에 따라 동일한 용어를 검색하는 경우에도 하나의 필드를 다른 필드와 다르게 처리해야 하는 경우가 있으며, 이에 대해 andField() 메서드를 사용합니다.

Query luceneQuery = mythQB.keyword()
    .onField("history")
    .andField("name")
      .boostedTo(5)
    .andField("description")
    .matching("storm")
    .createQuery();

이전 예에서 필드 이름만 5로 늘어납니다.

퍼지 쿼리(Levenshtein 거리 알고리즘 기반)를 실행하려면 키워드 쿼리로 시작하고 퍼지 플래그를 추가합니다.

Query luceneQuery = mythQB
    .keyword()
      .fuzzy()
        .withThreshold( .8f )
        .withPrefixLength( 1 )
    .onField("history")
    .matching("starm")
    .createQuery();

임계값 은 두 개의 용어가 일치하는 것으로 간주되는 제한입니다. 0에서 1 사이의 10진수이며 기본값은 0.5입니다. prefixLength 는 "허개"에서 무시하는 접두사 길이입니다. 기본값은 0이지만 다수의 고유한 용어를 포함하는 인덱스에는 0이 아닌 값이 권장됩니다.

와일드카드 쿼리는 단어의 일부만 알려진 경우에 유용합니다. ? 은 단일 문자를 나타내고 *는 여러 문자를 나타냅니다. 성능상의 이유로 쿼리를 ? 또는 * 로 시작하지 않는 것이 좋습니다.

Query luceneQuery = mythQB
    .keyword()
      .wildcard()
    .onField("history")
    .matching("sto*")
    .createQuery();

지금까지 우리는 단어나 단어의 집합을 찾고 있었기 때문에 사용자는 정확하거나 대략적인 문장을 검색할 수도 있습니다. phrase()를 사용하여 이를 수행합니다.

Query luceneQuery = mythQB
    .phrase()
    .onField("history")
    .sentence("Thou shalt not kill")
    .createQuery();

슬롭 인수를 추가하여 대략적인 문장을 검색할 수 있습니다. 슬랩 인수는 문장에서 허용된 다른 단어 수를 나타냅니다. 이 값은 연산자 내부 또는 가까운 연산자처럼 작동합니다.

Query luceneQuery = mythQB
    .phrase()
      .withSlop(3)
    .onField("history")
    .sentence("Thou kill")
    .createQuery();

범위 쿼리는 지정된 경계 사이의 값(포함 여부) 또는 특정 경계 이상의 값에 대한 값을 검색합니다.

//look for 0 <= starred < 3
Query luceneQuery = mythQB
    .range()
    .onField("starred")
    .from(0).to(3).excludeLimit()
    .createQuery();

//look for myths strictly BC
Date beforeChrist = ...;
Query luceneQuery = mythQB
    .range()
    .onField("creationDate")
    .below(beforeChrist).excludeLimit()
    .createQuery();

쿼리를 결합하여 더 복잡한 쿼리를 만들 수 있습니다. 다음 집계 운영자를 사용할 수 있습니다.

하위 쿼리는 부울 쿼리 자체를 포함한 모든 Lucene 쿼리일 수 있습니다.

//look for popular myths that are preferably urban
Query luceneQuery = mythQB
    .bool()
      .should( mythQB.keyword().onField("description").matching("urban").createQuery() )
      .must( mythQB.range().onField("starred").above(4).createQuery() )
    .createQuery();

//look for popular urban myths
Query luceneQuery = mythQB
    .bool()
      .must( mythQB.keyword().onField("description").matching("urban").createQuery() )
      .must( mythQB.range().onField("starred").above(4).createQuery() )
    .createQuery();

//look for popular modern myths that are not urban
Date twentiethCentury = ...;
Query luceneQuery = mythQB
    .bool()
      .must( mythQB.keyword().onField("description").matching("urban").createQuery() )
        .not()
      .must( mythQB.range().onField("starred").above(4).createQuery() )
      .must( mythQB
        .range()
        .onField("creationDate")
        .above(twentiethCentury)
        .createQuery() )
    .createQuery();

Hibernate Search 쿼리 DSL은 사용하기 쉽고 읽기 쉬운 쿼리 API입니다. Lucene 쿼리를 수락하고 생성할 때 DSL에서 아직 지원하지 않는 쿼리 유형을 통합할 수 있습니다.

다음은 쿼리 유형 및 필드에 대한 쿼리 옵션 요약입니다.

Query luceneQuery = mythQB
    .bool()
      .should( mythQB.keyword().onField("description").matching("urban").createQuery() )
      .should( mythQB
        .keyword()
        .onField("name")
          .boostedTo(3)
          .ignoreAnalyzer()
        .matching("urban").createQuery() )
      .must( mythQB
        .range()
          .boostedTo(5).withConstantScore()
        .onField("starred").above(4).createQuery() )
    .createQuery();

적절한 수의 결과(예: 페이지 번호 사용)가 예상하고 모두 작업할 것으로 예상되는 경우 list() 또는 uniqueResult() 를 사용하는 것이 좋습니다. list() 는 엔터티 batch-size 가 올바르게 설정된 경우 가장 효과적입니다. Hibernate Search는 list(), uniqueResult() 및 반복() 을 사용할 때 Lucene Hits 요소(p Page 내에)를 처리해야 합니다.

Lucene 문서 로드를 최소화하려면 scroll() 가 더 적합합니다. 완료 시 Lucene 리소스를 유지하므로 ScrollableResults 오브젝트를 종료해야 합니다. 스크롤을 사용할 것으로 예상되지만 배치로 오브젝트를 로드하려는 경우 query.setFetchSize() 를 사용할 수 있습니다. 개체에 액세스하고 이미 로드되지 않은 경우 Hibernate Search는 다음 fetchSize 개체를 한 번에 로드합니다.

일치하는 문서의 총 수를 아는 것이 유용할 수 있습니다.

물론 일치하는 모든 문서를 검색하는 데 비용이 너무 많이 듭니다. Hibernate Search를 사용하면 페이지 번호 매개 변수에 관계없이 일치하는 문서 수를 검색할 수 있습니다. 더욱 흥미로운 점은 단일 오브젝트 로드를 트리거하지 않고도 일치하는 요소 수를 검색할 수 있습니다.

org.hibernate.search.FullTextQuery query =
    s.createFullTextQuery( luceneQuery, Book.class );
//return the number of matching books without loading a single one
assert 3245 == ;

org.hibernate.search.FullTextQuery query =
    s.createFullTextQuery( luceneQuery, Book.class );
query.setMaxResult(10);
List results = query.list();
//return the total number of matching books regardless of pagination
assert 3245 == ;

예측 결과가 오브젝트 배열로 반환됩니다. 오브젝트에 사용된 데이터 구조가 애플리케이션의 요구 사항과 일치하지 않는 경우 ResultTransformer를 적용합니다. ResultTransformer는 쿼리 실행 후 필요한 데이터 구조를 빌드합니다.

org.hibernate.search.FullTextQuery query =
    s.createFullTextQuery( luceneQuery, Book.class );
query.setProjection( "title", "mainAuthor.name" );

query.setResultTransformer( new StaticAliasToBeanResultTransformer( BookView.class, "title", "author" ) );
List<BookView> results = (List<BookView>) query.list();
for(BookView view : results) {
    log.info( "Book: " + view.getTitle() + ", " + view.getAuthor() );
}

ResultTransformer 구현의 예는 Hibernate Core 코드베이스에서 확인할 수 있습니다.

쿼리 결과가 예상과 일치하지 않으면 Luke 툴에서 결과를 이해하는 데 유용합니다. 그러나 Hibernate Search를 사용하면 주어진 쿼리에서 Lucene Explanation 개체에 액세스할 수도 있습니다. 이 클래스는 Lucene 사용자에게 상당히 발전하지만 개체의 점수에 대해 잘 이해할 수 있습니다. 주어진 결과에 대해 설명 개체에 액세스하는 두 가지 방법이 있습니다.

첫 번째 접근 방식은 문서 ID를 매개 변수로 사용하고 Explanation 오브젝트를 반환합니다. 문서 ID는 예측 및 FullTextQuery.DOCUMENT_ID 상수를 사용하여 검색할 수 있습니다.

두 번째 접근 방식에서는 Full TextQuery.EXPLANATION 상수를 사용하여 Explanation 오브젝트를 예상합니다.

FullTextQuery ftQuery = s.createFullTextQuery( luceneQuery, Dvd.class )
        .setProjection(
             FullTextQuery.DOCUMENT_ID,
             ,
             FullTextQuery.THIS );
@SuppressWarnings("unchecked") List<Object[]> results = ftQuery.list();
for (Object[] result : results) {
    Explanation e = (Explanation) result[1];
    display( e.toString() );
}

Explanation 오브젝트는 Lucene 쿼리를 다시 실행하는 것처럼 필요한 경우에만 사용합니다.

Apache Lucene에는 사용자 지정 필터링 프로세스에 따라 쿼리 결과를 필터링할 수 있는 강력한 기능이 있습니다. 이 방법은 특히 필터를 캐시하고 재사용할 수 있으므로 추가 데이터 제한 사항을 적용하는 매우 강력한 방법입니다. 사용 사례는 다음과 같습니다.

Hibernate Search는 투명하게 캐시된 매개변수 지정 필터의 개념을 도입하여 개념을 추가로 푸시합니다. Hibernate Core 필터라는 개념을 잘 알고 있는 사용자의 경우 API는 매우 유사합니다.

fullTextQuery = s.createFullTextQuery( query, Driver.class );
fullTextQuery.enableFullTextFilter("bestDriver");
fullTextQuery.enableFullTextFilter("security").setParameter( "login", "andre" );
fullTextQuery.list(); //returns only best drivers where andre has credentials

이 예제에서는 쿼리 상단에 두 개의 필터를 활성화했습니다. 원하는 만큼 필터를 활성화하거나 비활성화할 수 있습니다.

필터 선언은 @FullTextFilterDef 주석을 통해 수행됩니다. 이 주석은 나중에 필터가 적용되는 쿼리와 관계없이 모든 @Indexed 엔터티에 있을 수 있습니다. 이는 필터 정의가 전역적이며 해당 이름은 고유해야 함을 의미합니다. 이름이 같은 두 개의 다른 @FullTextFilterDef 주석이 정의된 경우 SearchException이 발생합니다. 명명된 각 필터는 실제 필터 구현을 지정해야 합니다.

@FullTextFilterDefs( {
    @FullTextFilterDef(name = "bestDriver", impl = BestDriversFilter.class),
    @FullTextFilterDef(name = "security", impl = SecurityFilterFactory.class)
})
public class Driver { ... }

public class BestDriversFilter extends org.apache.lucene.search.Filter {

    public DocIdSet getDocIdSet(IndexReader reader) throws IOException {
        OpenBitSet bitSet = new OpenBitSet( reader.maxDoc() );
        TermDocs termDocs = reader.termDocs( new Term( "score", "5" ) );
        while ( termDocs.next() ) {
            bitSet.set( termDocs.doc() );
        }
        return bitSet;
    }
}

BestDriversFilter는 점수가 5인 드라이버로 설정된 결과를 줄이는 간단한 Lucene 필터의 예입니다. 이 예제에서 지정된 필터는 org.apache.lucene.search.Filter 를 직접 구현하고 no-arg 생성자를 포함합니다.

필터 생성에 추가 단계가 필요한 경우 또는 사용하려는 필터에 no-arg 생성자가 없는 경우 팩토리 패턴을 사용할 수 있습니다.

@FullTextFilterDef(name = "bestDriver", impl = BestDriversFilterFactory.class)
public class Driver { ... }

public class BestDriversFilterFactory {

@Factory
    public Filter getFilter() {
        //some additional steps to cache the filter results per IndexReader
        Filter bestDriversFilter = new BestDriversFilter();
        return new CachingWrapperFilter(bestDriversFilter);
    }
}

Hibernate Search는 @Factory 주석이 있는 메서드를 찾아 필터 인스턴스를 빌드하는 데 사용합니다. 이 팩토리에는 무중단 생성자가 있어야 합니다.

Infinispan 쿼리에서는 @Factory 주석이 추가된 메서드를 사용하여 필터 인스턴스를 빌드합니다. 이 팩토리에는 인수 생성자가 없어야 합니다.

명명된 필터는 매개 변수를 필터로 전달해야 하는 경우에 유용합니다. 예를 들어 보안 필터는 적용하려는 보안 수준을 알고자 할 수 있습니다.

fullTextQuery = s.createFullTextQuery( query, Driver.class );
fullTextQuery.enableFullTextFilter("security").setParameter( "level", 5 );

각 매개변수 이름에는 대상 명명된 필터 정의의 필터 또는 필터 팩터에 연결된 setter가 있어야 합니다.

public class SecurityFilterFactory {
    private Integer level;

    /**
     * injected parameter
     */
    public void setLevel(Integer level) {
        this.level = level;
    }

    @Key public FilterKey getKey() {
        StandardFilterKey key = new StandardFilterKey();
        key.addParameter( level );
        return key;
    }

    @Factory
    public Filter getFilter() {
        Query query = new TermQuery( new Term("level", level.toString() ) );
        return new CachingWrapperFilter( new QueryWrapperFilter(query) );
    }
}

주석이 추가된 @Key 메서드는 FilterKey 오브젝트를 반환합니다. 반환된 오브젝트에는 특별한 계약이 있습니다. key 오브젝트는 equals() / hashCode()를 구현해야 하므로, 지정된 Filter 유형이 동일하고 매개 변수 집합이 동일한 경우에만 두 키가 동일할 수 있습니다. 즉, 두 개의 필터 키는 생성되는 필터를 교환할 수 있는 경우에만 두 개의 필터 키가 동일하며. 키 오브젝트는 캐시 메커니즘의 키로 사용됩니다.

@key 메서드는 다음과 같은 경우에만 필요합니다.

대부분의 경우 StandardFilterKey 구현을 충분히 사용할 수 있습니다. 이는 equals() / hashcode() 구현을 각 매개 변수와 동일한 값과 해시 코드 메서드에 위임합니다.

정의된 필터가 기본 캐시당이고 캐시는 하드 및 소프트 참조의 조합을 사용하여 필요한 경우 메모리를 폐기할 수 있습니다. 하드 참조 캐시는 가장 최근에 사용된 필터를 추적하고 필요한 경우 가장 적게 사용된 필터를 변환합니다. 하드 참조 캐시의 제한에 도달하면 추가 필터가 softReferences로 캐시됩니다. 하드 참조 캐시의 크기를 조정하려면 hibernate.search.filter.cache_strategy.size (기본값: 128)를 사용합니다. 필터 캐싱의 고급 사용을 위해 자체 FilterCachingStrategy를 구현합니다. 클래스 이름은 hibernate.search.filter.cache_strategy 에서 정의합니다.

이 필터 캐싱 메커니즘은 실제 필터 결과를 캐싱하는 것과 혼동해서는 안 됩니다. Lucene에서는 CachingWrapperFilter를 중심으로 IndexReader를 사용하여 필터를 래핑하는 것이 일반적입니다. 래퍼는 값비싼 recomputation을 방지하기 위해 getDocIdSet(IndexReader reader) 방법에서 반환된 DocIdSet을 캐시합니다. 계산된 DocIdSet은 동일한 IndexReader 인스턴스에만 사용할 수 있다는 사실을 언급하는 것이 중요합니다. 리더는 열려 있는 현재 인덱스의 상태를 효과적으로 나타내기 때문입니다. 열린 IndexReader 내에서는 문서 목록을 변경할 수 없습니다. 그러나 다른/새 IndexReader 인스턴스는 다른 문서 집합(다른 인덱스에서 또는 인덱스가 변경되었기 때문에 간단히) 작업하므로 캐시된 DocIdSet을 다시 계산해야 합니다.

또한 Hibernate Search는 이러한 캐싱 측면에도 도움이 됩니다. 기본적으로 @FullTextFilterDef의 캐시 플래그는 FilterCacheModeType.INSTANCE_AND_DOCIDSETRESULTS 로 설정되어 필터 인스턴스를 자동으로 캐시하고 CachingWrapperFilter의 Hibernate 특정 구현을 중심으로 지정된 필터를 래핑합니다. Lucene의 이 클래스 버전에 비해 softReferences는 하드 참조 수와 함께 사용됩니다(필터 캐시에 대한 토론 참조). 하드 참조 수는 hibernate.search.filter.cache_docidresults.size(기본값: 5)를 사용하여 조정할 수 있습니다. 래핑 작업은 @FullTextFilterDef.cache 매개 변수를 사용하여 제어할 수 있습니다. 이 매개변수에는 세 가지 다른 값이 있습니다.

필터를 다음과 같은 상황에서 캐시해야 합니다.

분할된 환경에서는 사용 가능한 shard의 하위 집합에 대한 쿼리를 실행할 수 있습니다. 이 작업은 다음 두 단계로 수행할 수 있습니다.

public class CustomerShardingStrategy implements IndexShardingStrategy {

     // stored IndexManagers in an array indexed by customerID
     private IndexManager[] indexManagers;

     public void initialize(Properties properties, IndexManager[] indexManagers) {
       this.indexManagers = indexManagers;
     }

     public IndexManager[] getIndexManagersForAllShards() {
       return indexManagers;
     }

     public IndexManager getIndexManagerForAddition(
         Class<?> entity, Serializable id, String idInString, Document document) {
       Integer customerID = Integer.parseInt(document.getFieldable("customerID").stringValue());
       return indexManagers[customerID];
     }

     public IndexManager[] getIndexManagersForDeletion(
         Class<?> entity, Serializable id, String idInString) {
       return getIndexManagersForAllShards();
     }

      /**
      * Optimization; don't search ALL shards and union the results; in this case, we
      * can be certain that all the data for a particular customer Filter is in a single
      * shard; simply return that shard by customerID.
      */
     public IndexManager[] getIndexManagersForQuery(
         FullTextFilterImplementor[] filters) {
       FullTextFilter filter = getCustomerFilter(filters, "customer");
       if (filter == null) {
         return getIndexManagersForAllShards();
       }
       else {
         return new IndexManager[] { indexManagers[Integer.parseInt(
           filter.getParameter("customerID").toString())] };
       }
     }

     private FullTextFilter getCustomerFilter(FullTextFilterImplementor[] filters, String name) {
       for (FullTextFilterImplementor filter: filters) {
         if (filter.getName().equals(name)) return filter;
       }
       return null;
     }
    }

이 예에서 customer 라는 필터가 있으면 이 고객 전용 shard만 쿼리됩니다. 그렇지 않으면 모든 shard가 반환됩니다. 지정된 분할 전략은 하나 이상의 필터에 반응하고 해당 매개변수에 따라 달라집니다.

두 번째 단계는 쿼리 시간에 필터를 활성화하는 것입니다. 필터는 쿼리 후 Lucene 결과를 필터링하는 일반 필터(에 정의된 대로)일 수 있지만 sharding 전략에만 전달될 특수 필터를 사용할 수 있습니다(및 무시됨).

이 기능을 사용하려면 필터를 선언할 때 ShardSensitiveOnlyFilter 클래스를 지정합니다.

@Indexed
@FullTextFilterDef(name="customer", impl=ShardSensitiveOnlyFilter.class)
public class Customer {
   ...
}

FullTextQuery query = ftEm.createFullTextQuery(luceneQuery, Customer.class);
query.enableFulltextFilter("customer").setParameter("CustomerID", 5);
@SuppressWarnings("unchecked")
List<Customer> results = query.getResultList();

ShardSensitiveOnlyFilter를 사용하면 Lucene 필터를 구현할 필요가 없습니다. 이러한 필터에 대응하는 필터 및 분할 전략을 사용하면 sharded 환경에서 쿼리 속도를 높일 수 있습니다.

facet 검색을 위한 첫 번째 단계는 FacetingRequest를 생성하는 것입니다. 현재 두 가지 유형의 페이징 요청이 지원됩니다. 첫 번째 유형을 개별 faceting 및 두 번째 유형 범위 faceting 요청이라고 합니다. 개별 faceting 요청의 경우 facet(분산)할 인덱스 필드와 적용할 옵션을 지정합니다. 개별 다면 요청의 예는 다음 예에서 확인할 수 있습니다.

QueryBuilder builder = fullTextSession.getSearchFactory()
    .buildQueryBuilder()
        .forEntity( Cd.class )
            .get();
FacetingRequest labelFacetingRequest = builder.facet()
    .name( "labelFaceting" )
    .onField( "label")
    .discrete()
    .orderedBy( FacetSortOrder.COUNT_DESC )
    .includeZeroCounts( false )
    .maxFacetCount( 1 )
    .createFacetingRequest();

이 faceting 요청을 실행하면 색인화된 필드 레이블 의 각 개별 값에 대해 Facet 인스턴스가 생성됩니다. Facet 인스턴스는 원래 쿼리 결과 내에서 이 특정 필드 값이 얼마나 자주 발생하는지를 포함하여 실제 필드 값을 기록합니다. ordersBy에는 registriesCounts 및 maxFacetCount가 포함되며 모든 faceting 요청에 적용할 수 있는 선택적 매개변수입니다. orderedBy는 생성된 facet가 반환되는 순서를 지정할 수 있습니다. 기본값은 FacetSortOrder.COUNT_DESC 이지만 필드 값을 기준으로 정렬하거나 범위를 지정한 순서로 정렬할 수도 있습니다. include를 포함한 facet는 개수가 0인 facet가 결과에 포함될지 여부를 결정하고 maxFacetCount는 반환된 facet의 최대 양을 제한할 수 있습니다.

범위 턴팅 요청 생성은 우리가 직면하고 있는 필드 값에 대한 범위를 지정해야 한다는 점을 제외하고 매우 유사합니다. 범위 다면 요청은 세 가지 가격 범위가 지정된 아래에서 확인할 수 있습니다. 아래 와 위의 내용은 한 번만 지정할 수 있지만 원하는 만큼 from -부터 범위를 지정할 수 있습니다. 각 범위 경계에 대해 범위에 포함되었는지 여부를 excludeLimit를 통해 지정할 수도 있습니다.

QueryBuilder builder = fullTextSession.getSearchFactory()
    .buildQueryBuilder()
        .forEntity( Cd.class )
            .get();
FacetingRequest priceFacetingRequest = builder.facet()
    .name( "priceFaceting" )
    .onField( "price" )
    .range()
    .below( 1000 )
    .from( 1001 ).to( 1500 )
    .above( 1500 ).excludeLimit()
    .createFacetingRequest();

faceting 요청은 FullTextQuery 클래스를 통해 검색할 수 있는 FacetManager 클래스를 통해 쿼리에 적용됩니다.

faceting 요청 이름을 지정하는 getFacets()를 통해 원하는 만큼의 faceting 요청을 활성화하고 나중에 검색할 수 있습니다. 또한 이름을 지정하여 faceting 요청을 비활성화할 수 있는 disableFaceting() 메서드도 있습니다.

faceting 요청은 FullTextQuery를 통해 검색할 수 있는 FacetManager를 사용하여 쿼리에 적용할 수 있습니다.

// create a fulltext query
Query luceneQuery = builder.all().createQuery(); // match all query
FullTextQuery fullTextQuery = fullTextSession.createFullTextQuery( luceneQuery, Cd.class );

// retrieve facet manager and apply faceting request
FacetManager facetManager = fullTextQuery.getFacetManager();
facetManager.enableFaceting( priceFacetingRequest );

// get the list of Cds
List<Cd> cds = fullTextQuery.list();
...

// retrieve the faceting results
List<Facet> facets = facetManager.getFacets( "priceFaceting" );
...

getFacets() 및 faceting 요청 이름을 지정하여 여러 다면 지정 요청을 검색할 수 있습니다.

disableFaceting() 메서드는 이름을 지정하여 faceting 요청을 비활성화합니다.

마지막으로 반환된 Facets 중 하나를 "drill-down" 기능을 구현하기 위해 원래 쿼리에 대한 추가 기준으로 적용할 수 있습니다. 이 목적을 위해 FacetSelection을 사용할 수 있습니다. FacetSelection은 FacetManager를 통해 사용할 수 있으며 쿼리 기준(selectFacets)으로 facet를 선택하고, facet 제한(deselectFacets)을 제거하고 모든 facet 제한( clearSelectedFacets)을 제거하고 현재 선택된 facet(getSelectedFacets)를 검색합니다. 다음 코드 조각은 예를 보여줍니다.

// create a fulltext query
Query luceneQuery = builder.all().createQuery(); // match all query
FullTextQuery fullTextQuery = fullTextSession.createFullTextQuery( luceneQuery, clazz );

// retrieve facet manager and apply faceting request
FacetManager facetManager = fullTextQuery.getFacetManager();
facetManager.enableFaceting( priceFacetingRequest );

// get the list of Cd
List<Cd> cds = fullTextQuery.list();
assertTrue(cds.size() == 10);

// retrieve the faceting results
List<Facet> facets = facetManager.getFacets( "priceFaceting" );
assertTrue(facets.get(0).getCount() == 2)

// apply first facet as additional search criteria
facetManager.getFacetGroup( "priceFaceting" ).selectFacets( facets.get( 0 ) );

// re-execute the query
cds = fullTextQuery.list();
assertTrue(cds.size() == 2);

Lucene 인덱스의 주요 기능은 쿼리와 일치하는지 식별하는 것입니다. 쿼리를 수행한 후 유용한 정보를 추출하려면 결과를 분석해야 합니다. Hibernate Search는 일반적으로 클래스 유형과 기본 키를 추출해야 합니다.

인덱스에서 필요한 값을 추출하면 성능 비용이 발생하기 때문에 경우에 따라 매우 낮고 눈에 띄지 않을 수 있지만 다른 경우에는 캐싱에 적합한 후보가 될 수 있습니다.

요구 사항은 쿼리 컨텍스트 또는 기타 수단에서 유추할 수 있으므로 클래스 유형이 필요하지 않으므로 사용 중인 예상 유형에 따라 달라집니다.

@CacheFromIndex 주석을 사용하면 Hibernate Search에 필요한 기본 metadata 필드의 다양한 유형의 캐싱을 실험할 수 있습니다.

import static org.hibernate.search.annotations.FieldCacheType.CLASS;
import static org.hibernate.search.annotations.FieldCacheType.ID;

@Indexed
@CacheFromIndex( { CLASS, ID } )
public class Essay {
    ...

이 주석을 사용하여 클래스 유형 및 ID를 캐시할 수 있습니다.

FieldCache를 사용하면 고려해야 할 두 가지 단점이 있습니다.

일부 쿼리에서는 클래스 유형이 전혀 필요하지 않습니다. 이 경우 CLASS 필드 캐시를 활성화해도 사용되지 않을 수 있습니다. 예를 들어 단일 클래스를 대상으로 하는 경우 반환된 모든 값은 해당 유형이 됩니다(각 쿼리 실행 시 평가됨).

ID FieldCache를 사용하려면 대상 엔터티의 ID가 TwoWayFieldBridge(모든 빌드 브리지)를 사용해야 하며 특정 쿼리에 로드되는 모든 유형은 id에 필드 이름을 사용해야 하며 동일한 유형의 ID가 있어야 합니다(각 쿼리 실행 시 평가됨).

이 전략은 기존 인덱스를 제거한 다음 FullTextSession.purgeAll() 및 FullTextSession.index() 를 사용하여 인덱스에 모든 엔터티를 다시 추가하는 것으로 구성되지만 몇 가지 메모리 및 효율성 제약 조건이 있습니다. 최대 효율성을 위해 Hibernate Search 인덱스 작업을 배치하고 커밋 시 실행합니다. 트랜잭션 커밋까지 모든 문서가 큐에 보관되므로 많은 데이터를 인덱싱해야 합니다. 큐를 정기적으로 비우지 않는 경우 OutOfMemoryException 에 직면할 수 있습니다. 이렇게 하려면 fullTextSession.flushToIndexes() 를 사용합니다. fulltextSession.flushToIndexes() 를 호출할 때마다(또는 트랜잭션이 커밋된 경우) 배치 대기열이 처리되고 모든 인덱스 변경 사항을 적용합니다. 플러시되고 나면 변경 사항을 롤백할 수 없습니다.

fullTextSession.setFlushMode(FlushMode.MANUAL);
fullTextSession.setCacheMode(CacheMode.IGNORE);
transaction = fullTextSession.beginTransaction();
//Scrollable results will avoid loading too many objects in memory
ScrollableResults results = fullTextSession.createCriteria( Email.class )
    .setFetchSize(BATCH_SIZE)
    .scroll( ScrollMode.FORWARD_ONLY );
int index = 0;
while( results.next() ) {
    index++;
    fullTextSession.index( results.get(0) ); //index each element
    if (index % BATCH_SIZE == 0) {
        fullTextSession.flushToIndexes(); //apply changes to indexes
        fullTextSession.clear(); //free memory since the queue is processed
    }
}
transaction.commit();

애플리케이션이 메모리가 부족해지는 것을 보장하는 배치 크기를 사용하십시오. 데이터베이스에서 배치 크기 오브젝트가 더 빨리 가져오지만 더 많은 메모리가 필요합니다.

Hibernate Search의 MassIndexer는 여러 병렬 스레드를 사용하여 인덱스를 다시 빌드합니다. 선택적으로 다시 로드해야 하는 엔터티를 선택하거나 모든 엔터티를 다시 인덱스하도록 할 수 있습니다. 이 방법은 최상의 성능을 위해 최적화되지만 유지 관리 모드로 애플리케이션을 설정해야 합니다. MassIndexer가 사용 중인 경우 인덱스 쿼리는 권장되지 않습니다.

fullTextSession.createIndexer().startAndWait();

이렇게 하면 인덱스를 다시 빌드하여 삭제한 다음 데이터베이스에서 모든 엔터티를 다시 로드합니다. 사용이 간단하지만, 프로세스 속도를 높이기 위해 일부 조정을 권장합니다.

fullTextSession
 .createIndexer( User.class )
 .batchSizeToLoadObjects( 25 )
 .cacheMode( CacheMode.NORMAL )
 .threadsToLoadObjects( 12 )
 .idFetchSize( 150 )
 .progressMonitor( monitor ) //a MassIndexerProgressMonitor implementation
 .startAndWait();

그러면 모든 사용자 인스턴스(및 하위 유형)의 인덱스가 다시 빌드되고 쿼리당 25개 오브젝트의 배치를 사용하여 User 인스턴스를 로드할 12개의 병렬 스레드가 생성됩니다. 이 12개 스레드는 Lucene 문서를 출력하기 위해 인덱싱된 임베디드 관계 및 사용자 정의 Field Bridges 또는 ClassBridges 를 처리해야 합니다. 스레드는 변환 프로세스 중에 추가 속성의 지연 로드를 트리거합니다. 이로 인해 병렬로 작동하는 많은 스레드가 필요합니다. 실제 인덱스 쓰기에 사용되는 스레드 수는 각 인덱스의 백엔드 구성으로 정의됩니다.

대부분의 재지급 상황에서 캐시가 사용되지 않는 추가 오버헤드가 발생하므로 cache Mode.IGNORE(기본값)를 CacheMode.IGNORE(기본값)로 두는 것이 좋습니다. 기본 엔터티가 인덱스에 포함된 열거와 유사한 데이터와 관련된 경우 데이터를 향상시킬 수 있으므로 다른 CacheMode 를 활성화하는 것이 유용할 수 있습니다.

인덱싱 시간과 메모리 사용량에 영향을 주는 기타 매개변수는 다음과 같습니다.

이전 버전에는 max_field_length 도 있었지만 Lucene에서 제거되었습니다. LimitTokenCountAnalyzer 를 사용하여 유사한 효과를 얻을 수 있습니다.

all .indexwriter 매개변수는 Lucene 고유하며 Hibernate Search는 이러한 매개변수를 전달합니다.

MassIndexer는 로드할 기본 키를 반복하기 위해 앞으로만 스크롤 가능한 결과를 사용하지만 MySQL의 JDBC 드라이버는 메모리의 모든 값을 로드합니다. 이 "최적화"를 방지하려면 idFetchSize 를 Integer.MIN_VALUE 로 설정합니다.