Skip to content

Vector SQL Tests

View source code

There are 12 tests covering SQL vector functions for math, aggregations, distance metrics, normalization, and quantization.

Overview

Tests validate:

  • Vector math functions: addition, multiplication, scalar scaling
  • Vector aggregations (SUM, AVG, MIN, MAX) across multiple rows
  • Distance functions: cosine similarity, L2 (Euclidean), dot product
  • Vector normalization to unit length
  • Vector quantization (INT8) with proper scaling/unscaling
  • Handling edge cases: boundary conditions, nested vectors, metadata
  • Vector indexes and column type definitions in schema
  • SQL query support for vector operations

Test Cases

Vector Math

  • vector_math_functions: Tests SQL functions vector_add(v1, v2), vector_multiply_scalar(v, scalar), vector_scale() on float arrays; verifies expected results

Vector Aggregations

  • vector_aggregations: Tests SQL aggregate functions SUM(vectors), AVG(vectors), MIN(vectors), MAX(vectors) on vector columns across multiple rows; validates proper element-wise aggregation

Distance Metrics

  • vector_distance_functions: Tests distance functions:
    • vector_distance_cosine(v1, v2): cosine similarity (0 to 1)
    • vector_distance_l2(v1, v2): Euclidean distance
    • vector_distance_dot(v1, v2): dot product
    • Validates values for orthogonal, parallel, and arbitrary vectors

Normalization

  • vector_normalization: Tests vector_normalize(v) to unit length (magnitude 1); validates magnitude of result

Quantization

  • vector_quantization_functions: If enabled in your ArcadeDB build, tests vector_quantize_int8(v) and vector_unquantize_int8(v_quantized, scale) for compression

  • int8_quantization_boundary_condition_sql: If quantization helpers are available, tests INT8 quantization at min/max boundaries (-128, 127) and zero edge cases

  • quantization_with_scale_factors_sql: If quantization helpers are available, tests quantization with explicit scale factors

Advanced

  • nested_vector_objects_sql: Tests queries on nested/nested vector data structures; validates accessor syntax and iteration

  • vector_metadata_parsing: Tests SQL queries with vector metadata (dimension, type, quantization_type); validates extraction and type correctness

  • vector_indexes_sql: Creates vector indexes on columns and validates query execution; tests index creation syntax and HNSW/IVF options if available

  • vector_column_types_in_schema: Tests schema definition for vector-capable properties and validates insert/update behavior

Pattern

# Create vector columns
db.command("sql", "CREATE VERTEX TYPE VectorData")
db.command("sql", "CREATE PROPERTY VectorData.embedding ARRAY_OF_FLOATS")
db.command("sql", "CREATE PROPERTY VectorData.name STRING")

# Insert vectors
with db.transaction():
    db.command("sql", """
        INSERT INTO VectorData SET
            embedding = [1.0, 2.0, 3.0],
            name = 'sample'
    """)

# Query with vector functions
results = db.query("sql", """
    SELECT
        vector_normalize(embedding) as normalized,
        vector_distance_cosine(embedding, [1, 0, 0]) as distance
    FROM VectorData
""")

# Optional quantization check (only if helper functions are available in your build)
# compressed = db.query("sql", "SELECT vector_quantize_int8([1.5, 2.5, 3.5]) as q")

Key Functions

  • Math: vector_add(), vector_multiply_scalar(), vector_scale()
  • Aggregation: SUM(), AVG(), MIN(), MAX()
  • Distance: vector_distance_cosine(), vector_distance_l2(), vector_distance_dot()
  • Normalization: vector_normalize()
  • Quantization: vector_quantize_int8(), vector_unquantize_int8() (if available in your build)
  • Schema: ARRAY_OF_FLOATS properties for vector-capable columns
  • Indexes: Vector indexes (HNSW, IVF)