View Source LadybugEx.Vector (LadybugEx v0.2.0)
Interface for vector similarity search using the vector extension.
This module provides high-level functions for creating and querying HNSW (Hierarchical Navigable Small World) vector indexes in LadybugDB.
Prerequisites
The vector extension must be installed and loaded before using this module:
# Install once
LadybugEx.Extensions.install(conn, "vector")
# Load for each connection
LadybugEx.Extensions.load(conn, "vector")This module will automatically ensure the extension is loaded when calling its functions.
Supported Distance Metrics
:cosine- Cosine similarity (default):l2- Euclidean distance:l2sq- Squared Euclidean distance:dotproduct- Dot product similarity
Usage Examples
# Create a vector index
{:ok, _} = Vector.create_index(conn, "Product",
property: "embedding",
dimension: 1536,
metric: :cosine
)
# Query the index
{:ok, results} = Vector.query_index(conn, "Product", "product_embedding_idx",
vector: embedding,
k: 10
)
# Drop the index
{:ok, _} = Vector.drop_index(conn, "Product", "product_embedding_idx")Filtered Search with Projected Graphs
For filtered vector search, first create a projected graph:
# Create a filtered projection
{:ok, _} = Connection.query(conn, """
CALL PROJECT_GRAPH('filtered_products', 'Product', '*')
WHERE n.category = 'electronics'
RETURN *
""")
# Query on the projected graph
{:ok, results} = Vector.query_index(conn, "filtered_products", "product_embedding_idx",
vector: embedding,
k: 10
)Summary
Functions
Create a vector index on a node or relationship table.
Create a vector index on a node or relationship table.
Drop a vector index.
Drop a vector index.
List all vector indexes in the database.
List all vector indexes in the database.
Query a vector index to find the k-nearest neighbors.
Query a vector index to find the k-nearest neighbors.
Types
Functions
@spec create_index(LadybugEx.Connection.t(), String.t(), keyword()) :: {:ok, any()} | {:error, String.t()}
Create a vector index on a node or relationship table.
Options
:property- (required) The property name containing vectors:dimension- (required) The dimension of the vectors:metric- Distance metric to use (default::cosine):mu- HNSW M parameter for index building (default: 30):ml- HNSW M parameter for layer 0 (default: 30):pu- HNSW percentage of nodes in upper layers, 0.0-1.0 (default: 0.05):efc- HNSW ef parameter for construction (default: 200):cache_embeddings- Whether to cache embeddings (default: false):index_name- Custom index name (default: auto-generated)
Examples
# Basic usage with required options
{:ok, _} = Vector.create_index(conn, "Product",
property: "embedding",
dimension: 1536
)
# With custom parameters
{:ok, _} = Vector.create_index(conn, "Product",
property: "embedding",
dimension: 768,
metric: :l2,
mu: 50,
ml: 50,
efc: 400,
index_name: "custom_product_idx"
)@spec create_index!(LadybugEx.Connection.t(), String.t(), keyword()) :: any()
Create a vector index on a node or relationship table.
Raises an error if the index creation fails.
Examples
Vector.create_index!(conn, "Product",
property: "embedding",
dimension: 1536
)@spec drop_index(LadybugEx.Connection.t(), String.t(), String.t()) :: {:ok, any()} | {:error, String.t()}
Drop a vector index.
Examples
{:ok, _} = Vector.drop_index(conn, "Product", "product_embedding_idx")@spec drop_index!(LadybugEx.Connection.t(), String.t(), String.t()) :: any()
Drop a vector index.
Raises an error if dropping the index fails.
Examples
Vector.drop_index!(conn, "Product", "product_embedding_idx")@spec list_indexes(LadybugEx.Connection.t()) :: {:ok, [map()]} | {:error, String.t()}
List all vector indexes in the database.
Examples
{:ok, indexes} = Vector.list_indexes(conn)
Enum.each(indexes, fn idx ->
IO.inspect({idx["table"], idx["index_name"], idx["property"]})
end)@spec list_indexes!(LadybugEx.Connection.t()) :: [map()]
List all vector indexes in the database.
Raises an error if the listing fails.
@spec query_index(LadybugEx.Connection.t(), String.t(), String.t(), keyword()) :: {:ok, [search_result()]} | {:error, String.t()}
Query a vector index to find the k-nearest neighbors.
Options
:vector- (required) Query vector to search for:k- (required) Number of nearest neighbors to return:efs- HNSW ef parameter for search (default: 200)
Return Format
Returns a list of results, each containing:
"node"- The matched node"distance"- Distance to the query vector
Examples
# Basic query
{:ok, results} = Vector.query_index(conn, "Product", "product_embedding_idx",
vector: [0.1, 0.2, 0.3, ...],
k: 10
)
# With custom search parameter
{:ok, results} = Vector.query_index(conn, "Product", "product_embedding_idx",
vector: embedding,
k: 20,
efs: 400
)
# Access results
Enum.each(results, fn result ->
node = result["node"]
distance = result["distance"]
IO.inspect({node["name"], distance})
end)@spec query_index!(LadybugEx.Connection.t(), String.t(), String.t(), keyword()) :: [ search_result() ]
Query a vector index to find the k-nearest neighbors.
Raises an error if the query fails.
Examples
results = Vector.query_index!(conn, "Product", "product_embedding_idx",
vector: embedding,
k: 10
)