feat: add multiple prefix support to SearchIndex.fromExisting()

Port of Python RedisVL multiple prefix support (PR #392, commit c3c1733).
Enables SearchIndex.fromExisting() to preserve all prefixes from Redis
indices that were created with multiple PREFIX values, not just the first.

Implementation handles Union[String, List<String>] prefix type to match
Python behavior. Normalizes to first prefix for Redis key construction
while preserving all prefixes in schema definition for comparison and
serialization.

Changes:

**IndexSchema.Index:**
- Changed `prefix` field from String to Object (supports String or List<String>)
- Added `getPrefix()` - normalizes to first prefix for key construction
- Added `getPrefixRaw()` - returns raw prefix (String or List)
- Added `setPrefix(List<String>)` - overload with single-element normalization
- Added package-private `setPrefixRaw(Object)` for builder use
- Updated `getIndex()` to preserve raw prefix in defensive copy

**IndexSchema.Builder:**
- Updated `prefix` field to Object type
- Added `prefix(List<String>)` overload with normalization
- Updated `build()` to set raw prefix for multi-element lists
- Updated `index(Index)` to use getPrefixRaw()

**SearchIndex:**
- Updated `fromExisting()` to preserve all prefixes
- Normalizes single-element prefix lists to strings for backward compatibility
- Captures all prefixes when multiple are configured

**Tests:**
- New IndexSchemaPrefixTest with 6 unit tests
- New integration test testFromExistingMultiplePrefixes()
- All tests verify backward compatibility and multi-prefix handling

Test Coverage:
- Single prefix as String (backward compatible)
- Single-element prefix list normalized to String
- Multiple prefixes preserved as List
- getPrefix() returns first prefix for key construction
- getPrefixRaw() returns original List or String
- Serialization preserves multiple prefixes
- Integration test with real Redis index

Backward compatibility maintained by normalizing single-element prefix
lists to strings when loading from Redis. Ensures schema comparisons
work correctly between existing and new index configurations.

Python reference: /redis-vl-python/tests/unit/test_convert_index_info.py
Python reference: /redis-vl-python/tests/integration/test_search_index.py:172-243

Resolves #258, #392

Author: bsbodden

core/src/main/java/com/redis/vl/index/SearchIndex.java

@@ -376,7 +376,13 @@ public static SearchIndex fromExisting(String indexName, UnifiedJedis client) {
           @SuppressWarnings("unchecked")
           List<String> prefixes = (List<String>) indexDef.get(i + 1);
           if (!prefixes.isEmpty()) {
-            builder.prefix(prefixes.get(0));
+            // Python port: preserve all prefixes (issue #258/#392)
+            // Normalize single-element lists to string for backward compatibility
+            if (prefixes.size() == 1) {
+              builder.prefix(prefixes.get(0));
+            } else {
+              builder.prefix(prefixes);
+            }
           }
         } else if ("key_type".equals(key) && i + 1 < indexDef.size()) {
           String keyType = indexDef.get(i + 1).toString();

core/src/main/java/com/redis/vl/schema/IndexSchema.java

@@ -472,8 +472,9 @@ private Map<String, Object> toMap() {
 
     Map<String, Object> indexData = new HashMap<>();
     indexData.put("name", index.getName());
-    if (index.getPrefix() != null) {
-      indexData.put("prefix", index.getPrefix());
+    if (index.getPrefixRaw() != null) {
+      // Serialize raw prefix (String or List<String>)
+      indexData.put("prefix", index.getPrefixRaw());
     }
     indexData.put("storage_type", index.getStorageType().getValue());
     data.put("index", indexData);
@@ -498,7 +499,8 @@ public Index getIndex() {
     // Return a new Index with the same values to prevent external modification
     Index copy = new Index();
     copy.setName(index.getName());
-    copy.setPrefix(index.getPrefix());
+    // Use setPrefixRaw to preserve List<String> prefixes
+    copy.setPrefixRaw(index.getPrefixRaw());
     copy.setKeySeparator(index.getKeySeparator());
     copy.setStorageType(index.getStorageType());
     return copy;
@@ -564,7 +566,13 @@ public String getValue() {
   @Getter
   public static class Index {
     private String name;
-    private String prefix;
+
+    /**
+     * The prefix(es) used for Redis keys. Can be either a String (single prefix) or List<String>
+     * (multiple prefixes). Python port: supports Union[str, List[str]] for compatibility.
+     */
+    private Object prefix;
+
     private String keySeparator = ":";
     private StorageType storageType = StorageType.HASH;
 
@@ -599,23 +607,71 @@ public void setName(String name) {
     }
 
     /**
-     * Get the key prefix
+     * Get the key prefix (normalized).
+     *
+     * <p>If multiple prefixes are configured, returns the first one for Redis key construction.
+     * This matches Python behavior: prefix[0] if isinstance(prefix, list) else prefix.
      *
-     * @return the key prefix
+     * @return the normalized key prefix (first prefix if multiple), or null if not set
      */
     public String getPrefix() {
+      if (prefix instanceof List) {
+        @SuppressWarnings("unchecked")
+        List<String> prefixList = (List<String>) prefix;
+        return prefixList.isEmpty() ? null : prefixList.get(0);
+      }
+      return (String) prefix;
+    }
+
+    /**
+     * Get the raw prefix value (can be String or List<String>).
+     *
+     * <p>This method returns the prefix exactly as stored, without normalization. Use {@link
+     * #getPrefix()} for the normalized prefix used in key construction.
+     *
+     * @return the raw prefix (String or List<String>), or null if not set
+     */
+    public Object getPrefixRaw() {
       return prefix;
     }
 
     /**
-     * Set the key prefix
+     * Set the key prefix (single prefix)
      *
      * @param prefix the key prefix to set
      */
     public void setPrefix(String prefix) {
       this.prefix = prefix;
     }
 
+    /**
+     * Set multiple key prefixes.
+     *
+     * <p>Normalizes single-element lists to strings for backward compatibility. Python port:
+     * matches behavior in convert_index_info_to_schema.
+     *
+     * @param prefixes the list of key prefixes to set
+     */
+    public void setPrefix(List<String> prefixes) {
+      if (prefixes == null) {
+        this.prefix = null;
+      } else if (prefixes.size() == 1) {
+        // Normalize single-element lists to string for backward compatibility
+        this.prefix = prefixes.get(0);
+      } else {
+        this.prefix = List.copyOf(prefixes); // Defensive copy
+      }
+    }
+
+    /**
+     * Set prefix without normalization (package-private for Builder use).
+     *
+     * @param prefix the prefix to set (String or List<String>)
+     */
+    void setPrefixRaw(Object prefix) {
+      this.prefix = prefix;
+    }
+
     /**
      * Get the key separator
      *
@@ -673,7 +729,7 @@ public int hashCode() {
   public static class Builder {
     private final List<BaseField> fields = new ArrayList<>();
     private String name;
-    private String prefix;
+    private Object prefix; // Can be String or List<String>
     private StorageType storageType;
 
     /** Package-private constructor used by builder() and of() factory methods. */
@@ -691,7 +747,7 @@ public Builder name(String name) {
     }
 
     /**
-     * Set the key prefix
+     * Set the key prefix (single prefix)
      *
      * @param prefix the key prefix
      * @return this builder
@@ -701,6 +757,27 @@ public Builder prefix(String prefix) {
       return this;
     }
 
+    /**
+     * Set multiple key prefixes.
+     *
+     * <p>Normalizes single-element lists to strings for backward compatibility. Python port:
+     * matches behavior in convert_index_info_to_schema.
+     *
+     * @param prefixes the list of key prefixes
+     * @return this builder
+     */
+    public Builder prefix(List<String> prefixes) {
+      if (prefixes == null) {
+        this.prefix = null;
+      } else if (prefixes.size() == 1) {
+        // Normalize single-element lists to string for backward compatibility
+        this.prefix = prefixes.get(0);
+      } else {
+        this.prefix = List.copyOf(prefixes); // Defensive copy
+      }
+      return this;
+    }
+
     /**
      * Set the key prefix (alias for prefix)
      *
@@ -811,7 +888,25 @@ public Builder addVectorField(
      * @return the constructed IndexSchema
      */
     public IndexSchema build() {
-      return new IndexSchema(name, prefix, storageType, fields);
+      // Handle prefix (can be String or List<String>)
+      String prefixStr = null;
+      if (prefix instanceof String) {
+        prefixStr = (String) prefix;
+      } else if (prefix instanceof List) {
+        @SuppressWarnings("unchecked")
+        List<String> prefixList = (List<String>) prefix;
+        prefixStr = prefixList.isEmpty() ? null : prefixList.get(0);
+      }
+
+      IndexSchema schema = new IndexSchema(name, prefixStr, storageType, fields);
+
+      // Set the raw prefix (bypass normalization) for Lists to preserve multi-element lists
+      // Access the actual index field directly, not the defensive copy from getIndex()
+      if (prefix instanceof List) {
+        schema.index.setPrefixRaw(prefix);
+      }
+
+      return schema;
     }
 
     /**
@@ -822,7 +917,7 @@ public IndexSchema build() {
      */
     public Builder index(Index index) {
       this.name = index.getName();
-      this.prefix = index.getPrefix();
+      this.prefix = index.getPrefixRaw(); // Use raw prefix to preserve list
       this.storageType = index.getStorageType();
       return this;
     }

core/src/test/java/com/redis/vl/index/SearchIndexIntegrationTest.java

@@ -1016,4 +1016,86 @@ void testFromDictWithUrlAndValidateOnLoad() {
       }
     }
   }
+
+  /**
+   * Port of Python test_search_index_from_existing_multiple_prefixes
+   *
+   * <p>Python reference: /redis-vl-python/tests/integration/test_search_index.py:172-243
+   *
+   * <p>Test that from_existing correctly handles indices with multiple prefixes (issue #258/#392).
+   */
+  @Test
+  @DisplayName("Should handle multiple prefixes in from_existing()")
+  void testFromExistingMultiplePrefixes() {
+    String indexName = "test_multi_prefix_" + UUID.randomUUID().toString().substring(0, 8);
+
+    try {
+      // Clean up any existing index
+      try {
+        unifiedJedis.ftDropIndex(indexName);
+      } catch (Exception e) {
+        // Ignore if doesn't exist
+      }
+
+      // Create index using raw FT.CREATE command with multiple prefixes
+      // FT.CREATE index ON HASH PREFIX 3 prefix_a: prefix_b: prefix_c: SCHEMA user TAG text TEXT
+      // ...
+      unifiedJedis.ftCreate(
+          indexName,
+          redis.clients.jedis.search.FTCreateParams.createParams()
+              .on(redis.clients.jedis.search.IndexDataType.HASH)
+              .prefix("prefix_a:", "prefix_b:", "prefix_c:"),
+          redis.clients.jedis.search.schemafields.TextField.of("text"),
+          redis.clients.jedis.search.schemafields.TagField.of("user"),
+          redis.clients.jedis.search.schemafields.VectorField.builder()
+              .fieldName("embedding")
+              .algorithm(redis.clients.jedis.search.schemafields.VectorField.VectorAlgorithm.FLAT)
+              .attributes(
+                  Map.of(
+                      "TYPE", "FLOAT32",
+                      "DIM", 3,
+                      "DISTANCE_METRIC", "COSINE"))
+              .build());
+
+      // Now test from_existing - this is where the bug was
+      SearchIndex loadedIndex = SearchIndex.fromExisting(indexName, unifiedJedis);
+
+      // Verify all prefixes are preserved (this was failing before fix)
+      // Before the fix, only "prefix_a:" would be returned
+      Object prefixRaw = loadedIndex.getSchema().getIndex().getPrefixRaw();
+      assertThat(prefixRaw)
+          .as("Multiple prefixes should be preserved when loading existing index")
+          .isInstanceOf(List.class);
+
+      @SuppressWarnings("unchecked")
+      List<String> prefixList = (List<String>) prefixRaw;
+      assertThat(prefixList).containsExactly("prefix_a:", "prefix_b:", "prefix_c:");
+
+      // Verify the normalized prefix method returns the first prefix
+      assertThat(loadedIndex.getPrefix()).isEqualTo("prefix_a:");
+
+      // Verify the index name and storage type
+      assertThat(loadedIndex.getName()).isEqualTo(indexName);
+      assertThat(loadedIndex.getSchema().getIndex().getStorageType())
+          .isEqualTo(IndexSchema.StorageType.HASH);
+
+      // Verify TAG and TEXT fields are present
+      assertThat(loadedIndex.getSchema().getField("user")).isNotNull();
+      assertThat(loadedIndex.getSchema().getField("text")).isNotNull();
+
+      // Verify vector field if present
+      BaseField embeddingField = loadedIndex.getSchema().getField("embedding");
+      if (embeddingField != null) {
+        assertThat(embeddingField).isInstanceOf(VectorField.class);
+      }
+
+    } finally {
+      // Cleanup
+      try {
+        unifiedJedis.ftDropIndex(indexName);
+      } catch (Exception e) {
+        // Ignore cleanup errors
+      }
+    }
+  }
 }