Skip to main content
Core.Today

Databases

OpenSearch 기반의 고성능 문서 데이터베이스입니다. 스키마 정의, CRUD, 전문 검색, 벡터 검색을 지원합니다.

주요 기능

  • 스키마 정의: 필드 타입, 인덱싱 옵션, 벡터 필드 설정
  • CRUD 작업: 단일/대량 문서 생성, 조회, 수정, 삭제
  • 전문 검색: OpenSearch Query DSL 지원 (match, term, bool, range)
  • 벡터 검색: k-NN 기반 시맨틱 검색 (Pro 플랜 이상)
  • 집계: terms, date_histogram, 통계 집계
1

데이터베이스 생성

스키마와 함께 새 데이터베이스를 생성합니다. 데이터베이스 이름은 팀 내에서 고유해야 합니다.

curl -X POST https://api.core.today/v1/databases \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "products",
    "display_name": "Product Catalog",
    "description": "E-commerce product database",
    "schema_fields": {
      "title": {"type": "text", "index": true},
      "description": {"type": "text", "index": true},
      "price": {"type": "float"},
      "category": {"type": "keyword"},
      "tags": {"type": "keyword"},
      "in_stock": {"type": "boolean"},
      "created_at": {"type": "date"}
    }
  }'

응답 예시

{
  "database_uid": "db_abc123",
  "name": "products",
  "display_name": "Product Catalog",
  "description": "E-commerce product database",
  "team_id": "team_xyz",
  "schema_fields": {...},
  "document_count": 0,
  "created_at": "2024-12-26T10:00:00Z"
}

지원 필드 타입

타입설명예시
text전문 검색이 가능한 텍스트"Product description..."
keyword정확한 매칭용 문자열 (필터, 집계)"electronics"
integer정수42
float부동 소수점19.99
booleantrue/falsetrue
dateISO 8601 날짜"2024-12-26T10:00:00Z"
knn_vector벡터 검색용 임베딩 (Pro+)[0.1, 0.2, ...]

벡터 필드 설정

벡터 검색을 위한 필드는 dimension과 space_type을 지정해야 합니다:

"embedding": {
  "type": "knn_vector",
  "dimension": 1536,
  "space_type": "cosinesimil"
}
2

문서 CRUD

문서 생성

# 단일 문서 생성
curl -X POST https://api.core.today/v1/databases/{database_uid}/documents \
  -H "X-API-Key: cdt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "product-001",
    "data": {
      "title": "Wireless Headphones",
      "description": "High-quality wireless headphones with noise cancellation",
      "price": 199.99,
      "category": "electronics",
      "tags": ["audio", "wireless", "premium"],
      "in_stock": true
    }
  }'

대량 문서 생성

curl -X POST https://api.core.today/v1/databases/{database_uid}/documents/_bulk \
  -H "X-API-Key: cdt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {"id": "product-001", "data": {"title": "Product 1", "price": 99.99}},
      {"id": "product-002", "data": {"title": "Product 2", "price": 149.99}},
      {"id": "product-003", "data": {"title": "Product 3", "price": 199.99}}
    ]
  }'

응답: 성공/실패 개수와 에러 상세 정보가 반환됩니다.

문서 조회

# 특정 문서 조회
curl https://api.core.today/v1/databases/{database_uid}/documents/{doc_id} \
  -H "X-API-Key: cdt_your_api_key"

# 문서 목록 조회 (페이지네이션)
curl "https://api.core.today/v1/databases/{database_uid}/documents?size=20&from=0" \
  -H "X-API-Key: cdt_your_api_key"

문서 수정

# 전체 교체 (PUT)
curl -X PUT https://api.core.today/v1/databases/{database_uid}/documents/{doc_id} \
  -H "X-API-Key: cdt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"data": {"title": "Updated Title", "price": 299.99, ...}}'

# 부분 수정 (PATCH)
curl -X PATCH https://api.core.today/v1/databases/{database_uid}/documents/{doc_id} \
  -H "X-API-Key: cdt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"data": {"price": 179.99}}'

문서 삭제

curl -X DELETE https://api.core.today/v1/databases/{database_uid}/documents/{doc_id} \
  -H "X-API-Key: cdt_your_api_key"
3

검색

OpenSearch Query DSL을 사용한 강력한 검색 기능을 제공합니다.

전문 검색 (Full-text)

curl -X POST https://api.core.today/v1/databases/{database_uid}/search \
  -H "X-API-Key: cdt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": {
        "description": "wireless headphones"
      }
    },
    "size": 10,
    "from": 0
  }'

복합 검색 (Boolean Query)

{
  "query": {
    "bool": {
      "must": [
        {"match": {"description": "headphones"}}
      ],
      "filter": [
        {"term": {"category": "electronics"}},
        {"range": {"price": {"gte": 100, "lte": 300}}}
      ],
      "should": [
        {"term": {"in_stock": true}}
      ]
    }
  },
  "sort": [
    {"price": {"order": "asc"}}
  ],
  "highlight": {
    "fields": {"description": {}}
  }
}

검색 응답 예시

{
  "total": 42,
  "hits": [
    {
      "id": "product-001",
      "score": 1.5,
      "data": {
        "title": "Wireless Headphones",
        "price": 199.99,
        ...
      },
      "highlight": {
        "description": ["High-quality <em>wireless</em> <em>headphones</em>..."]
      }
    }
  ]
}
4

벡터 검색 (k-NN)

Pro+

임베딩 벡터를 사용한 시맨틱 유사도 검색입니다. AI 모델로 생성한 텍스트/이미지 임베딩을 저장하고 검색할 수 있습니다.

벡터 필드가 있는 스키마

{
  "name": "articles",
  "schema_fields": {
    "title": {"type": "text"},
    "content": {"type": "text"},
    "embedding": {
      "type": "knn_vector",
      "dimension": 1536,
      "space_type": "cosinesimil"
    }
  }
}

벡터 검색 요청

curl -X POST https://api.core.today/v1/databases/{database_uid}/search/vector \
  -H "X-API-Key: cdt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "field": "embedding",
    "vector": [0.1, 0.2, 0.3, ...],
    "k": 10,
    "filter": {
      "term": {"category": "technology"}
    }
  }'

임베딩 생성 팁

OpenAI의 text-embedding-3-small (1536차원) 또는 Cohere의 임베딩 모델을 사용하여 텍스트를 벡터로 변환할 수 있습니다. LLM API를 통해 임베딩을 생성하고 데이터베이스에 저장하세요.

5

집계 (Aggregations)

데이터 분석을 위한 집계 기능을 제공합니다.

curl -X POST https://api.core.today/v1/databases/{database_uid}/aggregate \
  -H "X-API-Key: cdt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {"match_all": {}},
    "aggregations": {
      "by_category": {
        "terms": {"field": "category", "size": 10}
      },
      "avg_price": {
        "avg": {"field": "price"}
      },
      "price_ranges": {
        "range": {
          "field": "price",
          "ranges": [
            {"to": 100},
            {"from": 100, "to": 200},
            {"from": 200}
          ]
        }
      }
    }
  }'

집계 응답 예시

{
  "total": 1000,
  "aggregations": {
    "by_category": {
      "buckets": [
        {"key": "electronics", "doc_count": 350},
        {"key": "clothing", "doc_count": 280},
        ...
      ]
    },
    "avg_price": {"value": 149.99},
    "price_ranges": {
      "buckets": [
        {"key": "*-100.0", "doc_count": 200},
        {"key": "100.0-200.0", "doc_count": 500},
        {"key": "200.0-*", "doc_count": 300}
      ]
    }
  }
}
6

데이터베이스 관리

데이터베이스 목록

curl https://api.core.today/v1/databases \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN"

필드 추가

기존 데이터베이스에 새 필드를 추가할 수 있습니다. 기존 필드의 타입은 변경할 수 없습니다.

curl -X POST https://api.core.today/v1/databases/{database_uid}/fields \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "rating": {"type": "float"},
      "reviews_count": {"type": "integer"}
    }
  }'

통계 조회

curl https://api.core.today/v1/databases/{database_uid}/stats \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN"

데이터베이스 삭제

주의: 데이터베이스 삭제는 되돌릴 수 없습니다. 모든 문서가 영구 삭제됩니다.

curl -X DELETE https://api.core.today/v1/databases/{database_uid} \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN"

SDK 예제

JavaScript / TypeScript

import axios from 'axios';

const api = axios.create({
  baseURL: 'https://api.core.today/v1',
  headers: { 'X-API-Key': 'cdt_your_api_key' }
});

// 문서 생성
const doc = await api.post('/databases/db_abc123/documents', {
  id: 'product-001',
  data: { title: 'My Product', price: 99.99 }
});

// 검색
const results = await api.post('/databases/db_abc123/search', {
  query: { match: { title: 'product' } },
  size: 10
});

console.log(results.data.hits);

Python

import requests

API_KEY = "cdt_your_api_key"
BASE_URL = "https://api.core.today/v1"
headers = {"X-API-Key": API_KEY}

# 문서 생성
response = requests.post(
    f"{BASE_URL}/databases/db_abc123/documents",
    headers=headers,
    json={
        "id": "product-001",
        "data": {"title": "My Product", "price": 99.99}
    }
)

# 검색
results = requests.post(
    f"{BASE_URL}/databases/db_abc123/search",
    headers=headers,
    json={
        "query": {"match": {"title": "product"}},
        "size": 10
    }
)

for hit in results.json()["hits"]:
    print(hit["data"]["title"])

Best Practices

  • 스키마 설계: 검색에 자주 사용되는 필드는 keyword 타입으로, 전문 검색이 필요한 필드는 text 타입으로 지정하세요.
  • 대량 작업: 여러 문서를 처리할 때는 /_bulk 엔드포인트를 사용하세요.
  • 페이지네이션: 대량의 결과를 처리할 때는 size와 from 파라미터를 사용하세요.
  • 필터 vs 쿼리: 정확한 값 매칭은 filter에, 점수 계산이 필요한 검색은 query에 작성하세요.
  • 벡터 검색: 벡터 차원은 임베딩 모델에 맞게 설정하고, 필터와 함께 사용하면 더 효율적입니다.
파일 업로드리포트 & 분석