Create a collection (C#)

Creates a new collection in a database.

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

Creates a collection with the specified parameters.

Returns a Collection object. You can use this object to work with documents in the collection.

By default, the Collection object is typed as Collection<Document>, where Document is Dictionary<string, object>. You can enable stronger typing by specifying a type when you create the collection. For more information and examples, see Custom typing for collections.

Parameters

You cannot edit a collection’s definition after you create the collection.

Use the CreateCollectionAsync method, which belongs to the Database class. You can also use CreateCollection, which is the synchronous version of the method.

Method signature 
public Task<Collection<T, TId>> CreateCollectionAsync<T, TId>(
  string collectionName,
  CollectionDefinition definition,
  CreateCollectionOptions options = null
) where T : class;
public Task<Collection<T, TId>> CreateCollectionAsync<T, TId>(
  CollectionDefinition definition, CreateCollectionOptions options = null
) where T : class;
public Task<Collection<T, TId>> CreateCollectionAsync<T, TId>(
  string collectionName, CreateCollectionOptions options = null
) where T : class;
public Task<Collection<T, TId>> CreateCollectionAsync<T, TId>(
  CreateCollectionOptions options = null
) where T : class;
public Task<Collection<Document>> CreateCollectionAsync(
  string collectionName,
  CollectionDefinition definition,
  CreateCollectionOptions options = null
);
public Task<Collection<T>> CreateCollectionAsync<T>(
  string collectionName,
  CollectionDefinition definition,
  CreateCollectionOptions options = null
) where T : class;
public Task<Collection<T>> CreateCollectionAsync<T>(
  CollectionDefinition definition, CreateCollectionOptions options = null
) where T : class;
public Task<Collection<T>> CreateCollectionAsync<T>(
  string collectionName, CreateCollectionOptions options = null
) where T : class;
public Task<Collection<T>> CreateCollectionAsync<T>(
  CreateCollectionOptions options = null
) where T : class;
public Task<Collection<Document>> CreateCollectionAsync(
  string collectionName, CreateCollectionOptions options = null
);
Name Type Summary

collectionName

string

The name of the new collection.

Collection names must follow these rules:

  • Can contain letters, numbers, and underscores

  • Cannot exceed 48 characters

  • Must be unique within the keyspace

If not specified, the client attempts to extract it from the CollectionName attribute on the custom document class if one is used. For more information and examples, see Custom typing for collections.

definition

CollectionDefinition

Optional. The full configuration for the collection. See Properties of the CollectionDefinition class and Examples for more details.

options

CreateCollectionOptions

Optional. Options for this operation. Keyspace is required unless you specified a working keyspace when instantiating the Database object. For more information and examples for general options such as timeout and keyspace, see Customize API interaction.
Properties of the CollectionDefinition class
Name Type Summary

Vector

VectorOptions

Optional. The vector configuration for the collection. This includes things like the vector dimension and similarity metric.

Required for vector search.

See Create a collection that can store vector embeddings for usage.

DefaultId

DefaultIdOptions

Optional. Specifies the default ID type for documents in the collection. This is used when you insert a document without an _id field.

DefaultId.Type can be one of:

  • DefaultIdType.ObjectId: Each autogenerated _id value is an objectId as provided by the bson library.

  • DefaultIdType.UuidV7: Each autogenerated _id value is a version 7 UUID. This is designed as a replacement for version 1 time UUID, and it is recommended for use in new systems.

  • DefaultIdType.UuidV6: Each autogenerated _id value is a version 6 UUID. This is field-compatible with version 1 time UUIDs, and it supports lexicographical sorting.

  • DefaultIdType.Uuid: Each autogenerated _id value is a version 4 UUID. This type is analogous to the uuid type and functions in Apache Cassandra®.

See the example for usage.

For more information, see Document IDs (C#).

Default: Each autogenerated _id value is a string form of a version 4 UUID

Indexing

IndexingOptions

Optional. The selective indexing configuration for the collection.

You must use & to escape any . or & in field names in the indexing clause. You cannot use & to escape any other characters. Dot notation, which is used to reference nested fields, should not be escaped.

See Create a collection and specify which fields to index and Create a collection and specify which fields shouldn’t be indexed for usage.

Default: All fields of all documents.

Examples

The following examples demonstrate how to create a collection.

Create a collection that is not vector-enabled

  • Typed collections

  • Untyped collections

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.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.SerDes;

namespace Examples;

// Define the type for the collection
[CollectionName("COLLECTION_NAME")]
public class User
{
  [DocumentId]
  public Guid? Id { get; set; }

  public string Name { get; set; } = null!;

  public int? Age { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

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

    // Create a collection
    var collection = await database.CreateCollectionAsync<User>();
  }
}

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;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

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

    // Create a collection
    var collection = await database.CreateCollectionAsync(
      "COLLECTION_NAME"
    );
  }
}

Create a collection that can store vector embeddings

Collections that are vector-enabled can store vector embeddings in the reserved $vector field and work with vector search.

For optimal vector search results, you should specify the dimension, metric, and source model of your vector embeddings. All vector embeddings in a collection should be generated by the same model with the same dimensions. The source model can be one of: ada002, bert, cohere-v3, gecko, nv-qa-4, openai-v3-large, openai-v3-small, other.

  • Typed collections

  • Untyped collections

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.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.SerDes;

namespace Examples;

// Define the type for the collection
[CollectionName("COLLECTION_NAME")]
[CollectionVector(SimilarityMetric.Cosine, 1024, SourceModel = "nv-qa-4")]
public class User
{
  [DocumentId]
  public Guid? Id { get; set; }

  public string Name { get; set; } = null!;

  public int? Age { get; set; }

  [DocumentMapping(DocumentMappingField.Vector)]
  public float[]? VectorEmbeddings { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

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

    // Create a collection
    var collection = await database.CreateCollectionAsync<User>();
  }
}

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;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

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

    // Create a collection
    var definition = new CollectionDefinition()
    {
      Vector = new VectorOptions()
      {
        Dimension = 1024,
        Metric = SimilarityMetric.Cosine,
        SourceModel = "nv-qa-4",
      },
    };

    var collection = await database.CreateCollectionAsync(
      "COLLECTION_NAME",
      definition
    );
  }
}

Create a collection that supports lexicographical matching

If you want to use lexicographical matching to find documents in your collection, you must create a collection that has lexical enabled. Your collection must also be in a database in the AWS us-east-2 region.

Lexical is enabled by default when you create a collection in a database in the AWS us-east-2 region, but you can optionally configure the lexical analyzer.

For configuration details about the lexical analyzer, see Configure and use SAI text analyzers with CQL. The following example uses a configuration suitable for English text.

  • Typed collections

  • Untyped collections

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.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.SerDes;

namespace Examples;

// Define the type for the collection
[CollectionName("COLLECTION_NAME")]
[LexicalOptions(
  TokenizerName = "standard",
  Filters = new[] { "lowercase", "stop", "porterstem", "asciifolding" },
  CharacterFilters = new string[] { }
)]
public class User
{
  [DocumentId]
  public Guid? Id { get; set; }

  public string Name { get; set; } = null!;

  public int? Age { get; set; }

  [DocumentMapping(DocumentMappingField.Vectorize)]
  public string StringToVectorize => Name;
}

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

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

    // Create a collection
    var collection = await database.CreateCollectionAsync<User>();
  }
}

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;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

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

    // Create a collection
    var definition = new CollectionDefinition()
    {
      Lexical = new LexicalOptions()
      {
        Analyzer = new AnalyzerOptions()
        {
          Tokenizer = new TokenizerOptions()
          {
            Name = "standard",
            Arguments = new Dictionary<string, object>() { },
          },
          Filters = new List<string>()
          {
            "lowercase",
            "stop",
            "porterstem",
            "asciifolding",
          },
          CharacterFilters = new List<string>() { },
        },
        Enabled = true,
      },
    };

    var collection = await database.CreateCollectionAsync(
      "COLLECTION_NAME",
      definition
    );
  }
}

Create a collection and specify the default ID format

For more information about the default ID format, see Document IDs (C#). For allowed values, see the Parameters.

  • Typed collections

  • Untyped collections

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.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.SerDes;
using MongoDB.Bson;

namespace Examples;

// Define the type for the collection
[CollectionName("COLLECTION_NAME")]
public class User
{
  [DocumentId(DefaultIdType.ObjectId)]
  public ObjectId? Id { get; set; }

  public string Name { get; set; } = null!;

  public int? Age { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

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

    // Create a collection
    var collection = await database.CreateCollectionAsync<User>();
  }
}

If you create a custom-typed collection without providing a CollectionDefinition, then you can use one of the following attributes on your custom type to specify the default ID type instead:

  • [DocumentId(DefaultIdType.UuidV6)]

  • [DocumentId(DefaultIdType.UuidV7)]

  • [DocumentId(DefaultIdType.ObjectId)]

  • [DocumentId] (defaults to UUID v4)

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;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

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

    // Create a collection
    var definition = new CollectionDefinition()
    {
      DefaultId = new DefaultIdOptions()
      {
        Type = DefaultIdType.ObjectId,
      },
    };

    var collection = await database.CreateCollectionAsync(
      "COLLECTION_NAME",
      definition
    );
  }
}

Create a collection and specify which fields to index

For more information about selective indexing, see Indexes in collections (C#).

  • Typed collections

  • Untyped collections

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.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.SerDes;

namespace Examples;

// Define the type for the collection
[CollectionName("COLLECTION_NAME")]
public class User
{
  [DocumentId]
  public Guid? Id { get; set; }

  public string Name { get; set; } = null!;

  public int? Age { get; set; }

  public string? City { get; set; }

  public string? Country { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

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

    // Create a collection
    var definition = new CollectionDefinition()
    {
      Indexing = new IndexingOptions()
      {
        Allow = new List<string> { "City", "Country" },
      },
    };

    var collection = await database.CreateCollectionAsync<User>(
      definition
    );
  }
}

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;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

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

    // Create a collection
    var definition = new CollectionDefinition()
    {
      Indexing = new IndexingOptions()
      {
        Allow = new List<string> { "city", "country" },
      },
    };

    var collection = await database.CreateCollectionAsync(
      "COLLECTION_NAME",
      definition
    );
  }
}

Create a collection and specify which fields shouldn’t be indexed

For more information about selective indexing, see Indexes in collections (C#).

  • Typed collections

  • Untyped collections

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.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.SerDes;

namespace Examples;

// Define the type for the collection
[CollectionName("COLLECTION_NAME")]
public class User
{
  [DocumentId]
  public Guid? Id { get; set; }

  public string Name { get; set; } = null!;

  public int? Age { get; set; }

  public string? City { get; set; }

  public string? Country { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

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

    // Create a collection
    var definition = new CollectionDefinition()
    {
      Indexing = new IndexingOptions()
      {
        Deny = new List<string> { "City", "Country" },
      },
    };

    var collection = await database.CreateCollectionAsync<User>(
      definition
    );
  }
}

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;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

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

    // Create a collection
    var definition = new CollectionDefinition()
    {
      Indexing = new IndexingOptions()
      {
        Deny = new List<string> { "city", "country" },
      },
    };

    var collection = await database.CreateCollectionAsync(
      "COLLECTION_NAME",
      definition
    );
  }
}

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