데이터 객체 동시 실행 제어를 위해 ETag 사용

벡터 검색 2.0은 최적의 동시 실행 제어 (OCC)를 사용하여 특정 데이터 객체 버전을 나타내는 불투명 식별자인 ETag (항목 태그)를 지원합니다.

실시간 API 업데이트 및 일괄 가져오기 작업과 같이 여러 프로세스가 동일한 데이터 세트에서 동시에 작동하는 경우 서로의 변경사항을 덮어쓸 위험이 있습니다 (마지막 쓰기 우선 시나리오). ETag를 사용하면 데이터 무결성을 보장하고 마지막으로 읽은 후 다른 프로세스에서 레코드를 수정하지 않았는지 확인할 수 있습니다.

ETag 작동 방식

  1. 읽기: 데이터 객체를 만들거나 가져오면 서버는 데이터 객체의 정확한 버전을 나타내는 ETag 문자열을 반환합니다.

  2. 수정: 데이터 객체를 로컬에서 변경합니다.

  3. 쓰기: 원래 수신한 ETag를 포함하여 업데이트 또는 삭제 요청을 벡터 검색 2.0으로 다시 보냅니다.

  4. 확인: 서버는 제공된 ETag가 데이터베이스에 저장된 현재 ETag 와 일치하는지 확인합니다.

    • **일치하는 경우** 작업이 성공하고 서버는 업데이트된 데이터 객체의 새 ETag 를 반환합니다.
    • 일치하지 않는 경우 작업이 차단되고 서버는 ABORTED 오류 (HTTP 409 Conflict)를 반환합니다.

ETag 가져오기

동시 실행 제어를 위해 ETag를 사용하려면 먼저 시스템에서 최신 버전을 가져와야 합니다.

ETag는 다음과 같은 방법으로 가져올 수 있습니다.

  • 실시간 API 응답: DataObjectService에서 읽기 또는 쓰기 메서드 (GetDataObject, ListDataObjects, CreateDataObject 또는 UpdateDataObject 등)를 호출하면 반환된 데이터 객체 리소스에 현재 ETag가 포함됩니다.

  • API 출력 가져오기: ImportDataObjects를 호출할 때 GcsImportConfig 필드 output-uri에서 Cloud Storage의 URI 접두어를 지정할 수 있습니다. 가져오기 작업이 성공하면 가져온 데이터 객체의 ID와 ETag가 포함된 각 줄이 있는 JSONL 파일이 생성됩니다. 형식은 다음과 같습니다.

    { "id": "movie-789", "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d"}

  • API 내보내기 (ExportDataObjects) - 벡터 검색 2.0 에서 Cloud Storage로 데이터를 내보낼 때 생성되는 정규 JSONL 데이터 파일에는 내보낸 모든 데이터 객체의 ETag가 포함됩니다.

데이터 객체 만들기

CreateDataObject 또는 BatchCreateDataObjects를 호출할 때 데이터 객체가 아직 존재하지 않으므로 요청에 제공하는 ETag는 무시됩니다.

만들기 요청이 성공하면 서버는 새로 생성된 ETag를 반환된 데이터 객체 리소스에 포함합니다.

데이터 객체 업데이트

UpdateDataObject 또는 BatchUpdateDataObjects를 사용하여 기존 레코드를 안전하게 업데이트하려면 요청의 데이터 객체 리소스 내에 ETag를 직접 포함하세요.

{
  "name": "projects/my-project/locations/us-central1/collections/my-collection/dataObjects/movie-789",
  "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d",
  "data": {
    "genre": ["science-fiction", "thriller", "action"]
  }
}

데이터 객체 삭제

DeleteDataObject 및 BatchDeleteDataObjects 메서드는 전체 데이터 객체 리소스를 페이로드로 사용하지 않으므로 ETag는 DeleteDataObjectRequest의 최상위 필드로 제공되어야 합니다.

{
  "name": "projects/my-project/locations/us-central1/collections/my-collection/dataObjects/movie-789",
  "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d"
}

일괄 수집 (ImportDataObjects)에 ETag 사용

ImportDataObjects API를 사용하면 비동기식으로 실행되며 실시간 업데이트와 충돌할 수 있습니다. JSONL

벡터 검색은 레코드별로 충돌 해결 모드를 자동으로 감지합니다.

  • ETag (OCC) 포함: ETag가 제공되었지만 서버의 현재 버전과 일치하지 않으면 특정 레코드를 가져오지 못합니다. 그러면 지정된 오류 URI에 실패가 로깅되지만 나머지 가져오기 작업은 계속됩니다.

  • ETag 없음: ETag가 생략되면 레코드가 수집되어 기존 데이터를 재정의합니다. 이렇게 하면 동시 실행 제어가 필요하지 않을 때 처리량이 극대화됩니다.

JSONL 형식

다음 예와 같이 가져오기 파일의 JSON 객체 루트 수준에 ETag를 포함합니다.

{ "id": "movie-789", "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d", "data":{ "genre": ["science-fiction", "thriller"] }, "vectors": { ... } }

동시 실행 오류 처리

작업이 ETag 확인에 실패하면 API는 ABORTED (HTTP 409 Conflict) 오류 코드를 반환합니다.

권장되는 오류 처리:

ABORTED 오류가 수신되면 애플리케이션은 다음 작업을 실행해야 합니다.

  1. 서버에서 데이터 객체의 최신 버전을 다시 가져옵니다.

  2. 새로 가져온 데이터와 의도한 업데이트 간의 비즈니스 로직 충돌을 해결합니다.

  3. 새 ETag를 사용하여 작업을 재시도합니다.

다음 단계