AWS CloudSearch를 활용한 검색엔진 구축하기

Build Search Engine Using AWS CloudSearch

Elasticsearch는 검색 엔진 구축에 주로 사용되는 강력한 도구지만, 그만큼 구현의 복잡성도 따릅니다. 반면에 Amazon Web Services의 CloudSearch와 OpenSearch는 관리형 검색 서비스로, 웹사이트나 애플리케이션에 검색 엔진을 손쉽게 통합할 수 있도록 설계되었습니다.

이번 포스팅에서는 구현이 가장 직관적이며 간편한 AWS CloudSearch를 이용하여 서비스에 검색 엔진을 구축하는 과정에 대해서 살펴봅니다.

Setting Up AWS CloudSearch Domain

CloudSearch 도메인(Domain)이란 CloudSearch에서 데이터와 관련 설정을 저장하는 색인 항목의 집합을 의미합니다. RDBMS (관계형 데이터베이스)의 테이블 개념과 유사하며, 도메인은 검색 요청을 받아 해당 도메인의 데이터 중에서 결과를 찾아 반환합니다. 한 개의 도메인에서는 한 개의 검색 색인만을 유지할 수 있으며, 이 색인은 해당 도메인에 대한 모든 검색 요청에서 문서를 찾는 데 사용됩니다.

Creating a CloudSearch Domain

CloudSearch 도메인을 생성하면 애플리케이션이 검색 요청을 보내고 결과를 받을 수 있는 엔드포인트가 할당됩니다. 각 도메인은 고유한 도메인 이름을 가지며, 이를 통해 해당 도메인에 접근할 수 있습니다.

먼저, Amazon Web Services에 로그인하고, CloudSearch 서비스 콘솔로 이동해야 합니다. 콘솔 메인 화면 우측에 위치한 create domain 버튼을 클릭하면 CloudSearch 인스턴스 생성 과정이 시작되며, 이는 총 다섯 단계를 거쳐 진행됩니다.

Step 1 Specify details

인스턴스의 스펙 및 스케일링 옵션을 설정합니다.

• Domain name: 해당 인스턴스를 특정할 수 있는 고유한 값
• Engine type: CloudSearch (2013 API)
• Desired instance type & Recommendations
  • serach.small: 1GB 이하 또는 1KB 문서 100만건 이하
  • serach.large: 1GB ~ 8GB
  • serach.xlarge: 8GB ~16GB
  • serach.2xlarge: 16GB ~ 32GB, 32GB 이상의 데이터를 업로드 할 경우 데이터셋을 수용할 수 있도록 원하는 파티션 수를 늘려야 합니다. 각 파티션은 최대 32GB의 데이터를 담을 수 있습니다.
• Desired replication count: Scaling-out 인스턴스 개수

Step 2 Configure index

검색에 활용할 인덱싱 필드를 구성합니다. 다양한 방법을 통해 인덱싱 필드를 설정할 수 있으며, 여기서는 CloudSearch 문서 형식인 SDF (Search Data Format)에 부합하는 JSON 파일을 업로드하여 인덱싱 필드를 구성합니다. 참고로, CloudSearch 문서(Document)란 하나의 데이터 단위이며, RDBMS 테이블의 레코드와 유사한 개념입니다.

SDF (Search Data Format)

• type
  • 문서의 업로드 및 삭제를 구분하는 타입으로 필수값입니다.
  • add: 새로운 문서를 추가하거나 기존에 동일한 id가 존재하는 경우 해당 문서를 업데이트합니다.
  • delete: 지정한id에 해당하는 문서를 삭제합니다.
• id
  • RDBMS의 테이블 기본 키(Primary Key)와 같이 각 문서의 고유 ID로 필수값입니다.
  • 영어 소문자, 숫자, 언더바, 최대 24자리까지 허용합니다.
• version: 문서의 버전이며 필수값은 아닙니다.
• lang: 문서의 언어(영어는 en, 한국어는 ko)를 나타내며 필수는 아닙니다.
• fields
  • 필드는 검색을 수행할 때 사용되는 데이터의 단위이며, RDBMS 테이블의 컬럼과 유사합니다.
  • 문서는 최소 하나 이상의 필드가 구성되어야 합니다.
  • 필드명은 영문 소문자, 언더바, 숫자, 최대 64자리까지 허용합니다.
  • 필드 자료형은 JSON 기본 타입을 따르며, 날짜는 UTC 형식만 허용합니다.

아래 예시를 참고하여 로컬 머신에 JSON 파일을 생성합니다.

[
  {
    "type": "add",
    "id": "1",
    "fields": {
      "id": 1,
      "title": "All-New Design",
      "content": "We've completely refreshed our blog. All-New Design. Not just how it looks! We moved away from a static website and built a private api server."
    }
  }
]

이렇게 생성한 JSON 파일을 업로드하면, 파일 검증이 시작되고 통과하는 경우 ✅ 표시가 활성화 됩니다. Next 버튼을 클릭하면 필드 인덱싱 처리가 시작되고 다음 단계로 이동합니다.

Step 3 Edit index

업로드한 JSON 파일의 인덱싱 분석이 성공적으로 통과한다면 아래와 같은 인덱싱 필드 설정 화면으로 이동합니다. 분석 결과에 따라 자동으로 설정된 값을 직접 정정할 수 있습니다. 물론, 인스턴스 생성 후에도 변경이 가능합니다. 인덱싱 필드 구성은 DataGrip과 같은 GUI 툴에서 테이블과 컬럼을 구성하는 방식과 유사합니다.

Step 4 Setup access policies

인덱싱 필드 구성까지 마무리 되었다면 CloudSearch 보안 정책을 설정합니다. 외부에서 HTTP 엔드포인트를 통해 접근하는 것을 허용하기 위해서는 적절한 보안 정책을 설정하는 것이 필요합니다. 이 예시에서는 프로세스의 이해를 목표로 하기 때문에, 모든 사용자가 검색에 접근 가능한 상태로 설정을 진행하도록 하겠습니다.

Step 5 Review and create

모든 CloudSearch 구성 작업을 완료하였다면, 마지막으로 이를 최종적으로 검토합니다. 확인이 끝난 후에는 인스턴스 생성 버튼을 클릭하여 작업을 마무리합니다.

CloudSearch 인스턴스가 완전히 구성되는 데는 몇 분 정도의 시간이 필요할 수 있습니다.

Uploading Data to CloudSearch Domain

이제 AWS CloudSearch 도메인을 성공적으로 생성했으니, 다음 단계는 실제 데이터를 CloudSearch 도메인에 업로드하는 것입니다. 이 과정을 통해 우리는 검색 엔진의 기능을 본격적으로 테스트해 볼 수 있습니다.

Step 1 Document source

업로드하려는 데이터는 AWS CloudSearch가 파싱할 수 있는 형식(JSON, XML, CSV 등)과 스펙(SDF)을 만족시켜야 합니다. 인스턴스 생성 과정에서 설정한 인덱싱 필드에 맞추어 JSON 형식으로 데이터를 준비하면 됩니다. 즉, 이전에 인스턴스를 생성하는 동안 인덱싱 구성을 위해 사용한 JSON 파일과 동일한 형식으로 데이터를 변환해주면 적합합니다.

이렇게 적절한 형식으로 데이터를 가공하고 준비하는 과정이 중요한데, 이것이 CloudSearch가 우리의 데이터를 올바르게 인덱싱하고 쿼리할 수 있는 근간이 되기 때문입니다.

[
  {
    "type": "add",
    "id": "21",
    "fields": {
      "id": 21,
      "title": "Springdoc 적용하기",
      "content": "스웨거(Swagger)는 API 문서 자동화 및 실제 테스트 요청을 보낼 수 있는 HTTP Client 툴을 제공합니다. Spring Framework에 최적화된 SpringDoc 라이브러리를 적용하여 REST API 문서를 작성하는 방법에 대해 살펴봅니다."
    }
  },
  {
    "type": "add",
    "id": "3",
    "fields": {
      "id": 3,
      "title": "Spring Boot 애플리케이션 터미널에서 프로파일 선택하여 실행하기",
      "content": "Spring Boot 프로젝트 또는 Jar 파일을 터미널에서 프로파일을 지정하여 실행하는 방법에 대해 알아봅니다."
    }
  },
  {
    "type": "add",
    "id": "2",
    "fields": {
      "id": 2,
      "title": "Jenkins CI/CD Pipeline 구축하기 01. AWS EC2에 Jenkins 서버 구축하기",
      "content": "We've completely refreshed our blog. All-New Design. Not just how it looks! We moved away from a static website and built a private api server."
    }
  },
  {
    "type": "add",
    "id": "1",
    "fields": {
      "id": 1,
      "title": "All-New Design",
      "content": "We've completely refreshed our blog. All-New Design. Not just how it looks! We moved away from a static website and built a private api server."
    }
  }
]

하나의 배치 파일의 최대 허용 크기는 5MB입니다. 파일 크기가 5MB 이하라 하더라도, 배열의 크기가 너무 큰 경우 데이터 파싱에 실패할 수 있습니다. 그래서 배열의 크기를 대략 최대 3,000~4,000 사이로 유지하는 것이 좋습니다. 또한, 10초 간격으로 문서 배치를 하나씩 업로드 할 수 있습니다. CloudSearch 제한사항은 CloudSearch Limitations에서 확인할 수 있습니다.

데이터를 변환하여 업로드 할 JSON 파일이 준비 되었다면, CloudSearch 콘솔로 다시 돌아가서 Upload documents 버튼을 눌러 Documents 업로드 프로세스를 시작합니다.

인덱싱 필드를 구성할 떄와 같이 JSON 파일을 업로드 하고, Next 버튼을 클릭히여 데이터 파싱을 진행합니다.

Step 2 Review and upload

데이터 파싱에 성공하면 포함된 Documents 수와 필드에 대한 정보가 화면에 출력됩니다. 데이터를 업로드 하기 전 최종적으로 검토한 후 Upload documents 버튼을 클릭하여 작업을 마무리합니다.

Step 3 Upload summary

업로드되는 문서들의 처리 속도는 파일의 크기, 인덱싱 필드의 개수 등 여러 요인에 의해 영향을 받을 수 있습니다. 업로드 과정이 성공적으로 완료되었다면, 그 결과에 대한 요약된 정보를 보여주는 화면으로 전환됩니다.

다시 CloudSearch 콘솔로 돌아오면, Searchable documents 값이 업로드 한 Documents 수에 맞게 증가한 것을 확인할 수 있습니다. 데이터가 많은 경우, 갱신되는 데에는 약간의 시간이 소요될 수 있습니다.

Searching Tests with AWS Console

여기까지 AWS CloudSearch의 설정을 완료했습니다. 셋업된 검색 엔진이 제대로 동작하는지 확인하기 위한 단계로서, 실제로 검색 테스트를 진행할 차례입니다. 해당 테스트 과정을 통해 CloudSearch 엔진의 세부 동작 방식과, 어떤 쿼리가 어떤 결과를 가져오는지에 대한 명확한 이해를 갖게 될 것입니다.

CloudSearch 콘솔의 우측 상단의 Run a test search 버튼을 클릭하여 검색 테스트 페이지로 이동합니다.

테스트 과정에서는 다양한 경우의 수를 고려하여 검색어를 입력해볼 수 있습니다. 예를 들어, 데이터에 포함되어 있어야 하는 키워드로 검색을 수행해보거나, 데이터에 포함되지 않은 키워드로 검색을 수행하여 검색 엔진의 정확성을 확인하는 것이 좋습니다. 또한, 유사한 키워드나 오타가 포함된 키워드로 검색해보며, 검색 엔진의 오류 허용성과 안정성을 체크해볼 수 있습니다.

이러한 다양한 테스트를 통해 검색 엔진의 정확성 및 신뢰성을 이해할 수 있습니다. 또한 이 과정에서 나타나는 어떠한 이상 증상이나 예상치 못한 결과들은 검색 엔진을 개선하고 최적화하는데 아주 중요한 힌트가 될 수 있습니다.

Searching Tests with Search API

추가적으로, CloudSearch 콘솔의 Search endpoint를 통하여 검색 API의 정상 작동 여부도 확인합니다. 검색 API의 기본 문법은 다음과 같습니다.

$ curl https://{endpoint}/2013-01-01/search?q={search_string}

• {endpoint}: CloudSearch 도메인의 엔드포인트입니다. 이 부분은 우리가 생성한 CloudSearch 도메인의 실제 엔드포인트 값으로 대체되어야 합니다.
• /2013-01-01: 이 부분은 CloudSearch API의 버전을 나타냅니다. 여기서는 2013년 1월 1일 버전을 사용하고 있다는 것을 나타냅니다.
• /search?q=: 검색 쿼리를 시작하는 부분입니다. q= 이후에 검색하고자 하는 문자열을 지정합니다.
• {search_string} : 실제 검색어 입니다. 이 부분에 수행하고자 하는 검색 쿼리에 대응하는 문자열을 입력하면 됩니다.

API Client 도구를 활용하여 실제로 CloudSearch 검색 API에 요청을 보내고 그 결과를 확인해봅니다.

GET /2013-01-01/search?q=aws HTTP/1.1
Host: search-catsriding-xxx.ap-northeast-2.cloudsearch.amazonaws.com
Connection: close
User-Agent: RapidAPI/4.2.0 (Macintosh; OS X/14.1.2) GCDHTTPRequest

이것은 기본적인 검색 쿼리의 사용 예제일 뿐입니다. CloudSearch는 다양한 검색 쿼리와 옵션을 지원합니다. 이에 대한 자세한 정보는 CloudSearch 검색 API 문서를 참조하면 좀 더 다양하고 풍부한 검색 기능을 활용할 수 있습니다.

Integrating AWS Java SDK with CloudSearch

CloudSearch를 애플리케이션과 통합하는 방법으로는 주로 AWS SDK 활용 또는 CloudSearch Domain Endpoint에 대한 HTTP 요청을 사용합니다.

Java & Spring Boot 기반의 프로젝트에 주로 사용되는 AWS SDK는 Spring Cloud AWS 라이브러리와 AWS Java SDK가 있습니다. Spring Cloud AWS Project는 Spring 프레임워크를 이용하는 개발자들에게 추상화된 형태의 클라우드 서비스를 제공하긴 하지만, 아직까지는 AWS의 모든 서비스와 기능을 지원하지 않습니다. 이런 경우 AWS Java SDK를 사용하여 필요한 AWS 기능에 직접적으로 접근할 수 있습니다.

이 섹션에서는 AWS Java SDK를 사용하여 Spring Boot 프로젝트에서 CloudSearch와 통합하는 과정을 살펴봅니다.

Configuring AWS Java SDK

AWS Java SDK를 이용하기 위해서는 먼저 프로젝트에 SDK를 추가해야 합니다. 이를 위해 build.gradle 파일을 열고 아래와 같이 의존성을 추가합니다.

dependencies {
    implementation 'com.amazonaws:aws-java-sdk:1.12.619'
}

AWS Java SDK가 추가되면, AmazonCloudSearchDomain 인스턴스를 구성해야 합니다. 이는 CloudSearch 검색 및 문서 업로드 기능을 사용하기 위한 클라이언트 역할을 하는 객체로, AWS 인증 정보 및 CloudSearch Domain Endpoint 정보를 이용하여 생성됩니다.

public AmazonCloudSearchDomain createCloudSearchClient() {
    BasicAWSCredentials credentials = new BasicAWSCredentials("accessKey", "secretKey");
    AWSStaticCredentialsProvider credentialsProvider = AWSStaticCredentialsProvider(credentials);
    EndpointConfiguration endpointConfiguration = new EndpointConfiguration("searchEndpoint", AP_NORTHEAST_2.name());

    return AmazonCloudSearchDomainClientBuilder.standard()
            .withCredentials(credentialsProvider)
            .withEndpointConfiguration(endpointConfiguration)
            .build();
}

• 인증 정보 생성: BasicAWSCredentials는 AWS에 접근하기 위한 본인 인증 정보를 생성하는데 사용됩니다. 이 정보는 각각 AWS 계정의 Access Key와 Secret Key에 해당합니다. 보안을 위해 IAM 계정 활용을 권장합니다.
• 인증 정보 제공: 생성된 인증 정보는 AmazonCloudSearchDomain 객체가 사용 할 수 있도록 AWSStaticCredentialsProvider를 통해 제공됩니다. 이 과정을 통해 AmazonCloudSearchDomain과 AWS 간의 안전한 연결이 구성됩니다.
• CloudSearch Domain 클라이언트 생성: 마지막으로, Client Builder를 사용하여 인증 정보와 엔드포인트 설정을 토대로 AmazonCloudSearchDomain 객체를 생성합니다. 이 객체를 통해서 검색 및 문서 업로드 기능을 구현할 수 있게 됩니다.

Implementing Search API

검색 API는 사용자로부터의 검색어를 입력으로 받아 해당하는 데이터를 조회한 다음 그 결과를 클라이언트에게 반환하는 핵심 기능을 수행합니다.

AWS Java SDK에서 제공하는 주요 객체들과 함수를 통해 이러한 검색 API의 핵심인 CloudSearch Domain으로의 검색 쿼리 전달과, 그로부터의 응답을 처리하는 과정을 알아봅니다.

public void searchDocuments(String query) {
    AmazonCloudSearchDomain cloudSearchClient = createCloudSearchClient();
    
    SearchRequest searchRequest = new SearchRequest().withQuery(query);
    SearchResult searchResult = cloudSearchClient.search(searchRequest);

    Hits hits = searchResult.getHits();
    for (Hit hit : hits.getHit()) {
        System.out.println("Document ID: " + hit.getId());
        System.out.println("Document Fields: " + hit.getFields());
    }
}

• createCloudSearchClient(): 위에서 정의한 함수를 호출하여 CloudSearch 클라이언트 객체를 생성합니다.
• SearchRequest: CloudSearch 서비스와 통신하기 위한 검색 요청을 정의하는데 사용됩니다.
  • withQueryParser(): 검색 쿼리의 Parser 유형을 설정할 수 있습니다. 선택할 수 있는 값으로는 simple(기본값), structured, lucene, dismax가 있습니다. 이들은 각각 다른 유형의 쿼리 구문을 지원합니다. 특히 structured를 사용하면 CloudSearch 구조화된 쿼리 구문을 사용할 수 있어, 특정 필드를 대상으로 검색을 하거나 논리적인 조건을 적용하는 등 복잡한 검색 요청을 보낼 수 있습니다.
  • withQuery(): 검색할 쿼리 문자열을 설정합니다. 이 문자열은 설정한 QueryParser에 적합한 형식으로 작성되어야 합니다.
  • withFilterQuery(): 검색에 적용할 필터 쿼리를 설정합니다. 이 필터를 사용하면 특정 조건을 만족하는 항목만 검색 결과로 반환됩니다.
  • withFacet(): 검색 결과로 반환할 퍼싯(Facet)를 설정합니다. 퍼싯은 검색 결과의 세부 범주를 나타냅니다.
  • withSort(): 검색 결과의 정렬 순서를 설정합니다. 여러 필드를 기준으로 정렬할 수 있으며, 각 필드는 오름차순 또는 내림차순으로 정렬될 수 있습니다.
  • withSize(): 한 번의 검색 요청으로 반환받을 문서의 최대 개수를 설정합니다. 이 값을 사용하면 대량의 데이터 중에서 일부만 빠르게 샘플링할 수 있습니다.
  • withStart(): 검색 결과에서 반환할 첫 번째 문서의 위치를 설정합니다. 이 값을 사용하면 검색 결과의 특정 부분만을 빠르게 탐색할 수 있습니다.
  • withHighlight(): 검색어와 매칭되는 텍스트를 하이라이트해서 표시합니다. 이는 검색어가 어떤 문맥에서 사용되었는지 보여주는데 유용합니다.
  • withReturn(): 이 메소드는 검색 결과로 반환할 특정 필드들을 설정하는데 사용됩니다. 인수로는 문서의 필드 이름들을 문자열 형태로 입력받으며, 여러 개의 필드 이름을 쉼표로 구분하여 입력할 수 있습니다. 이를 통해 검색 결과에서 필요한 정보만 선택적으로 받아올 수 있습니다.
  • withPartial(): 부분 검색 결과를 허용할지 설정합니다. 만약 일부 Shard에서만 검색 결과를 받는 것을 허용하려면 이 값을 true로 설정합니다.
  • withExpr(): 검색 결과의 순위를 결정하는 데 사용되는 계산식을 설정합니다. 이 값을 사용하면 복잡한 순위 결정 로직을 적용할 수 있습니다.
• SearchResult: CloudSearch의 검색 요청에 대한 응답을 나타내며, 검색 결과와 관련한 다양한 정보를 포함하고 있습니다.
  • getStatus(): 검색 요청의 상태 정보를 반환합니다. 이 메소드를 통해 검색이 얼마나 걸렸는지(ms 단위), 요청이 성공했는지 등을 알 수 있습니다.
  • getHits(): 검색 결과를 반환합니다. 이 메소드를 통해 검색결과로 돌아온 Hit 객체의 리스트를 가져올 수 있습니다. 어떤 문서가 검색되었는지, 각 문서의 필드는 어떤 값을 가지고 있는지 등을 확인할 수 있습니다.
  • getFacets(): 검색 결과의 Facet 정보를 반환합니다. 이 메소드를 통해 각 퍼싯에서 얼마나 많은 문서가 검색되었는지, Facet 별로 어떤 범위의 값들이 있는지 등을 확인할 수 있습니다.
  • getFieldStats(): 요청한 필드에 대한 통계 정보를 제공합니다. 이것은 숫자 필드나 날짜 필드에서만 사용할 수 있으며, 이들 필드에 대한 최대값, 최소값, 평균값, 합계, 문서 수 등을 확인할 수 있습니다.
  • getSuggest(): 제안된 쿼리를 반환합니다. 이 메소드를 사용하면 사용자의 원래 쿼리 문자열에 기반한 대체 쿼리 문자열이나 보완 쿼리 문자열을 제공받을 수 있습니다. 이는 검색 쿼리의 오타를 자동으로 고치거나, 검색 쿼리를 확장하는 데 사용할 수 있습니다.

구조화된 쿼리를 작성하여 CloudSearch로 전송하고 그 결과를 받아 콘솔에 출력하는 함수를 구현해보겠습니다. 이 흐름을 이해하고 응용한다면 검색 API를 구현할 수 있을 것입니다.

AmazonCloudSearchDomain cloudSearchClient = createCloudSearchClient();

SearchRequest searchRequest = new SearchRequest()
        .withQuery("(and title:'cats' author:'Jynn')") 
        .withQueryParser(QueryParser.Structured);

SearchResult searchResult = client.search(searchRequest);

Hits hits = searchResult.getHits();

System.out.println("Total documents retrieved: " + hits.getFound());
for (Hit hit : hits.getHit()) {
    System.out.println("==== Document ====");
    System.out.println("Document ID: " + hit.getId());
    System.out.println("Fields: ");
    for (Map.Entry<String, List<String>> field : hit.getFields().entrySet()) {
        System.out.println(" - " + field.getKey() + ": " + String.join(", ", field.getValue()));
    }
}

위 코드를 실행했을 때 예상되는 출력 결과는 아래와 같습니다.

Total documents retrieved: 2
==== Document ====
Document ID: ABC123
Fields:
 - title: catslearning
 - author: Jynn
==== Document ====
Document ID: XYZ456
Fields:
 - title: catsriding
 - author: Jynn

이를 토대로 실제 애플리케이션의 검색 API를 구현해본다면, 다음과 같은 프로세스를 생각해볼 수 있습니다. (요청 검증 및 예외 처리 등의 과정은 생략하였습니다.)

1. 요청 파라미터를 통해 필요한 검색어와 필터 조건 등을 전달 받습니다.
2. SearchRequest 인스턴스를 생성하여 쿼리를 완성합니다.
3. CloudSearch로 쿼리를 전송하고 SearchResult 객체로 결과를 바인딩합니다.
4. SearchResult에 담긴 데이터를 토대로 응답 페이로드를 작성하여 클라이언트에게 반환합니다.

Implementing Documents Upload API

AWS CloudSearch에 데이터를 색인하려면, 먼저 상호 작용할 수 있는 형태의 문서를 업로드해야 합니다. 이 API는 사용자가 원하는 데이터를 받아서 CloudSearch가 이해할 수 있는 형태로 변환하고, 이를 CloudSearch 서비스에 업로드하는 기능을 가집니다. 이 과정에서는 데이터를 받는 방법, 데이터를 CloudSearch가 이해할 수 있는 형식으로 변환하는 방법, 그리고 변환된 데이터를 업로드하는 방법 등에 대해 설명할 예정입니다. 이를 통해 데이터가 실시간으로 CloudSearch에 색인될 수 있도록 하여, 사용자가 항상 최신의 검색 결과를 얻을 수 있도록 합니다.