feat: support wider hamming hashes (#7767)

## Summary
- Support `FixedSizeList<UInt8, N>` hamming hashes where `N` is a
positive multiple of 8 bytes.
- Reuse the SIMD `u64` pairwise path lane-by-lane for wider hashes.
- Add Rust and Python coverage for 16-byte and wider hash clustering,
including invalid-width rejection.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Expanded Hamming-distance clustering to support binary hashes of any
positive, 8-byte-aligned width (`FixedSizeList<UInt8, N>`), including
16-byte hashes.
* Added sequential and parallel pairwise Hamming-distance APIs for
multi-lane binary hashes, with support for extracting fixed-list hash
values.
* **Bug Fixes**
* Improved validation and error handling for malformed or inconsistent
fixed-list hash inputs and byte widths.
* **Tests**
* Broadened and parameterized clustering and distance test coverage for
8- and 16-byte hashes, multi-segment behavior, and
sequential-vs-parallel consistency.
* **Documentation**
* Updated API docs and parameter descriptions to reflect the generalized
hash column shape.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: jackye1995

python/python/lance/vector.py

@@ -856,7 +856,8 @@ def hamming_clustering_for_sample(
     dataset : LanceDataset
         The Lance dataset containing the hash column.
     column : str
-        Name of the hash column (must be FixedSizeList<UInt8, 8>)
+        Name of the hash column (must be FixedSizeList<UInt8, N> where N is a
+        positive multiple of 8 bytes)
     sample_size : int, optional
         Number of rows to sample. If None, uses all rows.
     hamming_threshold : int, default 10
@@ -898,7 +899,8 @@ def hamming_clustering_for_range(
     dataset : LanceDataset
         The Lance dataset containing the hash column.
     column : str
-        Name of the hash column (must be FixedSizeList<UInt8, 8>)
+        Name of the hash column (must be FixedSizeList<UInt8, N> where N is a
+        positive multiple of 8 bytes)
     fragment_id : int
         The fragment ID to read from
     start_row : int

python/python/tests/test_vector.py

@@ -155,21 +155,26 @@ def test_binary_vectors_invalid_metric(tmp_path):
 
 
 def _hash_table(hashes):
-    """Build a table with a ``hash`` column of FixedSizeList<UInt8, 8>.
+    """Build a table with a ``hash`` column of FixedSizeList<UInt8, N>.
 
-    ``hashes`` is a list of 8-byte sequences, one per row.
+    ``hashes`` is a list of byte sequences, one per row. The byte width must
+    be a positive multiple of 8.
     """
+    byte_width = len(hashes[0])
+    assert byte_width > 0 and byte_width % 8 == 0
+    assert all(len(row) == byte_width for row in hashes)
     flat = [byte for row in hashes for byte in row]
     values = pa.FixedSizeListArray.from_arrays(
-        pa.array(flat, type=pa.uint8()), list_size=8
+        pa.array(flat, type=pa.uint8()), list_size=byte_width
     )
     return pa.Table.from_arrays([values], names=["hash"])
 
 
-def test_hamming_clustering_for_sample(tmp_path):
-    hash_a = [0, 0, 0, 0, 0, 0, 0, 0]
-    hash_b = [255, 0, 0, 0, 0, 0, 0, 0]  # 8 bits from hash_a
-    hash_c = [1, 2, 3, 4, 5, 6, 7, 8]  # far from both
+@pytest.mark.parametrize("byte_width", [8, 16])
+def test_hamming_clustering_for_sample(tmp_path, byte_width):
+    hash_a = [0] * byte_width
+    hash_b = [0] * (byte_width - 8) + [255] + [0] * 7  # 8 bits from hash_a
+    hash_c = list(range(1, byte_width + 1))  # far from both
     # Rows 0,1,2 share hash_a; rows 3,4 share hash_b; row 5 is unique.
     table = _hash_table([hash_a, hash_a, hash_a, hash_b, hash_b, hash_c])
     dataset = lance.write_dataset(table, tmp_path / "hashes")
@@ -189,11 +194,28 @@ def test_hamming_clustering_for_sample(tmp_path):
     assert clusters == {0: [1, 2], 3: [4]}
 
 
-def test_hamming_clustering_multi_segment(tmp_path):
+@pytest.mark.parametrize("byte_width", [8, 16])
+def test_hamming_clustering_multi_segment(tmp_path, byte_width):
+    mask = (1 << 64) - 1
+
+    def hash_bytes(value):
+        if byte_width == 8:
+            lanes = [(value * 0x9E3779B97F4A7C15) & mask]
+        else:
+            # Adjacent logical values share the first 64-bit lane and differ in
+            # later lanes, so threshold-0 clustering must compare every lane.
+            lanes = [
+                ((value // 2) * 0x9E3779B97F4A7C15) & mask,
+                ((value * 0xD6E8FEB86659FD93) ^ 0xA5A5A5A5A5A5A5A5) & mask,
+            ]
+        return [
+            byte for lane_value in lanes for byte in lane_value.to_bytes(8, "little")
+        ]
+
     # 25 distinct hash values, two copies each; the same table is written to
     # fragment 0 and appended as fragment 1.
-    values = [((i // 2) * 0x9E3779B97F4A7C15) & 0xFFFFFFFFFFFFFFFF for i in range(50)]
-    table = _hash_table([list(value.to_bytes(8, "little")) for value in values])
+    values = [i // 2 for i in range(50)]
+    table = _hash_table([hash_bytes(value) for value in values])
     dataset = lance.write_dataset(table, tmp_path / "hashes")
     dataset.create_index(
         "hash", index_type="IVF_FLAT", num_partitions=4, metric="hamming"

python/src/dataset.rs

@@ -3768,7 +3768,8 @@ impl Dataset {
     /// Parameters
     /// ----------
     /// column : str
-    ///     Name of the hash column (must be FixedSizeList<UInt8, 8>)
+    ///     Name of the hash column (must be FixedSizeList<UInt8, N> where N is
+    ///     a positive multiple of 8 bytes)
     /// sample_size : int, optional
     ///     Number of rows to sample (if None or >= total rows, uses all rows)
     /// hamming_threshold : int
@@ -3811,7 +3812,8 @@ impl Dataset {
     /// Parameters
     /// ----------
     /// column : str
-    ///     Name of the hash column (must be FixedSizeList<UInt8, 8>)
+    ///     Name of the hash column (must be FixedSizeList<UInt8, N> where N is
+    ///     a positive multiple of 8 bytes)
     /// fragment_id : int
     ///     The fragment ID to read from
     /// start_row : int

rust/lance-linalg/src/distance.rs

@@ -28,9 +28,11 @@ pub mod norm_l2;
 pub use cosine::*;
 pub use dot::*;
 pub use hamming::{
-    Cluster, ClusteringResult, PairwiseResult, UnionFind, cluster_edges, cluster_pairwise_result,
-    extract_hashes_from_fixed_list, hamming_distance_arrow_batch, hamming_u64,
-    pairwise_hamming_distance, pairwise_hamming_distance_parallel,
+    BinaryHashValues, Cluster, ClusteringResult, PairwiseResult, UnionFind, cluster_edges,
+    cluster_pairwise_result, extract_binary_hashes_from_fixed_list, extract_hashes_from_fixed_list,
+    hamming_distance_arrow_batch, hamming_u64, pairwise_hamming_distance,
+    pairwise_hamming_distance_binary, pairwise_hamming_distance_binary_parallel,
+    pairwise_hamming_distance_parallel,
 };
 pub use l2::*;
 use lance_core::deepsize::DeepSizeOf;