GraphQL 검색 API 개요

GraphQL 검색 API 개요

Weaviate에 질의하는 방법은 GraphQL과 gRPC 두 가지가 있어요. 클라이언트 라이브러리를 쓰면 내부 API 호출을 추상화해 주지만, 직접 GraphQL로 /graphql 엔드포인트에 POST 하거나 gRPC protobuf 명세에 따라 호출할 수도 있어요. 대부분의 경우 클라이언트 라이브러리를 권장해요.

출처: Weaviate 공식 문서 - Search (GraphQL | gRPC)

본문

GraphQL은 그래프 데이터 구조를 바탕으로 한 질의 언어예요. 과잉 조회(over-fetching)나 부족 조회(under-fetching) 같은 다른 질의 언어의 문제를 줄여서 데이터 조회·변경에 효율적이죠. GraphQL은 대소문자를 구분하니 질의를 쓸 때 정확한 표기를 꼭 확인해요.

질의 구조는 함수 안에 컬렉션, 그 안에 프로퍼티를 중첩하는 형태예요.

{
  Get {
    Article {
      title
      _additional { ... }
    }
  }
}

REST로 보낼 때는 /v1/graphql에 POST 하고, 본문은 query 필드에 질의 문자열을 담은 JSON이에요.

{
  "query": "{ Get { Article { title } } }"
}

여기서 주의할 점이 하나 있어요. GraphQL 정수 데이터는 현재 int32까지만 지원해요. int32보다 큰 정수 값을 가진 필드는 GraphQL 질의로는 반환되지 않는 제약이 있어서, 지금은 문자열로 대체하는 편법을 쓰는 중이에요.

gRPC API는 v1.19.0부터 점진적으로 추가되고 있어요. gRPC는 HTTP/2와 Protocol Buffers 기반의 계약 기반 RPC라 매우 빠르고 효율적이죠. 클라이언트 라이브러리가 없거나 프로토콜 세부를 직접 제어하고 싶을 때 선택할 수 있는 길이에요.

더 알아보기