From 223dcf51deb6c1798dcab737827ca8aa9807dc74 Mon Sep 17 00:00:00 2001
From: Rene Cannao <rene@proxysql.com>
Date: Mon, 22 Dec 2025 08:55:00 +0000
Subject: [PATCH] Add vector search testing framework with modular scripts

Create comprehensive testing guide for ProxySQL vector search capabilities:
- Separate test scripts for connectivity, table creation, data insertion, and similarity search
- Simplified README.md referencing external script files
- Modular structure for easy maintenance and extension
- Proper error handling and result tracking
- Executable scripts with consistent testing patterns

Removes previous inline documentation approach in favor of maintainable file structure.
---
 doc/vector-search-test/README.md              | 180 ++++++++++++++++++
 doc/vector-search-test/test_connectivity.sh   |  70 +++++++
 doc/vector-search-test/test_data_insertion.sh |  92 +++++++++
 .../test_similarity_search.sh                 | 102 ++++++++++
 doc/vector-search-test/test_vector_tables.sh  |  98 ++++++++++
 5 files changed, 542 insertions(+)
 create mode 100644 doc/vector-search-test/README.md
 create mode 100644 doc/vector-search-test/test_connectivity.sh
 create mode 100644 doc/vector-search-test/test_data_insertion.sh
 create mode 100644 doc/vector-search-test/test_similarity_search.sh
 create mode 100644 doc/vector-search-test/test_vector_tables.sh

diff --git a/doc/vector-search-test/README.md b/doc/vector-search-test/README.md
new file mode 100644
index 000000000..1cba309e1
--- /dev/null
+++ b/doc/vector-search-test/README.md
@@ -0,0 +1,180 @@
+# Vector Search Testing Guide
+
+This directory contains test scripts for verifying ProxySQL's vector search capabilities using the sqlite-vec extension.
+
+## Overview
+
+The testing framework is organized into four main test scripts, each covering a specific aspect of vector search functionality:
+
+1. **Connectivity Testing** - Verify basic connectivity to ProxySQL SQLite3 server
+2. **Vector Table Creation** - Test creation and verification of vector tables
+3. **Data Insertion** - Test insertion of vector data into tables
+4. **Similarity Search** - Test vector similarity search functionality
+
+## Prerequisites
+
+Before running the tests, ensure you have:
+
+1. **ProxySQL running** with SQLite3 backend enabled
+2. **mysql client** installed and accessible
+3. **Test database** configured with appropriate credentials
+4. **sqlite-vec extension** loaded in ProxySQL
+
+## Test Configuration
+
+All scripts use the following configuration (modify in each script as needed):
+
+```bash
+PROXYSQL_HOST="127.0.0.1"
+PROXYSQL_PORT="6030"
+MYSQL_USER="root"
+MYSQL_PASS="root"
+```
+
+## Running the Tests
+
+Each test script is self-contained and executable. Run them in sequence:
+
+### 1. Connectivity Test
+```bash
+./test_connectivity.sh
+```
+Tests basic connectivity to ProxySQL and database operations.
+
+### 2. Vector Table Creation Test
+```bash
+./test_vector_tables.sh
+```
+Tests creation of virtual tables using sqlite-vec extension.
+
+### 3. Data Insertion Test
+```bash
+./test_data_insertion.sh
+```
+Tests insertion of 128-dimensional vectors into vector tables.
+
+### 4. Similarity Search Test
+```bash
+./test_similarity_search.sh
+```
+Tests vector similarity search with various query patterns.
+
+## Test Descriptions
+
+### test_connectivity.sh
+- **Purpose**: Verify basic connectivity to ProxySQL SQLite3 server
+- **Tests**: Basic SELECT, database listing, current database
+- **Expected Result**: All connectivity tests pass
+
+### test_vector_tables.sh
+- **Purpose**: Test creation and verification of vector tables
+- **Tests**: CREATE VIRTUAL TABLE statements, table verification
+- **Vector Dimensions**: 128 and 256 dimensions
+- **Expected Result**: All vector tables created successfully
+
+### test_data_insertion.sh
+- **Purpose**: Test insertion of vector data
+- **Tests**: Insert unit vectors, document embeddings, verify counts
+- **Vector Dimensions**: 128 dimensions
+- **Expected Result**: All data inserted correctly
+
+### test_similarity_search.sh
+- **Purpose**: Test vector similarity search functionality
+- **Tests**: Exact match, similar vector, document similarity, result ordering
+- **Query Pattern**: `WHERE vector MATCH json(...)`
+- **Expected Result**: Correct distance calculations and result ordering
+
+## Test Results
+
+Each script provides:
+- Real-time feedback during execution
+- Success/failure status for each test
+- Detailed error messages when tests fail
+- Summary of passed/failed tests
+
+Exit codes:
+- `0`: All tests passed
+- `1`: One or more tests failed
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Connection Errors**
+   - Verify ProxySQL is running
+   - Check host/port configuration
+   - Verify credentials
+
+2. **Table Creation Errors**
+   - Ensure sqlite-vec extension is loaded
+   - Check database permissions
+   - Verify table doesn't already exist
+
+3. **Insertion Errors**
+   - Check vector format (JSON array)
+   - Verify dimension consistency
+   - Check data types
+
+4. **Search Errors**
+   - Verify JSON format in MATCH queries
+   - Check vector dimensions match table schema
+   - Ensure proper table and column names
+
+### Debug Mode
+
+For detailed debugging, modify the scripts to:
+1. Add `set -x` at the beginning for verbose output
+2. Remove `-s -N` flags from mysql commands for full result sets
+3. Add intermediate validation queries
+
+## Integration with CI/CD
+
+These scripts can be integrated into CI/CD pipelines:
+
+```bash
+#!/bin/bash
+# Example CI script
+set -e
+
+echo "Running vector search tests..."
+
+./test_connectivity.sh
+./test_vector_tables.sh
+./test_data_insertion.sh
+./test_similarity_search.sh
+
+echo "All tests completed successfully!"
+```
+
+## Customization
+
+### Adding New Tests
+
+1. Create new test script following existing pattern
+2. Use `execute_test()` function for consistent testing
+3. Include proper error handling and result validation
+4. Update README with new test description
+
+### Modifying Test Data
+
+Edit the vector arrays in:
+- `test_data_insertion.sh` for insertion tests
+- `test_similarity_search.sh` for search queries
+
+### Configuration Changes
+
+Update variables at the top of each script:
+- Connection parameters
+- Test data vectors
+- Expected patterns
+
+## Support
+
+For issues related to:
+- **ProxySQL configuration**: Check ProxySQL documentation
+- **sqlite-vec extension**: Refer to sqlite-vec documentation
+- **Test framework**: Review script source code and error messages
+
+---
+
+*This testing framework is designed to be comprehensive yet modular. Feel free to extend and modify based on your specific testing requirements.*
\ No newline at end of file
diff --git a/doc/vector-search-test/test_connectivity.sh b/doc/vector-search-test/test_connectivity.sh
new file mode 100644
index 000000000..18007fd31
--- /dev/null
+++ b/doc/vector-search-test/test_connectivity.sh
@@ -0,0 +1,70 @@
+#!/bin/bash
+
+# Vector Search Connectivity Testing Script
+# Tests basic connectivity to ProxySQL SQLite3 server
+
+set -e
+
+echo "=== Vector Search Connectivity Testing ==="
+echo "Starting at: $(date)"
+echo ""
+
+# Configuration
+PROXYSQL_HOST="127.0.0.1"
+PROXYSQL_PORT="6030"
+MYSQL_USER="root"
+MYSQL_PASS="root"
+
+# Test results tracking
+PASSED=0
+FAILED=0
+
+# Function to execute MySQL query and handle results
+execute_test() {
+    local test_name="$1"
+    local sql_query="$2"
+    local expected="$3"
+
+    echo "Testing: $test_name"
+    echo "Query: $sql_query"
+
+    # Execute query and capture results
+    result=$(mysql -h "$PROXYSQL_HOST" -P "$PROXYSQL_PORT" -u "$MYSQL_USER" -p"$MYSQL_PASS" -s -N -e "$sql_query" 2>&1)
+    local exit_code=$?
+
+    if [ $exit_code -eq 0 ]; then
+        echo "✅ SUCCESS: $test_name"
+        echo "Result: $result"
+        ((PASSED++))
+    else
+        echo "❌ FAILED: $test_name"
+        echo "Error: $result"
+        ((FAILED++))
+    fi
+
+    echo "----------------------------------------"
+    echo ""
+}
+
+# Test 1: Basic connectivity
+execute_test "Basic Connectivity" "SELECT 1 as test;" "1"
+
+# Test 2: Database listing
+execute_test "Database Listing" "SHOW DATABASES;" "main"
+
+# Test 3: Current database
+execute_test "Current Database" "SELECT database();" "main"
+
+# Summary
+echo "=== Test Summary ==="
+echo "Total tests: $((PASSED + FAILED))"
+echo "Passed: $PASSED"
+echo "Failed: $FAILED"
+
+if [ $FAILED -eq 0 ]; then
+    echo "🎉 All connectivity tests passed!"
+    exit 0
+else
+    echo "❌ $FAILED tests failed!"
+    exit 1
+fi
\ No newline at end of file
diff --git a/doc/vector-search-test/test_data_insertion.sh b/doc/vector-search-test/test_data_insertion.sh
new file mode 100644
index 000000000..16ea304fc
--- /dev/null
+++ b/doc/vector-search-test/test_data_insertion.sh
@@ -0,0 +1,92 @@
+#!/bin/bash
+
+# Vector Data Insertion Testing Script
+# Tests insertion of vector data into tables
+
+set -e
+
+echo "=== Vector Data Insertion Testing ==="
+echo "Starting at: $(date)"
+echo ""
+
+# Configuration
+PROXYSQL_HOST="127.0.0.1"
+PROXYSQL_PORT="6030"
+MYSQL_USER="root"
+MYSQL_PASS="root"
+
+# Test results tracking
+PASSED=0
+FAILED=0
+
+# Function to execute MySQL query and handle results
+execute_test() {
+    local test_name="$1"
+    local sql_query="$2"
+    expected_pattern="$3"
+
+    echo "Testing: $test_name"
+    echo "Query: $sql_query"
+
+    # Execute the query
+    result=$(mysql -h "$PROXYSQL_HOST" -P "$PROXYSQL_PORT" -u "$MYSQL_USER" -p"$MYSQL_PASS" -s -N -e "$sql_query" 2>&1)
+    local exit_code=$?
+
+    if [ $exit_code -eq 0 ]; then
+        # Check if result matches expected pattern
+        if [ -n "$expected_pattern" ] && ! echo "$result" | grep -q "$expected_pattern"; then
+            echo "❌ FAILED: $test_name - Pattern not matched"
+            echo "EXPECTED: $expected_pattern"
+            echo "RESULT: $result"
+            ((FAILED++))
+        else
+            echo "✅ SUCCESS: $test_name"
+            echo "Result: $result"
+            ((PASSED++))
+        fi
+    else
+        echo "❌ FAILED: $test_name - Query execution error"
+        echo "ERROR: $result"
+        ((FAILED++))
+    fi
+
+    echo "----------------------------------------"
+    echo ""
+}
+
+# Test 1: Insert unit vectors into embeddings
+execute_test "Insert unit vectors" "
+INSERT INTO embeddings(rowid, vector) VALUES
+  (1, '[1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]'),
+  (2, '[0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]'),
+  (3, '[0.9, 0.1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]');
+" ""
+
+# Test 2: Insert document embeddings
+execute_test "Insert document embeddings" "
+INSERT INTO documents(rowid, embedding) VALUES
+  (1, '[0.2, 0.8, 0.1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]'),
+  (2, '[0.1, 0.1, 0.7, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]'),
+  (3, '[0.6, 0.2, 0.1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]');
+" ""
+
+# Test 3: Verify data insertion
+execute_test "Verify data insertion" "
+SELECT COUNT(*) as total_vectors
+FROM embeddings
+WHERE rowid IN (1, 2, 3);
+" "3"
+
+# Summary
+echo "=== Test Summary ==="
+echo "Total tests: $((PASSED + FAILED))"
+echo "Passed: $PASSED"
+echo "Failed: $FAILED"
+
+if [ $FAILED -eq 0 ]; then
+    echo "🎉 All data insertion tests passed!"
+    exit 0
+else
+    echo "❌ $FAILED tests failed!"
+    exit 1
+fi
\ No newline at end of file
diff --git a/doc/vector-search-test/test_similarity_search.sh b/doc/vector-search-test/test_similarity_search.sh
new file mode 100644
index 000000000..24b528910
--- /dev/null
+++ b/doc/vector-search-test/test_similarity_search.sh
@@ -0,0 +1,102 @@
+#!/bin/bash
+
+# Vector Similarity Search Testing Script
+# Tests vector search capabilities
+
+set -e
+
+echo "=== Vector Similarity Search Testing ==="
+echo "Starting at: $(date)"
+echo ""
+
+# Configuration
+PROXYSQL_HOST="127.0.0.1"
+PROXYSQL_PORT="6030"
+MYSQL_USER="root"
+MYSQL_PASS="root"
+
+# Test results tracking
+PASSED=0
+FAILED=0
+
+# Function to execute MySQL query and handle results
+execute_test() {
+    local test_name="$1"
+    local sql_query="$2"
+    expected_pattern="$3"
+
+    echo "Testing: $test_name"
+    echo "Query: $sql_query"
+
+    # Execute the query
+    result=$(mysql -h "$PROXYSQL_HOST" -P "$PROXYSQL_PORT" -u "$MYSQL_USER" -p"$MYSQL_PASS" -s -N -e "$sql_query" 2>&1)
+    local exit_code=$?
+
+    if [ $exit_code -eq 0 ]; then
+        # Check if result matches expected pattern
+        if [ -n "$expected_pattern" ] && ! echo "$result" | grep -q "$expected_pattern"; then
+            echo "❌ FAILED: $test_name - Pattern not matched"
+            echo "EXPECTED: $expected_pattern"
+            echo "RESULT: $result"
+            ((FAILED++))
+        else
+            echo "✅ SUCCESS: $test_name"
+            echo "Result:"
+            echo "$result"
+            ((PASSED++))
+        fi
+    else
+        echo "❌ FAILED: $test_name - Query execution error"
+        echo "ERROR: $result"
+        ((FAILED++))
+    fi
+
+    echo "----------------------------------------"
+    echo ""
+}
+
+# Test 1: Exact match search
+execute_test "Exact match search" "
+SELECT rowid, distance
+FROM embeddings
+WHERE vector MATCH json('[1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]')
+ORDER BY distance ASC;
+" "1.*0.0"
+
+# Test 2: Similar vector search
+execute_test "Similar vector search" "
+SELECT rowid, distance
+FROM embeddings
+WHERE vector MATCH json('[0.9, 0.1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]')
+ORDER BY distance ASC;
+" "3.*0.1"
+
+# Test 3: Document similarity search
+execute_test "Document similarity search" "
+SELECT rowid, distance
+FROM documents
+WHERE embedding MATCH json('[0.5, 0.5, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]')
+ORDER BY distance ASC LIMIT 3;
+" ""
+
+# Test 4: Search with result ordering
+execute_test "Search with result ordering" "
+SELECT rowid, distance
+FROM embeddings
+WHERE vector MATCH json('[0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]')
+ORDER BY distance ASC;
+" "2.*0.0"
+
+# Summary
+echo "=== Test Summary ==="
+echo "Total tests: $((PASSED + FAILED))"
+echo "Passed: $PASSED"
+echo "Failed: $FAILED"
+
+if [ $FAILED -eq 0 ]; then
+    echo "🎉 All similarity search tests passed!"
+    exit 0
+else
+    echo "❌ $FAILED tests failed!"
+    exit 1
+fi
\ No newline at end of file
diff --git a/doc/vector-search-test/test_vector_tables.sh b/doc/vector-search-test/test_vector_tables.sh
new file mode 100644
index 000000000..2cfdf7bf0
--- /dev/null
+++ b/doc/vector-search-test/test_vector_tables.sh
@@ -0,0 +1,98 @@
+#!/bin/bash
+
+# Vector Table Creation Testing Script
+# Tests creation and verification of vector tables
+
+set -e
+
+echo "=== Vector Table Creation Testing ==="
+echo "Starting at: $(date)"
+echo ""
+
+# Configuration
+PROXYSQL_HOST="127.0.0.1"
+PROXYSQL_PORT="6030"
+MYSQL_USER="root"
+MYSQL_PASS="root"
+
+# Test results tracking
+PASSED=0
+FAILED=0
+
+# Function to execute MySQL query and handle results
+execute_test() {
+    local test_name="$1"
+    local sql_query="$2"
+    expected_pattern="$3"
+
+    echo "Testing: $test_name"
+    echo "Query: $sql_query"
+
+    # Execute the query
+    result=$(mysql -h "$PROXYSQL_HOST" -P "$PROXYSQL_PORT" -u "$MYSQL_USER" -p"$MYSQL_PASS" -s -N -e "$sql_query" 2>&1)
+    local exit_code=$?
+
+    if [ $exit_code -eq 0 ]; then
+        # Check if result matches expected pattern
+        if [ -n "$expected_pattern" ] && ! echo "$result" | grep -q "$expected_pattern"; then
+            echo "❌ FAILED: $test_name - Pattern not matched"
+            echo "EXPECTED: $expected_pattern"
+            echo "RESULT: $result"
+            ((FAILED++))
+        else
+            echo "✅ SUCCESS: $test_name"
+            echo "Result: $result"
+            ((PASSED++))
+        fi
+    else
+        echo "❌ FAILED: $test_name - Query execution error"
+        echo "ERROR: $result"
+        ((FAILED++))
+    fi
+
+    echo "----------------------------------------"
+    echo ""
+}
+
+# Test 1: Create embeddings table
+execute_test "Create embeddings table" "
+CREATE VIRTUAL TABLE IF NOT EXISTS embeddings USING vec0(
+    vector float[128]
+);
+" ""
+
+# Test 2: Create documents table
+execute_test "Create documents table" "
+CREATE VIRTUAL TABLE IF NOT EXISTS documents USING vec0(
+    embedding float[128]
+);
+" ""
+
+# Test 3: Create test_vectors table
+execute_test "Create test_vectors table" "
+CREATE VIRTUAL TABLE IF NOT EXISTS test_vectors USING vec0(
+    features float[256]
+);
+" ""
+
+# Test 4: Verify table creation
+execute_test "Verify vector tables" "
+SELECT name
+FROM sqlite_master
+WHERE type='table' AND (name LIKE '%embedding%' OR name LIKE '%document%' OR name LIKE '%vector%')
+ORDER BY name;
+" "embeddings"
+
+# Summary
+echo "=== Test Summary ==="
+echo "Total tests: $((PASSED + FAILED))"
+echo "Passed: $PASSED"
+echo "Failed: $FAILED"
+
+if [ $FAILED -eq 0 ]; then
+    echo "🎉 All vector table tests passed!"
+    exit 0
+else
+    echo "❌ $FAILED tests failed!"
+    exit 1
+fi
\ No newline at end of file