프라이머리 키 설계

Meilisearch의 모든 문서는 인덱스 안에서 유일한 식별자, 프라이머리 키를 가져야 해요. 이 값이 곧 Meilisearch가 문서를 식별하고, 업데이트하고, 중복을 걸러내는 기준이 돼요. 그래서 처음 인덱스를 만들 때 어떤 필드를 프라이머리 키로 쓸지 고르는 게 나중에 데이터를 관리하는 방식까지 좌우한답니다. 이 페이지에서는 Meilisearch가 프라이머리 키를 어떻게 자동 감지하는지, 어떤 값이 허용되는지, 그리고 어떤 키를 고르는 게 좋은지 하나씩 짚어볼게요.

출처: Meilisearch 공식 문서 — Design primary keys

본문

Meilisearch가 프라이머리 키를 선택하는 방식

새 인덱스에 문서를 추가하면 Meilisearch가 프라이머리 키를 자동으로 감지하려고 시도해요. id로 끝나는 속성(대소문자 무시)을 찾는데, 정확히 하나만 발견되면 그 속성을 사용하고, 후보가 여러 개이거나 아예 없으면 오류를 반환합니다. 인덱스를 만들 때나 문서를 추가할 때 프라이머리 키를 명시적으로 지정할 수도 있어요.

인덱스를 만들 때 지정하는 예시:

# Set when creating the index
curl \
  -X POST 'MEILISEARCH_URL/indexes' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "uid": "products",
    "primaryKey": "product_id"
  }'

혹은 문서를 추가할 때 primaryKey 쿼리 파라미터로 지정하는 방법도 있어요:

curl \
  -X POST 'MEILISEARCH_URL/indexes/products/documents?primaryKey=product_id' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary @products.json

⚠️ 한 번 설정한 프라이머리 키는 인덱스를 삭제하고 다시 만들지 않는 한 바꿀 수 없어요. 첫 번째 대량 import 전에 신중하게 정하세요.

허용되는 타입

프라이머리 키 값은 정수(integer) 또는 문자열(string) 이어야 해요. 문자열에는 영숫자(a-z, A-Z, 0-9), 하이픈(-), 밑줄(_)이 포함될 수 있답니다.

| 타입 | 예시 | 유효 여부 | | Integer | 42 | Yes | | String | "product-123" | Yes | | String with UUID | "550e8400-e29b-41d4-a716-446655440000" | Yes | | Float | 3.14 | No | | Boolean | true | No | | Null | null | No |

좋은 프라이머리 키 고르기

원천 시스템의 ID 활용

문서가 데이터베이스에서 온다면, 이미 존재하는 유일 식별자를 그대로 쓰는 게 좋아요. 이렇게 하면 Meilisearch를 원천 시스템과 동기화 상태로 유지하기 쉬워집니다.

{
  "product_id": "SKU-12345",
  "title": "Running Shoes",
  "price": 129.99
}

원천 시스템의 ID를 쓰면 같은 ID로 PUT(추가 또는 업데이트) 요청을 보냈을 때 Meilisearch가 변경 사항을 기존 문서에 병합해 줘요.

UUID vs 순차 정수

피해야 할 안티패턴

값이 변하는 필드

URL이나 slug처럼 시간에 따라 변할 수 있는 필드를 프라이머리 키로 쓰면 곤란해요. "ID"가 바뀌면 Meilisearch는 그것을 업데이트가 아니라 새 문서로 취급해버리거든요.

ID 필드가 여러 개일 때 자동 감지에 의존

id, product_id, user_id처럼 문서에 여러 개의 id로 끝나는 필드가 있으면 Meilisearch는 어느 것을 쓸지 자동 감지할 수 없어 오류를 반환해요. 이런 경우에는 반드시 프라이머리 키를 명시적으로 설정하세요.

프라이머리 키 바꾸기

한 번 설정하면 프라이머리 키는 수정할 수 없어요. 바꿔야 한다면 아래 순서로 진행합니다:

현재 인덱스에서 데이터 내보내기
인덱스 삭제
올바른 프라이머리 키로 새 인덱스 생성
데이터 재-import

# Delete the index
curl \
  -X DELETE 'MEILISEARCH_URL/indexes/products' \
  -H 'Authorization: Bearer MEILISEARCH_KEY'

# Recreate with the correct primary key
curl \
  -X POST 'MEILISEARCH_URL/indexes' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "uid": "products",
    "primaryKey": "sku"
  }'

프라이머리 키 설계