Algolia API 객체 저장

객체를 한 번에 여럿 저장하는 일, Algolia에선 이렇게 쉽게 처리할 수 있어요. saveObjects(또는 save_objects)는 여러 레코드(객체)를 한 인덱스에 추가하는 헬퍼 메서드인데요, 내부적으로 "한 인덱스에 대한 배치(batch) 작업" API를 addObject 액션으로 호출해요. 레코드가 1,000개 단위로 자동 분할되어 요청되기 때문에, 데이터가 커도 한 방의 호출로 안전하게 밀어 넣을 수 있어요. 우리 강의처럼 "이 데이터 묶음을 통째로 넣고 싶다" 할 때 딱 맞는 API라고 보시면 돼요.

한 번 저장한 레코드는 고유 식별자 objectID를 기준으로 관리돼요. 레코드마다 objectID를 직접 지정할 수도 있고, 생략하면 Algolia가 자동으로 만들어 주기도 해요. 인덱스의 레코드 전체를 새 데이터로 바꾸고 싶을 땐 배치의 updateObject 액션(레코드 추가 또는 전체 교체)을 쓰면 되고, 이 작업은 addObject ACL 권한과 인덱싱 속도 제한의 적용을 받는다는 점만 기억해 두면 돼요.

출처: 문서

본문

saveObjects는 한 인덱스에 대한 배치(index batch) 작업 API(POST /1/indexes/{indexName}/batch)를 기반으로 동작해요. 이 헬퍼 메서드는 addObject 액션으로 배치 쓰기 요청을 만들고, 레코드를 1,000개 단위로 자동 분할해 보내요. 이 메서드는 인덱싱 속도 제한의 적용을 받아요.

각 레코드(객체)는 인덱스의 검색 가능한 단위이며, 필드에 objectID를 넣으면 해당 ID로 레코드를 고유하게 식별하고 기록해요. objectID가 없는 레코드는 Algolia가 자동 생성한 objectID로 추가돼요.

클라이언트 라이브러리 기준 사용 예시는 다음과 같아요. 방식만 다를 뿐 모든 언어가 같은 동작을 해요.

const response = await client.saveObjects(
  {
    indexName: 'playlists',
    objects: [
      {
        objectID: '1',
        visibility: 'public',
        name: 'Hot 100 Billboard Charts',
        playlistId: 'd3e8e8f3-0a4f-4b7d-9b6b-7e8f4e8e3a0f',
        createdAt: '1500240452',
      },
    ],
    waitForTasks: false,
    batchSize: 1000,
  },
  {
    headers: { 'X-Algolia-User-ID': '*' },
  },
);

response = client.save_objects(
    index_name="INDEX_NAME",
    objects=[
        {
            "objectID": "1",
            "visibility": "public",
            "name": "Hot 100 Billboard Charts",
            "playlistId": "d3e8e8f3-0a4f-4b7d-9b6b-7e8f4e8e3a0f",
            "createdAt": "1500240452",
        },
    ],
    wait_for_tasks=False,
    batch_size=1000,
    request_options={
        "headers": loads("""{"X-Algolia-User-ID":"*"}"""),
    },
)

saveObjects가 실제로 호출하는 저수준 배치 엔드포인트(POST /1/indexes/{indexName}/batch)는 다음과 같이 addObject 액션과 레코드 본문(body)을 요청으로 받아요.

curl --request POST \
  --url https://algolia_application_id.algolia.net/1/indexes/ALGOLIA_INDEX_NAME/batch \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-algolia-api-key: *** \
  --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' \
  --data '
{
  "requests": [
    {
      "action": "addObject",
      "body": {
        "name": "Betty Jane McCamey",
        "company": "Vita Foods Inc.",
        "email": "[email protected]"
      }
    },
    {
      "action": "addObject",
      "body": {
        "name": "Gayla geimer",
        "company": "Ortman McCain Co.",
        "email": "[email protected]"
      }
    }
  ]
}
'

객체 추가 vs 전체 교체

배치 액션 중에서 이 API와 가장 밀접한 두 액션을 구분해 볼게요.

addObject: 인덱스에 레코드를 추가해요. objectID를 지정하지 않으면 자동 생성된 ID가 부여돼요.
updateObject: 인덱스에 레코드를 추가하거나 교체(replace) 해요. 같은 objectID가 이미 있으면 기존 레코드를 통째로 새 내용으로 덮어써요.

파라미터

indexName (string, 필수): 레코드를 추가할 인덱스의 이름이에요.
objects (records, 필수): 추가할 레코드 목록이에요. 각 레코드는 원하는 필드를 가진 JSON 객체이며, 원하면 objectID를 포함할 수 있어요.
waitForTasks (bool, 기본 false): 모든 배치 요청이 끝날 때까지 기다릴지 여부예요.
batchSize (int, 기본 1000): 한 번의 배치로 처리할 레코드 수예요.

응답

배치 작업은 비동기로 처리되며, 응답으로 objectIDs와 taskID를 돌려줘요. taskID는 인덱싱 작업 상태를 추적하는 데 사용돼요.

{
  "objectIDs": ["...", "..."],
  "taskID": 123456789
}

참고: Algolia의 실제 REST 엔드포인트는 POST /1/indexes/{indexName}/objects가 아니라 한 인덱스 배치 작업인 POST /1/indexes/{indexName}/batch예요. saveObjects는 이 배치 API를 addObject 액션으로 감싼 헬퍼 메서드예요.

Algolia API 객체 저장