插入数据

最近更新时间:2025-02-24 19:45:02

我的收藏

接口定义

upsert() 接口用于在 Base 类数据库创建的 Collection 中插入向量数据。
def upsert(
documents: List[Document | Dict],
timeout: float | None = None,
build_index: bool = True,
**kwargs: Any
) -> Any

使用示例

说明:
在插入数据时, Collection 中已经存在相同 ID 的 Document,则会删除源 Document 后插入新的 Document 数据。
如果 Collection 在创建时,配置 Embedding 参数,则插入文本,Embedding 服务会自动将文本信息转换为向量数据,存入数据库。
写入向量数据
写入原始文本
写入稠密向量 + 稀疏向量
原始文本 + 稀疏向量
写入二进制数据
写入 json 格式的数据
如果您无需使用腾讯云向量数据库(Tencent Cloud VectorDB)的 Embedding 功能做向量化,则可以直接写入向量数据。
import tcvectordb
from tcvectordb.model.document import Document

# 写入数据。
# 参数 build_index 为 True,指写入数据同时重新创建索引。
res = client.upsert(
database_name='db-test',
collection_name='book-vector',
documents=[
Document(id='0001', vector=[
0.2123, 0.23, 0.213], author='罗贯中', bookName='三国演义', page=21, tags=['曹操','诸葛亮','刘备']),
Document(id='0002', vector=[
0.2123, 0.22, 0.213], author='吴承恩', bookName='西游记', page=22, tags=['孙悟空','猪八戒','唐僧']),
Document(id='0003', vector=[
0.2123, 0.21, 0.213], author='曹雪芹', bookName='红楼梦', page=23, tags=['贾宝玉','林黛玉','王熙凤'])
],
build_index=True
)
print(res, flush=True)
如果您使用 Embedding 功能,在 create_collection() 建表时,配置 Embedding 模型相关参数之后,便可以通过 upsert() 接口可直接传入原始文本。Embedding 模型会将原始文本转换为向量数据,并将转换后的向量数据以及原始文本一并存入数据库。具体信息,请参见 Embedding 介绍。如下示例,基于 create_collection() 创建的集合 book-emb,写入原始文本。
import tcvectordb
from tcvectordb.model.document import Document

# 写入数据。
# 参数 build_index 为 True,指写入数据同时重新创建索引。
res = client.upsert(
database_name='db-test',
collection_name='book-emb',
documents=[
Document(id='0001', text="话说天下大势,分久必合,合久必分。", author='罗贯中', bookName='三国演义', page=21, tags=['曹操','诸葛亮','刘备']),
Document(id='0002', text="混沌未分天地乱,茫茫渺渺无人间。", author='吴承恩', bookName='西游记', page=22, tags=['孙悟空','猪八戒','唐僧']),
Document(id='0003', text="甄士隐梦幻识通灵,贾雨村风尘怀闺秀。", author='曹雪芹', bookName='红楼梦', page=23, tags=['贾宝玉','林黛玉','王熙凤'])
],
build_index=True
)
print(res, flush=True)
如果您无需使用腾讯云向量数据库(Tencent Cloud VectorDB)的 Embedding 功能做向量化,则可以直接写入向量数据与稀疏向量。
import tcvectordb
from tcvectordb.model.document import Document
from tcvdb_text.encoder.bm25 import BM25Encoder

texts = [
'《三国演义》是元末明初罗贯中创作的长篇章回体历史演义小说',
'《西游记》是明代吴承恩创作的长篇章回体神魔小说',
'《红楼梦》是清代曹雪芹创作的长篇章回体小说',
]

bm25 = BM25Encoder.default('zh')
sparse_vectors: List[SparseVector] = bm25.encode_texts(texts)

# 写入数据。
# 参数 build_index 为 True,指写入数据同时重新创建索引。
res = client.upsert(
database_name='db-test',
collection_name='book-vector',
documents=[
Document(id='0001', vector=[
0.1123, 0.13, 0.113], sparse_vector=sparse_vectors[0], author='罗贯中', bookName='三国演义', page=21, tags=['曹操','诸葛亮','刘备']),
Document(id='0002', vector=[
0.5123, 0.52, 0.513], sparse_vector=sparse_vectors[0], author='吴承恩', bookName='西游记', page=22, tags=['孙悟空','猪八戒','唐僧']),
Document(id='0003', vector=[
0.9123, 0.91, 0.913], sparse_vector=sparse_vectors[0], author='曹雪芹', bookName='红楼梦', page=23, tags=['贾宝玉','林黛玉','王熙凤'])
],
build_index=True
)
print(res, flush=True)
from typing import List
import tcvectordb
from tcvectordb.model.document import Document
from tcvdb_text.encoder.bm25 import BM25Encoder

texts = [
'腾讯云向量数据库(Tencent Cloud VectorDB)是一款全托管的自研企业级分布式数据库服务,专用于存储、索引、检索、管理由深度神经网络或其他机器学习模型生成的大量多维嵌入向量。',
'作为专门为处理输入向量查询而设计的数据库,它支持多种索引类型和相似度计算方法,单索引支持10亿级向量规模,高达百万级 QPS 及毫秒级查询延迟。',
'不仅能为大模型提供外部知识库,提高大模型回答的准确性,还可广泛应用于推荐系统、NLP 服务、计算机视觉、智能客服等 AI 领域。',
'腾讯云向量数据库(Tencent Cloud VectorDB)作为一种专门存储和检索向量数据的服务提供给用户, 在高性能、高可用、大规模、低成本、简单易用、稳定可靠等方面体现出显著优势。 ',
'腾讯云向量数据库可以和大语言模型 LLM 配合使用。企业的私域数据在经过文本分割、向量化后,可以存储在腾讯云向量数据库中,构建起企业专属的外部知识库,从而在后续的检索任务中,为大模型提供提示信息,辅助大模型生成更加准确的答案。',
]

bm25 = BM25Encoder.default('zh')
sparse_vectors: List[SparseVector] = bm25.encode_texts(texts)
# 写入数据。
# 参数 build_index 为 True,指写入数据同时重新创建索引。
res = client.upsert(
database_name='db-test',
collection_name='book-emb',
documents=[
{'id': '0001', 'text': texts[0], 'sparse_vector': sparse_vectors[0]},
{'id': '0002', 'text': texts[1], 'sparse_vector': sparse_vectors[1]},
{'id': '0003', 'text': texts[2], 'sparse_vector': sparse_vectors[2]},
{'id': '0004', 'text': texts[3], 'sparse_vector': sparse_vectors[3]},
]
)
print(res, flush=True)
import tcvectordb
from tcvectordb.model.document import Document

# 写入数据。
# 参数 build_index 为 True,指写入数据同时重新创建索引。
res = client.upsert(
database_name='db-test',
collection_name='bin-vector',
documents=[
Document(id='0001',
vector=binary_to_uint8([1, 1, 1, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0]),
bookName='西游记'),
Document(id='0002',
vector=binary_to_uint8([1, 1, 0, 0, 1, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0]),
bookName='西游记'),
Document(id='0003',
vector=binary_to_uint8([0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 1, 0, 0, 1, 0]),
bookName='三国演义'),
]
)
print(res, flush=True)
import tcvectordb
from tcvectordb.model.document import Document

res = client.upsert(
database_name="db-test-1",
collection_name="coll-json-autoid",
documents=[
{
'id': '0001',
'vector': [0.4],
'bookInfo': {
'bookName': '三国演义',
'author': '罗贯中',
}
},
{
'id': '0002',
'vector': [0.3],
'bookInfo': {
'bookName': '西游记',
'author': '吴承恩',
}
}
]
)
print(res, flush=True)

入参描述

参数名称
参数含义
子参数
是否必选
配置方法及要求
database_name
指定写入的数据库。
-
Database 命名要求如下:
只能使用英文字母,数字,下划线_、中划线-,并以英文字母开头。
长度要求:[1,128]。
collection_name
指定写入的集合名。
-
Collection 命名要求如下:
只能使用英文字母,数字,下划线_、中划线-,并以英文字母开头。
长度要求:[1,128]。
build_index
指定是否需要更新索引
-
取值如下所示:
True:需更新索引。默认值是 True
False:不更新索引。
注意:
如果创建 Collection 选择的索引类型为 IVF 系列:
当第一次写入时,当前集合还没有向量索引,此时 build_index 必须为 False。插入原始数据之后,需通过 rebuild_index() 训练数据并重建索引。
当集合已经调用过 rebuild_index() 创建索引后,集合已经存在向量索引,此时:
如果 build_index = True,表示新写入的数据会加入到已有的 IVF 索引中,但不会更新索引结构,此时新写入的数据可以被检索到。
如果 build_index = False,表示新写入的数据不会加入到已有的 IVF 索引中,此时新写入的数据无法被检索到。
documents
指定要插入的 Document 数据,是一个数组,支持单次插入一条或者多条 Document,最大可插入 1000 条。
id
Document 主键,长度限制为[1,128]。
vector
表示文档的向量值,
集合的向量索引为FLAT/HNSW/IVF时,直接传入向量数据,以32位浮点数存储,如[0.2123, 0.9281, ..., 0.6712]。
集合的向量索引为二进制索引时,写入向量时可以直接写入二进制数据,也可以以十进制写入。十进制写入数据时,数据维度是创建集合时指定维度的1/8。例如:upsert 时 vector=[12, 21],则创建集合时维度为16维,其代表的二进制数据为[00001100, 00010101]。
说明:
如果使用 Embedding 功能做向量化,则无需写入向量数据。
text
该参数为 创建集合 时,Embedding 参数 field 对应指定的文本字段名。该请求示例中为 text,您可以自定义其他便于识别的字段名。
说明:
写入原始文本数据,系统会自动从该字段中提取原始文本信息,并将其转换为向量数据,并将原始文本以及转化后的向量数据一起存储在数据库中。
输入的文本长度有限制,超过512个 token,约400个字符之后会自动截断。
sparse_vector
写入稀疏向量数据值。sparse_vector 为创建集合时自定义的稀疏向量的字段名。
other_scalar_field
其他标量字段,用于存储文档的其他信息。例如:请求示例中的 bookName、author、page、tags。
说明:
若字段为存储数据过期时间戳的标量字段,需以标准的 Unix 时间戳格式为该字段赋值,且数据类型为 uint64。例如:'expire_at': int(time.time()) + 10*60。具体示例,请参见 ttl.py
若时间戳字段为空未指定具体的过期时间,插入的该条数据将不会执行过期删除操作,数据将永久保留。
若时间戳字段传入 Value 的数据类型有误或者不符合 Unix 时间戳规范时,将会报出错误信息,请根据提示信息修改。
若时间戳字段指定的过期时间小于当前插入数据时的时间,则在下一个定时删除操作时,直接删除该条数据。

出参描述

{
'code': 0,
'msg': 'Operation success',
'affectedCount': 3,
'embeddingExtraInfo': {'tokenUsed': 285}
}
参数名
参数含义
affectedCount
影响行数,即为插入的数据条数。
embeddingExtraInfo
参数 tokenUsed,返回使用 Embedding 功能已经消耗的 Token 数量。