Projections for collections

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.

Include specific fields

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

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

Example using a dictionary:

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT",
    token="APPLICATION_TOKEN",
)
collection = database.get_collection("COLLECTION_NAME")

# Use a projection
cursor = collection.find(
    {"metadata.language": "English"},
    projection={"is_checked_out": True, "title": True},
)

Example using an iterable:

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT",
    token="APPLICATION_TOKEN",
)
collection = database.get_collection("COLLECTION_NAME")

# Use a projection
cursor = collection.find(
    {"metadata.language": "English"},
    projection=["is_checked_out", "title"],
)

Exclude specific fields

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

Use a dictionary of field names to exclude.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT",
    token="APPLICATION_TOKEN",
)
collection = database.get_collection("COLLECTION_NAME")

# Use a projection
cursor = collection.find(
    {"metadata.language": "English"},
    projection={"is_checked_out": False, "title": False},
)

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 $).

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT",
    token="APPLICATION_TOKEN",
)
collection = database.get_collection("COLLECTION_NAME")

# Use a projection
cursor = collection.find(
    {"metadata.language": "English"},
    projection={"is_checked_out": False, "title": False, "$vector": True},
)

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 $).

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT",
    token="APPLICATION_TOKEN",
)
collection = database.get_collection("COLLECTION_NAME")

# Use a projection
cursor = collection.find(
    {"metadata.language": "English"},
    projection={"is_checked_out": True, "title": True, "_id": False},
)

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.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT",
    token="APPLICATION_TOKEN",
)
collection = database.get_collection("COLLECTION_NAME")

# Use a projection
cursor = collection.find(
    {"metadata.language": "English"},
    projection={"*": True},
)

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.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT",
    token="APPLICATION_TOKEN",
)
collection = database.get_collection("COLLECTION_NAME")

# Use a projection
cursor = collection.find(
    {"metadata.language": "English"},
    projection={"*": False},
)

Include or exclude array elements

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

Instead of using True or False, use {"$slice": SLICE_VALUE} to indicate which array indexes to include.

For example:

  • Return the first two indexes: {"field_name": {"$slice": 2}}

  • Return the last two indexes: {"field_name": {"$slice": -2}}

  • Return two indexes, starting at index 4: {"field_name": {"$slice": [4, 2]}}

  • Return two indexes, starting at the fourth index from the end: {"field_name": {"$slice": [-4, 2]}}

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT",
    token="APPLICATION_TOKEN",
)
collection = database.get_collection("COLLECTION_NAME")

# Use a projection
cursor = collection.find(
    {"metadata.language": "English"},
    projection={"genres": {"$slice": [4, 2]}, "title": True},
)

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.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT",
    token="APPLICATION_TOKEN",
)
collection = database.get_collection("COLLECTION_NAME")

# Use a projection
cursor = collection.find(
    {"metadata.language": "English"},
    projection={"metadata.edition": True, "title": True},
)

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax | 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: +1 (650) 389-6000, info@datastax.com