Skip to content

docs(vdb): update command examples for current CLI#588

Draft
idevasena wants to merge 6 commits into
mainfrom
docs/vdb-command-examples-current
Draft

docs(vdb): update command examples for current CLI#588
idevasena wants to merge 6 commits into
mainfrom
docs/vdb-command-examples-current

Conversation

@idevasena

@idevasena idevasena commented Jun 29, 2026

Copy link
Copy Markdown
Contributor

Summary

This PR follows up on the VectorDB documentation review from #452 and updates the command examples to match the current mlpstorage CLI.

The change is intentionally narrow: it updates stale command syntax in vdb_benchmark/README.md and aligns the directly related VectorDB result-path / parameter wording in Rules.md. It does not rewrite the README structure or change unrelated sections such as Prerequisites, Deploy Milvus, Direct Scripts, Metrics, or Troubleshooting.

Motivation

The current VectorDB README still contains older mlpstorage command forms, including examples such as:

./mlpstorage vectordb ...
datagen --file
run --file
--open
--what-if
--mode timed

The current CLI uses a mode-first structure and positional storage type:

./mlpstorage <closed|open|whatif> vectordb <datasize|datagen|run> ...

Updates to Rules.md

Updated only the directly related VectorDB CLI / result identity wording.

Key updates:

Updated VectorDB result path wording from:

vector_database/<index>/...

to:

vector_database/<vdb_engine>/<vdb_index>/...

Clarified the distinction between:

--vdb-engine
--vdb-index
--index-type

where --vdb-engine and --vdb-index identify the benchmark result path / reporting identity, while --index-type remains the concrete Milvus build argument used by datasize and datagen.

Corrected the HNSW parameter row:

index.M

from the stale DiskANN-style flag:

--max-degree

to the HNSW-specific flag:

--M
Corrected the HNSW implementation fallback from 64 to 16.

Updated the run-mode row from:

run.mode / --mode

to:

run.benchmark_mode / --benchmark-mode

Renamed the VectorDB table column from Default to Implementation fallback to avoid implying that parser fallbacks are finalized CLOSED-profile requirements.

Signed-off-by: Devasena Inupakutika <devasena.i@samsung.com>
Signed-off-by: Devasena Inupakutika <devasena.i@samsung.com>
@idevasena idevasena requested a review from a team June 29, 2026 23:53
@github-actions

Copy link
Copy Markdown

MLCommons CLA bot All contributors have signed the MLCommons CLA ✍️ ✅

@FileSystemGuy FileSystemGuy marked this pull request as draft June 30, 2026 00:03
@FileSystemGuy

Copy link
Copy Markdown
Contributor

@idevasena I converted this to DRAFT so that I could figure out what needs to change (and what doesn't) in the --results-dir generation and validation code without worry that a wild @russfellows would merge it in! :-)

@russfellows

Copy link
Copy Markdown
Contributor

Perfect. I'm done merging for the day. I'll await further instructions.

@FileSystemGuy

Copy link
Copy Markdown
Contributor

@idevasena Sorry for taking so long to get back to you. How important are the changes to Rules.md? Do they bring the Rules into alignment with the code, or do they improve the Rules, or do they enable future flexibility?

It's very late in the process to change the Rules (we've got 10 days until the submission window closes) unless they're just broken, so I'm looking to understand the what's and why's. The addition of in the --results-dir path, for example, is that future flexibility or is it that the code generates that for all submissions so the validator needs to recognize it? Are all of the tweaks to the parameters just helpful human text changes, or do they change the values that the benchmark uses or defaults to?

@idevasena

Copy link
Copy Markdown
Contributor Author

@FileSystemGuy can we take changes to vdb Readme.md from this PR ? Because the vdb run commands now reflect latest cli changes for mlpstorage.
I will verify Rules.md once.

@FileSystemGuy

Copy link
Copy Markdown
Contributor

@idevasena Sure! The README for VDB is anything you want it to be. I'm protective over Rules.md, ManPage.md, and the mlpstorage_py directory hierarchy, but not much else.

@ram-sangle ram-sangle left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Comment thread vdb_benchmark/README.md

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Option modifications and default values look aligned to source code, the changes look good to me.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

README changes are merged as part of #670.

FileSystemGuy added a commit that referenced this pull request Jul 4, 2026
…ist_size are applied (#670)

* fix(#590): use snake_case DiskANN build params so max_degree/search_list_size are applied + README updates based on mlpstorage cli changes (pulled from PR #588)

* chore: bump 3.0.29 -> 3.0.30; regenerate uv.lock

Ride-along with the #590 DISKANN fix. Since 3.0.29 (silently rolled in
by #648) the following have landed on main: #649, #650, #652, #654,
#656, #657, #659, #665, and #602. Marks a natural version boundary
before the DISKANN key-name fix ships.

---------

Co-authored-by: Curtis Anderson <curtis@mlcommons.org>
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.

4 participants