메타데이터

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