MariaDB 한글 검색 제대로 설정하기, “my.cnf ngram_token_size=1” 적용 방법

들어가며

MariaDB에서 한글 검색 기능을 구현하다 보면 생각보다 자주 부딪히는 문제가 있습니다.

분명 데이터가 저장되어 있고 검색어도 정확하게 입력했는데 원하는 결과가 나오지 않는 경우입니다. 특히 FULLTEXT 검색이나 ngram 기반의 한글 검색을 사용하는 환경이라면 단순히 SQL 문장만 확인해서는 원인을 찾기 어려울 때가 있습니다.

저 역시 검색 기능을 구성하면서 여러 가지 설정을 확인하게 됐는데, 그중 하나가 바로 MariaDB의 ngram_token_size 설정이었습니다.

이번 글에서는 MariaDB의 my.cnf에서 ngram_token_size=1을 설정하는 방법과 이 옵션이 한글 검색에 어떤 영향을 주는지 정리해보겠습니다.

MariaDB의 ngram이란?

먼저 ngram이 무엇인지 간단하게 알아둘 필요가 있습니다.

ngram은 문자열을 일정한 길이의 단위로 나누어 검색할 수 있도록 만드는 방식입니다. 예를 들어 특정 문자열을 여러 개의 작은 토큰으로 분리한 뒤, 사용자가 입력한 검색어와 비교하는 방식이라고 생각하면 이해하기 쉽습니다.

특히 한국어처럼 띄어쓰기가 검색에 항상 중요한 의미를 갖지 않는 언어에서는 이러한 방식이 유용할 수 있습니다.

예를 들어 상품명이나 게시글 제목에 다음과 같은 문장이 있다고 가정해보겠습니다.

인천 맛집 추천

검색자가 인천을 입력했을 때 해당 문서를 찾아야 한다면 단순한 문자열 비교 외에도 적절한 토큰화가 필요합니다.

여기서 ngram 설정이 검색 결과에 영향을 줄 수 있습니다.

ngram_token_size=1은 무엇을 의미할까?

ngram_token_size는 ngram 토큰을 어느 정도 크기로 나눌 것인지 결정하는 설정입니다.

ngram_token_size=1로 설정하면 문자열을 1글자 단위로 쪼개어 처리하는 방식을 사용할 수 있습니다.

예를 들어 한글 문자열을 검색한다고 생각해보겠습니다.

축구경기

이를 1글자 단위로 보면 다음과 같은 형태로 생각할 수 있습니다.

축, 구, 경, 기

이렇게 작은 단위로 검색 데이터를 구성하면 짧은 검색어에 대한 대응이 쉬워질 수 있습니다.

특히 게시판, 블로그, 상품 검색처럼 사용자가 한두 글자만 입력해서 검색하는 경우라면 ngram 토큰 크기를 적절하게 설정하는 것이 중요합니다.

my.cnf에서 ngram_token_size 설정하기

MariaDB 서버에서 관련 설정을 변경하려면 일반적으로 MariaDB의 설정 파일인 my.cnf를 수정합니다.

환경에 따라 파일 위치는 다를 수 있지만 Linux 서버에서는 /etc/mysql/my.cnf 또는 MariaDB 설정 디렉터리 아래의 별도 설정 파일을 사용하는 경우가 많습니다.

설정 파일을 열어 필요한 영역에 다음과 같이 설정합니다.

[mysqld]
ngram_token_size=1

이미 [mysqld] 영역이 있다면 해당 영역에 옵션을 추가하면 됩니다.

설정을 저장한 뒤에는 MariaDB 서버를 재시작해야 변경 사항이 적용됩니다.

예를 들어 systemd 환경이라면 다음과 같이 실행할 수 있습니다.

sudo systemctl restart mariadb

서버 환경에 따라 서비스 이름이 mysql인 경우도 있으므로 실제 설치 환경에 맞춰 명령어를 확인하는 것이 좋습니다.

설정했다고 바로 검색 결과가 바뀌는 것은 아니다

여기서 중요한 부분이 하나 있습니다.

ngram_token_size=1을 설정했다고 해서 기존에 생성되어 있던 FULLTEXT 인덱스가 자동으로 새로운 방식으로 다시 만들어지는 것은 아닙니다.

FULLTEXT 검색을 사용하고 있다면 기존 인덱스와 토큰화 방식의 관계를 함께 확인해야 합니다.

설정을 변경한 후에도 검색 결과가 예상과 다르다면 다음 항목을 순서대로 확인하는 것이 좋습니다.

1. MariaDB 설정 파일에 옵션이 제대로 들어갔는지 확인
2. MariaDB가 정상적으로 재시작됐는지 확인
3. 실제 서버에 설정이 적용됐는지 확인
4. FULLTEXT 인덱스 설정 확인
5. 필요한 경우 인덱스를 다시 생성
6. 실제 데이터로 검색 테스트

설정 파일만 수정하고 테스트하는 것보다 이 과정을 하나씩 확인하는 편이 문제를 찾기 훨씬 쉽습니다.

설정이 제대로 적용됐는지 확인하는 방법

MariaDB에 접속한 뒤 현재 설정값을 확인할 수 있습니다.

SHOW VARIABLES LIKE 'ngram_token_size';

정상적으로 적용됐다면 결과에서 설정값이 1로 표시되는지 확인할 수 있습니다.

만약 원하는 값이 나오지 않는다면 설정 파일의 위치가 잘못됐거나, [mysqld]가 아닌 다른 영역에 설정했거나, MariaDB 재시작이 제대로 이루어지지 않았을 가능성도 있습니다.

따라서 설정 파일을 수정한 뒤에는 반드시 실제 서버에서 변수값을 확인하는 것이 좋습니다.

왜 한글 검색에서 신경 써야 할까?

한국어 검색은 영어 검색과 조금 다르게 생각할 필요가 있습니다.

영어는 공백을 기준으로 단어를 나누는 방식이 비교적 직관적이지만, 한글 검색에서는 사용자가 입력하는 검색어의 길이가 짧거나 조사와 표현 방식이 달라 검색 결과가 기대와 다르게 나오는 경우가 있습니다.

예를 들어 사용자가 게시글에서 토트넘이라는 단어를 검색한다고 해보겠습니다.

데이터에는 토트넘 경기 분석, 토트넘 최근 경기, 토트넘 예상 라인업 등의 문장이 저장되어 있을 수 있습니다.

이때 검색 시스템이 문자열을 어떻게 분리하고 색인했느냐에 따라 결과가 달라질 수 있습니다.

그래서 MariaDB에서 한글 검색을 구현할 때는 단순히 LIKE '%검색어%'만 사용할 것인지, FULLTEXT 검색을 사용할 것인지, 그리고 ngram 기반 검색을 적용할 것인지 등을 서비스 성격에 맞춰 결정해야 합니다.

ngram_token_size=1의 장점과 주의할 점

1글자 단위로 토큰을 생성하는 방식은 짧은 검색어를 처리하는 데 장점이 있을 수 있습니다.

하지만 무조건 1이 가장 좋은 설정이라고 생각해서는 안 됩니다.

토큰 크기가 작아질수록 생성되는 토큰의 수가 많아질 수 있기 때문에 인덱스 크기와 검색 성능도 함께 고려해야 합니다.

데이터가 적은 개인 블로그나 소규모 게시판에서는 큰 문제가 되지 않을 수도 있지만, 수십만~수백만 건 이상의 데이터를 가지고 있는 서비스라면 인덱스 크기와 검색 성능을 함께 테스트하는 것이 좋습니다.

결국 중요한 것은 ngram_token_size=1이라는 값을 무조건 적용하는 것이 아니라, 내가 만들고 있는 검색 기능에 적합한지를 확인하는 것입니다.

마무리

MariaDB에서 한글 검색이 제대로 동작하지 않을 때는 SQL 문장만 계속 수정하기보다 토큰화와 FULLTEXT 인덱스 설정을 함께 살펴볼 필요가 있습니다.

특히 ngram 기반 검색을 사용하고 있다면 my.cnf의 ngram_token_size 설정이 검색 결과에 영향을 줄 수 있습니다.

설정은 다음처럼 비교적 간단합니다.

[mysqld]
ngram_token_size=1

그리고 MariaDB를 재시작한 다음 아래 명령어로 실제 적용 여부를 확인합니다.

SHOW VARIABLES LIKE 'ngram_token_size';

다만 검색 시스템은 데이터의 양, 검색 방식, 인덱스 구성에 따라 성능 차이가 발생할 수 있기 때문에 실제 운영 환경에서는 반드시 테스트하는 것이 좋습니다.

결국 검색 기능에서 중요한 것은 단순히 검색이 되는 것만이 아닙니다.

사용자가 입력한 검색어를 얼마나 자연스럽게 찾아주느냐, 그리고 그 검색을 얼마나 빠르게 처리하느냐가 핵심입니다.

MariaDB에서 한글 검색을 구축하고 있다면 ngram_token_size 설정도 한 번쯤 확인해볼 만한 부분입니다.