10. 확장 JSON 형식 (Extended JSON) 지원

Altibase Document API는 64비트 정수(Long)와 고정밀 소수(Decimal128) 타입의 정밀도를 보장하기 위해 MongoDB 호환 확장 JSON 형식을 지원한다.

타입	확장 JSON 형식	설명
Long (64비트 정수)	{"$numberLong": "값"}	JavaScript Number 범위를 초과하는 정수
Decimal128 (고정밀 소수)	{"$numberDecimal": "값"}	금융 계산용 고정밀 소수점

10.1 입력(Request) 처리

문서의 삽입 및 수정 시 데이터 타입은 입력 형식에 따라 결정된다.

입력 형식	저장되는 타입	예시
일반 숫자	Integer 또는 Double	"count": 100 → Integer로 저장
확장 JSON 객체	Long 또는 Decimal128	"transactionId": {"$numberLong": "9223372036854775807"} → Long으로 저장

Important

JavaScript/Node.js 클라이언트에서 Long 범위의 큰 정수를 입력할 때는 반드시 확장 JSON 형식을 사용해야 한다. 이는 JavaScript의 Number 타입이 9,007,199,254,740,991을 초과하는 정수를 정확히 표현할 수 없어, 서버 전송 과정에서 정밀도 손실이 발생하기 때문이다.

Note

Java, Python, Go 등의 클라이언트는 64비트 정수를 정확히 처리할 수 있으므로, 일반 숫자로 전송해도 서버에서 Long으로 올바르게 파싱된다. 예: "transactionId": 9223372036854775807 → Long으로 저장됨. 단, 코드의 명확성과 일관성을 위해 확장 JSON 형식 사용을 권장한다.

Long 타입으로 저장하는 예시 :

curl -X POST http://localhost:8080/api/collections/orders/documents \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "document": {
      "orderId": 12345,
      "transactionId": {"$numberLong": "9223372036854775807"}
    }
  }' 

10.2 출력(Response) 처리

API 응답 시 각 타입은 다음과 같이 변환된다:

저장된 타입	응답 형식	예시
Integer, Double	표준 JSON 숫자	"count": 100
Long	확장 JSON 객체	"transactionId":
Decimal128	확장 JSON 객체	"price":

Info

API 응답에서 확장 JSON 타입(Long, Decimal128)을 처리하고, 키 메타데이터를 함께 복원할 때 각 언어별 라이브러리를 사용한다: - Java : AltibaseDocument.parseFromRestResponse(jsonString) 사용- REST 응답의 key, keyType, keyFieldName을 자동으로 설정 - JavaScript/Node.js : MongoDB EJSON 라이브러리 (bson 패키지의 EJSON.parse()) 사용 - Python : bson 모듈 또는 pymongo 라이브러리 사용

Note

AltibaseDocument.parse(jsonString)는 순수 JSON 파싱 용도로, 필터 조건이나 정렬 명세에 적합하다. REST 응답 전체를 파싱하여 키 메타데이터까지 활용하려면 parseFromRestResponse()를 사용해야 한다.

10.3 필터 검색 시 사용

Long 또는 Decimal128 값으로 저장된 필드를 검색할 때도 확장 JSON 형식 사용을 권장한다:

curl -X POST http://localhost:8080/api/collections/orders/documents/search \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "transactionId": {"$numberLong": "9223372036854775807"}
    }
  }'