Merge branch 'main' into DOC-5048

Author: dwdougherty

content/develop/clients/jedis/produsage.md

@@ -15,12 +15,62 @@ title: Production usage
 weight: 6
 ---
 
-The following sections explain how to handle situations that may occur
-in your production environment.
+This guide offers recommendations to get the best reliability and
+performance in your production environment.
+
+## Checklist
+
+Each item in the checklist below links to the section
+for a recommendation. Use the checklist icons to record your
+progress in implementing the recommendations.
+
+{{< checklist "prodlist" >}}
+    {{< checklist-item "#connection-pooling" >}}Connection pooling{{< /checklist-item >}}
+    {{< checklist-item "#client-side-caching" >}}Client-side caching{{< /checklist-item >}}
+    {{< checklist-item "#timeouts" >}}Timeouts{{< /checklist-item >}}
+    {{< checklist-item "#health-checks" >}}Health checks{{< /checklist-item >}}
+    {{< checklist-item "#exception-handling" >}}Exception handling{{< /checklist-item >}}
+    {{< checklist-item "#dns-cache-and-redis" >}}DNS cache and Redis{{< /checklist-item >}}
+{{< /checklist >}}
+
+## Recommendations
+
+The sections below offer recommendations for your production environment. Some
+of them may not apply to your particular use case.
+
+### Connection pooling
+
+Example code often opens a connection at the start, demonstrates a feature,
+and then closes the connection at the end. However, production code
+typically uses connections many times intermittently. Repeatedly opening
+and closing connections has a performance overhead.
+
+Use [connection pooling]({{< relref "/develop/clients/pools-and-muxing" >}})
+to avoid the overhead of opening and closing connections without having to
+write your own code to cache and reuse open connections. See
+[Connect with a connection pool]({{< relref "/develop/clients/jedis/connect#connect-with-a-connection-pool" >}})
+to learn how to use this technique with Jedis.
+
+### Client-side caching
+
+[Client-side caching]({{< relref "/develop/clients/client-side-caching" >}})
+involves storing the results from read-only commands in a local cache. If the
+same command is executed again later, the results can be obtained from the cache,
+without contacting the server. This improves command execution time on the client,
+while also reducing network traffic and server load. See
+[Connect using client-side caching]({{< relref "/develop/clients/jedis/connect#connect-using-client-side-caching" >}})
+for more information and example code.
 
 ### Timeouts
 
-To set a timeout for a connection, use the `JedisPooled` or `JedisPool` constructor with the `timeout` parameter, or use `JedisClientConfig` with the `socketTimeout` and `connectionTimeout` parameters:
+If a network or server error occurs while your code is opening a
+connection or issuing a command, it can end up hanging indefinitely.
+You can prevent this from happening by setting timeouts for socket
+reads and writes and for opening connections.
+
+To set a timeout for a connection, use the `JedisPooled` or `JedisPool` constructor with the `timeout` parameter, or use `JedisClientConfig` with the `socketTimeout` and `connectionTimeout` parameters.
+(The socket timeout is the maximum time allowed for reading or writing data while executing a
+command. The connection timeout is the maximum time allowed for establishing a new connection.)
 
 ```java
 HostAndPort hostAndPort = new HostAndPort("localhost", 6379);
@@ -34,9 +84,33 @@ JedisPooled jedisWithTimeout = new JedisPooled(hostAndPort,
 );
 ```
 
+### Health checks
+
+If your code doesn't access the Redis server continuously then it
+might be useful to make a "health check" periodically (perhaps once
+every few seconds). You can do this using a simple
+[`PING`]({{< relref "/commands/ping" >}}) command:
+
+```java
+try (Jedis jedis = jedisPool.getResource()) {
+  if (! "PONG".equals(jedis.ping())) {
+    // Report problem.
+  }
+}
+```
+
+Health checks help to detect problems as soon as possible without
+waiting for a user to report them.
+
 ### Exception handling
 
-The Jedis Exception Hierarchy is rooted on `JedisException`, which implements `RuntimeException`, and are therefore all unchecked exceptions.
+Redis handles many errors using return values from commands, but there
+are also situations where exceptions can be thrown. In production code,
+you should handle exceptions as they occur.
+
+The Jedis exception hierarchy is rooted on `JedisException`, which implements
+`RuntimeException`. All exceptions in the hierarchy are therefore unchecked
+exceptions.
 
 ```
 JedisException

content/develop/clients/jedis/vecsearch.md

@@ -31,6 +31,9 @@ of their meaning.
 In the example below, we use the [HuggingFace](https://huggingface.co/) model
 [`all-mpnet-base-v2`](https://huggingface.co/sentence-transformers/all-mpnet-base-v2)
 to generate the vector embeddings to store and index with Redis Query Engine.
+The code is first demonstrated for hash documents with a
+separate section to explain the
+[differences with JSON documents](#differences-with-json-documents).
 
 ## Initialize
 
@@ -75,6 +78,7 @@ import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
 import java.util.Map;
 import java.util.List;
+import org.json.JSONObject;
 
 // Tokenizer to generate the vector embeddings.
 import ai.djl.huggingface.tokenizers.HuggingFaceTokenizer;
@@ -185,8 +189,9 @@ as shown below to create the embedding that represents the `content` field.
 The `getIds()` method that follows `encode()` obtains the vector
 of `long` values which we then convert to a `float` array stored as a `byte`
 string using our helper method. Use the `byte` string representation when you are
-indexing hash objects (as we are here), but use the default list of `float` for
-JSON objects. Note that when we set the `embedding` field, we must use an overload
+indexing hash objects (as we are here), but use an array of `float` for
+JSON objects (see [Differences with JSON objects](#differences-with-json-documents)
+below). Note that when we set the `embedding` field, we must use an overload
 of `hset()` that requires `byte` arrays for each of the key, the field name, and
 the value, which is why we include the `getBytes()` calls on the strings.
 
@@ -281,6 +286,147 @@ For this model, the text *"That is a happy dog"*
 is the result judged to be most similar in meaning to the query text
 *"That is a happy person"*.
 
+## Differences with JSON documents
+
+Indexing JSON documents is similar to hash indexing, but there are some
+important differences. JSON allows much richer data modeling with nested fields, so
+you must supply a [path]({{< relref "/develop/data-types/json/path" >}}) in the schema
+to identify each field you want to index. However, you can declare a short alias for each
+of these paths (using the `as()` option) to avoid typing it in full for
+every query. Also, you must specify `IndexDataType.JSON` when you create the index.
+
+The code below shows these differences, but the index is otherwise very similar to
+the one created previously for hashes:
+
+```java
+SchemaField[] jsonSchema = {
+    TextField.of("$.content").as("content"),
+    TagField.of("$.genre").as("genre"),
+    VectorField.builder()
+        .fieldName("$.embedding").as("embedding")
+        .algorithm(VectorAlgorithm.HNSW)
+        .attributes(
+            Map.of(
+                "TYPE", "FLOAT32",
+                "DIM", 768,
+                "DISTANCE_METRIC", "L2"
+            )
+        )
+        .build()
+};
+
+jedis.ftCreate("vector_json_idx",
+    FTCreateParams.createParams()
+        .addPrefix("jdoc:")
+        .on(IndexDataType.JSON),
+        jsonSchema
+);
+```
+
+An important difference with JSON indexing is that the vectors are
+specified using arrays of `float` instead of binary strings. This requires
+a modified version of the `longsToFloatsByteString()` method
+used previously:
+
+```java
+public static float[] longArrayToFloatArray(long[] input) {
+    float[] floats = new float[input.length];
+    for (int i = 0; i < input.length; i++) {
+        floats[i] = input[i];
+    }
+    return floats;
+}
+```
+
+Use [`jsonSet()`]({{< relref "/commands/json.set" >}}) to add the data
+instead of [`hset()`]({{< relref "/commands/hset" >}}). Use instances
+of `JSONObject` to supply the data instead of `Map`, as you would for
+hash objects.
+
+```java
+String jSentence1 = "That is a very happy person";
+
+JSONObject jdoc1 = new JSONObject()
+        .put("content", jSentence1)
+        .put("genre", "persons")
+        .put(
+            "embedding",
+            longArrayToFloatArray(
+                sentenceTokenizer.encode(jSentence1).getIds()
+            )
+        );
+
+jedis.jsonSet("jdoc:1", Path2.ROOT_PATH, jdoc1);
+
+String jSentence2 = "That is a happy dog";
+
+JSONObject jdoc2 = new JSONObject()
+        .put("content", jSentence2)
+        .put("genre", "pets")
+        .put(
+            "embedding",
+            longArrayToFloatArray(
+                sentenceTokenizer.encode(jSentence2).getIds()
+            )
+        );
+
+jedis.jsonSet("jdoc:2", Path2.ROOT_PATH, jdoc2);
+
+String jSentence3 = "Today is a sunny day";
+
+JSONObject jdoc3 = new JSONObject()
+        .put("content", jSentence3)
+        .put("genre", "weather")
+        .put(
+            "embedding",
+            longArrayToFloatArray(
+                sentenceTokenizer.encode(jSentence3).getIds()
+            )
+        );
+
+jedis.jsonSet("jdoc:3", Path2.ROOT_PATH, jdoc3);
+```
+
+The query is almost identical to the one for the hash documents. This
+demonstrates how the right choice of aliases for the JSON paths can
+save you having to write complex queries. An important thing to notice
+is that the vector parameter for the query is still specified as a
+binary string (using the `longsToFloatsByteString()` method), even though
+the data for the `embedding` field of the JSON was specified as an array.
+
+```java
+String jSentence = "That is a happy person";
+
+int jK = 3;
+Query jq = new Query("*=>[KNN $K @embedding $BLOB AS distance]").
+                    returnFields("content", "distance").
+                    addParam("K", jK).
+                    addParam(
+                        "BLOB",
+                        longsToFloatsByteString(
+                            sentenceTokenizer.encode(jSentence).getIds()
+                        )
+                    )
+                    .setSortBy("distance", true)
+                    .dialect(2);
+
+// Execute the query
+List<Document> jDocs = jedis
+        .ftSearch("vector_json_idx", jq)
+        .getDocuments();
+
+```
+
+Apart from the `jdoc:` prefixes for the keys, the result from the JSON
+query is the same as for hash:
+
+```
+Results:
+ID: jdoc:2, Distance: 1411344, Content: That is a happy dog
+ID: jdoc:1, Distance: 9301635, Content: That is a very happy person
+ID: jdoc:3, Distance: 67178800, Content: Today is a sunny day
+```
+
 ## Learn more
 
 See

content/develop/clients/lettuce/produsage.md

@@ -29,6 +29,31 @@ In some cases, the defaults are based on environment-specific settings (e.g., op
 For more details on setting specific timeouts, see the [Lettuce reference guide](https://redis.github.io/lettuce/).
 {{% /alert  %}}
 
+### Prerequisites
+
+To set TCP-level timeouts, you need to ensure you have one of [Netty Native Transports](https://netty.io/wiki/native-transports.html) installed. The most common one is `netty-transport-native-epoll`, which is used for Linux systems. You can add it to your project by including the following dependency in your `pom.xml` file:
+
+```xml
+<dependency>
+    <groupId>io.netty</groupId>
+    <artifactId>netty-transport-native-epoll</artifactId>
+    <version>${netty.version}</version> <!-- e.g., 4.1.118.Final -->
+    <classifier>linux-x86_64</classifier>
+</dependency>
+```
+
+Once you have the native transport dependency, you can verify that by using the following code:
+
+```java
+logger.info("Lettuce epool is available: {}", EpollProvider.isAvailable());
+```
+
+If the snippet above returns `false`, you need to enable debugging logging for `io.lettuce.core` and `io.netty` to see why the native transport is not available.
+
+For more information on using Netty Native Transport, see the [Lettuce reference guide](https://redis.github.io/lettuce/advanced-usage/#native-transports).
+
+### Setting timeouts
+
 Below is an example of setting socket-level timeouts. The `TCP_USER_TIMEOUT` setting is useful for scenarios where the server stops responding without acknowledging the last request, while the `KEEPALIVE` setting is good for detecting dead connections where there is no traffic between the client and the server.
 
 ```java