3.x

src/Database/Adapter.php

@@ -1072,6 +1072,13 @@ abstract public function getSupportForBatchCreateAttributes(): bool;
      */
     abstract public function getSupportForSpatialAttributes(): bool;
 
+    /**
+     * Are object (JSON) attributes supported?
+     *
+     * @return bool
+     */
+    abstract public function getSupportForObject(): bool;
+
     /**
      * Does the adapter support null values in spatial indexes?
      *

src/Database/Adapter/MariaDB.php

@@ -2135,6 +2135,11 @@ public function getSupportForSpatialAttributes(): bool
         return true;
     }
 
+    public function getSupportForObject(): bool
+    {
+        return false;
+    }
+
     /**
      * Get Support for Null Values in Spatial Indexes
      *

src/Database/Adapter/Mongo.php

@@ -2790,6 +2790,11 @@ public function getSupportForBatchCreateAttributes(): bool
         return true;
     }
 
+    public function getSupportForObject(): bool
+    {
+        return false;
+    }
+
     /**
      * Get current attribute count from collection document
      *

src/Database/Adapter/Pool.php

@@ -585,6 +585,11 @@ public function decodePolygon(string $wkb): array
         return $this->delegate(__FUNCTION__, \func_get_args());
     }
 
+    public function getSupportForObject(): bool
+    {
+        return $this->delegate(__FUNCTION__, \func_get_args());
+    }
+
     public function castingBefore(Document $collection, Document $document): Document
     {
         return $this->delegate(__FUNCTION__, \func_get_args());

src/Database/Adapter/Postgres.php

@@ -889,7 +889,8 @@ public function createIndex(string $collection, string $id, string $type, array
             Database::INDEX_HNSW_COSINE,
             Database::INDEX_HNSW_DOT => 'INDEX',
             Database::INDEX_UNIQUE => 'UNIQUE INDEX',
-            default => throw new DatabaseException('Unknown index type: ' . $type . '. Must be one of ' . Database::INDEX_KEY . ', ' . Database::INDEX_UNIQUE . ', ' . Database::INDEX_FULLTEXT . ', ' . Database::INDEX_SPATIAL . ', ' . Database::INDEX_HNSW_EUCLIDEAN . ', ' . Database::INDEX_HNSW_COSINE . ', ' . Database::INDEX_HNSW_DOT),
+            Database::INDEX_OBJECT => 'INDEX',
+            default => throw new DatabaseException('Unknown index type: ' . $type . '. Must be one of ' . Database::INDEX_KEY . ', ' . Database::INDEX_UNIQUE . ', ' . Database::INDEX_FULLTEXT . ', ' . Database::INDEX_SPATIAL . ', ' . Database::INDEX_OBJECT . ', ' . Database::INDEX_HNSW_EUCLIDEAN . ', ' . Database::INDEX_HNSW_COSINE . ', ' . Database::INDEX_HNSW_DOT),
         };
 
         $key = "\"{$this->getNamespace()}_{$this->tenant}_{$collection}_{$id}\"";
@@ -908,6 +909,7 @@ public function createIndex(string $collection, string $id, string $type, array
             Database::INDEX_HNSW_EUCLIDEAN => " USING HNSW ({$attributes} vector_l2_ops)",
             Database::INDEX_HNSW_COSINE => " USING HNSW ({$attributes} vector_cosine_ops)",
             Database::INDEX_HNSW_DOT => " USING HNSW ({$attributes} vector_ip_ops)",
+            Database::INDEX_OBJECT => " USING GIN ({$attributes})",
             default => " ({$attributes})",
         };
 
@@ -1656,6 +1658,62 @@ protected function handleSpatialQueries(Query $query, array &$binds, string $att
         }
     }
 
+    /**
+     * Handle JSONB queries
+     *
+     * @param Query $query
+     * @param array<string, mixed> $binds
+     * @param string $attribute
+     * @param string $alias
+     * @param string $placeholder
+     * @return string
+     */
+    protected function handleObjectQueries(Query $query, array &$binds, string $attribute, string $alias, string $placeholder): string
+    {
+        switch ($query->getMethod()) {
+            case Query::TYPE_EQUAL:
+            case Query::TYPE_NOT_EQUAL: {
+                $isNot = $query->getMethod() === Query::TYPE_NOT_EQUAL;
+                $conditions = [];
+                foreach ($query->getValues() as $key => $value) {
+                    $binds[":{$placeholder}_{$key}"] = json_encode($value);
+                    $fragment = "{$alias}.{$attribute} @> :{$placeholder}_{$key}::jsonb";
+                    $conditions[] = $isNot ? "NOT (" . $fragment . ")" : $fragment;
+                }
+                $separator = $isNot ? ' AND ' : ' OR ';
+                return empty($conditions) ? '' : '(' . implode($separator, $conditions) . ')';
+            }
+
+            case Query::TYPE_CONTAINS:
+            case Query::TYPE_NOT_CONTAINS: {
+                $isNot = $query->getMethod() === Query::TYPE_NOT_CONTAINS;
+                $conditions = [];
+                foreach ($query->getValues() as $key => $value) {
+                    if (count($value) === 1) {
+                        $jsonKey = array_key_first($value);
+                        $jsonValue = $value[$jsonKey];
+
+                        // If scalar (e.g. "skills" => "typescript"),
+                        // wrap it to express array containment: {"skills": ["typescript"]}
+                        // If it's already an object/associative array (e.g. "config" => ["lang" => "en"]),
+                        // keep as-is to express object containment.
+                        if (!\is_array($jsonValue)) {
+                            $value[$jsonKey] = [$jsonValue];
+                        }
+                    }
+                    $binds[":{$placeholder}_{$key}"] = json_encode($value);
+                    $fragment = "{$alias}.{$attribute} @> :{$placeholder}_{$key}::jsonb";
+                    $conditions[] = $isNot ? "NOT (" . $fragment . ")" : $fragment;
+                }
+                $separator = $isNot ? ' AND ' : ' OR ';
+                return empty($conditions) ? '' : '(' . implode($separator, $conditions) . ')';
+            }
+
+            default:
+                throw new DatabaseException('Query method ' . $query->getMethod() . ' not supported for object attributes');
+        }
+    }
+
     /**
      * Get SQL Condition
      *
@@ -1679,6 +1737,10 @@ protected function getSQLCondition(Query $query, array &$binds): string
             return $this->handleSpatialQueries($query, $binds, $attribute, $alias, $placeholder);
         }
 
+        if ($query->isObjectAttribute()) {
+            return $this->handleObjectQueries($query, $binds, $attribute, $alias, $placeholder);
+        }
+
         switch ($query->getMethod()) {
             case Query::TYPE_OR:
             case Query::TYPE_AND:
@@ -1860,6 +1922,9 @@ protected function getSQLType(string $type, int $size, bool $signed = true, bool
             case Database::VAR_DATETIME:
                 return 'TIMESTAMP(3)';
 
+            case Database::VAR_OBJECT:
+                return 'JSONB';
+
             case Database::VAR_POINT:
                 return 'GEOMETRY(POINT,' . Database::DEFAULT_SRID . ')';
 
@@ -1873,7 +1938,7 @@ protected function getSQLType(string $type, int $size, bool $signed = true, bool
                 return "VECTOR({$size})";
 
             default:
-                throw new DatabaseException('Unknown Type: ' . $type . '. Must be one of ' . Database::VAR_STRING . ', ' . Database::VAR_INTEGER .  ', ' . Database::VAR_FLOAT . ', ' . Database::VAR_BOOLEAN . ', ' . Database::VAR_DATETIME . ', ' . Database::VAR_RELATIONSHIP . ', ' . Database::VAR_POINT . ', ' . Database::VAR_LINESTRING . ', ' . Database::VAR_POLYGON);
+                throw new DatabaseException('Unknown Type: ' . $type . '. Must be one of ' . Database::VAR_STRING . ', ' . Database::VAR_INTEGER .  ', ' . Database::VAR_FLOAT . ', ' . Database::VAR_BOOLEAN . ', ' . Database::VAR_DATETIME . ', ' . Database::VAR_RELATIONSHIP . ', ' . Database::VAR_OBJECT . ', ' . Database::VAR_POINT . ', ' . Database::VAR_LINESTRING . ', ' . Database::VAR_POLYGON);
         }
     }
 
@@ -2106,6 +2171,16 @@ public function getSupportForSpatialAttributes(): bool
         return true;
     }
 
+    /**
+     * Are object (JSONB) attributes supported?
+     *
+     * @return bool
+    */
+    public function getSupportForObject(): bool
+    {
+        return true;
+    }
+
     /**
      * Does the adapter support null values in spatial indexes?
      *

src/Database/Adapter/SQL.php

@@ -1175,6 +1175,15 @@ public function getAttributeWidth(Document $collection): int
                     $total += 7;
                     break;
 
+                case Database::VAR_OBJECT:
+                    /**
+                     * JSONB/JSON type
+                     * Only the pointer contributes 20 bytes to the row size
+                     * Data is stored externally
+                     */
+                    $total += 20;
+                    break;
+
                 case Database::VAR_POINT:
                     $total += $this->getMaxPointSize();
                     break;

src/Database/Adapter/SQLite.php

@@ -1008,6 +1008,11 @@ public function getSupportForSpatialAttributes(): bool
         return false; // SQLite doesn't have native spatial support
     }
 
+    public function getSupportForObject(): bool
+    {
+        return false;
+    }
+
     public function getSupportForSpatialIndexNull(): bool
     {
         return false; // SQLite doesn't have native spatial support