v2 API Redesign — Umbrella Tracking Issue

[oss-amikos]

Overview

Complete redesign of the Java client for Chroma's v2 API, modeled after the Go client with Java-idiomatic patterns (builders, strong typing, AutoCloseable).

This replaces PR #80 which explored the right patterns but accumulated too much technical debt across iterations.

Phase 1: API Design (shape the contract)

Get the public API surface right before writing implementation code.

Issue	Title	Status
#93	Package structure
#81	Core interfaces — Client and Collection
#82	Value objects — Tenant, Database, CollectionConfiguration, DistanceFunction
#83	Type-safe Where and WhereDocument filter DSL
#84	Record operation builders — Add, Query, Get, Update, Upsert, Delete
#85	Auth provider API
#86	Exception hierarchy and error handling
#87	Client builder — ChromaClient.builder()

Phase 2: Implementation

Build the internals.

Issue	Title	Status
#88	HTTP transport layer — replace swagger codegen
#89	Implement ChromaClient — collection CRUD, tenant/database ops
#90	Implement Collection record operations
#91	Integration test suite with TestContainers
#92	Remove swagger-codegen and clean up pom.xml

Phase 3: API Parity with Go Client

Gaps identified by cross-referencing the Go client API surface.

Client API additions

Issue	Title
#96	Client.preFlight and Client.getIdentity endpoints
#97	Session-level tenant/database switching (useTenant, useDatabase)

Collection API additions

Issue	Title
#98	Collection.modifyConfiguration — runtime HNSW/SPANN parameter updates
#99	Collection.fork — collection copying
#100	Collection.indexingStatus — indexing progress monitoring

Configuration & DSL

Issue	Title
#101	CollectionConfiguration — add numThreads, resizeFactor, schema, SPANN, CMEK
#102	Where DSL — IDIn/IDNotIn and inline document filters
#103	Client builder — SSL/TLS, custom HTTP client, structured logging, env config

Result types

Issue	Title
#104	Row-based result access pattern (ResultRow, Rows(), At())

Search API

Issue	Title
#105	Search API — ranking expressions, field projection, groupBy, read levels

Embedding & Reranking ecosystem

Issue	Title
#106	Sparse and multimodal embedding function interfaces
#107	Reranking function interface and providers
#108	Additional embedding function providers (Gemini, Bedrock, Voyage, etc.)
#109	Embedding function registry

Utilities

Issue	Title
#110	ID generators (UUID, ULID, SHA256)

Advanced

Issue	Title
#111	Local/embedded client mode

Phase 4: Future

• Async operations
• Cloud client convenience (ChromaClient.cloud())

Dependency Graph

Phase 1 (API Design):
  #93 (packages) ──┐
  #81 (interfaces) ├──→ #82 (value objects)
                    ├──→ #83 (Where DSL)
                    ├──→ #84 (record builders) ← depends on #83
                    ├──→ #85 (auth)
                    ├──→ #86 (exceptions)
                    └──→ #87 (client builder) ← depends on #82, #85

Phase 2 (Implementation):
  #88 (HTTP transport) ← depends on #85, #86
  #89 (ChromaClient)   ← depends on #81-#88
  #90 (record ops)     ← depends on #83, #84, #88, #89
  #91 (tests)          ← depends on #89, #90
  #92 (remove swagger) ← depends on #88, #89

Phase 3 (Go parity) — depends on Phase 2:
  #96-#97   (Client APIs)      ← depends on #89
  #98-#100  (Collection APIs)  ← depends on #90
  #101-#103 (Config & DSL)     ← depends on #82, #83, #87
  #104      (ResultRow)        ← depends on #90
  #105      (Search API)       ← depends on #90, #104
  #106-#109 (EF ecosystem)     ← independent
  #110      (ID generators)    ← depends on #84
  #111      (Local client)     ← depends on #89

Superseded Issues

These older issues are addressed by the v2 redesign:

• Fluent API #5 (Fluent API) → v2: Define core interfaces — Client and Collection #81, v2: Design record operation builders — Add, Query, Get, Update, Upsert, Delete #84
• Where and Where_document syntax #14 (Where and Where_document syntax) → v2: Design type-safe Where and WhereDocument filter DSL #83
• Auth support #15 (Auth support) → v2: Design auth provider API — Token, Basic, X-Chroma-Token, custom headers #85
• Collection.get is missing offset and include options #21 (Collection.get missing offset and include) → v2: Design record operation builders — Add, Query, Get, Update, Upsert, Delete #84
• Move away from swagger generated APIs #43 (Move away from swagger generated APIs) → v2: Implement HTTP transport layer — replace swagger-generated code #88, v2: Remove swagger-codegen dependency and clean up pom.xml #92
• DB and Tenant API support #47 (DB and Tenant API support) → v2: Define core interfaces — Client and Collection #81, v2: Implement ChromaClient (Client interface) — collection CRUD, tenant/database ops #89
• Pre-flight checks API #58 (Pre-flight checks API) → v2: Client.preFlight and Client.getIdentity endpoints #96 (preFlight + getIdentity)
• Request builders #59 (Request builders) → v2: Design record operation builders — Add, Query, Get, Update, Upsert, Delete #84
• Where and WhereDocument builders #60 (Where and WhereDocument builders) → v2: Design type-safe Where and WhereDocument filter DSL #83
• Records #61 (Records) → v2: Design record operation builders — Add, Query, Get, Update, Upsert, Delete #84
• Metadata Builder #63 (Metadata Builder) → v2: Design value objects — Tenant, Database, CollectionConfiguration, DistanceFunction #82