Projections for tables (Java)

You can use a projection with some Data API commands to control what columns to return.

When you specify a projection, you specify which columns to include or exclude. You cannot specify a mix of inclusions and exclusions.

If you don’t specify a projection, the Data API returns all columns. In order to optimize the response size and improve read performance, DataStax recommends always providing a projection tailored to the needs of your application.

Null values

If you make a direct HTTP request to the Data API, the response always excludes null values, regardless of the projection. This means that the response may include different columns for each returned row, depending on which columns are null in the row. You cannot forcibly include null values in the response.

If you use one of the clients, the client adds columns that were omitted due to a null value.

Include specific columns

The following examples include the is_checked_out and title columns.

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

Example using the Projection syntactic sugar:

import com.datastax.astra.client.DataAPIClients;
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 com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOneOptions;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getTable("TABLE_NAME");

    // Use a projection
    Filter filter = Filters.lt("number_of_pages", 300);
    TableFindOneOptions options =
        new TableFindOneOptions().projection(Projection.include("is_checked_out", "title"));
    Optional<Row> result = table.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.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Projection;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOneOptions;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getTable("TABLE_NAME");

    // Use a projection
    Filter filter = Filters.lt("number_of_pages", 300);
    TableFindOneOptions options =
        new TableFindOneOptions()
            .projection(new Projection("is_checked_out", true), new Projection("title", true));
    Optional<Row> result = table.findOne(filter, options);
    System.out.println(result);
  }
}

Exclude specific columns

The following examples exclude the is_checked_out and title columns.

Example using the Projection syntactic sugar:

import com.datastax.astra.client.DataAPIClients;
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 com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOneOptions;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getTable("TABLE_NAME");

    // Use a projection
    Filter filter = Filters.lt("number_of_pages", 300);
    TableFindOneOptions options =
        new TableFindOneOptions().projection(Projection.exclude("is_checked_out", "title"));
    Optional<Row> result = table.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.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Projection;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOneOptions;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getTable("TABLE_NAME");

    // Use a projection
    Filter filter = Filters.lt("number_of_pages", 300);
    TableFindOneOptions options =
        new TableFindOneOptions()
            .projection(new Projection("is_checked_out", false), new Projection("title", false));
    Optional<Row> result = table.findOne(filter, options);
    System.out.println(result);
  }
}

Include all columns

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

If set to true, all columns are returned. This is equivalent to not specifying a projection.

You cannot set the wildcard projection to false.

import com.datastax.astra.client.DataAPIClients;
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 com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOneOptions;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Optional;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getTable("TABLE_NAME");

    // Use a projection
    Filter filter = Filters.lt("number_of_pages", 300);
    TableFindOneOptions options = new TableFindOneOptions().projection(new Projection("*", true));
    Optional<Row> result = table.findOne(filter, options);
    System.out.println(result);
  }
}

Unsupported cases

A projection cannot include or exclude sub-column values, such as keys in map columns.

The Data API doesn’t support false wildcard projections for tables.