Add vector attribute support for PostgreSQL with pgvector extension

src/Database/Adapter.php

@@ -1001,6 +1001,13 @@ abstract public function getSupportForGetConnectionId(): bool;
      */
     abstract public function getSupportForUpserts(): bool;
 
+    /**
+     * Is vector type supported?
+     *
+     * @return bool
+     */
+    abstract public function getSupportForVectors(): bool;
+
     /**
      * Is Cache Fallback supported?
      *

src/Database/Adapter/Pool.php

@@ -405,6 +405,11 @@ public function getSupportForUpserts(): bool
         return $this->delegate(__FUNCTION__, \func_get_args());
     }
 
+    public function getSupportForVectors(): bool
+    {
+        return $this->delegate(__FUNCTION__, \func_get_args());
+    }
+
     public function getSupportForCacheSkipOnFailure(): bool
     {
         return $this->delegate(__FUNCTION__, \func_get_args());

src/Database/Adapter/Postgres.php

@@ -439,6 +439,11 @@ public function analyzeCollection(string $collection): bool
      */
     public function createAttribute(string $collection, string $id, string $type, int $size, bool $signed = true, bool $array = false): bool
     {
+        // Ensure pgvector extension is installed for vector types
+        if ($type === Database::VAR_VECTOR) {
+            $this->ensurePgVectorExtension();
+        }
+
         $name = $this->filter($collection);
         $id = $this->filter($id);
         $type = $this->getSQLType($type, $size, $signed, $array);
@@ -1798,6 +1803,18 @@ protected function getSQLCondition(Query $query, array &$binds): string
                 $binds[":{$placeholder}_0"] = $this->getFulltextValue($query->getValue());
                 return "NOT (to_tsvector(regexp_replace({$attribute}, '[^\w]+',' ','g')) @@ websearch_to_tsquery(:{$placeholder}_0))";
 
+            case Query::TYPE_VECTOR_DOT:
+                $binds[":{$placeholder}_0"] = '[' . implode(',', $query->getValues()) . ']';
+                return "({$attribute} <#> :{$placeholder}_0)";
+
+            case Query::TYPE_VECTOR_COSINE:
+                $binds[":{$placeholder}_0"] = '[' . implode(',', $query->getValues()) . ']';
+                return "({$attribute} <=> :{$placeholder}_0)";
+
+            case Query::TYPE_VECTOR_EUCLIDEAN:
+                $binds[":{$placeholder}_0"] = '[' . implode(',', $query->getValues()) . ']';
+                return "({$attribute} <-> :{$placeholder}_0)";
+
             case Query::TYPE_BETWEEN:
                 $binds[":{$placeholder}_0"] = $query->getValues()[0];
                 $binds[":{$placeholder}_1"] = $query->getValues()[1];
@@ -1924,6 +1941,9 @@ protected function getSQLType(string $type, int $size, bool $signed = true, bool
             case Database::VAR_DATETIME:
                 return 'TIMESTAMP(3)';
 
+            case Database::VAR_VECTOR:
+                return "vector({$size})";
+
             default:
                 throw new DatabaseException('Unknown Type: ' . $type);
         }
@@ -1943,6 +1963,22 @@ protected function getSQLSchema(): string
         return "\"{$this->getDatabase()}\".";
     }
 
+    /**
+     * Ensure pgvector extension is installed
+     *
+     * @return void
+     * @throws DatabaseException
+     */
+    private function ensurePgVectorExtension(): void
+    {
+        try {
+            $stmt = $this->getPDO()->prepare("CREATE EXTENSION IF NOT EXISTS vector");
+            $this->execute($stmt);
+        } catch (PDOException $e) {
+            throw new DatabaseException('Failed to install pgvector extension: ' . $e->getMessage(), $e->getCode(), $e);
+        }
+    }
+
     /**
      * Get PDO Type
      *
@@ -2049,6 +2085,16 @@ public function getSupportForUpserts(): bool
         return true;
     }
 
+    /**
+     * Is vector type supported?
+     *
+     * @return bool
+     */
+    public function getSupportForVectors(): bool
+    {
+        return true;
+    }
+
     /**
      * @return string
      */

src/Database/Adapter/SQL.php

@@ -1426,6 +1426,16 @@ public function getSupportForBatchCreateAttributes(): bool
         return true;
     }
 
+    /**
+     * Is vector type supported?
+     *
+     * @return bool
+     */
+    public function getSupportForVectors(): bool
+    {
+        return false;
+    }
+
     /**
      * @param string $tableName
      * @param string $columns
@@ -1505,6 +1515,10 @@ protected function getSQLOperator(string $method): string
             case Query::TYPE_NOT_ENDS_WITH:
             case Query::TYPE_NOT_CONTAINS:
                 return $this->getLikeOperator();
+            case Query::TYPE_VECTOR_DOT:
+            case Query::TYPE_VECTOR_COSINE:
+            case Query::TYPE_VECTOR_EUCLIDEAN:
+                throw new DatabaseException('Vector queries are only supported in PostgreSQL adapter');
             default:
                 throw new DatabaseException('Unknown method: ' . $method);
         }

src/Database/Database.php

@@ -43,10 +43,12 @@ class Database
     public const VAR_DATETIME = 'datetime';
     public const VAR_ID = 'id';
     public const VAR_OBJECT_ID = 'objectId';
+    public const VAR_VECTOR = 'vector';
 
     public const INT_MAX = 2147483647;
     public const BIG_INT_MAX = PHP_INT_MAX;
     public const DOUBLE_MAX = PHP_FLOAT_MAX;
+    public const VECTOR_MAX_SIZE = 16000; // pgvector limit
 
     // Relationship Types
     public const VAR_RELATIONSHIP = 'relationship';
@@ -1834,8 +1836,33 @@ private function validateAttribute(
             case self::VAR_DATETIME:
             case self::VAR_RELATIONSHIP:
                 break;
+            case self::VAR_VECTOR:
+                if (!$this->adapter->getSupportForVectors()) {
+                    throw new DatabaseException('Vector type is only supported in PostgreSQL adapter');
+                }
+                if ($array) {
+                    throw new DatabaseException('Vector type cannot be an array');
+                }
+                if ($size <= 0) {
+                    throw new DatabaseException('Vector size must be a positive integer');
+                }
+                if ($size > self::VECTOR_MAX_SIZE) {
+                    throw new DatabaseException('Vector size cannot exceed ' . self::VECTOR_MAX_SIZE);
+                }
+                break;
             default:
-                throw new DatabaseException('Unknown attribute type: ' . $type . '. Must be one of ' . self::VAR_STRING . ', ' . self::VAR_INTEGER . ', ' . self::VAR_FLOAT . ', ' . self::VAR_BOOLEAN . ', ' . self::VAR_DATETIME . ', ' . self::VAR_RELATIONSHIP);
+                $supportedTypes = [
+                    self::VAR_STRING,
+                    self::VAR_INTEGER,
+                    self::VAR_FLOAT,
+                    self::VAR_BOOLEAN,
+                    self::VAR_DATETIME,
+                    self::VAR_RELATIONSHIP
+                ];
+                if ($this->adapter->getSupportForVectors()) {
+                    $supportedTypes[] = self::VAR_VECTOR;
+                }
+                throw new DatabaseException('Unknown attribute type: ' . $type . '. Must be one of ' . implode(', ', $supportedTypes));
         }
 
         // Only execute when $default is given
@@ -1904,8 +1931,25 @@ protected function validateDefaultTypes(string $type, mixed $default): void
                     throw new DatabaseException('Default value ' . $default . ' does not match given type ' . $type);
                 }
                 break;
+            case self::VAR_VECTOR:
+                // When validating individual vector components (from recursion), they should be numeric
+                if ($defaultType !== 'double' && $defaultType !== 'integer') {
+                    throw new DatabaseException('Vector components must be numeric values (float or integer)');
+                }
+                break;
             default:
-                throw new DatabaseException('Unknown attribute type: ' . $type . '. Must be one of ' . self::VAR_STRING . ', ' . self::VAR_INTEGER . ', ' . self::VAR_FLOAT . ', ' . self::VAR_BOOLEAN . ', ' . self::VAR_DATETIME . ', ' . self::VAR_RELATIONSHIP);
+                $supportedTypes = [
+                    self::VAR_STRING,
+                    self::VAR_INTEGER,
+                    self::VAR_FLOAT,
+                    self::VAR_BOOLEAN,
+                    self::VAR_DATETIME,
+                    self::VAR_RELATIONSHIP
+                ];
+                if ($this->adapter->getSupportForVectors()) {
+                    $supportedTypes[] = self::VAR_VECTOR;
+                }
+                throw new DatabaseException('Unknown attribute type: ' . $type . '. Must be one of ' . implode(', ', $supportedTypes));
         }
     }
 
@@ -2146,8 +2190,33 @@ public function updateAttribute(string $collection, string $id, ?string $type =
                         throw new DatabaseException('Size must be empty');
                     }
                     break;
+                case self::VAR_VECTOR:
+                    if (!$this->adapter->getSupportForVectors()) {
+                        throw new DatabaseException('Vector type is only supported in PostgreSQL adapter');
+                    }
+                    if ($array) {
+                        throw new DatabaseException('Vector type cannot be an array');
+                    }
+                    if ($size <= 0) {
+                        throw new DatabaseException('Vector size must be a positive integer');
+                    }
+                    if ($size > self::VECTOR_MAX_SIZE) {
+                        throw new DatabaseException('Vector size cannot exceed ' . self::VECTOR_MAX_SIZE);
+                    }
+                    break;
                 default:
-                    throw new DatabaseException('Unknown attribute type: ' . $type . '. Must be one of ' . self::VAR_STRING . ', ' . self::VAR_INTEGER . ', ' . self::VAR_FLOAT . ', ' . self::VAR_BOOLEAN . ', ' . self::VAR_DATETIME . ', ' . self::VAR_RELATIONSHIP);
+                    $supportedTypes = [
+                        self::VAR_STRING,
+                        self::VAR_INTEGER,
+                        self::VAR_FLOAT,
+                        self::VAR_BOOLEAN,
+                        self::VAR_DATETIME,
+                        self::VAR_RELATIONSHIP
+                    ];
+                    if ($this->adapter->getSupportForVectors()) {
+                        $supportedTypes[] = self::VAR_VECTOR;
+                    }
+                    throw new DatabaseException('Unknown attribute type: ' . $type . '. Must be one of ' . implode(', ', $supportedTypes));
             }
 
             /** Ensure required filters for the attribute are passed */

src/Database/Query.php

@@ -27,6 +27,11 @@ class Query
     public const TYPE_ENDS_WITH = 'endsWith';
     public const TYPE_NOT_ENDS_WITH = 'notEndsWith';
 
+    // Vector query methods (PostgreSQL only)
+    public const TYPE_VECTOR_DOT = 'vectorDot';
+    public const TYPE_VECTOR_COSINE = 'vectorCosine';
+    public const TYPE_VECTOR_EUCLIDEAN = 'vectorEuclidean';
+
     public const TYPE_SELECT = 'select';
 
     // Order methods
@@ -64,6 +69,9 @@ class Query
         self::TYPE_NOT_STARTS_WITH,
         self::TYPE_ENDS_WITH,
         self::TYPE_NOT_ENDS_WITH,
+        self::TYPE_VECTOR_DOT,
+        self::TYPE_VECTOR_COSINE,
+        self::TYPE_VECTOR_EUCLIDEAN,
         self::TYPE_SELECT,
         self::TYPE_ORDER_DESC,
         self::TYPE_ORDER_ASC,
@@ -833,4 +841,40 @@ public function setOnArray(bool $bool): void
     {
         $this->onArray = $bool;
     }
+
+    /**
+     * Helper method to create Query with vectorDot method
+     *
+     * @param string $attribute
+     * @param array<float> $vector
+     * @return Query
+     */
+    public static function vectorDot(string $attribute, array $vector): self
+    {
+        return new self(self::TYPE_VECTOR_DOT, $attribute, $vector);
+    }
+
+    /**
+     * Helper method to create Query with vectorCosine method
+     *
+     * @param string $attribute
+     * @param array<float> $vector
+     * @return Query
+     */
+    public static function vectorCosine(string $attribute, array $vector): self
+    {
+        return new self(self::TYPE_VECTOR_COSINE, $attribute, $vector);
+    }
+
+    /**
+     * Helper method to create Query with vectorEuclidean method
+     *
+     * @param string $attribute
+     * @param array<float> $vector
+     * @return Query
+     */
+    public static function vectorEuclidean(string $attribute, array $vector): self
+    {
+        return new self(self::TYPE_VECTOR_EUCLIDEAN, $attribute, $vector);
+    }
 }

src/Database/Validator/Query/Filter.php

@@ -138,6 +138,25 @@ protected function isValidAttributeAndValues(string $attribute, array $values, s
                 case Database::VAR_RELATIONSHIP:
                     $validator = new Text(255, 0); // The query is always on uid
                     break;
+                case Database::VAR_VECTOR:
+                    // For vector queries, validate that the value is an array of floats
+                    if (!is_array($value)) {
+                        $this->message = 'Vector query value must be an array';
+                        return false;
+                    }
+                    foreach ($value as $component) {
+                        if (!is_numeric($component)) {
+                            $this->message = 'Vector query value must contain only numeric values';
+                            return false;
+                        }
+                    }
+                    // Check size match
+                    $expectedSize = $attributeSchema['size'] ?? 0;
+                    if (count($value) !== $expectedSize) {
+                        $this->message = "Vector query value must have {$expectedSize} elements";
+                        return false;
+                    }
+                    break;
                 default:
                     $this->message = 'Unknown Data type';
                     return false;
@@ -197,6 +216,18 @@ protected function isValidAttributeAndValues(string $attribute, array $values, s
             return false;
         }
 
+        // Vector queries can only be used on vector attributes (not arrays)
+        if (in_array($method, [Query::TYPE_VECTOR_DOT, Query::TYPE_VECTOR_COSINE, Query::TYPE_VECTOR_EUCLIDEAN])) {
+            if ($attributeSchema['type'] !== Database::VAR_VECTOR) {
+                $this->message = 'Vector queries can only be used on vector attributes';
+                return false;
+            }
+            if ($array) {
+                $this->message = 'Vector queries cannot be used on array attributes';
+                return false;
+            }
+        }
+
         return true;
     }
 
@@ -273,6 +304,27 @@ public function isValid($value): bool
             case Query::TYPE_IS_NOT_NULL:
                 return $this->isValidAttributeAndValues($attribute, $value->getValues(), $method);
 
+            case Query::TYPE_VECTOR_DOT:
+            case Query::TYPE_VECTOR_COSINE:
+            case Query::TYPE_VECTOR_EUCLIDEAN:
+                // Validate that the attribute is a vector type
+                if (!$this->isValidAttribute($attribute)) {
+                    return false;
+                }
+
+                $attributeSchema = $this->schema[$attribute];
+                if ($attributeSchema['type'] !== Database::VAR_VECTOR) {
+                    $this->message = 'Vector queries can only be used on vector attributes';
+                    return false;
+                }
+
+                if (count($value->getValues()) != 1) {
+                    $this->message = \ucfirst($method) . ' queries require exactly one vector value.';
+                    return false;
+                }
+
+                return $this->isValidAttributeAndValues($attribute, $value->getValues(), $method);
+
             case Query::TYPE_OR:
             case Query::TYPE_AND:
                 $filters = Query::groupByType($value->getValues())['filters'];

src/Database/Validator/Structure.php

@@ -8,6 +8,7 @@
 use Utopia\Database\Document;
 use Utopia\Database\Exception as DatabaseException;
 use Utopia\Database\Validator\Datetime as DatetimeValidator;
+use Utopia\Database\Validator\Vector;
 use Utopia\Validator;
 use Utopia\Validator\Boolean;
 use Utopia\Validator\FloatValidator;
@@ -350,6 +351,10 @@ protected function checkForInvalidAttributeValues(array $structure, array $keys)
                     );
                     break;
 
+                case Database::VAR_VECTOR:
+                    $validators[] = new Vector($attribute['size'] ?? 0);
+                    break;
+
                 default:
                     $this->message = 'Unknown attribute type "'.$type.'"';
                     return false;