Projections for tables (Python)

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.

You can use a dictionary or an iterable of columns names to include.

Example using a dictionary:

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)
table = database.get_table("TABLE_NAME")

# Use a projection
result = table.find_one(
    {"number_of_pages": {"$lt": 300}},
    projection={"is_checked_out": True, "title": True},
)

print(result)

Example using an iterable:

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)
table = database.get_table("TABLE_NAME")

# Use a projection
result = table.find_one(
    {"number_of_pages": {"$lt": 300}},
    projection=["is_checked_out", "title"],
)

print(result)

Exclude specific columns

The following examples exclude the is_checked_out and title columns.

Use a dictionary of column names to exclude.

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)
table = database.get_table("TABLE_NAME")

# Use a projection
result = table.find_one(
    {"number_of_pages": {"$lt": 300}},
    projection={"is_checked_out": False, "title": False},
)

print(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.

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)
table = database.get_table("TABLE_NAME")

# Use a projection
result = table.find_one(
    {"number_of_pages": {"$lt": 300}},
    projection={"*": True},
)

print(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.