AI Engineer

5 minute read

Migrating Vector Search Implementations: Moving from Deprecated HanaDB to the New langchain_hana Package for SAP HANA Cloud

If you’ve been using SAP HANA Cloud with LangChain for vector search capabilities, it’s time to upgrade your implementation. The HanaDB class from the langchain_community.vectorstores.hanavector module has been deprecated since version 0.3.23 and will eventually be removed. This guide will walk you through the migration process to ensure your vector search implementations continue to work seamlessly.

Understanding the Deprecation

The original HanaDB class served as an integration between LangChain and SAP HANA Cloud’s vector capabilities. However, a new dedicated package has been developed to provide improved functionality and better support.

As stated in the official documentation:

This class is deprecated and will be removed in a future version. Please use HanaDB from the langchain_hana package instead. See SAP/langchain-integration-for-sap-hana-cloud for details. Use from langchain_hana import HanaDB instead.

Why Migrate?

There are several compelling reasons to migrate to the new langchain_hana package:

  1. Improved Implementation: The new package offers enhanced functionality specifically designed for SAP HANA Cloud.
  2. Full Support: Unlike the deprecated class, the new package will continue to receive updates and support.
  3. Future-Proofing: The deprecated class will eventually be removed from LangChain, potentially causing your applications to break.
  4. Specialized Development: The new package is maintained by SAP, ensuring better alignment with SAP HANA Cloud’s capabilities.

Migration Steps

Step 1: Install the New Package

First, you’ll need to install the new langchain_hana package:

pip install langchain_hana

Step 2: Update Your Imports

Replace your old import statements:

# Old (deprecated)
from langchain_community.vectorstores.hanavector import HanaDB

With the new import:

# New
from langchain_hana import HanaDB

Step 3: Review Your Implementation

While the core functionality remains similar, you should review your implementation for any specific methods or parameters that might have changed. The new package aims to maintain API compatibility, but there could be subtle differences.

Example: Migrating a Basic Vector Store Implementation

Let’s look at a practical example of migrating a simple vector store implementation:

Old Implementation (Deprecated)

from langchain_community.vectorstores.hanavector import HanaDB
from langchain_openai import OpenAIEmbeddings
import hdbcli.dbapi

# Create a connection to SAP HANA Cloud
connection = hdbcli.dbapi.connect(
    address="your_hana_host",
    port=443,
    user="your_username",
    password="your_password"
)

# Initialize embeddings
embeddings = OpenAIEmbeddings()

# Create vector store
vector_store = HanaDB(
    connection=connection,
    embedding=embeddings,
    table_name="DOCUMENT_VECTORS",
    content_column="DOCUMENT_TEXT",
    metadata_column="METADATA",
    vector_column="EMBEDDING"
)

# Add documents
texts = ["SAP HANA is a high-performance in-memory database.", 
         "Vector search enables semantic similarity queries."]
vector_store.add_texts(texts)

# Perform similarity search
results = vector_store.similarity_search("How does SAP HANA handle memory?", k=2)

New Implementation

from langchain_hana import HanaDB
from langchain_openai import OpenAIEmbeddings
import hdbcli.dbapi

# Create a connection to SAP HANA Cloud
connection = hdbcli.dbapi.connect(
    address="your_hana_host",
    port=443,
    user="your_username",
    password="your_password"
)

# Initialize embeddings
embeddings = OpenAIEmbeddings()

# Create vector store
vector_store = HanaDB(
    connection=connection,
    embedding=embeddings,
    table_name="DOCUMENT_VECTORS",
    content_column="DOCUMENT_TEXT",
    metadata_column="METADATA",
    vector_column="EMBEDDING"
)

# Add documents
texts = ["SAP HANA is a high-performance in-memory database.", 
         "Vector search enables semantic similarity queries."]
vector_store.add_texts(texts)

# Perform similarity search
results = vector_store.similarity_search("How does SAP HANA handle memory?", k=2)

As you can see, the only difference is the import statement. However, it’s still important to review the documentation of the new package to ensure all functionality works as expected.

Advanced Features to Explore

The new langchain_hana package may offer enhanced capabilities not available in the deprecated implementation. Here are some features to explore:

Creating HNSW Indices

HNSW (Hierarchical Navigable Small World) indices can significantly improve the performance of vector searches. Here’s an example of how to create one:

# Create an HNSW index with custom parameters
vector_store.create_hnsw_index(
    m=16,                 # Maximum number of neighbors per graph node
    ef_construction=64,   # Candidates to consider when building the graph
    ef_search=40,         # Minimum candidates for top-k-nearest neighbor queries
    index_name="MY_CUSTOM_INDEX"
)

Filtering in Similarity Searches

The ability to filter results based on metadata is crucial for many applications:

# Search with metadata filtering
results = vector_store.similarity_search(
    "cloud database capabilities",
    k=5,
    filter={"category": "technical", "year": 2023}
)

For applications where diversity in search results is important:

# MMR search balances relevance with diversity
results = vector_store.max_marginal_relevance_search(
    "hybrid transactional analytical processing",
    k=4,
    fetch_k=20,
    lambda_mult=0.5  # 0.5 balances relevance and diversity
)

Handling the Migration in Production Systems

When migrating production systems, consider these best practices:

  1. Test Thoroughly: Create a test environment to verify that the new implementation works correctly with your existing data.

  2. Gradual Rollout: If possible, implement the change in stages rather than all at once.

  3. Monitoring: Add monitoring to ensure that vector searches continue to perform as expected after the migration.

  4. Backup: Always ensure you have backups of your vector data before making significant changes.

Code Example: Creating a Vector Store from Documents

Here’s a complete example of creating a vector store from documents using the new package:

from langchain_hana import HanaDB
from langchain_openai import OpenAIEmbeddings
from langchain_core.documents import Document
import hdbcli.dbapi

# Create a connection
connection = hdbcli.dbapi.connect(
    address="your_hana_host",
    port=443,
    user="your_username",
    password="your_password"
)

# Initialize embeddings
embeddings = OpenAIEmbeddings()

# Prepare documents
documents = [
    Document(page_content="SAP HANA Cloud offers vector search capabilities", 
             metadata={"source": "documentation", "page": 1}),
    Document(page_content="Vector search enables semantic similarity queries", 
             metadata={"source": "blog", "page": 2}),
    Document(page_content="HANA Cloud integrates with LangChain for AI applications", 
             metadata={"source": "whitepaper", "page": 3})
]

# Create vector store from documents
vector_store = HanaDB.from_documents(
    documents=documents,
    embedding=embeddings,
    connection=connection,
    table_name="AI_DOCUMENTS",
    content_column="CONTENT",
    metadata_column="METADATA",
    vector_column="VECTOR"
)

# Perform similarity search
results = vector_store.similarity_search(
    "How does HANA work with AI?",
    k=2
)

# Print results
for doc in results:
    print(f"Content: {doc.page_content}")
    print(f"Metadata: {doc.metadata}")
    print("---")

Conclusion

Migrating from the deprecated HanaDB class to the new langchain_hana package is a straightforward process that ensures your vector search implementations will continue to work with SAP HANA Cloud. The new package offers improved functionality and ongoing support, making it a worthwhile upgrade for all users.

Remember that the deprecated class will eventually be removed from LangChain, so it’s best to migrate sooner rather than later to avoid potential issues in the future.

By following the steps outlined in this guide, you should be able to smoothly transition your applications to the new package and take advantage of the enhanced capabilities it offers for vector search in SAP HANA Cloud.

This post was originally written in my native language and then translated using an LLM. I apologize if there are any grammatical inconsistencies.

Categories:

Updated:

You may also enjoy