How to enable and use pgvector on Azure Cosmos DB for PostgreSQL

APPLIES TO: Azure Cosmos DB for PostgreSQL (powered by the Citus database extension to PostgreSQL)

The pgvector extension adds an open-source vector similarity search to PostgreSQL.

This article introduces us to extra capabilities enabled by pgvector. It covers the concepts of vector similarity and embeddings, and provides guidance on how to enable the pgvector extension. We learn about, how to create, store and query the vectors. You might also want to refer to the official README of the project.

Enable extension

PostgreSQL extensions must be enabled in your database before you can use them. To enable the extension, run the command from the psql tool to load the packaged objects into your database.

SELECT CREATE_EXTENSION('vector');

Note

To disable an extension use drop_extension()

Concepts

Vector similarity

Vector similarity is a method used to measure how similar two items are by representing them as vectors, which are series of numbers. Vectors are often used to represent data points, where each element of the vector represents a feature or attribute of the data point.

Vector similarity is commonly calculated using distance metrics, such as Euclidean distance or cosine similarity. Euclidean distance measures the straight-line distance between two vectors in the n-dimensional space, while cosine similarity measures the cosine of the angle between two vectors. The values of similarity metrics typically range between 0 and 1, with higher values indicating greater similarity between the vectors.

Vector similarity is widely used in various applications, such as recommendation systems, text classification, image recognition, and clustering. For example, in recommendation systems, vector similarity can be used to identify similar items based on the user's preferences. In text classification, vector similarity can be used to determine the similarity between two documents or sentences based on their vector representations.

Embeddings

An embedding is a technique of evaluating "relatedness" of text, images, videos, or other types of information. The evaluation permits machine learning models to efficiently identify the relationships and similarities between data, allowing algorithms to identify patterns and make accurate predictions. For example, in a sentiment analysis task, words with similar embeddings might be expected to have similar sentiment scores.

Getting started

Create a table tblvector with an embedding column of type vector(3) representing a three-dimensional vector.

CREATE TABLE tblvector(
    id bigserial PRIMARY KEY,
    embedding vector(3)
    );

Once you generated an embedding using a service like the OpenAI API, you can store the resulting vector in your database. Defining a vector as vector(3) designates [x,y,z] coordinates in three-dimension plane. The command inserts five new rows into the tblvector table with the provided embeddings.

INSERT INTO tblvector (id, embedding) VALUES (1, '[1,2,3]'), (2, '[4,5,6]'), (3, '[5,4,6]'), (4, '[3,5,7]'), (5, '[7,8,9]');

By using the INSERT INTO ... ON CONFLICT statement, you can specify an alternative action, such as updating records that match the criteria. It allows you to handle potential conflicts in a more efficient and effective manner.

INSERT INTO tblvector (id, embedding) VALUES (1, '[1,2,3]'), (2, '[4,5,6]')
ON CONFLICT (id) DO UPDATE SET embedding = EXCLUDED.embedding;

The DELETE command removes rows from a specified table based on the conditions specified in the WHERE clause. When the WHERE clause isn't present, all the rows in the table are deleted.

DELETE FROM tblvector WHERE id = 1;

To retrieve vectors and calculate similarity, use SELECT statements and the built-in vector operators. For instance, the query computes the Euclidean distance (L2 distance) between the given vector and the vectors stored in the tblvector table, sorts the results by the calculated distance, and returns the closest five most similar items.

SELECT * FROM tblvector 
ORDER BY embedding <-> '[3,1,2]' 
LIMIT 5;

The query uses the "<->" operator, which is the "distance operator" used to calculate the distance between two vectors in a multi-dimensional space. The query returns all rows with the distance of less than 6 from the vector [3,1,2].

SELECT * FROM tblvector WHERE embedding <-> '[3,1,2]' < 6;

The command retrieves the average value of the "embedding" column from the "tblvector" table. For example, if the "embedding" column contains word embeddings for a language model, then the average value of these embeddings could be used to represent the entire sentence or document.

SELECT AVG(embedding) FROM tblvector;

Vector operators

pgvector introduces six new operators that can be used on vectors:

Operator	Description
+	element-wise addition
-	element-wise subtraction
*	element-wise multiplication
<->	Euclidean distance
<#>	negative inner product
<=>	cosine distance

Vector functions

cosine_distance

Calculates the cosine distance between two vectors.

cosine_distance(vector, vector)

Arguments

vector

First vector.

vector

Second vector.

Return type

double precision as distance between the two provided vectors.

inner_product

Calculates the inner product of two vectors.

inner_product(vector, vector)

Arguments

vector

First vector.

vector

Second vector

Return type

double precision as inner product of the two vectors.

l2_distance

Calculates the Euclidean distance (also known as L2) between two vectors.

l2_distance(vector, vector)

Arguments

vector

First vector.

vector

Second vector

Return type

double precision as the Euclidean distance between the two vectors.

l1_distance

Calculates the taxicab distance (also known as L1) between two vectors.

l1_distance(vector, vector)

Arguments

vector

First vector.

vector

Second vector

Return type

double precision as the taxicab distance between the two vectors.

vector_dims(vector)

Returns the dimensions of a given vector.

Arguments

vector

A vector.

Return type

integer representing the number of dimensions of the given vector.

vector_norms(vector)

Calculates the Euclidean norm of a given vector.

Arguments

vector

A vector.

Return type

double precision representing the Euclidean norm of the given vector.

Vector aggregates

AVG

Calculates the average of the processed vectors.

Arguments

vector

A vector.

Return type

vector representing the average of processed vectors.

SUM

Arguments

vector

A vector.

Return type

vector representing the sum of processed vectors.

Next Steps

Learn more around performance, indexing and limitations using pgvector.

Optimize performance using pgvector