JVMCBC-1496 Promote Vector Search from volatile to uncommitted public…

… API

including scope-level search.

Also marking scope/vector search as @SinceCouchbase("7.6").

Change-Id: Iaa144120d11251c3f697e96b4767de6864132e72
Reviewed-on: https://review.couchbase.org/c/couchbase-jvm-clients/+/206831
Reviewed-by: David Nault <david.nault@couchbase.com>
Tested-by: Build Bot <build@couchbase.com>

java-client/src/main/java/com/couchbase/client/java/AsyncCluster.java

@@ -418,7 +418,7 @@ AnalyticsRequest analyticsRequest(final String statement, final AnalyticsOptions
    * @throws TimeoutException if the operation times out before getting a result.
    * @throws CouchbaseException for all other error reasons (acts as a base type and catch-all).
    */
-  @Stability.Volatile
+  @Stability.Uncommitted
   public CompletableFuture<SearchResult> search(final String indexName, final SearchRequest searchRequest) {
     return search(indexName, searchRequest, DEFAULT_SEARCH_OPTIONS);
   }
@@ -435,7 +435,7 @@ public CompletableFuture<SearchResult> search(final String indexName, final Sear
    * @throws TimeoutException if the operation times out before getting a result.
    * @throws CouchbaseException for all other error reasons (acts as a base type and catch-all).
    */
-  @Stability.Volatile
+  @Stability.Uncommitted
   public CompletableFuture<SearchResult> search(final String indexName, final SearchRequest searchRequest, final SearchOptions options) {
     notNull(searchRequest, "SearchRequest", () -> new ReducedSearchErrorContext(indexName, null));
     notNull(options, "SearchOptions", () -> new ReducedSearchErrorContext(indexName, null));

java-client/src/main/java/com/couchbase/client/java/AsyncScope.java

@@ -304,7 +304,8 @@ AnalyticsRequest analyticsRequest(final String statement, final AnalyticsOptions
    * @throws TimeoutException if the operation times out before getting a result.
    * @throws CouchbaseException for all other error reasons (acts as a base type and catch-all).
    */
-  @Stability.Volatile
+  @Stability.Uncommitted
+  @SinceCouchbase("7.6")
   public CompletableFuture<SearchResult> search(final String indexName, final SearchRequest searchRequest) {
     return search(indexName, searchRequest, DEFAULT_SEARCH_OPTIONS);
   }
@@ -321,7 +322,8 @@ public CompletableFuture<SearchResult> search(final String indexName, final Sear
    * @throws TimeoutException if the operation times out before getting a result.
    * @throws CouchbaseException for all other error reasons (acts as a base type and catch-all).
    */
-  @Stability.Volatile
+  @Stability.Uncommitted
+  @SinceCouchbase("7.6")
   public CompletableFuture<SearchResult> search(final String indexName, final SearchRequest searchRequest, final SearchOptions options) {
     notNull(searchRequest, "SearchRequest", () -> new ReducedSearchErrorContext(indexName, null));
     notNull(options, "SearchOptions", () -> new ReducedSearchErrorContext(indexName, null));

java-client/src/main/java/com/couchbase/client/java/Cluster.java

@@ -445,7 +445,7 @@ public AnalyticsResult analyticsQuery(final String statement, final AnalyticsOpt
    * @throws TimeoutException if the operation times out before getting a result.
    * @throws CouchbaseException for all other error reasons (acts as a base type and catch-all).
    */
-  @Stability.Volatile
+  @Stability.Uncommitted
   public SearchResult search(final String indexName, final SearchRequest searchRequest) {
     return search(indexName, searchRequest, DEFAULT_SEARCH_OPTIONS);
   }
@@ -462,7 +462,7 @@ public SearchResult search(final String indexName, final SearchRequest searchReq
    * @throws TimeoutException if the operation times out before getting a result.
    * @throws CouchbaseException for all other error reasons (acts as a base type and catch-all).
    */
-  @Stability.Volatile
+  @Stability.Uncommitted
   public SearchResult search(final String indexName, final SearchRequest searchRequest, final SearchOptions options) {
     return block(asyncCluster.search(indexName, searchRequest, options));
   }

java-client/src/main/java/com/couchbase/client/java/ReactiveCluster.java

@@ -328,7 +328,7 @@ public Mono<ReactiveAnalyticsResult> analyticsQuery(final String statement, fina
    * @throws TimeoutException if the operation times out before getting a result.
    * @throws CouchbaseException for all other error reasons (acts as a base type and catch-all).
    */
-  @Stability.Volatile
+  @Stability.Uncommitted
   public Mono<ReactiveSearchResult> search(final String indexName, final SearchRequest searchRequest) {
     return search(indexName, searchRequest, DEFAULT_SEARCH_OPTIONS);
   }
@@ -345,7 +345,7 @@ public Mono<ReactiveSearchResult> search(final String indexName, final SearchReq
    * @throws TimeoutException if the operation times out before getting a result.
    * @throws CouchbaseException for all other error reasons (acts as a base type and catch-all).
    */
-  @Stability.Volatile
+  @Stability.Uncommitted
   public Mono<ReactiveSearchResult> search(final String indexName, final SearchRequest searchRequest, final SearchOptions options) {
     notNull(searchRequest, "SearchRequest", () -> new ReducedSearchErrorContext(indexName, null));
     notNull(options, "SearchOptions", () -> new ReducedSearchErrorContext(indexName, null));

java-client/src/main/java/com/couchbase/client/java/ReactiveScope.java

@@ -17,6 +17,7 @@
 package com.couchbase.client.java;
 
 import com.couchbase.client.core.Core;
+import com.couchbase.client.core.annotation.SinceCouchbase;
 import com.couchbase.client.core.annotation.Stability;
 import com.couchbase.client.core.api.search.CoreSearchQuery;
 import com.couchbase.client.core.api.search.queries.CoreSearchRequest;
@@ -209,7 +210,8 @@ public Mono<ReactiveAnalyticsResult> analyticsQuery(final String statement, fina
    * @throws TimeoutException if the operation times out before getting a result.
    * @throws CouchbaseException for all other error reasons (acts as a base type and catch-all).
    */
-  @Stability.Volatile
+  @Stability.Uncommitted
+  @SinceCouchbase("7.6")
   public Mono<ReactiveSearchResult> search(final String indexName, final SearchRequest searchRequest) {
     return search(indexName, searchRequest, DEFAULT_SEARCH_OPTIONS);
   }
@@ -226,7 +228,8 @@ public Mono<ReactiveSearchResult> search(final String indexName, final SearchReq
    * @throws TimeoutException if the operation times out before getting a result.
    * @throws CouchbaseException for all other error reasons (acts as a base type and catch-all).
    */
-  @Stability.Volatile
+  @Stability.Uncommitted
+  @SinceCouchbase("7.6")
   public Mono<ReactiveSearchResult> search(final String indexName, final SearchRequest searchRequest, final SearchOptions options) {
     notNull(searchRequest, "SearchRequest", () -> new ReducedSearchErrorContext(indexName, null));
     notNull(options, "SearchOptions", () -> new ReducedSearchErrorContext(indexName, null));

java-client/src/main/java/com/couchbase/client/java/Scope.java

@@ -217,6 +217,8 @@ public AnalyticsResult analyticsQuery(final String statement, final AnalyticsOpt
    * @throws TimeoutException if the operation times out before getting a result.
    * @throws CouchbaseException for all other error reasons (acts as a base type and catch-all).
    */
+  @Stability.Uncommitted
+  @SinceCouchbase("7.6")
   public SearchResult search(final String indexName, final SearchRequest searchRequest) {
     return search(indexName, searchRequest, DEFAULT_SEARCH_OPTIONS);
   }
@@ -233,6 +235,8 @@ public SearchResult search(final String indexName, final SearchRequest searchReq
    * @throws TimeoutException if the operation times out before getting a result.
    * @throws CouchbaseException for all other error reasons (acts as a base type and catch-all).
    */
+  @Stability.Uncommitted
+  @SinceCouchbase("7.6")
   public SearchResult search(final String indexName, final SearchRequest searchRequest, final SearchOptions options) {
     return block(async().search(indexName, searchRequest, options));
   }

java-client/src/main/java/com/couchbase/client/java/search/SearchRequest.java

@@ -15,10 +15,10 @@
  */
 package com.couchbase.client.java.search;
 
+import com.couchbase.client.core.annotation.SinceCouchbase;
 import com.couchbase.client.core.annotation.Stability;
 import com.couchbase.client.core.api.search.queries.CoreSearchRequest;
 import com.couchbase.client.core.error.InvalidArgumentException;
-import com.couchbase.client.java.search.queries.MatchNoneQuery;
 import com.couchbase.client.java.search.vector.VectorSearch;
 import reactor.util.annotation.Nullable;
 
@@ -29,7 +29,7 @@
  * <p>
  * If both are provided, the FTS service will merge the results.
  */
-@Stability.Volatile
+@Stability.Uncommitted
 public class SearchRequest {
 
   private @Nullable SearchQuery searchQuery;
@@ -77,6 +77,7 @@ public SearchRequest searchQuery(SearchQuery searchQuery) {
    *
    * @return this, for chaining purposes.
    */
+  @SinceCouchbase("7.6")
   public SearchRequest vectorSearch(VectorSearch vectorSearch) {
     if (this.vectorSearch != null) {
       throw new InvalidArgumentException("A VectorSearch has already been specified.  Note that a single VectorSearch can take multiple VectorQuery objects, allowing multiple vector queries to be run.", null, null);

java-client/src/main/java/com/couchbase/client/java/search/vector/VectorQuery.java

@@ -19,7 +19,7 @@
 import com.couchbase.client.core.api.search.vector.CoreVectorQuery;
 import reactor.util.annotation.Nullable;
 
-@Stability.Volatile
+@Stability.Uncommitted
 public class VectorQuery {
   private final float[] vectorQuery;
   private final String vectorField;

java-client/src/main/java/com/couchbase/client/java/search/vector/VectorQueryCombination.java

@@ -21,7 +21,7 @@
 /**
  * Controls how multiple vector queries are combined.
  */
-@Stability.Volatile
+@Stability.Uncommitted
 public enum VectorQueryCombination {
   /**
    * All vector queries must match a document for it to be included.

java-client/src/main/java/com/couchbase/client/java/search/vector/VectorSearch.java

@@ -28,7 +28,7 @@
 /**
  * A VectorSearch allows one or more individual {@link VectorQuery}s to be executed.
  */
-@Stability.Volatile
+@Stability.Uncommitted
 public class VectorSearch {
 
   private final List<VectorQuery> vectorQueries;

java-client/src/main/java/com/couchbase/client/java/search/vector/VectorSearchOptions.java

@@ -22,7 +22,7 @@
 /**
  * Options related to executing a {@link VectorSearch}.
  */
-@Stability.Volatile
+@Stability.Uncommitted
 public class VectorSearchOptions {
   private @Nullable VectorQueryCombination vectorQueryCombination;
 

kotlin-client/src/main/kotlin/com/couchbase/client/kotlin/Cluster.kt

@@ -39,7 +39,6 @@ import com.couchbase.client.kotlin.analytics.AnalyticsPriority
 import com.couchbase.client.kotlin.analytics.AnalyticsScanConsistency
 import com.couchbase.client.kotlin.analytics.internal.AnalyticsExecutor
 import com.couchbase.client.kotlin.annotations.UncommittedCouchbaseApi
-import com.couchbase.client.kotlin.annotations.VolatileCouchbaseApi
 import com.couchbase.client.kotlin.codec.JsonSerializer
 import com.couchbase.client.kotlin.diagnostics.DiagnosticsResult
 import com.couchbase.client.kotlin.diagnostics.PingResult
@@ -439,7 +438,7 @@ public class Cluster internal constructor(
      * @sample com.couchbase.client.kotlin.samples.searchSimpleVector
      * @sample com.couchbase.client.kotlin.samples.searchSpecMixedMode
      */
-    @VolatileCouchbaseApi
+    @UncommittedCouchbaseApi
     public fun search(
         indexName: String,
         spec: SearchSpec,

kotlin-client/src/main/kotlin/com/couchbase/client/kotlin/Scope.kt

@@ -41,7 +41,7 @@ import com.couchbase.client.kotlin.analytics.AnalyticsParameters
 import com.couchbase.client.kotlin.analytics.AnalyticsPriority
 import com.couchbase.client.kotlin.analytics.AnalyticsScanConsistency
 import com.couchbase.client.kotlin.analytics.internal.AnalyticsExecutor
-import com.couchbase.client.kotlin.annotations.VolatileCouchbaseApi
+import com.couchbase.client.kotlin.annotations.UncommittedCouchbaseApi
 import com.couchbase.client.kotlin.codec.JsonSerializer
 import com.couchbase.client.kotlin.internal.requireUnique
 import com.couchbase.client.kotlin.internal.toOptional
@@ -390,7 +390,7 @@ public class Scope(
      * @sample com.couchbase.client.kotlin.samples.searchSimpleVector
      * @sample com.couchbase.client.kotlin.samples.searchSpecMixedMode
      */
-    @VolatileCouchbaseApi
+    @UncommittedCouchbaseApi
     @SinceCouchbase("7.6")
     public fun search(
         indexName: String,

kotlin-client/src/main/kotlin/com/couchbase/client/kotlin/search/SearchSpec.kt

@@ -19,7 +19,7 @@ package com.couchbase.client.kotlin.search
 import com.couchbase.client.core.annotation.SinceCouchbase
 import com.couchbase.client.core.api.search.queries.CoreSearchRequest
 import com.couchbase.client.core.api.search.vector.CoreVectorQueryCombination
-import com.couchbase.client.kotlin.annotations.VolatileCouchbaseApi
+import com.couchbase.client.kotlin.annotations.UncommittedCouchbaseApi
 import com.couchbase.client.kotlin.search.SearchQuery.Companion.MatchOperator
 import java.time.Instant
 
@@ -43,7 +43,7 @@ import java.time.Instant
  * @sample com.couchbase.client.kotlin.samples.searchSpecVectorAllOf
  * @sample com.couchbase.client.kotlin.samples.searchSpecMixedMode
  */
-@VolatileCouchbaseApi
+@UncommittedCouchbaseApi
 public sealed class SearchSpec {
     internal abstract val coreRequest: CoreSearchRequest
 
@@ -54,7 +54,6 @@ public sealed class SearchSpec {
          *
          * @sample com.couchbase.client.kotlin.samples.searchSpecMixedMode
          */
-        @VolatileCouchbaseApi
         @SinceCouchbase("7.6")
         public fun mixedMode(
             searchQuery: SearchQuery,
@@ -413,7 +412,6 @@ public sealed class SearchSpec {
          * @sample com.couchbase.client.kotlin.samples.searchSpecVectorAnyOf
          * @sample com.couchbase.client.kotlin.samples.searchSpecMixedMode
          */
-        @VolatileCouchbaseApi
         @SinceCouchbase("7.6")
         public fun vector(
             field: String,
@@ -428,7 +426,7 @@ public sealed class SearchSpec {
          *
          * @sample com.couchbase.client.kotlin.samples.searchSpecVectorAnyOf
          */
-        @VolatileCouchbaseApi
+        @SinceCouchbase("7.6")
         public fun anyOf(
             vectorQueries: List<VectorQuery>,
         ): VectorSearchSpec = CompoundVectorSearchSpec(vectorQueries, CoreVectorQueryCombination.OR)
@@ -440,7 +438,7 @@ public sealed class SearchSpec {
          *
          * @sample com.couchbase.client.kotlin.samples.searchSpecVectorAnyOf
          */
-        @VolatileCouchbaseApi
+        @SinceCouchbase("7.6")
         public fun anyOf(
             first: VectorQuery,
             vararg remaining: VectorQuery,
@@ -453,7 +451,7 @@ public sealed class SearchSpec {
          *
          * @sample com.couchbase.client.kotlin.samples.searchSpecVectorAllOf
          */
-        @VolatileCouchbaseApi
+        @SinceCouchbase("7.6")
         public fun allOf(
             vectorQueries: List<VectorQuery>,
         ): VectorSearchSpec = CompoundVectorSearchSpec(vectorQueries, CoreVectorQueryCombination.AND)
@@ -465,7 +463,7 @@ public sealed class SearchSpec {
          *
          * @sample com.couchbase.client.kotlin.samples.searchSpecVectorAllOf
          */
-        @VolatileCouchbaseApi
+        @SinceCouchbase("7.6")
         public fun allOf(
             first: VectorQuery,
             vararg remaining: VectorQuery,

scala-client/src/main/scala/com/couchbase/client/scala/AsyncCluster.scala

@@ -17,7 +17,7 @@ package com.couchbase.client.scala
 
 import com.couchbase.client.core.Core
 import com.couchbase.client.core.annotation.Stability
-import com.couchbase.client.core.annotation.Stability.Volatile
+import com.couchbase.client.core.annotation.Stability.Uncommitted
 import com.couchbase.client.core.api.CoreCouchbaseOps
 import com.couchbase.client.core.diagnostics._
 import com.couchbase.client.core.env.Authenticator
@@ -264,7 +264,7 @@ class AsyncCluster(
     * @return a `Future` containing a `Success(SearchResult)` (which includes any returned rows) if successful,
     *         else a `Failure`
     */
-  @Volatile
+  @Uncommitted
   def search(
       indexName: String,
       request: SearchRequest
@@ -286,7 +286,7 @@ class AsyncCluster(
     * @return a `Future` containing a `Success(SearchResult)` (which includes any returned rows) if successful,
     *         else a `Failure`
     */
-  @Volatile
+  @Uncommitted
   def search(
       indexName: String,
       request: SearchRequest,

scala-client/src/main/scala/com/couchbase/client/scala/AsyncScope.scala

@@ -17,7 +17,7 @@ package com.couchbase.client.scala
 
 import com.couchbase.client.core.Core
 import com.couchbase.client.core.annotation.SinceCouchbase
-import com.couchbase.client.core.annotation.Stability.Volatile
+import com.couchbase.client.core.annotation.Stability.Uncommitted
 import com.couchbase.client.core.api.CoreCouchbaseOps
 import com.couchbase.client.core.api.manager.CoreBucketAndScope
 import com.couchbase.client.core.api.query.CoreQueryContext
@@ -172,7 +172,8 @@ class AsyncScope private[scala] (
     * @return a `Try` containing a `Success(SearchResult)` (which includes any returned rows) if successful,
     *         else a `Failure`
     */
-  @Volatile
+  @Uncommitted
+  @SinceCouchbase("7.6")
   def search(
       indexName: String,
       request: SearchRequest
@@ -192,7 +193,8 @@ class AsyncScope private[scala] (
     * @return a `Try` containing a `Success(SearchResult)` (which includes any returned rows) if successful,
     *         else a `Failure`
     */
-  @Volatile
+  @Uncommitted
+  @SinceCouchbase("7.6")
   def search(
       indexName: String,
       request: SearchRequest,

scala-client/src/main/scala/com/couchbase/client/scala/Cluster.scala

@@ -17,7 +17,7 @@
 package com.couchbase.client.scala
 
 import com.couchbase.client.core.annotation.Stability
-import com.couchbase.client.core.annotation.Stability.Volatile
+import com.couchbase.client.core.annotation.Stability.Uncommitted
 import com.couchbase.client.core.diagnostics._
 import com.couchbase.client.core.env.{Authenticator, PasswordAuthenticator}
 import com.couchbase.client.core.transaction.CoreTransactionsReactive
@@ -224,7 +224,7 @@ class Cluster private[scala] (
     * @return a `Try` containing a `Success(SearchResult)` (which includes any returned rows) if successful,
     *         else a `Failure`
     */
-  @Volatile
+  @Uncommitted
   def search(
       indexName: String,
       request: SearchRequest
@@ -247,7 +247,7 @@ class Cluster private[scala] (
     * @return a `Try` containing a `Success(SearchResult)` (which includes any returned rows) if successful,
     *         else a `Failure`
     */
-  @Volatile
+  @Uncommitted
   def search(
       indexName: String,
       request: SearchRequest,

scala-client/src/main/scala/com/couchbase/client/scala/ReactiveCluster.scala

@@ -18,7 +18,7 @@ package com.couchbase.client.scala
 
 import com.couchbase.client.core.Core
 import com.couchbase.client.core.annotation.Stability
-import com.couchbase.client.core.annotation.Stability.Volatile
+import com.couchbase.client.core.annotation.Stability.Uncommitted
 import com.couchbase.client.core.diagnostics.{DiagnosticsResult, PingResult}
 import com.couchbase.client.core.env.PasswordAuthenticator
 import com.couchbase.client.core.protostellar.CoreProtostellarUtil
@@ -222,7 +222,7 @@ class ReactiveCluster(val async: AsyncCluster) {
     * @return an `SMono` containing a [[ReactiveSearchResult]] which includes a Flux giving streaming access to any
     *         returned rows
     */
-  @Volatile
+  @Uncommitted
   def search(
       indexName: String,
       request: SearchRequest
@@ -243,7 +243,7 @@ class ReactiveCluster(val async: AsyncCluster) {
     * @return an `SMono` containing a [[ReactiveSearchResult]] which includes a Flux giving streaming access to any
     *         returned rows
     */
-  @Volatile
+  @Uncommitted
   def search(
       indexName: String,
       request: SearchRequest,