풀텍스트 검색

풀텍스트 검색 (Full-Text Search)

Full-text search를 사용하면 trace와 observation의 입력·출력·메타데이터에서 특정 키워드나 구절의 모든 발생을 찾을 수 있어요. 일부 내용은 기억나지만 어떤 trace에 속하는지 모를 때, 복잡한 애플리케이션을 디버깅할 때 특히 유용해요.

출처: 문서

본문

Full-text search는 trace와 observation의 입력·출력·메타데이터에서 특정 키워드나 구절을 검색하는 기능이에요. 일부 내용을 기억하지만 그것이 어떤 trace에 속하는지 모를 때 복잡한 애플리케이션을 디버깅하는 데 특히 유용해요.

UI에서 검색 (Search in the UI)

traces·observations 테이블 위의 검색 바를 사용해 입력·출력 내용을 검색해요. 일치하는 trace와 observation이 반환되어 찾고 있던 실행을 빠르게 찾고, 기존 필터와 시간 범위 선택기와 검색을 조합할 수 있어요.

v4 Observations·Traces 테이블에서는 level:ERROR·latency:>2 같은 구조적 필터와 함께 Filter Search Bar에서도 인라인으로 full-text search를 사용할 수 있어요.

성능 (Performance)

검색은 ClickHouse full-text search를 사용해요. 텍스트 인덱스는 Langfuse가 전체 observation 페이로드를 읽기 전에 쿼리와 일치할 수 없는 데이터를 건너뛸 수 있게 해서, 대용량 trace가 있는 큰 프로젝트에서도 검색을 빠르게 유지해요. 자세한 내용은 ClickHouse GA announcement에서 읽을 수 있어요.

이 인덱스가 토큰 기반이므로, 쿼리는 하위 문자열이 아니라 전체 단어와 일치해요 — error는 error와 일치하지만 errors와는 일치하지 않아요 — 그리고 다중 단어 쿼리는 연속 구절로 일치해요.

API로 검색 (Search via the API)

Observations API v2는 입력·출력·문자열 메타데이터 필터에서 토큰 기반 full-text search를 위한 matches 연산자를 지원해요.

/api/public/v2/observations에서 필터를 만들 때, 정확한 값을 알면 =를, 토큰 기반 검색을 원하면 matches를 선호하세요:

  • 입력·출력에서 matches는 대소문자 구분이 없어서 refund failed가 Refund Failed와 일치할 수 있어요.
  • 메타데이터 필터에서 matches는 대소문자 구분이며, 선택한 키의 문자열 메타데이터 값에 적용돼요.
  • contains, starts with, ends with 같은 부분 문자열 연산자는 입력·출력 필터에서 느린 전체 내용 스캔이 필요하므로 400으로 거부돼요. 이런 필드에서는 토큰 검색에 matches를 사용하세요.
[
  {
    "type": "string",
    "column": "output",
    "operator": "matches",
    "value": "refund failed"
  }
]

observation 출력의 matches 필터 예시:

[
  {
    "type": "stringObject",
    "column": "metadata",
    "key": "environment",
    "operator": "=",
    "value": "production"
  }
]

정확한 메타데이터 필터 예시:

JSON 배열을 GET /api/public/v2/observations의 URL 인코딩된 filter 쿼리 파라미터로 전달하세요. 전체 필터 스키마는 Observations API v2 문서와 API 레퍼런스를 참고하세요.

GitHub Discussions

더 알아보기 (Learn more)