컬렉션

Show: All versions v2 only

Collections API는 구형 클라이언트와 SDK를 위한 v1 호환성 계층(compatibility surface)이며, deprecated 상태의 API다. 내부적으로 collection(컬렉션)과 bucket(버킷)은 동일한 기본 저장 객체를 가리키며, 컬렉션 검색은 버킷 검색에 위임된다.

참고: 새로운 연동에서는 이 문서의 경로 대신 Buckets와 POST /v2/buckets/\{bucket_id\}/search를 사용하세요.

API 버전

버전	상태	경로 접두어	안내
v1	폐기 예정	/v1/collections/*	호환용이다. 새로운 기능이 추가되지 않는다.
v2	현재	/v2/buckets/*	모든 신규 연동에 사용하세요.

v1 컬렉션 검색 엔드포인트는 Deprecation: true, Warning, 그리고 POST /v2/buckets/\{bucket_id\}/search를 가리키는 Link 후속 버전 헤더를 반환한다.

인증

모든 컬렉션 API 엔드포인트는 Authorization 헤더에 API 키가 필요한다.

Authorization: Bearer sch_xxxxxxxxxxxxxxxxxxxx

각 엔드포인트는 특정 API 키 스코프(scope)도 필요한다.

Scope	Access
collections:manage	컬렉션을 생성하고 삭제한다.
collections:read	컬렉션을 목록 조회하거나, 단일 조회하거나, 통계를 읽는다.
collections:use	벡터를 추가(upsert)하거나 삭제한다.
embed	문서를 임베딩하고 추가한다(/documents 및 /add).
query	컬렉션을 검색한다.

/v1/organizations/\{org_id\} 아래의 대시보드 세션 경로는 대상 조직(organization)의 멤버인 로그인한 사용자가 필요한다.

컬렉션 객체

필드	타입	설명
id	string	고유한 컬렉션 식별자이다.
name	string	사람이 읽을 수 있는 컬렉션 이름이다.
dimension	integer	컬렉션의 임베딩 차원이다.
model	string	컬렉션에 사용되는 임베딩 모델이다.
backend	string	벡터 백엔드이다. 예: engine.
vector_count	integer	색인된 벡터의 개수이다.

POST /v1/collections

새 컬렉션을 생성한다. 컬렉션 이름은 조직 내에서 고유해야 한다.

요청 본문

필드	타입	필수	기본값	설명
name	string	Yes	,	컬렉션 이름이다.
dimension	integer	Yes	,	컬렉션의 벡터 차원이다.
model	string	No	schift-embed-1-small	사용할 임베딩 모델이다.
backend	string	No	engine	벡터 백엔드이다. 지원 값: engine, pgvector, weaviate, qdrant, pinecone, milvus, chroma, elasticsearch, redis, mongodb.

요청 예시

{
  "name": "legacy-faq",
  "dimension": 1024,
  "model": "schift-embed-1-small",
  "backend": "engine"
}

응답 예시

{
  "id": "abc123def456",
  "name": "legacy-faq",
  "dimension": 1024,
  "model": "schift-embed-1-small",
  "backend": "engine",
  "vector_count": 0
}

오류

상태	원인
400	잘못된 백엔드 또는 요청 본문이다.
403	API 키에 collections:manage 스코프가 없는다.
409	동일한 이름의 컬렉션이 이미 존재한다.

GET /v1/collections

인증된 조직의 컬렉션을 목록 조회한다.

응답 예시

[
  {
    "id": "abc123def456",
    "name": "legacy-faq",
    "dimension": 1024,
    "model": "schift-embed-1-small",
    "backend": "engine",
    "vector_count": 128
  }
]

오류

상태	원인
403	API 키에 collections:read 스코프가 없는다.

GET /v1/collections/{name}

이름으로 단일 컬렉션을 조회한다.

경로 매개변수

Parameter	Type	Description
name	string	컬렉션 이름이다.

응답 예시

{
  "id": "abc123def456",
  "name": "legacy-faq",
  "dimension": 1024,
  "model": "schift-embed-1-small",
  "backend": "engine",
  "vector_count": 128
}

오류

상태	원인
403	API 키에 collections:read 스코프가 없는다.
404	컬렉션을 찾을 수 없는다.

GET /v1/collections/{name}/stats

컬렉션의 현재 벡터 개수와 메타데이터를 반환한다. 개수는 벡터 백엔드에서 직접 읽어오며, 저장된 개수도 갱신된다.

경로 매개변수

Parameter	Type	Description
name	string	컬렉션 이름이다.

응답 예시

{
  "name": "legacy-faq",
  "dimension": 1024,
  "model": "schift-embed-1-small",
  "backend": "engine",
  "vector_count": 128
}

오류

상태	원인
403	API 키에 collections:read 스코프가 없는다.
404	컬렉션을 찾을 수 없는다.

DELETE /v1/collections/{name}

컬렉션을 삭제하고 벡터 테이블을 제거한다.

경로 매개변수

Parameter	Type	Description
name	string	컬렉션 이름이다.

응답

성공 시 204 No Content를 반환한다.

오류

상태	원인
403	API 키에 collections:manage 스코프가 없는다.
404	컬렉션을 찾을 수 없는다.

POST /v1/collections/{collection}/vectors

컬렉션에 원시 벡터를 추가(upsert)한다. 이미 존재하는 벡터 id는 대첩다.

참고: 요청당 최대 배치 크기는 2048개 벡터이다.

경로 매개변수

Parameter	Type	Description
collection	string	컬렉션 이름이다.

요청 본문

필드	타입	필수	설명
vectors	object[]	Yes	벡터 항목 배열이다.
vectors[].id	string	Yes	고유한 벡터 식별자이다.
vectors[].values	number[]	Yes	임베딩 값이다. 컬렉션 차원과 일치해야 한다.
vectors[].metadata	object	No	자유 형식의 메타데이터이다.

요청 예시

{
  "vectors": [
    {
      "id": "vec-1",
      "values": [0.01, -0.02, 0.03],
      "metadata": {"source": "faq"}
    }
  ]
}

응답 예시

{
  "upserted": 1
}

오류

상태	원인
400	배치 크기가 2048을 초과하거나, 벡터 차원이 컬렉션과 일치하지 않는다.
402	할당량을 초과했다.
403	API 키에 collections:use 스코프가 없는다.
404	컬렉션을 찾을 수 없는다.

DELETE /v1/collections/{collection}/vectors

ID로 컬렉션에서 특정 벡터를 삭제한다.

경로 매개변수

Parameter	Type	Description
collection	string	컬렉션 이름이다.

요청 본문

필드	타입	필수	설명
ids	string[]	Yes	삭제할 벡터 ID이다. 비어 있으면 안 된다.

요청 예시

{
  "ids": ["vec-1", "vec-2"]
}

응답 예시

{
  "deleted": 2
}

오류

상태	원인
400	ids가 비어 있는다.
403	API 키에 collections:use 스코프가 없는다.
404	컬렉션을 찾을 수 없는다.
501	설정된 백엔드가 ID 기반 벡터 삭제를 지원하지 않는다.

POST /v1/collections/{collection}/documents

문서를 임베딩하고 그 결과 벡터를 컬렉션에 저장한다. 요청 본문에는 대상 임베딩 모델이 포함된다.

참고: 요청당 최대 배치 크기는 2048개 문서이다.

경로 매개변수

Parameter	Type	Description
collection	string	컬렉션 이름이다.

요청 본문

필드	타입	필수	설명
documents	object[]	Yes	문서 항목 배열이다.
documents[].id	string	No	문서 식별자이다. 생략하면 자동 생성된다.
documents[].text	string	Yes	임베딩할 텍스트이다.
documents[].metadata	object	No	자유 형식의 메타데이터이다.
model	string	Yes	임베딩 모델 ID이다.

요청 예시

{
  "documents": [
    {
      "id": "doc-1",
      "text": "How do I reset my password?",
      "metadata": {"category": "support"}
    }
  ],
  "model": "schift-embed-1-small"
}

응답 예시

{
  "upserted": 1
}

오류

상태	원인
400	배치 크기가 2048을 초과하거나, 임베딩 모델을 알 수 없는다.
402	할당량을 초과했다.
403	API 키에 필요한 collections:use 또는 embed 스코프가 없는다.
404	컬렉션을 찾을 수 없는다.

POST /v1/collections/{name}/add

문서를 임베딩하여 컬렉션에 추가한다. 컬렉션이 존재하지 않으면 dimension=1024, model=schift-embed-1-small, backend=engine으로 자동 생성된다.

참고: 요청당 최대 배치 크기는 2048개 문서이다.

경로 매개변수

Parameter	Type	Description
name	string	컬렉션 이름이다.

요청 본문

필드	타입	필수	기본값	설명
documents	string[]	Yes	,	임베딩할 원시 텍스트 문자열이다. 비어 있으면 안 된다.
ids	string[]	No	null	선택적 문서 ID이다.
metadata	object[]	No	null	선택적 메타데이터 객체로, 문서당 하나씩이다.
task	string	No	null	임베딩 태스크이다. 다음 중 하나: retrieval_query, retrieval_document, semantic_similarity, question_answering, clustering, classification, code_retrieval.
model	string	No	schift-embed-1-small	임베딩 모델 ID이다.

요청 예시

{
  "documents": [
    "How do I reset my password?",
    "Where can I download invoices?"
  ],
  "metadata": [
    {"category": "support"},
    {"category": "billing"}
  ],
  "model": "schift-embed-1-small"
}

응답 예시

{
  "collection": "legacy-faq",
  "added": 2,
  "ids": ["id-1", "id-2"]
}

오류

상태	원인
400	documents가 비어 있거나 배치 크기가 2048을 초과한다.
402	할당량을 초과했다.
403	임베딩 사용 한도에 도달했거나, API 키에 필요한 스코프가 없는다.

POST /v1/collections/{name}/search

컬렉션을 검색한다. 이 엔드포인트는 bucket search 위에 있는 호환성 래퍼이며, 단순화된 응답을 반환한다.

경로 매개변수

Parameter	Type	Description
name	string	컬렉션 이름이다.

요청 본문

필드	타입	필수	기본값	설명
query	string	No*	,	텍스트 쿼리이다. query 또는 query_vector 중 하나는 필수이다.
query_vector	number[]	No*	,	미리 계산된 쿼리 벡터이다.
task	string	No	null	임베딩 태스크이다. 유효한 태스크 값을 참조하세요.
top_k	integer	No	10	반환할 결과 개수이다. 최대 1000.
filter	object	No	null	메타데이터 필터이다.
model	string	No	null	임베딩 또는 재정렬 모델 오버라이드이다.
mode	string	No	hybrid	검색 모드이다. vector 또는 hybrid.
rerank	boolean	No	false	재정렬을 활성화한다.
rerank_top_k	integer	No	null	재정렬의 상위 k 컷오프이다.
rerank_model	string	No	null	재정렬 모델 ID이다.
temporal	string	No	null	시간 필터이다. before, after, between, as_of, 또는 latest.
temporal_start	integer	No	null	temporal이 설정된 경우 필요한다(latest 제외).
temporal_end	integer	No	null	temporal=between인 경우 필요한다.
advanced	object	No	null	고급 스코어링 파라미터이다. graph_weight, temporal_weight, hit_weight, vector_weight, bm25_weight, hops, temporal_half_life_days.
expand_context	object	No	null	컨텍스트 확장 파라미터이다. window, max_extra, score_decay.

요청 예시

{
  "query": "reset password",
  "top_k": 5,
  "filter": {"category": "support"},
  "mode": "hybrid"
}

응답 예시

{
  "collection": "legacy-faq",
  "results": [
    {
      "id": "doc-1",
      "score": 0.92,
      "text": "How do I reset my password?",
      "metadata": {"category": "support"},
      "neighbors": null,
      "citation": null
    }
  ]
}

응답에는 v2 bucket search 후속 엔드포인트를 가리키는 더 이상 사용되지 않음(deprecation) 헤더도 포함된다.

Deprecation: true
Warning: 299 - "Deprecated search endpoint; migrate to /v2/buckets/{bucket_id}/search"
Link: </v2/buckets/abc123def456/search>; rel="successor-version"

오류

상태	원인
400	query와 query_vector 둘 다 제공되지 않았거나, 잘못된 시간 매개변수이다.
402	할당량을 초과했다.
403	검색 사용 한도에 도달했거나, API 키에 필요한 스코프가 없는다.
404	컬렉션을 찾을 수 없는다.

대시보드 조직 경로

이 경로는 Schift 대시보드에서 사용되며 세션 인증에 의존한다. 호출하는 사용자는 \{org_id\}의 멤버여야 한다.

GET /v1/organizations/{org_id}/collections

조직의 컬렉션을 목록 조회한다.

GET /v1/organizations/{org_id}/collections/{name}

조직에서 단일 컬렉션을 조회한다.

POST /v1/organizations/{org_id}/collections

조직에 컬렉션을 생성한다.

요청 본문

필드	타입	필수	기본값	설명
name	string	Yes	,	컬렉션 이름이다.
model	string	No	schift-embed-1-small	임베딩 모델이다.
dimension	integer	No	model default or 1024	벡터 차원이다.
backend	string	No	engine	벡터 백엔드이다.

오류

상태	원인
400	name이 누락되었거나 지원하지 않는 백엔드이다.
403	사용자가 조직 멤버가 아니거나, 요금제의 컬렉션 한도에 도달했다.

DELETE /v1/organizations/{org_id}/collections/{name}

조직에서 컬렉션을 삭제한다. 204 No Content를 반환한다.

GET /v1/organizations/{org_id}/collections/{name}/stats

실시간 벡터 개수를 포함한 컬렉션 통계를 반환한다.

GET /v1/organizations/{org_id}/vectordb-configs

조직 수준의 VectorDB 설정을 목록 조회한다.

PUT /v1/organizations/{org_id}/vectordb-configs

백엔드의 VectorDB 설정을 생성하거나 업데이트한다.

요청 본문

필드	타입	필수	설명
collection_id	string	Yes	대상 컬렉션 ID이다.
backend	string	Yes	백엔드 이름이다. 지원되는 값이어야 한다.
endpoint	string	No	백엔드 엔드포인트 URL이다.
api_key	string	No	백엔드 인증 정보이다.
extra	object	No	추가적인 백엔드별 옵션이다.

응답 예시

{
  "status": "ok"
}

오류

상태	원인
400	지원하지 않는 백엔드이다.
403	사용자가 조직 멤버가 아닙다.

같이 보기

• Buckets
• Query
• Embeddings