Projections for collections (Go)

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

Include specific fields

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

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Use a projection
	var result astra.Document
	err := collection.FindOne(
		ctx,
		filter.Eq("metadata.language", "English"),
		options.CollectionFindOne().SetProjection(map[string]any{
			"is_checked_out": true,
			"title":          true,
		}),
	).Decode(&result)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.ToMap())
}

Exclude specific fields

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

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Use a projection
	var result astra.Document
	err := collection.FindOne(
		ctx,
		filter.Eq("metadata.language", "English"),
		options.CollectionFindOne().SetProjection(map[string]any{
			"is_checked_out": false,
			"title":          false,
		}),
	).Decode(&result)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.ToMap())
}

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

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Use a projection
	var result astra.Document
	err := collection.FindOne(
		ctx,
		filter.Eq("metadata.language", "English"),
		options.CollectionFindOne().SetProjection(map[string]any{
			"is_checked_out": false,
			"title":          false,
			"$vectorize":     true,
		}),
	).Decode(&result)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.ToMap())
}

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

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Use a projection
	var result astra.Document
	err := collection.FindOne(
		ctx,
		filter.Eq("metadata.language", "English"),
		options.CollectionFindOne().SetProjection(map[string]any{
			"is_checked_out": true,
			"title":          true,
			"_id":            false,
		}),
	).Decode(&result)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.ToMap())
}

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.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Use a projection
	var result astra.Document
	err := collection.FindOne(
		ctx,
		filter.Eq("metadata.language", "English"),
		options.CollectionFindOne().SetProjection(map[string]any{
			"*": true,
		}),
	).Decode(&result)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.ToMap())
}

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.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Use a projection
	var result astra.Document
	err := collection.FindOne(
		ctx,
		filter.Eq("metadata.language", "English"),
		options.CollectionFindOne().SetProjection(map[string]any{
			"*": false,
		}),
	).Decode(&result)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.ToMap())
}

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 map[string]any{"$slice": SLICE_VALUE} to indicate which array indexes to include.

For example:

Return the first two indexes: "field_name": map[string]any{"$slice": 2}
Return the last two indexes: "field_name": map[string]any{"$slice": -2}
Return two indexes, starting at the fourth index: "field_name": map[string]any{"$slice": []any{4, 2}}
Return two indexes, starting at the fourth index from the end: "field_name": map[string]any{"$slice": []any{-4, 2}}

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Use a projection
	var result astra.Document
	err := collection.FindOne(
		ctx,
		filter.Eq("metadata.language", "English"),
		options.CollectionFindOne().SetProjection(map[string]any{
			"genres": map[string]any{
				"$slice": []any{4, 2},
			},
			"title": true,
		}),
	).Decode(&result)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.ToMap())
}

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.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Use a projection
	var result astra.Document
	err := collection.FindOne(
		ctx,
		filter.Eq("metadata.language", "English"),
		options.CollectionFindOne().SetProjection(map[string]any{
			"metadata.edition": true,
			"title":            true,
		}),
	).Decode(&result)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.ToMap())
}