semantic_router.index.postgres

MetricPgVecOperatorMap Objects

class MetricPgVecOperatorMap(Enum)

Enum to map the metric to PostgreSQL vector operators.

dotproduct

inner product

euclidean

L2 distance

manhattan

L1 distance

parse_vector

def parse_vector(vector_str: Union[str, Any]) -> List[float]

Parses a vector from a string or other representation. Arguments:

vector_str (Union[str, Any]): The string or object representation of a vector.

Returns: List[float]: A list of floats representing the vector.

clean_route_name

def clean_route_name(route_name: str) -> str

Cleans and formats the route name by stripping spaces and replacing them with hyphens. Arguments:

route_name (str): The original route name.

Returns: str: The cleaned and formatted route name.

PostgresIndexRecord Objects

class PostgresIndexRecord(BaseModel)

Model to represent a record in the Postgres index.

init

def __init__(**data) -> None

Initializes a new Postgres index record with given data. Arguments:

data (dict): Field values for the record.

to_dict

def to_dict() -> Dict

Converts the record to a dictionary. Returns: Dict: A dictionary representation of the record.

PostgresIndex Objects

class PostgresIndex(BaseIndex)

Postgres implementation of Index.

init

def __init__(connection_string: Optional[str] = None,
             index_prefix: str = "semantic_router_",
             index_name: str = "index",
             metric: Metric = Metric.COSINE,
             namespace: Optional[str] = "",
             dimensions: int | None = None,
             init_async_index: bool = False)

Initializes the Postgres index with the specified parameters. Arguments:

connection_string (Optional[str]): The connection string for the PostgreSQL database.
index_prefix (str): The prefix for the index table name.
index_name (str): The name of the index table.
dimensions (int): The number of dimensions for the vectors.
metric (Metric): The metric used for vector comparisons.
Optional[str]0 (Optional[str]): An optional namespace for the index.
Optional[str]2 (Optional[str]3): Whether to initialize the index asynchronously.

setup_index

@deprecated(
    "Use _init_index or sync methods such as `auto_sync` (read more "
    "https://docs.aurelio.ai/semantic-router/user-guide/features/sync). "
    "This method will be removed in 0.2.0")
def setup_index() -> None

Sets up the index by creating the table and vector extension if they do not exist. Raises:

ValueError: If the existing table’s vector dimensions do not match the expected dimensions.
TypeError: If the database connection is not established.

add

def add(embeddings: List[List[float]],
        routes: List[str],
        utterances: List[str],
        function_schemas: Optional[List[Dict[str, Any]]] = None,
        metadata_list: List[Dict[str, Any]] = [],
        **kwargs) -> None

Adds records to the index. Arguments:

embeddings (List[List[float]]): A list of vector embeddings to add.
routes (List[str]): A list of route names corresponding to the embeddings.
utterances (List[Any]): A list of utterances corresponding to the embeddings.
function_schemas (Optional[List[Dict[str, Any]]]): A list of function schemas corresponding to the embeddings.
metadata_list (List[Dict[str, Any]]): A list of metadata corresponding to the embeddings.

Raises:

List[List[float]]0: If the vector embeddings being added do not match the expected dimensions.
List[List[float]]1: If the database connection is not established.

aadd

async def aadd(embeddings: List[List[float]],
               routes: List[str],
               utterances: List[str],
               function_schemas: Optional[List[Dict[str, Any]]] = None,
               metadata_list: List[Dict[str, Any]] = [],
               batch_size: int = 100,
               **kwargs) -> None

Asynchronously adds records to the index in batches. Arguments:

embeddings: A list of vector embeddings to add.
routes: A list of route names corresponding to the embeddings.
utterances: A list of utterances corresponding to the embeddings.
function_schemas: (Optional) List of function schemas.
metadata_list: (Optional) List of metadata dictionaries.
batch_size: Number of records per batch insert.

Raises:

ValueError: If the vector embeddings don’t match expected dimensions.
TypeError: If connection is not an async Postgres connection.

delete

def delete(route_name: str) -> None

Deletes records with the specified route name. Arguments:

route_name (str): The name of the route to delete records for.

Raises:

TypeError: If the database connection is not established.

adelete

async def adelete(route_name: str) -> list[str]

Asynchronously delete specified route from index if it exists. Returns the IDs of the vectors deleted. Arguments:

route_name (str): Name of the route to delete.

Returns: list[str]: List of IDs of the vectors deleted.

describe

def describe() -> IndexConfig

Describes the index by returning its type, dimensions, and total vector count. Returns: IndexConfig: An IndexConfig object containing the index’s type, dimensions, and total vector count.

is_ready

def is_ready() -> bool

Checks if the index is ready to be used. Returns: bool: True if the index is ready, False otherwise.

ais_ready

async def ais_ready() -> bool

Checks if the index is ready to be used. Returns: bool: True if the index is ready, False otherwise.

query

def query(
    vector: np.ndarray,
    top_k: int = 5,
    route_filter: Optional[List[str]] = None,
    sparse_vector: dict[int, float] | SparseEmbedding | None = None
) -> Tuple[np.ndarray, List[str]]

Searches the index for the query vector and returns the top_k results. Arguments:

vector (np.ndarray): The query vector.
top_k (int): The number of top results to return.
route_filter (Optional[List[str]]): Optional list of routes to filter the results by.
sparse_vector (dict[int, float] | SparseEmbedding | None): Optional sparse vector to filter the results by.

Raises:

TypeError: If the database connection is not established.

Returns: Tuple[np.ndarray, List[str]]: A tuple containing the scores and routes of the top_k results.

aquery

async def aquery(
    vector: np.ndarray,
    top_k: int = 5,
    route_filter: Optional[List[str]] = None,
    sparse_vector: dict[int, float] | SparseEmbedding | None = None
) -> Tuple[np.ndarray, List[str]]

Asynchronously search the index for the query vector and return the top_k results. Arguments:

vector (np.ndarray): The query vector to search for.
top_k (int, optional): The number of top results to return, defaults to 5.
route_filter (Optional[List[str]], optional): A list of route names to filter the search results, defaults to None.
sparse_vector (dict[int, float] | SparseEmbedding | None): An optional sparse vector to include in the query.

Raises:

TypeError: If the database connection is not established.

Returns: Tuple[np.ndarray, List[str]]: A tuple containing an array of scores and a list of route names.

delete_all

def delete_all()

Deletes all records from the Postgres index. Raises:

TypeError: If the database connection is not established.

delete_index

def delete_index() -> None

Deletes the entire table for the index. Raises:

TypeError: If the database connection is not established.

adelete_index

async def adelete_index() -> None

Asynchronously delete the entire table for the index. Raises:

TypeError: If the async database connection is not established.

aget_routes

async def aget_routes() -> list[tuple]

Asynchronously get a list of route and utterance objects currently stored in the index. Raises:

TypeError: If the database connection is not established.

Returns: List[Tuple]: A list of (route_name, utterance) objects.

len

def __len__()

Returns the total number of vectors in the index. If the index is not initialized returns 0. Returns: The total number of vectors.

alen

async def alen()

Async version of len. Returns the total number of vectors in the index. Returns: int: The total number of vectors.

close

def close()

Closes the psycopg connection if it exists.

has_connection

def has_connection() -> bool

Returns True if there is an active and valid psycopg connection, otherwise False.

Get Started

Client Reference

User Guide

semantic_router.index.postgres

MetricPgVecOperatorMap Objects

dotproduct

euclidean

manhattan

parse_vector

clean_route_name

PostgresIndexRecord Objects

init

to_dict

PostgresIndex Objects

init

setup_index

add

aadd

delete

adelete

describe

is_ready

ais_ready

query

aquery

delete_all

delete_index

adelete_index

aget_routes

len

alen

close

has_connection

​MetricPgVecOperatorMap Objects

​dotproduct

​euclidean

​manhattan

​parse_vector

​clean_route_name

​PostgresIndexRecord Objects

​__init__

​to_dict

​PostgresIndex Objects

​__init__

​setup_index

​add

​aadd

​delete

​adelete

​describe

​is_ready

​ais_ready

​query

​aquery

​delete_all

​delete_index

​adelete_index

​aget_routes

​__len__

​alen

​close

​has_connection

MetricPgVecOperatorMap Objects

dotproduct

euclidean

manhattan

parse_vector

clean_route_name

PostgresIndexRecord Objects

init

to_dict

PostgresIndex Objects

init

setup_index

add

aadd

delete

adelete

describe

is_ready

ais_ready

query

aquery

delete_all

delete_index

adelete_index

aget_routes

len

alen

close

has_connection