fix

Author: jerry-024

.gitignore

@@ -37,3 +37,5 @@ paimon-faiss/paimon-faiss-jni/build/
 paimon-faiss/paimon-faiss-jni/src/main/resources/darwin*
 paimon-faiss/paimon-faiss-jni/src/main/resources/linux*
 paimon-faiss/paimon-faiss-jni/src/main/native/cmake-build-debug/
+paimon-diskann/paimon-diskann-jni/src/main/resources/darwin*
+paimon-diskann/paimon-diskann-jni/src/main/resources/linux*

paimon-diskann/PARAMETER_TUNING.md

@@ -92,16 +92,9 @@ DiskANN is a graph-based approximate nearest neighbor (ANN) search algorithm des
 - **Description**: Distance metric for similarity computation
 - **Recommendations**:
   - **L2**: For Euclidean distance (most common)
-  - **INNER_PRODUCT**: For dot product similarity (use with normalized vectors)
+  - **INNER_PRODUCT**: For dot product similarity
   - **COSINE**: For cosine similarity
 
-#### `vector.normalize`
-- **Default**: false
-- **Description**: Whether to L2-normalize vectors before indexing/searching
-- **Recommendations**:
-  - **true**: When using COSINE metric or when vectors have varying magnitudes
-  - **false**: When vectors are already normalized or using L2 metric
-
 ### 4. Index Organization
 
 #### `vector.size-per-index`

paimon-diskann/paimon-diskann-index/src/main/java/org/apache/paimon/diskann/index/DiskAnnIndex.java

@@ -35,24 +35,12 @@ public class DiskAnnIndex implements Closeable {
 
     private final Index index;
     private final int dimension;
-    private final DiskAnnVectorMetric metric;
-    private final DiskAnnIndexType indexType;
-    private final int maxDegree;
     private final int buildListSize;
     private volatile boolean closed = false;
 
-    private DiskAnnIndex(
-            Index index,
-            int dimension,
-            DiskAnnVectorMetric metric,
-            DiskAnnIndexType indexType,
-            int maxDegree,
-            int buildListSize) {
+    private DiskAnnIndex(Index index, int dimension, int buildListSize) {
         this.index = index;
         this.dimension = dimension;
-        this.metric = metric;
-        this.indexType = indexType;
-        this.maxDegree = maxDegree;
         this.buildListSize = buildListSize;
     }
 
@@ -65,7 +53,7 @@ public static DiskAnnIndex create(
         MetricType metricType = metric.toMetricType();
         Index index =
                 Index.create(dimension, metricType, indexType.value(), maxDegree, buildListSize);
-        return new DiskAnnIndex(index, dimension, metric, indexType, maxDegree, buildListSize);
+        return new DiskAnnIndex(index, dimension, buildListSize);
     }
 
     public void addWithIds(ByteBuffer vectorBuffer, ByteBuffer idBuffer, int n) {
@@ -85,62 +73,22 @@ public void build() {
         index.build(buildListSize);
     }
 
-    public void search(
-            float[] queryVectors,
-            int n,
-            int k,
-            int searchListSize,
-            float[] distances,
-            long[] labels) {
-        ensureOpen();
-        if (queryVectors.length < n * dimension) {
-            throw new IllegalArgumentException(
-                    "Query vectors array too small: required "
-                            + (n * dimension)
-                            + ", got "
-                            + queryVectors.length);
-        }
-        if (distances.length < n * k) {
-            throw new IllegalArgumentException(
-                    "Distances array too small: required " + (n * k) + ", got " + distances.length);
-        }
-        if (labels.length < n * k) {
-            throw new IllegalArgumentException(
-                    "Labels array too small: required " + (n * k) + ", got " + labels.length);
-        }
-        index.search(n, queryVectors, k, searchListSize, distances, labels);
-    }
-
-    public long size() {
-        ensureOpen();
-        return index.getCount();
-    }
-
-    public int dimension() {
-        return dimension;
-    }
-
-    public DiskAnnVectorMetric metric() {
-        return metric;
-    }
-
-    public DiskAnnIndexType indexType() {
-        return indexType;
-    }
-
-    public int maxDegree() {
-        return maxDegree;
-    }
-
-    public int buildListSize() {
-        return buildListSize;
-    }
-
+    /** Return the number of bytes needed for serialization. */
     public long serializeSize() {
         ensureOpen();
         return index.serializeSize();
     }
 
+    /**
+     * Serialize this index with its Vamana graph adjacency lists into the given direct ByteBuffer.
+     *
+     * <p>The serialized data is later split into an index file (header + graph) and a data file
+     * (raw vectors) by the writer, then loaded by {@link DiskAnnVectorGlobalIndexReader} for
+     * search.
+     *
+     * @param buffer a direct ByteBuffer of at least {@link #serializeSize()} bytes
+     * @return the number of bytes written
+     */
     public long serialize(ByteBuffer buffer) {
         ensureOpen();
         if (!buffer.isDirect()) {
@@ -149,27 +97,6 @@ public long serialize(ByteBuffer buffer) {
         return index.serialize(buffer);
     }
 
-    public static DiskAnnIndex deserialize(byte[] data, DiskAnnVectorMetric metric) {
-        Index index = Index.deserialize(data);
-        return new DiskAnnIndex(
-                index, index.getDimension(), metric, DiskAnnIndexType.UNKNOWN, 64, 100);
-    }
-
-    /**
-     * Reset the index (remove all vectors).
-     *
-     * <p>Note: This is not supported in the current implementation. DiskANN indices are immutable
-     * once built. To "reset", you must create a new index.
-     *
-     * @throws UnsupportedOperationException always, as reset is not currently supported
-     */
-    public void reset() {
-        throw new UnsupportedOperationException(
-                "Reset is not supported for DiskANN indices. "
-                        + "DiskANN indices are immutable once built. "
-                        + "Please create a new index instead.");
-    }
-
     public static ByteBuffer allocateVectorBuffer(int numVectors, int dimension) {
         return ByteBuffer.allocateDirect(numVectors * dimension * Float.BYTES)
                 .order(ByteOrder.nativeOrder());

paimon-diskann/paimon-diskann-index/src/main/java/org/apache/paimon/diskann/index/DiskAnnIndexMeta.java

@@ -25,7 +25,17 @@
 import java.io.IOException;
 import java.io.Serializable;
 
-/** Metadata for DiskANN vector index. */
+/**
+ * Metadata for DiskANN vector index.
+ *
+ * <p>Stores the file names of the companion files that live alongside the index file:
+ *
+ * <ul>
+ *   <li>{@link #dataFileName()} — raw vector data file
+ *   <li>{@link #pqPivotsFileName()} — PQ codebook (pivots)
+ *   <li>{@link #pqCompressedFileName()} — PQ compressed codes
+ * </ul>
+ */
 public class DiskAnnIndexMeta implements Serializable {
 
     private static final long serialVersionUID = 1L;
@@ -38,31 +48,29 @@ public class DiskAnnIndexMeta implements Serializable {
     private final long numVectors;
     private final long minId;
     private final long maxId;
+    private final String dataFileName;
+    private final String pqPivotsFileName;
+    private final String pqCompressedFileName;
 
     public DiskAnnIndexMeta(
-            int dim, int metricValue, int indexTypeValue, long numVectors, long minId, long maxId) {
+            int dim,
+            int metricValue,
+            int indexTypeValue,
+            long numVectors,
+            long minId,
+            long maxId,
+            String dataFileName,
+            String pqPivotsFileName,
+            String pqCompressedFileName) {
         this.dim = dim;
         this.metricValue = metricValue;
         this.indexTypeValue = indexTypeValue;
         this.numVectors = numVectors;
         this.minId = minId;
         this.maxId = maxId;
-    }
-
-    public int dim() {
-        return dim;
-    }
-
-    public int metricValue() {
-        return metricValue;
-    }
-
-    public int indexTypeValue() {
-        return indexTypeValue;
-    }
-
-    public long numVectors() {
-        return numVectors;
+        this.dataFileName = dataFileName;
+        this.pqPivotsFileName = pqPivotsFileName;
+        this.pqCompressedFileName = pqCompressedFileName;
     }
 
     public long minId() {
@@ -73,6 +81,11 @@ public long maxId() {
         return maxId;
     }
 
+    /** The file name of the separate vector data file. */
+    public String dataFileName() {
+        return dataFileName;
+    }
+
     /** Serialize metadata to byte array. */
     public byte[] serialize() throws IOException {
         ByteArrayOutputStream baos = new ByteArrayOutputStream();
@@ -84,6 +97,9 @@ public byte[] serialize() throws IOException {
         out.writeLong(numVectors);
         out.writeLong(minId);
         out.writeLong(maxId);
+        out.writeUTF(dataFileName);
+        out.writeUTF(pqPivotsFileName);
+        out.writeUTF(pqCompressedFileName);
         out.flush();
         return baos.toByteArray();
     }
@@ -101,6 +117,18 @@ public static DiskAnnIndexMeta deserialize(byte[] data) throws IOException {
         long numVectors = in.readLong();
         long minId = in.readLong();
         long maxId = in.readLong();
-        return new DiskAnnIndexMeta(dim, metricValue, indexTypeValue, numVectors, minId, maxId);
+        String dataFileName = in.readUTF();
+        String pqPivotsFileName = in.readUTF();
+        String pqCompressedFileName = in.readUTF();
+        return new DiskAnnIndexMeta(
+                dim,
+                metricValue,
+                indexTypeValue,
+                numVectors,
+                minId,
+                maxId,
+                dataFileName,
+                pqPivotsFileName,
+                pqCompressedFileName);
     }
 }

paimon-diskann/paimon-diskann-index/src/main/java/org/apache/paimon/diskann/index/DiskAnnIndexType.java

@@ -20,9 +20,7 @@
 
 /** DiskANN index type. */
 public enum DiskAnnIndexType {
-    MEMORY(0),
-    DISK(1),
-    UNKNOWN(-1);
+    MEMORY(0);
 
     private final int value;