Skip to content

Clarify SAMPLES option in MEMORY USAGE docs - #463

Open
locker95 wants to merge 1 commit into
valkey-io:mainfrom
locker95:docs/clarify-memory-usage-samples-401
Open

Clarify SAMPLES option in MEMORY USAGE docs#463
locker95 wants to merge 1 commit into
valkey-io:mainfrom
locker95:docs/clarify-memory-usage-samples-401

Conversation

@locker95

Copy link
Copy Markdown

Problem

The MEMORY USAGE documentation describes the SAMPLES option in terms of
"nested data types" and "sampled nested values". As raised in #401, this term
is ambiguous: it is unclear whether "nested" means any non-string type or an
actual nested structure (e.g. Valkey JSON).

What the code actually does

In objectComputeSize() (src/object.c), strings are measured directly with no
sampling. Only the aggregate types (list, set, hash, sorted set, stream) walk
their elements and average a sample to estimate the total size. The command
handler (memoryCommand) also maps SAMPLES 0 to "sample everything"
(if (samples == 0) samples = LLONG_MAX;) and rejects negative values.

So "nested data types" simply means the aggregate/container types, not nested
structures.

Fix

Replace the ambiguous wording with the explicit list of aggregate types, clarify
that SAMPLES counts elements, and note that it has no effect on strings. Also
fixes the grammar in "To sample the all of the nested values".

Verification (built from unstable)

# STRING — SAMPLES accepted but has no effect (no error):
> SET s "hello world"
> MEMORY USAGE s            -> 32
> MEMORY USAGE s SAMPLES 1  -> 32
> MEMORY USAGE s SAMPLES 0  -> 32

# HASH (hashtable-encoded, uneven fields) — SAMPLES changes the estimate:
> MEMORY USAGE h2 SAMPLES 1  -> 9240
> MEMORY USAGE h2 SAMPLES 5  -> 9240
> MEMORY USAGE h2 SAMPLES 0  -> 9304   (sampling all catches the large field)

# Negative SAMPLES:
> MEMORY USAGE h2 SAMPLES -1 -> ERR syntax error

Fixes #401

Signed-off-by: Dean Chen <862469039@qq.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

"nested data types" needs definition or rephrasing

1 participant