데이터 읽기

데이터 읽기 (edge-edge-api-reading-data)

Edge Shard는 데이터를 읽는 여러 방법을 제공해요. 먼저 큰 그림을 보면, query는 유사도 검색의 진입점이고 prefetch, fusion, reranking을 지원해요. scroll은 점수를 매기지 않고 포인트를 페이지 단위로 넘겨주고, retrieve와 count, facet은 포인트와 페이로드 통계를 직접 읽어요.

출처: Qdrant 공식 문서 — edge/edge-api/reading-data

Rust에서는 query_groups와 search_matrix를 쓰려면 EdgeShardRead 트레이트를 범위에 가져와야 해요: use qdrant_edge::EdgeShardRead;

query

쿼리를 실행하되, 선택적으로 중첩된 prefetch 쿼리의 결과를 결합해요.

def query(self, query: QueryRequest) -> List[ScoredPoint]

fn query(&self, query: QueryRequest) -> OperationResult<Vec<ScoredPoint>>

점수 순으로 정렬된 ScoredPoint 목록을 반환해요.

QueryRequest는 다음과 같은 파라미터를 받아요.

파라미터 유형 설명
limit int 반환할 포인트의 최대 개수. 필수
offset int 건너뛸 결과 수
query scoring query 무엇을 기준으로 점수를 매길지. 생략하면 필터만 반영하고 점수 없이 포인트를 반환해요.
prefetches list of Prefetch 이 쿼리가 rerank하거나 fusion하는 중첩 쿼리
filter Filter 포인트가 만족해야 하는 페이로드·ID 조건. Filtering 문서를 참고하세요.
score_threshold float 이 값보다 나쁜 점수의 결과는 제거해요.
params SearchParams hnsw_ef나 exact 같은 검색 시점 튜닝
with_payload bool, list of str, 또는 PayloadSelector 어떤 페이로드를 포함할지
with_vector bool 또는 list of str 어떤 벡터를 포함할지

query 파라미터는 여러 종류의 스코어링을 받아요.

종류 목적
Query 벡터 유사도: 최근접 이웃, 추천(recommendation), discovery, context, 피드백.
Fusion 여러 prefetch의 결과를 결합. Hybrid Queries 문서 참고.
OrderBy 유사도가 아니라 페이로드 필드 순서로 정렬.
Formula 페이로드와 점수에 대한 표현식으로 prefetch 결과를 리스코어.
Mmr 최대 한계 관련성. 유사도와 다양성을 절충.
Sample 포인트 샘플 반환.

Prefetch는 query, limit, filter, score_threshold, params, 그리고 자기 자신의 중첩된 prefetch를 가져요. 그래서 prefetch를 중첩해 **다단계 검색(multi-stage retrieval)**을 만들 수 있어요.

scroll

점수를 매기지 않고 샤드 안의 포인트를 페이지 단위로 넘겨줘요.

def scroll(self, scroll: ScrollRequest) -> Tuple[List[Record], Optional[PointId]]

fn scroll(&self, scroll: ScrollRequest) -> OperationResult<(Vec<Record>, Option<PointId>)>

일치하는 레코드와 다음 호출에 넘길 offset을 반환하며, 마지막 페이지에 도달하면 None을 반환해요.

파라미터 유형 설명
offset PointId 이 포인트 ID부터 시작. 이전 호출이 반환한 offset을 넘겨요.
limit int 반환할 포인트의 최대 개수
filter Filter 포인트가 만족해야 하는 페이로드·ID 조건
with_payload bool, list of str, 또는 PayloadSelector 어떤 페이로드를 포함할지
with_vector bool 또는 list of str 어떤 벡터를 포함할지
order_by OrderBy 포인트 ID가 아니라 페이로드 필드 순서로 페이지를 넘김

query_groups (Rust 전용)

쿼리 결과를 페이로드 필드로 그룹화해서, 고유 값별로 제한된 수의 히트를 반환해요.

fn query_groups(&self, request: GroupRequest) -> OperationResult<Vec<Group>>

각 그룹의 키(key)와 히트(hits)를 담은 Group 목록을 반환해요.

파라미터 유형 설명
query QueryRequest 각 그룹 안에서 실행할 쿼리
group_by JsonPath 그룹화할 페이로드 필드
groups usize 반환할 그룹의 최대 개수
group_size usize 그룹당 히트의 최대 개수

search_matrix (Rust 전용)

포인트를 샘플링하고 각 샘플의 최근접 이웃을 찾아, 클러스터링과 시각화에 유용한 유사도 행렬을 만들어요.

fn search_matrix(&self, request: SearchMatrixRequest) -> OperationResult<SearchMatrixResponse>

sample_ids와 각 샘플의 nearests를 담은 SearchMatrixResponse를 반환해요.

파라미터 유형 설명
sample_size usize 샘플링할 포인트 수
limit_per_sample usize 샘플 포인트당 찾을 최근접 이웃 수
filter Filter 일치하는 포인트로만 샘플링을 제한
using VectorNameBuf 비교에 사용할 명명된 벡터

retrieve

점수를 매기지 않고 ID로 포인트를 조회해요.

def retrieve(
    self,
    point_ids: List[PointId],
    with_payload: Optional[WithPayloadType] = None,
    with_vector: Optional[WithVectorType] = None,
) -> List[Record]

fn retrieve(
    &self,
    point_ids: Vec<PointId>,
    with_payload: Option<WithPayloadType>,
    with_vector: Option<WithVectorType>,
) -> OperationResult<Vec<Record>>

Record 목록을 반환해요. 존재하지 않는 포인트는 오류로 보고하지 않고 그냥 생략돼요.

파라미터 설명
point_ids 조회할 ID
with_payload 어떤 페이로드를 포함할지
with_vector 어떤 벡터를 포함할지

count

필터와 일치하는 포인트의 개수를 세요.

def count(self, count: CountRequest) -> int

fn count(&self, count: CountRequest) -> OperationResult<usize>

일치하는 포인트 수를 반환해요.

파라미터 유형 설명
filter Filter 집계 대상 포인트가 만족해야 할 조건. 생략하면 모든 포인트를 집계해요.
exact bool 추정이 아니라 정확하게 계산할지

facet

페이로드 필드의 가장 흔한 값들을 개수와 함께 반환해요.

def facet(self, facet: FacetRequest) -> FacetResponse

fn facet(&self, facet: FacetRequest) -> OperationResult<FacetResponse>

각각 값(value)과 개수(count)를 담은 히트의 FacetResponse를 반환해요.

파라미터 유형 설명
key JsonPath faceting할 페이로드 필드. 필수
limit int 반환할 고유 값의 최대 개수
exact bool 추정이 아니라 정확한 개수를 계산할지
filter Filter 일치하는 포인트로만 faceting을 제한

faceting과 filtering은 둘 다 해당 필드의 페이로드 인덱스가 있으면 성능이 좋아져요. Create a Payload Index 문서를 참고하세요.

요청 빌더 (Request Builders)

Rust에서는 요청 타입이 fluent builder 패턴을 따라요.

let request = QueryRequestBuilder::new(10)
    .with_payload(WithPayloadInterface::Bool(true))
    .build();

Builder는 QueryRequest, ScrollRequest, RetrieveRequest, CountRequest, FacetRequest, GroupRequest, SearchMatrixRequest, Prefetch에 제공돼요. Python에서는 요청을 클래스 생성자로 만들어요.

더 알아보기 (Learn more)