Skip to content

Vector SQL Tests

View source code

These tests cover SQL vector functions for math, aggregations, distance metrics, normalization, quantization, native INT8 encoding, sparse vectors, LSM_VECTOR index creation and search, and vector conversions, plus regression tests for the Python conversion fast paths.

Overview

Tests validate:

  • Vector math functions: element-wise add, multiply, scale, and scalar broadcast
  • Vector aggregations (vectorSum, vectorAvg, vectorMin, vectorMax) across multiple rows
  • Distance functions: cosine similarity, L2 (Euclidean), dot product, Manhattan/L1
  • Vector normalization, magnitude/L2-norm aliases, clamping, and null detection
  • Score-shaping helpers: vector.scoreTransform, vector.multiScore, vector.sparsity
  • Vector quantization (INT8, BINARY) and native INT8 encoding via LSM_VECTOR
  • LSM_VECTOR / LSM_SPARSE_VECTOR index creation with rich metadata
  • vectorNeighbors / vector.neighbors / vector.sparseNeighbors top-K retrieval (by vector, by key, grouped, parameterized, and over OpenCypher)

Test Cases

Vector Math

  • test_vector_math_functions: Tests vectorAdd([1,2],[3,4]), vectorMultiply (element-wise), and vectorScale(v, scalar).
  • test_vector_add_subtract_scalar_broadcast: vectorAdd / vectorSubtract broadcast a scalar operand across the vector (and vectorAdd is commutative for scalar + vector).

Vector Aggregations

  • test_vector_aggregations: Tests vectorSum, vectorAvg, vectorMin, vectorMax element-wise across rows of an ARRAY_OF_FLOATS property.

Distance Metrics

  • test_vector_distance_functions: vectorCosineSimilarity, vectorL2Distance, and vectorDotProduct on orthogonal vectors.
  • test_vector_manhattan_distance: vectorManhattanDistance / vectorL1Distance (and the dotted vector.manhattanDistance / vector.l1Distance aliases) compute the L1 distance.

Normalization & Helpers

  • test_vector_normalization: vectorNormalize([3,4]) returns the unit vector [0.6, 0.8].
  • test_vector_l2_norm_aliases: vectorL2Norm / vector.l2Norm are aliases of vectorMagnitude.
  • test_vector_clamp: vectorClamp / vector.clamp limit each element to a [min, max] range.
  • test_vector_has_null: vectorHasNull / vector.hasNull detect NaN/null elements (e.g. sqrt(-1.0)).

Score Shaping

  • test_vector_score_transform_modes: vector.scoreTransform supports LN (== LOG) and TANH modes.
  • test_vector_multi_score_fusion: vector.multiScore fuses a list of scores; MAX returns the largest.
  • test_vector_sparsity_modes: vector.sparsity reports a default sparsity ratio plus L0 and GMEAN modes.

Quantization & Encoding

  • test_vector_quantization_functions: vectorQuantizeInt8(v) runs and returns a non-null result.
  • test_int8_quantization_boundary_condition_sql: INT8 quantized LSM_VECTOR index (Dim=16, N=10) builds and accepts a vectorNeighbors query without error; the test asserts only that the projection returns a row, not that it holds a neighbour.
  • test_create_index_with_quantization_int8_sql: Creates an INT8 quantized LSM_VECTOR index, inserts N=50 vectors, and verifies vectorNeighbors returns one neighbour (the returned vector's values are not checked).
  • test_create_index_with_quantization_binary_sql: Creates a BINARY quantized LSM_VECTOR index (Dim=128) with storeVectorsInGraph and verifies search.
  • test_create_index_with_native_int8_encoding_sql: Creates an LSM_VECTOR index on a BINARY property with "quantization": "NONE", "encoding": "INT8" and verifies the metadata.
  • test_vector_neighbors_on_native_int8_storage_sql: Verifies vectorNeighbors works against native INT8-encoded storage ingested as byte arrays.

Index Creation & Metadata

  • test_sql_create_index_builds_vector_graph_immediately_by_default: A LSM_VECTOR index created via SQL is queryable immediately with vectorNeighbors.
  • test_create_index_with_rich_metadata_sql: LSM_VECTOR creation supports dimensions, similarity, quantization, idPropertyName, storeVectorsInGraph, addHierarchy, graphBuildCacheSize, and mutationsBeforeRebuild; verifies the resulting Java metadata, and that a METADATA block still carrying the removed locationCacheSize is rejected.
  • test_vector_neighbors: vectorNeighbors(indexName, vector, k) on a basic LSM_VECTOR index.
  • test_vector_neighbors_accepts_parameterized_index_and_vector: vectorNeighbors(?, ?, ?) accepts bound index name, vector, and k parameters.
  • test_vector_neighbors_by_key_sql: vectorNeighbors('Word[vector]', 'docA', 3) searches from an existing record key.
  • test_vector_neighbors_by_key_opencypher: OpenCypher exposes CALL vector.neighbors(...) with key-based lookup.
  • test_vector_neighbors_group_by_sql: vector.neighbors supports { groupBy, groupSize } options.
  • test_sparse_vector_neighbors_sql: LSM_SPARSE_VECTOR index plus vector.sparseNeighbors top-K retrieval.
  • test_vector_delete_and_search_others_sql: Inserts 100 random vectors, deletes every 10th, and verifies nearest-match search with vectorL2Distance and ORDER BY.
  • test_document_vector_search_sql: KNN search on a DOCUMENT type using vectorL2Distance and ORDER BY ... LIMIT.

Vector Conversions (TestVectorConversionSQL)

  • test_as_string_formats: asString() emits the NUMPY, MATLAB, MATLAB_COLUMN, and JULIA layouts (the NUMPY output parses with numpy).
  • test_as_vector_round_trip: asVector() parses a space-separated string, a NUMPY string, and a single number back into a float vector.
  • test_as_sparse_round_trip: asSparse() converts dense to sparse, and vector.sparseToDense inverts it.
  • test_quantize_dequantize_binary: vector.dequantizeBinary reconstructs +1/-1 (or custom low/high values) from vector.quantizeBinary.

Conversion Fast Paths (TestConversionFastPaths)

  • test_plain_list_query_params: Plain Python lists work as query parameters among several arguments.
  • test_float_array_property_round_trip: ARRAY_OF_FLOATS properties come back as Python float lists.
  • test_find_nearest_repeated_calls_consistent: Consecutive find_nearest calls on the same index return identical results.

Pattern

# Create vector property and LSM_VECTOR index
db.command("sql", "CREATE VERTEX TYPE Movie")
db.command("sql", "CREATE PROPERTY Movie.embedding ARRAY_OF_FLOATS")
db.command(
    "sql",
    """
    CREATE INDEX ON Movie (embedding)
    LSM_VECTOR
    METADATA { "dimensions": 4, "similarity": "COSINE" }
    """,
)

# Insert vectors
with db.transaction():
    db.command("sql", "INSERT INTO Movie SET embedding = [1.0, 0.0, 0.0, 0.0]")

# Top-K search
rows = db.query(
    "sql",
    "SELECT expand(vectorNeighbors('Movie[embedding]', [1.0, 0.0, 0.0, 0.0], 2))",
).to_list()

Key Functions

  • Math: vectorAdd(), vectorSubtract(), vectorMultiply(), vectorScale()
  • Aggregation: vectorSum(), vectorAvg(), vectorMin(), vectorMax()
  • Distance: vectorCosineSimilarity(), vectorL2Distance(), vectorDotProduct(), vectorManhattanDistance() / vectorL1Distance()
  • Helpers: vectorNormalize(), vectorMagnitude() / vectorL2Norm(), vectorClamp(), vectorHasNull()
  • Score shaping: vector.scoreTransform(), vector.multiScore(), vector.sparsity()
  • Quantization/encoding: vectorQuantizeInt8(); LSM_VECTOR quantization (INT8, BINARY, NONE) and encoding (INT8) metadata
  • Schema: ARRAY_OF_FLOATS (dense), ARRAY_OF_INTEGERS + ARRAY_OF_FLOATS (sparse), BINARY (native-encoded) properties
  • Indexes: LSM_VECTOR, LSM_SPARSE_VECTOR
  • Search: vectorNeighbors(), vector.neighbors(), vector.sparseNeighbors()
  • Conversion: asString(), asVector(), asSparse(), vector.sparseToDense(), vector.quantizeBinary() / vector.dequantizeBinary()