Skip to main content

Insert Or Replace Documents

To insert one or more documents in Tigris, you can use Insert or Replace API.

Request Specification

HTTP APIHTTP MethodURL ParamsResource
INSERTPOST
  • Database Name
  • Collection Name
  • /databases/{db}/collections/{collection}/documents/insert
    REPLACEPUT
  • Database Name
  • Collection Name
  • /databases/{db}/collections/{collection}/documents/replace

    Request Payload

    {
    "documents": [{doc1}, {doc2}...]
    }

    Understanding the request payload:

    • The documents represent an array of json documents that you want to insert or replace in a collection.

    Example collection

    The first step is to set up the collection object. All the operations on the collection are performed through this collection object.

    curl 'http://localhost:8081/v1/databases/catalogdb/collections/catalog/createOrUpdate' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{
    "schema":{
    "title":"catalog",
    "properties":{
    "id":{
    "type":"integer",
    "format":"int32",
    "autoGenerate":true
    },
    "name":{
    "type":"string"
    },
    "price":{
    "type":"number"
    },
    "brand":{
    "type":"string"
    },
    "labels":{
    "type":"string"
    },
    "popularity":{
    "type":"integer"
    },
    "reviews":{
    "type":"object",
    "properties":{
    "author":{
    "type":"string"
    },
    "rating":{
    "type":"number"
    }
    }
    }
    },
    "primary_key":[
    "id"
    ]
    }
    }'

    Insert a Single Document

    Insert API can be used to insert one or more documents into the collection. Since the id field is marked as autoGenerate, you don't need to specify a value for it and Tigris will automatically generate it for you.

    curl 'http://localhost:8081/v1/databases/catalogdb/collections/catalog/documents/insert' \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
    "documents":[
    {
    "name":"fiona handbag",
    "price":99.9,
    "brand":"michael kors",
    "labels":"purses",
    "popularity":8
    }
    ]
    }'

    The insert API maintains the uniqueness of the field marked as the primary key, for example, the field id in the example above. If the document with the same primary key value already exists in the collection, the operation will fail by throwing an HTTP status code 409 with the message "duplicate key value, violates key constraint"

    Insert Multiple Documents

    Similar, to a single row insert, you can also insert multiple documents by passing an array of documents.

    curl 'http://localhost:8081/v1/databases/catalogdb/collections/catalog/documents/insert' \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
    "documents":[
    {
    "name":"tote bag",
    "price":49,
    "brand":"coach",
    "labels":"handbags",
    "popularity":9
    },
    {
    "name":"sling bag",
    "price":75,
    "brand":"coach",
    "labels":"purses",
    "popularity":9
    }
    ]
    }'

    Upsert a Single Document

    Insert or replace operation can be used to insert a new document or replace an existing document with the same primary key value. This API is useful when there is no need for a uniqueness check on the primary key, and it is fine to replace documents that already exist. The following is an example when the row with an id 3 already exists so the below operation will replace the document with the newly provided data.

    curl 'http://localhost:8081/v1/databases/catalogdb/collections/catalog/documents/replace' \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '{
    "documents":[
    {
    "id":3,
    "name":"sling bag",
    "price":99,
    "brand":"coach",
    "labels":"purses",
    "popularity":9
    }
    ]
    }'

    Upsert Multiple Documents

    As the API can also be used when the document doesn't exist. The following is an example of when these two documents are inserted because there are no corresponding ids.

    curl 'http://localhost:8081/v1/databases/catalogdb/collections/catalog/documents/replace' \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '{
    "documents":[
    {
    "name":"sneakers shoes",
    "price":40,
    "brand":"adidas",
    "labels":"shoes",
    "popularity":10
    },
    {
    "name":"running shoes",
    "price":89,
    "brand":"coach",
    "labels":"shoes",
    "popularity":10
    }
    ]
    }'