E-commerce product search with full-text search
+ + +## Prerequisites + +Before you begin, ensure you have the following: + +- **Python (>=3.10)**: Install [Python](https://www.python.org/downloads/) 3.10 or a later version. +- **A TiDB Cloud Starter cluster**: You can create a free TiDB cluster on [TiDB Cloud](https://tidbcloud.com/free-trial). + +## How to run + +### Step 1. Clone the `pytidb` repository + +[`pytidb`](https://github.com/pingcap/pytidb) is the official Python SDK for TiDB, designed to help developers build AI applications efficiently. + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/fulltext_search/ +``` + +### Step 2. Install the required packages and set up the environment + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r reqs.txt +``` + +### Step 3. Set environment variables + +1. In the [TiDB Cloud console](https://tidbcloud.com/), navigate to the [**Clusters**](https://tidbcloud.com/clusters) page, and then click the name of your target cluster to go to its overview page. +2. Click **Connect** in the upper-right corner. A connection dialog is displayed, with connection parameters listed. +3. Set environment variables according to the connection parameters as follows: + +```bash +cat > .env <TiDB Hybrid Search Demo
+ + +## Prerequisites + +Before you begin, ensure you have the following: + +- **Python (>=3.10)**: Install [Python](https://www.python.org/downloads/) 3.10 or a later version. +- **A TiDB Cloud Starter cluster**: You can create a free TiDB cluster on [TiDB Cloud](https://tidbcloud.com/free-trial). +- **OpenAI API key**: Get an OpenAI API key from [OpenAI](https://platform.openai.com/api-keys). + +> **Note** +> +> Currently, full-text search is available only in the following product option and regions: +> +> - TiDB Cloud Starter: Frankfurt (`eu-central-1`), Singapore (`ap-southeast-1`) + +## How to run + +### Step 1. Clone the `pytidb` repository + +[pytidb](https://github.com/pingcap/pytidb) is the official Python SDK for TiDB, designed to help developers build AI applications efficiently. + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/hybrid_search +``` + +### Step 2. Install the required packages and set up the environment + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r reqs.txt +``` + +### Step 3. Set environment variables + +1. In the [TiDB Cloud console](https://tidbcloud.com/), navigate to the [**Clusters**](https://tidbcloud.com/clusters) page, and then click the name of your target cluster to go to its overview page. +2. Click **Connect** in the upper-right corner. A connection dialog is displayed, with connection parameters listed. +3. Set environment variables according to the connection parameters as follows: + +```bash +cat > .env <
+
+
Pet image search via multimodal embeddings
+ + +## Prerequisites + +Before you begin, ensure you have the following: + +- **Python (>=3.10)**: Install [Python](https://www.python.org/downloads/) 3.10 or a later version. +- **A TiDB Cloud Starter cluster**: You can create a free TiDB cluster on [TiDB Cloud](https://tidbcloud.com/free-trial). +- **Jina AI API key**: You can get a free API key from [Jina AI Embeddings](https://jina.ai/embeddings/). + +## How to run + +### Step 1. Clone the `pytidb` repository + +[`pytidb`](https://github.com/pingcap/pytidb) is the official Python SDK for TiDB, designed to help developers build AI applications efficiently. + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/image_search/ +``` + +### Step 2. Install the required packages + +```bash +python -m venv .venv +source .venv/bin/activate # Windows: .venv\Scripts\activate +pip install -r reqs.txt +``` + +### Step 3. Set environment variables + +1. In the [TiDB Cloud console](https://tidbcloud.com/), navigate to the [**Clusters**](https://tidbcloud.com/clusters) page, and then click the name of your target cluster to go to its overview page. +2. Click **Connect** in the upper-right corner. A connection dialog is displayed, with connection parameters listed. +3. Set environment variables according to the connection parameters as follows: + +```bash +cat > .env <AI Agent with memory powered by TiDB
+ + +## Prerequisites + +Before you begin, ensure you have the following: + +- **Python (>=3.10)**: Install [Python](https://www.python.org/downloads/) 3.10 or a later version. +- **A TiDB Cloud Starter cluster**: You can create a free TiDB cluster on [TiDB Cloud](https://tidbcloud.com/free-trial). +- **OpenAI API key**: Get an OpenAI API key from [OpenAI](https://platform.openai.com/api-keys). + +## How to run + +### Step 1. Clone the `pytidb` repository + +[`pytidb`](https://github.com/pingcap/pytidb) is the official Python SDK for TiDB, designed to help developers build AI applications efficiently. + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/memory/ +``` + +### Step 2. Install the required packages + +```bash +python -m venv .venv +source .venv/bin/activate # Windows: .venv\Scripts\activate +pip install -r reqs.txt +``` + +### Step 3. Set environment variables + +1. In the [TiDB Cloud console](https://tidbcloud.com/), navigate to the [**Clusters**](https://tidbcloud.com/clusters) page, and then click the name of your target cluster to go to its overview page. +2. Click **Connect** in the upper-right corner. A connection dialog is displayed, with connection parameters listed. +3. Set environment variables according to the connection parameters as follows: + +```bash +cat > .env <RAG application built with PyTiDB
+ + +## Prerequisites + +Before you begin, ensure you have the following: + +- **Python (>=3.10)**: Install [Python](https://www.python.org/downloads/) 3.10 or a later version. +- **A TiDB Cloud Starter cluster**: You can create a free TiDB cluster on [TiDB Cloud](https://tidbcloud.com/free-trial). +- **Ollama**: Install from [Ollama](https://ollama.com/download). + +## How to run + +### Step 1. Prepare the inference API + +Pull the embedding and LLM models with the Ollama CLI: + +```bash +ollama pull mxbai-embed-large +ollama pull gemma3:4b +ollama run gemma3:4b +``` + +Verify that the `/embed` and `/generate` endpoints are running: + +```bash +curl http://localhost:11434/api/embed -d '{ + "model": "mxbai-embed-large", + "input": "Llamas are members of the camelid family" +}' +``` + +```bash +curl http://localhost:11434/api/generate -d '{ + "model": "gemma3:4b", + "prompt": "Hello, Who are you?" +}' +``` + +### Step 2. Clone the repository + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/rag/ +``` + +### Step 3. Install the required packages and set up the environment + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r reqs.txt +``` + +### Step 4. Set environment variables + +1. In the [TiDB Cloud console](https://tidbcloud.com/), navigate to the [**Clusters**](https://tidbcloud.com/clusters) page, and then click the name of your target cluster to go to its overview page. +2. Click **Connect** in the upper-right corner. A connection dialog is displayed, with connection parameters listed. +3. Set environment variables according to the connection parameters as follows: + +```bash +cat > .env <
+
+
Semantic search with vector embeddings
+ + +## Prerequisites + +Before you begin, ensure you have the following: + +- **Python (>=3.10)**: Install [Python](https://www.python.org/downloads/) 3.10 or a later version. +- **A TiDB Cloud Starter cluster**: You can create a free TiDB cluster on [TiDB Cloud](https://tidbcloud.com/free-trial). +- **Ollama**: Install from [Ollama](https://ollama.com/download). + +## How to run + +### Step 1. Start the embedding service with Ollama + +Pull the embedding model: + +```bash +ollama pull mxbai-embed-large +``` + +Verify that the embedding service is running: + +```bash +curl http://localhost:11434/api/embed -d '{ + "model": "mxbai-embed-large", + "input": "Llamas are members of the camelid family" +}' +``` + +### Step 2. Clone the repository + +```bash +git clone https://github.com/pingcap/pytidb.git +cd pytidb/examples/vector_search/ +``` + +### Step 3. Install the required packages and set up the environment + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r reqs.txt +``` + +### Step 4. Set environment variables + +1. In the [TiDB Cloud console](https://tidbcloud.com/), navigate to the [**Clusters**](https://tidbcloud.com/clusters) page, and then click the name of your target cluster to go to its overview page. +2. Click **Connect** in the upper-right corner. A connection dialog is displayed, with connection parameters listed. +3. Set environment variables according to the connection parameters as follows: + + ```bash + cat > .env <
+
+You can [create a TiDB Cloud Starter cluster](https://tidbcloud.com/free-trial/), and then get the connection parameters from the web console as follows:
+
+1. Navigate to the [Clusters page](https://tidbcloud.com/clusters), and then click the name of your target cluster to go to its overview page.
+2. Click **Connect** in the upper-right corner. A connection dialog is displayed, with connection parameters listed.
+3. Copy the connection parameters to your code or environment variables.
+
+Example code:
+
+```python title="main.py"
+from pytidb import TiDBClient
+
+db = TiDBClient.connect(
+ host="{gateway-region}.prod.aws.tidbcloud.com",
+ port=4000,
+ username="{prefix}.root",
+ password="{password}",
+ database="test",
+)
+```
+
+> **Note:**
+>
+> For TiDB Cloud Starter, [TLS connection to the database](https://docs.pingcap.com/tidbcloud/secure-connections-to-starter-clusters/) is required when using a public endpoint. The `pytidb` client **automatically** enables TLS for TiDB Cloud Starter clusters.
+
+
+
+
+Follow [Quick Start with TiDB Self-Managed](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb/#deploy-a-local-test-cluster) to deploy a TiDB cluster for testing.
+
+Example code:
+
+```python title="main.py"
+from pytidb import TiDBClient
+
+db = TiDBClient.connect(
+ host="{tidb_server_host}",
+ port=4000,
+ username="root",
+ password="{password}",
+ database="test",
+)
+```
+
+> **Note:**
+>
+> If you are using `tiup playground` to deploy a TiDB cluster for testing, the default host is `127.0.0.1` and the default password is empty.
+
+
+
+
+You can [create a TiDB Cloud Starter cluster](https://tidbcloud.com/free-trial/), and then get the connection parameters from the web console as follows:
+
+1. Navigate to the [Clusters page](https://tidbcloud.com/clusters), and then click the name of your target cluster to go to its overview page.
+2. Click **Connect** in the upper-right corner. A connection dialog is displayed, with the connection parameters listed.
+3. Copy the connection parameters and construct a connection string in the following format:
+
+```python title="main.py"
+from pytidb import TiDBClient
+
+db = TiDBClient.connect(
+ database_url="mysql+pymysql://{USERNAME}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}?ssl_verify_cert=true&ssl_verify_identity=true",
+)
+```
+
+> **Note:**
+>
+> For TiDB Cloud Starter, [TLS connection to the database](https://docs.pingcap.com/tidbcloud/secure-connections-to-starter-clusters/) is required when using a public endpoint, so you need to set `ssl_verify_cert=true&ssl_verify_identity=true` in the connection string.
+
+
+
+
+You can follow the format below to construct the connection string:
+
+```python title="main.py"
+from pytidb import TiDBClient
+
+db = TiDBClient.connect(
+ database_url="mysql+pymysql://{USERNAME}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}",
+)
+```
+
+> **Note:**
+>
+> If you are using `tiup playground` to deploy a TiDB cluster for testing, the connection string is:
+>
+> ```
+> mysql+pymysql://root:@127.0.0.1:4000/test
+> ```
+
+
+
+
+Assuming you have already [connected to TiDB](/ai/guides/connect.md) using `TiDBClient`:
+
+Create a `documents` table and insert some sample data:
+
+```python
+from pytidb import Session
+from pytidb.schema import TableModel, Field
+from pytidb.sql import select
+
+class Document(TableModel):
+ __tablename__ = "documents"
+ id: int = Field(primary_key=True)
+ title: str = Field(max_length=255)
+
+client.create_table(schema=Document, if_exists="overwrite")
+client.table("documents").truncate()
+client.table("documents").bulk_insert([
+ Document(id=1, title="The Power of Positive Thinking"),
+ Document(id=2, title="The Happiness Advantage"),
+ Document(id=3, title="The Art of Happiness"),
+])
+```
+
+Create a `chunks` table and insert some sample data:
+
+```python
+class Chunk(TableModel):
+ __tablename__ = "chunks"
+ id: int = Field(primary_key=True)
+ text: str = Field(max_length=255)
+ document_id: int = Field(foreign_key="documents.id")
+
+client.create_table(schema=Chunk, if_exists="overwrite")
+client.table("chunks").truncate()
+client.table("chunks").bulk_insert([
+ Chunk(id=1, text="Positive thinking can change your life", document_id=1),
+ Chunk(id=2, text="Happiness leads to success", document_id=2),
+ Chunk(id=3, text="Finding joy in everyday moments", document_id=3),
+])
+```
+
+
+
+
+Create a `documents` table and insert some sample data:
+
+```sql
+CREATE TABLE documents (
+ id INT PRIMARY KEY,
+ title VARCHAR(255) NOT NULL
+);
+
+INSERT INTO documents (id, title) VALUES
+ (1, 'The Power of Positive Thinking'),
+ (2, 'The Happiness Advantage'),
+ (3, 'The Art of Happiness');
+```
+
+Create a `chunks` table and insert some sample data:
+
+```sql
+CREATE TABLE chunks (
+ id INT PRIMARY KEY,
+ text VARCHAR(255) NOT NULL,
+ document_id INT NOT NULL,
+ FOREIGN KEY (document_id) REFERENCES documents(id)
+);
+
+INSERT INTO chunks (id, text, document_id) VALUES
+ (1, 'Positive thinking can change your life', 1),
+ (2, 'Happiness leads to success', 2),
+ (3, 'Finding joy in everyday moments', 3);
+```
+
+
+
+
+```python
+with Session(client.db_engine) as db_session:
+ query = (
+ select(Chunk)
+ .join(Document, Chunk.document_id == Document.id)
+ .where(Document.title == "The Power of Positive Thinking")
+ )
+ chunks = db_session.exec(query).all()
+
+[(c.id, c.text, c.document_id) for c in chunks]
+```
+
+
+
+
+Perform a join query to combine data from the `chunks` and `documents` tables:
+
+```sql
+SELECT c.id, c.text, c.document_id
+FROM chunks c
+JOIN documents d ON c.document_id = d.id
+WHERE d.title = 'The Power of Positive Thinking';
+```
+
+
+
+
+After you [connect to the database](/ai/guides/connect.md) using `pytidb` and obtain a `client` instance, you can create a table with the `create_table` method.
+
+```python hl_lines="12"
+from pytidb.schema import TableModel, Field, VectorField
+from pytidb.datatype import TEXT, JSON
+
+class Item(TableModel):
+ __tablename__ = "items"
+
+ id: int = Field(primary_key=True)
+ content: str = Field(sa_type=TEXT)
+ embedding: list[float] = VectorField(dimensions=3)
+ meta: dict = Field(sa_type=JSON, default_factory=dict)
+
+table = client.create_table(schema=Item, if_exists="overwrite")
+```
+
+The `create_table` method accepts these parameters:
+
+- `schema`: The `TableModel` class that defines your table structure.
+- `if_exists`: The table creation mode.
+ - `raise` (default): Creates the table if it does not exist; raises an error if it already exists.
+ - `skip`: Creates the table if it does not exist; does nothing if it already exists.
+ - `overwrite`: Drops the existing table and creates a new one. This is useful for **testing and development**, but not recommended for production environments.
+
+Once the table is created, you can use the `table` object to insert, update, delete, and query data.
+
+
+
+
+Use the `CREATE TABLE` statement to create a table.
+
+```sql
+CREATE TABLE items (
+ id INT PRIMARY KEY,
+ content TEXT,
+ embedding VECTOR(3),
+ meta JSON
+);
+```
+
+
+
+
+Use the `table.insert()` method to insert a single record into the table.
+
+```python
+table.insert(
+ Item(
+ id=1,
+ content="TiDB is a distributed SQL database",
+ embedding=[0.1, 0.2, 0.3],
+ meta={"category": "database"},
+ )
+)
+```
+
+
+
+
+Use the `INSERT INTO` statement to insert a single record into the table.
+
+```sql
+INSERT INTO items(id, content, embedding, meta)
+VALUES (1, 'TiDB is a distributed SQL database', '[0.1, 0.2, 0.3]', '{"category": "database"}');
+```
+
+
+
+
+Use the `table.bulk_insert()` method to insert multiple records into the table.
+
+```python
+table.bulk_insert([
+ Item(
+ id=2,
+ content="GPT-4 is a large language model",
+ embedding=[0.4, 0.5, 0.6],
+ meta={"category": "llm"},
+ ),
+ Item(
+ id=3,
+ content="LlamaIndex is a Python library for building AI-powered applications",
+ embedding=[0.7, 0.8, 0.9],
+ meta={"category": "rag"},
+ ),
+])
+```
+
+
+
+
+Use the `INSERT INTO` statement to insert multiple records into the table.
+
+```sql
+INSERT INTO items(id, content, embedding, meta)
+VALUES
+ (2, 'GPT-4 is a large language model', '[0.4, 0.5, 0.6]', '{"category": "llm"}'),
+ (3, 'LlamaIndex is a Python library for building AI-powered applications', '[0.7, 0.8, 0.9]', '{"category": "rag"}');
+```
+
+
+
+
+Use the `table.insert()` method with a dictionary to insert a single record into the table.
+
+```python
+table.insert({
+ "id": 1,
+ "content": "TiDB is a distributed SQL database",
+ "embedding": [0.1, 0.2, 0.3],
+ "meta": {"category": "database"},
+})
+```
+
+
+
+
+Use the `INSERT INTO` statement to insert a single record into the table.
+
+```sql
+INSERT INTO items(id, content, embedding, meta)
+VALUES (1, 'TiDB is a distributed SQL database', '[0.1, 0.2, 0.3]', '{"category": "database"}');
+```
+
+
+
+
+Use the `table.save()` method to save a single record to the table.
+
+**Example: Save a new record**
+
+```python
+saved_record = table.save(
+ Item(
+ id=4,
+ content="Vector databases enable AI applications",
+ embedding=[1.0, 1.1, 1.2],
+ meta={"category": "vector-db"},
+ )
+)
+```
+
+**Example: Save an existing record (overwrites the entire record)**
+
+```python
+# This overwrites the entire record with id=1
+updated_record = table.save(
+ Item(
+ id=1, # Existing ID
+ content="Updated content for TiDB",
+ embedding=[0.2, 0.3, 0.4],
+ meta={"category": "updated"},
+ )
+)
+```
+
+
+
+
+Use the `INSERT ... ON DUPLICATE KEY UPDATE` statement to save a record.
+
+**Example: Save a new record or update if it exists**
+
+```sql
+INSERT INTO items(id, content, embedding, meta)
+VALUES (4, 'Vector databases enable AI applications', '[1.0, 1.1, 1.2]', '{"category": "vector-db"}')
+ON DUPLICATE KEY UPDATE
+ content = VALUES(content),
+ embedding = VALUES(embedding),
+ meta = VALUES(meta);
+```
+
+
+
+
+Use the `table.query()` method to fetch records from the table.
+
+**Example: Fetch the first 10 records**
+
+```python
+result = table.query(limit=10).to_list()
+```
+
+
+
+
+Use the `SELECT` statement to fetch the records from the table.
+
+**Example: Fetch the first 10 records**
+
+```sql
+SELECT * FROM items LIMIT 10;
+```
+
+
+
+
+Pass the `filters` parameter to the `table.query()` method.
+
+```python
+result = table.query(
+ filters={"meta.category": "database"},
+ limit=10
+).to_list()
+```
+
+
+
+
+Use the `WHERE` clause to filter records.
+
+**Example: Fetch the 10 records with category "database"**
+
+```sql
+SELECT * FROM items WHERE meta->>'$.category' = 'database' LIMIT 10;
+```
+
+
+
+
+Use the `table.update()` method to update records with [filters](/ai/guides/filtering.md).
+
+**Example: Update the record whose `id` equals 1**
+
+```python
+table.update(
+ values={
+ "content": "TiDB Cloud Starter is a fully managed, auto-scaling cloud database service",
+ "embedding": [0.1, 0.2, 0.4],
+ "meta": {"category": "dbaas"},
+ },
+ filters={
+ "id": 1
+ },
+)
+```
+
+
+
+
+Use the `UPDATE` statement to update records with [filters](/ai/guides/filtering.md).
+
+**Example: Update the record whose `id` equals 1**
+
+```sql
+UPDATE items
+SET
+ content = 'TiDB Cloud Starter is a fully managed, auto-scaling cloud database service',
+ embedding = '[0.1, 0.2, 0.4]',
+ meta = '{"category": "dbaas"}'
+WHERE
+ id = 1;
+```
+
+
+
+
+Use the `table.delete()` method to delete records with [filters](/ai/guides/filtering.md).
+
+**Example: Delete the record where `id` equals 2**
+
+```python
+table.delete(
+ filters={
+ "id": 2
+ }
+)
+```
+
+
+
+
+Use the `DELETE` statement to delete records with [filters](/ai/guides/filtering.md).
+
+**Example: Delete the record where `id` equals 2**
+
+```sql
+DELETE FROM items WHERE id = 2;
+```
+
+
+
+
+To remove all data from the table but keep the table structure, use the `table.truncate()` method.
+
+```python
+table.truncate()
+```
+
+To check that the table is truncated, verify that it contains 0 rows.
+
+```python
+table.rows()
+```
+
+
+
+
+To remove all data from the table but keep the table structure, use the `TRUNCATE TABLE` statement.
+
+```sql
+TRUNCATE TABLE items;
+```
+
+To check that the table is truncated, verify that it contains 0 rows.
+
+```sql
+SELECT COUNT(*) FROM items;
+```
+
+
+
+
+To permanently remove a table from the database, use the `client.drop_table()` method.
+
+```python
+client.drop_table("items")
+```
+
+To check that the table is removed from the database:
+
+```python
+client.table_names()
+```
+
+
+
+
+To permanently remove a table from the database, use the `DROP TABLE` statement.
+
+```sql
+DROP TABLE items;
+```
+
+To check that the table is removed from the database:
+
+```sql
+SHOW TABLES;
+```
+
+
+
+
+You can use `client.create_table()` to create a table and `VectorField` to define a vector field.
+
+The following example creates a `documents` table with four columns:
+
+- `id`: The primary key of the table.
+- `text`: The text content of the document.
+- `text_vec`: The vector embedding of the text content.
+- `meta`: The metadata of the document, which is a JSON object.
+
+```python hl_lines="9"
+from pytidb.schema import TableModel, Field, VectorField
+from pytidb.datatype import TEXT, JSON
+
+class Document(TableModel):
+ __tablename__ = "documents"
+
+ id: int = Field(primary_key=True)
+ text: str = Field(sa_type=TEXT)
+ text_vec: list[float] = VectorField(dimensions=3)
+ meta: dict = Field(sa_type=JSON, default_factory=dict)
+
+table = client.create_table(schema=Document, if_exists="overwrite")
+```
+
+The `VectorField` class accepts the following parameters:
+
+- `dimensions`: The vector dimension. Once specified, only vectors with this exact dimension can be stored in this field.
+- `index`: Whether to create a [vector index](https://docs.pingcap.com/tidbcloud/vector-search-index/) for the vector field. Defaults to `True`.
+- `distance_metric`: The distance metric to use for the vector index. Supported values:
+ - `DistanceMetric.COSINE` (default): Cosine distance metric, suitable for measuring text similarity
+ - `DistanceMetric.L2`: L2 distance metric, suitable for capturing overall difference
+
+
+
+
+Use the `CREATE TABLE` statement to create a table and use the `VECTOR` type to define a vector column.
+
+```sql hl_lines="4 5"
+CREATE TABLE documents (
+ id INT PRIMARY KEY,
+ text TEXT,
+ text_vec VECTOR(3),
+ VECTOR INDEX `vec_idx_text_vec`((VEC_COSINE_DISTANCE(`text_vec`)))
+);
+```
+
+In this example:
+
+- The `text_vec` column is defined as `VECTOR(3)`, so vectors stored in this column must have 3 dimensions.
+- A vector index is created using the `VEC_COSINE_DISTANCE` function to optimize vector search performance.
+
+TiDB supports two distance functions for vector indexes:
+
+- `VEC_COSINE_DISTANCE`: Calculates the cosine distance between two vectors
+- `VEC_L2_DISTANCE`: Calculates L2 distance (Euclidean distance) between two vectors
+
+
+
+
+```python
+table.bulk_insert([
+ Document(text="dog", text_vec=[1,2,1], meta={"category": "animal"}),
+ Document(text="fish", text_vec=[1,2,4], meta={"category": "animal"}),
+ Document(text="tree", text_vec=[1,0,0], meta={"category": "plant"}),
+])
+```
+
+
+
+
+```sql
+INSERT INTO documents (id, text, text_vec, meta)
+VALUES
+ (1, 'dog', '[1,2,1]', '{"category": "animal"}'),
+ (2, 'fish', '[1,2,4]', '{"category": "animal"}'),
+ (3, 'tree', '[1,0,0]', '{"category": "plant"}');
+```
+
+> **Note:**
+>
+> In real-world applications, embeddings are usually generated by an [embedding model](/ai/concepts/vector-search-overview.md#embedding-model).
+
+For convenience, pytidb provides an auto embedding feature that can automatically generate vector embeddings for your text fields when you insert, update, or search—no manual processing needed.
+
+For details, see the [Auto Embedding](/ai/guides/auto-embedding.md) guide.
+
+
+
+
+Use the `table.search()` method to perform vector search. It uses `search_mode="vector"` by default.
+
+```python
+table.search([1, 2, 3]).limit(3).to_list()
+```
+
+```python title="Execution result"
+[
+ {"id": 2, "text": "fish", "text_vec": [1,2,4], "_distance": 0.00853986601633272},
+ {"id": 1, "text": "dog", "text_vec": [1,2,1], "_distance": 0.12712843905603044},
+ {"id": 3, "text": "tree", "text_vec": [1,0,0], "_distance": 0.7327387580875756},
+]
+```
+
+The result shows that the most relevant document is `fish` with a distance of `0.00853986601633272`.
+
+
+
+
+Use the `ORDER BY (, ) LIMIT ` clause in a `SELECT` statement to get the `n` nearest neighbors of a query vector.
+
+The following example uses the `vec_cosine_distance` function to calculate the cosine distance between the vectors stored in the `text_vec` column and the provided query vector `[1, 2, 3]`.
+
+```sql
+SELECT id, text, vec_cosine_distance(text_vec, '[1,2,3]') AS distance
+FROM documents
+ORDER BY distance
+LIMIT 3;
+```
+
+```plain title="Execution result"
++----+----------+---------------------+
+| id | text | distance |
++----+----------+---------------------+
+| 2 | fish | 0.00853986601633272 |
+| 1 | dog | 0.12712843905603044 |
+| 3 | tree | 0.7327387580875756 |
++----+----------+---------------------+
+3 rows in set (0.15 sec)
+```
+
+The result shows that the most relevant document is `fish` with a distance of `0.00853986601633272`.
+
+
+
+
+The `table.search()` API supports the following distance metrics:
+
+| Metric Name | Description | Best For |
+|--------------------------|----------------------------------------------------------------|----------|
+| `DistanceMetric.COSINE` | Calculates the cosine distance between two vectors (default). Measures the angle between vectors. | Text embeddings, semantic search |
+| `DistanceMetric.L2` | Calculates the L2 distance (Euclidean distance) between two vectors. Measures the straight-line distance. | Image features |
+
+To change the distance metric used for vector search, use the `.distance_metric()` method.
+
+**Example: Use the L2 distance metric**
+
+```python
+from pytidb.schema import DistanceMetric
+
+results = (
+ table.search([1, 2, 3])
+ .distance_metric(DistanceMetric.L2)
+ .limit(10)
+ .to_list()
+)
+```
+
+
+
+
+In SQL, you can use the following built-in functions to calculate vector distances directly in your queries:
+
+| Function Name | Description |
+|-------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|
+| [`VEC_L2_DISTANCE`](https://docs.pingcap.com/tidbcloud/vector-search-functions-and-operators/#vec_l2_distance) | Calculates L2 distance (Euclidean distance) between two vectors |
+| [`VEC_COSINE_DISTANCE`](https://docs.pingcap.com/tidbcloud/vector-search-functions-and-operators/#vec_cosine_distance) | Calculates the cosine distance between two vectors |
+| [`VEC_NEGATIVE_INNER_PRODUCT`](https://docs.pingcap.com/tidbcloud/vector-search-functions-and-operators/#vec_negative_inner_product) | Calculates the negative of the inner product between two vectors|
+| [`VEC_L1_DISTANCE`](https://docs.pingcap.com/tidbcloud/vector-search-functions-and-operators/#vec_l1_distance) | Calculates L1 distance (Manhattan distance) between two vectors |
+
+
+
+
+Use the `.distance_threshold()` method to set a maximum distance for search results. Only records with a distance less than the threshold are returned.
+
+**Example: Only return documents with a distance less than 0.5**
+
+```python
+results = table.search([1, 2, 3]).distance_threshold(0.5).limit(10).to_list()
+```
+
+
+
+
+In SQL, use the `HAVING` clause with a distance function to filter results by distance:
+
+**Example: Only return documents with a distance less than 0.1**
+
+```sql
+SELECT id, text, vec_cosine_distance(text_vec, '[1,2,3]') AS distance
+FROM documents
+HAVING distance < 0.1
+ORDER BY distance
+LIMIT 10;
+```
+
+
+
+
+Use the `.distance_range()` method to set both minimum and maximum distance values. Only records with a distance within this range are returned.
+
+**Example: Only return documents with a distance between 0.01 and 0.05**
+
+```python
+results = table.search([1, 2, 3]).distance_range(0.01, 0.05).limit(10).to_list()
+```
+
+
+
+
+To specify a distance range in SQL, use `BETWEEN` or other comparison operators in the `HAVING` clause:
+
+**Example: Only return documents with a distance between 0.01 and 0.05**
+
+```sql
+SELECT id, text, vec_l2_distance(text_vec, '[1,2,3]') AS distance
+FROM documents
+HAVING distance BETWEEN 0.01 AND 0.05
+ORDER BY distance
+LIMIT 10;
+```
+
+
+
+
+Use the `.filter()` method with a filter dictionary to apply filtering to vector search.
+
+By default, the `table.search()` API uses post-filtering mode to maximize search performance with the vector index.
+
+**Example: Vector search with post-filtering**
+
+```python
+results = (
+ table.search([1, 2, 3])
+ # The `meta` is a JSON field, and its value is a JSON object
+ # like {"category": "animal"}
+ .filter({"meta.category": "animal"})
+ .num_candidate(50)
+ .limit(10)
+ .to_list()
+)
+```
+
+> **Note:**
+>
+> When using a vector index, if the final `limit` is very small, the accuracy of the results might decrease. You can use the `.num_candidate()` method to control how many candidates to retrieve from the vector index during the vector search phase, without changing the `limit` parameter.
+
+> A higher `num_candidate` value generally improves recall but might reduce query performance. Adjust this value based on your dataset and accuracy requirements.
+
+
+
+
+Currently, vector indexes are only effective in strict ANN (Approximate Nearest Neighbor) queries, such as:
+
+```sql
+SELECT * FROM ORDER BY
