Affected area

other

Motivation

Parent issue #1947 proposes sharing one Pyramid vector base across multiple independent path hierarchies. Before refactoring internals, the user-facing API and parameter names should be fixed so later PRs do not drift.

Proposed solution

Define the staged API contract:

• Legacy build/add keeps Dataset::Paths(paths).
• Named build/add uses Dataset::Paths("site", site_paths) and Dataset::Paths("taxonomy", taxonomy_paths).
• Build parameters accept index_param.hierarchies, either as names or objects with name and no_build_levels.
• Single-hierarchy search uses pyramid.hierarchy.
• Future multi-hierarchy search reserves pyramid.hierarchies plus pyramid.hierarchy_op with union / intersection.
• Parser should validate non-empty and unique hierarchy names.
• Future operators may be parsed first, while execution can return a clear not-implemented error.

Alternatives considered

Encoding multiple hierarchy paths into one legacy path string with separators such as comma or custom protocol was considered, but it makes validation ambiguous and mixes hierarchy selection with path syntax.

API / ABI compatibility impact

additive only (no break)

References

• [Feature Request] Pyramid: share a single vector base (FlattenInterface) across multiple path hierarchies #1947
• include/vsag/dataset.h:321
• include/vsag/dataset.h:331

Additional context

This issue should only settle API and parameter parsing. It should not refactor Pyramid storage, serialization, or Analyzer behavior.

Related issues

• [Feature Request] Pyramid: share a single vector base (FlattenInterface) across multiple path hierarchies #1947 [Feature Request] Pyramid: share a single vector base (FlattenInterface) across multiple path hierarchies

Drafted with AI assistant: Codex:gpt-5