Introduction to Lucene's API : 다른 Lucene Pakcages들의 high-level summary

Materials

• • Apache Lucene은 고성능의 full-featured text search engine library이다. 여기 indexing을 하고 searching을 하는데 Lucene을 어떻게 사용하는지 예제가 있다. (기대한 결과를 check하기 위해 JUnit을 이용한다.)
    
    

    Analyzer analyzer = new StandardAnalyzer();       // Store the index in memory:     Directory directory = new RAMDirectory();     // To store an index on disk, use this instead:     //Directory directory = FSDirectory.open("/tmp/testindex");     IndexWriterConfig config = new IndexWriterConfig(analyzer);     IndexWriter iwriter = new IndexWriter(directory, config);     Document doc = new Document();     String text = "This is the text to be indexed.";     doc.add(new Field("fieldname", text, TextField.TYPE_STORED));     iwriter.addDocument(doc);     iwriter.close();           // Now search the index:     DirectoryReader ireader = DirectoryReader.open(directory);     IndexSearcher isearcher = new IndexSearcher(ireader);     // Parse a simple query that searches for "text":     QueryParser parser = new QueryParser("fieldname", analyzer);     Query query = parser.parse("text");     ScoreDoc[] hits = isearcher.search(query, null, 1000).scoreDocs;     assertEquals(1, hits.length);     // Iterate through the results:     for (int i = 0; i < hits.length; i++) {       Document hitDoc = isearcher.doc(hits[i].doc);       assertEquals("This is the text to be indexed.", hitDoc.get("fieldname"));     }     ireader.close();     directory.close();

  • Lucene API는 몇가지 package로 구분된다.

    Icon

    org.apache.lucene.analysis : Reader에서 TokenStream으로 text를 변환하는 추상화된 Analyzer API 정의.

    org.apache.lucene.codecs : index 구조를 뒤집어서 encoding/decoding하는 추상 계층 제공.

    org.apache.lucene.document : 간단한 Document class 제공. Document는 Field들의 집합이다. 값으로는 String이나 Reader를 가질 수 있다.

    org.apache.lucene.index : 2개의 주요 class 제공. IndexWriter - index에 document를 생성, 추가. IndexReader - index의 data에 access.

    org.apache.lucene.search : query를 설명하는 data 구조 제공. (ex. 개별 단어에 대한 TermQuery, Phrase에 대한 PhraseQuery, query상의 boolean 조합에 대한 BooleanQuery). IndexSearcher - TopDocs로 query를 바꿈. QueryParser의 개수는 string이나 xml로부터 query 구조를 만들어 내기 위해 제공된다.

    org.apache.lucene.store : persistent data를 저장하기 위한 추상화 클래스. Directory는 IndexOutput에 의해 쓰여지거나 IndexInput에 의해 읽혀진 named file의 집합이다. FSDirectory를 포함하여 여러 가지 형태의 구현체가 제공된다. RAMDirectory는 메모리에 데이터 구조를 쓰기 위한 구현체이다.

    org.apache.lucene.util : FixedBitSet과 PriorityQueue와 같은 몇 가지 데이터 구조와 util class를 포함하고 있다.

    
    

  • Lucene을 사용하기 위해서, Application은 다음과 같이 해야 한다.

    • Fields를 추가하기 위해서는 Document를 생성해야 한다.

    • IndexWriter를 생성하고 addDocument()를 통해서 document를 추가해야 한다.

    • String으로부터 Query를 생성하기 위해서는 QueryParser.parse()를 호출해야 한다.

    • IndexSearcher를 생성하고 search() method에 query를 전달해야 한다.

  • 간단한 code example은 다음과 같다.

    • IndexFiles.java : directory에 있는 모든 파일들에 대해서 index를 생성한다.

    • SearchFiles.java : query를 입력하고, index를 검색한다.

  • 이것을 설명하기 위해서 다음과 같이 실행해 보라.

    > java -cp lucene-core.jar:lucene-demo.jar:lucene-analyzers-common.jar org.apache.lucene.demo.IndexFiles -index index -docs rec.food.recipes/soups adding rec.food.recipes/soups/abalone-chowder  [ ... ]> java -cp lucene-core.jar:lucene-demo.jar:lucene-queryparser.jar:lucene-analyzers-common.jar org.apache.lucene.demo.SearchFiles Query: chowder Searching for: chowder 34 total matching documents 1. rec.food.recipes/soups/spam-chowder  [ ... thirty-four documents contain the word "chowder" ... ] Query: "clam chowder" AND Manhattan Searching for: +"clam chowder" +manhattan 2 total matching documents 1. rec.food.recipes/soups/clam-chowder  [ ... two documents contain the phrase "clam chowder" and the word "manhattan" ... ]  [ Note: "+" and "-" are canonical, but "AND", "OR" and "NOT" may be used. ]

Lucene은 Java 기반 Full-text search engine이다.

Lucene은 완전한 application이 아니라, 검색 기능을 제공하고자 하는 Application에 쉽게 사용할 수 있는 code library이고 API를 제공한다.

Apache Lucene 5.2.1에 대한 official documentation에 대해서 정리해 보고자 한다. 추가적인 문서는 Wiki(http://wiki.apache.org/lucene-java)에서 살펴볼 수 있다.

Getting Started

다음 섹션은 getting started guide를 제공하고자 하는 목적으로 작성되었다.

다음 3가지 유형의 사용자를 대상으로 한다.

1) Application에 Apache Lucene을 처음 설치하고자 하는 사용자

2) Lucene 기반 Application을 개발하거나 수정하고자 하는 개발자

3) Lucene 개발에 참여하거나 기여하고자 하는 개발자

Lucene에 대한 깊은 개념이나 상세한 내용을 다루지는 않는다.

Lucene demo, its usage, and sources : Command-line Lucene demo에 대한 tutorial.

• • Lucene demo를 사용하고 실행하기 위한 getting started guide로 기획된 문서.
  • 기본적인 설치와 설정에 대해서 다루고 있음.
  • Lucene command-line demo code는 Lucene의 다양한 기능과 application에 Lucene을 어떻게 추가하여 사용할 수 있는지를 설명하는 application으로 구성되어 있음.
  • 먼저 가장 최근 배포한 Lucene을 다운로드(http://www.apache.org/dyn/closer.cgi/lucene/java/)하고 working directory 에 압축해제한다.
  • 4개의 jar가 필요하다 : Lucene jar, queryparser jar, common analysis jar, Lucene demo jar.
  • 이 4개의 jar 파일을 java CLASSPATH에 위치시킨다.
    
    
  • CLASSPATH가 잘 잡혔다면, java org.apache.lucene.demo.IndexFiles -docs {path-to-lucene}/src 로 index를 생성할 수 있다.
  • 위의 결과로 모든 lucene source code에 대한 index를 포함하고 있는 index라고 불리는 subdirectory를 생성할 것이다.
  • index를 검색하기 위해서 java org.apache.lucene.demo.SearchFiles 라고 치면, query를 입력하라는 prompt가 든다.
  • 횡설수설하는 말이나 임의의 단어를 쳐보자. 검색 결과가 없음을 볼 수 있다.
  • string이라는 단어를 쳐보자. 모든 document에 대해서 리턴할 것이다.
  • 매 10개의 결과를 보여주는 페이지가 뜨고, 계속해서 더 많은 결과를 볼 것인지 묻는다.

• • 다음 2가지 source code를 살펴보자.
    • IndexFiles.java : Lucene index를 생성하는 코드
      앞에서 논의한 것처럼, IndexFiles class는 Lucene index를 생성한다. 어떻게 동작하는지 알아보자.
      main() method는 command-line parameter를 파싱한다. 그 후, IndexWriter를 초기화하고, Directory를 open하고, StandardAnalyzer와 IndexWriterConfig를 초기화한다.
      
      -index command-line parameter 값은 모든 index 정보가 저장되어야 할 filesystem directory의 이름을 의미한다.
      만약, IndexFiles가 command-line에서 주어진 -index parameter에 대해 상대경로로 호출되거나 -index값이 주어지지 않는다면, "index" 경로로 default 상대 경로가 사용되기 때문에 index path는 현재 working directory의 subdirectory로 생성될 것이다. (이미 존재하지 않는다면). 어떤 플랫폼(OS)에서는 index path가 다른 directory에 생성될 것이다. (ex. user's home directory)
      
      -docs command-line 파라미터 값은 index된 파일들이 있는 directory의 위치를 의미한다.
      
      -update command-line 파라미터 값은 이미 존재하는 index에 대해서 IndexFiles가 삭제하지 않도록 한다.
      
      Lucene Directory는 index에 정보를 저장하기 위해서 IndexWriter가 사용한다. 게다가, 확장하여 사용하는 FSDirectory는 RAM이나 데이터베이스와 같은 곳에 write할 수 있는 몇가지 다른 Directory의 subclass들이 있다.
      
      Lucene Analyzer는 text를 indexed tokens로 쪼개는 pipeline 프로세스를 처리한다. 또한 소문자화, 유사어 삽입, 원치 않는 token 필터링과 같은 동작을 수행한다.
      Analyzer는 StandardAnalyzer를 사용하고, Unicode Standard Annex #29에 정의된 Unicode Text Segmentation 알고리즘에 의한 word break rule을 사용하여 token을 생성한다. token을 소문자화하고, 불용어를 걸러낸다. 불용어는 a, an, the와 같은 일반적인 단어들과 검색에 잘 쓰이지 않는 token들을 의미한다. 각 언어마다 다른 rule이 있기 때문에 각각의 경우에 적합한 analyzer를 사용해야 한다. Lucene은 현재 많은 다른 언어에 대해 Analyzer를 제공한다.
      
      IndexWriterConfig instance는 IndexWriter에 대한 모든 설정을 담고 있다. 예를 들면, -update command-line 파라미터에 근거하여 사용할 수 있도록 OpenMode를 설정할 수 있다.
      
      파일 내에서 더 아래로 내려가보면, IndexWriter가 초기화된 이후, indexDocs() code를 볼 수 있다. 재귀함수는 directory들을 크롤링하면서 Document object를 생성한다. Document는 간단한 file에 있는 text content와 생성 시간, 위치를 표현하는 data object이다. 이런 Document들은 IndexWriter에 추가된다. 만약 -update 파라미터가 주어지면, IndexWriterConfig의 OpenMode는 OpenMode.CREATE_OR_APPEND로 설정될 것이다. 그리고 index에 document를 추가하기보다 IndexWriter는 동일한 identifier로 이미 indexed된 document인지 확인한 후, 있으면 지우고 index에 새로운 document를 추가하는 방식으로 update할 것이다.
      
      
    • SearchFiles.java : Lucene index를 검색하는 코드
      
      SearchFiles class는 매우 간단하다. IndexSearcher, StandardAnalyzer(IndexFiles에서 사용하는 것과 동일함), QueryParser와 협업한다. Query parser는 document가 해석되는 것과 동일한 방식으로 query text를 해석하는데 사용하는 analyzer이다. word boundary를 찾고, 소문자화한 이후, a, an, the와 같이 불필요한 단어를 제거한다. Query object는 searcher로 넘겨지는 QueryParser의 결과를 담고 있다. Query Parser를 사용하지 않고 프로그램으로 Query object를 만들 수도 있다. query parser는 Query object와 일치하도록 lucene query syntax를 decoding할 수 있다.
      
      SearchFiles는 최대 n번의 hit를 가지는 TopDocs를 리턴하는 IndexSearcher.search(query, n) method를 사용한다. 그 결과로 score로 정렬된 page들을 print한다.