接口定义
upsert() 接口用于在 Base 类数据库创建的 Collection 中插入向量数据。
def upsert(self,database_name: str,collection_name: str,documents: List[Union[Document, Dict]],timeout: Optional[float] = None,build_index: bool = True,**kwargs)
使用实例
说明:
在插入数据时, Collection 中已经存在相同 ID 的 Document,则会删除源 Document 后插入新的 Document 数据。
如果 Collection 在创建时,配置 Embedding 参数,则插入文本,Embedding 服务会自动将文本信息转换为向量数据,存入数据库。
如果您无需使用腾讯云向量数据库(Tencent Cloud VectorDB)的 Embedding 功能做向量化,则可以直接写入向量数据。
import tcvectordbfrom 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], sparse_vector=[[2,0.96],[5,0.53],[100,0.443]], author='罗贯中', bookName='三国演义', page=21, tags=['曹操','诸葛亮','刘备']),Document(id='0002', vector=[0.2123, 0.22, 0.213], sparse_vector=[[2,0.97],[5,0.54],[100,0.444]], author='吴承恩', bookName='西游记', page=22, tags=['孙悟空','猪八戒','唐僧']),Document(id='0003', vector=[0.2123, 0.21, 0.213], sparse_vector=[[2,0.98],[5,0.55],[100,0.445]], author='曹雪芹', bookName='红楼梦', page=23, tags=['贾宝玉','林黛玉','王熙凤'])],build_index=True)print(res, flush=True)
如果您使用 Embedding 功能,在 create_collection() 建表时,配置 Embedding 模型相关参数之后,便可以通过 upsert() 接口可直接传入原始文本。Embedding 模型会将原始文本转换为向量数据,并将转换后的向量数据以及原始文本一并存入数据库。具体信息,请参见 Embedding 介绍。如下示例,基于 create_collection() 创建的集合 book-emb,写入原始文本。
import tcvectordbfrom tcvectordb.model.document import Documentdb = client.database('db-test')coll = db.collection('book-emb')# 写入数据。# 参数 build_index 为 True,指写入数据同时重新创建索引。res = client.upsert(database_name='db-test',collection_name='book-emb-1012',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)
入参描述
参数名称 | 参数含义 | 子参数 | 是否必选 | 配置方法及要求 |
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 | 否 | 表示文档的向量值,请务必使用32位浮点数存储向量数据。 说明: 如果业务无需使用腾讯云向量数据库(Tencent Cloud VectorDB)的 Embedding 功能做向量化,则配置该参数,写入向量数据,而无需配置 Embedding 参数 text (创建 Collection 时,Embedding 参数 field 对应指定的文本字段名,示例中为 text)。 |
| | 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}
参数名 | 参数含义 |
affectedCount | 影响行数,即为插入的数据条数。 |