> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Upsert vectors
> Upsert vectors into a namespace. If a new value is upserted for an existing vector ID, it will overwrite the previous value.
For guidance, examples, and limits, see [Upsert data](https://docs.pinecone.io/guides/index-data/upsert-data).
```python Python theme={null}
# pip install "pinecone[grpc]"
from pinecone.grpc import PineconeGRPC as Pinecone
pc = Pinecone(api_key="YOUR_API_KEY")
# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")
index.upsert(
vectors=[
{
"id": "vec1",
"values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
"metadata": {"genre": "comedy", "year": 2020}
},
{
"id": "vec2",
"values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2],
"metadata": {"genre": "documentary", "year": 2019}
}
],
namespace="example-namespace"
)
```
```javascript JavaScript theme={null}
// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone'
const pc = new Pinecone({ apiKey: "YOUR_API_KEY" })
// To get the unique host for an index,
// see https://docs.pinecone.io/guides/manage-data/target-an-index
const index = pc.index("INDEX_NAME", "INDEX_HOST")
const records = [
{
id: 'vec1',
values: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
metadata: { genre: "comedy", year: 2020 },
},
{
id: 'vec2',
values: [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2],
metadata: { genre: "documentary", year: 2019 },
}
]
await index.('example-namespace').upsert(records);
```
```java Java theme={null}
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import io.pinecone.clients.Index;
import io.pinecone.configs.PineconeConfig;
import io.pinecone.configs.PineconeConnection;
import java.util.Arrays;
import java.util.List;
public class UpsertExample {
public static void main(String[] args) {
PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
// To get the unique host for an index,
// see https://docs.pinecone.io/guides/manage-data/target-an-index
config.setHost("INDEX_HOST");
PineconeConnection connection = new PineconeConnection(config);
Index index = new Index(connection, "INDEX_NAME");
List values1 = Arrays.asList(0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f);
List values2 = Arrays.asList(0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f);
Struct metaData1 = Struct.newBuilder()
.putFields("genre", Value.newBuilder().setStringValue("comedy").build())
.putFields("year", Value.newBuilder().setNumberValue(2020).build())
.build();
Struct metaData2 = Struct.newBuilder()
.putFields("genre", Value.newBuilder().setStringValue("documentary").build())
.putFields("year", Value.newBuilder().setNumberValue(2019).build())
.build();
index.upsert("vec1", values1, null, null, metaData1, 'example-namespace');
index.upsert("vec2", values2, null, null, metaData2, 'example-namespace');
}
}
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
"github.com/pinecone-io/go-pinecone/v3/pinecone"
"google.golang.org/protobuf/types/known/structpb"
)
func main() {
ctx := context.Background()
pc, err := pinecone.NewClient(pinecone.NewClientParams{
ApiKey: "YOUR_API_KEY",
})
if err != nil {
log.Fatalf("Failed to create Client: %v", err)
}
// To get the unique host for an index,
// see https://docs.pinecone.io/guides/manage-data/target-an-index
idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
if err != nil {
log.Fatalf("Failed to create IndexConnection for Host: %v", err)
}
metadataMap1 := map[string]interface{}{
"genre": "comedy",
"year": 2020,
}
metadata1, err := structpb.NewStruct(metadataMap1)
if err != nil {
log.Fatalf("Failed to create metadata map: %v", err)
}
metadataMap2 := map[string]interface{}{
"genre": "documentary",
"year": 2019,
}
metadata2, err := structpb.NewStruct(metadataMap2)
if err != nil {
log.Fatalf("Failed to create metadata map: %v", err)
}
vectors := []*pinecone.Vector{
{
Id: "vec1",
Values: []float32{0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1},
Metadata: metadata1,
},
{
Id: "vec2",
Values: []float32{0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2},
Metadata: metadata2,
},
}
count, err := idxConnection.UpsertVectors(ctx, vectors)
if err != nil {
log.Fatalf("Failed to upsert vectors: %v", err)
} else {
fmt.Printf("Successfully upserted %d vector(s)!\n", count)
}
}
```
```csharp C# theme={null}
using Pinecone;
var pinecone = new PineconeClient("YOUR_API_KEY");
// To get the unique host for an index,
// see https://docs.pinecone.io/guides/manage-data/target-an-index
var index = pinecone.Index(host: "INDEX_HOST");
var upsertResponse = await index.UpsertAsync(new UpsertRequest {
Vectors = new[]
{
new Vector
{
Id = "vec1",
Values = new[] { 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f },
Metadata = new Metadata {
["genre"] = new("comedy"),
["year"] = new(2020),
},
},
new Vector
{
Id = "vec2",
Values = new[] { 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f },
Metadata = new Metadata {
["genre"] = new("documentary"),
["year"] = new(2019),
},
}
},
Namespace = "example-namespace",
});
```
```shell curl theme={null}
# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"
curl "https://$INDEX_HOST/vectors/upsert" \
-H "Api-Key: $PINECONE_API_KEY" \
-H 'Content-Type: application/json' \
-H "X-Pinecone-Api-Version: 2025-01" \
-d '{
"vectors": [
{
"id": "vec1",
"values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
"metadata": {"genre": "comedy", "year": 2020}
},
{
"id": "vec2",
"values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2],
"metadata": {"genre": "documentary", "year": 2019}
}
],
"namespace": "example-namespace"
}'
```
```json curl theme={null}
{"upsertedCount":2}
```
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-01/db_data_2025-01.oas.yaml post /vectors/upsert
openapi: 3.0.3
info:
title: Pinecone Data Plane API
description: >-
Pinecone is a vector database that makes it easy to search and retrieve
billions of high-dimensional vectors.
contact:
name: Pinecone Support
url: https://support.pinecone.io
email: support@pinecone.io
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 2025-01
servers:
- url: https://{index_host}
variables:
index_host:
default: unknown
description: host of the index
security:
- ApiKeyAuth: []
tags:
- name: Vector Operations
- name: Bulk Operations
externalDocs:
description: More Pinecone.io API docs
url: https://docs.pinecone.io/introduction
paths:
/vectors/upsert:
post:
tags:
- Vector Operations
summary: Upsert vectors
description: >-
Upsert vectors into a namespace. If a new value is upserted for an
existing vector ID, it will overwrite the previous value.
For guidance, examples, and limits, see [Upsert
data](https://docs.pinecone.io/guides/index-data/upsert-data).
operationId: upsertVectors
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertRequest'
required: true
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertResponse'
'400':
description: Bad request. The request body included invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
4XX:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
5XX:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
components:
schemas:
UpsertRequest:
description: The request for the `upsert` operation.
type: object
properties:
vectors:
description: >-
An array containing the vectors to upsert. Recommended batch limit
is up to 1000 vectors.
type: array
items:
$ref: '#/components/schemas/Vector'
minLength: 1
maxLength: 1000
namespace:
example: example-namespace
description: The namespace where you upsert vectors.
type: string
required:
- vectors
UpsertResponse:
description: The response for the `upsert` operation.
type: object
properties:
upsertedCount:
example: 2
description: The number of vectors upserted.
type: integer
format: int64
rpcStatus:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
$ref: '#/components/schemas/protobufAny'
Vector:
type: object
properties:
id:
example: example-vector-1
description: This is the vector's unique id.
type: string
required:
- id
minLength: 1
maxLength: 512
values:
example:
- 0.1
- 0.2
- 0.3
- 0.4
- 0.5
- 0.6
- 0.7
- 0.8
description: This is the vector data included in the request.
type: array
required:
- values
items:
type: number
format: float
minLength: 1
maxLength: 20000
sparseValues:
$ref: '#/components/schemas/SparseValues'
metadata:
example:
genre: documentary
year: 2019
description: This is the metadata included in the request.
type: object
required:
- id
protobufAny:
type: object
properties:
typeUrl:
type: string
value:
type: string
format: byte
SparseValues:
description: >-
Vector sparse data. Represented as a list of indices and a list of
corresponded values, which must be with the same length.
type: object
properties:
indices:
example:
- 1
- 312
- 822
- 14
- 980
description: The indices of the sparse data.
type: array
required:
- indices
items:
type: integer
format: int64
minLength: 1
maxLength: 1000
values:
example:
- 0.1
- 0.2
- 0.3
- 0.4
- 0.5
description: >-
The corresponding values of the sparse data, which must be with the
same length as the indices.
type: array
required:
- values
items:
type: number
format: float
minLength: 1
maxLength: 1000
required:
- indices
- values
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Api-Key
description: >-
An API Key is required to call Pinecone APIs. Get yours from the
[console](https://app.pinecone.io/).
````