추가 연산자 (limit·offset·autocut·sort)

검색 결과의 양과 순서를 다듬는 연산자예요. limit, autocut, sort는 클래스 수준에서 질의를 조정하고, offset, after는 페이지네이션에 쓰여요.

출처: Weaviate 공식 문서 - Additional operators

본문

limit

limit은 결과 개수를 제한해요. Get, Explore, Aggregate에서 쓸 수 있어요.

{
  Get {
    Article(limit: 5) {
      title
    }
  }
}

offset을 이용한 페이지네이션

offset과 limit을 함께 써서 결과의 "페이지"를 지정해요. 예를 들어 처음 10개는 limit: 10, offset: 0, 다음 10개는 offset: 10처럼 계속 올려가며 보는 방식이에요. Get과 Explore 함수가 offset을 지원해요.

{
  Get {
    Article(
      limit: 5,
      offset: 2
    ) {
      title
    }
  }
}

페이지네이션은 커서 기반이 아니라서 주의할 점이 있어요. offset이 커질수록 응답 시간과 시스템 부하가 늘어나요 — 21~30번째 결과를 요청하면 Weaviate는 30개를 가져와 앞 20개를 버리는 식이죠. 멀티샤드 구성에서는 자원 사용이 더 커져요. 또한 한 질의는 QUERY_MAXIMUM_RESULTS까지만 반환하고, offset+limit이 그 값을 넘으면 오류가 나요. 게다가 페이지네이션은 상태를 기억하지 않아서, 호출 사이에 쓰기가 일어나면 페이지가 건너뛸 수 있어요.

autocut

autocut은 결과 지표(벡터 거리나 검색 점수)의 "점프"(불연속 지점)를 기준으로 결과를 잘라요. 점프가 몇 번 일어날지 숫자로 지정하고, 그만큼 점프가 생긴 뒤에는 결과를 반환하지 않아요. 예를 들어 거리값이 [0.1899, 0.1901, 0.191, 0.21, 0.215, 0.23]일 때 autocut: 1은 [0.1899, 0.1901, 0.191]까지만, autocut: 2는 0.215까지 반환해요. nearXXX, bm25, hybrid에서 동작하고, 기본은 비활성이에요(0 또는 음수로 비활성화). limit과 함께 쓰면 limit 값까지의 첫 객체들만 고려해요.

after 커서

v1.18부터 after로 객체를 순차 조회할 수 있어요. 객체 ID에 의존하기 때문에 리스트 질의(list query)에서만 동작하고, where, near<Media>, bm25, hybrid, 필터와는 함께 쓸 수 없어요. 그런 경우에는 offset+limit 페이지네이션을 쓰면 돼요.

{
  Get {
    Article(
      limit: 5,
      after: "002d5cb3-298b-380d-addb-2e026b76c8ed"
    ) {
      title
      _additional {
        id
      }
    }
  }
}

sort (정렬)

원시 프로퍼티(텍스트·숫자·int)로 결과를 정렬할 수 있어요. 다만 검색 연산자와는 정렬을 같이 쓸 수 없어요 — 검색 연산자는 거리나 점수 같은 관련성 지표로 이미 결과에 순위를 매기기 때문이에요.

{
  Get {
    JeopardyQuestion(
      sort: {
        path: ["answer"]
        order: asc
      }
      limit: 3
    ) {
      question
      answer
    }
  }
}

정렬 순서 규칙이 몇 가지 있어요. boolean은 false가 true보다 작고, null은 어떤 non-null 값보다도 작아서 오름차순에서 맨 앞에 와요. 배열은 각 요소를 앞에서부터 하나씩 비교해요. _creationTimeUnix처럼 메타데이터로 정렬하려면 프로퍼티명 앞에 밑줄을 붙여요 (_id, _creationTimeUnix, _lastUpdateTimeUnix).

groupBy (그룹핑)

group를 쓰면 비슷한 개념을 하나로 합칠 수 있어요. type: closest는 가장 가까운 개념을 반환하고, type: merge는 비슷한 엔티티를 하나의 문자열로 합쳐 반환해요. force는 0~1 사이 값으로 이동 강도를 조절해요 — 0이면 이동 없음, 1이면 최대 이동.

{
  Get {
    Publication(
      group: {
        type: merge,
        force: 0.05
      }
    ) {
      name
    }
  }
}

추가 연산자 (limit·offset·autocut·sort)