Insert a row (C#)

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 a single row 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 row and returns a TableInsertOneResult instance that includes the primary key of the inserted row and the schema of the primary key.

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

If any of the inserted columns use the wrong datatype or improper encoding, then the entire insert fails.

Parameters

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

Method signature

public Task<TableInsertOneResult> InsertOneAsync(
  T row, TableInsertOneOptions options = null
);

Name Type Summary

Name	Type	Summary
`row`	`T`	An object that defines the 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`	`TableInsertOneOptions`	Optional. General API options for this operation, including the timeout. For more information and examples, see Customize API interaction.

row

T

An object that defines the 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

TableInsertOneOptions

Optional. General API options for this operation, including the timeout. For more information and examples, see Customize API interaction.

Examples

The following examples demonstrate how to insert a row into a table.

Insert a row

When you insert a row, you must specify a non-null value for each primary key column. 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; }
}

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var table = database.GetTable<Book>("TABLE_NAME");

    // Insert a row into the table
    var row = new Book()
    {
      Title = "Computed Wilderness",
      Author = "Ryan Eau",
      NumberOfPages = 432,
      DueDate = new DateOnly(2024, 12, 18),
      Genres = new HashSet<string> { "History", "Biography" },
    };

    await table.InsertOneAsync(row);
  }
}

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(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var table = database.GetTable("TABLE_NAME");

    // Insert a row into the table
    var 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" }
      },
    };

    await table.InsertOneAsync(row);
  }
}

Insert a row 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.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!;

  [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(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var table = database.GetTable<Book>("TABLE_NAME");

    // Insert a row into the table
    var embeddings = new double[] { 0.08f, -0.62f, 0.39f };
    var row = new Book()
    {
      Title = "Computed Wilderness",
      Author = "Ryan Eau",
      SummaryGenresVector = embeddings,
    };

    await table.InsertOneAsync(row);
  }
}

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(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    var table = database.GetTable("TABLE_NAME");

    // Insert a row into the table
    var embeddings = new double[] { 0.08f, -0.62f, 0.39f };
    var row = new Row()
    {
      { "title", "Computed Wilderness" },
      { "author", "Ryan Eau" },
      { "summary_genres_vector", embeddings },
    };

    await table.InsertOneAsync(row);
  }
}

Client reference

For more information, see the client reference.

Insert a row (C#)

Result

Parameters

Examples

Insert a row

Insert a row with vector embeddings

Client reference

Was this helpful?

Give Feedback