데이터 원본 바인딩

데이터 차트는 데이터를 시각화하기 전에 데이터 원본에 연결해야 합니다. SpreadJS에서는 일반적으로 데이터 매니저를 통해 데이터를 관리하며, 여기에서 테이블을 정의하고 유지 관리합니다.

데이터 차트에 데이터를 표시하려면 다음을 수행합니다.

차트를 테이블에 바인딩합니다.
테이블 필드를 차트 인코딩에 매핑합니다.

이 항목에서는 데이터 바인딩을 구성하는 방법과 인코딩이 데이터 시각화를 제어하는 방법을 설명합니다.

차트를 테이블에 바인딩

각 데이터 차트는 차트 구성에서 tableName 속성을 설정하여 테이블에 바인딩됩니다.

dataChart.setChartConfig({
  tableName: 'Sales',
  plots: [...]
});

테이블은 데이터 매니저에 있어야 합니다.

데이터 차트는 여러 관련 테이블의 데이터에도 바인딩할 수 있습니다. 여러 테이블을 사용하는 경우:

데이터 매니저에서 관계를 정의해야 합니다.
관련 테이블의 필드는 tableName.fieldName을 사용하여 참조할 수 있습니다.

인코딩

인코딩은 데이터 필드가 차트의 시각적 요소에 매핑되는 방식을 정의합니다.

각 플롯은 다음에서 인코딩을 정의합니다.

plots[n].encodings

인코딩은 다음을 제어합니다.

집계할 값
데이터 그룹화 방법
색, 도구 설명 및 필터 적용 방법

인코딩은 다음과 같이 구성됩니다.

값 인코딩
범주 인코딩
트렐리스 바인딩
세부 정보 인코딩
색 인코딩
기타 인코딩

값 인코딩

값 인코딩은 측정값으로 시각화할 숫자 필드(일반적으로 Y축에 표시됨)를 정의합니다.

단일 필드 값 인코딩

가장 일반적인 시나리오에서는 값 항목당 하나의 필드를 바인딩합니다.

encodings: {
  values: [
    {
      field: "Sales",
      aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
    }
  ]
}

image-20260420.52eaa2.png

여러 값 필드가 정의된 경우:

각 필드는 별도의 계열로 처리됩니다.
값 필드를 기반으로 범례가 자동으로 생성됩니다.

일부 차트 유형(예: 원형 및 도넛형)은 하나의 값 필드만 지원합니다.

다중 필드 값 인코딩

지원되는 차트 유형

범위 값 인코딩:
- 범위 세로 막대형
- 범위 가로 막대형
- 범위 영역형
주식 값 인코딩:
- 캔들스틱
- OHLC

일부 차트 유형에서는 하나의 논리적 값을 나타내기 위해 여러 데이터 필드가 필요합니다.

예:

범위 차트에는 하한값과 상한값이 필요합니다.
캔들스틱 및 OHLC 차트에는 시가, 고가, 저가 및 종가 값이 필요합니다.

이러한 차트에서는 vectors 구조를 사용하여 여러 필드를 하나의 값 항목 아래에 그룹화합니다.

범위 차트 예제

encodings: {
  values: [{
    vectors: {
      lower: { field: "Return" },
      upper: { field: "Sales" }
    },
    aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
  }],
  category: { field: "Product" }
}

image-20260806.c00bc9.png

주식형 차트 예제

encodings: {
  values: [{
    vectors: {
      open:  { field: "open" },
      high:  { field: "high" },
      low:   { field: "low" },
      close: { field: "close" }
    }
  }],
  category: { field: "date" }
}

image-20260417.a41881.png

이 구조에서는:

명명된 각 벡터가 특정 필드에 바인딩됩니다.
해당 차트 유형에 필요한 모든 벡터를 제공해야 합니다.

별도의 값 항목을 사용하는 기존 구성도 계속 동작하지만, 명확성과 일관성을 위해 벡터 구조를 사용하는 것이 좋습니다.

참고:
벡터가 필요한 차트 유형에서는 필수 필드를 모두 제공해야 합니다. 필수 벡터 필드가 누락되면 차트가 올바르게 렌더링되지 않습니다.

범주 인코딩

범주 인코딩은 차원(일반적으로 X축)을 따라 데이터가 그룹화되는 방식을 정의합니다.

단일 범주

단일 범주는 하나의 필드를 바인딩합니다.

encodings: {
  category: {
    field: "timePeriod"
  }
}

image-20260417.27b715.png

날짜 범주 인코딩

날짜 필드가 범주에 바인딩된 경우 dateMode를 사용하여 날짜 값이 그룹화되는 방식을 제어할 수 있습니다.

dateMode를 지정하지 않거나 null 또는 undefined로 설정하면 차트에서 원래 날짜 값을 사용합니다. 이것이 원시 날짜 동작입니다.

dateMode를 설정하여 날짜 값을 연도, 분기, 월, 일, 시간, 분 또는 초와 같은 특정 시간 단위로 그룹화할 수 있습니다.

encodings: {
  category: {
    field: "orderDate",
    dateMode: GC.Spread.Sheets.DataCharts.DateMode.month
  }
}

이 예제에서는 orderDate 필드의 날짜 값이 월별로 그룹화됩니다.

dateMode를 설정하면 날짜 값이 그룹화되는 방식이 변경됩니다. 축 눈금이 자동으로 변경되지는 않습니다. 기본적으로 범주에 바인딩된 날짜 필드는 그룹화된 각 날짜 값을 하나의 범주로 취급하는 순서형 축을 사용합니다. 날짜 값을 연속적인 시간 축에 렌더링하려면 범주 축에서 날짜 눈금을 사용하도록 구성합니다.

날짜 범주 인코딩은 세로 막대형, 가로 막대형, 꺾은선형, 영역형, 폭포 차트, 캔들스틱 및 OHLC 차트와 같이 범주 바인딩을 지원하는 차트 유형에서 지원됩니다.
원형 및 도넛형 차트는 날짜 범주 인코딩을 지원하지 않습니다.

계층 구조 범주

계층 구조 범주를 사용하면 하나의 플롯 내에 여러 그룹화 수준을 정의할 수 있습니다.

다음과 같이 자연스럽게 중첩된 데이터를 사용할 때 유용합니다.

연도 → 분기 → 월
지역 → 국가 → 도시

중첩된 child 개체를 사용하여 계층 구조 수준을 정의합니다.

예제

encodings: {
  values: [{
    field: "Sales",
    aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
  }],
  category: {
    field: "Year",
    child: {
      field: "Quarter",
      child: {
        field: "Month"
      }
    }
  }
}

image-20260417.f76f78.png

주요 특징:

중첩 순서에 따라 그룹화 순서가 결정됩니다.
각 수준은 상위 수준의 그룹화를 세분화합니다.
모든 수준은 동일한 집계 규칙을 공유합니다.
child가 정의되지 않은 경우 범주는 단일 범주로 동작합니다.

계층 구조 범주에 날짜 필드가 포함된 경우 각 날짜 수준에 자체 dateMode를 정의할 수 있습니다.

encodings: {
  category: {
    field: "orderDate",
    dateMode: GC.Spread.Sheets.DataCharts.DateMode.year,
    child: {
      field: "orderDate",
      dateMode: GC.Spread.Sheets.DataCharts.DateMode.month
    }
  }
}

다중 수준 날짜 범주는 그룹화 계층 구조를 정의합니다. 각 수준은 독립적으로 평가됩니다.

지원되는 차트 유형	지원되지 않는 차트 유형
세로 막대형 범위 세로 막대형 누적 세로 막대형 100% 누적 세로 막대형 가로 막대형 범위 가로 막대형 누적 가로 막대형 100% 누적 가로 막대형 영역형 범위 영역형 누적 영역형 100% 누적 영역형 꺾은선형 캔들스틱 OHLC	원형 도넛형 방사형 극좌표 차트 트리맵 깔때기형 분산형 거품형

참고:
모든 계층 구조 수준은 동시에 렌더링됩니다. 계층 구조 범주는 확장, 축소 또는 드릴다운 동작을 제공하지 않습니다.

트렐리스 바인딩

스몰 멀티플이라고도 하는 트렐리스 바인딩은 하나 이상의 범주형 필드를 기준으로 하나의 데이터 세트를 여러 차트 패널로 나눕니다. 각 패널에는 동일한 차트 유형과 시각적 구성이 적용되지만 특정 행 또는 열 값에 해당하는 데이터의 하위 집합이 표시됩니다.

지역, 제품 범주, 부서 또는 기간과 같은 차원에서 동일한 측정값을 비교하려는 경우 트렐리스 바인딩을 사용합니다.

트렐리스 바인딩은 row 및 column 인코딩을 사용합니다.

row는 행별로 구성된 트렐리스 패널을 만듭니다.
column은 열별로 구성된 트렐리스 패널을 만듭니다.
row와 column을 함께 사용하여 패널 그리드를 만들 수 있습니다.
트렐리스 바인딩은 모든 데이터 차트 유형에서 지원됩니다. 축 렌더링 동작은 차트 유형에 따라 달라집니다.

행 바인딩

행 바인딩은 바인딩된 필드의 각 고유 값에 대해 별도의 트렐리스 행을 만듭니다.

encodings: {
  values: [{ field: "Profit" }],
  category: { field: "Product" },
  row: { field: "Region" }
}

image-20260806.d8d818.png

열 바인딩

열 바인딩은 바인딩된 필드의 각 고유 값에 대해 별도의 트렐리스 열을 만듭니다.

encodings: {
  values: [{ field: "Profit" }],
  category: { field: "Product" },
  column: { field: "Channel" }
}

image-20260806.88a2aa.png

행 및 열 바인딩

행 및 열 바인딩을 함께 사용하여 2차원 트렐리스 레이아웃을 만들 수 있습니다.

encodings: {
  values: [{ field: "Profit" }],
  category: { field: "Product" },
  row: { field: "Region" },
  column: { field: "Channel" }
}

image-20260806.3c8dd3.png

다중 수준 트렐리스 바인딩

트렐리스 행 및 열 바인딩은 중첩된 child 개체를 사용하여 계층 구조 필드를 지원합니다. 각 수준은 트렐리스 레이아웃을 더욱 세분화합니다.

encodings: {
  values: [{ field: "Profit" }],
  category: { field: "Product" },
  row: {
    field: "Region",
    child: {
      field: "City"
    }
  },
  column: {
    field: "Quarter",
    child: {
      field: "Month"
    }
  }
}

image-20260714.b81beb.png

트렐리스 레이아웃 옵션

기본적으로 데카르트 좌표계 트렐리스 차트는 트렐리스 셀 외부에 공유 축을 사용합니다. includeAxesInCells를 true로 설정하여 각 트렐리스 셀 내부에 축을 렌더링할 수 있습니다.

config: {
  trellis: {
    includeAxesInCells: true
  }
}

image-20260806.4804d1.png

축이 셀 내부에 렌더링되는 경우 includeEmptyCells를 사용하여 빈 트렐리스 셀을 제어할 수 있습니다.

기본적으로 includeEmptyCells는 false이며 빈 트렐리스 셀에도 플롯 영역과 축이 렌더링됩니다.

image-20260714.5b662a.png

includeEmptyCells를 true로 설정하면 데이터가 없는 트렐리스 셀은 렌더링되지 않고 빈 상태로 표시됩니다.

config: {
  trellis: {
    includeEmptyCells: true
  }
}

image-20260714.e58bc5.png

트렐리스 차트는 전체 트렐리스 레이아웃에서 하나의 공유 범례를 사용합니다. 도구 설명에는 셀의 컨텍스트를 식별할 수 있도록 트렐리스 행 및 열 필드 값이 포함됩니다. 가로 막대형 및 세로 막대형 차트 계열에서는 트렐리스 셀 간 비교가 쉽도록 막대 높이 또는 열 너비가 일관되게 유지됩니다.

세부 정보 인코딩

세부 정보 인코딩은 현재 차트 구조 내에서 데이터를 추가 그룹으로 나눕니다. 데이터를 세분화하는 데 사용되지만 데이터 요소에 색을 할당하지는 않습니다.

image-20260715.f79363.png

encodings: {
  values: [{ field: "Sales" }],
  category: { field: "Product" },
  details: [{ field: "Region" }]
}

세부 정보 인코딩을 지원하는 대부분의 차트 유형에서는 하나의 세부 정보 필드를 사용할 수 있습니다. 선버스트 및 트리맵 차트는 여러 세부 정보 필드를 지원하며, 필드 순서에 따라 바깥쪽 수준에서 안쪽 수준으로 계층 구조가 정의됩니다.

encodings: {
  values: [{ field: "Sales" }],
  details: [
    { field: "Category" },
    { field: 'Subcategory' },
    { field: 'Product' }
  ]
}

image-20260715.033746.png

하나의 세부 정보 필드만 지원하는 차트 유형에 여러 세부 정보 필드를 구성하면 첫 번째 세부 정보 필드만 적용됩니다.

서로 다른 세부 정보 그룹을 서로 다른 색으로 표시하려면 색 인코딩을 명시적으로 구성합니다. 세부 정보 인코딩만으로는 색 범례가 생성되지 않습니다.

색 인코딩

색 인코딩은 데이터 요소에 색을 할당하는 방식과 색 범례 항목을 생성하는 방식을 결정합니다.

데이터 차트는 세부 정보 인코딩을 기반으로 색을 자동으로 할당하지 않습니다. 색 인코딩을 지정하지 않으면 이전의 기본 제공 색 지정 방식이 적용되지 않으며 색 범례도 생성되지 않습니다.

색 인코딩은 차트 유형에 따라 다음 필드 유형을 지원합니다.

문자열 필드
숫자 필드
값 이름

문자열 필드

대부분의 차트 유형에서 색 인코딩에 사용되는 문자열 필드는 범주 또는 세부 정보에서 이미 사용되고 있어야 합니다. 이렇게 하면 색이 할당되기 전에 데이터가 이미 세분화됩니다.

encodings: {
  values: [{ field: "Sales" }],
  category: { field: "Product" },
  details: [{ field: "Region" }],
  color: { field: "Region" }
}

image-20260715.4959ff.png

숫자 필드

숫자 색 인코딩을 지원하는 차트 유형에서는 숫자 필드를 사용하면 그라데이션 색 범례가 생성됩니다.

encodings: {
  values: [{ field: "Sales" }],
  category: { field: "Product" },
  color: {
    field: "Sales",
    aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
  }
}

색 필드가 숫자인 경우 색 필드에 집계를 적용할 수 있습니다. 색 필드가 숫자가 아닌 경우 집계 설정은 적용되지 않습니다.

image-20260715.b010a8.png

값 이름

차트에 여러 값 필드가 있고 각 값 필드를 서로 다른 색으로 나타내려는 경우 값 이름을 사용합니다.

encodings: {
  values: [
    { field: "Sales" },
    { field: "Return" }
  ],
  category: { field: "Product" },
  color: {
    field: GC.Spread.Sheets.DataCharts.EncodingField.valueName
  }
}

색 인코딩에 값 이름을 사용하면 각 값 필드에 대해 색 범례 항목이 생성됩니다.

image-20260715.195814.png

차트 유형에 따른 세부 정보 및 색 인코딩 차이

세부 정보 및 색 인코딩 동작은 차트 유형에 따라 다를 수 있습니다.

영역형 및 꺾은선형 차트는 계열 수준에서 색을 적용합니다. 범주 필드를 색 필드로 사용하는 것을 지원하지 않으며 숫자 색 인코딩도 지원하지 않습니다.
방사형 및 채워진 방사형 차트에는 영역형 및 꺾은선형 차트와 동일한 색 인코딩 제한이 적용됩니다.
분산형 및 거품형 차트는 세부 정보 인코딩을 지원하지 않습니다. 모든 문자열 필드를 색 인코딩에 사용할 수 있지만 값 이름 색 인코딩은 지원되지 않습니다.
선버스트 및 트리맵 차트는 계층 구조 데이터를 위한 여러 세부 정보 필드를 지원합니다.
깔때기형 차트는 세부 정보 인코딩을 지원하지 않습니다.

기타 인코딩

size - 연속 크기 눈금을 적용합니다. 거품형 차트에서만 지원됩니다.
tooltip - 도구 설명에 표시할 필드를 지정합니다.
filter - 집계 전에 원본 데이터에 필터링을 적용합니다. 숫자 및 문자열 필터링과 중첩된 논리 조건을 지원합니다.

호환성

이제 데이터 차트에서는 인코딩을 명시적으로 구성해야 합니다.

색 인코딩을 지정하지 않으면 이전의 기본 제공 색 지정 방식으로 색이 할당되지 않으며 색 범례도 생성되지 않습니다.

기존 .sjs 또는 .ssjson 파일의 경우 파일 버전에 따라 호환성 처리가 자동으로 적용됩니다.

코드 기반 구성의 경우 setChartConfig의 두 번째 매개 변수로 true를 전달하여 이전 동작과의 호환성을 위해 누락된 인코딩을 추론할 수 있습니다.

dataChart.setChartConfig(config, true);

메서드 시그니처에 대한 자세한 내용은 API 참조를 참조하세요.

코드 사용

데이터 차트는 SpreadJS 데이터 매니저에서 관리하는 테이블에 바인딩됩니다.

차트를 구성하기 전에 다음을 수행해야 합니다.

데이터 매니저 초기화
테이블 등록
(선택 사항) 테이블 간 관계 정의

1단계 – 데이터 매니저 초기화

const dataManager = spread.dataManager();

2단계 – 테이블 등록

차트를 만들기 전에 필요한 모든 테이블을 등록합니다.

// Sales table
const salesTable = createSalesTable(dataManager);
await salesTable.fetch();

// Orders table
const ordersTable = createOrders(dataManager);
await ordersTable.fetch();

// Order details table
const orderDetailsTable = createOrderDetails(dataManager);
await orderDetailsTable.fetch();

// Hierarchical sales table (used for hierarchical category examples)
const hierarchySalesTable = createHierarchySalesTable(dataManager);
await hierarchySalesTable.fetch();

3단계 – 테이블 관계 정의(선택 사항)

여러 테이블을 바인딩하는 경우 테이블 간 관계를 정의해야 합니다.

dataManager.addRelationship(
    ordersTable, "orderId",
    "orderDetailsTable",
    orderDetailsTable, "OrderId",
    "ordersTable"
);

4단계 – 기본 데이터 바인딩 예제

다음 예제에서는 세로 막대형 차트를 Sales 테이블에 바인딩합니다.

const sheet = spread.getSheet(0);
sheet.name("Binding Data");

const dataChart = sheet.dataCharts.add('data-chart', 10, 10, 600, 400);

dataChart.setChartConfig({
    tableName: 'Sales',
    plots: [{
        type: GC.Spread.Sheets.DataCharts.DataChartType.column,
        encodings: {
            values: [{
                field: "Sales",
                aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
            }],
            category: {
                field: "Product"
            }
        }
    }],
    config: {
        header: {
            title: "Sales by Product"
        }
    }
});

image-20260420.54c315.png

5단계 – 여러 테이블 바인딩

관계가 있는 경우 경로 식을 사용하여 관련 테이블의 필드를 참조할 수 있습니다.

다음 예제에서는 차트를 Orders 테이블에 바인딩하고 관련 orderDetailsTable의 데이터를 집계합니다.

let sheet2 = spread.getSheet(1);
sheet2.name("Binding Multiple Tables");

const dataChart2 = sheet2.dataCharts.add('data-chart-2', 10, 10, 600, 400);

dataChart2.setChartConfig({
    tableName: 'Orders',
    plots: [{
        type: GC.Spread.Sheets.DataCharts.DataChartType.column,
        encodings: {
            values: [{
                field: 'orderDetailsTable.Sales'
            }],
            category: {
                field: 'shipCountry'
            }
        }
    }],
    config: {
        header: {
            title: "Sales by Country (Multiple Tables)"
        }
    }
});

image-20260420.2a67b9.png

6단계 – 계층 구조 범주 바인딩

데이터 차트는 category 인코딩 내에 중첩된 child 필드를 정의하여 다중 수준 범주 그룹화를 지원합니다.

다음 예제에서는 계층 구조 범주(연도 → 분기 → 월)를 사용하여 세로 막대형 차트를 바인딩합니다.

let sheet3 = spread.getSheet(2);
sheet3.name("Hierarchical Category Binding");

const dataChart3 = sheet3.dataCharts.add('data-chart-3', 10, 10, 600, 400);

dataChart3.setChartConfig({
    tableName: 'HierarchySales',
    plots: [{
        type: GC.Spread.Sheets.DataCharts.DataChartType.column,
        encodings: {
            values: [{
                field: 'sales'
            }],
            category: {
                field: "year",
                    child: {
                        field: "quarter",
                            child: {
                                field: "month"
                            }
                        }
            }
        }
    }],
    config: {
        header: {
            title: "Hierarchical Column Chart"
        }
    }
});

전체 예제

이 항목에서는 다음 함수의 구현을 보여주지 않습니다.

createSalesTable
createOrders
createOrderDetails
createHierarchySalesTable

모든 테이블 생성 유틸리티가 포함된 실행 가능한 전체 예제를 다운로드하세요.

BindDataSourceExample.js