Merge pull request #1965 from redis/DOC-5556-lettuce-query-examples

DOC-5556 lettuce index/query example

Author: andy-stark-redis

build/local_examples.py

@@ -51,6 +51,24 @@ def get_client_name_from_language(language: str) -> str:
     return LANGUAGE_TO_CLIENT.get(language, language.title())
 
 
+def get_client_name_from_language_and_path(language: str, path: str) -> str:
+    """Get client name from language with path-based overrides.
+
+    For Java (.java) files, override based on path substrings:
+    - If 'lettuce-async' in path -> Java-Async
+    - If 'lettuce-reactive' in path -> Java-Reactive
+
+    Substring checks are case-sensitive and can appear anywhere in the path.
+    """
+    if language == 'java':
+        if 'lettuce-async' in path:
+            return 'Java-Async'
+        if 'lettuce-reactive' in path:
+            return 'Java-Reactive'
+    # Default behavior for all languages (and Java fallback)
+    return get_client_name_from_language(language)
+
+
 def get_example_id_from_file(path: str) -> str:
     """Extract example ID from the first line of a file."""
     try:
@@ -136,8 +154,8 @@ def process_local_examples(local_examples_dir: str = 'local_examples',
             # Process with Example class
             example = Example(language, target_file)
 
-            # Get client name
-            client_name = get_client_name_from_language(language)
+            # Get client name (with Java path-based overrides)
+            client_name = get_client_name_from_language_and_path(language, source_file)
 
             # Create metadata
             example_metadata = {

content/develop/clients/lettuce/queryjson.md

@@ -0,0 +1,123 @@
+---
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+description: Learn how to use the Redis query engine with JSON and hash documents.
+linkTitle: Index and query documents
+title: Index and query documents
+weight: 2
+---
+
+This example shows how to create a
+[search index]({{< relref "/develop/ai/search-and-query/indexing" >}})
+for [JSON]({{< relref "/develop/data-types/json" >}}) documents and
+run queries against the index. It then goes on to show the slight differences
+in the equivalent code for [hash]({{< relref "/develop/data-types/hashes" >}})
+documents.
+
+## Initialize
+
+Make sure that you have [Redis Open Source]({{< relref "/operate/oss_and_stack/" >}})
+or another Redis server available. Also install the
+[Lettuce]({{< relref "/develop/clients/lettuce" >}}) client library if you
+haven't already done so.
+
+Add the following dependencies. All of them are applicable to both JSON and hash,
+except for the `JsonParser`, `JsonPath`, and `JsonObject` classes.
+
+{{< clients-example lettuce_home_json import >}}
+{{< /clients-example >}}
+
+## Create data
+
+Create some test data to add to the database:
+
+{{< clients-example lettuce_home_json create_data >}}
+{{< /clients-example >}}
+
+## Add the index
+
+Connect to your Redis database. The code below shows the most
+basic connection but see
+[Connect to the server]({{< relref "/develop/clients/lettuce/connect" >}})
+to learn more about the available connection options.
+
+{{< clients-example lettuce_home_json connect >}}
+{{< /clients-example >}}
+
+Create an index. In this example, only JSON documents with the key prefix `user:` are indexed. For more information, see [Query syntax]({{< relref "/develop/ai/search-and-query/query/" >}}).
+
+{{< clients-example lettuce_home_json make_index >}}
+{{< /clients-example >}}
+
+## Add the data
+
+Add the three sets of user data to the database as
+[JSON]({{< relref "/develop/data-types/json" >}}) objects.
+If you use keys with the `user:` prefix then Redis will index the
+objects automatically as you add them:
+
+{{< clients-example lettuce_home_json add_data >}}
+{{< /clients-example >}}
+
+## Query the data
+
+You can now use the index to search the JSON objects. The
+[query]({{< relref "/develop/ai/search-and-query/query" >}})
+below searches for objects that have the text "Paul" in any field
+and have an `age` value in the range 30 to 40:
+
+{{< clients-example lettuce_home_json query1 >}}
+{{< /clients-example >}}
+
+Specify query options to return only the `city` field:
+
+{{< clients-example lettuce_home_json query2 >}}
+{{< /clients-example >}}
+
+Use an
+[aggregation query]({{< relref "/develop/ai/search-and-query/query/aggregation" >}})
+to count all users in each city.
+
+{{< clients-example lettuce_home_json query3 >}}
+{{< /clients-example >}}
+
+## Differences with hash documents
+
+Indexing for hash documents is very similar to JSON indexing but you
+need to specify some slightly different options.
+
+When you create the schema for a hash index, you don't need to
+add aliases for the fields, since you use the basic names to access
+the fields. Also, you must use `CreateArgs.TargetType.HASH` for the `On()`
+option of `CreateArgs` when you create the index. The code below shows these
+changes with a new index called `hash-idx:users`, which is otherwise the same as
+the `idx:users` index used for JSON documents in the previous examples.
+
+{{< clients-example lettuce_home_json make_hash_index >}}
+{{< /clients-example >}}
+
+Use [`hset()`]({{< relref "/commands/hset" >}}) to add the hash
+documents instead of [`jsonSet()`]({{< relref "/commands/json.set" >}}).
+
+{{< clients-example lettuce_home_json add_hash_data >}}
+{{< /clients-example >}}
+
+The query commands work the same here for hash as they do for JSON (but
+the name of the hash index is different). The results are returned in 
+a `List` of `SearchReply.SearchResult<String, String>` objects, as with JSON:
+
+{{< clients-example lettuce_home_json query1_hash >}}
+{{< /clients-example >}}
+
+## More information
+
+See the [Redis query engine]({{< relref "/develop/ai/search-and-query" >}}) docs
+for a full description of all query features with examples.

content/develop/clients/redis-py/vecsets.md

@@ -47,7 +47,7 @@ pip install sentence-transformers
 
 In a new Python file, import the required classes:
 
-{{< clients-example set="home_vecsets" step="import" >}}
+{{< clients-example set="home_vecsets" step="import" lang_filter="Python" >}}
 {{< /clients-example >}}
 
 The first of these imports is the
@@ -61,15 +61,15 @@ tokens (see
 at the [Hugging Face](https://huggingface.co/) docs to learn more about the way tokens
 are related to the original text).
 
-{{< clients-example set="home_vecsets" step="model" >}}
+{{< clients-example set="home_vecsets" step="model" lang_filter="Python" >}}
 {{< /clients-example >}}
 
 ## Create the data
 
 The example data is contained a dictionary with some brief
 descriptions of famous people:
 
-{{< clients-example set="home_vecsets" step="data" >}}
+{{< clients-example set="home_vecsets" step="data" lang_filter="Python" >}}
 {{< /clients-example >}}
 
 ## Add the data to a vector set
@@ -99,7 +99,7 @@ The call to `vadd()` also adds the `born` and `died` values from the
 original dictionary as attribute data. You can access this during a query
 or by using the [`vgetattr()`]({{< relref "/commands/vgetattr" >}}) method.
 
-{{< clients-example set="home_vecsets" step="add_data" >}}
+{{< clients-example set="home_vecsets" step="add_data" lang_filter="Python" >}}
 {{< /clients-example >}}
 
 ## Query the vector set
@@ -112,7 +112,7 @@ of the set, ranked in order of similarity to the query.
 
 Start with a simple query for "actors":
 
-{{< clients-example set="home_vecsets" step="basic_query" >}}
+{{< clients-example set="home_vecsets" step="basic_query" lang_filter="Python" >}}
 {{< /clients-example >}}
 
 This returns the following list of elements (formatted slightly for clarity):
@@ -131,7 +131,7 @@ on the information contained in the embedding model.
 You can use the `count` parameter of `vsim()` to limit the list of elements
 to just the most relevant few items:
 
-{{< clients-example set="home_vecsets" step="limited_query" >}}
+{{< clients-example set="home_vecsets" step="limited_query" lang_filter="Python" >}}
 {{< /clients-example >}}
 
 The reason for using text embeddings rather than simple text search
@@ -141,7 +141,7 @@ different. For example, the word "entertainer" doesn't appear in any of the
 descriptions but if you use it as a query, the actors and musicians are ranked
 highest in the results list:
 
-{{< clients-example set="home_vecsets" step="entertainer_query" >}}
+{{< clients-example set="home_vecsets" step="entertainer_query" lang_filter="Python" >}}
 {{< /clients-example >}}
 
 Similarly, if you use "science" as a query, you get the following results:
@@ -162,7 +162,7 @@ with `vsim()` to restrict the search further. For example,
 repeat the "science" query, but this time limit the results to people
 who died before the year 2000:
 
-{{< clients-example set="home_vecsets" step="filtered_query" >}}
+{{< clients-example set="home_vecsets" step="filtered_query" lang_filter="Python" >}}
 {{< /clients-example >}}
 
 Note that the boolean filter expression is applied to items in the list