데이터와 큐브

DataSet으로 행 데이터를 로드한 뒤, Cube 스키마로 차원과 측정값을 설정하는 방법입니다.

피벗에 올리는 데이터는 DataSet, 분석 모델은 Cube입니다.
Control을 만들기 전에 보통 다음 순서로 준비합니다.

1. createDataSet — 테이블(또는 Star Schema)에 행 데이터를 로드합니다.
2. createCubeManager — DataSet 위에 Cube 스키마(차원·측정값)를 올립니다.
3. createControl — Book 설정의 tables[].cube 속성으로 사용할 큐브를 지정합니다.

전체 생성 흐름은 개발 가이드·시작하기를 참고하세요.

DataSet

createDataSet에는 테이블 옵션(PivotDataTableOptions) 또는 Star Schema 옵션(PivotStarSchemaOptions)을 전달합니다.
createDataSet은 비동기 함수이므로, await나 .then()을 사용해 Promise 처리가 완료될 때까지 대기해야 합니다.

테이블 옵션

name·source·sourceUrl 중 하나는 있어야 합니다.

source (배열·JSON 문자열)

const ds = await createDataSet([
  {
    name: 'sales',
    source: [
      { 국가: '한국', 판매수량: 10 },
      { 국가: '미국', 판매수량: 20 },
    ],
    table: {
      fields: [
        { name: '국가', type: 'text' },
        { name: '판매수량', type: 'number' },
      ],
    },
  },
]);

• 배열은 그대로 행으로 들어갑니다.
• 문자열은 JSON.parse 후 행으로 들어갑니다. 인라인 source에는 CSV를 넣을 수 없습니다.

sourceUrl (파일·원격)

const ds = await createDataSet([
  {
    name: 'sales',
    sourceUrl: '/data/sales.json',
    table: {
      fields: [
        { name: '국가', type: 'text' },
        { name: '판매수량', type: 'number' },
      ],
    },
  },
]);

CSV는 sourceType: 'csv'와 함께 지정합니다.

{
  name: 'sales',
  sourceUrl: '/data/sales.csv',
  sourceType: 'csv',
  // csvOptions: { delimiter: ',', hasHeader: true },
  table: { fields: [/* ... */] },
}

테이블 필드 타입

table.fields의 type은 DataTable 값 타입('text', 'number' 등)을 사용하며, 이는 Cube 스키마 타입명(str, f64, i32)과 다르므로 주의해야 합니다.

Star Schema (여러 테이블)

fact 테이블과 차원 테이블을 조인하려면 type: 'star' 옵션을 같은 createDataSet 배열에 넣습니다.

const ds = await createDataSet([
  { name: 'orders', sourceUrl: '/data/orders.json', table: { fields: [/* ... */] } },
  { name: 'products', sourceUrl: '/data/products.json', table: { fields: [/* ... */] } },
  {
    type: 'star',
    name: 'star',
    fact: 'orders',
    dimensions: [
      {
        table: 'products',
        foreignKey: 'product_id',
        // primaryKey 생략 시 차원 테이블 첫 컬럼
      },
    ],
  },
]);

Cube를 만들 때 table에는 단일 테이블 name 또는 Star name을 지정합니다.

Cube

createCubeManager(ds, cubes)는 동기입니다. 각 큐브에는 name·table·schema가 필수입니다.

const cm = createCubeManager(ds, [
  {
    name: 'sales',
    table: 'sales',
    schema: {
      dimensions: [
        { name: '국가', type: 'str' },
        { name: '차종', type: 'str' },
      ],
      measures: [
        { name: '판매수량', type: 'f64', aggregate: 'sum' },
      ],
    },
  },
]);

PivotCubeOptions

차원 (dimensions)

날짜 분해 예:

{
  name: '판매날짜',
  source: '판매날짜',
  type: 'date',
  dateFields: ['판매반기;half', '판매분기;quarter', '판매월;month'],
}

dateFields 항목은 레벨(year, half, quarter, month, week, day 등)이거나 "표시이름;레벨" 형식입니다.
date 분해로 생긴 필드는 Book의 rows / columns에 그 이름(판매분기 등)으로 배치합니다.

측정값 (measures)

aggregate 값 예: sum, avg, min, max, count, distinct, first, last, p25, p50, p75, product, stdev, stdevp, var, varp
자세한 목록은 집계 함수를 참고하세요.

str / date 타입 측정값은 보통 count · distinct만 의미가 있습니다.
Book에서 값 필드의 집계를 바꿀 때는 PivotValueFieldOptions.aggregate도 참고하세요.

이름 연결

관례로 name / table / cube를 같은 문자열로 맞추는 경우가 많지만 필수는 아닙니다. Book 페이지의 name은 시트 이름이며 DataSet 테이블명과 다릅니다.

런타임 필터

초기 필터는 Cube 옵션의 filters로 지정합니다.
실행 중 필터는 개별 큐브 API로 다룹니다.

const cube = cm.get('sales');
cube.addFilter({ dimension: '국가', values: ['한국'] });

See Also

• 시작하기
• 개발 가이드
• 필드 구성
• 집계 함수
• Config 개요
• API 개요