7. 문서 API#
문서(Document)는 컬렉션에 저장되는 JSON 데이터 단위이다. 각 문서는 고유한 키(key)를 가진다.
7.1 문서 삽입#
7.1.1 단일 문서 삽입#
컬렉션에 새 문서 1건을 삽입한다. 키를 지정하지 않으면, UUID 키 유형의 키가 자동으로 생성된다.
엔드포인트 :
POST /api/collections/{name}/documents
필요 권한 :
- 일반 컬렉션: WRITE 또는 ADMIN
- 공유 컬렉션: SHARED 또는 ADMIN
경로 파라미터 :
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| name | string | 필수 | 컬렉션 이름 |
요청 바디 :
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| key | any | 선택 | 문서의 고유 키. 키 생성 방식이 CLIENT 방식일 때만 지정할 수 있으며, 데이터 타입은 컬렉션의 keyColumnType에 따라 결정된다. key를 지정하지 않으면, 서버가 자동으로 UUID 키를 자동으로 생성한다. |
| document | object | 필수 | 컬렉션에 저장할 문서의 정보를 JSON 데이터로 입력 |
예제#
key를 지정하지 않은 경우 (UUID 키 자동 생성) :
books 컬렉션에 "1984"라는 책 정보를 JSON 문서로 저장(삽입)하는 요청 예제이다. key를 지정하지 않았으므로, 서버가 자동으로 UUID 키를 생성하여 문서를 삽입한다.
curl -X POST http://localhost:8080/api/collections/books/documents \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"document": {
"title": "1984",
"author": "George Orwell",
"year": 1949
}
}'
key를 직접 지정한 경우 :
products 컬렉션에 상품 정보를 JSON 문서로 저장하는 요청 예제이다. 이 예제에서는 key를 "PROD-001"로 직접 지정하여 문서를 삽입한다.
curl -X POST http://localhost:8080/api/collections/products/documents \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"key": "PROD-001",
"document": {
"name": "노트북",
"price": 1500000
}
}'
응답 (201 Created):
{
"insertedKey": "550e8400-e29b-41d4-a716-446655440000",
"keyType": "String",
"affectedCount": 1
}
| 필드 | 설명 |
|---|---|
| insertedKey | 생성된 문서의 키 |
| keyType | 키 타입 |
| affectedCount | 삽입된 문서 수 |
7.1.2 다중 문서 삽입 (배치 작업)#
여러 개의 문서를 한 번의 요청으로 삽입할 수 있다.
엔드포인트 :
POST /api/collections/{name}/documents/batch
필요 권한 :
- 일반 컬렉션: WRITE 또는 ADMIN
- 공유 컬렉션: SHARED 또는 ADMIN
경로 파라미터 :
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| name | string | 필수 | 컬렉션 이름 |
요청 바디 :
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| documents | array | 필수 | 삽입할 문서 목록 |
- 예시
{
"documents": [
{"key": "key1", "document": {"field": "value1"}},
{"key": "key2", "document": {"field": "value2"}}
]
}
예제#
curl -X POST http://localhost:8080/api/collections/products/documents/batch \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"documents": [
{"key": "key1", "document": {"field": "value1"}},
{"key": "key2", "document": {"field": "value2"}}
]
}'
응답 (201 Created):
{
"results": [
{"insertedKey": "key1", "keyType": "String", "affectedCount": 1},
{"insertedKey": "key2", "keyType": "String", "affectedCount": 1}
]
}
| 필드 | 설명 |
|---|---|
| results | 각 문서 삽입 결과 목록 |
7.2 문서 조회#
7.2.1 전체 문서 조회#
컬렉션에 저장된 문서를 조회하는 API이며, offset과 limit을 사용하여 페이징 방식으로 조회할 수도 있다.
엔드포인트 :
GET /api/collections/{name}/documents
필요 권한 :
- 일반 컬렉션: READ 또는 WRITE 또는 ADMIN
- 공유 컬렉션: READ 또는 WRITE 또는 SHARED 또는 ADMIN
경로 파라미터 :
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| name | string | 필수 | 컬렉션 문서 |
쿼리 파라미터 :
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
offset |
integer | 선택 | 건너뛸 문서 수를 지정. 기본값은 0 |
limit |
integer | 선택 | 반환할 문서 수를 지정. 기본값은 100 |
예제#
페이징 조회 :
# 첫 페이지 (1-20)
curl -X GET "http://localhost:8080/api/collections/books/documents?offset=0&limit=20" \
-H "Authorization: Bearer ${TOKEN}"
# 두 번째 페이지 (21-40)
curl -X GET "http://localhost:8080/api/collections/books/documents?offset=20&limit=20" \
-H "Authorization: Bearer ${TOKEN}"
응답 (200 OK):
{
"documents": [
{
"key": "uuid-1",
"keyType": "String",
"document": {...},
"created": "2025-01-15T10:30:00",
"createdBy": "mobileApp",
"lastModified": "2025-01-15T10:30:00",
"lastModifiedBy": "mobileApp"
}
],
"totalCount": 150,
"hasMore": true
}
| 필드 | 타입 | 설명 |
|---|---|---|
| documents | array | 조회된 문서 목록 |
| totalCount | integer | 조회 조건에 해당하는 전체 문서 수 |
| hasMore | boolean | 추가 페이지 존재 여부 |
7.2.2 키로 단일 문서 조회#
문서의 키를 사용하여 특정 문서를 조회한다.
엔드포인트 :
GET /api/collections/{name}/documents/{key}
필요 권한 :
- 일반 컬렉션: READ 또는 WRITE 또는 ADMIN
- 공유 컬렉션: READ 또는 WRITE 또는 SHARED 또는 ADMIN
경로 파라미터 :
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| collectionName | string | 필수 | 컬렉션의 이름 |
| key | string | 필수 | 문서 키 |
예제#
books 컬렉션에 저장된 문서 중에서 key가 "550e8400-e29b-41d4-a716-446655440000"인 단일 문서를 조회하는 요청 예제이다.
curl -X GET http://localhost:8080/api/collections/books/documents/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer ${TOKEN}"
응답 (200 OK):
{
"key": "550e8400-e29b-41d4-a716-446655440000",
"keyType": "String",
"keyFieldName": "_ID",
"document": {
"title": "1984",
"author": "George Orwell",
"year": 1949
},
"created": "2025-01-15T10:30:00",
"createdBy": "mobileApp",
"lastModified": "2025-01-15T10:30:00",
"lastModifiedBy": "mobileApp"
}
7.2.3 조건부 문서 조회 (필터)#
엔드포인트 :
POST /api/collections/{name}/documents/search
필요 권한 :
- 일반 컬렉션: READ 또는 WRITE 또는 ADMIN
- 공유 컬렉션: READ 또는 WRITE 또는 SHARED 또는 ADMIN
경로 파라미터 :
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| collectionName | string | 필수 | 컬렉션의 이름 |
요청 바디 :
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| filter | object | 선택 | 필터 조건. 생략 시 전체 문서 반환 |
| limit | integer | 선택 | 반환할 최대 문서 수로 1~1000 범위내 지정 가능 |
| offset | integer | 선택 | 건너뛸 문서 수(페이지네이션) |
| sort | object | 선택 | 정렬 기준 - 1: 오름차순 - -1: 내림차순 |
- 예시
{
"filter": {
"category": "electronics",
"price": {"$gt": 100}
},
"limit": 10,
"offset": 0,
"sort": {
"price": 1,
"name": -1
}
}
예제#
복합 조건 검색 :
curl -X POST http://localhost:8080/api/collections/products/documents/search \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"$and": [
{"category": "electronics"},
{"price": {"$gte": 10000, "$lte": 100000}},
{"inStock": true}
]
},
"limit": 20,
"offset": 0,
"sort": {"price": 1}
}'
응답 (200 OK):
{
"documents": [...],
"totalCount": 25,
"hasMore": true
}
7.2.4 JsonPath로 문서 조회#
엔드포인트 :
POST /api/collections/{name}/documents/jsonpath
필요 권한 :
- 일반 컬렉션: READ 또는 WRITE 또는 ADMIN
- 공유 컬렉션: READ 또는 WRITE 또는 SHARED 또는 ADMIN
경로 파라미터 :
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| collectionName | string | 필수 | 컬렉션의 이름 |
요청 바디 :
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| jsonPath | string | 필수 | JSONPath 표현식 |
| limit | integer | 선택 | 반환할 최대 문서 수 |
| offset | integer | 선택 | 건너뛸 문서 수(페이지네이션) |
| sort | object | 선택 | 정렬 기준 - 1: 오름차순 - -1: 내림차순 |
- 예시
{
"jsonPath": "$.items[*]?(@.price > 100)",
"offset": 0,
"limit": 10
}
예제#
curl -X POST http://localhost:8080/api/collections/orders/documents/jsonpath \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"jsonPath": "$?(@.address.city == \"Seoul\")",
"limit": 50
}'
7.3 문서 교체#
7.3.1 키로 문서 교체#
지정한 key를 가진 기존의 문서를 전체 교체한다.
엔드포인트 :
PUT /api/collections/{name}/documents/{key}
필요 권한 :
- 일반 컬렉션: WRITE 또는 ADMIN
- 공유 컬렉션: SHARED 또는 ADMIN
경로 파라미터 :
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| name | string | 필수 | 컬렉션의 이름 |
| key | string | 필수 | 교체할 문서 키 |
요청 바디 :
새로 교체할 문서의 내용을 전달한다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| document | object | 필수 | 새로 교체할 문서의 정보 |
예제#
books 컬렉션에서 key가 "550e8400-e29b-41d4-a716-446655440000"인 문서를 새로운 문서로 교체하는 요청 예제이다.
curl -X PUT http://localhost:8080/api/collections/books/documents/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"document": {
"title": "1984",
"author": "George Orwell",
"year": 1949,
"edition": "revised"
}
}'
응답 (200 OK):
{
"affectedCount": 1
}
7.3.2 조건부 문서 교체#
조건(filter)에 맞는 문서 1건을 찾아 새로운 문서로 교체하는 요청이다.
엔드포인트 :
PUT /api/collections/{name}/documents/replace-one
필요 권한 :
- 일반 컬렉션: WRITE 또는 ADMIN
- 공유 컬렉션: SHARED 또는 ADMIN
경로 파라미터 :
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| name | string | 필수 | 컬렉션의 이름 |
요청 바디 :
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| filter | object | 필수 | 필터 조건 |
| document | object | 필수 | 새로 교체할 문서의 정보 |
예제#
curl -X PUT http://localhost:8080/api/collections/tasks/documents/replace-one \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filter": {"taskId": "TASK-001", "status": "pending"},
"document": {
"taskId": "TASK-001",
"status": "in_progress",
"startedAt": "2025-01-15T10:30:00"
}
}'
응답 (200 OK):
{
"affectedCount": 1
}
7.4 문서 삭제#
7.4.1 키로 문서 삭제#
엔드포인트 :
DELETE /api/collections/{name}/documents/{key}
필요 권한 :
- 일반 컬렉션: WRITE 또는 ADMIN
- 공유 컬렉션: SHARED 또는 ADMIN
경로 파라미터 :
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| collectionName | string | 필수 | 컬렉션의 이름 |
| key | string | 필수 | 삭제할 문서 키 |
예제#
curl -X DELETE http://localhost:8080/api/collections/books/documents/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer ${TOKEN}"
응답 (200 OK):
{
"affectedCount": 1
}
7.4.2 조건부 단일 문서 삭제#
필터 조건에 일치하는 첫번째 문서를 삭제한다.
엔드포인트 :
POST /api/collections/{name}/documents/delete-one
필요 권한 :
- 일반 컬렉션: WRITE 또는 ADMIN
- 공유 컬렉션: SHARED 또는 ADMIN
요청 바디 :
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| filter | object | 선택 | 필터 조건. 생략 시 전체 문서 반환 |
| limit | integer | 선택 | 반환할 최대 문서 수 |
| offset | integer | 선택 | 건너뛸 문서 수(페이지네이션) |
| sort | object | 선택 | 정렬 기준 - 1: 오름차순 - -1: 내림차순 |
예제#
curl -X POST http://localhost:8080/api/collections/logs/documents/delete-one \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filter": {"level": "DEBUG", "expired": true}
}'
7.4.3 조건부 다중 문서 삭제#
필터 조건에 일치하는 모든 문서를 삭제한다.
엔드포인트 :
POST /api/collections/{name}/documents/delete-many
필요 권한 :
- 일반 컬렉션: WRITE 또는 ADMIN
- 공유 컬렉션: SHARED 또는 ADMIN
요청 바디 :
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| filter | object | 선택 | 필터 조건. 생략 시 전체 문서 반환 |
| limit | integer | 선택 | 반환할 최대 문서 수 |
| offset | integer | 선택 | 건너뛸 문서 수(페이지네이션) |
| sort | object | 선택 | 정렬 기준 - 1: 오름차순 - -1: 내림차순 |
예제#
curl -X POST http://localhost:8080/api/collections/logs/documents/delete-many \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"createdAt": {"$lt": "2024-01-01"}
}
}'
응답 (200 OK):
{
"affectedCount": 150
}
7.5 문서 개수 조회#
7.5.1 전체 문서 개수#
컬렉션에 포함된 문서의 총 개수를 반환한다.
엔드포인트 :
GET /api/collections/{name}/documents/count
필요 권한 :
- 일반 컬렉션: READ 또는 WRITE 또는 ADMIN
- 공유 컬렉션: READ 또는 WRITE 또는 SHARED 또는 ADMIN
예제#
curl -X GET http://localhost:8080/api/collections/orders/documents/count \
-H "Authorization: Bearer ${TOKEN}"
응답 (200 OK):
{
"count": 1500
}
7.5.2 조건부 문서 개수#
필터 조건에 일치하는 모든 문서의 개수를 반환한다.
엔드포인트 :
POST /api/collections/{name}/documents/count
필요 권한 :
- 일반 컬렉션: READ 또는 WRITE 또는 ADMIN
- 공유 컬렉션: READ 또는 WRITE 또는 SHARED 또는 ADMIN
요청 바디 :
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| filter | object | 선택 | 필터 조건. 생략 시 전체 문서 반환 |
| limit | integer | 선택 | 반환할 최대 문서 수 |
| offset | integer | 선택 | 건너뛸 문서 수(페이지네이션) |
| sort | object | 선택 | 정렬 기준 - 1: 오름차순 - -1: 내림차순 |
예제#
curl -X POST http://localhost:8080/api/collections/orders/documents/count \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"status": "completed",
"totalAmount": {"$gte": 100000}
}
}'