데이터셋(Datasets)

원문 보기 위키 갱신 2026.10.11

lakeFS Team 및 lakeFS Enterprise에서 제공되는 기능이에요. 무료 체험을 시작하거나 문의하기를 통해 연락해 보세요.

출처: 문서

본문

개요

**데이터셋(dataset)**은 lakeFS에서 일급(first-class)이고 버전 관리되는 엔티티로, 리포지토리 데이터 위에 큐레이션된 뷰를 명명해요. 데이터셋은 설치의 최상위 수준에서 리포지토리와 나란히 위치해요.

데이터셋은 포인터 집합 + 설명적 메타데이터예요. 데이터는 복사되지 않아요: 데이터셋 정의는 데이터 자체가 아니라 소스 리포지토리의 데이터에 대한 참조를 저장해요.

데이터셋이 가능하게 하는 것:

발견 가능성: 그 데이터가 어느 리포지토리에 사는지 알 필요 없이 데이터셋 이름으로 설치 전체에서 데이터를 찾아요.
재현성: 모든 데이터셋 버전은 불변이에요. customer-360@v7은 기반 리포지토리가 어떻게 진화했든 항상 동일한 객체·테이블 집합으로 해석돼요.
거버넌스된 공유: 소스 리포지토리 권한과 독립적으로 데이터셋 인터페이스를 통해 데이터 접근을 통제해요.

핵심 개념

Term	Definition
Dataset	데이터 위의 명명된 뷰: 포인터(데이터 항목) 집합 + 설명적 메타데이터.
Data item	데이터셋 안의 (target, source) 쌍. target은 소비자가 읽는 주소이고, source는 특정 커밋에 고정(pinned)된 lakeFS 리포지토리의 경로, 프리픽스, 테이블 또는 네임스페이스예요.
Dataset version (v1, v2, ...)	데이터셋 정의의 불변하며 단조 증가하는 번호가 매겨진 스냅샷. 생성이나 업데이트마다 다음 버전이 만들어져요.
latest	항상 가장 최신 게시 버전을 가리켜요.
Metadata keys	설치 전역의 관리자 정의 타입 속성(예: classification, owner)으로, required/allowed-value 제약을 선택적으로 가질 수 있어요.

시작하기

구성

데이터셋으로 작업하기 전에 이 설정이 필요해요. lakeFS가 데이터셋 메타데이터를 저장할 객체 스토리지 경로(예: s3://my-bucket/path/)를 정의해요.

Self-hosted EnterpriselakeFS Cloud

lakefs.yaml에 다음을 추가하세요:

datasets:
  storage_namespace_prefix: "<dataset_metadata_storage_location>"

여러분 환경을 위해 이 설정을 구성하려면 문의해 주세요.

정책

lakeFS에는 사전 구성된 데이터셋 정책이 함께 제공돼요. 새 설치(>= v1.89.0)에는 자동으로 포함돼요.

Note

v1.89.0 이전 버전에서 업그레이드한 설치는 수동으로 만들어야 해요.

Preconfigured Policies 문서에서 전체 목록을 볼 수 있어요:

DatasetsFullAccess — 모든 dataset:* 액션
DatasetsReadWriteAll — 데이터셋 나열, 읽기, 생성, 업데이트, 삭제 + 메타데이터 키 읽기
DatasetsReadAll — 데이터셋 나열·읽기 + 메타데이터 키 읽기
DatasetsManageMetadataKeys — 메타데이터 키 정의의 전체 CRUD

적절한 정책을 사용자나 그룹에 붙이세요. 예를 들어 데이터셋 생성자는 DatasetsReadWriteAll이 필요하고, 데이터셋만 둘러보는 소비자는 DatasetsReadAll이면 충분해요.

메타데이터 키 정의

데이터셋을 만들기 전에 관리자가 설치의 메타데이터 키 스키마를 정의해야 해요. 자세한 내용은 Dataset metadata를 참고하세요.

데이터셋 생성과 관리

구성, 정책, 메타데이터 키가 준비되면 데이터셋을 만들 준비가 된 거예요. Creating and managing datasets을 참고하세요.

데이터셋 만들기

데이터셋은 다음으로 구성돼요:

이름 — 전역적으로 고유하며 소문자, 숫자, 하이픈. 생성 후 변경 불가.
설명 — 자유 텍스트.
메타데이터 — 설치의 메타데이터 키 정의에 맞는 키/값 쌍.
데이터 항목 — lakeFS 리포지토리 데이터를 가리키는 (target, source) 포인터 집합. v1.96.0부터 데이터셋은 여러 리포지토리의 데이터를 포함할 수 있어요.

각 데이터 항목은 소스 리포지토리의 특정 커밋을 가리켜요. 데이터 항목은 네 유형 중 하나예요:

Type	Source	Target address
object	단일 객체	Path (예: gold/lookup.json)
prefix	경로 프리픽스	Path (예: gold)
table	Iceberg 테이블	FQN (예: sales.orders)
namespace	Iceberg 네임스페이스	FQN (예: analytics)

target은 소비자가 데이터셋을 통해 데이터를 읽는 데 사용하는 주소예요. target은 데이터셋 내에서 고유해야 해요. target이 읽기 경로로 매핑되는 방식은 Reading dataset data를 참고하세요.

UI 사용

상단 내비게이션에서 Datasets로 이동해 Create Dataset을 클릭하세요.
데이터셋 이름과 설명을 입력하세요.
소스 리포지토리를 선택하고 데이터 항목을 추가하세요 - 유형을 선택하고, 커밋을 고르고, 소스 경로나 테이블을 지정하고, target을 설정해요.
필요한 메타데이터 필드를 채우세요.
통제된 검토 과정을 통해 데이터셋을 만들려면 Open Pull Request를, 즉시 만들려면 Publish directly를 클릭하세요.

JSON 모드로 전환해 전체 데이터셋 정의를 JSON으로 편집할 수도 있어요.

데이터셋 정의 예시

{
  "name": "customer-360",
  "definition": {
    "format_version": 1,
    "description": "Curated customer data for analytics and reporting.",
    "metadata": {
      "classification": "internal",
      "owner": "data-platform",
      "tier": "gold",
      "retention": "1y"
    },
    "data": [
      {
        "target": "customers",
        "repository": "lakehouse-repo",
        "ref": { "type": "commit", "id": "30f9eb1c..." },
        "type": "prefix",
        "prefix": { "path": "data/customers/" }
      },
      {
        "target": "sales.customers",
        "repository": "lakehouse-repo",
        "ref": { "type": "commit", "id": "30f9eb1c..." },
        "type": "table",
        "table": { "namespace": "sales", "name": "customers" }
      }
    ]
  },
  "publish": { "message": "Initial dataset with customer objects and table" }
}

데이터셋 업데이트

데이터 항목 추가/제거, 메타데이터 변경, 설명 업데이트를 위해 데이터셋을 편집하세요. 각 업데이트는 새 불변 버전을 만들어요 — 이전 버전은 계속 접근 가능해요.

데이터셋 메타데이터

메타데이터 키는 모든 데이터셋이 반드시(또는 선택적으로) 가져야 할 메타데이터를 통제하는 설치 전역 정의예요. 관리자가 키 스키마를 정의하고, 데이터셋 생성자가 값을 채워요.

메타데이터 키 정의하기

각 메타데이터 키는 다음을 가져요:

Property	Description
Name	키의 고유 식별자.
Type	string, enum, number, boolean, 또는 date.
Required	true이면 모든 데이터셋이 이 키의 값을 제공해야 해요.
Allowed values	enum 키의 경우 유효한 값의 집합.
Allow multiple	데이터셋이 이 키에 여러 값을 제공할 수 있는지 여부.
Description	UI에 표시되는 도움말 텍스트.

데이터셋을 만들기 전에 키를 정의하세요. 필수 키는 생성 시점과 업데이트 시점에 모든 데이터셋에서 채워져야 해요.

Tip

작은 필수 키 집합(예: owner, classification, tier)으로 시작하고, 필요가 생기면 선택 키를 추가하세요.

Note

새 필수 키를 추가해도 기존 데이터셋이 소급적으로 무효화되지는 않지만, 이후 어떤 데이터셋을 편집할 때든 새 키를 채워야 해요.

버저닝

데이터셋에는 선형 버전 히스토리가 있어요. 데이터 항목, 메타데이터, 설명 중 무엇을 바꾸든 다음 단조 버전이 만들어져요: v1, v2, v3, 등등.

Ref	Resolves to	Use case
latest	가장 최신 게시 버전	현재 데이터를 원하는 소비자의 기본값
v (예: v3)	특정 불변 버전	소비자나 파이프라인을 알려진 상태에 고정, 어떤 데이터가 결정을 뒷받침했는지 감사자에게 증명

버전 식별자는 시스템 생성이고 불변이며 재사용되지 않아요. v7이 게시되면 영원히 동일한 바이트로 해석돼요.

데이터셋의 버전 히스토리를 보려면 데이터셋 세부 페이지로 이동해 History 탭을 클릭하세요. 각 항목은 버전 식별자(v1, v2, ...), 게시 메시지, 작성자, 타임스탬프를 보여줘요

버전 비교

두 데이터셋 버전을 비교해 무엇이 바뀌었는지 정확히 볼 수 있어요. diff는 다음을 보여줘요:

추가, 제거 또는 수정된 데이터 항목
변경된 메타데이터 값
설명 업데이트

버전 비교에는 diff 엔드포인트를 사용하세요: GET /api/v1/datasets/{dataset}/refs/{leftRef}/diff/{rightRef}.

예를 들어 customer-360에 sales.orders 테이블을 추가해(v2가 됨) 무엇이 바뀌었는지 볼 수 있어요:

GET /api/v1/datasets/customer-360/refs/v1/diff/v2

응답은 sales.orders가 새 데이터 항목으로 추가되었음을 보여줘요.

데이터셋 데이터 읽기

동작 방식

데이터셋은 표준 lakeFS URI와 Iceberg FQN으로 어드레싱돼요 - 보통 리포지토리 이름을 쓰는 자리에 데이터셋 이름을 쓰고, ref로 latest나 v<N>을 쓰면 돼요. 오늘날 lakeFS와 동작하는 모든 도구는 데이터셋과도 바로 동작해요.

객체 읽기

데이터셋 이름과 버전을 ref로 사용하세요. 데이터 항목의 target이 경로가 돼요.

What you're reading	lakefs:// URI	s3:// URI (via S3 gateway)
Latest version of customers.csv	lakefs://customer-360/latest/customers/customers.csv	s3://customer-360/latest/customers/customers.csv
Pinned to version 3	lakefs://customer-360/v3/customers/customers.csv	s3://customer-360/v3/customers/customers.csv
List all objects under customers/	lakefs://customer-360/latest/customers/	s3://customer-360/latest/customers/

lakefs://와 s3://(S3 게이트웨이 경유) URI 스킴 모두 지원돼요.

테이블 읽기 (Iceberg)

테이블 데이터 항목에는 데이터셋 이름을 리포지토리로 하는 lakeFS Iceberg 카탈로그 FQN을 사용하세요:

What you're reading	Iceberg FQN
Latest version of sales.customers	catalog.customer-360.latest.sales.customers
Pinned to version 3	catalog.customer-360.v3.sales.customers

이 FQN은 lakeFS Iceberg REST 카탈로그를 향해 구성된 모든 Iceberg 클라이언트(Spark, Trino, PyIceberg 등)와 동작해요.

접근 제어

데이터셋 라이프사이클 권한

데이터셋 연산은 dataset:* 액션 네임스페이스와 리소스 ARN arn:lakefs:dataset:::dataset/{datasetId}를 사용해요. 모든 데이터셋에 접근을 부여하려면 arn:lakefs:dataset:::*을 사용하세요.

데이터셋 액션과 API 엔드포인트의 전체 목록은 Actions and Permissions을, 바로 쓸 수 있는 정책 정의는 Preconfigured Policies를 참고하세요.

데이터셋을 통한 데이터 접근

데이터 접근은 여러분이 이미 아는 동일한 RBAC 기본 요소를 사용해요 - 객체에는 fs:* 액션, 테이블에는 catalog:* 액션이에요. ARN에서는 보통 리포지토리 이름을 쓰는 자리에 데이터셋 이름을 쓰면 돼요.

동작 방식을 지배하는 두 가지 핵심 원칙이 있어요:

부착 시점 강제(Attach-time enforcement)

데이터셋 생성자는 자신이 읽을 수 있는 데이터만 부착할 수 있어요. 객체와 프리픽스의 경우 소스 경로에 대한 fs:ListObjects + fs:ReadObject가 필요해요. 테이블과 네임스페이스의 경우 소스에 대한 동등한 카탈로그 권한(catalog:ReadTable, catalog:ListTables 등)이 필요해요. 생성자가 부착하는 어떤 소스에도 접근 권한이 없으면 데이터셋 생성/업데이트가 거부돼요.

독립적 접근 경로

데이터셋을 통해 데이터를 읽는 소비자는 소스 리포가 아니라 데이터셋에 스코프된 권한만 필요해요. 읽기 시점에 소스 리포 정책은 평가되지 않아요. 이것이 의미하는 것:

customer-360에 대한 fs:ReadObject를 부여받은 소비자는 소스 리포에 권한이 전혀 없어도 데이터를 읽을 수 있어요.
소비자가 소스 리포에 명시적 deny를 갖고 있더라도 데이터셋을 통한 읽기는 계속 동작해요. 데이터셋이 곧 접근 경계예요.

예시: 소비자에게 읽기 권한 부여

데이터셋에 스코프된 읽기 접근을 부여하는 정책을 만드세요:

{
  "id": "ReadCustomer360",
  "statement": [
    {
      "effect": "allow",
      "action": ["fs:ListObjects"],
      "resource": "arn:lakefs:fs:::repository/customer-360"
    },
    {
      "effect": "allow",
      "action": ["fs:ReadObject"],
      "resource": "arn:lakefs:fs:::repository/customer-360/object/*"
    },
    {
      "effect": "allow",
      "action": ["catalog:ListNamespaces", "catalog:GetNamespace", "catalog:ListTables"],
      "resource": "arn:lakefs:catalog:::namespace/customer-360/*"
    },
    {
      "effect": "allow",
      "action": ["catalog:ReadTable"],
      "resource": "arn:lakefs:catalog:::table/customer-360/*/*"
    }
  ]
}

이제 소비자는 lakehouse-repo에 대한 어떤 접근도 없이 lakefs://customer-360/latest/customers/customers.csv를 읽고 catalog.customer-360.latest.sales.customers를 쿼리할 수 있어요.

제한 사항

가비지 컬렉션: 데이터셋은 소스 리포지토리의 데이터를 참조해요. 기반 데이터가 소스 리포지토리의 가비지 컬렉션으로 제거되면 데이터셋의 참조는 해석 불가능해져요. 데이터셋이 참조하는 소스 데이터가 가비지 컬렉션으로부터 보호되도록 하세요.

더 알아보기 (Learn more)

공식 문서의 데이터셋 페이지는 https://docs.lakefs.io/datasets 에서 확인할 수 있어요.