Algolia API 검색

Algolia가 제공하는 검색 API는 인덱스에 저장해 둔 데이터를 실시간으로 검색해 주는 핵심 기능이에요. 애플리케이션에서 검색창을 만들 때 이 API가 가장 먼저 호출되는 지점이라고 보면 돼요. 한 번의 요청으로 인덱스 하나를 검색하고, 그 결과를 hits 형태로 받아 화면에 바로 그려낼 수 있어요. 오늘은 이 검색 엔드포인트 하나를 깊게 파볼게요.

검색 엔드포인트는 POST /1/indexes/{indexName}/query로, 이 메서드 하나로 최대 1,000개의 검색 결과(hit)를 가져올 수 있어요. 더 많은 결과가 필요하면 browse 연산을 쓰거나 인덱스 설정의 paginatedLimitedTo를 늘려야 해요. 검색에 필요한 자격은 search ACL이에요. 코드 대신 개념부터 제대로 잡고 가는 게 좋아요.

출처: 문서

본문

검색 엔드포인트

단일 인덱스를 검색하고 일치하는 검색 결과를 hits로 반환해요. HTTP 메서드와 기본 URL은 아래와 같아요.

POST https://{appId}.algolia.net/1/indexes/{indexName}/query

기본 URL 외에도 재시도 전략을 위해 아래 호스트를 사용할 수 있어요.

https://{appId}.algolia.net
https://{appId}-dsn.algolia.net
https://{appId}-1.algolianet.com
https://{appId}-2.algolianet.com
https://{appId}-3.algolianet.com

모든 요청은 HTTPS를 사용해야 해요. 인증은 요청 헤더로 처리해요.

헤더	설명
`x-algolia-application-id`	Algolia 애플리케이션 ID
`x-algolia-api-key`	필요한 권한을 가진 API 키 (ACL: `search`)

경로 파라미터

파라미터	타입	설명
`indexName`	string (required)	검색을 수행할 인덱스의 이름

검색 파라미터

요청 본문(body)은 검색 파라미터를 URL-인코딩된 쿼리 문자열로 보내거나(예: params 필드) 객체로 보낼 수 있어요. 대표적인 파라미터를 정리하면 다음과 같아요.

파라미터	타입	기본값	설명
`query`	string	`""`	인덱스에서 검색할 텍스트. 빈 문자열이면 `customRanking` 기준으로 정렬된 전체 레코드를 반환해요. 쿼리 문자열은 최대 512바이트이며, 여러 단어는 전부 일치해야 해요.
`hitsPerPage`	integer	`20`	페이지당 hit 수. 범위는 1~1000.
`filters`	string	`""`	숫자·패싯·태그 필터로 검색 결과를 좁히는 필터 표현식. `AND`·`OR`·`NOT`과 괄호로 조합할 수 있어요.
`attributesToRetrieve`	array of string	전체 속성	반환되는 hit에 포함할 속성 목록. `*`는 전체, `-속성명`은 제외를 의미해요. `objectID`는 명시하지 않아도 항상 조회돼요.

`filters` 문법 핵심

패싯 필터  : facet:value            예) category:Book
숫자 비교  : facet <op> value       예) price > 12.99  (<, <=, =, !=, >=, >)
숫자 범위  : facet:low TO high      예) price:5.99 TO 100
태그 필터  : _tags:value            예) published

`attributesToRetrieve` 사용법

속성 이름은 대소문자를 구분해요.
*는 모든 속성을 포함하고, -attributeName(*와 함께 사용)은 특정 속성을 제외할 수 있어요.
중첩 속성도 지원돼요. author.name을 요청하면 {"author": {"name": "Agatha Christie"}} 형태로 반환돼요.

응답 구조

성공 시 200 응답으로 아래와 같은 JSON이 와요. hits는 인덱스에서 검색 조건에 맞는 레코드에 하이라이팅 등의 추가 속성이 붙은 배열이고, nbHits는 전체 검색 결과 수예요.

{
  "hits": [
    {
      "objectID": "test-record-123",
      "_highlightResult": {},
      "_snippetResult": {}
    }
  ],
  "nbHits": 20,
  "nbPages": 1,
  "page": 0,
  "hitsPerPage": 20,
  "query": "",
  "processingTimeMS": 20,
  "params": "query=a&hitsPerPage=20"
}

필드	타입	설명
`hits`	object[] (required)	검색 조건에 일치하는 레코드 배열. 하이라이팅용 추가 속성이 함께 포함돼요.
`nbHits`	integer	검색 결과(hit)의 총 개수
`hitsPerPage`	integer	페이지당 hit 수 (기본값 20)
`page`	integer	검색 결과의 페이지 번호 (기본값 0)
`nbPages`	integer	결과의 총 페이지 수
`query`	string	검색 쿼리
`processingTimeMS`	integer	서버가 요청을 처리하는 데 걸린 시간(ms)

hits의 각 레코드에는 보통 objectID와 함께 _highlightResult, _rankingInfo, _snippetResult 같은 메타데이터가 포함돼요. objectID는 항상 존재하므로 검색 결과를 클릭했을 때 어떤 레코드인지 식별하는 키로 쓰면 돼요.

사용 예시

cURL로 실제 요청을 보내는 모습이에요. 검색 파라미터를 params 문자열로 넘기고, 인증 헤더 두 개를 꼭 챙겨야 해요.

curl --request POST \
  --url https://algolia_application_id.algolia.net/1/indexes/ALGOLIA_INDEX_NAME/query \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-algolia-api-key: ALGOLIA_API_KEY' \
  --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' \
  --data '{
  "params": "hitsPerPage=2&getRankingInfo=1"
}'

검색 파라미터를 객체로 보내고 싶다면 query, hitsPerPage, filters, attributesToRetrieve 필드를 바로 넣으면 돼요.

{
  "query": "phone",
  "hitsPerPage": 10,
  "filters": "category:Book AND price > 12.99",
  "attributesToRetrieve": ["title", "author", "price"]
}

더 알아보기

공식 문서

Algolia API 검색