Class MatchingEngine

A class that represents a connection to a Google Vertex AI Matching Engine instance.

Hierarchy

  • VectorStore
    • MatchingEngine

Implements

Constructors

constructor

Properties

FilterType apiEndpoint apiVersion authOptions caller callerOptions callerParams deployedIndexId docstore embeddings endpoint index indexEndpoint indexEndpointClient location removeDatapointClient upsertDatapointClient

Methods

addDocuments addVectors asRetriever buildDatapoint cleanMetadata delete determinePublicAPIEndpoint getDeployedIndexId getPublicAPIEndpoint maxMarginalRelevanceSearch? metadataToRestrictions similaritySearch similaritySearchVectorWithScore similaritySearchWithScore toJSON toJSONNotImplemented fromDocuments fromTexts

Constructors

constructor

Properties

FilterType

FilterType: Restriction[]

apiEndpoint

apiEndpoint: string

The host to connect to for queries and upserts.

apiVersion

apiVersion: string = "v1"

The version of the API functions. Part of the path.

authOptions

authOptions: GoogleAuthOptions<JSONClient>

Explicitly set Google Auth credentials if you cannot get them from google auth application-default login This is useful for serverless or autoscaling environments like Fargate

caller

caller: AsyncCaller

callerOptions

callerOptions: AsyncCallerCallOptions

callerParams

callerParams: AsyncCallerParams

deployedIndexId

deployedIndexId: string

The id for the "deployed index", which is an identifier in the index endpoint that references the index (but is not the index id)

docstore

docstore: Docstore

Docstore that retains the document, stored by ID

embeddings

embeddings: EmbeddingsInterface

Embeddings interface for generating vector embeddings from text queries, enabling vector-based similarity searches.

endpoint

endpoint: string = "us-central1-aiplatform.googleapis.com"

Hostname for the API call

index

index: string

The id for the index

indexEndpoint

indexEndpoint: string

The id for the index endpoint

indexEndpointClient

indexEndpointClient: IndexEndpointConnection

location

location: string = "us-central1"

Region where the LLM is stored

removeDatapointClient

removeDatapointClient: RemoveDatapointConnection

upsertDatapointClient

upsertDatapointClient: UpsertDatapointConnection

Methods

addDocuments

  • addDocuments(documents): Promise<void>

  • Adds documents to the vector store, embedding them first through the embeddings instance.

    Parameters

    • documents: Document<Record<string, any>>[]

      Array of documents to embed and add.

    Returns Promise<void>

    A promise resolving to an array of document IDs or void, based on implementation.

    Abstract

addVectors

  • addVectors(vectors, documents): Promise<void>

  • Adds precomputed vectors and corresponding documents to the vector store.

    Parameters

    • vectors: number[][]

      An array of vectors representing each document.

    • documents: Document<Record<string, any>>[]

      Array of documents associated with each vector.

    Returns Promise<void>

    A promise resolving to an array of document IDs or void, based on implementation.

    Abstract

asRetriever

  • asRetriever(kOrFields?, filter?, callbacks?, tags?, metadata?, verbose?): VectorStoreRetriever<MatchingEngine>

  • Creates a VectorStoreRetriever instance with flexible configuration options.

    Parameters

    • OptionalkOrFields: number | Partial<VectorStoreRetrieverInput<MatchingEngine>>

      If a number is provided, it sets the k parameter (number of items to retrieve).

      • If an object is provided, it should contain various configuration options.
    • Optionalfilter: Restriction[]

      Optional filter criteria to limit the items retrieved based on the specified filter type.

    • Optionalcallbacks: Callbacks

      Optional callbacks that may be triggered at specific stages of the retrieval process.

    • Optionaltags: string[]

      Tags to categorize or label the VectorStoreRetriever. Defaults to an empty array if not provided.

    • Optionalmetadata: Record<string, unknown>

      Additional metadata as key-value pairs to add contextual information for the retrieval process.

    • Optionalverbose: boolean

      If true, enables detailed logging for the retrieval process. Defaults to false.

    Returns VectorStoreRetriever<MatchingEngine>

    • A configured VectorStoreRetriever instance based on the provided parameters.

    Example

    Basic usage with a k value:

    const retriever = myVectorStore.asRetriever(5);

    Usage with a configuration object:

    const retriever = myVectorStore.asRetriever({
      k: 10,
      filter: myFilter,
      tags: ['example', 'test'],
      verbose: true,
      searchType: 'mmr',
      searchKwargs: { alpha: 0.5 },
    });

buildDatapoint

cleanMetadata

  • cleanMetadata(documentMetadata): {
        [key: string]:
            | string
            | number
            | boolean
            | string[]
            | null;
    }

  • Parameters

    • documentMetadata: Record<string, any>

    Returns {
        [key: string]:
            | string
            | number
            | boolean
            | string[]
            | null;
    }

    • [key: string]:
          | string
          | number
          | boolean
          | string[]
          | null

delete

determinePublicAPIEndpoint

getDeployedIndexId

getPublicAPIEndpoint

OptionalmaxMarginalRelevanceSearch

  • maxMarginalRelevanceSearch(query, options, _callbacks): Promise<DocumentInterface<Record<string, any>>[]>

  • Return documents selected using the maximal marginal relevance. Maximal marginal relevance optimizes for similarity to the query AND diversity among selected documents.

    Parameters

    • query: string

      Text to look up documents similar to.

    • options: MaxMarginalRelevanceSearchOptions<Restriction[]>
    • _callbacks: undefined | Callbacks

    Returns Promise<DocumentInterface<Record<string, any>>[]>

    • List of documents selected by maximal marginal relevance.

metadataToRestrictions

  • metadataToRestrictions(documentMetadata): Restriction[]

  • Given the metadata from a document, convert it to an array of Restriction objects that may be passed to the Matching Engine and stored. The default implementation flattens any metadata and includes it as an "allowList". Subclasses can choose to convert some of these to "denyList" items or to add additional restrictions (for example, to format dates into a different structure or to add additional restrictions based on the date).

    Parameters

    • documentMetadata: Record<string, any>

      The metadata from a document

    Returns Restriction[]

    a Restriction[] (or an array of a subclass, from the FilterType)

similaritySearch

  • similaritySearch(query, k?, filter?, _callbacks?): Promise<DocumentInterface<Record<string, any>>[]>

  • Searches for documents similar to a text query by embedding the query and performing a similarity search on the resulting vector.

    Parameters

    • query: string

      Text query for finding similar documents.

    • Optionalk: number

      Number of similar results to return. Defaults to 4.

    • Optionalfilter: Restriction[]

      Optional filter based on FilterType.

    • Optional_callbacks: Callbacks

      Optional callbacks for monitoring search progress

    Returns Promise<DocumentInterface<Record<string, any>>[]>

    A promise resolving to an array of DocumentInterface instances representing similar documents.

similaritySearchVectorWithScore

  • similaritySearchVectorWithScore(query, k, filter?): Promise<[Document<Record<string, any>>, number][]>

  • Performs a similarity search using a vector query and returns results along with their similarity scores.

    Parameters

    • query: number[]

      Vector representing the search query.

    • k: number

      Number of similar results to return.

    • Optionalfilter: Restriction[]

      Optional filter based on FilterType to restrict results.

    Returns Promise<[Document<Record<string, any>>, number][]>

    A promise resolving to an array of tuples containing documents and their similarity scores.

    Abstract

similaritySearchWithScore

  • similaritySearchWithScore(query, k?, filter?, _callbacks?): Promise<[DocumentInterface<Record<string, any>>, number][]>

  • Searches for documents similar to a text query by embedding the query, and returns results with similarity scores.

    Parameters

    • query: string

      Text query for finding similar documents.

    • Optionalk: number

      Number of similar results to return. Defaults to 4.

    • Optionalfilter: Restriction[]

      Optional filter based on FilterType.

    • Optional_callbacks: Callbacks

      Optional callbacks for monitoring search progress

    Returns Promise<[DocumentInterface<Record<string, any>>, number][]>

    A promise resolving to an array of tuples, each containing a document and its similarity score.

toJSON

  • toJSON(): Serialized

  • Returns Serialized

toJSONNotImplemented

StaticfromDocuments

  • fromDocuments(docs, embeddings, dbConfig): Promise<VectorStore>

  • Creates a VectorStore instance from an array of documents, using the specified embeddings and database configuration.

    Subclasses must implement this method to define how documents are embedded and stored. Throws an error if not overridden.

    Parameters

    • docs: Document<Record<string, any>>[]
    • embeddings: EmbeddingsInterface
    • dbConfig: MatchingEngineArgs

    Returns Promise<VectorStore>

    A promise that resolves to a new VectorStore instance.

    Throws

    Throws an error if this method is not overridden by a subclass.

StaticfromTexts

  • fromTexts(texts, metadatas, embeddings, dbConfig): Promise<VectorStore>

  • Creates a VectorStore instance from an array of text strings and optional metadata, using the specified embeddings and database configuration.

    Subclasses must implement this method to define how text and metadata are embedded and stored in the vector store. Throws an error if not overridden.

    Parameters

    • texts: string[]
    • metadatas: object | object[]
    • embeddings: EmbeddingsInterface
    • dbConfig: MatchingEngineArgs

    Returns Promise<VectorStore>

    A promise that resolves to a new VectorStore instance.

    Throws

    Throws an error if this method is not overridden by a subclass.

Settings

Member Visibility

On This Page

Constructors
Properties
Methods