Say what the client is now, not what it was against - #65
Merged
Conversation
The README's opening argument was that gRPC is what the official client costs you. Kdrant has a gRPC engine now, so that argument is half wrong and reads as an omission. The pitch is the wire being yours to pick: REST by default with no gRPC, protobuf or Netty on the classpath, and the gRPC engine one dependency away when throughput is the bottleneck. The bigger gap was discoverability. Six published modules were reachable only from a paragraph of roadmap prose, so someone arriving from a search for a Spring AI or LangChain4j vector store found no coordinate to copy. There is a module table with one line each now, a BOM snippet, and a short section on choosing an engine that names the two things that actually differ: the port, and the eleven operations Qdrant serves over HTTP only. The Architecture section had become a second copy of that table. It says the thing the table cannot instead: adding a second engine changed no line of kdrant-core, which is what the seam was for, and is the same reason the core compiles for eight native targets. STABILITY.md was written to argue for cutting 1.0 and then to justify shipping 1.x changes as minors. Both readings are history. The gates for a release three majors ago are gone, the 0.x section with them, and in their place is what a reader upgrading actually needs: the JVM API is unchanged byte for byte, a Gradle build changes only the version number, and a Maven build naming kdrant-core has to move to kdrant-core-jvm. The eleven HTTP-only operations are named there too, because "both engines behave the same" is only a contract if the exception is written down.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A content pass over the README and
STABILITY.mdbefore cutting2.0.0, so the documentationdescribes the library that exists rather than the one that existed at
1.2.0.The pitch was arguing against gRPC. "It pulls a large gRPC/Netty stack onto your classpath" was the
opening paragraph's case against the official client. Kdrant has a gRPC engine now, so that reads as an
omission rather than an argument. The claim it becomes is the one that is still true and is stronger:
the wire is yours to pick, REST by default with none of that on the classpath, gRPC one dependency away.
Six published modules were undiscoverable.
kdrant-spring-ai,kdrant-langchain4j,kdrant-koog,kdrant-micrometer,kdrant-spring-boot-starterandkdrant-bomappeared only inside a paragraph ofroadmap prose, so someone arriving from a search for a Spring AI vector store found no coordinate to
copy. There is a module table with one line each now, plus a BOM snippet and a "choosing an engine"
section that names the two things that actually differ between the engines: the port, and the eleven
operations Qdrant serves over HTTP only.
Architecture stopped duplicating that table and says what the table cannot: a second engine was
added without changing one line of
kdrant-core, which is what the seam was for, and is the samereason the core compiles for eight native targets.
STABILITY.mdwas written to argue for cutting1.0and then to justify shipping1.xchanges asminors. The gate list for a release three majors ago is gone, the
0.xsection with it, and in theirplace is an "Upgrading from
1.x" section: the JVM API is unchanged byte for byte, a Gradle buildchanges only the version number, a Maven build naming
kdrant-coremust move tokdrant-core-jvm. Theeleven HTTP-only operations are part of the contract there, because "both engines behave the same" only
means something if the exception is written down.
Also: version references moved to
2.0.0, the local-developmentdocker runmaps 6334 as well, andthe repository description and topics gained
kotlin-multiplatformandgrpc.No code changes.