Flint 차트 명세와 편집 가능한 출력: 무엇을 어디서 수정할까

Flint 차트 명세는 짧은 입력을 시각화 라이브러리별 설정으로 바꿔 줍니다. 수정할 곳은 입력 명세, 생성된 설정, Excel 네이티브 차트 세 군데로 나뉘어요. 차트 종류와 필드 배치는 입력 명세에서, 세부 표현은 생성된 설정에서 조정하면 됩니다. Excel 안에서 직접 편집하고 싶다면 네이티브 차트를 생성하는 경로를 쓰면 되고요.

여기서 말하는 백엔드는 차트를 실제로 그리는 라이브러리나 실행 환경입니다. Flint는 Vega-Lite 명세, ECharts의 option, Chart.js 설정, Plotly의 { data, layout } 등을 생성해요. 그래서 '편집 가능한 출력'을 받았다면 어떤 설정 형식인지부터 확인하는 게 순서입니다. PNG·SVG는 정적 배포용 출력이에요. 나중에 데이터나 축을 고칠 계획이라면 원자료와 명세도 함께 남겨 두는 편이 좋습니다.

모양을 고치기 전에 데이터의 의미부터 보세요

명세는 data, semantic_types, chart_spec 순서로 읽기를 권합니다. 차례대로 원자료, 필드의 의미, 차트 종류와 필드 배치가 들어 있어요. 이 순서를 권하는 이유는 같은 값도 의미에 따라 축과 서식이 달라질 수 있기 때문입니다. 모양부터 손대면 데이터를 잘못 해석한 문제를 표현 설정으로 덮어 버리기 쉬워요.

숫자 202001을 예로 들어 볼게요. 이 값은 단순한 수량으로 읽힐 수도 있지만, 의미 타입을 YearMonth로 지정하면 연월로 해석할 수 있습니다. Flint 컴파일러는 이런 의미와 데이터 특성을 바탕으로 축, 색상, 서식, 배치를 결정해요. 이 구분은 공식 개요 문서에도 설명돼 있습니다.

필드의 의미를 확인했다면, 그다음에 축에 무엇을 놓을지 정하면 됩니다.

chart_spec 안의 encodings에서 x와 y는 각 축에 연결할 필드를 지정합니다. 의미 타입이 필드를 어떻게 읽을지 알려 준다면, 인코딩은 그 필드를 차트의 어디에 배치할지 정하는 셈이에요. 많이 헷갈리는 지점이 여기입니다. 축에 엉뚱한 필드가 연결된 문제인지, 필드 자체를 잘못 해석한 문제인지 먼저 구분해야 어디를 고칠지 분명해져요.

명세 수정과 Excel 생성은 편집 경로가 다릅니다

같은 데이터로 구성만 바꾸려면 data와 semantic_types는 그대로 두고 chart_spec만 수정한 뒤 다시 컴파일하면 됩니다. 기존 필드를 교체하거나 차트 유형을 바꾸는 정도라면 LLM을 다시 호출할 필요가 없어요. 다만 선택한 차트 유형을 대상 백엔드가 지원해야 합니다. 지원하지 않는 조합은 컴파일 오류로 이어지니, 지원 여부와 실제 생성 결과를 함께 확인해 보세요.

세부 표현은 생성된 라이브러리 설정에서도 조정할 수 있습니다. 차트 구성은 Flint 명세에서 바꾸고, 출력 라이브러리에 맞춘 세밀한 조정은 생성 설정에서 처리하는 식으로 나눠 두면 관리하기 편해요. 공식 개발 설명 문서도 두 편집 방식을 모두 안내합니다. 새로운 데이터 변환이나 분석 요청은 기존 필드를 교체하는 작업과 다른 일로 구분해서 이해하는 게 좋습니다.

Excel 경로에서는 산출물 생성과 실제 차트 생성을 나눠서 봐야 해요. assembleExcel()은 직렬화 가능한 차트 산출물을 반환하고, renderExcelChart()는 Office.js가 실행되는 Excel 환경에서 워크시트에 네이티브 차트를 만듭니다. Excel 안에서 편집하게 되는 대상은 이 단계에서 생성된 차트입니다.

generateOfficeJs()는 실행할 소스 코드를 반환하므로, 함수를 호출한 뒤 그 코드를 실행하는 단계가 따로 필요합니다. 그러니 이 API 흐름은 .xlsx를 곧바로 다운로드하는 기능이라기보다 Excel 내부에서 차트를 생성하는 경로로 이해하는 쪽이 정확해요.

원본은 따로 두고, 재컴파일 뒤에는 경고를 확인하세요

반복해서 수정할 차트라면 원자료와 Flint 명세를 원본으로 보관하길 권합니다. 생성된 설정에 직접 손으로 넣은 변경은 별도 후처리로 관리하는 편이 좋아요. 수동 변경이 Flint 입력에 자동으로 역반영되거나 재컴파일 결과에 병합되는 동작은 확인되지 않았습니다. 다음 컴파일 결과에 다시 적용할 조정을 추적할 수 있도록 따로 분리해 두세요.

재컴파일한 뒤에는 모양만 보지 말고 표시된 데이터도 함께 확인해야 합니다.

특히 챙겨 볼 것은 백엔드별 차트 지원 여부와 생성 결과의 _warnings예요. 공식 API에는 공간이 부족할 때 일부 범주를 걸러내고 경고를 남기는 동작이 설명돼 있습니다. 차트가 깔끔해 보여도 원자료의 범주가 모두 표시됐는지는 따로 대조해 봐야 해요. 지원 템플릿 조회와 경고 처리 방식은 API 문서를 기준으로 확인하면 됩니다.