[WinUI] Lucene.NET 텍스트 검색 라이브러리 사용하기 (1) - 기본 개념과 구성 요소

🚩 Lucene.NET이란

⭐ Lucene과 Lucene.NET

• Lucene은 Apache Software Foundation에서 만든 Java 기반 고성능 오픈 소스 풀텍스트 검색 라이브러리이다. Lucene은 대규모 데이터의 인덱싱 및 검색 기능을 애플리케이션에 통합할 수 있게 한다. 자체적으로 완전한 검색 애플리케이션이 아닌, 검색 기능을 구축하기 위한 핵심 구성 요소(라이브러리)이다. 역 인덱스 구조를 기반으로 빠르고 효율적인 검색을 지원한다.
• ElasticSearch, OpenSearch 등의 유명 검색 엔진이 Lucene 기반으로 제작되었다. 이들 검색 엔진은 Lucene을 코어로 사용하여 REST API, 분산 처리, 샤딩, 리플리케이션, 클러스터링 등의 기능을 추가하였다.
• Lucene은 JVM(Java, Kotlin, Scala 등) 기반에서만 동작한다. 이렇게 원래 Java로 작성된 Lucene의 기능을 .NET 언어로 재작성하여 .NET 런타임에서도 사용할 수 있도록 .NET 포팅 버전을 제작하였는데, 이것이 Lucene.NET이다.
• Lucene.NET은 인덱스, 쿼리, 분석기(Analyzer), 토큰화 등 기본 개념과 API 구조가 Lucene과 거의 동일하다. Lucene.NET은 독립 프로젝트이지만, Lucene의 아키텍처와 버전 호환을 따라간다.
• Lucene.NET에 대한 자세한 설명은 Apache Lucene.NET에서 확인할 수 있다.

 

---

⭐ Lucene.NET 버전과 NuGet 패키지

• NuGet 패키지로 Lucene.NET 라이브러리를 설치할 수 있다. 현재 최신 버전은 4.8.0-beta00017로 NuGet 패키지 관리에서 "시험판 포함"을 선택하면 최신 시험판을 다운로드받을 수 있다.
• Lucene.NET은 전통적인 텍스트 검색(토큰화, 역색인, 불용어 처리, 문서 정렬 등) 중심이며, 최신 검색 패러다임에는 한계가 있다.
• Lucene.NET에 관련된 여러 NuGet 패키지가 있는데 기본적으로 Lucene.Net, Lucene.Net.Analysis.Common, Lucene.Net.QueryParser를 설치한다.

 

---

🚩 Lucene.NET 구성 요소 (1): 인덱스에 입력하는 데이터

⭐ Document와 Field

• Document(문서): 인덱스의 대상이 되는 기본 단위이다. 하나의 Document는 검색 가능한 객체 하나를 의미한다. Document는 여러 개의 Field를 가진다.
• 여기에서는 Document를 한국어로 번역하여 "문서"라고 표현하였다. 이는 텍스트 데이터나 글로서 사용하는 "문서"의 의미가 아니라, Lucene.Net.Documents.Document 객체로서 앞서 설명했던 인덱스의 대상이 되는 단위를 의미한다.
• Field(필드): 필드는 Document의 한 부분으로, Document 내부의 속성이다. 각 필드마다 이름, 값, 유형(인덱스 여부, 저장 여부, 검색 가능 여부 등)을 지정할 수 있다. 필드는 선택적으로 인덱스에 저장되어 문서에 대한 조회 결과로 반환될 수 있다.
• Document가 게시판 글이라면, 그 안에 제목, 작성자, 작성 시간, 본문 등의 Field들을 지정할 수 있다.
• Document 객체는 Lucene.Net.Documents 네임스페이스의 Document 클래스 인스턴스를 생성하여 만든다. 이때 Document는 IEnumerable 타입으로 컬렉션 초기자로 Field 객체를 추가하여 초기화할 수 있다. 또한 Get, Add, RemoveField 등의 메서드로 필드를 확인/변경할 수 있다.

using Lucene.Net.Documents;

(string Id, string Title, string Content) article = ("User Id", "Title 1", "Content 1");

Document doc = new()
{
    new StringField("Id", article.Id, Field.Store.YES),
    new TextField("Title", article.Title, Field.Store.YES),
    new TextField("Content", article.Content, Field.Store.NO)
};

• Field 객체는 Lucene.Net.Documents 네임스페이스의 Field 클래스 또는 Field의 파생 클래스 인스턴스를 생성하여 만들 수 있다. Field 인스턴스를 생성할 때는 주로 세 개의 매개변수를 받는 생성자를 사용한다. 첫 번째 인자로는 여러 필드들을 구분할 생성하려는 필드의 이름, 두 번째 인자로는 필드에 삽입할 값(콘텐츠), 세 번째 인자로는 필드를 어떻게 다룰 것인지 결정하는 설정값이 들어간다.
• Field 객체의 FieldType 속성을 조정하여 Field 인스턴스 하나로 모든 파생 클래스 필드 인스턴스를 대체할 수 있다. 파생 클래스들은 타입을 고정하고 편리한 사용을 위해 만들어진 것이다. FieldType으로 지정할 수 있는 속성은 다음과 같다.

속성	타입	설명	기본값
DocValueType	DocValuesType Enum (BINARY, NONE, NUMERIC, SORTED, SORTED_SET)	DocValue 값 타입	NONE
IndexOptions	IndexOptions Enum (DOCS_AND_FREQS, DOCS_AND_FREQS_AND_POSITIONS, DOCS_AND_FREQS_AND_POSITIONS_AND_OFFSETS, DOCS_ONLY, NONE)	인덱싱 옵션	DOCS_AND_FREQS_AND_POSITIONS
IsIndexed	bool	인덱싱 여부	false
IsStored	bool	필드 값 저장 여부	false
IsTokenized	bool	토큰화 여부	true
NumericPrecisionStep	int	숫자 값 정확도	PRECISION_STEP_DEFAULT (4)
NumericType	NumericType Enum (DOUBLE, INT32, INT64, SINGLE, NONE)	숫자 값 타입	NONE
OmitNorms	bool	omit normalization	false
StoreTermVectorOffsets	bool		false
StoreTermVectorPayloads	bool		false
StoreTermVectorPositions	bool		false
StoreTermVectors	bool		false

 

• Field의 파생 클래스들은 크게 검색 조건으로 사용 가능한 인덱싱 필드와, 검색용이 아닌 다른 용도인 비인덱싱 필드색 조건으로 사용 가능한 인덱싱 필드와, 검색용이 아닌 다른 용도인 비인덱싱 필드로 나눈다.
  • 인덱싱 필드: 인덱싱 필드는 필드 값 타입에 따라 나눌 수 있다.

필드(Field)	필드 값 타입(CLR)	설명	특징
StringField	string	문자열 값을 인덱싱하는 텍스트 필드 텍스트를 토큰화함	전체 문자열 값이 단일 토큰으로 인덱싱됨
TextField	string	문자열 값을 인덱싱하는 텍스트 필드 텍스트를 토큰화함	토큰화하여 인덱싱하지만 TermVector는 저장하지 않음
Int32Field	int	int 값을 인덱싱하는 필드	효율적인 범위 필터링 및 정렬을 사용
Int64Field	long	long 값을 인덱싱하는 필드	효율적인 범위 필터링 및 정렬을 사용
SingleField	float	float 값을 인덱싱하는 필드	효율적인 범위 필터링 및 정렬을 사용
DoubleField	double	double 값을 인덱싱하는 필드	효율적인 범위 필터링 및 정렬을 사용

 

• 비인덱싱 필드: 비인덱싱 필드는 저장 구조에 따라 Document와 Field 기반으로 나눌 수 있다.
  • Document(행) 기반: 문서 단위로 데이터가 저장된다. 특정 필드만 조회하려면 해당 문서를 디코딩해야 한다. 따라서 랜덤 접근은 가능하지만 순차 접근은 비효율적이다. 검색 결과 반환용으로 설계되었다.
  • Field(열) 기반: 필드별로 모든 문서 값이 연속 배열로 저장되어 DocID와 값 매핑이 빠르다. 빠른 값 조회, 대량 순차 접근, 후처리, 정렬/그룹핑에 효율적이다. 검색 과정과 후처리용으로 설계되었다.

필드(Field)	저장 구조	필드 값 타입	설명	특징
StoredField	Document(행) 기반	모든 타입 (string, int, long, float, double, BytesRef)	d	d
BinaryDocValuesField 및 파생	Field(열) 기반	BytesRef	d	d
NumericDocValuesField 및 파생	Field(열) 기반	숫자 타입 (byte, short, int, long, float, double)	d	d
SortedDocValuesField 및 파생	Field(열) 기반	BytesRef	d	d
SortedSetDocValuesField	Field(열) 기반	BytesRef	d	d

 

---

🚩 Lucene.NET 구성 요소 (2): 인덱스가 데이터를 가공하는 방식

⭐ Token과 Term

• Token(토큰): Token은 Analyzer가 원본 텍스트를 분석할 때 만들어내는 중간 산출물이다. 텍스트 데이터는 검색을 위해 초기에 텍스트를 분석하여 이것을 작은 단위로 분해하는 과정을 수행한다. 이때 이 분해된 조각을 Token이라고 부른다. Token은 Analyzer 단계에서만 존재하는 임시 객체이며, 실제 인덱스에는 저장되지 않는다.
• 예를 들어 "The quick brown fox jumps"와 같은 원본 텍스트 데이터가 있다고 하자. Analyzer가 이 텍스트를 분석할 때, 단어 단위로 문장을 쪼갠 후 대문자를 모두 소문자로 바꾼다. 그리고 "the"와 같은 불용어를 제거하고 "jumps"와 같은 문법적 단어에서 "jump"라는 표제어를 추출(lemmatization)한다. 그 결과로 "quick", "brown", "fox", "jump"와 같은 단어들을 얻을 수 있다. 이렇게 얻은 단어 하나하나를 Token이라고 하고, 이 Token들을 모두 모은 묶음(컬렉션)을 TokenStream이라고 한다.
• Term(텀): Term은 Token을 기반으로 인덱스에 실제로 저장되는 검색 단위이다. Term은 기본적으로 필드명과 텍스트의 조합으로 정의되며 인덱스에는 Term이 사전 형태로 저장된다. 인덱스에서 문서를 검색할 때 검색 쿼리는 Term 단위로 이루어진다.
• 예를 들어 어떤 Document의 "body"라는 Field의 값이 "The quick brown fox jumps"라고 하자. 인덱싱 시 Analyzer가 호출되어 텍스트를 토큰화하여 "quick", "brown", "fox", "jump"와 같이 만든다. 각 토큰들은 Term으로 간주되어 다음과 같이 Field와 Text 속성이 포함된 Term 객체를 생성하여 인덱스에 저장한다.

// 실제 객체 구조가 아닌 논리적 구조를 표현함
Term body:quick  (Field -> "body", Text -> "quick")
Term body:brown  (Field -> "body", Text -> "brown")
Term body:fox    (Field -> "body", Text -> "fox")
Term body:jump   (Field -> "body", Text -> "jump")

• 그 다음 인덱서는 현재 Document에 대해 각 Term의 정보를 추가한다. 그 정보에는 현재 문서의 Id(DocId), Term이 문서에서 발생한 빈도(Frequency), 발생 위치(Position), 텍스트의 범위(Offset) 등이 선택적으로 저장된다.
• 검색 시 쿼리 문자열(검색어)가 들어오면 그 문자열도 Analyzer로 처리하여 Term을 생성한다. 그 Term을 기반으로 인덱스에서 일치하는 Term을 찾을 수 있고 그 Term에 해당하는 정보를 불러와 어느 문서, 어느 위치에 존재하는지 조회할 수 있다.

 

---

⭐ Analyzer

• Analyzer(분석기): 텍스트를 분석하여 색인, 검색 가능한 토큰들의 집합인 TokenStream을 생성하는 정책(파이프라인)이다. 파이프라인은 일반적으로 CharFilter -> Tokenizer -> TokenFilter 형태로 동작하고, 각 단계는 텍스트를 정규화, 분해, 가공한다.
• CharFilter: 원본 텍스트를 문자 단위로 삽입, 삭제, 치환하여 전처리한다. HTML 태그를 제거(HTMLStripCharFilter)하거나, 특정 문자열을 치환하고 축약어를 확장(MappingCharFilter)하거나, 문장부호를 공백으로 치환하는 등 Tokenizer가 텍스트를 TokenStream으로 분리하기 전 더 잘 분리할 수 있도록 원본 텍스트를 전처리하는 역할을 한다. CharFilter는 연속적으로 사용 가능하며 내부적으로 오프셋 보정 정보를 관리한다.
• Lucene.NET Analyzer 클래스에서는 InitReader 메서드를 오버라이드하여 메서드 인자로 받은 TextReader 객체를 CharFilter로 래핑하여 다시 TextReader 객체로 반환할 수 있도록 지원한다. 이때, TextReader는 .NET의 System.IO.TextReader를 의미한다.

// CharFilter를 적용시킬 Analyzer 클래스의 가상 메서드
protected virtual TextReader InitReader(string fieldName, TextReader reader)

• TokenStream: Document의 필드 또는 쿼리 텍스트에서 토큰 시퀀스를 나열하는 객체이다. TokenStream 클래스는 추상 클래스로, 파생 클래스로 Tokenizer와 TokenFilter 클래스를 가진다. Tokenizer는 TextReader를 입력으로 받는 TokenStream이고, TokenFilter는 다른 TokenStream을 입력으로 받는 TokenStream이다.
• TokenStream 클래스는 AttributeSource 클래스의 파생 클래스로서, 다양한 Attribute(특성) 목록과 특성을 추가하고 가져오는 메서드를 가지고 있다. TokenStream 클래스에 특성을 추가하고 설정함으로써 토큰의 특성을 지정할 수 있다.
• TokenStream은 다음과 같은 단계로 토큰과 그에 맞는 토큰 특성을 생성한다. 세 메서드는 모두 오버라이드 가능하다.
  • Reset() 메서드: TokenStream이 새로운 입력을 처리할 준비를 하는 단계이다. 이전 토큰 상태를 초기화하고, TokenStream이 입력을 처음부터 읽도록 설정한다.
  • IncrementToken() 메서드: 실제로 토큰을 생성하고 변환하는 단계이다. 그 다음 스트림을 다음 토큰으로 이동시킨다. 토큰은 여러 TokenStream 체인을 한 토큰씩 통과한다. 메서드 내부는 다음과 같은 방식으로 TokenStream 내부 상태를 갱신한다(오버라이드 시 다음과 같은 방식으로 동작하게 처리한다).
    • 메서드 호출 시 다음 토큰이 있으면 true를 반환하고 더이상 토큰이 없으면 false를 반환한다.
    • 메서드가 호출되는 동안 토큰을 생성하고 토큰 특성(term, offset, position 등의 attribute)을 새로운 토큰에 맞게 갱신한다.
    • 특성을 지정하기 전 기존 특성을 ClearAttribute() 메서드로 초기화한 후, 필요한 특성을 설정하고 다음 토큰 존재 여부에 따라 true 혹은 false를 반환한다.
    • 토큰 속성은 토큰(혹은 텀) 텍스트를 지정하는 ICharTermAttribute, 텀의 위치(오프셋)을 지정하는 IOffsetAttribute, 토큰의 타입(단어, 숫자 등)을 지정하는 ITypeAttribute 등이 있다.
  • End() 메서드: TokenStream이 마지막 토큰을 처리한 후 정리하는 단계이다. 마지막 오프셋 설정, 리소스 정리 등의 스트림 종료 작업을 수행하는 데 사용된다.
• Tokenizer: 원본 텍스트 또는 CharFilter로 래핑된 TextReader를 읽어 텍스트를 토큰들로 분해한다. 토큰을 분해할 때 토큰 경계를 결정하고, 토큰 단위의 특성을 추가한다. Tokenizer는 TextReader를 받아서 TokenStream을 반환하므로 Analyzer 파이프라인에서 내부에서 처음 한 번만 수행된다.
• TokenFilter: Tokenizer로 분해된 기존 토큰들을 변환, 필터링하는 역할을 한다. 토큰 텍스트를 변환하거나, 불필요한 토큰을 제거하고, 더 작은 토큰으로 분해하는 등 기존 TokenStream을 받아서 변환 후 새로운 TokenStream을 반환한다. Analyzer 파이프라인에서 Tokenizer의 후속 단계들로 여러 TokenFilter를 중첩하여 사용할 수 있다.