# 서버 측 행 모델

서버가 그룹·피벗을 계산하고 펼친 그룹 경로별로 행을 공급하는 모델입니다. 이미 받은 로컬 행을 groupBy로 묶는 방식과 데이터 책임이 다릅니다.

Canonical: https://grid.syidax.com/ko/docs/features/server-side-row-model/

<a id="understand"></a>

## 동작 원리와 선택 기준

serverSideDatasource의 getRows는 요청과 성공·실패 콜백을 별도 인수로 받습니다. Infinite datasource의 params.success 형태와 혼동하지 마세요.

이 기능을 제품에서 사용하려면 Pro 패키지와 유효한 라이선스가 필요합니다. 설정 이름이 같더라도 Community에서 Pro 기능이 활성화되는 것은 아닙니다.

코드의 grid는 설치와 연결 장에서 준비한 Grid 요소입니다. 예제마다 필요한 데이터·설정을 확인하고, 코드에서 소개하는 앱 함수와 서버 주소는 프로젝트에 맞게 구현하세요.

- [설치와 연결 · 공통 예제 데이터](https://grid.syidax.com/ko/docs/guides/getting-started.md)

<a id="example-1"></a>

## 예제 1. 그룹 요청 연결

서버는 요청에 포함된 그룹 경로·필터·정렬을 해석해 rows와 rowCount를 반환하도록 준비합니다.

```javascript
grid.serverSideDatasource = { getRows: async (request, success, fail) => {
  try {
    const response = await fetch('/api/orders/groups', { method: 'POST',
      headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(request) });
    if (!response.ok) throw new Error('조회 실패');
    success(await response.json());
  } catch { fail(); }
}};
```

결과 확인: 처음에는 최상위 데이터, 그룹을 펼치면 해당 경로의 데이터가 공급됩니다. API의 ServerSideGetRowsParams와 Result를 서버 계약으로 함께 검토하세요.

<a id="example-2"></a>

## 예제 2. 일부 데이터만 로드된 선택

아직 내려받지 않은 주문까지 선택 대상으로 삼으려면 서버 선택 상태를 사용합니다.

```javascript
console.log(await grid.getServerSideSelectionState());
console.log(await grid.getServerGroupSelectionState());
```

결과 확인: 표시된 행 ID 목록과 서버 전체 선택 규칙을 구분할 수 있습니다. 앱의 일괄 처리 API도 이 선택 규칙을 이해해야 합니다.

<a id="example-3"></a>

## 예제 3. 캐시와 처리 결과 조사

그룹을 펼쳐도 비어 보일 때 어떤 저장소가 로드되었는지 확인합니다.

```javascript
console.log(await grid.getServerSideStoreState());
console.log(await grid.getServerPivotResultColumns());
```

결과 확인: 그룹 저장소 상태와 서버가 공급한 피벗 열을 따로 확인합니다. 서버 집계 열 이름이 응답 데이터 키와 맞는지도 검사하세요.

<a id="pitfalls"></a>

## 조합할 때와 문제를 해결할 때

일반 클라이언트 applyTransaction으로 아직 내려받지 않은 서버 행을 모두 바꾸려 하지 마세요. 서버 변경과 서버 전용 트랜잭션·재조회 흐름을 사용합니다.

그룹 수와 리프 주문 수, 피벗 결과 열과 원본 열을 구분해서 응답하세요. 펼침 경로의 잘못된 rowCount는 로딩과 선택에도 영향을 줍니다.

<a id="related-api"></a>

## 이 기능에 사용하는 API

- [serverSideDatasource](https://grid.syidax.com/ko/docs/options/serverSideDatasource.md) — 서버가 정렬·필터·그룹 등의 요청을 처리하는 행 모델의 데이터 공급자입니다.
- [serverSideGroupCols](https://grid.syidax.com/ko/docs/options/serverSideGroupCols.md) — 서버에서 그룹화할 열을 바깥 그룹부터 순서대로 지정합니다. 빈 배열은 평면 데이터입니다.
- [serverSideTransactionWaitMs](https://grid.syidax.com/ko/docs/options/serverSideTransactionWaitMs.md) — 비동기 서버 행 트랜잭션을 모아 처리하기까지 기다릴 시간입니다.
- [getServerSideSelectionState](https://grid.syidax.com/ko/docs/methods/getServerSideSelectionState.md) — 평면 서버 행 모델의 전체 선택 조건과 예외 ID를 읽습니다. 그룹형 모델에서는 모델 불일치를 보고합니다.
- [getServerGroupSelectionState](https://grid.syidax.com/ko/docs/methods/getServerGroupSelectionState.md) — 그룹형 서버 행 모델의 계층적 전체 선택·예외 상태를 읽습니다.
- [setServerSideSelectionState](https://grid.syidax.com/ko/docs/methods/setServerSideSelectionState.md) — 평면 서버 행 모델의 전체 선택 조건과 예외 ID를 교체합니다.
- [setServerGroupSelectionState](https://grid.syidax.com/ko/docs/methods/setServerGroupSelectionState.md) — 그룹형 서버 행 모델의 계층적 선택 상태를 교체합니다.
- [selectAllServerSide](https://grid.syidax.com/ko/docs/methods/selectAllServerSide.md) — 서버 데이터 전체를 행별로 메모리에 펼치지 않고 전체 선택 조건을 설정합니다.
- [selectServerGroupChildren](https://grid.syidax.com/ko/docs/methods/selectServerGroupChildren.md) — 그룹 키 경로 아래의 서버 하위 행들을 선택하거나 선택 해제합니다.
- [refreshServerSide](https://grid.syidax.com/ko/docs/methods/refreshServerSide.md) — 지정한 서버 저장소 범위를 새로 조회하고 처리 결과를 반환합니다.
- [applyServerSideTransaction](https://grid.syidax.com/ko/docs/methods/applyServerSideTransaction.md) — 서버 행 모델의 캐시에 행 변경을 반영합니다. 서버 원본 저장과 구분합니다.
- [applyServerSideTransactionAsync](https://grid.syidax.com/ko/docs/methods/applyServerSideTransactionAsync.md) — 서버 행 트랜잭션을 비동기 큐에 넣습니다. 최종 반영 결과와 큐 등록 결과는 다릅니다.
- [flushServerSideAsyncTransactions](https://grid.syidax.com/ko/docs/methods/flushServerSideAsyncTransactions.md) — 대기 중인 서버 행 트랜잭션을 처리하고 완료 보고서를 반환합니다.
- [getServerSideStoreState](https://grid.syidax.com/ko/docs/methods/getServerSideStoreState.md) — 서버 행 저장소의 경로·상태·블록 캐시를 읽습니다. 로딩 정도는 상태 이름뿐 아니라 블록 수와 complete도 함께 확인합니다.
- [getServerPivotResultColumns](https://grid.syidax.com/ko/docs/methods/getServerPivotResultColumns.md) — 서버가 제공한 피벗 결과 열 모델을 읽습니다. stale과 메타데이터 없음 상태를 구분합니다.
- [auditServerPivotResultColumns](https://grid.syidax.com/ko/docs/methods/auditServerPivotResultColumns.md) — 차트·출력·복원에 쓰려는 서버 피벗 열 ID가 현재 모델에 존재하는지 검사합니다. 사라진 열을 계속 사용하지 않도록 결과를 확인합니다.
- [serverStoreUpdated](https://grid.syidax.com/ko/docs/events/serverStoreUpdated.md) — 서버 행 저장소가 갱신되었을 때 발생합니다. 경로와 캐시 상태를 확인합니다.

<a id="next"></a>

## 함께 읽기

- [행·열·ID의 관계](https://grid.syidax.com/ko/docs/guides/concepts.md)
- [결과와 이벤트 연결](https://grid.syidax.com/ko/docs/guides/data-event-access.md)
- [Features에서 살펴보기](https://grid.syidax.com/grid/server-side-row-model) — 직접 체험 가능한 범위는 해당 가이드에 안내되어 있습니다.