Object(json) attribute support for postgres

src/Database/Adapter.php

@@ -1056,6 +1056,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

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

src/Database/Adapter/Postgres.php

@@ -1562,6 +1562,64 @@ 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:
+                $conditions = [];
+                foreach ($query->getValues() as $key => $value) {
+                    if (is_array($value)) {
+                        // JSONB containment operator @>
+                        $binds[":{$placeholder}_{$key}"] = json_encode($value);
+                        $conditions[] = "{$alias}.{$attribute} @> :{$placeholder}_{$key}::jsonb";
+                    } else {
+                        // Direct equality
+                        $binds[":{$placeholder}_{$key}"] = json_encode($value);
+                        $conditions[] = "{$alias}.{$attribute} = :{$placeholder}_{$key}::jsonb";
+                    }
+                }
+                return empty($conditions) ? '' : '(' . implode(' OR ', $conditions) . ')';
+
+            case Query::TYPE_CONTAINS:
+                $conditions = [];
+                foreach ($query->getValues() as $key => $value) {
+                    if (is_array($value)) {
+                        // For JSONB contains, we need to check if an array contains a specific element
+                        // The JSONB containment operator @> checks if left contains right
+                        // For array element containment: {"array": ["element"]} means array contains "element"
+                        // For nested array containment: {"matrix": [[4,5,6]]} means matrix contains [4,5,6]
+
+                        if (count($value) === 1) {
+                            $jsonKey = array_key_first($value);
+                            $jsonValue = $value[$jsonKey];
+
+                            // Always wrap the value in an array to represent "array contains this element"
+                            // - For scalar: 'react' becomes ["react"]
+                            // - For array: [4,5,6] becomes [[4,5,6]]
+                            $value[$jsonKey] = [$jsonValue];
+                        }
+
+                        $binds[":{$placeholder}_{$key}"] = json_encode($value);
+                        $conditions[] = "{$alias}.{$attribute} @> :{$placeholder}_{$key}::jsonb";
+                    }
+                }
+                return empty($conditions) ? '' : '(' . implode(' OR ', $conditions) . ')';
+
+            default:
+                throw new DatabaseException('Query method ' . $query->getMethod() . ' not supported for object attributes');
+        }
+    }
+
     /**
      * Get SQL Condition
      *
@@ -1585,6 +1643,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:
@@ -1732,6 +1794,9 @@ protected function getSQLType(string $type, int $size, bool $signed = true, bool
             case Database::VAR_DATETIME:
                 return 'TIMESTAMP(3)';
 
+            case Database::TYPE_OBJECT:
+                return 'JSONB';
+
                 // in all other DB engines, 4326 is the default SRID
             case Database::VAR_POINT:
                 return 'GEOMETRY(POINT,' . Database::SRID . ')';
@@ -1743,7 +1808,7 @@ protected function getSQLType(string $type, int $size, bool $signed = true, bool
                 return 'GEOMETRY(POLYGON,' . Database::SRID . ')';
 
             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::TYPE_OBJECT . ', ' . Database::VAR_POINT . ', ' . Database::VAR_LINESTRING . ', ' . Database::VAR_POLYGON);
         }
     }
 
@@ -1951,6 +2016,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

@@ -1122,6 +1122,15 @@ public function getAttributeWidth(Document $collection): int
                     $total += 7;
                     break;
 
+                case Database::TYPE_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

@@ -973,6 +973,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

src/Database/Database.php

@@ -44,6 +44,7 @@ class Database
     public const VAR_DATETIME = 'datetime';
     public const VAR_ID = 'id';
     public const VAR_OBJECT_ID = 'objectId';
+    public const TYPE_OBJECT = 'object';
 
     public const INT_MAX = 2147483647;
     public const BIG_INT_MAX = PHP_INT_MAX;
@@ -1950,6 +1951,17 @@ private function validateAttribute(
             case self::VAR_DATETIME:
             case self::VAR_RELATIONSHIP:
                 break;
+            case self::TYPE_OBJECT:
+                if (!$this->adapter->getSupportForObject()) {
+                    throw new DatabaseException('Object attributes are not supported');
+                }
+                if (!empty($size)) {
+                    throw new DatabaseException('Size must be empty for object attributes');
+                }
+                if (!empty($array)) {
+                    throw new DatabaseException('Object attributes cannot be arrays');
+                }
+                break;
             case self::VAR_POINT:
             case self::VAR_LINESTRING:
             case self::VAR_POLYGON:
@@ -1965,7 +1977,7 @@ private function validateAttribute(
                 }
                 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 . ', ' . self::VAR_POINT . ', ' . self::VAR_LINESTRING . ', ' . self::VAR_POLYGON);
+                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 . ', ' . self::TYPE_OBJECT . ', ' . self::VAR_POINT . ', ' . self::VAR_LINESTRING . ', ' . self::VAR_POLYGON);
         }
 
         // Only execute when $default is given
@@ -2037,16 +2049,22 @@ protected function validateDefaultTypes(string $type, mixed $default): void
                     throw new DatabaseException('Default value ' . $default . ' does not match given type ' . $type);
                 }
                 break;
+            case self::TYPE_OBJECT:
+                // Object types expect arrays as default values
+                if ($defaultType !== 'array') {
+                    throw new DatabaseException('Default value for object type must be an array');
+                }
+                break;
             case self::VAR_POINT:
             case self::VAR_LINESTRING:
             case self::VAR_POLYGON:
                 // Spatial types expect arrays as default values
                 if ($defaultType !== 'array') {
                     throw new DatabaseException('Default value for spatial type ' . $type . ' must be an array');
                 }
-                // no break
+                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 . ', ' . self::VAR_POINT . ', ' . self::VAR_LINESTRING . ', ' . self::VAR_POLYGON);
+                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 . ', ' . self::TYPE_OBJECT . ', ' . self::VAR_POINT . ', ' . self::VAR_LINESTRING . ', ' . self::VAR_POLYGON);
         }
     }
 
@@ -2293,6 +2311,18 @@ public function updateAttribute(string $collection, string $id, ?string $type =
                     }
                     break;
 
+                case self::TYPE_OBJECT:
+                    if (!$this->adapter->getSupportForObject()) {
+                        throw new DatabaseException('Object attributes are not supported');
+                    }
+                    if (!empty($size)) {
+                        throw new DatabaseException('Size must be empty for object attributes');
+                    }
+                    if (!empty($array)) {
+                        throw new DatabaseException('Object attributes cannot be arrays');
+                    }
+                    break;
+
                 case self::VAR_POINT:
                 case self::VAR_LINESTRING:
                 case self::VAR_POLYGON:
@@ -2307,7 +2337,7 @@ public function updateAttribute(string $collection, string $id, ?string $type =
                     }
                     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);
+                    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 . ', ' . self::TYPE_OBJECT);
             }
 
             /** Ensure required filters for the attribute are passed */
@@ -7287,6 +7317,12 @@ public function casting(Document $collection, Document $document): Document
                     case self::VAR_FLOAT:
                         $node = (float)$node;
                         break;
+                    case self::TYPE_OBJECT:
+                        // Decode JSONB string to array
+                        if (is_string($node)) {
+                            $node = json_decode($node, true);
+                        }
+                        break;
                     default:
                         break;
                 }

src/Database/Query.php

@@ -960,6 +960,14 @@ public function isSpatialAttribute(): bool
         return in_array($this->attributeType, Database::SPATIAL_TYPES);
     }
 
+    /**
+     * @return bool
+     */
+    public function isObjectAttribute(): bool
+    {
+        return $this->attributeType === Database::TYPE_OBJECT;
+    }
+
     // Spatial query methods
 
     /**

src/Database/Validator/Query/Filter.php

@@ -147,6 +147,15 @@ protected function isValidAttributeAndValues(string $attribute, array $values, s
                     $validator = new Text(255, 0); // The query is always on uid
                     break;
 
+                case Database::TYPE_OBJECT:
+                    // For JSONB/object queries, value must be an array
+                    if (!is_array($value)) {
+                        $this->message = 'Query value for object type must be an array';
+                        return false;
+                    }
+                    // No further validation needed - JSONB accepts any valid array structure
+                    continue 2;
+
                 case Database::VAR_POINT:
                 case Database::VAR_LINESTRING:
                 case Database::VAR_POLYGON:
@@ -201,10 +210,11 @@ protected function isValidAttributeAndValues(string $attribute, array $values, s
             !$array &&
             in_array($method, [Query::TYPE_CONTAINS, Query::TYPE_NOT_CONTAINS]) &&
             $attributeSchema['type'] !== Database::VAR_STRING &&
+            $attributeSchema['type'] !== Database::TYPE_OBJECT &&
             !in_array($attributeSchema['type'], Database::SPATIAL_TYPES)
         ) {
             $queryType = $method === Query::TYPE_NOT_CONTAINS ? 'notContains' : 'contains';
-            $this->message = 'Cannot query ' . $queryType . ' on attribute "' . $attribute . '" because it is not an array or string.';
+            $this->message = 'Cannot query ' . $queryType . ' on attribute "' . $attribute . '" because it is not an array, string, or object.';
             return false;
         }
 

src/Database/Validator/Structure.php

@@ -350,6 +350,15 @@ protected function checkForInvalidAttributeValues(array $structure, array $keys)
                     );
                     break;
 
+                case Database::TYPE_OBJECT:
+                    // For JSONB/object types, just validate it's an array (associative or list)
+                    if (!is_array($value)) {
+                        $this->message = 'Attribute "'.$key.'" has invalid type. Value must be an array for object type';
+                        return false;
+                    }
+                    // No additional validators needed - JSONB accepts any valid array structure
+                    continue 2; // Skip to next attribute
+
                 case Database::VAR_POINT:
                 case Database::VAR_LINESTRING:
                 case Database::VAR_POLYGON:

tests/e2e/Adapter/Scopes/AttributeTests.php

@@ -1523,7 +1523,7 @@ public function testArrayAttribute(): void
                 ]);
                 $this->fail('Failed to throw exception');
             } catch (Throwable $e) {
-                $this->assertEquals('Invalid query: Cannot query contains on attribute "age" because it is not an array or string.', $e->getMessage());
+                $this->assertEquals('Invalid query: Cannot query contains on attribute "age" because it is not an array, string, or object.', $e->getMessage());
             }
 
             $documents = $database->find($collection, [