테이블 데이터 API (CRUD)

테이블 row 의 생성/조회/수정/삭제 엔드포인트입니다. 모든 엔드포인트는 X-Public-Key 인증이 필요합니다.

데이터 목록 조회 (페이지네이션)

GET /v1/public/tables/:tableID/data

쿼리	타입	기본값	설명
`limit`	number	20	조회할 row 수
`offset`	number	0	시작 위치

bash

curl -X GET "https://api.connectbase.world/v1/public/tables/tbl_xxx/data?limit=10&offset=0" \
  -H "X-Public-Key: cb_pk_your_public_key"

응답:

json

{
  "data": [
    {
      "id": "row_abc",
      "data": { "name": "홍길동", "age": 30 },
      "created_at": "2026-04-09T00:00:00Z",
      "updated_at": "2026-04-09T00:00:00Z"
    }
  ],
  "total_count": 42,
  "limit": 20,
  "offset": 0,
  "execution_time_ms": 8
}

📌 응답 필드는 data 와 total_count 입니다. 사용자 필드는 row.data.xxx 안에 들어있습니다. limit / offset / execution_time_ms 도 함께 반환됩니다.

단일 데이터 조회

GET /v1/public/tables/:tableID/data/:dataID

bash

curl -X GET "https://api.connectbase.world/v1/public/tables/tbl_xxx/data/row_abc" \
  -H "X-Public-Key: cb_pk_your_public_key"

응답: 단일 DataItem ({id, data, created_at, updated_at}).

데이터 생성

POST /v1/public/tables/:tableID/data

요청 본문은 반드시 { data: {...} } 형태여야 합니다.

bash

curl -X POST "https://api.connectbase.world/v1/public/tables/tbl_xxx/data" \
  -H "X-Public-Key: cb_pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "홍길동",
      "email": "[email protected]",
      "age": 30
    }
  }'

응답: 201 Created

json

{
  "id": "019d9180-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "data": {
    "name": "홍길동",
    "email": "[email protected]",
    "age": 30
  },
  "created_at": "2026-04-21T07:12:33.491Z",
  "updated_at": "2026-04-21T07:12:33.491Z"
}

📌 생성된 row 의 ID/타임스탬프가 응답 바디에 포함되므로 별도 재조회 없이 후속 작업에 바로 사용할 수 있습니다.

벌크 생성

POST /v1/public/tables/:tableID/data/bulk

또는 일반 POST /v1/public/tables/:tableID/data 의 data 필드에 객체 배열을 넘기면 자동으로 벌크로 처리됩니다.

bash

curl -X POST "https://api.connectbase.world/v1/public/tables/tbl_xxx/data/bulk" \
  -H "X-Public-Key: cb_pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      { "name": "User 1" },
      { "name": "User 2" }
    ]
  }'

응답: 201 Created

json

{
  "created": [
    { "id": "...", "data": { "name": "User 1" }, "created_at": "...", "updated_at": "..." },
    { "id": "...", "data": { "name": "User 2" }, "created_at": "...", "updated_at": "..." }
  ],
  "total": 2,
  "success": 2
}

조건부 조회 (Query)

POST /v1/public/tables/:tableID/data/query

where, order_by, order_direction, limit, offset 가 필요할 때 사용합니다.

bash

curl -X POST "https://api.connectbase.world/v1/public/tables/tbl_xxx/data/query" \
  -H "X-Public-Key: cb_pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "where": { "age": { "$gte": 18 } },
    "order_by": "created_at",
    "order_direction": "desc",
    "limit": 10,
    "offset": 0
  }'

⚠️ select 같은 필드 화이트리스트는 현재 무시됩니다 — 모든 컬럼이 반환됩니다.

응답: { "data": [...], "total_count": N } (목록 조회와 동일).

지원 연산자

연산자	설명
`$eq`	같음
`$ne`	같지 않음
`$gt` / `$gte` / `$lt` / `$lte`	비교
`$in` / `$nin`	목록 포함 / 미포함
`$contains` / `$startsWith` / `$endsWith`	문자열 매칭
`$matches`	정규식 (MySQL REGEXP)
`$between`	범위 `[min, max]`
`$isNull`	null 여부
`$arrayContains` / `$arrayContainsAny`	JSON 배열 포함
`$or`	OR 조건 (배열)

데이터 수정

PATCH /v1/public/tables/:tableID/data/:dataID

부분 업데이트입니다. 전달한 필드만 수정되고 나머지는 유지됩니다.

bash

curl -X PATCH "https://api.connectbase.world/v1/public/tables/tbl_xxx/data/row_abc" \
  -H "X-Public-Key: cb_pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": { "age": 31 }
  }'

응답: 수정된 DataItem 전체 ({id, data, created_at, updated_at}). data 필드는 기존 + 수정본을 병합한 최종 상태입니다.

데이터 삭제

DELETE /v1/public/tables/:tableID/data/:dataID

bash

curl -X DELETE "https://api.connectbase.world/v1/public/tables/tbl_xxx/data/row_abc" \
  -H "X-Public-Key: cb_pk_your_public_key"

조건부 삭제

POST /v1/public/tables/:tableID/data/delete-where

bash

curl -X POST "https://api.connectbase.world/v1/public/tables/tbl_xxx/data/delete-where" \
  -H "X-Public-Key: cb_pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "where": { "is_active": false }
  }'

응답:

json

{ "deleted_count": 12 }

일부 row 가 실패한 경우 failed_count 가 함께 반환될 수 있습니다.

집계 (Aggregate)

POST /v1/public/aggregate

MongoDB 스타일 집계 파이프라인을 실행합니다.

bash

curl -X POST "https://api.connectbase.world/v1/public/aggregate" \
  -H "X-Public-Key: cb_pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "table_id": "tbl_xxx",
    "pipeline": [
      { "$group": { "_id": "$category", "count": { "$sum": 1 } } },
      { "$sort": { "count": -1 } }
    ]
  }'

검색 (Search)

POST /v1/public/search

전문 검색을 실행합니다.

bash

curl -X POST "https://api.connectbase.world/v1/public/search" \
  -H "X-Public-Key: cb_pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "table_id": "tbl_xxx",
    "query": "검색어",
    "fields": ["title", "content"],
    "limit": 10
  }'

자동완성

POST /v1/public/autocomplete

bash

curl -X POST "https://api.connectbase.world/v1/public/autocomplete" \
  -H "X-Public-Key: cb_pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "table_id": "tbl_xxx",
    "query": "홍",
    "field": "name",
    "limit": 5
  }'

지리 쿼리

POST /v1/public/geo

near / within / polygon 중 하나를 본문 최상단에 두어야 합니다 (query 객체로 감싸지 않습니다).

bash

curl -X POST "https://api.connectbase.world/v1/public/geo" \
  -H "X-Public-Key: cb_pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "table_id": "tbl_xxx",
    "field": "location",
    "near": {
      "center": { "latitude": 37.5, "longitude": 127.0 },
      "max_distance": 1000
    },
    "limit": 20
  }'

배치 / 트랜잭션

POST /v1/public/batch — 원자성 보장 없음 POST /v1/public/transactions — 원자성 보장

bash

curl -X POST "https://api.connectbase.world/v1/public/batch" \
  -H "X-Public-Key: cb_pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      { "type": "create", "table_id": "tbl_a", "data": { "name": "..." } },
      { "type": "update", "table_id": "tbl_b", "doc_id": "row_1", "data": { "count": 2 } },
      { "type": "delete", "table_id": "tbl_c", "doc_id": "row_2" }
    ]
  }'

데이터베이스 API

스토리지 API