Projections for collections (Java)

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 (Java).

Include specific fields

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

Java client has different Options classes that provide a projection method. The projection method takes either an array of Projection classes with the field name and a boolean flag indicating inclusion or exclusion, or Projection syntactic sugar indicating which fields to include or exclude.

Example using the Projection syntactic sugar:

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.options.CollectionFindOneOptions;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Projection;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Use a projection
    Filter filter = Filters.eq("metadata.language", "English");
    CollectionFindOneOptions options =
        new CollectionFindOneOptions().projection(Projection.include("is_checked_out", "title"));
    Optional<Document> result = collection.findOne(filter, options);
    System.out.println(result);
  }
}

Example using an array of Projection classes:

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.options.CollectionFindOneOptions;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Projection;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Use a projection
    Filter filter = Filters.eq("metadata.language", "English");
    CollectionFindOneOptions options =
        new CollectionFindOneOptions()
            .projection(new Projection("is_checked_out", true), new Projection("title", true));
    Optional<Document> result = collection.findOne(filter, options);
    System.out.println(result);
  }
}

Exclude specific fields

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

Java client has different Options classes that provide a projection method. The projection method takes either an array of Projection classes with the field name and a boolean flag indicating inclusion or exclusion, or Projection syntactic sugar indicating which fields to include or exclude.

Example using the Projection syntactic sugar:

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.options.CollectionFindOneOptions;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Projection;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Use a projection
    Filter filter = Filters.eq("metadata.language", "English");
    CollectionFindOneOptions options =
        new CollectionFindOneOptions().projection(Projection.exclude("is_checked_out", "title"));
    Optional<Document> result = collection.findOne(filter, options);
    System.out.println(result);
  }
}

Example using an array of Projection classes:

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.options.CollectionFindOneOptions;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Projection;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Use a projection
    Filter filter = Filters.eq("metadata.language", "English");
    CollectionFindOneOptions options =
        new CollectionFindOneOptions()
            .projection(new Projection("is_checked_out", false), new Projection("title", false));
    Optional<Document> result = collection.findOne(filter, options);
    System.out.println(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 $).

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.options.CollectionFindOneOptions;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Projection;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Use a projection
    Filter filter = Filters.eq("metadata.language", "English");
    CollectionFindOneOptions options =
        new CollectionFindOneOptions()
            .projection(
                new Projection("is_checked_out", false),
                new Projection("title", false),
                new Projection("$vector", true));
    Optional<Document> result = collection.findOne(filter, options);
    System.out.println(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 $).

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.options.CollectionFindOneOptions;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Projection;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Use a projection
    Filter filter = Filters.eq("metadata.language", "English");
    CollectionFindOneOptions options =
        new CollectionFindOneOptions()
            .projection(
                new Projection("is_checked_out", true),
                new Projection("title", true),
                new Projection("_id", false));
    Optional<Document> result = collection.findOne(filter, options);
    System.out.println(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.

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.options.CollectionFindOneOptions;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Projection;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Use a projection
    Filter filter = Filters.eq("metadata.language", "English");
    CollectionFindOneOptions options =
        new CollectionFindOneOptions().projection(new Projection("*", true));
    Optional<Document> result = collection.findOne(filter, options);
    System.out.println(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.

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.options.CollectionFindOneOptions;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Projection;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Use a projection
    Filter filter = Filters.eq("metadata.language", "English");
    CollectionFindOneOptions options =
        new CollectionFindOneOptions().projection(new Projection("*", false));
    Optional<Document> result = collection.findOne(filter, options);
    System.out.println(result);
  }
}

Include or exclude array elements

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

Set the present parameter of the Projection class to null, and specify the sliceStart and sliceEnd parameters.

For example:

  • Return the first two indexes: sliceStart is 2, sliceEnd is null

  • Return the last two indexes: sliceStart is -2, sliceEnd is null

  • Return two indexes, starting at index 4: sliceStart is 4, sliceEnd is 2

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

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.options.CollectionFindOneOptions;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Projection;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Use a projection
    Filter filter = Filters.eq("metadata.language", "English");
    CollectionFindOneOptions options =
        new CollectionFindOneOptions()
            .projection(new Projection("genres", null, 4, 2), new Projection("title", true));
    Optional<Document> result = collection.findOne(filter, options);
    System.out.println(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.

Example using the Projection syntactic sugar:

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.options.CollectionFindOneOptions;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Projection;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Use a projection
    Filter filter = Filters.eq("metadata.language", "English");
    CollectionFindOneOptions options =
        new CollectionFindOneOptions().projection(Projection.include("metadata.edition", "title"));
    Optional<Document> result = collection.findOne(filter, options);
    System.out.println(result);
  }
}

Example using an array of Projection classes:

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.options.CollectionFindOneOptions;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Projection;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Use a projection
    Filter filter = Filters.eq("metadata.language", "English");
    CollectionFindOneOptions options =
        new CollectionFindOneOptions()
            .projection(new Projection("metadata.edition", true), new Projection("title", true));
    Optional<Document> result = collection.findOne(filter, options);
    System.out.println(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