docs/v1.15.11/en/tools/database-data/db2searchtool.mdx
DB2VectorSearchToolPerform semantic vector similarity searches against IBM Db2 tables using the native VECTOR_DISTANCE function.
Supports configurable distance metrics, OpenAI or custom embeddings, metadata filtering, and result shaping.
pip install ibm_db openai
Or with uv:
uv add ibm_db openai
OPENAI_API_KEY=your_openai_key # Required when using default OpenAI embeddings
DB2_CONNECTION_STRING=DATABASE=TESTDB;HOSTNAME=localhost;PORT=50000;PROTOCOL=TCPIP;UID=db2user;PWD=password;
from crewai import Agent
from crewai_tools import DB2VectorSearchTool
tool = DB2VectorSearchTool(
connection_string="DATABASE=TESTDB;HOSTNAME=localhost;PORT=50000;PROTOCOL=TCPIP;UID=db2user;PWD=password;",
table_name="documents",
vector_column="embedding",
)
agent = Agent(
role="Research Assistant",
goal="Find relevant information in documents",
tools=[tool],
)
import os
from dotenv import load_dotenv
from crewai import Agent, Task, Crew, Process
from crewai_tools import DB2VectorSearchTool
load_dotenv()
db2_tool = DB2VectorSearchTool(
connection_string=os.getenv("DB2_CONNECTION_STRING"),
table_name="documents",
vector_column="embedding",
return_columns=["content", "category"],
limit=3,
distance_metric="COSINE",
max_distance=0.35,
)
search_agent = Agent(
role="Senior Semantic Search Agent",
goal="Find and analyse documents based on semantic search",
backstory="You are an expert research assistant who can find relevant information using semantic search in a Db2 database.",
tools=[db2_tool],
verbose=True,
)
answer_agent = Agent(
role="Senior Answer Assistant",
goal="Generate answers based on retrieved context",
backstory="You are an expert assistant who generates answers from provided context.",
tools=[db2_tool],
verbose=True,
)
search_task = Task(
description="""Search for relevant documents about {query}.
Include the relevant information found, vector distances, and returned fields.""",
agent=search_agent,
)
answer_task = Task(
description="Given the retrieved Db2 context, generate a final answer.",
agent=answer_agent,
)
crew = Crew(
agents=[search_agent, answer_agent],
tasks=[search_task, answer_task],
process=Process.sequential,
verbose=True,
)
result = crew.kickoff(inputs={"query": "What is the role of X in the document?"})
print(result)
| Parameter | Type | Default | Description |
|---|---|---|---|
connection_string | str | required | Db2 connection string. Format: DATABASE=x;HOSTNAME=x;PORT=50000;PROTOCOL=TCPIP;UID=x;PWD=x; |
table_name | str | "documents" | Table to search. Supports schema.table notation. |
vector_column | str | "embedding" | Column storing the vector embeddings. |
embedding_model | str | "text-embedding-3-large" | OpenAI model used when no custom embedding function is provided. |
return_columns | list[str] | ["content"] | Columns to include in each result. Must contain at least one entry. |
limit | int | 3 | Maximum number of results (1–100). |
distance_metric | str | "COSINE" | Db2 distance metric. See supported values below. |
max_distance | float | None | None | Drop results whose distance exceeds this value. |
custom_embedding_fn | Callable[[str], list[float]] | None | None | Custom embedding function. Overrides OpenAI when provided. |
The following values map directly to the Db2 VECTOR_DISTANCE function:
COSINEEUCLIDEANEUCLIDEAN_SQUAREDDOTHAMMINGMANHATTANReference: IBM Db2 VECTOR_DISTANCE documentation
| Parameter | Type | Required | Description |
|---|---|---|---|
query | str | ✅ | The search query. |
filter_by | str | None | ❌ | Column name for metadata filtering. Must be paired with filter_value. |
filter_value | Any | None | ❌ | Value to filter on. Must be paired with filter_by. |
{
"success": true,
"results": [
{
"distance": 0.1401,
"data": {
"content": "Document content here",
"category": "research"
}
}
]
}
On error:
{
"success": false,
"error": "Description of what went wrong",
"error_type": "ExceptionClassName"
}
result = db2_tool.run(
query="machine learning",
filter_by="category",
filter_value="research",
)
filter_by and filter_value must always be provided together. Providing only one raises a validation error.
Use any embedding model by supplying a custom_embedding_fn:
from sentence_transformers import SentenceTransformer
from crewai_tools import DB2VectorSearchTool
model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
def custom_embeddings(text: str) -> list[float]:
return model.encode(text).tolist()
tool = DB2VectorSearchTool(
connection_string="DATABASE=TESTDB;HOSTNAME=localhost;PORT=50000;PROTOCOL=TCPIP;UID=db2user;PWD=password;",
table_name="documents",
custom_embedding_fn=custom_embeddings,
)
When custom_embedding_fn is provided, OPENAI_API_KEY is not required.
^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)?$)