Projections for collections (C#)

You can use a projection with many Data API commands to control what fields to include in the returned documents.

If you don’t specify a projection, the Data API returns the _id field and all fields that are not prefixed with $. In order to optimize the response size and improve read performance, DataStax recommends always providing a projection tailored to the needs of the application.

When you specify a projection, you specify which fields to include or exclude. You cannot specify a mix of inclusions and exclusions unless the field is _id or is prefixed with $.

If a projection includes fields that don’t exist in a returned document, then those fields are ignored for that document.

You must use & to escape any . or & in field names in a projection. Dot notation, which is used to reference nested fields, should not be escaped. For more information, see Work with . and & in field names (C#).

Include specific fields

The following examples include the is_checked_out and title fields. _id is included by default.

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;

namespace Examples;

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

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

    var collection = database.GetCollection("COLLECTION_NAME");

    // Use a projection
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Eq("metadata.language", "English");
    var findOptions = new CollectionFindOneOptions<Document>()
    {
      Projection = Builders<Document>
        .Projection.Include("is_checked_out")
        .Include("title"),
    };

    var result = await collection.FindOneAsync(filter, findOptions);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}

Exclude specific fields

The following examples exclude the is_checked_out and title fields. All fields prefixed with $ are excluded by default.

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;

namespace Examples;

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

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

    var collection = database.GetCollection("COLLECTION_NAME");

    // Use a projection
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Eq("metadata.language", "English");
    var findOptions = new CollectionFindOneOptions<Document>()
    {
      Projection = Builders<Document>
        .Projection.Exclude("is_checked_out")
        .Exclude("title"),
    };
    var result = await collection.FindOneAsync(filter, findOptions);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}

Explicitly include fields prefixed by $

All fields prefixed with $ are excluded by default. You must explicitly include these fields in the projection if you want the Data API to return them.

Although you cannot specify a mix of included and excluded regular fields, you can specify a mix of included and excluded reserved fields (_id or fields prefixed with $).

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;

namespace Examples;

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

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

    var collection = database.GetCollection("COLLECTION_NAME");

    // Use a projection
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Eq("metadata.language", "English");
    var findOptions = new CollectionFindOneOptions<Document>()
    {
      Projection = Builders<Document>
        .Projection.Exclude("is_checked_out")
        .Exclude("title")
        .IncludeSpecial("$vector"),
    };

    var result = await collection.FindOneAsync(filter, findOptions);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}

Explicitly exclude the _id field

_id is included by default. You must explicitly exclude _id from the projection if you want the Data API to omit that field.

Although you cannot specify a mix of included and excluded regular fields, you can specify a mix of included and excluded special fields (_id or fields prefixed with $).

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;

namespace Examples;

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

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

    var collection = database.GetCollection("COLLECTION_NAME");

    // Use a projection
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Eq("metadata.language", "English");
    var findOptions = new CollectionFindOneOptions<Document>()
    {
      Projection = Builders<Document>
        .Projection.Include("is_checked_out")
        .Include("title")
        .ExcludeSpecial("_id"),
    };
    var result = await collection.FindOneAsync(filter, findOptions);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}

Include all fields

The wildcard projection "*" represents the whole document. If you use this projection, it must be the only key in the projection.

If set to true, all fields are returned.

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;

namespace Examples;

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

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

    var collection = database.GetCollection("COLLECTION_NAME");

    // Use a projection
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Eq("metadata.language", "English");
    var findOptions = new CollectionFindOneOptions<Document>()
    {
      Projection = Builders<Document>.Projection.Include("*"),
    };

    var result = await collection.FindOneAsync(filter, findOptions);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}

Exclude all fields

The wildcard projection "*" represents the whole of the document. If you use this projection, it must be the only key in the projection.

If set to false, no fields are returned.

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;

namespace Examples;

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

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

    var collection = database.GetCollection("COLLECTION_NAME");

    // Use a projection
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Eq("metadata.language", "English");
    var findOptions = new CollectionFindOneOptions<Document>()
    {
      Projection = Builders<Document>.Projection.Exclude("*"),
    };

    var result = await collection.FindOneAsync(filter, findOptions);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}

Include or exclude array elements

For array fields, you can use $slice to specify which elements of the array to return.

Use Slice with start and optionally length parameters to indicate which array indexes to include.

For example:

  • Return the first two indexes: start is 2, length is null

  • Return the last two indexes: start is -2, length is null

  • Return two indexes, starting at index 4: start is 4, length is 2

  • Return two indexes, starting at the fourth index from the end: start is -4, length is 2

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;

namespace Examples;

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

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

    var collection = database.GetCollection("COLLECTION_NAME");

    // Use a projection
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Eq("metadata.language", "English");
    var findOptions = new CollectionFindOneOptions<Document>()
    {
      Projection = Builders<Document>
        .Projection.Slice("genres", 4, 2)
        .Include("title"),
    };

    var result = await collection.FindOneAsync(filter, findOptions);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}

Include or exclude nested fields

To refer to nested fields in the projection, use dot notation. For example, field.subfield.subsubfield.

You cannot reference overlapping paths. For example, using both continent.country and continent.country.city in a projection will raise an error.

If you exclude all subfields of a field, then the return value of the field will be an empty object.

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;

namespace Examples;

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

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

    var collection = database.GetCollection("COLLECTION_NAME");

    // Use a projection
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.Eq("metadata.language", "English");
    var findOptions = new CollectionFindOneOptions<Document>()
    {
      Projection = Builders<Document>
        .Projection.Include("metadata.edition")
        .Include("title"),
    };

    var result = await collection.FindOneAsync(filter, findOptions);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}

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