Add calculation cache to improve CalcCellValue performance #2144

DengY11 · 2025-05-25T13:44:37Z

PR Details

Add calculation cache to improve CalcCellValue performance

Description

Implements a calculation cache mechanism for CalcCellValue to significantly improve performance when calculating formulas repeatedly. The cache stores calculated results and automatically invalidates when cells are modified.

Related Issue

Fixes #2057 - Performance enhancement - cache calculated values

Motivation and Context

As described in #2057, Excelize doesn't cache calculated values from CalcCellValue, causing expensive formulas to be recalculated every time they are referenced by other cells. This leads to poor performance when dealing with complex formula dependencies.

Example scenario:

A1: 40
A2: =VERYEXPENSIVEFUNCTION()  // takes 100ms
A3: =A1+A2                    // takes 100ms (recalculates A2)

Solution implemented:

Cache calculated results in thread-safe sync.Map
Clear entire cache when any SetCellX() function is called
Cache key format: "sheet!cell"

Performance improvement:

First calculation: ~150µs (calculated and cached)
Second calculation: ~600ns (from cache, 250x faster)

How Has This Been Tested

go test -v -run "TestCalc.*Cache|TestSetFunctionsClearCache"
go test ./...

Test coverage includes:

☑️ Basic cache hit/miss scenarios
☑️ Cache invalidation on cell modifications
☑️ Multi-cell formula dependencies
☑️ All 12 Set functions properly clear cache
☑️ Thread safety
☑️ 3 new comprehensive test functions added

Types of changes

☑️ New feature (non-breaking change which adds functionality)
☐ Docs change / refactoring / dependency upgrade
☐ Bug fix (non-breaking change which fixes an issue)
☐ Breaking change (fix or feature that would cause existing functionality to change)

Checklist

☑️ My code follows the code style of this project.
☐ My change requires a change to the documentation.
☐ I have updated the documentation accordingly.
☑️ I have read the CONTRIBUTING document.
☑️ I have added tests to cover my changes.
☑️ All new and existing tests passed.

Implementation Details

Modified Files:

excelize.go: Added cache fields (calcCache sync.Map, calcCacheMu sync.RWMutex) to File struct
calc.go: Implemented caching logic in CalcCellValue() + added clearCalcCache() helper
cell.go: Added cache clearing to all 12 Set functions
calc_test.go: Added 3 comprehensive cache test functions

codecov · 2025-05-25T14:05:56Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.47%. Comparing base (8a99deb) to head (83aeae4).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2144   +/-   ##
=======================================
  Coverage   99.47%   99.47%           
=======================================
  Files          32       32           
  Lines       25704    25740   +36     
=======================================
+ Hits        25569    25605   +36     
  Misses         72       72           
  Partials       63       63

Flag	Coverage Δ
unittests	`99.47% <100.00%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

xuri

Thanks for your PR. We need add any cache cautiously, after these changes we also need remove cache in following scenario:

RemoveCol
RemoveRow
DuplicateRow
DuplicateRowTo
SetSheetCol

And update or delete cache when:

SetSheetName
DeleteSheet

Consider if other scenario needed.

DengY11 · 2025-05-27T13:38:06Z

Thanks for your PR. We need add any cache cautiously, after these changes we also need remove cache in following scenario:

RemoveCol

RemoveRow

DuplicateRow

DuplicateRowTo

SetSheetCol

And update or delete cache when:

SetSheetName

DeleteSheet

Consider if other scenario needed.

Thanks for your quick respond!
sorry for missing a few spots where we needed to clear the CalcCellValue cache in my first commit. After taking another look and with some great input, I think we've got all a_bases covered now.
Here’s a quick rundown of where we’ve added the f.clearCalcCache() calls:
These are the functions we sorted out earlier, based on what was initially asked for and our first round of checks:
RemoveCol ✅
RemoveRow ✅
DuplicateRow ✅
DuplicateRowTo ✅
SetSheetCol ✅
SetSheetName ✅
DeleteSheet ✅
SetCellValue ✅
SetCellInt ✅
SetCellUint ✅
SetCellBool ✅
SetCellFloat ✅
SetCellStr ✅
SetCellDefault ✅
SetCellFormula ✅
SetCellRichText ✅
SetCellHyperLink ✅

New additions in this commit:
While double-checking things more recently, we found a few more functions that also mess with the sheet in ways that would need the cache to be cleared. So, I've added the cache clearing to these in the latest changes:
MergeCell ✅
UnmergeCell ✅
InsertCols ✅
InsertRows ✅
CopySheet ✅
MoveSheet ✅

xuri

Code conflicts need resolve.

DengY11 · 2025-06-02T12:05:41Z

Code conflicts need resolve.

so sorry, the conflict was caused by my local auto-formatting. I've resolved it by keeping the original content from master

ar090 · 2025-06-17T19:57:43Z

This is really exciting! I have some very large workbooks this should help out on a ton.

ar090 · 2025-06-26T03:47:12Z

Hi @DengY11 and @xuri thanks so much for working on this! What is left to get this merged and released?

paolobarbolini · 2025-10-13T23:29:08Z

Ping @xuri

xuri · 2025-10-14T00:04:29Z

Will take review for this.

xuri

Sorry for late reply, I've left some comments.

sheet.go

xuri · 2025-11-27T00:59:52Z

sheet.go

 //	err := f.MoveSheet("Sheet2", "Sheet1")
 func (f *File) MoveSheet(source, target string) error {
+	f.clearCalcCache()
 	if strings.EqualFold(source, target) {


Does clear calc cache on move sheet order is required?

xuri · 2025-11-27T01:00:22Z

sheet.go

 // sheet name in the formula or reference associated with the cell. So there
 // may be problem formula error or reference missing.
 func (f *File) SetSheetName(source, target string) error {
+	f.clearCalcCache()


Clear calc cache after sheet name checking.

xuri · 2025-11-27T01:17:34Z

rows.go

 // as formulas, charts, and so on. If there is any referenced value of the
 // worksheet, it will cause a file error when you open it. The excelize only
 // partially updates these references currently.
 func (f *File) DuplicateRow(sheet string, row int) error {


For the DuplicateRow, DuplicateRowTo, InsertCol and InsertRow functions, we can clear calc cache in f.adjustHelper function instead of call f.clearCalcCache on each functions.

xuri

Due to formula function may reference defined name or table name, so we need also clear calc cache in SetDefinedName, DeleteDefinedName, AddPivotTable, DeletePivotTable, AddTable and DeleteTable functions.

xuri · 2025-11-27T06:04:03Z

cell.go

 //
 //	err := f.SetCellHyperLink("Sheet1", "A3", "Sheet1!A40", "Location")
 func (f *File) SetCellHyperLink(sheet, cell, link, linkType string, opts ...HyperlinkOpts) error {
+	f.clearCalcCache()


Need to clear calc cache on set cell hyperlink.

xuri · 2025-11-27T06:10:42Z

cell.go

 //
 //	err := f.SetSheetRow("Sheet1", "B6", &[]interface{}{"1", nil, 2})
 func (f *File) SetSheetRow(sheet, cell string, slice interface{}) error {
+	f.clearCalcCache()


The SetSheetCol and SetSheetRow will call SetCellValue, so we needn't clear calc cache at here.

xuri · 2025-11-27T06:14:25Z

col.go

 // worksheet, it will cause a file error when you open it. The excelize only
 // partially updates these references currently.
 func (f *File) InsertCols(sheet, col string, n int) error {
+	f.clearCalcCache()


Clear calc cache in f.adjustHelper function would be better approach.

xuri · 2025-11-27T06:15:08Z

col.go

 // worksheet, it will cause a file error when you open it. The excelize only
 // partially updates these references currently.
 func (f *File) RemoveCol(sheet, col string) error {
+	f.clearCalcCache()


Same as above, clear calc cache in f.adjustHelper function.

xuri · 2025-11-27T06:17:23Z

rows.go

 // worksheet, it will cause a file error when you open it. The excelize only
 // partially updates these references currently.
 func (f *File) InsertRows(sheet string, row, n int) error {
+	f.clearCalcCache()


Clear calc cache in f.adjustHelper.

xuri · 2025-11-27T06:21:16Z

sheet.go

 //	}
 //	err = f.CopySheet(0, index)
 func (f *File) CopySheet(from, to int) error {
+	f.clearCalcCache()


Clear calc in the f.copySheet function.

xuri · 2025-11-27T07:20:26Z

calc.go

+func (f *File) clearCalcCache() {
+	f.calcCacheMu.Lock()
+	defer f.calcCacheMu.Unlock()
+	f.calcCache.Range(func(key, value interface{}) bool {


Can we using f.calcCache.Clear() instead of range each key?

add calc cache

2512d3c

xuri added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label May 25, 2025

xuri requested changes May 26, 2025

View reviewed changes

consider more scenario needed del cache

93c378e

xuri requested changes Jun 2, 2025

View reviewed changes

resolve conflict

840ad9c

DengY11 requested a review from xuri June 2, 2025 12:06

Merge remote-tracking branch 'upstream/master'

f62109b

xuri requested changes Nov 27, 2025

View reviewed changes

Merge remote-tracking branch 'upstream/master'

3b16889

xuri requested changes Nov 27, 2025

View reviewed changes

xuri added 2 commits November 27, 2025 15:26

Fix code review issues

7597dc2

Remove unnecessary clearCalcCache call

83aeae4

Uh oh!

Add calculation cache to improve CalcCellValue performance #2144

Are you sure you want to change the base?

Add calculation cache to improve CalcCellValue performance #2144

Conversation

DengY11 commented May 25, 2025

PR Details

Description

Related Issue

Motivation and Context

How Has This Been Tested

Types of changes

Checklist

Implementation Details

Uh oh!

codecov bot commented May 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

xuri left a comment

Choose a reason for hiding this comment

Uh oh!

DengY11 commented May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

xuri left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DengY11 commented Jun 2, 2025

Uh oh!

ar090 commented Jun 17, 2025

Uh oh!

ar090 commented Jun 26, 2025

Uh oh!

paolobarbolini commented Oct 13, 2025

Uh oh!

xuri commented Oct 14, 2025

Uh oh!

xuri left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xuri Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xuri left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov bot commented May 25, 2025 •

edited

Loading

DengY11 commented May 27, 2025 •

edited

Loading

xuri left a comment •

edited

Loading

xuri Nov 27, 2025 •

edited

Loading