포인트
포인트는 Qdrant에서 조작되는 핵심 엔터티입니다. 포인트는 벡터와 선택적으로 페이로드로 구성된 레코드입니다.
벡터 유사성에 따라 그룹화된 포인트를 컬렉션에서 검색할 수 있습니다. 프로세스에 대한 더 자세한 설명은 검색 및 필터 섹션에서 제공됩니다.
이 섹션에서는 벡터를 생성하고 관리하는 방법을 소개합니다.
포인트에 대한 모든 수정 작업은 비동기적이며 두 단계로 나뉩니다. 첫 번째 단계에서 작업은 전방 로그에 기록됩니다.
이 순간에는 기계 전원이 꺼져도 서비스는 데이터를 잃지 않습니다.
팁: 포인트는 Qdrant에서 추상적인 개념으로, MySQL 테이블의 데이터 행으로 생각할 수 있습니다.
결과 대기
API가 &wait=false 매개변수로 호출되거나 명시적으로 지정되지 않으면, 클라이언트는 데이터 수신에 대한 확인 메시지를 수신합니다:
{
"result": {
"operation_id": 123,
"status": "acknowledged"
},
"status": "ok",
"time": 0.000206061
}
이 응답은 데이터의 즉시 검색을 보장하지는 않습니다. 이것은 최종적 일관성의 형태를 사용합니다. 컬렉션을 실제로 업데이트하는 과정에서 시간이 걸릴 수 있습니다. 실제로 이 요청은 최종적으로 실패할 수 있습니다. 많은 양의 벡터를 삽입하는 경우, 파이프라인 작업을 완전히 활용하기 위해 비동기 요청을 사용하는 것을 권장합니다.
API 응답 후 검색에 대한 즉각적인 가용성이 응용 프로그램 로직에서 필요한 경우 ?wait=true 플래그를 사용하세요. 이 경우, API는 작업이 완료된 후에만 결과를 반환합니다:
{
"result": {
"operation_id": 0,
"status": "completed"
},
"status": "ok",
"time": 0.000206061
}
포인트 ID
Qdrant는 포인트의 식별자로 '64비트 부호 없는 정수' 및 'UUID'를 지원합니다.
UUID 문자열 표현의 예는 다음과 같습니다:
- 간단한 표현:
936DA01F9ABD4d9d80C702AF85C822A8 - 하이픈이 있는 표현:
550e8400-e29b-41d4-a716-446655440000 - URN:
urn:uuid:F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4
이는 각 요청에서 숫자 ID 대신 UUID 문자열을 사용할 수 있음을 의미합니다. 예를 들어:
PUT /collections/{collection_name}/points
{
"points": [
{
"id": "5c56c793-69f3-4fbf-87e6-c4bf54c28c26",
"payload": {"color": "red"},
"vector": [0.9, 0.1, 0.1]
}
]
}
그리고
PUT /collections/{collection_name}/points
{
"points": [
{
"id": 1,
"payload": {"color": "red"},
"vector": [0.9, 0.1, 0.1]
}
]
}
모두 유효합니다.
데이터 포인트 업로드
성능을 최적화하기 위해 Qdrant는 데이터 포인트의 일괄 로드를 지원합니다. 이는 여러 데이터 포인트를 한 번의 API 호출로 서비스에 로드할 수 있다는 것을 의미합니다. 일괄 로드는 네트워크 연결 오버헤드를 크게 줄일 수 있습니다.
Qdrant API는 두 가지 일괄 생성 방법을 지원합니다 - 레코드 지향적 방법과 열 지향적 방법입니다. 내부적으로 이러한 옵션들은 구분되지 않으며, 간편한 상호 작용을 위한 것입니다.
REST API를 사용하여 데이터 포인트를 생성하는 방법:
PUT /collections/{collection_name}/points
{
"batch": {
"ids": [1, 2, 3],
"payloads": [
{"color": "red"},
{"color": "green"},
{"color": "blue"}
],
"vectors": [
[0.9, 0.1, 0.1],
[0.1, 0.9, 0.1],
[0.1, 0.1, 0.9]
]
}
}
또는 레코드 지향적 방법을 사용하여 동등한 방법을 사용할 수 있습니다:
PUT /collections/{collection_name}/points
{
"points": [
{
"id": 1,
"payload": {"color": "red"},
"vector": [0.9, 0.1, 0.1]
},
{
"id": 2,
"payload": {"color": "green"},
"vector": [0.1, 0.9, 0.1]
},
{
"id": 3,
"payload": {"color": "blue"},
"vector": [0.1, 0.1, 0.9]
}
]
}
Qdrant의 모든 API, 데이터 포인트 로딩을 포함하여 멱등성이 있습니다. 이는 동일한 메서드를 연속적으로 수행하는 것이 단일 실행과 동일하다는 것을 의미합니다.
이 시나리오에서는 동일한 ID로 데이터 포인트를 다시 업로드할 때 기존 데이터 포인트가 덮어씌워집니다.
멱등성 속성은 정확한 단 한 번만 보장하지 않는 메시지 큐를 사용하는 데 유용합니다. 심지어 이 경우에도 Qdrant는 데이터 일관성을 보장합니다.
v0.10.0부터 사용 가능
만약 생성되는 컬렉션이 여러 벡터를 가지고 있는 경우, 각 벡터에 대한 데이터를 제공할 수 있습니다. 이를 위해 벡터에 이름을 지정할 수 있습니다:
PUT /collections/{collection_name}/points
{
"points": [
{
"id": 1,
"vector": {
"image": [0.9, 0.1, 0.1, 0.2],
"text": [0.4, 0.7, 0.1, 0.8, 0.1, 0.1, 0.9, 0.2]
}
},
{
"id": 2,
"vector": {
"image": [0.2, 0.1, 0.3, 0.9],
"text": [0.5, 0.2, 0.7, 0.4, 0.7, 0.2, 0.3, 0.9]
}
}
]
}
v1.2.0부터 사용 가능
이름이 지정된 벡터는 선택 사항입니다. 데이터 포인트를 업로드할 때 일부 벡터를 생략할 수 있습니다. 예를 들어, image 벡터만을 가진 데이터 포인트와 text 벡터만을 가진 데이터 포인트를 업로드할 수 있습니다.
기존 ID를 가진 데이터 포인트를 수정할 때, 기존 데이터 포인트가 먼저 삭제되고 지정된 벡터로 다시 삽입됩니다. 다시 말해, 전체 데이터 포인트가 대체되며, 지정되지 않은 벡터는 null로 설정됩니다. 기존 벡터를 변경하지 않고 특정 벡터만 업데이트하려면 벡터 업데이트를 참조하십시오.
데이터 포인트 수정
데이터 포인트를 수정하기 위해 벡터나 페이로드를 수정할 수 있습니다. 이를 달성하기 위한 여러 가지 방법이 있습니다.
벡터 업데이트
버전 v1.2.0부터 사용 가능
이 메서드는 지정된 포인트에서 지정된 벡터를 업데이트합니다. 지정되지 않은 벡터는 변경되지 않습니다. 모든 주어진 포인트는 존재해야 합니다.
REST API (스키마):
PUT /collections/{collection_name}/points/vectors
{
"points": [
{
"id": 1,
"vector": {
"image": [0.1, 0.2, 0.3, 0.4]
}
},
{
"id": 2,
"vector": {
"text": [0.9, 0.8, 0.7, 0.6, 0.5, 0.4, 0.3, 0.2]
}
}
]
}
포인트를 업데이트하고 모든 벡터를 교체하려면 업로드 포인트 작업을 참조하십시오.
벡터 삭제
버전 v1.2.0부터 사용 가능
이 방법은 지정된 포인트에서만 지정된 벡터를 삭제합니다. 다른 벡터는 변경되지 않습니다. 포인트는 삭제되지 않습니다.
REST API (스키마):
POST /collections/{collection_name}/points/vectors/delete
{
"points": [0, 3, 100],
"vectors": ["text", "image"]
}
페이로드 설정
주어진 페이로드 값을 포인트에 설정합니다.
REST API (스키마):
POST /collections/{collection_name}/points/payload
{
"payload": {
"property1": "string",
"property2": "string"
},
"points": [
0, 3, 100
]
}
수정할 포인트의 id를 알 필요가 없습니다. 다른 방법은 필터를 사용하는 것입니다.
POST /collections/{collection_name}/points/payload
{
"payload": {
"property1": "string",
"property2": "string"
},
"filter": {
"must": [
{
"key": "color",
"match": {
"value": "red"
}
}
]
}
}
페이로드 덮어쓰기
주어진 페이로드로 기존 페이로드를 완전히 교체합니다.
REST API (스키마):
PUT /collections/{collection_name}/points/payload
{
"payload": {
"property1": "string",
"property2": "string"
},
"points": [
0, 3, 100
]
}
페이로드 설정와 비슷하게, 수정할 포인트의 id를 알 필요가 없습니다. 다른 방법은 필터를 사용하는 것입니다.
페이로드 키 삭제
REST API (스키마):
POST /collections/{collection_name}/points/payload/delete
{
"keys": ["color", "price"],
"points": [0, 3, 100]
}
또는 필터를 사용하여 포인트에서 페이로드 키를 삭제할 수 있습니다.
POST /collections/{collection_name}/points/payload/delete
{
"keys": ["color", "price"],
"filter": {
"must": [
{
"key": "color",
"match": {
"value": "red"
}
}
]
}
}
페이로드 지우기
이 방법은 지정된 포인트에서 모든 페이로드 키를 제거합니다.
REST API (스키마):
POST /collections/{collection_name}/points/payload/clear
{
"points": [0, 3, 100]
}
포인트 삭제
REST API (스키마):
POST /collections/{collection_name}/points/delete
{
"points": [0, 3, 100]
}
포인트를 삭제하는 다른 방법은 필터를 사용하여 지정하는 것입니다:
POST /collections/{collection_name}/points/delete
{
"filter": {
"must": [
{
"key": "color",
"match": {
"value": "red"
}
}
]
}
}
이 예제는 컬렉션에서 { "color": "red" }를 가진 모든 포인트를 삭제합니다.
포인트 검색
ID에 따라 포인트를 검색하는 방법:
REST API (스키마):
POST /collections/{collection_name}/points
{
"ids": [0, 3, 100]
}
이 메소드에는 with_vectors와 with_payload라는 추가적인 파라미터가 있습니다. 이러한 파라미터를 사용하여 필요한 포인트 결과의 부분을 선택할 수 있습니다. 제외하는 것은 쓸모없는 데이터 전송을 피하는데 도움을 줍니다.
또한 API를 통해 단일 포인트를 검색하는 것도 가능합니다:
REST API (스키마):
GET /collections/{collection_name}/points/{point_id}
스크롤
가끔은 ID를 모르는 모든 저장된 포인트를 검색하거나 필터링 조건을 충족하는 포인트를 반복적으로 순회해야 할 때가 있습니다.
REST API (스키마):
POST /collections/{collection_name}/points/scroll
{
"filter": {
"must": [
{
"key": "color",
"match": {
"value": "red"
}
}
]
},
"limit": 1,
"with_payload": true,
"with_vector": false
}
color=red와 일치하는 모든 포인트를 반환합니다:
{
"result": {
"next_page_offset": 1,
"points": [
{
"id": 0,
"payload": {
"color": "red"
}
}
]
},
"status": "ok",
"time": 0.0001
}
스크롤 API는 페이지네이션 방식으로 필터와 일치하는 모든 포인트를 반환합니다.
결과 포인트는 모두 ID에 의해 정렬됩니다. 다음 페이지를 쿼리하려면 발견된 ID의 최대값을 offset 필드에 지정해야 합니다. 편의상 이 ID는 next_page_offset 필드에서도 반환됩니다. next_page_offset 필드의 값이 null인 경우, 마지막 페이지에 도달했다는 것을 의미합니다.
포인트 수 세기
버전 v0.8.4부터 사용 가능
가끔은 검색을 진행하지 않고도 필터링 조건과 일치하는 포인트의 수를 파악하는 것이 유용할 수 있습니다.
예를 들어 다음과 같은 시나리오에서 유용할 수 있습니다:
- 액세스할 수 있는 검색 결과 크기 추정
- 페이지네이션을 위한 페이지 수 결정
- 쿼리 실행 속도 디버깅
REST API (스키마):
POST /collections/{collection_name}/points/count
{
"filter": {
"must": [
{
"key": "color",
"match": {
"value": "red"
}
}
]
},
"exact": true
}
주어진 필터링 조건과 일치하는 포인트 수를 반환합니다:
{
"count": 3811
}
일괄 업데이트
v1.5.0부터 사용 가능
여러 지점에 대한 일괄 작업을 수행할 수 있습니다. 이에는 지점, 벡터 및 페이로드의 삽입, 업데이트 및 삭제가 포함됩니다.
일괄 업데이트 요청은 순차적으로 실행되는 연속적인 작업으로 구성됩니다. 일괄 처리할 수 있는 작업은 다음과 같습니다:
- 지점의 삽입 또는 업데이트:
upsert또는UpsertOperation - 지점 삭제:
delete_points또는DeleteOperation - 벡터 업데이트:
update_vectors또는UpdateVectorsOperation - 벡터 삭제:
delete_vectors또는DeleteVectorsOperation - 페이로드 설정:
set_payload또는SetPayloadOperation - 페이로드 덮어쓰기:
overwrite_payload또는OverwritePayload - 페이로드 삭제:
delete_payload또는DeletePayloadOperation - 페이로드 지우기:
clear_payload또는ClearPayloadOperation
다음 예시 코드 스니펫은 모든 작업을 사용합니다.
REST API (스키마):
POST /collections/{collection_name}/points/batch
{
"operations": [
{
"upsert": {
"points": [
{
"id": 1,
"vector": [1.0, 2.0, 3.0, 4.0],
"payload": {}
}
]
}
},
{
"update_vectors": {
"points": [
{
"id": 1,
"vector": [1.0, 2.0, 3.0, 4.0]
}
]
}
},
{
"delete_vectors": {
"points": [1],
"vector": [""]
}
},
{
"overwrite_payload": {
"payload": {
"test_payload": "1"
},
"points": [1]
}
},
{
"set_payload": {
"payload": {
"test_payload_2": "2",
"test_payload_3": "3"
},
"points": [1]
}
},
{
"delete_payload": {
"keys": ["test_payload_2"],
"points": [1]
}
},
{
"clear_payload": {
"points": [1]
}
},
{"delete": {"points": [1]}}
]
}
단일 작업 유형으로 일괄 지점을 사용하려면 해당 작업 내에서 일괄 기능을 직접 사용하십시오.