improvements

Author: RichardSmedley

modules/howtos/pages/encrypting-using-sdk.adoc

@@ -179,47 +179,10 @@ include::devguide:example$java/EncryptingUsingSDK.java[tag=encrypting_using_sdk_
 [#migration-from-sdk2]
 == Migrating from SDK 2
 
-WARNING: SDK 2 cannot read fields encrypted by SDK 3.
+SDK 2.x reached end-of-life long ago,
+but should you have fields encrypted by SDK 2.x, and the need to read them from SDK 3.x, 
+then follow the steps in the https://docs-archive.couchbase.com/java-sdk/3.4/howtos/encrypting-using-sdk.html#migration-from-sdk2[archived documents].
 
-It's inadvisable to have both the old and new versions of your application active at the same time.
-The simplest way to migrate is to do an offline upgrade during a scheduled a maintenance window.
-For an online upgrade without downtime, consider a https://en.wikipedia.org/wiki/Blue-green_deployment[blue-green deployment^].
 
-SDK 3 requires additional configuration to read fields encrypted by SDK 2.
-The rest of this section describes how to configure Field-Level Encryption in SDK 3 for backwards compatibility with SDK 2.
-
-[#configure-field-name-prefix]
-=== Changing the field name prefix
-
-In SDK 2, the default prefix for encrypted field names was `\__crypt_`.
-This caused problems for Couchbase Sync Gateway, which does not like field names to begin with an underscore.
-In SDK 3, the default prefix is `encrypted$`.
-
-For compatibility with SDK 2, you can configure the `CryptoManager` to use the old `\__crypt_` prefix:
-
-[source,java]
-----
-include::devguide:example$java/EncryptingUsingSDK.java[tag=legacy_field_name_prefix,indent=0]
-----
-
-Alternatively, you can https://forums.couchbase.com/t/replacing-field-name-prefix/28786[rename the existing fields] using a {sqlpp_url}[{sqlpp} (formerly N1QL)] statement.
-
-WARNING: In SDK 2, only top-level fields could be encrypted.
-SDK 3 allows encrypting fields at any depth.
-If you decide to rename the existing fields, make sure to do so _before_ writing any encrypted fields below the top level, otherwise it may be difficult to rename the nested fields using a generic {sqlpp} statement.
-
-
-[#configure-legacy-decrypters]
-=== Enabling decrypters for legacy algorithms
-
-The encryption algorithms used by SDK 2 are deprecated, and are no longer used for encrypting new data.
-To enable decrypting fields written by SDK 2, register the legacy decrypters when configuring the `CryptoManager`:
-
-[source,java]
-----
-include::devguide:example$java/EncryptingUsingSDK.java[tag=legacy_decrypters,indent=0]
-----
-
-NOTE: The legacy decrypters require a mapping function.
-For AES, this function accepts an encryption key name and returns the corresponding signing key name.
-For RSA, this function accepts a public key name and returns the corresponding private key name.
+IMPORTANT: The encryption algorithms used by SDK 2 are deprecated, and are no longer used for encrypting new data.
+Do not rely on the security of outdated encryption algorithms.

modules/howtos/pages/vector-searching-with-sdk.adoc

@@ -43,18 +43,125 @@ Hybrid searches can combine Vector, geo-spatial search, range search, and tradit
 ////
 
 
-This is currently implemented using xref:full-text-searching-with-sdk.adoc[Search Indexes], and can even be combined with traditional full text search queries.
-Vector embeddings can be an array of floats or a xref:server:vector-search:run-vector-search-ui.adoc#base64[base64 encoded string].
+Vector Search has been available in Couchbase Capella Operational and self-managed Server since version 7.6, using the COuchbase Server Search Service.
+Version 8.0 introduces vector query using Global Secondary Indexes (GSI), the query index --
+using either a fast Hyperscale index, or a composite index to combine scala queries with semantic search.
+
+For fast and scalable vector query, use one of the GSI choices -- detailed in the next section.
+If you don't require the scale of vector query with GSI, or need combined searches, then consider {#vector-search-with-the-search-service}.
+
+
+
+== Vector Search With the Query Service and GSI
+
+From the SDK, a vector query using GSI is the same as any other query.
+However, you will need to build one or more indexes.
+
+=== Prerequisites
+
+Couchbase Server 8.0.0 or newer -- or a recent Capella instance.
+
+Your chosen xref:server:vector-index:use-vector-indexes.adoc[vector index] -- 
+hyperscale or composite.
+
+
+=== Examples
+
+These examples simply take the {sqlpp} queries shown in the
+xref:server:vector-index:composite-vector-index.html#examples[Composite Index] and
+xref:server:vector-index:hyperscale-vector-index.html#query-example[Hyperscale Index] example pages,
+wrapped inside the {name-sdk} Query API.
+
+
+
+
+
+.With Composite Vector Index
+[source,java]
+----
+package com.couchbase.client.java.examples.query;
+
+import com.couchbase.client.java.Bucket;
+import com.couchbase.client.java.Cluster;
+import com.couchbase.client.java.query.QueryResult;
+
+public class SimpleQueryExample {
 
+  public static void main(String... args) {
+    Cluster cluster = Cluster.connect("127.0.0.1", "Administrator", "password");
+    Bucket bucket = cluster.bucket("travel-sample");
 
-== Prerequisites
+    QueryResult result = cluster.query(SELECT RAW OBJECT_PUT(d, "embedding_vector_dot",ARRAY_CONCAT(d.embedding_vector_dot[0:4], ["..."])) FROM `vector-sample`.`color`.`rgb` AS d USE KEYS ["#FFEFD5"]);
+    System.out.println(result.rowsAsObject());
+  }
+
+}
+----
+
+
+
+
+
+.Hyperscale Index Example
+[source,java]
+----
+import static com.couchbase.client.java.query.QueryOptions.queryOptions;
+
+import com.couchbase.client.core.error.CouchbaseException;
+import com.couchbase.client.java.*;
+import com.couchbase.client.java.json.*;
+import com.couchbase.client.java.query.*;
+
+// tag::vector-hyperscale[]
+public class SimpleQueryCloud {
+  // Update these variables to point to your Couchbase Capella instance and credentials.
+  static String connectionString = "couchbases://cb.<your-endpoint-here>.cloud.couchbase.com";
+  static String username = "Administrator";
+  static String password = "password";
+
+  public static void main(String[] args) throws Exception {
+    Cluster cluster = Cluster.connect(
+    connectionString,
+    ClusterOptions.clusterOptions(username, password).environment(env -> {
+    env.applyProfile("wan-development");
+    })
+    );
+
+    { 
+      try {
+        final QueryResult result = cluster.query("SELECT d.id, d.question, d.wanted_similar_color_from_search, ARRAY_CONCAT(d.couchbase_search_query.knn[0].vector[0:4], ["..."]) AS vector FROM `vector-sample`.`color`.`rgb-questions` AS d WHERE d.id = "#87CEEB",
+        queryOptions().metrics(true));
+
+        for (JsonObject row : result.rowsAsObject()) {
+          System.out.println(row);
+      }
+
+      System.out.println("Reported execution time: " + result.metaData().metrics().get().executionTime());
+
+      } catch (CouchbaseException ex) {
+        ex.printStackTrace();
+      }
+    }
+  }
+}
+// end::vector-hyperscale[]
+----
+
+
+
+== Vector Search With the Search Service
+
+Vector search is also implemented using xref:full-text-searching-with-sdk.adoc[Search Indexes], and can be combined with traditional full text search queries.
+Vector embeddings can be an array of floats or a xref:server:vector-search:run-vector-search-ui.adoc#base64[base64 encoded string].
+
+=== Prerequisites
 
 Couchbase Server 7.6.0
 (7.6.2 for base64-encoded vectors) -- or recent Capella instance.
 
-== Examples
+=== Examples
 
-=== Single vector query
+==== Single vector query
 
 In this first example we are performing a single vector query:
 
@@ -80,7 +187,7 @@ If it was a global index we would use `cluster.search()` instead - see <<Scoped
 
 It returns the same `SearchResult` detailed earlier.
 
-=== Multiple vector queries
+==== Multiple vector queries
 You can run multiple vector queries together:
 
 [source,java]
@@ -90,7 +197,7 @@ include::devguide:example$java/Search.java[tag=vector3,indent=0]
 
 How the results are combined (ANDed or ORed) can be controlled with `vectorSearchOptions().vectorQueryCombination()`.
 
-=== Combining FTS and vector queries
+==== Combining FTS and vector queries
 
 You can combine a traditional FTS query with vector queries:
 
@@ -104,7 +211,7 @@ How the results are combined (ANDed or ORed) can be controlled with `vectorSearc
 
 
 ////
-=== FTS queries
+==== FTS queries
 And note that traditional FTS queries, without vector search, are also supported with the new `cluster.search()` / `scope.search()` APIs:
 [source,java]
 ----
@@ -125,6 +232,13 @@ include::devguide:example$java/Search.java[tag=vector4,indent=0]
 
 == Further Reading
 
+
+=== Vector Query
+
+
+
+=== Vector Search
+
 * xref:server:vector-search:vector-search.adoc[Vector Search for AI Apps docs (self-managed Couchbase Server)]
 * xref:cloud::vector-search:vector-search.adoc[Vector Search for AI Apps docs (Capella DBaaS)]
 * Vector Search in the https://docs.couchbase.com/sdk-api/couchbase-java-client/com/couchbase/client/java/search/vector/VectorSearch.html[Java API reference].