メタデータ

Show: All versions v2 only

ドキュメントのメタデータは、Schiftにおける検索フィルタリング、アクセス制御、引用生成を駆動します。単一のドキュメントまたは一括でメタデータを更新でき、現在の予約済みキーのレジストリと検証制限をサーバーに問い合わせることができます。

Note: メタデータの値は文字列として保存されます。ブール値は "true" または "false" になり、数値は永続化前に文字列表現に変換されます。

メタデータモデル

ユーザーメタデータ

ユーザーメタデータは、フィルタリングやファセットに使用される任意のスカラーキー/値データです。書き込み時に server.validation.metadata によって検証されます。

Rule	Limit
Key characters	A-Z, a-z, 0-9, _, ., -
Value types	string, number, boolean, or null
Max JSON payload	4 KB
Max keys	32
Max key length	64 characters
Max value length	512 characters
Control characters	not allowed

予約済みキー

予約済みキーは、インジェスト、インデックス、スコアリング、グラフパイプラインによって所有されています。ユーザーペイロードはそれらを設定してはいけません。

Group	Keys
Identity	chunk_id, document_id, doc_id, bucket_id, ingest_job_id
Source	s3_chunk, source_path, file_name, file_type, source_kind, source_connection_id, source_row_id
Source row	source_schema, source_table, source_pk
Chunk	chunk_index, locator, text, modality, embed_model
Scoring	vector_score, bm25_score, rrf_score, rerank_score, hit_score, hit_boost
Graph / search	_graph_injected, graph_expanded, semantic_registry_boost, semantic_registry_terms, semantic_registry_attachments, event_time

schift. プレフィックスはシステム所有です。ベクトルソースのマテリアライズには、schift.vector_source_id、schift.source_schema、schift.source_table、schift.source_pk などのキーが使用されます。

アクセスポリシーメタデータ

これらのキーは制御された語彙です。クライアントは、制御されたインジェストまたはメタデータ管理APIを通じてのみ要求でき、値はバケットポリシーと呼び出し元の認証レベルによって制限されます。

Key	Type	Notes
privacy_level	integer string 1..10	アップローダーの要求は呼び出し元の認証レベルで制限されます。
internal_accessible	boolean string	サーバースタンプ済み; クライアントは設定できません。
public_accessible	boolean string	サーバースタンプ済み; 外部アクセスもプライバシーレベルを制限します。
classification	string	internal, public, restricted, または confidential。
review_status	string	pending, approved, または rejected。
owner_department	string	サーバースタンプ済みのアップローダー/メンバー部門。
scope	string	部門または common の取得範囲。
uploaded_by_user_id	string	サーバースタンプ済みのアップローダーID。

Note: internal_accessible、owner_department、および uploaded_by_user_id は、メタデータ管理画面でも呼び出し元が編集できません。

ステートメントDSL

一括メタデータエンドポイントは、制限されたSQLライクなステートメントを受け入れます。これは生のSQLではなく、ドキュメントメタデータAPIに解析されてマッピングされます。

サポートされている操作:

• SELECT documents WHERE ... — 変更を加えずに一致するドキュメントをプレビューします。
• UPDATE documents SET ... WHERE ... — メタデータを更新します。
• SOFTDELETE FROM documents WHERE ... — 検索を無効にし、インデックスされたベクトルを削除します。
• HARDDELETE FROM documents WHERE ... — ハードデリートジョブをキューに入れます。

DELETE FROM documents ... は意図的にサポートされていません。曖昧だからです。

SELECT documents WHERE privacy_level = 3 LIMIT 50
UPDATE documents SET privacy_level = 4, scope = 'sales' WHERE privacy_level = 3
SOFTDELETE FROM documents WHERE review_status = 'rejected'
HARDDELETE FROM documents WHERE review_status = 'rejected'

PATCH /v1/buckets/{bucket_id}/documents/{document_id}/metadata

単一のドキュメントのメタデータを更新します。このエンドポイントは、バケットポリシーと呼び出し元の認証レベルに従ってアクセスポリシーフィールドを制限し、オプションでドキュメントのインデックスされたベクトルを削除し、再処理ジョブをキューに入れます。

Authorization

• APIキーの呼び出し元は buckets:manage スコープが必要です。
• JWTの呼び出し元は、admin、owner、org_admin、または platform_admin の役割が必要です。
• 呼び出し元の auth_level は、ドキュメントの現在の privacy_level 以上でなければなりません。

Path parameters

Parameter	Type	Description
bucket_id	string	バケット識別子。
document_id	string	ドキュメント識別子。

Request body

Field	Type	Required	Description
metadata	object	No	マージするユーザーメタデータキーと値。
public_accessible	boolean	No	ドキュメントを公開アクセス可能にします。
privacy_level	integer	No	1 から 10 までのプライバシーレベル。
classification	string	No	internal、public、restricted、または confidential。
review_status	string	No	pending、approved、または rejected。
reindex	boolean	No	インデックスされたベクトルを削除し、再処理ジョブをキューに入れます。デフォルトは true。

Request example

{
  "metadata": {
    "department": "sales",
    "region": "apac"
  },
  "privacy_level": 4,
  "classification": "internal",
  "review_status": "approved",
  "reindex": true
}

Response example

{
  "id": "doc_01j8x9q2mvn9q",
  "bucket_id": "bucket_01j8x9q2mvk8r",
  "collection_id": "bucket_01j8x9q2mvk8r",
  "metadata": {
    "department": "sales",
    "region": "apac",
    "privacy_level": "4",
    "classification": "internal",
    "review_status": "approved"
  },
  "reindex_queued": true,
  "reindex_job_id": "job_01j8x9q2mvn9s",
  "indexed_vectors_deleted": 12,
  "warnings": []
}

Error examples

Status	Meaning	Example response body
400	Bad request	{ "detail": "metadata key 'chunk_id' is reserved by the system" }
403	Forbidden	{ "detail": "Requires admin role to manage document metadata" }
403	Insufficient auth level	{ "detail": "Insufficient auth_level for this document" }
404	Not found	{ "detail": "Bucket not found" } or { "detail": "Document not found" }

PATCH /v1/buckets/{bucket_id}/documents/metadata/bulk

正確な一致メタデータ述語またはステートメント文字列を使用して、多くのドキュメントを一度に編集します。このエンドポイントはドキュメントを一致させ、更新を適用し、オプションで再インデックスまたは無効化し、ドライランプレビューをサポートします。

Authorization

• SELECT プレビューにはメタデータ管理の役割は必要ありません。
• すべての変更操作には、単一ドキュメントエンドポイントと同じ認可が必要です。
• HARDDELETE にはさらに、組織管理者ユーザーセッションと confirm = "HARDDELETE \{bucket_id\}" が必要です。

Request body

Field	Type	Required	Description
statement	string	No	SQLライクなステートメント（最大4,000文字）。提供された場合、個々のフィールドを上書きします。
confirm	string	No	非ドライラン HARDDELETE に必要: "HARDDELETE \{bucket_id\}"。
where	object	No	正確な一致メタデータフィルター。
metadata	object	No	マージするユーザーメタデータ。
public_accessible	boolean	No	公開アクセス可能性を更新します。
privacy_level	integer	No	プライバシーレベルを更新します（1..10）。
classification	string	No	分類を更新します。
review_status	string	No	レビューステータスを更新します。
searchable	boolean	No	false は検索を無効にし、ベクトルを削除します; true は検索を有効のままにします。
reindex	boolean	No	一致するドキュメントの再処理ジョブをキューに入れます。デフォルトは true。
dry_run	boolean	No	変更を適用せずに一致するドキュメントを返します。デフォルトは false。
limit	integer	No	処理する最大ドキュメント数（1..2000）。デフォルトは 500。

Request examples

述語による更新:

{
  "where": { "privacy_level": 3 },
  "privacy_level": 4,
  "scope": "sales",
  "reindex": false
}

ステートメントによるプレビュー:

{
  "statement": "SELECT documents WHERE privacy_level = 3 LIMIT 50",
  "dry_run": true
}

ソフトデリートのキュー:

{
  "statement": "SOFTDELETE FROM documents WHERE review_status = 'rejected'"
}

ハードデリートのキュー:

{
  "statement": "HARDDELETE FROM documents WHERE review_status = 'rejected'",
  "confirm": "HARDDELETE bucket_01j8x9q2mvk8r"
}

Response example

{
  "bucket_id": "bucket_01j8x9q2mvk8r",
  "matched": 12,
  "updated": 12,
  "skipped": 0,
  "reindex_queued": 12,
  "indexed_vectors_deleted": 12,
  "dry_run": false,
  "items": [
    {
      "id": "doc_01j8x9q2mvn9q",
      "metadata": {
        "privacy_level": "4",
        "scope": "sales"
      },
      "searchable": true,
      "reindex_job_id": "job_01j8x9q2mvn9s",
      "indexed_vectors_deleted": 1,
      "warnings": []
    }
  ],
  "warnings": []
}

非ドライラン HARDDELETE の場合、レスポンスステータスは 202 で、status: "queued"、job_id、および delete_requested_at を含みます。

Error examples

Status	Meaning	Example response body
400	Bad request	{ "detail": "HARDDELETE requires confirm='HARDDELETE bucket_01j8x9q2mvk8r'" }
403	Forbidden	{ "detail": "API key missing required scope: buckets:manage" }
403	Hard delete forbidden	{ "detail": "HARDDELETE requires an org admin user session" }
404	Bucket not found	{ "detail": "Bucket not found" }

GET /v1/metadata/reserved-keys

サーバー所有のメタデータ語彙、検証制限、およびサポートされているステートメント操作を返します。

Response example

{
  "pipeline_reserved": [
    "bm25_score",
    "bucket_id",
    "chunk_id",
    ...
  ],
  "reserved_prefixes": [
    "schift."
  ],
  "access_policy": [
    "classification",
    "internal_accessible",
    "owner_department",
    "privacy_level",
    "public_accessible",
    "review_status",
    "scope",
    "uploaded_by_user_id"
  ],
  "document_state": [
    "deleted",
    "disabled",
    "searchable",
    "status"
  ],
  "knowledge_search": {
    "citation_metadata": [
      "asset_id",
      "chunk_hash",
      ...
    ],
    "system_filterable": [
      "bucket_id",
      "chunk_id",
      ...
    ],
    "user_filterable": "any validated user metadata key outside reserved keys, reserved prefixes, and access-policy keys"
  },
  "limits": {
    "json_bytes": 4096,
    "keys": 32,
    "key_length": 64,
    "value_length": 512
  },
  "statement_operations": [
    "SELECT",
    "UPDATE",
    "SOFTDELETE",
    "HARDDELETE"
  ]
}

See also

• バケット
• Documents
• Upload