메타데이터

Show: All versions v2 only

문서 metadata(메타데이터)는 Schift에서 검색 필터링, 접근 제어, 인용 생성을 담당합니다. 단일 문서 또는 일괄로 metadata(메타데이터)를 업데이트할 수 있으며, 서버에 현재 reserved-key(예약 키) 레지스트리와 검증 한도를 조회할 수도 있습니다.

참고: metadata(메타데이터) 값은 string(문자열)로 저장됩니다. boolean(불리언)은 "true" 또는 "false"로, number(숫자)는 persistence(지속화) 전 문자열 표현으로 강제 변환됩니다.

메타데이터 모델

사용자 메타데이터

사용자 metadata(메타데이터)는 필터링과 faceting(패싯)에 사용되는 임의의 scalar(스칼라) 키/값 데이터입니다. 모든 쓰기 시 server.validation.metadata에 의해 검증됩니다.

규칙	한도
키 문자	A-Z, a-z, 0-9, _, ., -
값 타입	string, number, boolean, 또는 null
최대 JSON payload(페이로드)	4 KB
최대 키 개수	32
최대 키 길이	64자
최대 값 길이	512자
제어 문자	허용되지 않음

예약 키

reserved keys(예약 키)는 ingestion(인제스트), indexing(인덱싱), scoring(스코어링), graph(그래프) 파이프라인이 소유합니다. 사용자 페이로드는 이 키들을 설정하면 안 됩니다.

그룹	키
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. 접두어는 시스템이 소유합니다. vector-source materialization(벡터 소스 구체화)는 schift.vector_source_id, schift.source_schema, schift.source_table, schift.source_pk 같은 키를 사용합니다.

접근 정책 메타데이터

이 키들은 controlled vocabulary(통제된 어휘)입니다. 클라이언트는 controlled ingest(통제된 인제스트) 또는 metadata-management API(메타데이터 관리 API)를 통해서만 이 키들을 요청할 수 있으며, 값은 bucket policy(버킷 정책)와 호출자의 auth level(인증 수준)에 따라 clamp(클램프)됩니다.

키	타입	설명
privacy_level	integer string 1..10	업로더 요청은 호출자 auth level(인증 수준)에 따라 상한이 정해집니다.
internal_accessible	boolean string	서버가 기록합니다. 클라이언트는 설정할 수 없습니다.
public_accessible	boolean string	서버가 기록합니다. 외부 접근도 privacy level(개인정보 수준)을 제한합니다.
classification	string	internal, public, restricted, 또는 confidential.
review_status	string	pending, approved, 또는 rejected.
owner_department	string	서버가 기록한 업로더/멤버 부서입니다.
scope	string	부서 또는 common 검색 범위입니다.
uploaded_by_user_id	string	서버가 기록한 업로더 ID입니다.

참고: internal_accessible, owner_department, uploaded_by_user_id는 metadata-management surface(메타데이터 관리 화면)에서도 호출자가 절대 편집할 수 없습니다.

Statement DSL

일괄 metadata(메타데이터) 엔드포인트는 제한된 SQL-like statement(SQL 유사 문)를 받습니다. 이는 raw SQL(원시 SQL)이 아니며, 문서 metadata(메타데이터) API로 파싱되어 매핑됩니다.

지원하는 연산:

• SELECT documents WHERE ... — 변경 없이 일치하는 문서를 미리 봅니다.
• UPDATE documents SET ... WHERE ... — metadata(메타데이터)를 업데이트합니다.
• 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

단일 문서의 metadata(메타데이터)를 업데이트합니다. 이 엔드포인트는 bucket policy(버킷 정책)와 호출자의 auth level(인증 수준)에 따라 접근 정책 필드를 clamp(클램프)하며, 선택적으로 문서의 인덱싱된 벡터를 삭제하고 reprocessing(재처리) 작업을 큐에 넣습니다.

인증

• API 키 호출자는 buckets:manage scope(스코프)가 필요합니다.
• JWT 호출자는 org(조직)의 admin, owner, org_admin, 또는 platform_admin role(역할)이 필요합니다.
• 호출자의 auth_level은 문서의 현재 privacy_level보다 크거나 같아야 합니다.

경로 매개변수

매개변수	타입	설명
bucket_id	string	bucket(버킷) 식별자입니다.
document_id	string	문서 식별자입니다.

요청 본문

필드	타입	필수	설명
metadata	object	아니오	병합할 사용자 metadata(메타데이터) 키와 값입니다.
public_accessible	boolean	아니오	문서를 공개 접근 가능하게 만듭니다.
privacy_level	integer	아니오	1부터 10까지의 privacy level(개인정보 수준)입니다.
classification	string	아니오	internal, public, restricted, 또는 confidential.
review_status	string	아니오	pending, approved, 또는 rejected.
reindex	boolean	아니오	인덱싱된 벡터를 삭제하고 reprocessing(재처리) 작업을 큐에 넣습니다. 기본값은 true입니다.

요청 예시

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

응답 예시

{
  "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": []
}

오류 예시

상태	의미	응답 본문 예시
400	잘못된 요청	{ "detail": "metadata key 'chunk_id' is reserved by the system" }
403	금지됨	{ "detail": "Requires admin role to manage document metadata" }
403	인증 수준 부족	{ "detail": "Insufficient auth_level for this document" }
404	찾을 수 없음	{ "detail": "Bucket not found" } 또는 { "detail": "Document not found" }

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

정확히 일치하는 metadata predicate(메타데이터 조건)나 statement(문) 문자열을 사용하여 여러 문서를 한 번에 편집합니다. 이 엔드포인트는 문서를 매칭하고 업데이트를 적용하며, 선택적으로 reindex(재인덱싱)하거나 비활성화하고, dry-run(시뮬레이션) 미리보기를 지원합니다.

인증

• SELECT 미리보기는 metadata-management role(메타데이터 관리 역할)을 필요로 하지 않습니다.
• 모든 변경 작업은 단일 문서 엔드포인트와 동일한 인증을 필요로 합니다.
• HARDDELETE는 추가로 org admin(조직 관리자) 사용자 세션과 confirm = "HARDDELETE \{bucket_id\}"가 필요합니다.

요청 본문

필드	타입	필수	설명
statement	string	아니오	SQL-like statement(SQL 유사 문)(최대 4,000자). 제공되면 개별 필드를 덮어씁니다.
confirm	string	아니오	비 dry-run HARDDELETE에 필요: "HARDDELETE \{bucket_id\}".
where	object	아니오	정확히 일치하는 metadata(메타데이터) 필터입니다.
metadata	object	아니오	병합할 사용자 metadata(메타데이터)입니다.
public_accessible	boolean	아니오	공개 접근성을 업데이트합니다.
privacy_level	integer	아니오	privacy level(개인정보 수준)(1..10)을 업데이트합니다.
classification	string	아니오	classification(분류)를 업데이트합니다.
review_status	string	아니오	검토 상태를 업데이트합니다.
searchable	boolean	아니오	false면 검색을 비활성화하고 벡터를 삭제합니다. true면 검색을 활성화된 상태로 둡니다.
reindex	boolean	아니오	일치하는 문서에 대해 reprocessing(재처리) 작업을 큐에 넣습니다. 기본값은 true입니다.
dry_run	boolean	아니오	변경을 적용하지 않고 일치하는 문서를 반환합니다. 기본값은 false입니다.
limit	integer	아니오	처리할 최대 문서 수(1..2000). 기본값은 500입니다.

요청 예시

predicate(조건)으로 업데이트:

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

statement(문)으로 미리보기:

{
  "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"
}

응답 예시

{
  "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": []
}

비 dry-run HARDDELETE의 경우 응답 상태는 202이며, status: "queued", job_id, delete_requested_at을 포함합니다.

오류 예시

상태	의미	응답 본문 예시
400	잘못된 요청	{ "detail": "HARDDELETE requires confirm='HARDDELETE bucket_01j8x9q2mvk8r'" }
403	금지됨	{ "detail": "API key missing required scope: buckets:manage" }
403	하드 삭제 금지	{ "detail": "HARDDELETE requires an org admin user session" }
404	bucket(버킷)을 찾을 수 없음	{ "detail": "Bucket not found" }

GET /v1/metadata/reserved-keys

서버가 소유한 metadata vocabulary(메타데이터 어휘), 검증 한도, 지원하는 statement(문) 연산을 반환합니다.

응답 예시

{
  "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"
  ]
}

같이 보기

• Buckets
• Documents
• Upload