PCBC-1070: SDK Support for Hybrid Search Score Fusion

Couchbase/SearchOptions.php

@@ -20,6 +20,7 @@
 
 namespace Couchbase;
 
+use Couchbase\Exception\InvalidArgumentException;
 use JsonSerializable;
 
 class SearchOptions implements JsonSerializable
@@ -29,6 +30,7 @@ class SearchOptions implements JsonSerializable
     private ?int $skip = null;
     private ?bool $explain = null;
     private ?bool $disableScoring = null;
+    private ?SearchScoring $scoring = null;
     private ?MutationState $consistentWith = null;
     private ?array $fields = null;
     private ?array $facets = null;
@@ -113,13 +115,46 @@ public function explain(bool $explain): SearchOptions
      *
      * @return SearchOptions
      * @since 4.0.0
+     *
+     * @deprecated Use scoring(new SearchScoringNone()) instead.
+     *
+     * @throws InvalidArgumentException if $disabled is true and scoring() has already been set:
+     *   both would write the same field, so they cannot be used together.
      */
     public function disableScoring(bool $disabled): SearchOptions
     {
+        if ($disabled && $this->scoring !== null) {
+            throw new InvalidArgumentException("disableScoring(true) cannot be used together with scoring()");
+        }
         $this->disableScoring = $disabled;
         return $this;
     }
 
+    /**
+     * Selects how the server scores the hits, and how it merges the FTS and vector result sets
+     * of a hybrid request into a single ranked list.
+     *
+     * @param SearchScoring $scoring the scoring mode
+     *
+     * @return SearchOptions
+     * @since 4.6.0
+     *
+     * @see \SearchScoringNone
+     * @see \SearchScoringReciprocalRankFusion
+     * @see \SearchScoringRelativeScoreFusion
+     *
+     * @throws InvalidArgumentException if disableScoring(true) has already been set: both would
+     *   write the same field, so they cannot be used together.
+     */
+    public function scoring(SearchScoring $scoring): SearchOptions
+    {
+        if ($this->disableScoring === true) {
+            throw new InvalidArgumentException("scoring() cannot be used together with disableScoring(true)");
+        }
+        $this->scoring = $scoring;
+        return $this;
+    }
+
     /**
      * Sets the consistency to consider for this FTS query to AT_PLUS and
      * uses the MutationState to parameterize the consistency.
@@ -334,6 +369,7 @@ public static function export(?SearchOptions $options): array
             'skip' => $options->skip,
             'explain' => $options->explain,
             'disableScoring' => $options->disableScoring,
+            'scoring' => $options->scoring?->export(),
             'fields' => $options->fields,
             'sortSpecs' => $sort,
             'consistentWith' => $options->consistentWith == null ? null : $options->consistentWith->export(),

Couchbase/SearchScoring.php

@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * Copyright 2014-Present Couchbase, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Couchbase;
+
+/**
+ * Common interface for the scoring mode of a search query.
+ *
+ * @see \SearchOptions::scoring()
+ * @see \SearchScoringNone
+ * @see \SearchScoringReciprocalRankFusion
+ * @see \SearchScoringRelativeScoreFusion
+ *
+ * @since 4.6.0
+ */
+interface SearchScoring
+{
+    /**
+     * @internal
+     */
+    public function export(): array;
+}

Couchbase/SearchScoringNone.php

@@ -0,0 +1,64 @@
+<?php
+
+/**
+ * Copyright 2014-Present Couchbase, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Couchbase;
+
+use JsonSerializable;
+
+/**
+ * Disables scoring, so that the server does not perform any scoring on the hits.
+ *
+ * This sends the same "none" that the deprecated SearchOptions::disableScoring() sends. It is
+ * not a fusion strategy: "none" predates score fusion, so it works on older server versions.
+ *
+ * @since 4.6.0
+ */
+class SearchScoringNone implements JsonSerializable, SearchScoring
+{
+    /**
+     * Static helper to keep code more readable
+     *
+     * @return SearchScoringNone
+     * @since 4.6.0
+     */
+    public static function build(): SearchScoringNone
+    {
+        return new SearchScoringNone();
+    }
+
+    /**
+     * @internal
+     * @return mixed
+     */
+    public function jsonSerialize(): mixed
+    {
+        return $this->export();
+    }
+
+    /**
+     * @internal
+     */
+    public function export(): array
+    {
+        return [
+            'strategy' => 'none',
+        ];
+    }
+}

Couchbase/SearchScoringReciprocalRankFusion.php

@@ -0,0 +1,111 @@
+<?php
+
+/**
+ * Copyright 2014-Present Couchbase, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Couchbase;
+
+use JsonSerializable;
+
+/**
+ * Merges the FTS and vector result sets by rank rather than by raw score.
+ *
+ * It works well with the server defaults, and is the recommended strategy.
+ *
+ * Note: available from Couchbase Server 8.1.
+ *
+ * @since 4.6.0
+ *
+ * @UNCOMMITTED: This API may change in the future.
+ */
+class SearchScoringReciprocalRankFusion implements JsonSerializable, SearchScoring
+{
+    private ?int $rankConstant = null;
+    private ?int $windowSize = null;
+
+    /**
+     * Static helper to keep code more readable
+     *
+     * @return SearchScoringReciprocalRankFusion
+     * @since 4.6.0
+     *
+     * @UNCOMMITTED: This API may change in the future.
+     */
+    public static function build(): SearchScoringReciprocalRankFusion
+    {
+        return new SearchScoringReciprocalRankFusion();
+    }
+
+    /**
+     * Sets the rank constant of the Reciprocal Rank Fusion formula.
+     *
+     * @param int $rankConstant the rank constant
+     *
+     * @return SearchScoringReciprocalRankFusion
+     * @since 4.6.0
+     *
+     * @UNCOMMITTED: This API may change in the future.
+     */
+    public function rankConstant(int $rankConstant): SearchScoringReciprocalRankFusion
+    {
+        $this->rankConstant = $rankConstant;
+        return $this;
+    }
+
+    /**
+     * Sets how many results per list are considered for fusion.
+     *
+     * @param int $windowSize the window size
+     *
+     * @return SearchScoringReciprocalRankFusion
+     * @since 4.6.0
+     *
+     * @UNCOMMITTED: This API may change in the future.
+     */
+    public function windowSize(int $windowSize): SearchScoringReciprocalRankFusion
+    {
+        $this->windowSize = $windowSize;
+        return $this;
+    }
+
+    /**
+     * @internal
+     * @return mixed
+     */
+    public function jsonSerialize(): mixed
+    {
+        return $this->export();
+    }
+
+    /**
+     * @internal
+     */
+    public function export(): array
+    {
+        $json = [
+            'strategy' => 'rrf',
+        ];
+        if ($this->rankConstant !== null) {
+            $json['rankConstant'] = $this->rankConstant;
+        }
+        if ($this->windowSize !== null) {
+            $json['windowSize'] = $this->windowSize;
+        }
+        return $json;
+    }
+}

Couchbase/SearchScoringRelativeScoreFusion.php

@@ -0,0 +1,91 @@
+<?php
+
+/**
+ * Copyright 2014-Present Couchbase, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Couchbase;
+
+use JsonSerializable;
+
+/**
+ * Merges the FTS and vector result sets by normalized score rather than by rank.
+ *
+ * Note: available from Couchbase Server 8.1. Setting it makes the SDK check for the score
+ * fusion cluster capability, and fail the operation with a FeatureNotAvailableException if the
+ * cluster does not advertise it.
+ *
+ * @since 4.6.0
+ *
+ * @UNCOMMITTED: This API may change in the future.
+ */
+class SearchScoringRelativeScoreFusion implements JsonSerializable, SearchScoring
+{
+    private ?int $windowSize = null;
+
+    /**
+     * Static helper to keep code more readable
+     *
+     * @return SearchScoringRelativeScoreFusion
+     * @since 4.6.0
+     *
+     * @UNCOMMITTED: This API may change in the future.
+     */
+    public static function build(): SearchScoringRelativeScoreFusion
+    {
+        return new SearchScoringRelativeScoreFusion();
+    }
+
+    /**
+     * Sets how many results per list are considered for fusion.
+     *
+     * @param int $windowSize the window size
+     *
+     * @return SearchScoringRelativeScoreFusion
+     * @since 4.6.0
+     *
+     * @UNCOMMITTED: This API may change in the future.
+     */
+    public function windowSize(int $windowSize): SearchScoringRelativeScoreFusion
+    {
+        $this->windowSize = $windowSize;
+        return $this;
+    }
+
+    /**
+     * @internal
+     * @return mixed
+     */
+    public function jsonSerialize(): mixed
+    {
+        return $this->export();
+    }
+
+    /**
+     * @internal
+     */
+    public function export(): array
+    {
+        $json = [
+            'strategy' => 'rsf',
+        ];
+        if ($this->windowSize !== null) {
+            $json['windowSize'] = $this->windowSize;
+        }
+        return $json;
+    }
+}