Skip to content

feat: fetch() with outputFields parameter (closes #176) - #191

Merged
s2x merged 1 commit into
mainfrom
feat/issue-176-fetch-output-fields
Aug 8, 2026
Merged

feat: fetch() with outputFields parameter (closes #176)#191
s2x merged 1 commit into
mainfrom
feat/issue-176-fetch-output-fields

Conversation

@s2x

@s2x s2x commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

Description

Closes #176

Adds optional output-field selection to ZVecCollection::fetch(), matching upstream zvec v0.5.0+ (alibaba/zvec#358) and the Go SDK's Fetch(pks, FetchOptions).

Changes

  • FFI (ffi/zvec_ffi.h, zvec_ffi.cc, zvec_ffi_php.h): zvec_collection_fetch extended with output_fields / output_field_count parameters; builds std::optional only when count > 0 (nullopt = all fields, exact upstream semantics from c_api.cc). Per-entry null guard added.
  • PHP (src/ZVec.php): fetch(array|string ...$args) — BC-compatible dual form: legacy fetch('a', 'b') and new fetch(['a','b'], ['name','score']). Full input validation via ZVecException (empty/non-string PKs, non-array/non-string/empty output fields, extra arguments).
  • Test: tests/test_fetch_output_fields.phpt — 8 scenarios: subset selection, BC all-fields, array form, unknown-fields-ignored, 3 validation throws, extra-args throw.
  • Docs: README API listing + CHANGELOG updated.

Testing

  • Builds locally (./build_ffi.sh clean on macOS/arm64)
  • All .phpt tests pass: 175 passed, 0 failed, 2 expected-fail, 1 skipped
  • No test database leftovers (test_dbs/ empty)

Code Review

  • Passed subagent code review (2 low-severity findings — both fixed)
  • Re-review approved ("Code looks good, no issues to fix")
  • Follow-up candidates reported (includeVector exposure, nullable normalization — separate issues)

Notes

  • include_vector intentionally not exposed (out of scope for fetch() with outputFields parameter (zvec v0.5.0) #176): vector fields are always present in fetched docs, matching the upstream default.
  • Unknown output field names are silently ignored by the C++ layer (documented in test; upstream Node/Python behave the same).

- Extend zvec_collection_fetch FFI binding with optional output fields
  (output_fields/output_field_count), building std::optional only when
  count > 0 (nullopt = all fields, matching upstream C API)
- ZVecCollection::fetch() accepts fetch(['pk1','pk2'], ['name']) while
  keeping the legacy variadic fetch('pk1','pk2') BC-compatible; full
  input validation via ZVecException
- Per-entry null guard on output_fields in the C++ wrapper
- Add tests/test_fetch_output_fields.phpt (8 scenarios)
- Update README API listing and CHANGELOG
@s2x s2x self-assigned this Aug 8, 2026
@s2x
s2x merged commit d37bbe7 into main Aug 8, 2026
3 checks passed
@s2x
s2x deleted the feat/issue-176-fetch-output-fields branch August 8, 2026 16:20
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.

fetch() with outputFields parameter (zvec v0.5.0)

1 participant