# Upsert entities

Insert new rows or replace rows with matching primary keys. Use partialUpdate to update selected fields.

SDK: `@zilliz/milvus2-sdk-node@3.0.10` · Tested with Milvus 3.0.6

Canonical documentation: https://milvus-io.github.io/milvus-sdk-node/rest-api/entities/upsert/

## Section links

- [cURL command](https://milvus-io.github.io/milvus-sdk-node/rest-api/entities/upsert/#curl-command)
- [Default request](https://milvus-io.github.io/milvus-sdk-node/rest-api/entities/upsert/#default-request)
- [Sample response](https://milvus-io.github.io/milvus-sdk-node/rest-api/entities/upsert/#sample-response)
- [Request fields](https://milvus-io.github.io/milvus-sdk-node/rest-api/entities/upsert/#request-fields)

`POST /v2/vectordb/entities/upsert`

Replace `https://your-cluster.example.com` with your Milvus endpoint. Set `MILVUS_TOKEN` for authentication or omit the Authorization header on an unauthenticated cluster.

## cURL command

```bash
curl --request POST --url 'https://your-cluster.example.com/v2/vectordb/entities/upsert' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${MILVUS_TOKEN}" \
  --data-raw '{
  "dbName": "default",
  "collectionName": "books",
  "data": [
    {
      "id": 101,
      "title": "Invisible Cities",
      "vector": [
        0.1,
        0.2,
        0.3,
        0.4
      ]
    }
  ]
}'
```

## Default request

```json
{
  "dbName": "default",
  "collectionName": "books",
  "data": [
    {
      "id": 101,
      "title": "Invisible Cities",
      "vector": [
        0.1,
        0.2,
        0.3,
        0.4
      ]
    }
  ]
}
```

## Sample response

```json
{
  "code": 0,
  "data": {
    "upsertCount": 1,
    "upsertIds": [
      101
    ]
  },
  "cost": 0
}
```

## Request fields

- `dbName` string
  Database name. Operations on collections use default when omitted.
- `collectionName` string (required)
  Name of the collection.
- `partitionName` string
  Name of the partition.
- `data` array of object (required)
  Array of entity objects keyed by field name.
- `partialUpdate` boolean
  Update only the provided fields of existing entities.
- `fieldOps` array of object
  Per-field operations for a partial upsert, such as appending array elements.

See [`HttpClient.upsert`](https://milvus-io.github.io/milvus-sdk-node/api-reference/http-client/#upsert) for the Node.js SDK method.
