### Run Quickstart Example

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

Execute the `quickstart.py` script to test the local development environment.

```bash
python examples/quickstart.py
```

--------------------------------

### Install Example Dependencies

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

Install the Python packages required by the example scripts, such as `openai` and `mysql-connector-python`.

```bash
pip install openai mysql-connector-python numpy
```

--------------------------------

### Development Installation

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/module-overview.md

Install the package in development mode, cloning the repository and installing dependencies. This is suitable for contributing to the project.

```bash
git clone https://github.com/oceanbase/langchain-oceanbase
cd langchain-oceanbase
pip install -e ".[pyseekdb]"
poetry install
```

--------------------------------

### Complete OceanBase AI Functions Configuration Example

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/ai_functions.md

Demonstrates the full setup process for both embedding and completion AI models, including creation and verification. Ensure you replace placeholder values like API keys and model names with your actual credentials and desired model identifiers.

```python
from langchain_oceanbase.ai_functions import OceanBaseAIFunctions

# Initialize
ai_functions = OceanBaseAIFunctions(connection_args={
    "host": "127.0.0.1",
    "port": "2881",
    "user": "root@test",
    "password": "",
    "db_name": "test",
})

# Configure Embedding model
print("Configuring Embedding model...")
ai_functions.create_ai_model(
    model_name="your-embedding-model",
    model_type="dense_embedding"
)
ai_functions.create_ai_model_endpoint(
    endpoint_name="embedding_endpoint",
    ai_model_name="your-embedding-model",
    url="https://api.example.com/v1",
    access_key="YOUR_API_KEY",
    provider="openai"
)
print("✅ Embedding model configured")

# Configure Completion model
print("Configuring Completion model...")
ai_functions.create_ai_model(
    model_name="your-completion-model",
    model_type="completion"
)
ai_functions.create_ai_model_endpoint(
    endpoint_name="complete_endpoint",
    ai_model_name="your-completion-model",
    url="https://api.example.com/v1",
    access_key="YOUR_API_KEY",
    provider="openai"
)
print("✅ Completion model configured")

# Verify configuration
print("\nVerifying model configuration...")
vector = ai_functions.ai_embed(
    text="test",
    model_name="your-embedding-model"
)
print(f"✅ Embedding model available: {len(vector)} dimensions")

completion = ai_functions.ai_complete(
    prompt="Hello",
    model_name="your-completion-model"
)
print(f"✅ Completion model available")
```

--------------------------------

### Start SeekDB Alternative

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/CONTRIBUTING.md

Start the SeekDB lightweight alternative database for development.

```bash
make docker-up-seek
```

--------------------------------

### Setup OceanBaseCheckpointSaver

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/api-reference-checkpoint-saver.md

Initialize the checkpoint database by calling the setup() method. This must be done once before the checkpointer can be used with LangGraph.

```python
checkpointer = OceanBaseCheckpointSaver(connection_args=connection_args)
checkpointer.setup()  # Required before first use

# Now safe to use with LangGraph
app = graph.compile(checkpointer=checkpointer)
```

--------------------------------

### Setup and Run Integration Tests

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

Start the OceanBase/seekdb Docker container and then run integration tests. Alternatively, use poetry to run pytest for integration tests.

```bash
make docker-up
make integration_tests
```

```bash
poetry run pytest tests/integration_tests/
```

--------------------------------

### Troubleshooting: Ensure `setup()` is Called

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/migration_guide.md

Provides a solution for tables not being created by ensuring the `setup()` method is called after initializing the checkpointer.

```python
checkpointer = OceanBaseCheckpointSaver(connection_args=...)
checkpointer.setup()  # Don't forget this!
```

--------------------------------

### Install Langchain-Oceanbase for Development

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/INDEX.md

Set up the development environment by cloning the repository and installing the package in editable mode with pyseekdb support.

```bash
# Development
git clone https://github.com/oceanbase/langchain-oceanbase
cd langchain-oceanbase
pip install -e ".[pyseekdb]"
```

--------------------------------

### Start Local OceanBase Database

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

Use `make docker-up` to start the OceanBase Community Edition service for local development.

```bash
# start OceanBase
make docker-up
```

--------------------------------

### Install Dependencies with Pip

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/CONTRIBUTING.md

Use pip and a virtual environment to install project dependencies.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

--------------------------------

### Install Dependencies with Poetry

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/CONTRIBUTING.md

Use Poetry to install project dependencies and activate the virtual environment.

```bash
poetry install
poetry shell
```

--------------------------------

### Start Learning with Module Overview

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/README.md

Begin with module-overview.md for a comprehensive understanding of how different components of the integration work together.

```text
Start with [module-overview.md](module-overview.md) for a complete understanding of how components work together.
```

--------------------------------

### Explore Configuration Options

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/README.md

Refer to configuration.md for a complete list of parameters, their explanations, default values, and usage examples.

```text
[configuration.md](configuration.md) lists all parameters with explanations, defaults, and examples.
```

--------------------------------

### Minimal OceanbaseVectorStore Configuration

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/configuration.md

This is the recommended minimal configuration for quickstart. It uses all default settings for embedding, vector store, and checkpointing.

```python
from langchain_oceanbase import OceanbaseVectorStore

# Uses all defaults: embedding, vector store, checkpoint
vector_store = OceanbaseVectorStore(
    embedding_function=None,  # Auto-uses DefaultEmbeddingFunctionAdapter
    embedding_dim=384,
)
```

--------------------------------

### Install langchain-oceanbase Base Package

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/api-reference-embedding-utils.md

Install the core `langchain-oceanbase` package using pip.

```bash
pip install -U langchain-oceanbase
```

--------------------------------

### setup

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/api-reference-oceanbase-store.md

Creates the backing table and indexes for the store if they do not already exist. This method must be called once before using the store.

```APIDOC
## Method: setup

### Description
Creates the backing table and indexes for the store if they do not already exist. This method must be called once before using the store.

### Returns
`None`

### Details
Creates:
- Main items table with columns for namespace, key, value, timestamps
- Optional index columns for semantic search
- Indexes on namespace_path and expires_at for query performance

### Example
```python
store = OceanBaseStore(connection_args=connection_args)
store.setup()  # Required before first use
```
```

--------------------------------

### Run Hybrid Search Demo Example

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

Execute the `hybrid_search_demo.py` script to run the hybrid search demonstration.

```bash
python examples/hybrid_search_demo.py
```

--------------------------------

### Install Dependencies

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/migration_guide.md

Install the necessary packages for OceanBase and LangGraph. Use the `-U` flag to ensure you have the latest versions.

```bash
pip install -U langchain-oceanbase langgraph
```

--------------------------------

### Start Local SeekDB Database

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

Use `make docker-up-seek` to start the lightweight SeekDB alternative for local development.

```bash
# or start seekdb (lightweight alternative)
make docker-up-seek
```

--------------------------------

### TTL Configuration Example

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/types.md

Example configuration for time-to-live settings. Specifies default TTL in seconds and whether to refresh expiry on read access.

```python
{
    "default_ttl": 3600,        # 1 hour
    "refresh_on_read": True,    # Reset timer on access
}
```

--------------------------------

### Quick Navigation for First-Time Users

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/README.md

For new users, begin with the Quick Navigation section in INDEX.md to get oriented.

```text
Start with [INDEX.md](INDEX.md) Quick Navigation section
```

--------------------------------

### Setup OceanBaseStore

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/api-reference-oceanbase-store.md

Initialize the OceanBaseStore by creating necessary tables and indexes. This method must be called once before any other operations.

```python
store = OceanBaseStore(connection_args=connection_args)
store.setup()  # Required before first use
```

--------------------------------

### OceanBaseStore Constructor with Basic Configuration

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/api-reference-oceanbase-store.md

Instantiate OceanBaseStore with basic connection arguments. Ensure the setup() method is called before first use.

```python
from langchain_oceanbase import OceanBaseStore
from langchain_core.embeddings import Embeddings

connection_args = {
    "host": "127.0.0.1",
    "port": "2881",
    "user": "root@test",
    "password": "",
    "db_name": "test",
}

# Basic store without semantic search
store = OceanBaseStore(connection_args=connection_args)
store.setup()
```

--------------------------------

### Start OceanBase Docker Container

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/langgraph_store.ipynb

Starts a local OceanBase CE instance in Docker for demonstration purposes.

```bash
!docker run --name=oceanbase -e MODE=mini -e OB_SERVER_IP=127.0.0.1 -p 2881:2881 -d oceanbase/oceanbase-ce:latest
```

--------------------------------

### Multi-Turn Agent with Memory Setup

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/INDEX.md

Configure a multi-turn agent with memory persistence using OceanBaseCheckpointSaver and OceanBaseStore. Ensure setup is called for both.

```python
from langchain_oceanbase import OceanBaseCheckpointSaver, OceanBaseStore

checkpointer = OceanBaseCheckpointSaver(connection_args={...})
memory_store = OceanBaseStore(connection_args={...})

checkpointer.setup()
memory_store.setup()

app = graph.compile(checkpointer=checkpointer)
config = {"configurable": {"thread_id": "user-123"}}

# Memories persist across invocations
result = app.invoke(input, config)
memory_store.put(("memories", "user-123"), "fact", {"fact": "..."})
```

--------------------------------

### Install langchain-oceanbase Package

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/ai_functions.ipynb

Installs the necessary Python package for integrating Langchain with OceanBase AI functions. Use '-qU' for quiet and upgrade installation.

```bash
pip install -qU "langchain-oceanbase"

```

--------------------------------

### Install LangGraph and Langchain-Oceanbase

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/langgraph_checkpoint.ipynb

Installs the necessary packages for LangGraph and OceanBase integration. Use the `-qU` flags for quiet installation and upgrades.

```python
%pip install -qU langchain-oceanbase langgraph

```

--------------------------------

### Install Langchain-Oceanbase Package

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/vectorstores.ipynb

Installs the necessary langchain-oceanbase integration package using pip.

```python
%pip install -qU "langchain-oceanbase"
```

--------------------------------

### Base Installation

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/module-overview.md

Install the base langchain-oceanbase package. This includes vectorstore, checkpoint, and store functionalities but does not include built-in embeddings.

```bash
pip install langchain-oceanbase
```

--------------------------------

### Start Local Database

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/CONTRIBUTING.md

Bring up the local OceanBase database for development using Docker Compose.

```bash
make docker-up
```

--------------------------------

### Environment Variables Example

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/CONTRIBUTING.md

Example configuration for environment variables required for database connection and API keys. Create a .env file or export these variables.

```dotenv
OB_HOST=127.0.0.1
OB_PORT=3306
OB_USER=root
OB_PASSWORD=yourpassword
OB_DB=langchain_ob_demo
OPENAI_API_KEY=sk-xxxx
```

--------------------------------

### Setup OceanBase Database Tables

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/migration_guide.md

Sets up the necessary database tables for checkpointing. This should be run once after initializing the checkpointer.

```python
# Setup database tables (run once)
checkpointer.setup()
```

--------------------------------

### Install Langchain-OceanBase Dependencies

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

Install the necessary Python packages for Langchain-OceanBase and the `pyobvector` library.

```bash
pip install -U langchain-oceanbase pyobvector
```

--------------------------------

### Install Langchain-Oceanbase with Pyseekdb

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/INDEX.md

Install langchain-oceanbase along with built-in embeddings and an embedded seekdb instance.

```bash
# With built-in embeddings & embedded seekdb
pip install "langchain-oceanbase[pyseekdb]"
```

--------------------------------

### Install langchain-oceanbase with pyseekdb extra

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/embeddings.md

Install the necessary package with the optional pyseekdb extra for local ONNX runtime inference.

```bash
pip install -qU "langchain-oceanbase[pyseekdb]"
```

--------------------------------

### OceanBaseStore Index Configuration Example

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/types.md

Example configuration for semantic search indexing in OceanBaseStore. Requires embedding dimension, an embeddings instance, and fields to embed.

```python
{
    "dims": 384,
    "embed": embeddings_instance,
    "fields": ["memory", "context"],
}
```

--------------------------------

### setup

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/api-reference-checkpoint-saver.md

Initializes the checkpoint database with required tables and migrations. This method must be called once before using the checkpointer and ensures the necessary database structures are in place.

```APIDOC
## Method: setup

### Description
Initializes the checkpoint database with required tables and migrations. This method must be called once before using the checkpointer and ensures the necessary database structures are in place.

### Signature
```python
def setup(self) -> None
```

### Returns
`None`

### Raises
- `OceanBaseConnectionError`: Database connection fails.

### Details
Must be called once before using the checkpointer. Creates:
- `checkpoints` table: stores checkpoint states
- `checkpoint_blobs` table: stores channel values
- `checkpoint_writes` table: stores task writes
- Indexes for performance optimization

### Example
```python
checkpointer = OceanBaseCheckpointSaver(connection_args=connection_args)
checkpointer.setup()  # Required before first use

# Now safe to use with LangGraph
app = graph.compile(checkpointer=checkpointer)
```
```

--------------------------------

### Run RAG Demo Example

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

Execute the `rag_demo.py` script to run the Retrieval-Augmented Generation demo.

```bash
python examples/rag_demo.py
```

--------------------------------

### Install Dependencies for AI Functions

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

To enable AI functions, install `langchain-oceanbase`, `pyobvector`, and `langgraph-checkpoint`.

```bash
pip install -U langchain-oceanbase pyobvector langgraph-checkpoint
```

--------------------------------

### RAG Pipeline Setup

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/INDEX.md

Initialize a RAG pipeline by creating an OceanbaseVectorStore, defining a retriever, and setting up a RetrievalQA chain.

```python
from langchain_oceanbase import OceanbaseVectorStore
from langchain.chains import RetrievalQA

vector_store = OceanbaseVectorStore(...)
retriever = vector_store.as_retriever(search_kwargs={"k": 5})

qa = RetrievalQA.from_chain_type(llm=llm, retriever=retriever)
result = qa.run("What is OceanBase?")
```

--------------------------------

### Runnable Example for LangGraph Store

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

This Python script provides a runnable example for the LangGraph Store, showcasing namespace-scoped memory, semantic search, and TTL functionality.

```python
# Runnable example for namespace-scoped memory, semantic search, and TTL
```

--------------------------------

### LangChain Document Example

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/types.md

Example of creating a LangChain Document object. Includes page content, metadata, and an optional ID.

```python
from langchain_core.documents import Document

doc = Document(
    page_content="Machine learning is AI",
    metadata={"source": "wiki", "year": 2024},
    id="doc-123"
)
```

--------------------------------

### Create and Initialize OceanBaseStore

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/langgraph_store.ipynb

Initializes the OceanBaseStore with connection details, embedding configuration, and TTL settings. It also calls the setup method to prepare the store.

```python
from langchain_oceanbase import OceanBaseStore


store = OceanBaseStore(
    connection_args={
        "host": "127.0.0.1",
        "port": "2881",
        "user": "root@test",
        "password": "",
        "db_name": "test",
    },
    index={"dims": 3, "embed": DemoEmbeddings(), "fields": ["memory"]},
    ttl_config={"refresh_on_read": True, "default_ttl": 60},
)
store.setup()
```

--------------------------------

### Start OceanBase Docker Container

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/langgraph_checkpoint.ipynb

Starts a local OceanBase Community Edition instance using Docker. This command is useful for local development and testing.

```bash
!docker run --name=oceanbase -e MODE=mini -e OB_SERVER_IP=127.0.0.1 -p 2881:2881 -d oceanbase/oceanbase-ce:latest

```

--------------------------------

### Recommended: LangGraph with OceanBaseCheckpointSaver - Full Example

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/api-reference-chat-message-histories.md

Provides a complete example of using `OceanBaseCheckpointSaver` with LangGraph, including defining a `ChatState`, a `chat_node` function, and demonstrating persistence across multiple invocations.

```python
from langchain_oceanbase import OceanBaseCheckpointSaver
from langgraph.graph import StateGraph, START, END
from langchain_core.messages import BaseMessage, HumanMessage, AIMessage
from typing import TypedDict

class ChatState(TypedDict):
    messages: list[BaseMessage]

def chat_node(state: ChatState) -> ChatState:
    # Your chat logic here
    last_message = state["messages"][-1]
    response = AIMessage(content=f"Echo: {last_message.content}")
    return {"messages": state["messages"] + [response]}

# Create graph
builder = StateGraph(ChatState)
builder.add_node("chat", chat_node)
builder.add_edge(START, "chat")
builder.add_edge("chat", END)

# Setup checkpointer
checkpointer = OceanBaseCheckpointSaver(connection_args=connection_args)
checkpointer.setup()

app = builder.compile(checkpointer=checkpointer)

# Use with persistence
config = {"configurable": {"thread_id": "user-123"}}

# First call
result1 = app.invoke({"messages": [HumanMessage(content="Hello")]}, config)
print(result1["messages"])

# Second call – messages are persistent
result2 = app.invoke({"messages": [HumanMessage(content="How are you?")]}, config)
print(result2["messages"])
```

--------------------------------

### Hybrid Search with Default and Custom Weights Examples

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/hybrid_search.ipynb

Provides examples of performing hybrid searches using both default (automatic) and custom weights for different search modalities. Demonstrates how to configure weights to prioritize semantic, sparse, or full-text relevance.

```python
# Default weights (automatic)
results = vector_store.advanced_hybrid_search(
    vector_query="AI technology",
    sparse_query={1: 0.8, 5: 0.6},
    fulltext_query="machine learning"
)

# Custom weights emphasizing semantic similarity
semantic_weights = {'vector': 0.8, 'sparse': 0.1, 'fulltext': 0.1}
results = vector_store.advanced_hybrid_search(
    vector_query="AI technology",
    sparse_query={1: 0.8, 5: 0.6},
    fulltext_query="machine learning",
    modality_weights=semantic_weights
)
```

--------------------------------

### Full Installation with Built-in Embeddings

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/module-overview.md

Install the full package with built-in embeddings and embedded seekdb support. This option includes all features.

```bash
pip install "langchain-oceanbase[pyseekdb]"
```

--------------------------------

### Configure OceanBaseCheckpointSaver

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/langgraph_checkpoint.ipynb

Initializes the OceanBaseCheckpointSaver with connection arguments. Adjust these based on your OceanBase setup (cloud, local, etc.). The `setup()` method prepares the necessary database schema.

```python
import os

from langchain_oceanbase import OceanBaseCheckpointSaver


connection_args = {
    "host": os.getenv("OCEANBASE_HOST", "127.0.0.1"),
    "port": os.getenv("OCEANBASE_PORT", "2881"),
    "user": os.getenv("OCEANBASE_USER", "root@test"),
    "password": os.getenv("OCEANBASE_PASSWORD", ""),
    "db_name": os.getenv("OCEANBASE_DB", "test"),
}

checkpointer = OceanBaseCheckpointSaver(connection_args=connection_args)
checkpointer.setup()

```

--------------------------------

### Install langchain-oceanbase with Embedding Support

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/api-reference-embedding-utils.md

Install `langchain-oceanbase` with the `pyseekdb` extra to enable ONNX-based embedding functions. This includes `pyseekdb`, `pylibseekdb`, and the integration package.

```bash
pip install -U "langchain-oceanbase[pyseekdb]"
```

--------------------------------

### Get Architectural Overview

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/README.md

Obtain an architectural overview by consulting the module-overview.md file.

```text
See [module-overview.md](module-overview.md) Architectural overview
```

--------------------------------

### Initialize OceanBaseCheckpointSaver

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/api-reference-checkpoint-saver.md

Instantiate OceanBaseCheckpointSaver with connection arguments and optional serializer. Call setup() once before using the checkpointer with LangGraph.

```python
from langchain_oceanbase import OceanBaseCheckpointSaver
from langgraph.graph import StateGraph

connection_args = {
    "host": "127.0.0.1",
    "port": "2881",
    "user": "root@test",
    "password": "",
    "db_name": "test",
}

checkpointer = OceanBaseCheckpointSaver(connection_args=connection_args)
checkpointer.setup()

# Use with LangGraph
graph = StateGraph(state_schema=MyState)
# ... add nodes and edges ...
app = graph.compile(checkpointer=checkpointer)

# Run with persistence
config = {"configurable": {"thread_id": "my-thread"}}
result = app.invoke({"messages": [...]}, config)
```

--------------------------------

### Hybrid Search Setup with OceanbaseVectorStore

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/vectorstores.ipynb

Initializes OceanbaseVectorStore to support hybrid search by enabling both sparse vector and full-text search capabilities. Requires 'embeddings' and 'connection_args'.

```python
# Create vector store with hybrid search capabilities
hybrid_vectorstore = OceanbaseVectorStore(
    embedding_function=embeddings,
    table_name="hybrid_search_docs",
    connection_args=connection_args,
    include_sparse=True,
    include_fulltext=True,
    drop_old=True,
)

```

--------------------------------

### Run OceanBase Docker Container

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/hybrid_search.ipynb

Starts a standalone OceanBase CE server in a Docker container. Ensure Docker is installed and running.

```bash
docker run --name=oceanbase -e MODE=mini -e OB_SERVER_IP=127.0.0.1 -p 2881:2881 -d oceanbase/oceanbase-ce:latest

```

--------------------------------

### Upgrade OceanBase for AI Functions

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

To enable AI functions, ensure your OceanBase version is 4.4.1 or later. This example shows how to start a Docker container with the required version.

```bash
docker run --name=oceanbase -e MODE=mini -e OB_SERVER_IP=127.0.0.1 \
    -p 2881:2881 -d oceanbase/oceanbase-ce:4.4.1.0-100000032025101610
```

--------------------------------

### Install LangGraph and Langchain-OceanBase

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/langgraph_store.ipynb

Installs the necessary packages for using LangGraph with OceanBase.

```python
%pip install -qU langchain-oceanbase langgraph
```

--------------------------------

### Initialize OceanBaseStore

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

Instantiate the OceanBaseStore for general data persistence.

```python
store = OceanBaseStore(connection_args=connection_args)
store.setup()
```

--------------------------------

### OceanBaseStore Constructor with Semantic Search and TTL

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/api-reference-oceanbase-store.md

Instantiate OceanBaseStore with connection arguments, semantic search index configuration, and TTL settings. The setup() method must be called subsequently.

```python
from langchain_oceanbase import OceanBaseStore
from langchain_core.embeddings import Embeddings

connection_args = {
    "host": "127.0.0.1",
    "port": "2881",
    "user": "root@test",
    "password": "",
    "db_name": "test",
}

# Store with semantic search
embeddings = ...  # Any LangChain Embeddings implementation
store = OceanBaseStore(
    connection_args=connection_args,
    index={
        "dims": 384,
        "embed": embeddings,
        "fields": ["memory", "notes"],  # Fields to embed
    },
    ttl_config={"default_ttl": 86400, "refresh_on_read": True},  # 24 hours
)
store.setup()
```

--------------------------------

### Handling ImportError for pyseekdb

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/api-reference-embedding-utils.md

Catch an ImportError if pyseekdb is not installed and provide instructions on how to install it with the necessary extras.

```python
from langchain_oceanbase.embedding_utils import DefaultEmbeddingFunctionAdapter

try:
    embeddings = DefaultEmbeddingFunctionAdapter()
except ImportError as e:
    print(f"Install with: pip install 'langchain-oceanbase[pyseekdb]'")
```

--------------------------------

### Find All Parameters

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/README.md

Access configuration.md to find a comprehensive list of all available parameters.

```text
See [configuration.md](configuration.md)
```

--------------------------------

### Build RAG with OceanbaseVectorStore

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/vectorstores.ipynb

Demonstrates how to set up OceanbaseVectorStore for RAG, add documents, and build a question-answering chain using OpenAI. Ensure 'embeddings' and 'connection_args' are defined beforehand.

```python
from langchain.chains import RetrievalQA
from langchain.llms import OpenAI

# Create vector store for knowledge base
rag_vectorstore = OceanbaseVectorStore(
    embedding_function=embeddings,
    table_name="knowledge_base",
    connection_args=connection_args,
    vidx_metric_type="l2",
    drop_old=True,
)

# Add knowledge documents
documents = [
    "LangChain is a framework for developing applications powered by language models.",
    "OceanBase is a distributed relational database developed by Ant Group.",
    "Vector databases are specialized databases for storing and searching vector embeddings.",
    "Hybrid search combines multiple search modalities for better results."
]
rag_vectorstore.add_texts(documents)

# Build RAG chain
retriever = rag_vectorstore.as_retriever(search_kwargs={"k": 3})
qa_chain = RetrievalQA.from_chain_type(
    llm=OpenAI(),
    chain_type="stuff",
    retriever=retriever
)

# Ask questions
question = "What is LangChain?"
answer = qa_chain.run(question)
print(f"Q: {question}")
print(f"A: {answer}")

```

--------------------------------

### OceanBaseStore Constructor

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/configuration.md

Initialize OceanBaseStore with connection details, index configuration, TTL settings, and table name. Additional arguments are passed to ObVecClient.

```python
OceanBaseStore(
    connection_args: Optional[Dict[str, Any]] = None,
    *,
    index: Optional[Dict[str, Any]] = None,
    ttl_config: Optional[Dict[str, Any]] = None,
    table_name: str = "langgraph_store_items",
    **kwargs: Any,
)
```

--------------------------------

### Install langchain-oceanbase and pyseekdb

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/embeddings.ipynb

Installs the necessary packages for using the built-in embedding functionality. This includes langchain-oceanbase and pyseekdb, which handles local ONNX inference.

```python
%pip install -qU "langchain-oceanbase" "pyseekdb"

```

--------------------------------

### Programmatic Configuration using Environment Variables

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/configuration.md

Example of configuring OceanbaseVectorStore programmatically by fetching connection details from environment variables. This allows for flexible configuration without hardcoding sensitive information.

```python
import os

connection_args = {
    "host": os.environ.get("OCEANBASE_HOST", "localhost"),
    "port": os.environ.get("OCEANBASE_PORT", "2881"),
    "user": os.environ.get("OCEANBASE_USER", "root@test"),
    "password": os.environ.get("OCEANBASE_PASSWORD", ""),
    "db_name": os.environ.get("OCEANBASE_DB", "test"),
}

vector_store = OceanbaseVectorStore(
    embedding_function=None,
    embedding_dim=384,
    connection_args=connection_args,
)
```

--------------------------------

### Filter Type Examples

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/types.md

Examples of filter clauses for metadata filtering in vector stores. Demonstrates filtering by specific fields, JSON values, and complex conditions.

```python
# Filter by metadata field
"metadata->>'category' = 'news'"
```

```python
# Filter by JSON field
"metadata->'year' = 2024"
```

```python
# Complex filter
"metadata->>'category' IN ('tech', 'science') AND id != 'skip-me'"
```

--------------------------------

### Search Parameter Type Examples

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/types.md

Examples of search parameters for vector stores. HNSW uses 'efSearch' for quality/speed trade-off, while IVF uses 'nprobe' for search probes.

```python
{"efSearch": 100}  # Higher = better quality but slower
```

```python
{"nprobe": 16}  # Number of probes for search
```

--------------------------------

### OceanbaseVectorStore Constructor Parameters

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/configuration.md

Full list of parameters for initializing OceanbaseVectorStore, covering embeddings, connection, table schema, and search options.

```python
OceanbaseVectorStore(
    # Embedding
    embedding_function: Optional[Embeddings] = None,
    embedding_dim: Optional[int] = None,
    
    # Connection & table
    connection_args: Optional[Dict[str, Any]] = None,
    table_name: str = "langchain_vector",
    
    # Vector index parameters
    index_type: str = "HNSW",
    vidx_metric_type: str = "l2",
    vidx_algo_params: Optional[Dict] = None,
    vidx_name: str = "vidx",
    
    # Table schema
    primary_field: str = "id",
    vector_field: str = "embedding",
    text_field: str = "document",
    metadata_field: Optional[str] = "metadata",
    
    # Advanced
    normalize: bool = False,
    drop_old: bool = False,
    partitions: Optional[Any] = None,
    extra_columns: Optional[List[Column]] = None,
    
    # Hybrid search
    include_sparse: bool = False,
    include_fulltext: bool = False,
    
    # Additional client args
    **kwargs: Any,
)
```

--------------------------------

### OceanBaseCheckpointSaver Setup

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/INDEX.md

Set up and compile a Langchain application with OceanBaseCheckpointSaver for state persistence. This involves providing connection arguments and integrating the checkpointer into the application compilation process.

```python
checkpointer = OceanBaseCheckpointSaver(connection_args={...})
checkpointer.setup()
app = graph.compile(checkpointer=checkpointer)
```

--------------------------------

### Create Hotfix Branch

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/CONTRIBUTING.md

Create a new branch for hotfixes starting from the 'main' branch.

```bash
git checkout -b hotfix/restore-ci origin/main
```

--------------------------------

### Initialize OceanBaseCheckpointSaver (Recommended)

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/api-reference-chat-message-histories.md

Shows the recommended approach using OceanBaseCheckpointSaver with LangGraph. This is the preferred method for managing chat history.

```python
from langchain_oceanbase import OceanBaseCheckpointSaver

# ✅ Recommended approach instead
connection_args = {
    "host": "127.0.0.1",
    "port": "2881",
    "user": "root@test",
    "password": "",
    "db_name": "test",
}
checkpointer = OceanBaseCheckpointSaver(connection_args=connection_args)
checkpointer.setup()
# Use with LangGraph instead
```

--------------------------------

### Create Release Branch

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/CONTRIBUTING.md

Create a new branch for a release starting from the 'develop' branch.

```bash
git checkout -b release/0.3.4 origin/develop
```

--------------------------------

### Run Unit Tests

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

Execute unit tests using `make test`. This command does not require a database connection.

```bash
make test
```

--------------------------------

### Create Bugfix Branch

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/CONTRIBUTING.md

Create a new branch for bug fixes starting from the 'develop' branch.

```bash
git checkout -b bugfix/fix-seekdb-timeout origin/develop
```

--------------------------------

### Create Feature Branch

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/CONTRIBUTING.md

Create a new branch for feature development starting from the 'develop' branch.

```bash
git checkout -b feature/onboard-docker-compose origin/develop
```

--------------------------------

### Configure Database Connection Arguments

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/ai_functions.md

Sets up the connection parameters required to establish a connection to the OceanBase database.

```python
connection_args = {
    "host": "127.0.0.1",        # OceanBase server address
    "port": "2881",             # OceanBase port
    "user": "root@test",        # Database username (format: username@tenant)
    "password": "",              # Database password
    "db_name": "test",          # Database name
}
```

--------------------------------

### Configuration for Thread-Based Organization

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/migration_guide.md

Example of setting the `thread_id` in the configuration dictionary to manage distinct conversations.

```python
config = {"configurable": {"thread_id": "conversation-123"}}
```

--------------------------------

### Get and Put Checkpoint

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/_autodocs/INDEX.md

Retrieve an existing checkpoint configuration and then update it with new metadata and values.

```python
# Separate read/write patterns
checkpoint = checkpointer.get_checkpoint(config)
checkpointer.put_checkpoint(config, checkpoint, metadata, values)
```

--------------------------------

### Get Item by Key from Store

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/langgraph_store.ipynb

Retrieves a specific item from the OceanBaseStore using its namespace and key.

```python
exact_item = store.get(namespace, "favorite-language")
exact_item
```

--------------------------------

### Initialize OceanbaseVectorStore with Connection Arguments

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/vectorstores.md

Initializes the OceanbaseVectorStore with specific connection parameters for a deployed OceanBase instance. Ensure the connection details match your deployment.

```python
import os

from langchain_oceanbase.embedding_utils import DefaultEmbeddingFunctionAdapter

from langchain_oceanbase.vectorstores import OceanbaseVectorStore


connection_args = {
    "host": "127.0.0.1",
    "port": "2881",
    "user": "root@test",
    "password": "",
    "db_name": "test",
}

embeddings = DefaultEmbeddingFunctionAdapter()

vector_store = OceanbaseVectorStore(
    embedding_function=embeddings,
    table_name="langchain_vector",
    connection_args=connection_args,
    vidx_metric_type="l2",
    drop_old=True,
)
```

--------------------------------

### Enable Sparse Vector Support

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

Initialize `OceanbaseVectorStore` with `include_sparse=True` to enable sparse vector capabilities.

```python
# Enable sparse vector support
vector_store = OceanbaseVectorStore(
    include_sparse=True,
    ...
)
```

--------------------------------

### Before: Old ChatMessageHistory Pattern

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/migration_guide.md

Example of using the legacy OceanBaseChatMessageHistory to create and manage message history manually.

```python
from langchain_oceanbase import OceanBaseChatMessageHistory
from langchain_core.messages import HumanMessage, AIMessage

# Create message history
history = OceanBaseChatMessageHistory(
    table_name="chat_messages",
    connection_args={
        "host": "127.0.0.1",
        "port": "2881",
        "user": "root@test",
        "password": "",
        "db_name": "test",
    }
)

# Add messages manually
history.add_message(HumanMessage(content="Hello"))
history.add_message(AIMessage(content="Hi there!"))

# Retrieve messages
messages = history.messages
```

--------------------------------

### Initialize Server Mode Components

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/README.md

Instantiate saver, store, and vector store components for server mode connections. Note that MySQL only supports checkpoint and store, not vector store.

```python
saver = OceanBaseCheckpointSaver(connection_args=connection_args)
store = OceanBaseStore(connection_args=connection_args)
vector_store = OceanbaseVectorStore(
    embedding_function=my_embeddings,
    table_name="my_vectors",
    connection_args=connection_args,
    embedding_dim=384,
)
```

--------------------------------

### Upgrade pyseekdb

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/vectorstores.md

Upgrades pyseekdb to ensure the correct platform wheel for pylibseekdb is installed, necessary for embedded SeekDB.

```bash
pip install -U "pyseekdb>=1.2"
```

--------------------------------

### Simple Chatbot Migration: Before

Source: https://github.com/oceanbase/langchain-oceanbase/blob/develop/docs/migration_guide.md

Illustrates the 'before' state of a simple chatbot using OceanBaseChatMessageHistory for message storage and manual chain invocation.

```python
history = OceanBaseChatMessageHistory(...)
chain = prompt | llm | StrOutputParser()

for message in user_messages:
    history.add_message(HumanMessage(content=message))
    response = chain.invoke({"messages": history.messages})
    history.add_message(AIMessage(content=response))
```