Added Vector query and Tag filter entities (#5)

* Added Vector query and Tag filter entities

* Fixed feature tests

* Added missing unit test

* Added part of feature tests

* Fixed unit test

* Added missing coverage

* Added more feature test coverage

Author: vladvildanov

src/Enum/Condition.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Vladvildanov\PredisVl\Enum;
+
+use Vladvildanov\PredisVl\Enum\Traits\EnumNames;
+
+enum Condition: string
+{
+    use EnumNames;
+
+    case equal = '==';
+    case notEqual = '!=';
+    case greaterThan = '>';
+    case lowerThan = '<';
+    case pattern = '%';
+}

src/Enum/Logical.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Vladvildanov\PredisVl\Enum;
+
+use Vladvildanov\PredisVl\Enum\Traits\EnumNames;
+
+enum Logical: string
+{
+    use EnumNames;
+
+    case and = '&&';
+    case or = '||';
+}

src/Factory.php

@@ -3,6 +3,7 @@
 namespace Vladvildanov\PredisVl;
 
 use Predis\Command\Argument\Search\CreateArguments;
+use Predis\Command\Argument\Search\SearchArguments;
 
 /**
  * Simple factory for general purpose objects creation.
@@ -16,4 +17,12 @@ public function createIndexBuilder(): CreateArguments
     {
         return new CreateArguments();
     }
+
+    /**
+     * @inheritDoc
+     */
+    public function createSearchBuilder(): SearchArguments
+    {
+        return new SearchArguments();
+    }
 }

src/FactoryInterface.php

@@ -3,6 +3,7 @@
 namespace Vladvildanov\PredisVl;
 
 use Predis\Command\Argument\Search\CreateArguments;
+use Predis\Command\Argument\Search\SearchArguments;
 
 interface FactoryInterface
 {
@@ -12,4 +13,11 @@ interface FactoryInterface
      * @return CreateArguments
      */
     public function createIndexBuilder(): CreateArguments;
+
+    /**
+     * Creates builder object for search command arguments.
+     *
+     * @return SearchArguments
+     */
+    public function createSearchBuilder(): SearchArguments;
 }

src/Index/IndexInterface.php

@@ -2,6 +2,8 @@
 
 namespace Vladvildanov\PredisVl\Index;
 
+use Vladvildanov\PredisVl\Query\QueryInterface;
+
 interface IndexInterface
 {
     /**
@@ -35,4 +37,12 @@ public function load(string $key, mixed $values): bool;
      * @return mixed
      */
     public function fetch(string $id): mixed;
+
+    /**
+     * Query for a data from current index.
+     *
+     * @param QueryInterface $query
+     * @return mixed
+     */
+    public function query(QueryInterface $query);
 }

src/Index/SearchIndex.php

@@ -10,6 +10,7 @@
 use Vladvildanov\PredisVl\Enum\StorageType;
 use Vladvildanov\PredisVl\Factory;
 use Vladvildanov\PredisVl\FactoryInterface;
+use Vladvildanov\PredisVl\Query\QueryInterface;
 
 class SearchIndex implements IndexInterface
 {
@@ -94,6 +95,10 @@ public function create(bool $isOverwrite = false): bool
      */
     public function load(string $key, mixed $values): bool
     {
+        $key = (array_key_exists('prefix', $this->schema['index']))
+            ? $this->schema['index']['prefix'] . $key
+            : $key;
+
         if (is_string($values)) {
             $response = $this->client->jsonset($key, '$', $values);
         } elseif (is_array($values)) {
@@ -122,6 +127,44 @@ public function fetch(string $id): mixed
         return $this->client->hgetall($key);
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function query(QueryInterface $query)
+    {
+        $response = $this->client->ftsearch(
+            $this->schema['index']['name'],
+            $query->getQueryString(),
+            $query->getSearchArguments()
+        );
+
+        $processedResponse = ['count' => $response[0]];
+        $withScores = in_array('WITHSCORES', $query->getSearchArguments()->toArray(), true);
+
+        if (count($response) > 1) {
+            for ($i = 1, $iMax = count($response); $i < $iMax; $i++) {
+                $processedResponse['results'][$response[$i]] = [];
+
+                // Different return type depends on WITHSCORE condition
+                if ($withScores) {
+                    $processedResponse['results'][$response[$i]]['score'] = $response[$i + 1];
+                    $step = 2;
+                } else {
+                    $step = 1;
+                }
+
+                for ($j = 0, $jMax = count($response[$i + $step]); $j < $jMax; $j++) {
+                    $processedResponse['results'][$response[$i]][$response[$i + $step][$j]] = $response[$i + $step][$j + 1];
+                    ++$j;
+                }
+
+                $i += $step;
+            }
+        }
+
+        return $processedResponse;
+    }
+
     /**
      * Validates schema array.
      *

src/Query/AbstractQuery.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace Vladvildanov\PredisVl\Query;
+
+use Predis\Command\Argument\Search\SearchArguments;
+use Vladvildanov\PredisVl\Factory;
+use Vladvildanov\PredisVl\FactoryInterface;
+use Vladvildanov\PredisVl\Query\Filter\FilterInterface;
+
+abstract class AbstractQuery implements QueryInterface
+{
+    /**
+     * @var FactoryInterface
+     */
+    protected FactoryInterface $factory;
+
+    /**
+     * @var array{first: int, limit: int}|null
+     */
+    protected ?array $pagination;
+
+    public function __construct(protected ?FilterInterface $filter = null, FactoryInterface $factory = null)
+    {
+        $this->factory = $factory ?? new Factory();
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getFilter(): FilterInterface
+    {
+        return $this->filter;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    abstract public function getSearchArguments(): SearchArguments;
+
+    /**
+     * @inheritDoc
+     */
+    abstract public function getQueryString(): string;
+
+    /**
+     * @inheritDoc
+     */
+    public function setPagination(int $first, int $limit): void
+    {
+        $this->pagination['first'] = $first;
+        $this->pagination['limit'] = $limit;
+    }
+}

src/Query/Filter/FilterInterface.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Vladvildanov\PredisVl\Query\Filter;
+
+use Vladvildanov\PredisVl\Enum\Condition;
+
+interface FilterInterface
+{
+    /**
+     * Creates field-based filter.
+     *
+     * @param string $fieldName
+     * @param Condition $condition
+     * @param mixed $value
+     */
+    public function __construct(string $fieldName, Condition $condition, mixed $value);
+
+    /**
+     * Returns expression-string representation of current filter.
+     *
+     * @return string
+     */
+    public function toExpression(): string;
+}

src/Query/Filter/TagFilter.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace Vladvildanov\PredisVl\Query\Filter;
+
+use JetBrains\PhpStorm\ArrayShape;
+use Vladvildanov\PredisVl\Enum\Condition;
+use Vladvildanov\PredisVl\Enum\Logical;
+
+class TagFilter implements FilterInterface
+{
+    /**
+     * Mappings according to Redis Query Syntax
+     *
+     * @link https://redis.io/docs/interact/search-and-query/advanced-concepts/query_syntax/
+     * @var array
+     */
+    private array $conditionMappings = [
+        '==' => '',
+        '!=' => '-'
+    ];
+
+    /**
+     * Creates tag filter based on condition.
+     * Value can be provided as a string (single tag) or as an array (multiple tags).
+     *
+     * @param string $fieldName
+     * @param Condition $condition
+     * @param string|array $value
+     */
+    public function __construct(
+        private readonly string    $fieldName,
+        private readonly Condition $condition,
+        #[ArrayShape([
+            'conjunction' => Logical::class,
+            'tags' => 'array',
+        ])] private $value
+    ) {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function toExpression(): string
+    {
+        $condition = $this->conditionMappings[$this->condition->value];
+
+        if (is_string($this->value)) {
+            return "{$condition}@{$this->fieldName}:{{$this->value}}";
+        }
+
+        if ($this->value['conjunction'] === Logical::or) {
+            $query = "{$condition}@{$this->fieldName}:{";
+
+            foreach ($this->value['tags'] as $tag) {
+                $query .= $tag . " | ";
+            }
+
+            return trim($query, '| ') . '}';
+        }
+
+        $query = '';
+
+        foreach ($this->value['tags'] as $tag) {
+            $query .= "{$condition}@{$this->fieldName}:{{$tag}} ";
+        }
+
+        return trim($query);
+    }
+}

src/Query/QueryInterface.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace Vladvildanov\PredisVl\Query;
+
+use Predis\Command\Argument\Search\SearchArguments;
+use Vladvildanov\PredisVl\Query\Filter\FilterInterface;
+
+interface QueryInterface
+{
+    /**
+     * Returns filter for current query.
+     *
+     * @return FilterInterface|null
+     */
+    public function getFilter(): ?FilterInterface;
+
+    /**
+     * Returns Predis search builder object.
+     *
+     * @return SearchArguments
+     */
+    public function getSearchArguments(): SearchArguments;
+
+    /**
+     * Returns generated query string.
+     *
+     * @return string
+     */
+    public function getQueryString(): string;
+
+    /**
+     * Set the paging parameters for the query to limit the results between first and num_results.
+     *
+     * @param int $first
+     * @param int $limit
+     * @return void
+     */
+    public function setPagination(int $first, int $limit): void;
+}