PCBC-970 SDK Support for Scoped Search Indexes

Couchbase/Cluster.php

@@ -170,6 +170,21 @@ public function searchQuery(string $indexName, SearchQuery $query, SearchOptions
         return new SearchResult($result);
     }
 
+    /**
+     * Executes a search query against the full text search services.
+     *
+     * This can be used to perform a traditional FTS query, and/or a vector search.
+     *
+     * @param string $indexName the cluster-level FTS index to use for the search request
+     * @param SearchRequest $request The search request to run
+     * @param SearchOptions|null $options The options to use when executing the search request
+     *
+     * @return SearchResult
+     * @throws InvalidArgumentException
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
     public function search(string $indexName, SearchRequest $request, SearchOptions $options = null): SearchResult
     {
         $exportedRequest = SearchRequest::export($request);

Couchbase/Management/ScopeSearchIndexManager.php

@@ -0,0 +1,230 @@
+<?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\Management;
+
+use Couchbase\Extension;
+
+class ScopeSearchIndexManager implements ScopeSearchIndexManagerInterface
+{
+    private $core;
+    private string $bucketName;
+    private string $scopeName;
+
+    public function __construct($core, string $bucketName, string $scopeName)
+    {
+        $this->core = $core;
+        $this->bucketName = $bucketName;
+        $this->scopeName = $scopeName;
+    }
+
+    /**
+     * Fetches scope-level index with the specified name from the server
+     *
+     * @param string $indexName
+     * @param GetSearchIndexOptions|null $options
+     * @return SearchIndex
+     *
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
+    public function getIndex(string $indexName, GetSearchIndexOptions $options = null): SearchIndex
+    {
+        $result = Extension\scopeSearchIndexGet($this->core, $this->bucketName, $this->scopeName, $indexName, GetSearchIndexOptions::export($options));
+
+        return SearchIndex::import($result);
+    }
+
+    /**
+     * Fetches all scope-level indexes from the server
+     *
+     * @param GetAllSearchIndexesOptions|null $options
+     * @return array
+     *
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
+    public function getAllIndexes(GetAllSearchIndexesOptions $options = null): array
+    {
+        $result = Extension\scopeSearchIndexGetAll($this->core, $this->bucketName, $this->scopeName, GetAllSearchIndexesOptions::export($options));
+        $indexes = [];
+        foreach ($result as $index) {
+            $indexes[] = SearchIndex::import($index);
+        }
+        return $indexes;
+    }
+
+    /**
+     * Upserts scope-level index to the server
+     *
+     * @param SearchIndex $indexDefinition
+     * @param UpsertSearchIndexOptions|null $options
+     *
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
+    public function upsertIndex(SearchIndex $indexDefinition, UpsertSearchIndexOptions $options = null)
+    {
+        Extension\scopeSearchIndexUpsert($this->core, $this->bucketName, $this->scopeName, SearchIndex::export($indexDefinition), UpsertSearchIndexOptions::export($options));
+    }
+
+    /**
+     * Drops a scope-level index from the server
+     *
+     * @param string $name
+     * @param DropSearchIndexOptions|null $options
+     *
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
+    public function dropIndex(string $name, DropSearchIndexOptions $options = null)
+    {
+        Extension\scopeSearchIndexDrop($this->core, $this->bucketName, $this->scopeName, $name, DropSearchIndexOptions::export($options));
+    }
+
+    /**
+     * Retrieves the number of documents that have been indexed for the scope-level index
+     *
+     * @param string $indexName
+     * @param GetIndexedSearchIndexOptions|null $options
+     *
+     * @return int
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
+    public function getIndexedDocumentsCount(string $indexName, GetIndexedSearchIndexOptions $options = null): int
+    {
+        $result = Extension\scopeSearchIndexGetDocumentsCount($this->core, $this->bucketName, $this->scopeName, $indexName, GetIndexedSearchIndexOptions::export($options));
+        return $result['count'];
+    }
+
+    /**
+     * Pauses updates and maintenance for the scope-level index
+     *
+     * @param string $indexName
+     * @param PauseIngestSearchIndexOptions|null $options
+     *
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
+    public function pauseIngest(string $indexName, PauseIngestSearchIndexOptions $options = null)
+    {
+        Extension\scopeSearchIndexIngestPause($this->core, $this->bucketName, $this->scopeName, $indexName, PauseIngestSearchIndexOptions::export($options));
+    }
+
+    /**
+     * Resumes updates and maintenance for the scope-level index
+     *
+     * @param string $indexName
+     * @param ResumeIngestSearchIndexOptions|null $options
+     *
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
+    public function resumeIngest(string $indexName, ResumeIngestSearchIndexOptions $options = null)
+    {
+        Extension\scopeSearchIndexIngestResume($this->core, $this->bucketName, $this->scopeName, $indexName, ResumeIngestSearchIndexOptions::export($options));
+    }
+
+    /**
+     * Allows querying against the scope-level index
+     *
+     * @param string $indexName
+     * @param AllowQueryingSearchIndexOptions|null $options
+     *
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
+    public function allowQuerying(string $indexName, AllowQueryingSearchIndexOptions $options = null)
+    {
+        Extension\scopeSearchIndexQueryingAllow($this->core, $this->bucketName, $this->scopeName, $indexName, AllowQueryingSearchIndexOptions::export($options));
+    }
+
+    /**
+     * Disallows querying against the scope-level index
+     *
+     * @param string $indexName
+     * @param DisallowQueryingSearchIndexOptions|null $options
+     *
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
+    public function disallowQuerying(string $indexName, DisallowQueryingSearchIndexOptions $options = null)
+    {
+        Extension\scopeSearchIndexQueryingDisallow($this->core, $this->bucketName, $this->scopeName, $indexName, DisallowQueryingSearchIndexOptions::export($options));
+    }
+
+    /**
+     * Freezes the assigment of scope-level index partitions to nodes
+     *
+     * @param string $indexName
+     * @param FreezePlanSearchIndexOptions|null $options
+     *
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
+    public function freezePlan(string $indexName, FreezePlanSearchIndexOptions $options = null)
+    {
+        Extension\scopeSearchIndexPlanFreeze($this->core, $this->bucketName, $this->scopeName, $indexName, FreezePlanSearchIndexOptions::export($options));
+    }
+
+    /**
+     * Unfreezes the assignment of index partitions to nodes
+     *
+     * @param string $indexName
+     * @param UnfreezePlanSearchIndexOptions|null $options
+     *
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
+    public function unfreezePlan(string $indexName, UnfreezePlanSearchIndexOptions $options = null)
+    {
+        Extension\scopeSearchIndexPlanUnfreeze($this->core, $this->bucketName, $this->scopeName, $indexName, UnfreezePlanSearchIndexOptions::export($options));
+    }
+
+    /**
+     * Fetches the analysis of a document against a specific scope-level index
+     *
+     * @param string $indexName
+     * @param $document
+     * @param AnalyzeDocumentOptions|null $options
+     *
+     * @return array
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
+    public function analyzeDocument(string $indexName, $document, AnalyzeDocumentOptions $options = null): array
+    {
+        $result = Extension\scopeSearchIndexDocumentAnalyze($this->core, $this->bucketName, $this->scopeName, $indexName, json_encode($document), AnalyzeDocumentOptions::export($options));
+        return json_decode($result["analysis"], true);
+    }
+}

Couchbase/Management/ScopeSearchIndexManagerInterface.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Couchbase\Management;
+
+interface ScopeSearchIndexManagerInterface
+{
+    public function getIndex(string $indexName, GetSearchIndexOptions $options = null): SearchIndex;
+
+    public function getAllIndexes(GetAllSearchIndexesOptions $options = null): array;
+
+    public function upsertIndex(SearchIndex $indexDefinition, UpsertSearchIndexOptions $options = null);
+
+    public function dropIndex(string $name, DropSearchIndexOptions $options = null);
+
+    public function getIndexedDocumentsCount(string $indexName, GetIndexedSearchIndexOptions $options = null): int;
+
+    public function pauseIngest(string $indexName, PauseIngestSearchIndexOptions $options = null);
+
+    public function resumeIngest(string $indexName, ResumeIngestSearchIndexOptions $options = null);
+
+    public function allowQuerying(string $indexName, AllowQueryingSearchIndexOptions $options = null);
+
+    public function disallowQuerying(string $indexName, DisallowQueryingSearchIndexOptions $options = null);
+
+    public function freezePlan(string $indexName, FreezePlanSearchIndexOptions $options = null);
+
+    public function unfreezePlan(string $indexName, UnfreezePlanSearchIndexOptions $options = null);
+
+    public function analyzeDocument(string $indexName, $document, AnalyzeDocumentOptions $options = null): array;
+}

Couchbase/Scope.php

@@ -21,7 +21,10 @@
 namespace Couchbase;
 
 use Couchbase\Exception\CouchbaseException;
+use Couchbase\Exception\InvalidArgumentException;
 use Couchbase\Exception\TimeoutException;
+use Couchbase\Management\ScopeSearchIndexManager;
+use Couchbase\Management\ScopeSearchIndexManagerInterface;
 
 /**
  * Scope is an object for providing access to collections.
@@ -110,4 +113,54 @@ public function analyticsQuery(string $statement, AnalyticsOptions $options = nu
 
         return new AnalyticsResult($result, AnalyticsOptions::getTranscoder($options));
     }
+
+    /**
+     * Executes a search query against the full text search services.
+     *
+     * This can be used to perform a traditional FTS query, and/or a vector search.
+     *
+     * @param string $indexName the scope-level fts index to use for the search request
+     * @param SearchRequest $request The search request to run
+     * @param SearchOptions|null $options The options to use when executing the search request
+     *
+     * @return SearchResult
+     * @throws InvalidArgumentException
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
+    public function search(string $indexName, SearchRequest $request, SearchOptions $options = null): SearchResult
+    {
+        $exportedRequest = SearchRequest::export($request);
+        $exportedOptions = SearchOptions::export($options);
+
+        $exportedOptions['bucketName'] = $this->bucketName;
+        $exportedOptions['scopeName'] = $this->name;
+
+        $exportedOptions["showRequest"] = false;
+        $query = $exportedRequest['searchQuery'];
+
+        if (!$exportedRequest['vectorSearch']) {
+            $result = Extension\searchQuery($this->core, $indexName, json_encode($query), $exportedOptions);
+            return new SearchResult($result);
+        }
+
+        $vectorSearch = $exportedRequest['vectorSearch'];
+        $result = Extension\vectorSearch($this->core, $indexName, json_encode($query), json_encode($vectorSearch), $exportedOptions, VectorSearchOptions::export($vectorSearch->options()));
+        return new SearchResult($result);
+    }
+
+    /**
+     * Provides access to search index management services at the scope level
+     *
+     * @return ScopeSearchIndexManagerInterface
+     *
+     * @since 4.1.7
+     *
+     * @VOLATILE: This API is subject to change at any time.
+     */
+    public function searchIndexes(): ScopeSearchIndexManagerInterface
+    {
+        return new ScopeSearchIndexManager($this->core, $this->bucketName, $this->name);
+    }
 }

Couchbase/ScopeInterface.php

@@ -20,6 +20,8 @@
 
 namespace Couchbase;
 
+use Couchbase\Management\ScopeSearchIndexManagerInterface;
+
 /**
  * Scope is an object for providing access to collections.
  */
@@ -31,5 +33,9 @@ public function collection(string $name): CollectionInterface;
 
     public function query(string $statement, QueryOptions $options = null): QueryResult;
 
+    public function search(string $indexName, SearchRequest $request, SearchOptions $options = null): SearchResult;
+
     public function analyticsQuery(string $statement, AnalyticsOptions $options = null): AnalyticsResult;
+
+    public function searchIndexes(): ScopeSearchIndexManagerInterface;
 }

package.xml

@@ -208,6 +208,8 @@
                     <file role="php" name="RoleAndDescription.php"/>
                     <file role="php" name="RoleAndOrigin.php"/>
                     <file role="php" name="S3ExternalAnalyticsLink.php"/>
+                    <file role="php" name="ScopeSearchIndexManager.php"/>
+                    <file role="php" name="ScopeSearchIndexManagerInterface.php"/>
                     <file role="php" name="ScopeSpec.php"/>
                     <file role="php" name="SearchIndex.php"/>
                     <file role="php" name="SearchIndexManager.php"/>
@@ -1264,6 +1266,8 @@
                                 <file role="src" name="encoded_value.hxx"/>
                                 <file role="src" name="json_transcoder.hxx"/>
                                 <file role="src" name="raw_binary_transcoder.hxx"/>
+                                <file role="src" name="raw_json_transcoder.hxx"/>
+                                <file role="src" name="raw_string_transcoder.hxx"/>
                                 <file role="src" name="serializer_traits.hxx"/>
                                 <file role="src" name="tao_json_serializer.hxx"/>
                                 <file role="src" name="transcoder_traits.hxx"/>
@@ -1500,6 +1504,7 @@
                             <file role="src" name="retry_request.hxx"/>
                             <file role="src" name="retry_strategy.hxx"/>
                             <file role="src" name="scope.hxx"/>
+                            <file role="src" name="scope_search_index_manager.hxx"/>
                             <file role="src" name="search_date_range.hxx"/>
                             <file role="src" name="search_error_context.hxx"/>
                             <file role="src" name="search_facet.hxx"/>