Vector Store

The C3 Agentic AI Platform supports pgvector, an extension for PostgreSQL that enables efficient storage, retrieval, and manipulation of vector data. It provides vector data management and querying capabilities within your existing database environment.

Vectors play a critical role in many AI and machine learning applications, especially in tasks involving similarity searches, such as recommendation systems, image recognition. Vectors are also important in generative AI tasks, like retrieval-augmented generation, where vectors help in sourcing relevant text to inform content creation. Vector store integration on the C3 Agentic AI Platform is catered to developers who build Generative AI applications by facilitating efficient vector operations at scale.

The C3 Agentic AI Platform offers the following benefits:

• Seamless Integration — Since PostgreSQL is part of the standard platform deployment, incorporating pgvector utilizes familiar infrastructure and requires minimal additional configuration.

• Scalability — The C3 Agentic AI Platform is optimized for handling large-scale vector data. pgvector supports advanced indexing mechanisms like IVFFlat and HNSW, which is suitable for enterprise-level applications.

• Flexibility — The platform accommodates a range of vector operations, from precise k-nearest neighbor (KNN) searches to approximate nearest neighbor (ANN) searches using different indexing strategies.

Use the C3 Agentic AI Platform to access key features:

• Vector storage — Manage vectors as primary entities within your database environment.

• Advanced indexing — Enhance search speed and accuracy using sophisticated indexing techniques.

• Comprehensive search capabilities — Run precise or approximate searches to find vectors most similar to your query vectors.

Copy link to this section

Configure an Entity Type to store vector embeddings

Vectors can be integrated into any PostgreSQL table by defining an EntityType Type that includes the following details:

• Vector Field Annotation — Apply a vector annotation directly to the vector field in your entity definition to specify necessary attributes. This annotation should include:

  • dimension — The dimensionality of the vector, indicating the number of elements in the vector. This parameter is crucial since it defines the size and structure of the vector data.

• Index Configuration Annotation — Use a db annotation to specify the index settings for the vector field. This annotation allows for flexible index configuration based on the indexing method chosen.

  • fields — An array that details each field to be indexed. Each entry in this array must include:

    • name — The name of the vector field (for example, emb) for which the index is to be created.

    • opClass — The distance metric used for indexing, such as L2 for Euclidean distance.

Depending on the type of index used, additional parameters are required. For HNSW Indexes:

• neighborsCount — Specifies the number of nearest neighbors to consider, impacting the search's performance and accuracy.

• efConstruction — Defines the size of the dynamic candidate list during the index construction, influencing the build speed and the quality of the index.

For IVFFlat Indexes:

• clustersCount — Determines the number of clusters into which the vector space is divided, affecting the granularity and efficiency of the search.

If no specific index-related parameters are set within the annotation, the vector search will default to using a simple k-nearest neighbors (KNN) search.

Here is an example Type used to store vector embeddings:

/**
 * This is an example Type.
 */
@db(index = [{fields:[{name:emb, opClass:L2}], neighborsCount:16, efConstruction: 40}])
entity type VectorTestType {
  /**
   * The ID of the doc.
   */
  id: ~
  /**
   * The text of the doc.
   */
  text: string
  /**
   * The vector embedding.
   */
  @vector(dimension=768)
  emb: string
}

For more information on creating an entity Type, see Platform Types in the C3 AI Type System. For more information on C3 Agentic AI Platform Types, see Platform Types in the C3 AI Type System.

Copy link to this section

Insert and retrieve vector data

Since the data is modeled as an EntityType, it can be loaded using standard data integration processes.

While directly loading vector data is supported, it is often not common practice. Typically, vector data is generated as an output from complex data processing pipelines. These pipelines involve various preprocessing steps, such as normalization, tokenization, or feature extraction, followed by converting raw data into vector form using specific embedding models before storage.

Although the C3 Agentic AI Platform does not natively support all the preprocessing and transformation steps required for converting text data into vectors as a single automated process, it does facilitate the hosting of embedding models using the C3 AI Model Inference Service (MIS). Additionally, developers have the flexibility to integrate any necessary libraries to handle other preprocessing tasks within the platform's development environment. This setup allows for you to create a comprehensive pipeline that includes both custom preprocessing logic and embedding, utilizing C3 AI's platform capabilities. The resulting vectors can then be inserted into the pgvector table, making full use of the platform's environment to manage the entire data preparation and embedding process. For more information on MIS, see the C3 AI Model Inference Service Administration topic.

After data is loaded, it can be queried using existing C3 AI APIs. For more information, see the Fetch and Filter Data From the Database notebook.

Copy link to this section

Build a vector index

To optimize the retrieval of vector data, you can build a vector index on your dataset. Indexing is crucial for improving search performance and efficiency, especially with large datasets. To trigger the indexing process on your vector data, use the following API commands in the static console of your application:

// Retrieve the root table name for the vector data
var tableName = VectorTestType.meta().rootC3TableName();

// Command to rebuild the index on the specified table
DbAdmin.rebuildIndex(tableName);

Building a vector index can be a time-consuming process, particularly for large datasets. The time required depends on several factors.

• The choice between IVFFlat and HNSW indexing strategies impacts both the build time and the search performance.

  • IVFFlat is known for faster index build times and lower memory usage, making it an advantageous approach for databases with up to a million entries. It works by dividing vectors into clusters, enabling more targeted and resource-efficient searches.

  • HNSW uses a multi-layered graph structure which requires more time and memory to build, but offers superior speed-recall tradeoffs. It is particularly effective in scenarios with sparse initial data or when data is gradually accumulated, and it is less sensitive to dataset size changes, which reduces the need for frequent re-indexing.

• Dataset Size — The volume and dimensionality of vectors significantly impact the time required to build the index.

• System Resources — The available compute power and memory can drastically influence the speed of indexing.

Copy link to this section

Perform similarity search

To perform a similarity search, use the following API commands in the static console of your application:

var queryVector = '[1, 2, 3, 4, 5]'; // Define the query vector
var distanceMetric = "L2"; // Specify the distance metric to use

// Build the evaluation specification
var spec = EvalSpec.builder()
                   .projection("docid, emb") // Specify fields to retrieve
                   .order("vectorDistance('emb', " + queryVector + ", {'metric': '" + distanceMetric + "'})") // Order results by vector distance
                   .limit(3) // Limit the number of results returned
                   .build();

// Execute the evaluation with the specified spec
VectorTestType.eval(spec);

• queryVector defines the vector against which other vectors are compared.

• distanceMetric specifies the method used to compute distances. Available options are:

  • "L2" for Euclidean distance

  • "INNER_PRODUCT" for dot product

  • "COSINE" for cosine similarity

• The order parameter in the EvalSpec directs the function to compute the distance between each vector in the 'emb' column and the queryVector using the specified metric. The results are then ordered based on these distances, from the most relevant match to the least relevant.

• The limit field restricts the number of results returned, effectively controlling the top 'k' results in the similarity search.

The nprobes metric for the IVFFlat index and the ef_search metric for the HNSW index are currently configured at the PostgreSQL instance level, with default values of 1 and 40 respectively.

Copy link to this section

Optimize pgvector usage

There are several advanced strategies aimed at enhancing vector similarity searches. The following sections describe some key practices to consider for optimizing pgvector's performance across any deployment environment:

Copy link to this section

Use pg_prewarm

Use the DbAdmin.pgPrewarm(tableName) API to prewarm tables that are frequently accessed. This is particularly useful for reducing I/O latency at the start of heavy operations.

Schedule prewarming during periods of low demand to ensure that the data is ready in the cache when needed without impacting peak time performance.

Copy link to this section

Indexing Strategies

Refer to the table below for an overview of the key indexing strategies, their respective characteristics, and ideal use cases.

Copy link to this section

Distance metrics

Refer to the table below for a comparison of different metrics and their applications.