Query API 레퍼런스

엣지 쿼리 API (유니크 엣지). 유니크 엣지와 멀티 엣지의 차이는 FAQ를 참고하세요. 개념적 배경은 쿼리를 참고하세요.

1. Count

특정 노드에서 시작하는 엣지의 수를 조회합니다.

엔드포인트

GET /graph/v3/databases/{database}/tables/{table}/edges/count

파라미터

위치	파라미터	필수 여부	설명
Header	Authorization	선택	인증 키 (향후 사용을 위해 예약됨)
Path	database	필수	타겟 데이터베이스 이름
Path	table	필수	타겟 테이블 이름
Query	start	필수	시작 노드 ID
Query	direction	필수	쿼리 방향 (OUT 또는 IN)
Query	ranges	선택 (기본값: null)	스캔 범위

응답 타입

Count - 엣지 카운트 정보를 포함한 페이로드

요청 예시

파라미터	값
Authorization	YOUR_API_KEY
database	your_database
table	your_table
start	source1
direction	OUT

# count?start=source1&direction=OUT
curl -X GET \
    "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/count?start=source1&direction=OUT" \
    -H "Authorization: YOUR_API_KEY"

응답 예시

{
  "start": "source1",
  "direction": "OUT",
  "count": 10,
  "context": {}
}

2. Get

소스 노드와 타겟 노드 사이의 엣지를 조회합니다.

엔드포인트

GET /graph/v3/databases/{database}/tables/{table}/edges/get

파라미터

위치	파라미터	필수 여부	설명
Header	Authorization	선택	인증 키 (향후 사용을 위해 예약됨)
Path	database	필수	타겟 데이터베이스 이름
Path	table	필수	타겟 테이블 이름
Query	source	필수	소스 노드 ID 목록 (쉼표로 구분)
Query	target	필수	타겟 노드 ID 목록 (쉼표로 구분)
Query	filters	선택 (기본값: null)	필터링 조건

여러 소스 또는 타겟 ID를 지정하면 mget으로 동작하여 여러 엣지를 조회합니다. 이 경우 API 요청당 최대 25개의 엣지를 조회할 수 있습니다. 더 많은 엣지를 조회하려면 여러 API 요청을 보내세요.

응답 타입

EdgeFrame - 엣지 데이터를 포함한 페이로드

요청 예시 (Get) - 소스 1개, 타겟 1개

(source, target)에 대한 엣지 데이터를 조회합니다. (최대 1개 결과)

파라미터	값
Authorization	YOUR_API_KEY
database	your_database
table	your_table
source	source1
target	target1

# get?source=source1&target=target1
curl -X GET \
    "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/get?source=source1&target=target1" \
    -H "Authorization: YOUR_API_KEY"

응답:

{
  "edges": [
    {
      "version": 1,
      "source": "source1",
      "target": "target1",
      "properties": {
        "weight": 0.8,
        "type": "FOLLOWS"
      },
      "context": {}
    }
  ],
  "count": 1,
  "total": 1,
  "offset": null,
  "hasNext": false,
  "context": {}
}

요청 예시 (MGet) - 소스 1개, 타겟 N개

(source, target1) ~ (source, targetN)에 대한 엣지 데이터를 조회합니다. (최대 N개 결과)

파라미터	값
Authorization	YOUR_API_KEY
database	your_database
table	your_table
source	source1
target	target1,target2,target3

# get?source=source1&target=target1,target2,target3
curl -X GET \
    "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/get?source=source1&target=target1,target2,target3" \
    -H "Authorization: YOUR_API_KEY"

응답:

{
  "edges": [
    {
      "version": 3,
      "source": "source1",
      "target": "target3",
      "properties": {
        "weight": 0.75,
        "type": "FOLLOWS"
      },
      "context": {}
    },
    {
      "version": 1,
      "source": "source1",
      "target": "target1",
      "properties": {
        "weight": 0.8,
        "type": "FOLLOWS"
      },
      "context": {}
    }
  ],
  "count": 2,
  "total": 2,
  "offset": null,
  "hasNext": false,
  "context": {}
}

요청 예시 (MGet) - 소스 M개, 타겟 1개

(source1, target) ~ (sourceM, target)에 대한 엣지 데이터를 조회합니다. (최대 M개 결과)

파라미터	값
Authorization	YOUR_API_KEY
database	your_database
table	your_table
source	source1,source2,source3
target	target1

# get?source=source1,source2,source3&target=target1
curl -X GET \
    "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/get?source=source1,source2,source3&target=target1" \
    -H "Authorization: YOUR_API_KEY"

응답:

{
  "edges": [
    {
      "version": 3,
      "source": "source3",
      "target": "target1",
      "properties": {
        "weight": 0.75,
        "type": "FOLLOWS"
      },
      "context": {}
    },
    {
      "version": 1,
      "source": "source1",
      "target": "target1",
      "properties": {
        "weight": 0.8,
        "type": "FOLLOWS"
      },
      "context": {}
    }
  ],
  "count": 2,
  "total": 2,
  "offset": null,
  "hasNext": false,
  "context": {}
}

요청 예시 (MGet) - 소스 M개, 타겟 N개 (권장하지 않음)

(source1, target1) ~ (sourceM, targetN)에 대한 엣지 데이터를 조회합니다. (최대 M × N개 결과)

참고: 이 형식은 최대 M × N개의 엣지를 조회할 수 있으므로 프로덕션에서 사용하지 않아야 합니다.

파라미터	값
Authorization	YOUR_API_KEY
database	your_database
table	your_table
source	source1,source2,source3
target	target1,target2,target3

# get?source=source1,source2,source3&target=target1,target2,target3
curl -X GET \
    "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/get?source=source1,source2,source3&target=target1,target2,target3" \
    -H "Authorization: YOUR_API_KEY"

응답:

{
  "edges": [
    {
      "version": 3,
      "source": "source1",
      "target": "target3",
      "properties": {
        "weight": 0.75,
        "type": "FOLLOWS"
      },
      "context": {}
    },
    {
      "version": 3,
      "source": "source3",
      "target": "target1",
      "properties": {
        "weight": 0.75,
        "type": "FOLLOWS"
      },
      "context": {}
    },
    {
      "version": 1,
      "source": "source1",
      "target": "target1",
      "properties": {
        "weight": 0.8,
        "type": "FOLLOWS"
      },
      "context": {}
    }
  ],
  "count": 3,
  "total": 3,
  "offset": null,
  "hasNext": false,
  "context": {}
}

3. Scan

인덱스를 사용하여 엣지를 스캔합니다.

엔드포인트

GET /graph/v3/databases/{database}/tables/{table}/edges/scan/{index}

파라미터

위치	파라미터	필수 여부	설명
Header	Authorization	선택	인증 키 (향후 사용을 위해 예약됨)
Path	database	필수	타겟 데이터베이스 이름
Path	table	필수	타겟 테이블 이름
Path	index	필수	사용할 인덱스 이름
Query	start	필수	시작 노드 ID
Query	direction	필수	쿼리 방향 (OUT 또는 IN)
Query	limit	선택	반환할 최대 결과 수; 프로덕션에서는 25 권장
Query	offset	선택 (기본값: null)	페이지네이션 오프셋
Query	ranges	선택 (기본값: null)	스캔 범위
Query	filters	선택 (기본값: null)	필터링 조건
Query	features	선택 (기본값: 빈 리스트)	포함할 기능 목록 (예: `total`로 전체 값 계산)

응답 타입

EdgeFrame - 엣지 데이터를 포함한 페이로드

요청 예시

파라미터	값
Authorization	YOUR_API_KEY
database	your_database
table	your_table
index	your_index
start	source1
direction	OUT

# scan/your_index?start=source1&direction=OUT
curl -X GET \
    "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/scan/your_index?start=source1&direction=OUT" \
    -H "Authorization: YOUR_API_KEY"

응답 예시

{
  "edges": [
    {
      "version": 1,
      "source": "source1",
      "target": "target1",
      "properties": {
        "weight": 0.8,
        "type": "FOLLOWS"
      },
      "context": {}
    }
  ],
  "count": 1,
  "total": -1,
  "offset": null,
  "hasNext": false,
  "context": {}
}

참고: total이 -1이면 전체 개수가 계산되지 않은 것입니다. features=total을 제공하면 전체 개수가 실제로 계산됩니다.

페이지네이션

offset 파라미터는 다음 페이지의 시작 위치를 나타내고, hasNext는 다음 페이지가 있는지를 나타냅니다. 오프셋이 없으면 첫 번째 페이지가 반환됩니다.

1. 첫 번째 페이지 요청

오프셋 없이 첫 번째 페이지를 요청합니다.

요청 예시

파라미터	값	설명
Authorization	YOUR_API_KEY
database	your_database
table	your_table
index	your_index
start	source1
direction	OUT
limit		25 권장

# scan/your_index?start=source1&direction=OUT
curl -X GET \
    "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/scan/your_index?start=source1&direction=OUT" \
    -H "Authorization: YOUR_API_KEY"

응답:

{
  "edges": [
    {
      "version": 1,
      "source": "source1",
      "target": "target1",
      "properties": {
        "weight": 0.8,
        "type": "FOLLOWS"
      },
      "context": {}
    },
    ...
  ],
  "count": 10,
  "total": -1,
  "offset": "string_encoded",
  "hasNext": true,
  "context": {}
}

2. 다음 페이지 요청

이전 응답의 offset 값을 사용하여 다음 페이지를 조회합니다.

요청 예시

파라미터	값	설명
Authorization	YOUR_API_KEY
database	your_database
table	your_table
index	your_index
start	source1
direction	OUT
offset	string_encoded	이전 응답에서 받은 값
limit		25 권장

# scan/your_index?start=source1&direction=OUT&offset=string_encoded
curl -X GET \
    "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/scan/your_index?start=source1&direction=OUT&offset=string_encoded" \
    -H "Authorization: YOUR_API_KEY"

응답:

{
  "edges": [
    {
      "version": 1,
      "source": "source1",
      "target": "target1",
      "properties": {
        "weight": 0.8,
        "type": "FOLLOWS"
      },
      "context": {}
    },
    ...
  ],
  "count": 10,
  "total": -1,
  "offset": null,
  "hasNext": false,
  "context": {}
}

인덱스 범위

ranges 파라미터를 사용하면 count/scan 쿼리에서 데이터 스캔 범위를 지정할 수 있습니다.

범위와 인덱스의 관계

중요: 범위는 인덱스에 포함된 필드만 사용할 수 있습니다.

인덱스 의존성: ranges에 사용되는 필드는 인덱스가 있어야 합니다. 인덱스가 없는 필드에 범위를 지정하면 예상치 못한 결과가 반환됩니다.
연산자 의미: eq, gt(e), lt(e), between 연산자는 실제 스토리지 스캔의 시작점과 끝점을 결정합니다. 인덱스 속성에 맞게 적절히 사용해야 합니다.
- 인덱스가 DESC (내림차순)으로 설정된 경우: lt가 시작점, gt가 끝점이 됩니다.
- 인덱스가 ASC (오름차순)으로 설정된 경우: gt가 시작점, lt가 끝점이 됩니다.
복합 범위: 범위는 인덱스가 정의된 필드 조합의 순서대로 사용할 수 있습니다. 범위는 인덱스에 정의된 필드 순서대로 적용해야 합니다.

범위 구문

범위는 다음 형식으로 작성합니다:

ranges=range1[;range2;range3;...]

각 범위는 다음 형식을 따릅니다:

field:operator:value

여러 범위를 적용하려면 세미콜론(;)으로 구분합니다:

field1:operator1:value1;field2:operator2:value2

in 또는 bt (between) 연산자를 사용할 때 여러 값은 쉼표(,)로 구분합니다:

field:in:value1,value2,value3
field:bt:minValue,maxValue

연산자

연산자	설명	예시
`eq`	같음	`type:eq:0`
`gt`	초과	`createdAt:gt:1000000`
`gte`	이상	`createdAt:gte:1000000`
`lt`	미만	`createdAt:lt:2000000`
`lte`	이하	`createdAt:lte:2000000`
`bt`	두 값 사이	`createdAt:bt:1000000,2000000`

예시

단순 범위:

GET .../scan/your_index?start=10&direction=OUT&ranges=type:eq:0

이 예시는 type 프로퍼티가 0인 엣지만 조회하는 범위를 지정합니다. type은 properties.type을 의미하며, properties.type이 your_index에 포함되어 있어야 합니다.

복합 범위:

GET .../scan/your_index?start=10&direction=OUT&ranges=type:eq:0;createdAt:gt:1000000

이 예시는 type이 0이고 createdAt이 1000000보다 큰 엣지만 조회하는 범위를 지정합니다.

Between 연산자:

GET .../scan/your_index?start=10&direction=OUT&ranges=createdAt:bt:1000000,2000000

이 예시는 createdAt이 1000000에서 2000000 사이인 엣지만 조회하는 범위를 지정합니다.

필터

filters 파라미터를 사용하면 get/scan 쿼리에서 데이터(엣지)를 필터링할 수 있습니다. 범위와 동일한 형식을 사용합니다.

범위와의 차이점: 범위는 쿼리 범위를 사전에 지정하며 인덱스로 설정된 필드만 사용할 수 있는 반면, filters는 쿼리 결과를 필터링하며 인덱스로 설정되지 않은 필드도 사용할 수 있습니다.

필터 예시

GET .../get?source=1,2,3&target=10&filters=type:eq:0
GET .../scan/your_index?start=1&direction=OUT&ranges=createdAt:gte:1000000&filters=type:eq:0

데이터 모델

쿼리 방향

OUT: 나가는 방향 (예: 사용자 [좋아요]→ 상품 관계에서 사용자가 좋아한 상품 조회)
IN: 들어오는 방향 (예: 위 관계에서 상품을 좋아한 사용자 조회)

Count 응답

카운트 쿼리 응답. 엣지 카운트 정보를 포함한 페이로드.

data class Count(
  val start: Any,                 // 시작 노드 ID
  val direction: Direction,       // 방향 (IN, OUT)
  val count: Long,                // 엣지 카운트
  val context: Map<String, Any?>, // 컨텍스트 정보
)

EdgeFrame 응답

Get 및 scan 쿼리 응답. 엣지 데이터를 포함한 페이로드.

data class EdgeFrame(
  val edges: List<Edge>,          // 엣지 목록
  val count: Int,                 // 현재 반환된 엣지 수
  val total: Long,                // 전체 엣지 카운트 (-1은 계산되지 않음을 의미)
  val offset: String?,            // 페이지네이션 오프셋
  val hasNext: Boolean,           // 다음 페이지 존재 여부
  val context: Map<String, Any?>, // 컨텍스트 정보
)

Edge

개별 엣지 정보 페이로드.

data class Edge(
  val version: Long,                 // 엣지 버전
  val source: Any,                   // 소스 노드 ID
  val target: Any,                   // 타겟 노드 ID
  val properties: Map<String, Any?>, // 엣지 프로퍼티
  val context: Map<String, Any?>,    // 컨텍스트 정보
)