pytidb

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PyTiDB (pytidb)

Use this skill to connect to TiDB from Python via

pytidb

, define tables, and build search / AI features on top.

使用本Skill通过

pytidb

从Python连接到TiDB，定义表结构，并在其之上构建搜索与AI功能。

When to Use This Skill

何时使用本Skill

You want a Python ORM-like experience on TiDB via
```
pytidb
```
(built on SQLAlchemy).
You want vector search / full-text search / hybrid search on TiDB with high-level APIs.
You want runnable starter templates (scripts + small examples) you can adapt.

Need to provision a TiDB Cloud cluster first? Use

tidbx

(TiDB X) for cluster lifecycle guidance.

你希望通过
```
pytidb
```
（基于SQLAlchemy）在TiDB上获得类Python ORM的使用体验。
你希望通过高级API在TiDB上实现向量搜索/全文搜索/混合搜索。
你需要可直接运行的入门模板（脚本+小型示例）并进行适配。

需要先部署TiDB Cloud集群？ 使用

tidbx

（TiDB X）获取集群生命周期管理指导。

Code Generation Rules (Python)

代码生成规则（Python）

Never hardcode credentials; use env vars (
```
.env
```
) and document required variables.
Prefer
```
python -m venv .venv
```
and pinned deps for reproducibility.
When editing requirements.txt, do not invent pytidb versions, use an unpinned pytidb by default unless the user explicitly requests it and the version has been verified to exist.
Keep examples minimal and runnable; avoid framework-specific assumptions unless the user asks.
Use parameterized SQL for any dynamic value (SQL injection safety).
For interactive environments, avoid “table already defined” errors (use
```
extend_existing
```
/
```
open_table
```
/
```
if rows()==0
```
patterns).

切勿硬编码凭证；使用环境变量（
```
.env
```
）并记录所需变量。
优先使用
```
python -m venv .venv
```
和固定版本的依赖以保证可复现性。
编辑requirements.txt时，不要自定义pytidb版本，默认使用未固定版本，除非用户明确要求且该版本已验证存在。
保持示例简洁可运行；除非用户要求，否则避免依赖特定框架。
任何动态值都使用参数化SQL（防止SQL注入）。
在交互式环境中，避免“表已定义”错误（使用
```
extend_existing
```
/
```
open_table
```
/
```
if rows()==0
```
等模式）。

Available Guides

可用指南

Each guide is a self-contained walkthrough with a checklist and phases:

```
guides/quickstart.md
```
— one-file “connect → create table → insert → vector search”
```
guides/search.md
```
— vector / full-text / hybrid: when to use which, plus gotchas
```
guides/demos.md
```
— examples playbook (vector/hybrid/image)
```
guides/agent-apps.md
```
— agent-ish examples (RAG / memory / text2sql)
```
guides/troubleshooting.md
```
— connection, TLS, embedding, and index/search issues
```
guides/custom-embedding.md
```
— implement a custom embedding function (example: BGE-M3)

I’ll infer your intent (CRUD vs search vs “agent app”), then point you to the smallest guide and template set that gets you running.

每个指南都是包含检查清单和阶段的独立教程：

```
guides/quickstart.md
```
— 单文件指南：连接→创建表→插入→向量搜索
```
guides/search.md
```
— 向量/全文/混合搜索：适用场景与注意事项
```
guides/demos.md
```
— 示例手册（向量/混合/图像）
```
guides/agent-apps.md
```
— 面向Agent的示例（RAG/记忆/Text2SQL）
```
guides/troubleshooting.md
```
— 连接、TLS、嵌入与索引/搜索问题排查
```
guides/custom-embedding.md
```
— 实现自定义嵌入函数（示例：BGE-M3）

我会推断你的需求（CRUD操作 vs 搜索 vs “Agent应用”），然后为你推荐最适合的最简指南与模板集。

Templates & Scripts

模板与脚本

Each template is a complete file you can copy into your project. Choose the smallest one that matches your goal.

每个模板都是可直接复制到项目中的完整文件。选择与你的目标最匹配的最小模板。

Core usage

核心用法

```
templates/quickstart.py
```
— minimal end-to-end: connect → create table → insert → vector search
```
templates/crud.py
```
— basic table modeling + CRUD lifecycle (create/truncate/insert/query/update/delete)
```
templates/auto_embedding.py
```
— auto embedding with pluggable providers (env-driven)
```
templates/vector_search.py
```
— vector search example (optional metadata filter + threshold)
```
templates/hybrid_search.py
```
— hybrid search example (FullTextField + vector field) with fused scoring

```
templates/quickstart.py
```
— 极简端到端示例：连接→创建表→插入→向量搜索
```
templates/crud.py
```
— 基础表建模+CRUD生命周期（创建/清空/插入/查询/更新/删除）
```
templates/auto_embedding.py
```
— 支持可插拔提供商的自动嵌入（由环境变量驱动）
```
templates/vector_search.py
```
— 向量搜索示例（可选元数据过滤+阈值）
```
templates/hybrid_search.py
```
— 混合搜索示例（FullTextField+向量字段），融合评分

Image search

图像搜索

```
templates/image_search.py
```
— image-to-image or text-to-image search (requires multimodal embedding + Pillow)

templates/image_search_data_loader.py

— loads Oxford Pets dataset into TiDB (used by

image_search.py

)

```
templates/image_search.py
```
— 图搜图或文搜图（需要多模态嵌入+Pillow）
```
templates/image_search_data_loader.py
```
— 将Oxford Pets数据集加载到TiDB（供
```
image_search.py
```
使用）

Custom embeddings

自定义嵌入

templates/custom_embedding_function.py

— example

BaseEmbeddingFunction

implementation (BGE-M3 via FlagEmbedding)

```
templates/custom_embedding.py
```
— uses the custom embedder with auto embedding + vector search

templates/custom_embedding_function.py

—

BaseEmbeddingFunction

实现示例（通过FlagEmbedding的BGE-M3）

```
templates/custom_embedding.py
```
— 将自定义嵌入器与自动嵌入+向量搜索结合使用

Agent-ish examples

面向Agent的示例

```
templates/rag.py
```
— minimal RAG: retrieve via vector search, then generate via local LLM (Ollama via LiteLLM)
```
templates/memory_lib.py
```
— reusable “memory” library (extract facts → store → retrieve)
```
templates/memory.py
```
— CLI memory chat example using
```
memory_lib.py
```
```
templates/text2sql.py
```
— interactive Text2SQL (generates SQL via OpenAI; asks before executing)

```
templates/rag.py
```
— 极简RAG：通过向量搜索检索，再通过本地LLM生成（Ollama via LiteLLM）
```
templates/memory_lib.py
```
— 可复用的“记忆”库（提取事实→存储→检索）
```
templates/memory.py
```
— 使用
```
memory_lib.py
```
的CLI记忆聊天示例
```
templates/text2sql.py
```
— 交互式Text2SQL（通过OpenAI生成SQL；执行前会确认）

Scripts

脚本

```
scripts/validate_connection.py
```
— quick connection +
```
SELECT 1
```
smoke test (supports params or
```
DATABASE_URL
```
)

scripts/validate_connection.py

— 快速连接+

SELECT 1

冒烟测试（支持参数或

DATABASE_URL

）

Related Skills

Workflow

工作流程

I will:

Confirm your TiDB deployment (Cloud Starter vs self-managed) and how you want to connect (params vs
```
DATABASE_URL
```
).
Help you set env vars, validate the connection, and choose the right path:
- CRUD/table modeling
- vector/full-text/hybrid search (and embedding provider)
- example templates
Generate the minimal set of files and commands to get you running.

我会：

确认你的TiDB部署类型（Cloud Starter vs 自托管）以及连接方式（参数 vs
```
DATABASE_URL
```
）。
帮助你设置环境变量、验证连接，并选择合适的路径：
- CRUD/表建模
- 向量/全文/混合搜索（以及嵌入提供商）
- 示例模板
生成让你快速上手的最小文件集与命令。

pytidb

Original

Translation

PyTiDB (pytidb)

PyTiDB (pytidb)

When to Use This Skill

何时使用本Skill

Code Generation Rules (Python)

代码生成规则（Python）

Available Guides

可用指南

Templates & Scripts

模板与脚本

Core usage

核心用法

Image search

图像搜索

Custom embeddings

自定义嵌入

Agent-ish examples

面向Agent的示例

Scripts

脚本

Related Skills

相关Skill

Workflow

工作流程