Refactor VectorDB Embeddings API and Update Dimension Handling

- Updated the Create.php file to streamline the embedding creation process by removing unnecessary authentication checks and simplifying the parameter structure. - Changed the parameter from 'documents' to 'texts' for clarity and adjusted the embedding model handling. - Modified the response model to include error handling for embedding generation. - Updated the Embedding response model to reflect changes in dimension naming and added error message handling. - Refactored VectorDBCollection model to replace 'dimensions' with 'dimension' for consistency across the codebase. - Adjusted all relevant tests to accommodate the new parameter names and response structures, ensuring comprehensive coverage for the updated functionality.
2026-05-26 13:51:13 +00:00 · 2025-12-02 14:20:25 +05:30
parent abe1257bd5
commit d2c9ac079a
18 changed files with 135 additions and 273 deletions
@@ -41,7 +41,7 @@ return [
                'filters' => [],
            ],
            [
-                '$id' => ID::custom('dimensions'),
+                '$id' => ID::custom('dimension'),
                'type' => Database::VAR_INTEGER,
                'size' => 0,
                'required' => true,
@@ -298,11 +298,6 @@ class Update extends Action
                    $data = $data->getArrayCopy();
                }

-                // Decode JSON strings that may have been encoded when storing nested arrays/objects
-                if (\is_array($data)) {
-                    $data = $this->decodeJsonStrings($data);
-                }
-
                if (!isset($dbCache[$databaseInternalId])) {
                    $databaseDoc = Authorization::skip(fn () => $dbForProject->findOne('databases', [
                        Query::equal('$sequence', [$databaseInternalId])
@@ -727,8 +722,6 @@ class Update extends Action
        array &$state
    ): int {
        $count = 0;
-        // Decode JSON strings in bulk create data
-        $data = $this->decodeJsonStrings($data);
        $dbForProject->withRequestTimestamp($createdAt, function () use ($dbForProject, $collectionId, $data, &$state, &$count) {
            $documents = \array_map(function ($doc) {
                return $doc instanceof Document ? $doc : new Document($doc);
@@ -767,11 +760,8 @@ class Update extends Action
        \DateTime $createdAt,
        array &$state
    ): int {
-        // extracting query first then decoding the nested transaction log data
-        // otherwise can result error as queries would get transformed to array instead of string
        $queries = Query::parseQueries($data['queries'] ?? []);
        $updateData = new Document($data['data']);
-        $data = $this->decodeJsonStrings($data);

        $dependentDocs = [];

@@ -842,8 +832,6 @@ class Update extends Action
        \DateTime $createdAt,
        array &$state
    ): int {
-        // Decode JSON strings in bulk upsert data
-        $data = $this->decodeJsonStrings($data);
        $documents = \array_map(function ($doc) {
            return $doc instanceof Document ? $doc : new Document($doc);
        }, $data);
@@ -919,31 +907,4 @@ class Update extends Action

        return $count;
    }
-
-    /**
-     * Recursively decode JSON strings in data array
-     * This handles cases where nested arrays/objects are stored as JSON strings in the database
-     *
-     * @param array $data
-     * @return array
-     */
-    private function decodeJsonStrings(array $data): array
-    {
-        foreach ($data as $key => $value) {
-            if (\is_string($value)) {
-                $decoded = \json_decode($value, true);
-                if (\json_last_error() === JSON_ERROR_NONE && (\is_array($decoded) || \is_object($decoded))) {
-                    $data[$key] = $decoded;
-                    // Recursively decode nested structures
-                    if (\is_array($decoded)) {
-                        $data[$key] = $this->decodeJsonStrings($decoded);
-                    }
-                }
-            } elseif (\is_array($value)) {
-                // Recursively process nested arrays
-                $data[$key] = $this->decodeJsonStrings($value);
-            }
-        }
-        return $data;
-    }
 }
@@ -69,7 +69,7 @@ class Create extends CollectionAction
            ->param('databaseId', '', fn (Database $dbForProject) => new UID($dbForProject->getAdapter()->getMaxUIDLength()), 'Database ID.', false, ['dbForProject'])
            ->param('collectionId', '', fn (Database $dbForProject) => new CustomId(false, $dbForProject->getAdapter()->getMaxUIDLength()), 'Unique Id. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can\'t start with a special char. Max length is 36 chars.', false, ['dbForProject'])
            ->param('name', '', new Text(128), 'Collection name. Max length: 128 chars.')
-            ->param('dimensions', null, new Range(MIN_VECTOR_DIMENSION, MAX_VECTOR_DIMENSION), 'Embedding dimensions.')
+            ->param('dimension', null, new Range(MIN_VECTOR_DIMENSION, MAX_VECTOR_DIMENSION), 'Embedding dimension.')
            ->param('permissions', null, new Permissions(APP_LIMIT_ARRAY_PARAMS_SIZE), 'An array of permissions strings. By default, no user is granted with any permissions. [Learn more about permissions](https://appwrite.io/docs/permissions).', true)
            ->param('documentSecurity', false, new Boolean(true), 'Enables configuring permissions for individual documents. A user needs one of document or collection level permissions to access a document. [Learn more about permissions](https://appwrite.io/docs/permissions).', true)
            ->param('enabled', true, new Boolean(), 'Is collection enabled? When set to \'disabled\', users cannot access the collection but Server SDKs with and API key can still read and write to the collection. No data is lost when this is toggled.', true)
@@ -80,7 +80,7 @@ class Create extends CollectionAction
            ->callback($this->action(...));
    }

-    public function action(string $databaseId, string $collectionId, string $name, int $dimensions, ?array $permissions, bool $documentSecurity, bool $enabled, UtopiaResponse $response, Database $dbForProject, callable $getDatabasesDB, Event $queueForEvents): void
+    public function action(string $databaseId, string $collectionId, string $name, int $dimension, ?array $permissions, bool $documentSecurity, bool $enabled, UtopiaResponse $response, Database $dbForProject, callable $getDatabasesDB, Event $queueForEvents): void
    {
        $database = Authorization::skip(fn () => $dbForProject->getDocument('databases', $databaseId));

@@ -102,7 +102,7 @@ class Create extends CollectionAction
                'documentSecurity' => $documentSecurity,
                'enabled' => $enabled,
                'name' => $name,
-                'dimensions' => $dimensions,
+                'dimension' => $dimension,
                'search' => \implode(' ', [$collectionId, $name]),
            ]));

@@ -121,7 +121,7 @@ class Create extends CollectionAction
        $collections = (Config::getParam('collections', [])['vectordb'] ?? [])['collections'] ?? [];
        foreach ($collections['defaultAttributes'] as $attribute) {
            if ($attribute['$id'] === 'embeddings') {
-                $attribute['size'] = $dimensions;
+                $attribute['size'] = $dimension;
            }
            $attributes[] = new Document($attribute);
        }
@@ -142,7 +142,7 @@ class Create extends CollectionAction
            );
            // Create attribute and indexes metadata documents in the attributes and indexes collections
            // needed for the get and list calls
-            $attributeDocs = array_map(function ($attributeConfig) use ($database, $collection, $databaseId, $collectionId, $dimensions) {
+            $attributeDocs = array_map(function ($attributeConfig) use ($database, $collection, $databaseId, $collectionId, $dimension) {
                $key = \is_string($attributeConfig['$id']) ? $attributeConfig['$id'] : (string) $attributeConfig['$id'];
                return new Document([
                    '$id' => ID::custom($database->getSequence() . '_' . $collection->getSequence() . '_' . $key),
@@ -153,7 +153,7 @@ class Create extends CollectionAction
                    'collectionId' => $collectionId,
                    'type' => $attributeConfig['type'],
                    'status' => 'available',
-                    'size' => $dimensions,
+                    'size' => $dimension,
                    'required' => $attributeConfig['required'] ?? false,
                    'signed' => $attributeConfig['signed'] ?? false,
                    'default' => $attributeConfig['default'] ?? null,
@@ -59,7 +59,7 @@ class Update extends CollectionAction
            ->param('databaseId', '', new UID(), 'Database ID.')
            ->param('collectionId', '', new UID(), 'Collection ID.')
            ->param('name', null, new Text(128), 'Collection name. Max length: 128 chars.')
-            ->param('dimensions', null, new Range(MIN_VECTOR_DIMENSION, MAX_VECTOR_DIMENSION), 'Embedding dimensions.', true)
+            ->param('dimension', null, new Range(MIN_VECTOR_DIMENSION, MAX_VECTOR_DIMENSION), 'Embedding dimensions.', true)
            ->param('permissions', null, new Permissions(APP_LIMIT_ARRAY_PARAMS_SIZE), 'An array of permission strings. By default, the current permissions are inherited. [Learn more about permissions](https://appwrite.io/docs/permissions).', true)
            ->param('documentSecurity', false, new Boolean(true), 'Enables configuring permissions for individual documents. A user needs one of document or collection level permissions to access a document. [Learn more about permissions](https://appwrite.io/docs/permissions).', true)
            ->param('enabled', true, new Boolean(), 'Is collection enabled? When set to \'disabled\', users cannot access the collection but Server SDKs with and API key can still read and write to the collection. No data is lost when this is toggled.', true)
@@ -94,7 +94,7 @@ class Update extends CollectionAction
            $collectionId,
            $collection
                ->setAttribute('name', $name ?? $collection->getAttribute('name'))
-                ->setAttribute('dimensions', $dimensions ?? $collection->getAttribute('dimensions'))
+                ->setAttribute('dimension', $dimensions ?? $collection->getAttribute('dimension'))
                ->setAttribute('$permissions', $permissions)
                ->setAttribute('documentSecurity', $documentSecurity)
                ->setAttribute('enabled', $enabled)
@@ -2,8 +2,6 @@

 namespace Appwrite\Platform\Modules\Databases\Http\VectorDB\Embeddings\Text;

-use Appwrite\Auth\Auth;
-use Appwrite\Extend\Exception;
 use Appwrite\Platform\Modules\Databases\Http\Databases\Collections\Documents\Action as CreateDocumentAction;
 use Appwrite\SDK\AuthType;
 use Appwrite\SDK\ContentType;
@@ -11,14 +9,13 @@ use Appwrite\SDK\Method;
 use Appwrite\SDK\Parameter;
 use Appwrite\SDK\Response as SDKResponse;
 use Appwrite\Utopia\Response as UtopiaResponse;
-use Utopia\Database\Database;
+use Utopia\Agents\Adapters\Ollama;
+use Utopia\Agents\Agent;
 use Utopia\Database\Document;
-use Utopia\Database\Validator\Authorization;
 use Utopia\Swoole\Response as SwooleResponse;
 use Utopia\Validator\ArrayList;
-use Utopia\Validator\JSON;
-
-// Agent is dynamically provided via container; avoid strict type to pass lints
+use Utopia\Validator\Text;
+use Utopia\Validator\WhiteList;

 class Create extends CreateDocumentAction
 {
@@ -58,7 +55,7 @@ class Create extends CreateDocumentAction
                    name: 'createTextEmbeddings',
                    desc: 'Create Text Embedding',
                    description: '/docs/references/vectordb/create-document.md',
-                    auth: [AuthType::SESSION, AuthType::KEY, AuthType::JWT],
+                    auth: [AuthType::KEY, AuthType::JWT],
                    responses: [
                        new SDKResponse(
                            code: SwooleResponse::STATUS_CODE_OK,
@@ -73,73 +70,44 @@ class Create extends CreateDocumentAction
                    ]
                )
            ])
-            ->param('documents', [], fn (array $plan) => new ArrayList(new JSON(), $plan['databasesBatchSize'] ?? APP_LIMIT_DATABASE_BATCH), 'Array of documents data as JSON objects.', true, ['plan'])
+            ->param('embeddingModel', Ollama::MODEL_EMBEDDING_GEMMA, new WhiteList(Ollama::MODELS), 'The embedding model to use for generating vector embeddings.', false)
+            ->param('texts', [], fn (array $plan) => new ArrayList(new Text(0), $plan['databasesBatchSize'] ?? APP_LIMIT_DATABASE_BATCH), 'Array of text to generate embeddings.', true, ['plan'])
            ->inject('response')
            ->inject('embeddingAgent')
-            ->inject('dbForProject')
-            ->inject('getDatabasesDB')
            ->callback($this->action(...));
    }

-    public function action(array $documents, UtopiaResponse $response, $embeddingAgent, Database $dbForProject, callable $getDatabasesDB): void
+    public function action(string $embeddingModel, array $texts, UtopiaResponse $response, Agent $embeddingAgent): void
    {
-        $isAPIKey = Auth::isAppUser(Authorization::getRoles());
-        $isPrivilegedUser = Auth::isPrivilegedUser(Authorization::getRoles());
-
-        if (!$isAPIKey && !$isPrivilegedUser) {
-            throw new Exception(Exception::GENERAL_BAD_REQUEST);
-        }
-
-        if (empty($documents)) {
-            throw new Exception(Exception::DOCUMENT_MISSING_DATA);
-        }
-
-        // Validate and process each document
-        $availableModels = [];
-        $availableModels = $embeddingAgent->getAdapter()->getModels();
-
        $results = [];
+        $embeddingAgent->getAdapter()->setModel($embeddingModel);
+        $dimension = $embeddingAgent->getAdapter()->getEmbeddingDimension();

-        // validating all documents first
-        foreach ($documents as $index => $item) {
-            if (!\is_array($item)) {
-                throw new Exception(Exception::DOCUMENT_INVALID_STRUCTURE, 'Invalid item at index ' . $index);
-            }
+        foreach ($texts as $text) {

-            $text = $item['text'] ?? '';
-            $model = $item['embeddingModel'] ?? ($item['embeddingModel'] ?? null);
-
-            if (!\is_string($text) || $text === '') {
-                throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Missing or invalid "text" at index ' . $index);
+            $embedding = [];
+            $error = '';
+            try {
+                $embedResult = $embeddingAgent->embed($text);
+                $embedding = $embedResult['embedding'] ?? [];
+            } catch (\Exception $e) {
+                $error = 'Error while generating embedding';
            }
-            if (!\is_string($model) || $model === '') {
-                throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Missing or invalid "embeddingModel" at index ' . $index);
-            }
-            if (!empty($availableModels) && !\in_array($model, $availableModels, true)) {
-                throw new Exception(Exception::GENERAL_BAD_REQUEST, 'Unknown embedding model: ' . $model);
-            }
-        }
-        foreach ($documents as $index => $item) {
-            $embeddingAgent->getAdapter()->setModel($model);
-
-            $embedResult = $embeddingAgent->embed($text);
-            $vector = $embedResult['embedding'] ?? [];
-            $dimensions = \is_array($vector) ? \count($vector) : 0;

            $results[] = new Document([
-                'model' => $model,
-                'dimensions' => $dimensions,
-                'embeddings' => $vector,
+                'model' => $embeddingModel,
+                'dimension' => $dimension,
+                'embedding' => $embedding,
+                'error' => $error
            ]);
-
        }
-        $list = new Document([
-            'embeddings' => array_map(fn ($d) => $d, $results),
+        $embeddings = new Document([
+            'embeddings' => $results,
            'total' => \count($results),
        ]);

        $response
            ->setStatusCode(SwooleResponse::STATUS_CODE_OK)
-            ->dynamic($list, $this->getBulkResponseModel());
+            ->dynamic($embeddings, $this->getBulkResponseModel());
    }
 }
@@ -24,16 +24,24 @@ class Embedding extends Model
                'description' => 'Embedding model used to generate embeddings.',
                'example' => 'embeddinggemma'
            ])
-            ->addRule('dimensions', [
+            ->addRule('dimension', [
                'type' => self::TYPE_INTEGER,
                'description' => 'Number of dimensions for each embedding vector.',
                'example' => 768
            ])
-            ->addRule('embeddings', [
+            ->addRule('embedding', [
                'type' => self::TYPE_FLOAT,
                'array' => true,
-                'description' => 'Embedding vector values.',
+                'default' => [],
+                'description' => 'Embedding vector values. If an error occurs, this will be an empty array.',
                'example' => [0.01, 0.02, 0.03]
+            ])
+            ->addRule('error', [
+                'type' => self::TYPE_STRING,
+                'array' => false,
+                'default' => '',
+                'description' => 'Error message if embedding generation fails. Empty string if no error.',
+                'example' => 'Error message'
            ]);
    }
 }
@@ -3,74 +3,19 @@
 namespace Appwrite\Utopia\Response\Model;

 use Appwrite\Utopia\Response;
-use Appwrite\Utopia\Response\Model;

-class VectorDBCollection extends Model
+class VectorDBCollection extends Collection
 {
    public function __construct()
    {
+        parent::__construct();
        $this
-            ->addRule('$id', [
-                'type' => self::TYPE_STRING,
-                'description' => 'Collection ID.',
-                'default' => '',
-                'example' => '5e5ea5c16897e',
-            ])
-            ->addRule('$createdAt', [
-                'type' => self::TYPE_DATETIME,
-                'description' => 'Collection creation date in ISO 8601 format.',
-                'default' => '',
-                'example' => self::TYPE_DATETIME_EXAMPLE,
-            ])
-            ->addRule('$updatedAt', [
-                'type' => self::TYPE_DATETIME,
-                'description' => 'Collection update date in ISO 8601 format.',
-                'default' => '',
-                'example' => self::TYPE_DATETIME_EXAMPLE,
-            ])
-            ->addRule('$permissions', [
-                'type' => self::TYPE_STRING,
-                'description' => 'Collection permissions. [Learn more about permissions](https://appwrite.io/docs/permissions).',
-                'default' => '',
-                'example' => ['read("any")'],
-                'array' => true
-            ])
-            ->addRule('databaseId', [
-                'type' => self::TYPE_STRING,
-                'description' => 'Database ID.',
-                'default' => '',
-                'example' => '5e5ea5c16897e',
-            ])
-            ->addRule('name', [
-                'type' => self::TYPE_STRING,
-                'description' => 'Collection name.',
-                'default' => '',
-                'example' => 'My Collection',
-            ])
-            ->addRule('enabled', [
-                'type' => self::TYPE_BOOLEAN,
-                'description' => 'Collection enabled. Can be \'enabled\' or \'disabled\'. When disabled, the collection is inaccessible to users, but remains accessible to Server SDKs using API keys.',
-                'default' => true,
-                'example' => false,
-            ])
-            ->addRule('documentSecurity', [
-                'type' => self::TYPE_BOOLEAN,
-                'description' => 'Whether document-level permissions are enabled. [Learn more about permissions](https://appwrite.io/docs/permissions).',
-                'default' => '',
-                'example' => true,
-            ])
-            ->addRule('dimensions', [
+            ->addRule('dimension', [
                'type' => self::TYPE_INTEGER,
-                'description' => 'Embedding dimensions.',
+                'description' => 'Embedding dimension.',
                'default' => 0,
                'example' => 1536,
            ])
-            ->addRule('search', [
-                'type' => self::TYPE_STRING,
-                'description' => 'Search text.',
-                'default' => '',
-                'example' => 'collectionId name',
-            ])
            ->addRule('attributes', [
                'type' => [
                    Response::MODEL_ATTRIBUTE_OBJECT,
@@ -81,13 +26,6 @@ class VectorDBCollection extends Model
                'example' => new \stdClass(),
                'array' => true,
            ])
-            ->addRule('indexes', [
-                'type' => Response::MODEL_INDEX,
-                'description' => 'Collection indexes.',
-                'default' => [],
-                'example' => new \stdClass(),
-                'array' => true
-            ])
        ;
    }

@@ -504,7 +504,7 @@ trait DatabasesBase
            'collectionId' => ID::unique(),
            'name' => 'Movies',
            'documentSecurity' => true,
-            'dimensions' => 1536,
+            'dimension' => 1536,
            'permissions' => [
                Permission::create(Role::user($this->getUser()['$id'])),
            ],
@@ -521,7 +521,7 @@ trait DatabasesBase
            'collectionId' => ID::unique(),
            'name' => 'Actors',
            'documentSecurity' => true,
-            'dimensions' => 1536,
+            'dimension' => 1536,
            'permissions' => [
                Permission::create(Role::user($this->getUser()['$id'])),
            ],
@@ -570,7 +570,7 @@ trait DatabasesBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'Sample Collection',
-            'dimensions' => 1536,
+            'dimension' => 1536,
            'documentSecurity' => true,
            'permissions' => [
                Permission::create(Role::user($this->getUser()['$id'])),
@@ -579,7 +579,7 @@ trait DatabasesBase

        $this->assertEquals(201, $collection['headers']['status-code']);
        $this->assertEquals('Sample Collection', $collection['body']['name']);
-        $this->assertEquals(1536, $collection['body']['dimensions']);
+        $this->assertEquals(1536, $collection['body']['dimension']);

        return [
            'databaseId' => $databaseId,
@@ -626,7 +626,7 @@ trait DatabasesBase
                'collectionId' => ID::unique(),
                'name' => $name,
                'documentSecurity' => true,
-                'dimensions' => $dimensions,
+                'dimension' => $dimensions,
                'permissions' => [
                    Permission::create(Role::user($userId)),
                ],
@@ -702,7 +702,7 @@ trait DatabasesBase
            'collectionId' => ID::unique(),
            'name' => 'ZeroDims',
            'documentSecurity' => true,
-            'dimensions' => 0,
+            'dimension' => 0,
            'permissions' => [Permission::create(Role::user($this->getUser()['$id']))],
        ]);
        $this->assertGreaterThanOrEqual(400, $col['headers']['status-code']);
@@ -717,7 +717,7 @@ trait DatabasesBase
            'collectionId' => ID::unique(),
            'name' => 'HugeDims',
            'documentSecurity' => true,
-            'dimensions' => 16001,
+            'dimension' => 16001,
            'permissions' => [Permission::create(Role::user($this->getUser()['$id']))],
        ]);
        $this->assertGreaterThanOrEqual(400, $col2['headers']['status-code']);
@@ -745,7 +745,7 @@ trait DatabasesBase
            'collectionId' => ID::unique(),
            'name' => 'OneDim',
            'documentSecurity' => true,
-            'dimensions' => 1,
+            'dimension' => 1,
            'permissions' => [Permission::create(Role::user($this->getUser()['$id']))],
        ]);
        $this->assertEquals(201, $col['headers']['status-code']);
@@ -802,7 +802,7 @@ trait DatabasesBase
            'collectionId' => ID::unique(),
            'name' => 'Docs',
            'documentSecurity' => true,
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [Permission::create(Role::user($this->getUser()['$id']))],
        ]);
        $this->assertEquals(201, $col['headers']['status-code']);
@@ -859,7 +859,7 @@ trait DatabasesBase
            'collectionId' => ID::unique(),
            'name' => 'Zeros',
            'documentSecurity' => true,
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [Permission::create(Role::user($this->getUser()['$id']))],
        ]);
        $this->assertEquals(201, $col['headers']['status-code']);
@@ -900,7 +900,7 @@ trait DatabasesBase
            'content-type' => 'application/json',
            'x-appwrite-project' => $this->getProject()['$id'],
            'x-appwrite-key' => $this->getProject()['apiKey']
-        ], [ 'collectionId' => ID::unique(), 'name' => 'Docs', 'documentSecurity' => true, 'dimensions' => 3, 'permissions' => [Permission::create(Role::user($this->getUser()['$id']))] ]);
+        ], [ 'collectionId' => ID::unique(), 'name' => 'Docs', 'documentSecurity' => true, 'dimension' => 3, 'permissions' => [Permission::create(Role::user($this->getUser()['$id']))] ]);
        $this->assertEquals(201, $col['headers']['status-code']);
        $collectionId = $col['body']['$id'];

@@ -932,7 +932,7 @@ trait DatabasesBase
            'content-type' => 'application/json',
            'x-appwrite-project' => $this->getProject()['$id'],
            'x-appwrite-key' => $this->getProject()['apiKey']
-        ], [ 'collectionId' => ID::unique(), 'name' => 'Docs', 'documentSecurity' => true, 'dimensions' => 3, 'permissions' => [Permission::create(Role::user($this->getUser()['$id']))] ]);
+        ], [ 'collectionId' => ID::unique(), 'name' => 'Docs', 'documentSecurity' => true, 'dimension' => 3, 'permissions' => [Permission::create(Role::user($this->getUser()['$id']))] ]);
        $this->assertEquals(201, $col['headers']['status-code']);
        $collectionId = $col['body']['$id'];

@@ -959,7 +959,7 @@ trait DatabasesBase
            'content-type' => 'application/json',
            'x-appwrite-project' => $this->getProject()['$id'],
            'x-appwrite-key' => $this->getProject()['apiKey']
-        ], [ 'collectionId' => ID::unique(), 'name' => 'Docs', 'documentSecurity' => true, 'dimensions' => 3, 'permissions' => [Permission::create(Role::user($this->getUser()['$id']))] ]);
+        ], [ 'collectionId' => ID::unique(), 'name' => 'Docs', 'documentSecurity' => true, 'dimension' => 3, 'permissions' => [Permission::create(Role::user($this->getUser()['$id']))] ]);
        $this->assertEquals(201, $col['headers']['status-code']);
        $collectionId = $col['body']['$id'];

@@ -40,7 +40,7 @@ class DatabasesConsoleClientTest extends Scope
        ], $this->getHeaders()), [
            'collectionId' => ID::unique(),
            'name' => 'Movies',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::read(Role::any()),
                Permission::create(Role::any()),
@@ -72,7 +72,7 @@ class DatabasesConsoleClientTest extends Scope
        ], $this->getHeaders()), [
            'collectionId' => ID::unique(),
            'name' => 'TvShows',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::read(Role::any()),
                Permission::create(Role::any()),
@@ -42,7 +42,7 @@ class DatabasesCustomClientTest extends Scope
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'Movies',
-            'dimensions' => 3,
+            'dimension' => 3,
            'documentSecurity' => true,
            'permissions' => [
                Permission::write(Role::user($this->getUser()['$id'])),
@@ -129,7 +129,7 @@ class DatabasesCustomClientTest extends Scope
        ]), [
            'collectionId' => ID::custom('permissionCheck'),
            'name' => 'permissionCheck',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [],
            'documentSecurity' => true,
        ]);
@@ -154,7 +154,7 @@ class DatabasesCustomServerTest extends Scope
                Permission::delete(Role::any()),
            ],
            'documentSecurity' => true,
-            'dimensions' => 3,
+            'dimension' => 3,
        ]);
        $this->assertEquals(201, $col1['headers']['status-code']);
        // Validate collection response model on create
@@ -163,7 +163,7 @@ class DatabasesCustomServerTest extends Scope
        $this->assertArrayHasKey('$updatedAt', $col1['body']);
        $this->assertArrayHasKey('enabled', $col1['body']);
        $this->assertArrayHasKey('documentSecurity', $col1['body']);
-        $this->assertArrayHasKey('dimensions', $col1['body']);
+        $this->assertArrayHasKey('dimension', $col1['body']);

        $col2 = $this->client->call(Client::METHOD_POST, '/vectordb/' . $databaseId . '/collections', [
            'content-type' => 'application/json',
@@ -179,7 +179,7 @@ class DatabasesCustomServerTest extends Scope
                Permission::delete(Role::any()),
            ],
            'documentSecurity' => true,
-            'dimensions' => 3,
+            'dimension' => 3,
        ]);
        $this->assertEquals(201, $col2['headers']['status-code']);
        $this->assertArrayHasKey('$id', $col2['body']);
@@ -198,7 +198,7 @@ class DatabasesCustomServerTest extends Scope
        $this->assertIsArray($list['body']['collections']);
        $this->assertArrayHasKey('$id', $list['body']['collections'][0]);
        $this->assertArrayHasKey('name', $list['body']['collections'][0]);
-        $this->assertArrayHasKey('dimensions', $list['body']['collections'][0]);
+        $this->assertArrayHasKey('dimension', $list['body']['collections'][0]);

        // Get collection
        $get = $this->client->call(Client::METHOD_GET, '/vectordb/' . $databaseId . '/collections/' . $col1['body']['$id'], [
@@ -209,7 +209,7 @@ class DatabasesCustomServerTest extends Scope
        $this->assertEquals(200, $get['headers']['status-code']);
        $this->assertEquals($col1['body']['$id'], $get['body']['$id']);
        $this->assertEquals('Test 1', $get['body']['name']);
-        $this->assertEquals(3, $get['body']['dimensions']);
+        $this->assertEquals(3, $get['body']['dimension']);

        // Update collection (name only)
        $upd = $this->client->call(Client::METHOD_PUT, '/vectordb/' . $databaseId . '/collections/' . $col1['body']['$id'], [
@@ -253,11 +253,11 @@ class DatabasesCustomServerTest extends Scope
            'x-appwrite-key' => $this->getProject()['apiKey']
        ], [
            'name' => 'Test 1 Renamed',
-            'dimensions' => 4,
+            'dimension' => 4,
        ]);
        $this->assertEquals(200, $upd['headers']['status-code']);
        $this->assertEquals('Test 1 Renamed', $upd['body']['name']);
-        $this->assertEquals(4, $upd['body']['dimensions']);
+        $this->assertEquals(4, $upd['body']['dimension']);

        // Read back to confirm
        $get = $this->client->call(Client::METHOD_GET, '/vectordb/' . $databaseId . '/collections/' . $collectionId, [
@@ -267,7 +267,7 @@ class DatabasesCustomServerTest extends Scope
        ]);
        $this->assertEquals(200, $get['headers']['status-code']);
        $this->assertEquals('Test 1 Renamed', $get['body']['name']);
-        $this->assertEquals(4, $get['body']['dimensions']);
+        $this->assertEquals(4, $get['body']['dimension']);

        return $data;
    }
@@ -506,7 +506,7 @@ class DatabasesCustomServerTest extends Scope
            'collectionId' => ID::unique(),
            'name' => 'BulkColCreate',
            'documentSecurity' => true,
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [Permission::read(Role::any())]
        ]);
        $this->assertEquals(201, $col['headers']['status-code']);
@@ -582,7 +582,7 @@ class DatabasesCustomServerTest extends Scope
            'collectionId' => ID::unique(),
            'name' => 'EmbedCol',
            'documentSecurity' => true,
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [Permission::read(Role::any())]
        ]);
        $this->assertEquals(201, $col['headers']['status-code']);
@@ -594,10 +594,11 @@ class DatabasesCustomServerTest extends Scope
            'x-appwrite-project' => $this->getProject()['$id'],
            'x-appwrite-key' => $this->getProject()['apiKey']
        ], [
-            'documents' => [
-                ['text' => 'hello world', 'embeddingModel' => 'embeddinggemma'],
-                ['text' => 'second sentence', 'embeddingModel' => 'embeddinggemma'],
-            ]
+            'embeddingModel' => 'embeddinggemma',
+            'texts' => [
+                'hello world',
+                'second sentence',
+            ],
        ]);
        $this->assertEquals(200, $ok['headers']['status-code']);
        $this->assertIsInt($ok['body']['total'] ?? 0);
@@ -606,56 +607,42 @@ class DatabasesCustomServerTest extends Scope
        $this->assertCount(2, $ok['body']['embeddings']);
        foreach ($ok['body']['embeddings'] as $embed) {
            $this->assertIsString($embed['model']);
-            $this->assertIsInt($embed['dimensions']);
-            $this->assertIsArray($embed['embeddings']);
-            $this->assertGreaterThan(0, count($embed['embeddings']));
+            $this->assertIsInt($embed['dimension']);
+            $this->assertIsArray($embed['embedding']);
+            $this->assertGreaterThan(0, count($embed['embedding']));
+            $this->assertArrayHasKey('error', $embed);
        }

-        // Error: missing documents
-        $missingDocs = $this->client->call(Client::METHOD_POST, "/vectordb/embeddings/text", [
+        // Error: missing texts payload
+        $missingTexts = $this->client->call(Client::METHOD_POST, "/vectordb/embeddings/text", [
            'content-type' => 'application/json',
            'x-appwrite-project' => $this->getProject()['$id'],
            'x-appwrite-key' => $this->getProject()['apiKey']
        ], []);
-        $this->assertEquals(400, $missingDocs['headers']['status-code']);
+        $this->assertEquals(400, $missingTexts['headers']['status-code']);

-        // Error: invalid item structure (not an object)
+        // Error: invalid texts item type (must be strings)
        $invalidItem = $this->client->call(Client::METHOD_POST, "/vectordb/embeddings/text", [
            'content-type' => 'application/json',
            'x-appwrite-project' => $this->getProject()['$id'],
            'x-appwrite-key' => $this->getProject()['apiKey']
        ], [
-            'documents' => [ 'oops' ]
+            'embeddingModel' => 'embeddinggemma',
+            'texts' => [
+                'valid text',
+                123, // invalid, not a string
+            ],
        ]);
        $this->assertEquals(400, $invalidItem['headers']['status-code']);

-        // Error: missing text
-        $missingText = $this->client->call(Client::METHOD_POST, "/vectordb/embeddings/text", [
-            'content-type' => 'application/json',
-            'x-appwrite-project' => $this->getProject()['$id'],
-            'x-appwrite-key' => $this->getProject()['apiKey']
-        ], [
-            'documents' => [ ['embeddingModel' => 'embeddinggemma'] ]
-        ]);
-        $this->assertEquals(400, $missingText['headers']['status-code']);
-
-        // Error: missing embeddingModel
-        $missingModel = $this->client->call(Client::METHOD_POST, "/vectordb/embeddings/text", [
-            'content-type' => 'application/json',
-            'x-appwrite-project' => $this->getProject()['$id'],
-            'x-appwrite-key' => $this->getProject()['apiKey']
-        ], [
-            'documents' => [ ['text' => 'no model'] ]
-        ]);
-        $this->assertEquals(400, $missingModel['headers']['status-code']);
-
        // Error: unknown embedding model
        $unknownModel = $this->client->call(Client::METHOD_POST, "/vectordb/embeddings/text", [
            'content-type' => 'application/json',
            'x-appwrite-project' => $this->getProject()['$id'],
            'x-appwrite-key' => $this->getProject()['apiKey']
        ], [
-            'documents' => [ ['text' => 'hello', 'embeddingModel' => 'nonexistent-model'] ]
+            'embeddingModel' => 'nonexistent-model',
+            'texts' => ['hello'],
        ]);
        $this->assertEquals(400, $unknownModel['headers']['status-code']);
    }
@@ -679,7 +666,7 @@ class DatabasesCustomServerTest extends Scope
            'collectionId' => ID::unique(),
            'name' => 'BulkColUpsert',
            'documentSecurity' => true,
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [Permission::read(Role::any())]
        ]);
        $this->assertEquals(201, $col['headers']['status-code']);
@@ -772,7 +759,7 @@ class DatabasesCustomServerTest extends Scope
            'collectionId' => ID::unique(),
            'name' => 'BulkColUpdate',
            'documentSecurity' => true,
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [Permission::read(Role::any())]
        ]);
        $this->assertEquals(201, $col['headers']['status-code']);
@@ -840,7 +827,7 @@ class DatabasesCustomServerTest extends Scope
            'collectionId' => ID::unique(),
            'name' => 'BulkColDelete',
            'documentSecurity' => true,
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [Permission::read(Role::any())]
        ]);
        $this->assertEquals(201, $col['headers']['status-code']);
@@ -905,7 +892,7 @@ class DatabasesCustomServerTest extends Scope
            'collectionId' => ID::unique(),
            'name' => 'TimestampTestCollection',
            'documentSecurity' => true,
-            'dimensions' => 1536,
+            'dimension' => 1536,
            'permissions' => [Permission::read(Role::any())]
        ]);
        $this->assertEquals(201, $col['headers']['status-code']);
@@ -34,7 +34,7 @@ class DatabasesPermissionsGuestTest extends Scope
        $publicMovies = $this->client->call(Client::METHOD_POST, '/vectordb/' . $databaseId . '/collections', $this->getServerHeader(), [
            'collectionId' => ID::unique(),
            'name' => 'Movies',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::read(Role::any()),
                Permission::create(Role::any()),
@@ -45,7 +45,7 @@ class DatabasesPermissionsGuestTest extends Scope
        $privateMovies = $this->client->call(Client::METHOD_POST, '/vectordb/' . $databaseId . '/collections', $this->getServerHeader(), [
            'collectionId' => ID::unique(),
            'name' => 'Movies',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [],
            'documentSecurity' => true,
        ]);
@@ -239,7 +239,7 @@ class DatabasesPermissionsGuestTest extends Scope
        $movies = $this->client->call(Client::METHOD_POST, '/vectordb/' . $databaseId . '/collections', $this->getServerHeader(), [
            'collectionId' => ID::unique(),
            'name' => 'Movies',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::create(Role::any()),
            ],
@@ -127,7 +127,7 @@ class DatabasesPermissionsMemberTest extends Scope
        $public = $this->client->call(Client::METHOD_POST, '/vectordb/' . $databaseId . '/collections', $this->getServerHeader(), [
            'collectionId' => ID::unique(),
            'name' => 'Movies',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::read(Role::any()),
                Permission::create(Role::any()),
@@ -142,7 +142,7 @@ class DatabasesPermissionsMemberTest extends Scope
        $private = $this->client->call(Client::METHOD_POST, '/vectordb/' . $databaseId . '/collections', $this->getServerHeader(), [
            'collectionId' => ID::unique(),
            'name' => 'Private Movies',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::read(Role::users()),
                Permission::create(Role::users()),
@@ -157,7 +157,7 @@ class DatabasesPermissionsMemberTest extends Scope
        $doconly = $this->client->call(Client::METHOD_POST, '/vectordb/' . $databaseId . '/collections', $this->getServerHeader(), [
            'collectionId' => ID::unique(),
            'name' => 'Document Only Movies',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [],
            'documentSecurity' => true,
        ]);
@@ -47,7 +47,7 @@ class DatabasesPermissionsTeamTest extends Scope
        $collection1 = $this->client->call(Client::METHOD_POST, '/vectordb/' . $this->databaseId . '/collections', $this->getServerHeader(), [
            'collectionId' => ID::custom('collection1'),
            'name' => 'Collection 1',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::read(Role::team($teams['team1']['$id'])),
                Permission::create(Role::team($teams['team1']['$id'], 'admin')),
@@ -61,7 +61,7 @@ class DatabasesPermissionsTeamTest extends Scope
        $collection2 = $this->client->call(Client::METHOD_POST, '/vectordb/' . $this->databaseId . '/collections', $this->getServerHeader(), [
            'collectionId' => ID::custom('collection2'),
            'name' => 'Collection 2',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::read(Role::team($teams['team2']['$id'])),
                Permission::create(Role::team($teams['team2']['$id'], 'owner')),
@@ -48,7 +48,7 @@ class ACIDTest extends Scope
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'AtomicityTest',
-            'dimensions' => 3,
+            'dimension' => 3,
            'documentSecurity' => false,
            'permissions' => [
                Permission::create(Role::any()),
@@ -160,7 +160,7 @@ class ACIDTest extends Scope
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'ConsistencyTest',
-            'dimensions' => 3,
+            'dimension' => 3,
            'documentSecurity' => false,
            'permissions' => [
                Permission::create(Role::any()),
@@ -268,7 +268,7 @@ class ACIDTest extends Scope
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'IsolationTest',
-            'dimensions' => 3,
+            'dimension' => 3,
            'documentSecurity' => false,
            'permissions' => [
                Permission::create(Role::any()),
@@ -416,7 +416,7 @@ class ACIDTest extends Scope
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'DurabilityTest',
-            'dimensions' => 3,
+            'dimension' => 3,
            'documentSecurity' => false,
            'permissions' => [
                Permission::create(Role::any()),
@@ -128,7 +128,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TransactionOperationsTest',
-            'dimensions' => 3,
+            'dimension' => 3,
            'documentSecurity' => false,
            'permissions' => [
                Permission::create(Role::any()),
@@ -267,7 +267,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TransactionCommitTest',
-            'dimensions' => 3,
+            'dimension' => 3,
            'documentSecurity' => false,
            'permissions' => [
                Permission::create(Role::any()),
@@ -409,7 +409,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TransactionRollbackTest',
-            'dimensions' => 3,
+            'dimension' => 3,
            'documentSecurity' => false,
            'permissions' => [
                Permission::create(Role::any()),
@@ -489,7 +489,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::read(Role::any()),
                Permission::create(Role::any()),
@@ -575,7 +575,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [Permission::create(Role::any())],
        ]);

@@ -690,7 +690,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::read(Role::any()),
                Permission::create(Role::any()),
@@ -821,7 +821,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::read(Role::any()),
                Permission::create(Role::any()),
@@ -919,7 +919,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::read(Role::any()),
                Permission::create(Role::any()),
@@ -1079,7 +1079,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::read(Role::any()),
                Permission::create(Role::any()),
@@ -1220,7 +1220,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [Permission::create(Role::any())],
        ]);

@@ -1331,7 +1331,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::create(Role::any()),
                Permission::update(Role::any()),
@@ -1421,7 +1421,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'documentSecurity' => false,
            'permissions' => [
                Permission::create(Role::any()),
@@ -1515,7 +1515,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::create(Role::any()),
                Permission::read(Role::any()),
@@ -1624,7 +1624,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::create(Role::any()),
                Permission::read(Role::any()),
@@ -1733,7 +1733,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::create(Role::any()),
                Permission::read(Role::any()),
@@ -1829,7 +1829,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::create(Role::any()),
                Permission::read(Role::any()),
@@ -1959,7 +1959,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::create(Role::any()),
                Permission::read(Role::any()),
@@ -2064,7 +2064,7 @@ trait TransactionsBase
        ]), [
            'collectionId' => ID::unique(),
            'name' => 'TestCollection',
-            'dimensions' => 3,
+            'dimension' => 3,
            'permissions' => [
                Permission::create(Role::any()),
                Permission::read(Role::any()),
@@ -1406,7 +1406,7 @@ trait MigrationsBase
            ], [
                'collectionId' => ID::unique(),
                'name' => 'Vector CSV Import Collection',
-                'dimensions' => 3,
+                'dimension' => 3,
                'documentSecurity' => true,
            ]);

@@ -1527,7 +1527,7 @@ trait MigrationsBase
            ], [
                'collectionId' => ID::unique(),
                'name' => 'Vector CSV Export Collection',
-                'dimensions' => 3,
+                'dimension' => 3,
                'documentSecurity' => true,
            ]);

@@ -1761,7 +1761,7 @@ trait MigrationsBase
        ], [
            'collectionId' => ID::unique(),
            'name' => 'VDB - Movies',
-            'dimensions' => 3,
+            'dimension' => 3,
        ]);

        $this->assertEquals(201, $collection['headers']['status-code']);
@@ -2207,7 +2207,7 @@ trait MigrationsBase
        ], [
            'collectionId' => ID::unique(),
            'name' => 'Products',
-            'dimensions' => 3,
+            'dimension' => 3,
        ]);

        $this->assertEquals(201, $vectorCollection['headers']['status-code']);
@@ -4347,7 +4347,7 @@ class RealtimeCustomClientTest extends Scope
                Permission::create(Role::user($this->getUser()['$id'])),
            ],
            'documentSecurity' => true,
-            'dimensions' => 3,
+            'dimension' => 3,
        ]);

        $actorsId = $actors['body']['$id'];