向量数据库写入数据

接口定义
Upsert() 接口用于给创建的 Collection 中插入 Document。如果 Collection 在创建时，已配置 Embedding 参数，则仅需要插入文本信息，Embedding 服务会自动将文本信息转换为向量数据，存入数据库。
Upsert(ctx context.Context, databaseName string, collectionName string, documents interface{}, params ...*tcvectordb.UpsertDocumentParams) (result *tcvectordb.UpsertDocumentResult, err error)
使用示例
写入文本
写入向量
写入稀疏向量
稀疏向量工具
写入二进制
Embedding文本与稀疏向量
Json 类型
如下示例，给集合 go-sdk-test-emcoll 基于文本字段 segment 插入数据。segment  为创建 Collection 时指定的文本字段。
var (
    ctx                 = context.Background()
    database            = "go-sdk-test-db"
    embeddingCollection = "go-sdk-test-emcoll"
)
result, err := client.Upsert(ctx, database, embeddingCollection, []tcvectordb.Document{
    {
        Id: "0001",
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "西游记"},
            "author":   {Val: "吴承恩"},
            "page":     {Val: 21},
            "text":  {Val: "富贵功名，前缘分定，为人切莫欺心。"},
        },
    },
    {
        Id: "0002",
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "西游记"},
            "author":   {Val: "吴承恩"},
            "page":     {Val: 22},
            "text":  {Val: "正大光明，忠良善果弥深。些些狂妄天加谴，眼前不遇待时临。"},
        },
    },
    {
        Id: "0003",
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "三国演义"},
            "author":   {Val: "罗贯中"},
            "page":     {Val: 23},
            "text":  {Val: "细作探知这个消息，飞报吕布。"},
        },
    },
    {
        Id: "0004",
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "三国演义"},
            "author":   {Val: "罗贯中"},
            "page":     {Val: 24},
            "text":  {Val: "布大惊，与陈宫商议。宫曰：“闻刘玄德新领徐州，可往投之。”布从其言，竟投徐州来。有人报知玄德。"},
        },
    },
    {
        Id: "0005",
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "三国演义"},
            "author":   {Val: "罗贯中"},
            "page":     {Val: 25},
            "text":  {Val: "玄德曰：“布乃当今英勇之士，可出迎之。”糜竺曰：“吕布乃虎狼之徒，不可收留；收则伤人矣。"},
        },
    },
})
﻿
log.Printf("upsert result: %+v", result)
如下示例，给集合 go-sdk-test-coll 直接写入向量数据。
var (
    ctx                 = context.Background()
    database            = "go-sdk-test-db"
    collectionName      = "go-sdk-test-coll"
)
buildIndex := true
result, err := client.Upsert(ctx, database, collectionName, []tcvectordb.Document{
    {
        Id:     "0001",
        Vector: []float32{0.2123, 0.21, 0.213},
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "西游记"},
            "author":   {Val: "吴承恩"},
            "page":     {Val: 21},
            "segment":  {Val: "富贵功名，前缘分定，为人切莫欺心。"},
            "tag":      {Val: []string{"孙悟空", "猪八戒", "唐僧"}},
        },
    },
    {
        Id:     "0002",
        Vector: []float32{0.2123, 0.22, 0.213},
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "西游记"},
            "author":   {Val: "吴承恩"},
            "page":     {Val: 22},
            "segment":  {Val: "正大光明，忠良善果弥深。些些狂妄天加谴，眼前不遇待时临。"},
            "tag":      {Val: []string{"孙悟空", "猪八戒", "唐僧"}},
        },
    },
    {
        Id:     "0003",
        Vector: []float32{0.2123, 0.23, 0.213},
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "三国演义"},
            "author":   {Val: "罗贯中"},
            "page":     {Val: 23},
            "segment":  {Val: "细作探知这个消息，飞报吕布。"},
            "tag":      {Val: []string{"曹操", "诸葛亮", "刘备"}},
        },
    },
  }, &tcvectordb.UpsertDocumentParams{BuildIndex: &buildIndex})
﻿
log.Printf("upsert result: %+v", result)
如下示例，给集合 go-sdk-test-coll 直接写入向量数据与稀疏向量，对应字段为 Vector 与 SparseVector。
var (
    ctx                 = context.Background()
    database            = "go-sdk-test-db"
    collectionName      = "go-sdk-test-coll"
)
buildIndex := true
result, err := client.Upsert(ctx, database, collectionName, []tcvectordb.Document{
    {
        Id:     "0001",
        Vector: []float32{0.2123, 0.21, 0.213},
        SparseVector: []encoder.SparseVecItem{
            {
               TermId: 4056151844,
               Score:  0.7627807,
            },
            {
               TermId: 4293601821,
               Score:  0.7627807,
            },
            {
               TermId: 1834252564,
               Score:  0.7627807,
            },
        },
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "西游记"},
            "author":   {Val: "吴承恩"},
            "page":     {Val: 21},
            "segment":  {Val: "富贵功名，前缘分定，为人切莫欺心。"},
            "tag":      {Val: []string{"孙悟空", "猪八戒", "唐僧"}},
        },
    },
    {
        Id:     "0002",
        Vector: []float32{0.2123, 0.22, 0.213},
        SparseVector: []encoder.SparseVecItem{{
           TermId: 4056151844,
           Score:  0.7627807,
            },
            {
               TermId: 4293601821,
               Score:  0.7627807,
            },
            {
               TermId: 1834252564,
               Score:  0.7627807,
            },
        },
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "西游记"},
            "author":   {Val: "吴承恩"},
            "page":     {Val: 22},
            "segment":  {Val: "正大光明，忠良善果弥深。些些狂妄天加谴，眼前不遇待时临。"},
            "tag":      {Val: []string{"孙悟空", "猪八戒", "唐僧"}},
        },
    },
    {
        Id:     "0003",
        Vector: []float32{0.2123, 0.23, 0.213},
        SparseVector: []encoder.SparseVecItem{{
           TermId: 4056151844,
           Score:  0.7627807,
            },
            {
               TermId: 4293601821,
               Score:  0.7627807,
            },
            {
               TermId: 1834252564,
               Score:  0.7627807,
            },
        },
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "三国演义"},
            "author":   {Val: "罗贯中"},
            "page":     {Val: 23},
            "segment":  {Val: "细作探知这个消息，飞报吕布。"},
            "tag":      {Val: []string{"曹操", "诸葛亮", "刘备"}},
        },
    },
  },
}, &tcvectordb.UpsertDocumentParams{BuildIndex: &buildIndex})
﻿
log.Printf("upsert result: %+v", result)
﻿
var (
    ctx                 = context.Background()
    database            = "go-sdk-test-db"
    collectionName      = "go-sdk-test-coll"
)
buildIndex := true
bm25, err := encoder.NewBM25Encoder(&encoder.BM25EncoderParams{Bm25Language: "zh"})
if err != nil {
  log.Fatalf(err.Error())
}
segments := []string{
  "腾讯云向量数据库（Tencent Cloud VectorDB）是一款全托管的自研企业级分布式数据库服务，专用于存储、索引、检索、管理由深度神经网络或其他机器学习模型生成的大量多维嵌入向量。",
  "作为专门为处理输入向量查询而设计的数据库，它支持多种索引类型和相似度计算方法，单索引支持10亿级向量规模，高达百万级 QPS 及毫秒级查询延迟。",
  "不仅能为大模型提供外部知识库，提高大模型回答的准确性，还可广泛应用于推荐系统、NLP 服务、计算机视觉、智能客服等 AI 领域。",
}
// 查看稀疏向量文本拆分情况
tokens := bm25.GetTokenizer().Tokenize(segments[0])
fmt.Println("tokens: ", tokens)
// 如下使用 tcvdb-text 工具的接口 bm25.EncodeTexts 将segments 文本转为稀疏向量表示。
sparse_vectors, err := bm25.EncodeTexts(segments)
if err != nil {
  log.Fatalf(err.Error())
}
// 写入向量数据、稀疏向量、标量字段
result, err1 := client.Upsert(ctx,, database, collectionName, []tcvectordb.Document{
    {
        Id:     "0001",
        Vector: []float32{0.2123, 0.21, 0.213},
        SparseVector: sparse_vectors[0],
    },
    {
        Id:     "0002",
        Vector: []float32{0.2123, 0.22, 0.213},
        SparseVector: sparse_vectors[1],
    },
    {
        Id:     "0003",
        Vector: []float32{0.2123, 0.23, 0.213},
        SparseVector: sparse_vectors[2],
    },
  },
}, &tcvectordb.UpsertDocumentParams{BuildIndex: &buildIndex})
import (
    "context"
    "log"
﻿
    "github.com/tencent/vectordatabase-sdk-go/tcvectordb"
    "github.com/tencent/vectordatabase-sdk-go/tcvectordb/utils"
)
var (
    ctx                 = context.Background()
    database            = "go-sdk-test-db"
    collectionName      = "go-sdk-test-coll"
)
binaryVectors := [][]byte{
        {1, 1, 1, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0},
        {1, 1, 0, 0, 1, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0},
        {0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 1, 0, 0, 1, 0},
        {0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 0, 0, 1, 0, 0},
        {0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 1, 1, 0, 0, 1},
}
insertVectors := make([][]float32, 0)
for _, binaryVector := range binaryVectors {
    res, err := utils.BinaryToUint8(binaryVector)
    if err != nil {
        panic(err)
    }
    insertVectors = append(insertVectors, res)
}
documentList := []tcvectordb.Document{
    {
        Id:     "0001",
        Vector: insertVectors[0],
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "西游记"},
            "author":   {Val: "吴承恩"},
            "page":     {Val: 21},
            "segment":  {Val: "富贵功名，前缘分定，为人切莫欺心。"},
        },
    },
    {
        Id:     "0002",
        Vector: insertVectors[1],
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "西游记"},
            "author":   {Val: "吴承恩"},
            "page":     {Val: 22},
            "segment":  {Val: "正大光明，忠良善果弥深。些些狂妄天加谴，眼前不遇待时临。"},
        },
    },
    {
        Id:     "0003",
        Vector: insertVectors[2],
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "三国演义"},
            "author":   {Val: "罗贯中"},
            "page":     {Val: 23},
            "segment":  {Val: "细作探知这个消息，飞报吕布。"},
        },
    },
    {
        Id:     "0004",
        Vector: insertVectors[3],
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "三国演义"},
            "author":   {Val: "罗贯中"},
            "page":     {Val: 24},
            "segment":  {Val: "布大惊，与陈宫商议。宫曰：“闻刘玄德新领徐州，可往投之。”布从其言，竟投徐州来。有人报知玄德。"},
        },
    },
    {
        Id:     "0005",
        Vector: insertVectors[4],
        Fields: map[string]tcvectordb.Field{
            "bookName": {Val: "三国演义"},
            "author":   {Val: "罗贯中"},
            "page":     {Val: 25},
            "segment":  {Val: "玄德曰：“布乃当今英勇之士，可出迎之。”糜竺曰：“吕布乃虎狼之徒，不可收留；收则伤人矣。"},
        },
    },
}
result, _ := client.Upsert(ctx, database, collectionName, documentList)
log.Printf("UpsertResult: %+v", result)
import (
    "context"
    "log"
    "strconv"
    "time"
﻿
    "github.com/tencent/vectordatabase-sdk-go/tcvdbtext/encoder"
    "github.com/tencent/vectordatabase-sdk-go/tcvectordb"
)
var (
    ctx                 = context.Background()
    database            = "go-sdk-test-db"
    collectionName      = "go-sdk-test-coll"
)
segments := []string{
    "腾讯云向量数据库（Tencent Cloud VectorDB）是一款全托管的自研企业级分布式数据库服务，专用于存储、索引、检索、管理由深度神经网络或其他机器学习模型生成的大量多维嵌入向量。",
    "作为专门为处理输入向量查询而设计的数据库，它支持多种索引类型和相似度计算方法，单索引支持10亿级向量规模，高达百万级 QPS 及毫秒级查询延迟。",
    "不仅能为大模型提供外部知识库，提高大模型回答的准确性，还可广泛应用于推荐系统、NLP 服务、计算机视觉、智能客服等 AI 领域。",
    "腾讯云向量数据库（Tencent Cloud VectorDB）作为一种专门存储和检索向量数据的服务提供给用户， 在高性能、高可用、大规模、低成本、简单易用、稳定可靠等方面体现出显著优势。 ",
    "腾讯云向量数据库可以和大语言模型 LLM 配合使用。企业的私域数据在经过文本分割、向量化后，可以存储在腾讯云向量数据库中，构建起企业专属的外部知识库，从而在后续的检索任务中，为大模型提供提示信息，辅助大模型生成更加准确的答案。",
}
bm25, _ := encoder.NewBM25Encoder(&encoder.BM25EncoderParams{Bm25Language: "zh"})
sparse_vectors, _ := bm25.EncodeTexts(segments)
documentList := []tcvectordb.Document{
        {
            Id: "0001",
            Fields: map[string]tcvectordb.Field{
                "text":     {Val: segments[0]},
                "bookName": {Val: "腾讯云向量数据库"},
            },
            SparseVector: sparse_vectors[0],
        },
        {
            Id: "0002",
            Fields: map[string]tcvectordb.Field{
                "text": {Val: segments[1]},
                "bookName": {Val: "VectorDB"},
            },
            SparseVector: sparse_vectors[1],
        },
        {
            Id: "0003",
            Fields: map[string]tcvectordb.Field{
                "text": {Val: segments[2]},
                "bookName": {Val: "腾讯云向量数据库"}
            },
            SparseVector: sparse_vectors[2],
        },
        {
            Id: "0004",
            Fields: map[string]tcvectordb.Field{
                "text": {Val: segments[3]},
            },
            SparseVector: sparse_vectors[3],
        },
        {
            Id: "0005",
            Fields: map[string]tcvectordb.Field{
                "text": {Val: segments[4]},
            },
            SparseVector: sparse_vectors[4],
        },
    }
result, _ := client.Upsert(ctx, database, collectionName, documentList)
log.Printf("UpsertResult: %+v", result)
var (
    ctx = context.Background()
    database = "go-sdk-test-db"
    collection = "go-sdk-test-coll"
)
documentList := []tcvectordb.Document{
    {
        Vector: []float32{0},
        Fields: map[string]tcvectordb.Field{
            "bookInfo": {Val: map[string]interface{}{
                "bookName": "西游记",
                "author":   "吴承恩",
            }},
        },
    },
    {
        Vector: []float32{0.3},
        Fields: map[string]tcvectordb.Field{
            "bookInfo": {Val: map[string]interface{}{
                "bookName": "红楼梦",
                "author":   "曹雪芹",
            }},
        },
    },
}
result, _ := client.Upsert(ctx, database, collection, documentList)
log.Printf("UpsertResult: %+v", result)
入参描述
参数名称
参数含义
子参数
是否必选
配置方法
databaseName 
指定需写入的数据库名
-
是
Database 命名要求如下：
只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。
长度要求：[1,128]。
collectionName 
指定写入数据的集合
-
是
Collection 命名要求如下：
只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。
长度要求：[1,128]。

BuildIndex

是否重建索引
-
否
取值如下所示：
true：需更新索引。默认值是 true。
false：不更新索引。
注意：
如果创建 Collection 选择的索引类型为 IVF 系列：
当第一次写入时，当前集合还没有向量索引，此时 BuildIndex 必须为 false。插入原始数据之后，需通过 rebuild_index() 训练数据并重建索引。
当集合已经调用过 rebuild_index() 创建索引后，集合已经存在向量索引，此时：
如果 BuildIndex = true，表示新写入的数据会加入到已有的 IVF 索引中，但不会更新索引结构，此时新写入的数据可以被检索到。
如果 BuildIndex = false，表示新写入的数据不会加入到已有的 IVF 索引中，此时新写入的数据无法被检索到。
Document
指定要插入的 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 功能做向量化，则无需写入向量数据。
﻿
﻿
SparseVector
否
写入稀疏向量数据。支持写入稠密向量与稀疏向量，或使用 Embedding 写入原始文本与稀疏向量。
﻿
﻿

Fields
否
text 字段为创建集合时，Embedding 参数 Field 对应指定的文本字段名，您可以自定义其他便于识别的字段名。
说明：
写入原始文本数据，系统会自动从该字段中提取原始文本信息，并将其转换为向量数据，并将原始文本以及转化后的向量数据一起存储在数据库中。
﻿
﻿
﻿
﻿
其他自定义扩展的标量字段，用于存储文档的其他信息。例如：bookName、author、page。
说明：
若字段为存储数据过期时间戳的标量字段，需以标准的 Unix 时间戳格式为该字段赋值，且数据类型为 uint64。具体示例，请参见ttl_demo。代码主要部分，如下所示。
Fields: map[string]tcvectordb.Field{
    "expire_at": {Val: time.Now().Add(10 * time.Second).Unix()},
},
若时间戳字段为空未指定具体的过期时间，插入的该条数据将不会执行过期删除操作，数据将永久保留。
若时间戳字段传入 Value 的数据类型有误或者不符合 Unix 时间戳规范时，将会报出错误信息，请根据提示信息修改。
若时间戳字段指定的过期时间小于当前插入数据时的时间，则在下一个定时删除操作时，直接删除该条数据。

参数名称	参数含义	子参数	是否必选	配置方法
databaseName	指定需写入的数据库名	-	是	Database 命名要求如下：只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。长度要求：[1,128]。
collectionName	指定写入数据的集合	-	是	Collection 命名要求如下：只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。长度要求：[1,128]。
BuildIndex	是否重建索引	-	否	取值如下所示： true：需更新索引。默认值是 true。 false：不更新索引。注意：如果创建 Collection 选择的索引类型为 IVF 系列：当第一次写入时，当前集合还没有向量索引，此时 BuildIndex 必须为 false。插入原始数据之后，需通过 rebuild_index() 训练数据并重建索引。当集合已经调用过 rebuild_index() 创建索引后，集合已经存在向量索引，此时：如果 BuildIndex = true，表示新写入的数据会加入到已有的 IVF 索引中，但不会更新索引结构，此时新写入的数据可以被检索到。如果 BuildIndex = false，表示新写入的数据不会加入到已有的 IVF 索引中，此时新写入的数据无法被检索到。
Document	指定要插入的 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 功能做向量化，则无需写入向量数据。
				SparseVector	否	写入稀疏向量数据。支持写入稠密向量与稀疏向量，或使用 Embedding 写入原始文本与稀疏向量。
				Fields	否	text 字段为创建集合时，Embedding 参数 Field 对应指定的文本字段名，您可以自定义其他便于识别的字段名。说明：写入原始文本数据，系统会自动从该字段中提取原始文本信息，并将其转换为向量数据，并将原始文本以及转化后的向量数据一起存储在数据库中。
				Fields	否		其他自定义扩展的标量字段，用于存储文档的其他信息。例如：bookName、author、page。说明：若字段为存储数据过期时间戳的标量字段，需以标准的 Unix 时间戳格式为该字段赋值，且数据类型为 uint64。具体示例，请参见ttl_demo。代码主要部分，如下所示。 Fields: map[string]tcvectordb.Field{ "expire_at": {Val: time.Now().Add(10 * time.Second).Unix()}, }, 若时间戳字段为空未指定具体的过期时间，插入的该条数据将不会执行过期删除操作，数据将永久保留。若时间戳字段传入 Value 的数据类型有误或者不符合 Unix 时间戳规范时，将会报出错误信息，请根据提示信息修改。若时间戳字段指定的过期时间小于当前插入数据时的时间，则在下一个定时删除操作时，直接删除该条数据。

写入数据

本页目录：

接口定义

使用示例

入参描述