Insert rows (HTTP)

For details about additional languages, see:

Tables with the Data API are currently in public preview. Development is ongoing, and the features and functionality are subject to change. Hyper-Converged Database (HCD), and the use of such, is subject to the DataStax Preview Terms.

Inserts multiple rows into a table.

This method can insert a row in an existing CQL table, but the Data API does not support all CQL data types or modifiers. For more information, see Data type compatibility in tables (HTTP).

For general information about working with tables and rows, see About tables with the Data API (HTTP).

Ready to write code? See the examples for this method to get started.

Result

Inserts the specified rows.

If a row with the specified primary key already exists in the table, the row is overwritten with the specified column values. Unspecified columns remain unchanged.

The JSON response includes the following:

status.primaryKeySchema: An object that describes the table’s primary key definition, including column names and types.
status.insertedIds: A nested array that contains the primary key values for each inserted row. If the primary key has multiple columns, then the order of each array matches the order described by status.primaryKeySchema.

Omitted if the options.returnDocumentResponses parameter is true.
status.documentResponses: An array of objects where each object represents a row. In each object, status describes the outcome of the insertion, and _id is an array that contains the primary key values.

Included only if the options.returnDocumentResponses parameter is true.

You must check the entire response for errors to verify that all rows inserted successfully.

If a row fails to insert and the insertions are sequential (options.ordered is true), then that row and all subsequent rows are not inserted. The resulting error message indicates the first row that failed to insert.

If a row fails to insert and the insertions are not sequential (options.ordered is false), the operation will try to insert the remaining rows. The response includes a status object that describes successful insertions and an errors array that describes problems with failed rows.

Example response for a single-column primary key:

{
  "status": {
    "primaryKeySchema": {
      "email": {
        "type": "ascii"
      }
    },
    "insertedIds": [
      [
        "tal@example.com"
      ],
      [
        "sami@example.com"
      ],
      [
        "kirin@example.com"
      ]
    ]
  }
}

Example response for a multi-column primary key:

{
  "status": {
    "primaryKeySchema": {
      "email": {
        "type": "ascii"
      },
      "graduation_year": {
        "type": "int"
      }
    },
    "insertedIds": [
      [
        "tal@example.com",
        2024
      ],
      [
        "sami@example.com",
        2024
      ],
      [
        "kiran@example.com",
        2024
      ]
    ]
  }
}

Example response when options.returnDocumentResponses is true:

{
  "status": {
    "primaryKeySchema": {
      "email": {
        "type": "ascii"
      }
    },
    "documentResponses": [
      {"_id":["tal@example.com"], "status":"OK"},
      {"_id":["sami@example.com"], "status":"OK"},
      {"_id":["kirin@example.com"], "status":"OK"}
    ]
  }
}

Signature

Use the insertMany command.

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "insertMany": {
    "documents": ROWS_JSON_ARRAY,
    "options": {
      "ordered": BOOLEAN,
      "returnDocumentResponses": BOOLEAN
    }
  }
}'

Parameters

Name Type Summary

Name	Type	Summary
`documents`	`array`	An array of objects where each object defines a row to insert. All primary key values are required. To reduce tombstones, you should not explicitly set a column to `null`. The table definition determines the columns in the row, the type for each column, and the primary key. To get this information, see List table metadata (HTTP). You can insert up to 100 rows per HTTP request. If you want to insert more rows at once, you must make multiple requests or use the Data API clients.
`options.ordered`	`boolean`	Whether to insert the rows sequentially. If false, the rows are inserted in an arbitrary order with possible concurrency. This results in a much higher insert throughput than an equivalent ordered insertion. Default: false
`options.returnDocumentResponses`	`boolean`	Whether the response should include a `status` for each insertion. Default: false

documents

array

An array of objects where each object defines a row to insert.

All primary key values are required.

To reduce tombstones, you should not explicitly set a column to null.

The table definition determines the columns in the row, the type for each column, and the primary key. To get this information, see List table metadata (HTTP).

You can insert up to 100 rows per HTTP request. If you want to insert more rows at once, you must make multiple requests or use the Data API clients.

options.ordered

boolean

Whether to insert the rows sequentially.

If false, the rows are inserted in an arbitrary order with possible concurrency. This results in a much higher insert throughput than an equivalent ordered insertion.

Default: false

options.returnDocumentResponses

boolean

Whether the response should include a status for each insertion.

Default: false

Examples

The following examples demonstrate how to insert multiple rows into a table.

Insert rows

When you insert rows, you must specify a non-null value for each primary key column for each row. Non-primary key columns are optional. To reduce tombstones, you should not explicitly set a column to null.

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "insertMany": {
    "documents": [
      {
        "title": "Computed Wilderness",
        "author" :"Ryan Eau",
        "number_of_pages": 432,
        "due_date": "2024-12-18",
        "genres": ["History", "Biography"]
      },
      {
        "title": "Desert Peace",
        "author" :"Walter Dray",
        "number_of_pages": 355,
        "rating": 4.5
      }
    ]
  }
}'

Insert rows with vector embeddings

You can only insert vector embeddings into vector columns.

To create a table with a vector column, see Create a table (HTTP). To add a vector column to an existing table, see Alter a table (HTTP).

All embeddings in the column should use the same provider, model, and dimensions. Mismatched embeddings can cause inaccurate vector searches.

You can provide the vector embeddings as an array of floats, or you can use $binary to provide the vector embeddings as a Base64-encoded string. $binary can be more performant.

For more information about how to convert an array of floats to a Base64-encoded string, see BLOB type (HTTP).

Array of floats

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "insertMany": {
    "documents": [
      {
        "title": "Computed Wilderness",
        "author" :"Ryan Eau",
        "summary_genres_vector": [0.08, -0.62, 0.39]
      },
      {
        "title": "Desert Peace",
        "author" :"Walter Dray",
        "summary_genres_vector": [0.12, 0.53, 0.32]
      }
    ]
  }
}'

$binary

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "insertMany": {
    "documents": [
      {
        "title": "Computed Wilderness",
        "author" :"Ryan Eau",
        "summary_genres_vector": {"$binary": "PaPXCr8euFI+x64U"}
      },
      {
        "title": "Desert Peace",
        "author" :"Walter Dray",
        "summary_genres_vector": {"$binary": "PfXCjz8HrhQ+o9cK"}
      }
    ]
  }
}'

Insert rows and specify insertion behavior

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "insertMany": {
    "documents": [
      {
        "title": "Computed Wilderness",
        "author" :"Ryan Eau",
        "number_of_pages": 432,
        "due_date": "2024-12-18",
        "genres": ["History", "Biography"]
      },
      {
        "title": "Desert Peace",
        "author" :"Walter Dray",
        "number_of_pages": 355,
        "rating": 4.5
      }
    ],
    "options": {
      "ordered": false,
      "returnDocumentResponses": true
    }
  }
}'

Insert rows (HTTP)

Result

Signature

Parameters

Examples

Insert rows

Insert rows with vector embeddings

Insert rows and specify insertion behavior

Was this helpful?

Give Feedback