feat: Add Neo4j Vector type support (#290)

Author: p123-stack

README.md

@@ -241,9 +241,12 @@ Cypher values and types map to these php types and classes:
 | Node           | `\Laudis\Neo4j\Types\Node`                    |
 | Relationship   | `\Laudis\Neo4j\Types\Relationship`            |
 | Path           | `\Laudis\Neo4j\Types\Path`                    |
+| Vector         | `\Laudis\Neo4j\Types\Vector` ***              |
 
 (*) These items can also be used as parameters in the bolt protocol and will automatically be converted by the driver, so they can be used in Cypher.
 
+(***) Vector (e.g. embedding) is only produced when decoding results from the server; it is not supported as a query parameter.
+
 Besides these examples, `\DateTimeInterface` will map to `DateTimeZoneId` in Cypher. An empty or list-type `array` will be converted to a cypher `List`, and an `associative array` will be converted to a `map`.
 
 (**) A point can be one of four types implementing PointInterface: `\Laudis\Neo4j\Types\CartesianPoint` `\Laudis\Neo4j\Types\Cartesian3DPoint` `\Laudis\Neo4j\Types\WGS84Point` `\Laudis\Neo4j\Types\WGS843DPoint`

src/Enum/VectorTypeMarker.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Neo4j PHP Client and Driver package.
+ *
+ * (c) Nagels <https://nagels.tech>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Laudis\Neo4j\Enum;
+
+/**
+ * Type marker for Neo4j Vector element encoding (Bolt structure semantics).
+ * Indicates how the vector payload is encoded (integer or float, and width).
+ *
+ * @see https://neo4j.com/docs/bolt/current/bolt/structure-semantics/#structure-vector
+ */
+enum VectorTypeMarker: int
+{
+    case INT_8 = 0xC8;
+    case INT_16 = 0xC9;
+    case INT_32 = 0xCA;
+    case INT_64 = 0xCB;
+    case FLOAT_32 = 0xC6;
+    case FLOAT_64 = 0xC1;
+}

src/Formatter/Specialised/BoltOGMTranslator.php

@@ -26,6 +26,8 @@
 use Bolt\protocol\v1\structures\Relationship as BoltRelationship;
 use Bolt\protocol\v1\structures\Time as BoltTime;
 use Bolt\protocol\v1\structures\UnboundRelationship as BoltUnboundRelationship;
+use Bolt\protocol\v6\structures\Vector as BoltVector;
+use Laudis\Neo4j\Enum\VectorTypeMarker;
 use Laudis\Neo4j\Formatter\SummarizedResultFormatter;
 use Laudis\Neo4j\Types\Abstract3DPoint;
 use Laudis\Neo4j\Types\AbstractPoint;
@@ -44,6 +46,7 @@
 use Laudis\Neo4j\Types\Relationship;
 use Laudis\Neo4j\Types\Time;
 use Laudis\Neo4j\Types\UnboundRelationship;
+use Laudis\Neo4j\Types\Vector;
 use Laudis\Neo4j\Types\WGS843DPoint;
 use Laudis\Neo4j\Types\WGS84Point;
 use UnexpectedValueException;
@@ -81,6 +84,7 @@ public function __construct()
             BoltPoint2D::class => $this->makeFromBoltPoint2D(...),
             BoltPoint3D::class => $this->makeFromBoltPoint3D(...),
             BoltDateTimeZoneId::class => $this->makeBoltTimezoneIdentifier(...),
+            BoltVector::class => $this->makeFromBoltVector(...),
             'array' => $this->mapArray(...),
             'int' => static fn (int $x): int => $x,
             'null' => static fn (): ?object => null,
@@ -268,6 +272,18 @@ private function makeFromBoltPoint3D(BoltPoint3D $x): Abstract3DPoint
         throw new UnexpectedValueException('An srid of '.$x->srid.' has been returned, which has not been implemented.');
     }
 
+    private function makeFromBoltVector(BoltVector $value): Vector
+    {
+        /** @psalm-suppress ImpureMethodCall Vector::decode() only reads protocol data but Psalm treats Bolt structures as potentially stateful */
+        $decoded = $value->decode();
+        // Cast to string then read first byte to avoid Bytes::offsetGet (ImpureMethodCall) and to satisfy Psalm that ord() never receives null
+        $bytesStr = (string) $value->type_marker;
+        $markerByte = $bytesStr !== '' ? ord($bytesStr[0]) : null;
+        $typeMarker = $markerByte !== null ? VectorTypeMarker::tryFrom($markerByte) : null;
+
+        return new Vector(array_values($decoded), $typeMarker);
+    }
+
     private function makeFromBoltPath(BoltPath $path): Path
     {
         $nodes = [];

src/Formatter/SummarizedResultFormatter.php

@@ -47,6 +47,7 @@
 use Laudis\Neo4j\Types\Path;
 use Laudis\Neo4j\Types\Relationship;
 use Laudis\Neo4j\Types\Time;
+use Laudis\Neo4j\Types\Vector;
 use Laudis\Neo4j\Types\WGS843DPoint;
 use Laudis\Neo4j\Types\WGS84Point;
 
@@ -55,7 +56,7 @@
 /**
  * Decorates the result of the provided format with an extensive summary.
  *
- * @psalm-type OGMTypes = string|int|float|bool|null|Date|DateTime|Duration|LocalDateTime|LocalTime|Time|Node|Relationship|Path|Cartesian3DPoint|CartesianPoint|WGS84Point|WGS843DPoint|DateTimeZoneId|CypherList<mixed>|CypherMap<mixed>
+ * @psalm-type OGMTypes = string|int|float|bool|null|Date|DateTime|Duration|LocalDateTime|LocalTime|Time|Node|Relationship|Path|Cartesian3DPoint|CartesianPoint|WGS84Point|WGS843DPoint|DateTimeZoneId|Vector|CypherList<mixed>|CypherMap<mixed>
  * @psalm-type OGMResults = CypherList<CypherMap<OGMTypes>>
  * @psalm-type CypherStats = array{
  *     nodes_created: int,

src/ParameterHelper.php

@@ -83,7 +83,8 @@ public static function asParameter(
         mixed $value,
         ConnectionProtocol $protocol,
     ): iterable|int|float|bool|string|stdClass|IStructure|null {
-        return self::cypherMapToStdClass($value) ??
+        return self::passThroughBoltStructure($value) ??
+            self::cypherMapToStdClass($value) ??
             self::emptySequenceToArray($value) ??
             self::convertBoltConvertibles($value) ??
             self::convertTemporalTypes($value, $protocol) ??
@@ -92,6 +93,15 @@ public static function asParameter(
             self::filterInvalidType($value);
     }
 
+    private static function passThroughBoltStructure(mixed $value): ?IStructure
+    {
+        if ($value instanceof IStructure) {
+            return $value;
+        }
+
+        return null;
+    }
+
     /**
      * @pure
      */

src/Types/Vector.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Neo4j PHP Client and Driver package.
+ *
+ * (c) Nagels <https://nagels.tech>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Laudis\Neo4j\Types;
+
+use Laudis\Neo4j\Enum\VectorTypeMarker;
+
+/**
+ * Neo4j Vector type (e.g. embedding). Holds a list of numbers.
+ *
+ * This type is only produced when decoding results from the server (Bolt). It is not supported
+ * as a query parameter; use a plain list of numbers if you need to pass vector-like data.
+ *
+ * @psalm-immutable
+ *
+ * @extends AbstractPropertyObject<list<int|float>, list<int|float>>
+ */
+final class Vector extends AbstractPropertyObject
+{
+    /**
+     * @param list<int|float>       $values
+     * @param VectorTypeMarker|null $typeMarker Bolt type marker (how values were encoded); set when received from server
+     */
+    public function __construct(
+        private readonly array $values,
+        private readonly ?VectorTypeMarker $typeMarker = null,
+    ) {
+    }
+
+    /**
+     * @return list<int|float>
+     */
+    public function getValues(): array
+    {
+        return $this->values;
+    }
+
+    /**
+     * Bolt type marker indicating how the vector payload is encoded (e.g. FLOAT_64, INT_32).
+     * Set when the vector was received from the server.
+     */
+    public function getTypeMarker(): ?VectorTypeMarker
+    {
+        return $this->typeMarker;
+    }
+
+    /**
+     * @return array{values: list<int|float>, typeMarker: string|null}
+     *
+     * @psalm-suppress ImplementedReturnTypeMismatch parent expects array<string, list<int|float>> but we add typeMarker (string|null) for clarity
+     */
+    public function toArray(): array
+    {
+        return [
+            'values' => $this->values,
+            'typeMarker' => $this->typeMarker?->name,
+        ];
+    }
+
+    public function getProperties(): CypherMap
+    {
+        return new CypherMap($this);
+    }
+}

testkit-backend/src/Responses/Types/CypherObject.php

@@ -22,6 +22,7 @@
 use Laudis\Neo4j\Types\Path;
 use Laudis\Neo4j\Types\Relationship;
 use Laudis\Neo4j\Types\UnboundRelationship;
+use Laudis\Neo4j\Types\Vector;
 use RuntimeException;
 
 /**
@@ -84,6 +85,14 @@ public static function autoDetect($value): TestkitResponseInterface
                     $tbr = new CypherObject('CypherMap', new CypherMap($map));
                 }
                 break;
+            case Vector::class:
+                /** @var Vector $value */
+                $list = [];
+                foreach ($value->getValues() as $item) {
+                    $list[] = self::autoDetect($item);
+                }
+                $tbr = new CypherObject('Vector', new CypherList($list));
+                break;
             case 'int':
                 $tbr = new CypherObject('CypherInt', $value);
                 break;