etcd-io/etcd

Optimize Range WithKeysOnly to avoid loading values in memory

Open

#20386 opened on Jul 22, 2025

View on GitHub
 (5 comments) (0 reactions) (1 assignee)Go (51,701 stars) (10,352 forks)batch import
area/performancehelp wantedpriority/important-longtermstage/triagedtype/feature

Description

What would you like to be added?

Kubernetes 1.34 will start using Range WithKeysOnly. Main reason to use this method is to reduce the overhead of loading values in memory when they are not needed. While using WithKeysOnly avoids transferring them to client, it doesn't help with etcd memory

Noticed that it loads values in memory just to throw them out little later: https://github.com/etcd-io/etcd/blob/810d69619e33aa09bfdc0449dc65ceb34e589ab6/server/etcdserver/txn/range.go#L150-L152

TODO:

  • Add thorough tests for range so we don't break it.
  • Identify places that use value in etcd server. For example when sorting by value
  • Implement support for KeysOnly method for keyindex
  • Use KeysOnly method when we don't need value, like when we don't sort by it.
  • Benchmark to show improvement

Please note this task is complicated and not good for first contributor.

Why is this needed?

Align with user expectation that using WithKeysOnly is more efficient on server.

Contributor guide

Tech stack
go
Domain
databaseperformance
Issue type
performance
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
5
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
over 1 week
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
blocked
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
mostly clear
Prerequisites
Goetcd internalskey value store concepts
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
10
Research direction
Examine the file server/etcdserver/txn/range.go lines 150-152 to understand current behavior. Investigate the keyindex implementation to identify where KeysOnly method can be added. Review existing tests for Range to ensure thorough test coverage. Follow the TODO list in the issue description.