feat: MVI method updates (#959)

* feat: MVI method updates

Rename addItemBatch to upsertItemBatch to reflect its new upsert
functionality.

Make metadataFields in SearchOptions either an array of metadata
fields, or a sentinel value representing all metadata.

Add a similarity metric enum to createIndex to let the user specify
which metric to use when creating an index.

packages/client-sdk-nodejs/package.json

@@ -53,7 +53,7 @@
     "uuid": "8.3.2"
   },
   "dependencies": {
-    "@gomomento/generated-types": "0.77.0",
+    "@gomomento/generated-types": "0.84.0",
     "@gomomento/sdk-core": "file:../core",
     "@grpc/grpc-js": "1.9.0",
     "@types/google-protobuf": "3.15.6",

packages/client-sdk-nodejs/src/internal/vector-index-control-client.ts

@@ -1,16 +1,12 @@
 import {control} from '@gomomento/generated-types';
-import grpcControl = control.control_client;
 import {Header, HeaderInterceptorProvider} from './grpc/headers-interceptor';
 import {ClientTimeoutInterceptor} from './grpc/client-timeout-interceptor';
 import {Status} from '@grpc/grpc-js/build/src/constants';
 import {cacheServiceErrorMapper} from '../errors/cache-service-error-mapper';
 import {ChannelCredentials, Interceptor} from '@grpc/grpc-js';
 import {
-  ListCaches,
-  CreateSigningKey,
-  ListSigningKeys,
-  RevokeSigningKey,
   CredentialProvider,
+  InvalidArgumentError,
   MomentoLogger,
   VectorIndexConfiguration,
 } from '..';
@@ -20,16 +16,18 @@ import {GrpcClientWrapper} from './grpc/grpc-client-wrapper';
 import {
   validateIndexName,
   validateNumDimensions,
-  validateTtlMinutes,
 } from '@gomomento/sdk-core/dist/src/internal/utils';
 import {normalizeSdkError} from '@gomomento/sdk-core/dist/src/errors';
-import {_SigningKey} from '@gomomento/sdk-core/dist/src/messages/responses/grpc-response-types';
 import {
   CreateVectorIndex,
   DeleteVectorIndex,
   ListVectorIndexes,
 } from '@gomomento/sdk-core';
-import {IVectorIndexControlClient} from '@gomomento/sdk-core/dist/src/internal/clients';
+import {
+  IVectorIndexControlClient,
+  VectorSimilarityMetric,
+} from '@gomomento/sdk-core/dist/src/internal/clients';
+import grpcControl = control.control_client;
 
 export interface ControlClientProps {
   configuration: VectorIndexConfiguration;
@@ -73,7 +71,8 @@ export class VectorIndexControlClient implements IVectorIndexControlClient {
 
   public async createIndex(
     indexName: string,
-    numDimensions: number
+    numDimensions: number,
+    similarityMetric?: VectorSimilarityMetric
   ): Promise<CreateVectorIndex.Response> {
     try {
       validateIndexName(indexName);
@@ -85,6 +84,31 @@ export class VectorIndexControlClient implements IVectorIndexControlClient {
     const request = new grpcControl._CreateIndexRequest();
     request.index_name = indexName;
     request.num_dimensions = numDimensions;
+
+    similarityMetric ??= VectorSimilarityMetric.COSINE_SIMILARITY;
+
+    switch (similarityMetric) {
+      case VectorSimilarityMetric.INNER_PRODUCT:
+        request.inner_product =
+          new grpcControl._CreateIndexRequest._InnerProduct();
+        break;
+      case VectorSimilarityMetric.EUCLIDEAN_SIMILARITY:
+        request.euclidean_similarity =
+          new grpcControl._CreateIndexRequest._EuclideanSimilarity();
+        break;
+      case VectorSimilarityMetric.COSINE_SIMILARITY:
+        request.cosine_similarity =
+          new grpcControl._CreateIndexRequest._CosineSimilarity();
+        break;
+      default:
+        return new CreateVectorIndex.Error(
+          new InvalidArgumentError(
+            // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+            `Invalid similarity metric: ${similarityMetric}`
+          )
+        );
+    }
+
     return await new Promise<CreateVectorIndex.Response>(resolve => {
       this.clientWrapper.getClient().CreateIndex(
         request,
@@ -107,7 +131,7 @@ export class VectorIndexControlClient implements IVectorIndexControlClient {
     });
   }
 
-  public async listIndexes(): Promise<ListCaches.Response> {
+  public async listIndexes(): Promise<ListVectorIndexes.Response> {
     const request = new grpcControl._ListIndexesRequest();
     this.logger.debug("Issuing 'listIndexes' request");
     return await new Promise<ListVectorIndexes.Response>(resolve => {
@@ -160,85 +184,4 @@ export class VectorIndexControlClient implements IVectorIndexControlClient {
       );
     });
   }
-
-  public async createSigningKey(
-    ttlMinutes: number,
-    endpoint: string
-  ): Promise<CreateSigningKey.Response> {
-    try {
-      validateTtlMinutes(ttlMinutes);
-    } catch (err) {
-      return new CreateSigningKey.Error(normalizeSdkError(err as Error));
-    }
-    this.logger.debug("Issuing 'createSigningKey' request");
-    const request = new grpcControl._CreateSigningKeyRequest();
-    request.ttl_minutes = ttlMinutes;
-    return await new Promise<CreateSigningKey.Response>(resolve => {
-      this.clientWrapper
-        .getClient()
-        .CreateSigningKey(
-          request,
-          {interceptors: this.interceptors},
-          (err, resp) => {
-            if (err) {
-              resolve(new CreateSigningKey.Error(cacheServiceErrorMapper(err)));
-            } else {
-              const signingKey = new _SigningKey(resp?.key, resp?.expires_at);
-              resolve(new CreateSigningKey.Success(endpoint, signingKey));
-            }
-          }
-        );
-    });
-  }
-
-  public async revokeSigningKey(
-    keyId: string
-  ): Promise<RevokeSigningKey.Response> {
-    const request = new grpcControl._RevokeSigningKeyRequest();
-    request.key_id = keyId;
-    this.logger.debug("Issuing 'revokeSigningKey' request");
-    return await new Promise<RevokeSigningKey.Response>(resolve => {
-      this.clientWrapper
-        .getClient()
-        .RevokeSigningKey(request, {interceptors: this.interceptors}, err => {
-          if (err) {
-            resolve(new RevokeSigningKey.Error(cacheServiceErrorMapper(err)));
-          } else {
-            resolve(new RevokeSigningKey.Success());
-          }
-        });
-    });
-  }
-
-  public async listSigningKeys(
-    endpoint: string
-  ): Promise<ListSigningKeys.Response> {
-    const request = new grpcControl._ListSigningKeysRequest();
-    request.next_token = '';
-    this.logger.debug("Issuing 'listSigningKeys' request");
-    return await new Promise<ListSigningKeys.Response>(resolve => {
-      this.clientWrapper
-        .getClient()
-        .ListSigningKeys(
-          request,
-          {interceptors: this.interceptors},
-          (err, resp) => {
-            if (err || !resp) {
-              resolve(new ListSigningKeys.Error(cacheServiceErrorMapper(err)));
-            } else {
-              const signingKeys = resp.signing_key.map(
-                sk => new _SigningKey(sk.key_id, sk.expires_at)
-              );
-              resolve(
-                new ListSigningKeys.Success(
-                  endpoint,
-                  signingKeys,
-                  resp.next_token
-                )
-              );
-            }
-          }
-        );
-    });
-  }
 }

packages/client-sdk-nodejs/src/internal/vector-index-data-client.ts

@@ -7,9 +7,9 @@ import {
   MomentoLogger,
   MomentoLoggerFactory,
   SearchOptions,
-  VectorAddItemBatch,
   VectorDeleteItemBatch,
   VectorSearch,
+  VectorUpsertItemBatch,
 } from '@gomomento/sdk-core';
 import {VectorIndexClientProps} from '../vector-index-client-props';
 import {VectorIndexConfiguration} from '../config/vector-index-configuration';
@@ -23,6 +23,7 @@ import {
   validateTopK,
 } from '@gomomento/sdk-core/dist/src/internal/utils';
 import {normalizeSdkError} from '@gomomento/sdk-core/dist/src/errors';
+import {ALL_VECTOR_METADATA} from '@gomomento/sdk-core/dist/src/clients/IVectorIndexClient';
 
 export class VectorIndexDataClient implements IVectorIndexDataClient {
   private readonly configuration: VectorIndexConfiguration;
@@ -72,23 +73,23 @@ export class VectorIndexDataClient implements IVectorIndexDataClient {
     );
   }
 
-  public async addItemBatch(
+  public async upsertItemBatch(
     indexName: string,
     items: Array<VectorIndexItem>
-  ): Promise<VectorAddItemBatch.Response> {
+  ): Promise<VectorUpsertItemBatch.Response> {
     try {
       validateIndexName(indexName);
     } catch (err) {
-      return new VectorAddItemBatch.Error(normalizeSdkError(err as Error));
+      return new VectorUpsertItemBatch.Error(normalizeSdkError(err as Error));
     }
-    return await this.sendAddItemBatch(indexName, items);
+    return await this.sendUpsertItemBatch(indexName, items);
   }
 
-  private async sendAddItemBatch(
+  private async sendUpsertItemBatch(
     indexName: string,
     items: Array<VectorIndexItem>
-  ): Promise<VectorAddItemBatch.Response> {
-    const request = new vectorindex._AddItemBatchRequest({
+  ): Promise<VectorUpsertItemBatch.Response> {
+    const request = new vectorindex._UpsertItemBatchRequest({
       index_name: indexName,
       items: items.map(item => {
         return new vectorindex._Item({
@@ -108,14 +109,16 @@ export class VectorIndexDataClient implements IVectorIndexDataClient {
       }),
     });
     return await new Promise(resolve => {
-      this.client.AddItemBatch(
+      this.client.UpsertItemBatch(
         request,
         {interceptors: this.interceptors},
         (err, resp) => {
           if (resp) {
-            resolve(new VectorAddItemBatch.Success());
+            resolve(new VectorUpsertItemBatch.Success());
           } else {
-            resolve(new VectorAddItemBatch.Error(cacheServiceErrorMapper(err)));
+            resolve(
+              new VectorUpsertItemBatch.Error(cacheServiceErrorMapper(err))
+            );
           }
         }
       );
@@ -180,16 +183,21 @@ export class VectorIndexDataClient implements IVectorIndexDataClient {
     queryVector: Array<number>,
     options?: SearchOptions
   ): Promise<VectorSearch.Response> {
+    const metadataRequest = new vectorindex._MetadataRequest();
+    if (options?.metadataFields === ALL_VECTOR_METADATA) {
+      metadataRequest.all = new vectorindex._MetadataRequest.All();
+    } else {
+      metadataRequest.some = new vectorindex._MetadataRequest.Some({
+        fields:
+          options?.metadataFields === undefined ? [] : options.metadataFields,
+      });
+    }
+
     const request = new vectorindex._SearchRequest({
       index_name: indexName,
       query_vector: new vectorindex._Vector({elements: queryVector}),
       top_k: options?.topK,
-      metadata_fields: new vectorindex._MetadataRequest({
-        some: new vectorindex._MetadataRequest.Some({
-          fields:
-            options?.metadataFields === undefined ? [] : options.metadataFields,
-        }),
-      }),
+      metadata_fields: metadataRequest,
     });
 
     return await new Promise(resolve => {

packages/client-sdk-web/package.json

@@ -53,7 +53,7 @@
     "xhr2": "^0.2.1"
   },
   "dependencies": {
-    "@gomomento/generated-types-webtext": "0.77.0",
+    "@gomomento/generated-types-webtext": "0.84.0",
     "@gomomento/sdk-core": "file:../core",
     "google-protobuf": "3.21.2",
     "grpc-web": "1.4.2",

packages/client-sdk-web/src/internal/vector-index-control-client.ts

@@ -1,13 +1,21 @@
 import {control} from '@gomomento/generated-types-webtext';
-import {CredentialProvider, MomentoLogger, VectorIndexConfiguration} from '..';
+import {
+  CredentialProvider,
+  InvalidArgumentError,
+  MomentoLogger,
+  VectorIndexConfiguration,
+} from '..';
 import {Request, StatusCode, UnaryResponse} from 'grpc-web';
 import {
   _CreateIndexRequest,
   _ListIndexesRequest,
   _DeleteIndexRequest,
 } from '@gomomento/generated-types-webtext/dist/controlclient_pb';
 import {cacheServiceErrorMapper} from '../errors/cache-service-error-mapper';
-import {IVectorIndexControlClient} from '@gomomento/sdk-core/dist/src/internal/clients';
+import {
+  IVectorIndexControlClient,
+  VectorSimilarityMetric,
+} from '@gomomento/sdk-core/dist/src/internal/clients';
 import {normalizeSdkError} from '@gomomento/sdk-core/dist/src/errors';
 import {
   validateIndexName,
@@ -60,7 +68,8 @@ export class VectorIndexControlClient<
 
   public async createIndex(
     indexName: string,
-    numDimensions: number
+    numDimensions: number,
+    similarityMetric?: VectorSimilarityMetric
   ): Promise<CreateVectorIndex.Response> {
     try {
       validateIndexName(indexName);
@@ -71,6 +80,32 @@ export class VectorIndexControlClient<
     const request = new _CreateIndexRequest();
     request.setIndexName(indexName);
     request.setNumDimensions(numDimensions);
+
+    similarityMetric ??= VectorSimilarityMetric.COSINE_SIMILARITY;
+
+    switch (similarityMetric) {
+      case VectorSimilarityMetric.INNER_PRODUCT:
+        request.setInnerProduct(new _CreateIndexRequest._InnerProduct());
+        break;
+      case VectorSimilarityMetric.EUCLIDEAN_SIMILARITY:
+        request.setEuclideanSimilarity(
+          new _CreateIndexRequest._EuclideanSimilarity()
+        );
+        break;
+      case VectorSimilarityMetric.COSINE_SIMILARITY:
+        request.setCosineSimilarity(
+          new _CreateIndexRequest._CosineSimilarity()
+        );
+        break;
+      default:
+        return new CreateVectorIndex.Error(
+          new InvalidArgumentError(
+            // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+            `Invalid similarity metric: ${similarityMetric}`
+          )
+        );
+    }
+
     this.logger.debug("Issuing 'createIndex' request");
     return await new Promise<CreateVectorIndex.Response>(resolve => {
       this.clientWrapper.createIndex(