Insert rows (C#)

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 (C#).

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

Ready to write code? See the examples for this method to get started. If you are new to the Data API, check out the quickstart.

Result

Inserts the specified rows and returns a TableInsertManyResult object that includes the primary keys of the inserted rows and the schema of the primary key.

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.

If a row fails to insert and the insertions are sequential (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 (Ordered is false), the operation will try to insert the remaining rows and then throw an error. The error indicates which rows were successfully inserted and the problems with the failed rows.

Parameters

Use the InsertManyAsync method, which belongs to the Table class. You can also use InsertMany, which is the synchronous version of the method.

Method signature 
public Task<TableInsertManyResult> InsertManyAsync(
  List<T> rows, TableInsertManyOptions options = null
);
Name Type Summary

rows

IEnumerable<T>

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

All primary key values are required. If you use a custom class, any unspecified columns are set 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 (C#).

options

TableInsertManyOptions

Optional. Options for this operation. For more information and examples for general options such as timeout, see Customize API interaction. For options specific to this method, see Method-specific properties of the TableInsertManyOptions class.
Method-specific properties of the TableInsertManyOptions class
Name Type Summary

ChunkSize

int

The number of rows to insert in a single API request.

DataStax recommends that you leave this unspecified to use the system default.

Concurrency

int

The maximum number of concurrent requests to the API at a given time.

For ordered insertions, must be 1 or unspecified.

Default: 20 if Ordered is False. 1 if Ordered is True.

Ordered

bool

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

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.

  • Typed

  • Untyped

You can manually define a client-side type for your table to help statically catch errors. For more information and examples, see Custom typing for tables.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Book
{
  [ColumnPrimaryKey(1)]
  [ColumnName("title")]
  public string Title { get; set; } = null!;

  [ColumnPrimaryKey(2)]
  [ColumnName("author")]
  public string Author { get; set; } = null!;

  [ColumnName("number_of_pages")]
  public int? NumberOfPages { get; set; }

  [ColumnName("genres")]
  public HashSet<string>? Genres { get; set; }

  [ColumnName("due_date")]
  public DateOnly? DueDate { get; set; }

  [ColumnName("rating")]
  public double? Rating { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable<Book>("TABLE_NAME");

    // Insert rows into the table
    var rows = new List<Book>()
    {
      new Book()
      {
        Title = "Computed Wilderness",
        Author = "Ryan Eau",
        NumberOfPages = 432,
        DueDate = new DateOnly(2024, 12, 18),
        Genres = new HashSet<string> { "History", "Biography" },
      },
      new Book()
      {
        Title = "Desert Peace",
        Author = "Walter Dray",
        NumberOfPages = 355,
        Rating = 4.5,
      },
    };

    await table.InsertManyAsync(rows);
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable("TABLE_NAME");

    // Insert rows into the table
    var rows = new List<Row>()
    {
      new Row()
      {
        { "title", "Computed Wilderness" },
        { "author", "Ryan Eau" },
        { "number_of_pages", 432 },
        { "due_date", new DateOnly(2024, 12, 18) },
        {
          "genres",
          new HashSet<string> { "History", "Biography" }
        },
      },
      new Row()
      {
        { "title", "Desert Peace" },
        { "author", "Walter Dray" },
        { "number_of_pages", 355 },
        { "rating", 4.5 },
      },
    };

    await table.InsertManyAsync(rows);
  }
}

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 (C#). To add a vector column to an existing table, see Alter a table (C#).

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

The C# client automatically encodes your vector embeddings when you insert to a vector column.

  • Typed

  • Untyped

You can manually define a client-side type for your table to help statically catch errors. For more information and examples, see Custom typing for tables.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Book
{
  [ColumnPrimaryKey(1)]
  [ColumnName("title")]
  public string Title { get; set; } = null!;

  [ColumnPrimaryKey(2)]
  [ColumnName("author")]
  public string Author { get; set; } = null!;

  [ColumnVector(3)]
  [ColumnName("summary_genres_vector")]
  public double[]? SummaryGenresVector { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable<Book>("TABLE_NAME");

    // Insert rows into the table
    var rows = new List<Book>()
    {
      new Book()
      {
        Title = "Computed Wilderness",
        Author = "Ryan Eau",
        SummaryGenresVector = new double[] { 0.08f, -0.62f, 0.39f },
      },
      new Book()
      {
        Title = "Desert Peace",
        Author = "Walter Dray",
        SummaryGenresVector = new double[] { 0.12f, 0.53f, 0.32f },
      },
    };

    await table.InsertManyAsync(rows);
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable("TABLE_NAME");

    // Insert rows into the table
    var rows = new List<Row>()
    {
      new Row()
      {
        { "title", "Computed Wilderness" },
        { "author", "Ryan Eau" },
        {
          "summary_genres_vector",
          new double[] { 0.08f, -0.62f, 0.39f }
        },
      },
      new Row()
      {
        { "title", "Desert Peace" },
        { "author", "Walter Dray" },
        { "summary_genres_vector", new double[] { 0.12f, 0.53f, 0.32f } },
      },
    };

    await table.InsertManyAsync(rows);
  }
}

Insert rows and generate vector embeddings

To automatically generate vector embeddings, your table must have a vector column with an embedding provider integration. You can configure embedding provider integrations when you create a table, add a vector column to an existing table, or alter an existing vector column.

When you insert a row, you can pass a string to the vector column. Astra DB uses the embedding provider integration to generate vector embeddings from that string.

The strings used to generate the vector embeddings are not stored. If you want to store the original strings, you must store them in a separate column.

In the following examples, summary_genres_vector is a vector column that has an embedding provider integration configured, and summary_genres_original_text is a text column to store the original text.

  • Typed

  • Untyped

You can manually define a client-side type for your table to help statically catch errors. For more information and examples, see Custom typing for tables.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Book
{
  [ColumnPrimaryKey(1)]
  [ColumnName("title")]
  public string Title { get; set; } = null!;

  [ColumnPrimaryKey(2)]
  [ColumnName("author")]
  public string Author { get; set; } = null!;

  [ColumnVectorize(
    provider: "nvidia",
    modelName: "nvidia/nv-embedqa-e5-v5",
    dimension: 1024
  )]
  [ColumnName("summary_genres_vector")]
  public object? SummaryGenresVector { get; set; }

  [ColumnName("summary_genres_original_text")]
  public string? SummaryGenresOriginalText { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable<Book>("TABLE_NAME");

    // Insert rows into the table
    var rows = new List<Book>()
    {
      new Book()
      {
        Title = "Computed Wilderness",
        Author = "Ryan Eau",
        SummaryGenresVector = "Text to vectorize",
        SummaryGenresOriginalText = "Text to vectorize",
      },
      new Book()
      {
        Title = "Desert Peace",
        Author = "Walter Dray",
        SummaryGenresVector = "Text to vectorize",
        SummaryGenresOriginalText = "Text to vectorize",
      },
    };

    await table.InsertManyAsync(rows);
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable("TABLE_NAME");

    // Insert rows into the table
    var rows = new List<Row>()
    {
      new Row()
      {
        { "title", "Computed Wilderness" },
        { "author", "Ryan Eau" },
        { "summary_genres_vector", "Text to vectorize" },
        { "summary_genres_original_text", "Text to vectorize" },
      },
      new Row()
      {
        { "title", "Desert Peace" },
        { "author", "Walter Dray" },
        { "summary_genres_vector", "Text to vectorize" },
        { "summary_genres_original_text", "Text to vectorize" },
      },
    };

    await table.InsertManyAsync(rows);
  }
}

Insert rows with a map column that uses non-string keys

The C# client supports insertion of rows with a map column that includes non-string keys. (You don’t need to use an array of key-value pairs to represent the map column.)

  • Typed

  • Untyped

You can manually define a client-side type for your collection to help statically catch errors. For more information and examples, see Custom typing for collections.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Book
{
  [ColumnPrimaryKey(1)]
  [ColumnName("title")]
  public string Title { get; set; } = null!;

  [ColumnPrimaryKey(2)]
  [ColumnName("author")]
  public string Author { get; set; } = null!;

  [ColumnName("map_column_int_str")]
  public Dictionary<int, string>? MapColumnIntStr { get; set; }

  [ColumnName("map_column_str_str")]
  public Dictionary<string, string>? MapColumnStrStr { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable<Book>("TABLE_NAME");

    var rows = new List<Book>()
    {
      new Book
      {
        MapColumnIntStr = new Dictionary<int, string>
        {
          { 1, "value1" },
          { 2, "value2" },
        },
        MapColumnStrStr = new Dictionary<string, string>
        {
          { "key1", "value1" },
          { "key2", "value2" },
        },
        Title = "Once in a Living Memory",
        Author = "Kayla McMaster",
      },
    };

    await table.InsertManyAsync(rows);
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable("TABLE_NAME");

    var rows = new List<Row>()
    {
      new Row()
      {
        {
          "map_column_int_str",
          new Dictionary<int, string> { { 1, "value1" }, { 2, "value2" } }
        },
        {
          "map_column_str_str",
          new Dictionary<string, string>
          {
            { "key1", "value1" },
            { "key2", "value2" },
          }
        },
        { "title", "Once in a Living Memory" },
        { "author", "Kayla McMaster" },
      },
    };

    await table.InsertManyAsync(rows);
  }
}

Insert rows and specify insertion behavior

  • Typed

  • Untyped

You can manually define a client-side type for your table to help statically catch errors. For more information and examples, see Custom typing for tables.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Book
{
  [ColumnPrimaryKey(1)]
  [ColumnName("title")]
  public string Title { get; set; } = null!;

  [ColumnPrimaryKey(2)]
  [ColumnName("author")]
  public string Author { get; set; } = null!;

  [ColumnName("number_of_pages")]
  public int? NumberOfPages { get; set; }

  [ColumnName("genres")]
  public HashSet<string>? Genres { get; set; }

  [ColumnName("due_date")]
  public DateOnly? DueDate { get; set; }

  [ColumnName("rating")]
  public double? Rating { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable<Book>("TABLE_NAME");

    // Insert rows into the table
    var rows = new List<Book>()
    {
      new Book()
      {
        Title = "Computed Wilderness",
        Author = "Ryan Eau",
        NumberOfPages = 432,
        DueDate = new DateOnly(2024, 12, 18),
        Genres = new HashSet<string> { "History", "Biography" },
      },
      new Book()
      {
        Title = "Desert Peace",
        Author = "Walter Dray",
        NumberOfPages = 355,
        Rating = 4.5,
      },
    };

    var options = new TableInsertManyOptions
    {
      ChunkSize = 2,
      Concurrency = 2,
      Ordered = false,
    };

    await table.InsertManyAsync(rows, options);
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable("TABLE_NAME");

    // Insert rows into the table
    var rows = new List<Row>()
    {
      new Row()
      {
        { "title", "Computed Wilderness" },
        { "author", "Ryan Eau" },
        { "number_of_pages", 432 },
        { "due_date", new DateOnly(2024, 12, 18) },
        {
          "genres",
          new HashSet<string> { "History", "Biography" }
        },
      },
      new Row()
      {
        { "title", "Desert Peace" },
        { "author", "Walter Dray" },
        { "number_of_pages", 355 },
        { "rating", 4.5 },
      },
    };

    var options = new TableInsertManyOptions
    {
      ChunkSize = 2,
      Concurrency = 2,
      Ordered = false,
    };

    await table.InsertManyAsync(rows, options);
  }
}

Client reference

For more information, see the client reference.

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | Privacy policy | Terms of use |  Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: Contact IBM