コレクション

Show: All versions v2 only

コレクション APIは、古いクライアントとSDKのための非推奨のv1互換サーフェスです。内部的には、コレクションとバケットは同じ基盤のストレージオブジェクトを指し、コレクション検索はバケット検索に委任されます。

注意: 新しい統合には、ここで文書化されているルートの代わりにバケットとPOST /v2/buckets/\{bucket_id\}/searchを使用してください。

APIバージョン

Version	Status	Path prefix	Guidance
v1	Deprecated	/v1/collections/*	互換性のみ。新機能は追加されません。
v2	Current	/v2/buckets/*	すべての新しい統合に使用してください。

v1コレクション検索エンドポイントは、Deprecation: true、Warning、およびLinkの後継バージョンヘッダーを返し、POST /v2/buckets/\{bucket_id\}/searchを指します。

認証

すべてのコレクションAPIエンドポイントには、AuthorizationヘッダーにAPIキーが必要です：

Authorization: Bearer sch_xxxxxxxxxxxxxxxxxxxx

各エンドポイントには特定のAPIキーのスコープも必要です：

Scope	Access
collections:manage	コレクションの作成と削除。
collections:read	コレクションの一覧表示、取得、または統計の読み取り。
collections:use	ベクトルのアップサートまたは削除。
embed	ドキュメントの埋め込みとアップサート（/documentsと/add）。
query	コレクションの検索。

/v1/organizations/\{org_id\}の下のダッシュボードセッションルートには、対象組織のメンバーであるサインイン済みユーザーが必要です。

コレクションオブジェクト

Field	Type	Description
id	string	ユニークなコレクション識別子。
name	string	人間が読めるコレクション名。
dimension	integer	コレクションの埋め込み次元。
model	string	コレクションに使用される埋め込みモデル。
backend	string	ベクトルバックエンド、例：engine。
vector_count	integer	インデックスされたベクトルの数。

POST /v1/collections

新しいコレクションを作成します。コレクション名は組織内でユニークでなければなりません。

リクエストボディ

Field	Type	Required	Default	Description
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
}

エラー

Status	Cause
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
  }
]

エラー

Status	Cause
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
}

エラー

Status	Cause
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
}

エラー

Status	Cause
403	APIキーにcollections:readスコープがありません。
404	コレクションが見つかりません。

DELETE /v1/collections/{name}

コレクションを削除し、そのベクトルテーブルを削除します。

パスパラメータ

Parameter	Type	Description
name	string	コレクション名。

レスポンス

成功時に204 No Contentを返します。

エラー

Status	Cause
403	APIキーにcollections:manageスコープがありません。
404	コレクションが見つかりません。

POST /v1/collections/{collection}/vectors

生のベクトルをコレクションにアップサートします。既に存在する場合、各ベクトルidは置き換えられます。

注意: 最大バッチサイズはリクエストごとに2048ベクトルです。

パスパラメータ

Parameter	Type	Description
collection	string	コレクション名。

リクエストボディ

Field	Type	Required	Description
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
}

エラー

Status	Cause
400	バッチサイズが2048を超えているか、ベクトル次元がコレクションと一致しません。
402	クォータを超えました。
403	APIキーにcollections:useスコープがありません。
404	コレクションが見つかりません。

DELETE /v1/collections/{collection}/vectors

IDで特定のベクトルをコレクションから削除します。

パスパラメータ

Parameter	Type	Description
collection	string	コレクション名。

リクエストボディ

Field	Type	Required	Description
ids	string[]	Yes	削除するベクトルID。空であってはなりません。

リクエスト例

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

レスポンス例

{
  "deleted": 2
}

エラー

Status	Cause
400	idsが空です。
403	APIキーにcollections:useスコープがありません。
404	コレクションが見つかりません。
501	設定されたバックエンドはIDによるベクトル削除をサポートしていません。

POST /v1/collections/{collection}/documents

ドキュメントを埋め込み、結果のベクトルをコレクションに保存します。リクエストボディにはターゲット埋め込みモデルが含まれます。

注意: 最大バッチサイズはリクエストごとに2048ドキュメントです。

パスパラメータ

Parameter	Type	Description
collection	string	コレクション名。

リクエストボディ

Field	Type	Required	Description
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
}

エラー

Status	Cause
400	バッチサイズが2048を超えているか、埋め込みモデルが不明です。
402	クォータを超えました。
403	必要なcollections:useまたはembedスコープがAPIキーにありません。
404	コレクションが見つかりません。

POST /v1/collections/{name}/add

ドキュメントを埋め込み、コレクションに追加します。コレクションが存在しない場合、dimension=1024、model=schift-embed-1-small、backend=engineで自動作成されます。

注意: 最大バッチサイズはリクエストごとに2048ドキュメントです。

パスパラメータ

Parameter	Type	Description
name	string	コレクション名。

リクエストボディ

Field	Type	Required	Default	Description
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"]
}

エラー

Status	Cause
400	documentsが空であるか、バッチサイズが2048を超えています。
402	クォータを超えました。
403	埋め込み権限の制限に達したか、APIキーに必要なスコープがありません。

POST /v1/collections/{name}/search

コレクションを検索します。このエンドポイントはバケット検索の互換性ラッパーであり、簡略化されたレスポンスを返します。

パスパラメータ

Parameter	Type	Description
name	string	コレクション名。

リクエストボディ

Field	Type	Required	Default	Description
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バケット検索の後継を指す非推奨ヘッダーも含まれます：

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

エラー

Status	Cause
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

組織内にコレクションを作成します。

リクエストボディ

Field	Type	Required	Default	Description
name	string	Yes	—	コレクション名。
model	string	No	schift-embed-1-small	埋め込みモデル。
dimension	integer	No	model default or 1024	ベクトル次元。
backend	string	No	engine	ベクトルバックエンド。

エラー

Status	Cause
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設定を作成または更新します。

リクエストボディ

Field	Type	Required	Description
collection_id	string	Yes	ターゲットコレクションID。
backend	string	Yes	バックエンド名。サポートされている必要があります。
endpoint	string	No	バックエンドエンドポイントURL。
api_key	string	No	バックエンドの資格情報。
extra	object	No	追加のバックエンド固有のオプション。

レスポンス例

{
  "status": "ok"
}

エラー

Status	Cause
400	サポートされていないバックエンド。
403	ユーザーが組織のメンバーではありません。

参照

• バケット
• クエリ
• エンベディング