Find a row (Go)

Finds a single row in a table using filter and sort clauses, including vector search.

For general information about working with tables and rows, see About tables with the Data API (Go).

Ready to write code? See the examples for this method to get started. If you are new to the Data API, check out the quickstart.

Result

Returns a *results.SingleResult pointer to a result object that encapsulates the response and any errors. Call Decode(v any) to unmarshal the row into v. If no row was found, Decode(v any) returns an ErrNoDocuments error.

The columns included in the returned row depend on the subset of columns that were requested in the projection. If requested and applicable, the row will also include a $similarity key with a numeric similarity score that represents the closeness of the sort vector and the row’s vector.

Parameters

Use the FindOne method, which belongs to the Table type.

Method signature 
func (t *Table) FindOne(
  ctx context.Context,
  f TableFilter,
  opts ...options.TableFindOneOption
) *results.SingleResult
Name Type Summary

ctx

context.Context

The context for the operation.

f

TableFilter

Optional. An object that defines filter criteria using the Data API filter syntax. The method only finds rows that match the filter criteria. Filters can improve performance by reducing the number of rows that the Data API processes.

For a list of available filter operators and more examples, see Filter operators for tables (Go).

To perform a vector search, use sort instead of filter.

To avoid fetching unnecessary rows, which can contain tombstones, DataStax recommends that you use a filter that limits the number of rows scanned. For example, filter on partition key columns or indexed columns.

Default: No filter

For an example, see Use filters to find a row.

opts

…​options.TableFindOneOption

Optional. A builder to generate options for this operation. See Methods of the options.TableFindOneOption builder for more details.
Methods of the options.TableFindOneOption builder
Method Summary

SetSort(v sort.Sortable)

Optional. Sorts rows by one or more columns, or performs a vector search.

For more information, see Sort clauses for tables (Go).

For examples, see Use sorting to find a row and Use vector search with a search vector to find a row.

SetProjection(v map[string]any)

Optional. Controls which columns are included or excluded in the returned rows.

For more information, see Projections for tables (Go).

DataStax recommends a projection to avoid unnecessarily returning large columns, such as vector columns with highly dimensional embeddings.

Default: All columns

For examples, see Include only specific columns in the response and Exclude specific columns from the response.

SetIncludeSimilarity(v bool)

Optional. Whether to include a $similarity property in the response. The $similarity value represents the closeness of the sort vector and the row’s vector.

Default: false

For an example, see Include the similarity score with the result.

UpdateAPIOptions(v …​APIOption)

Optional. General API options for this operation, including the timeout.

Examples

The following examples demonstrate how to find a row in a table.

Use filters to find a row

You can use a filter to find a row that matches specific criteria. For example, you can find a row with an is_checked_out value of false and a number_of_pages value less than 300.

For optimal performance, only filter on indexed columns. The Data API returns a warning if you filter on a non-indexed column.

For a list of available filter operators, see Filter operators for tables (Go).

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 table
	client := astra.NewClient(
		options.API().SetEnvironment(options.EnvironmentHCD),
	)

	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetUsernamePasswordTokenProvider(
				"USERNAME",
				"PASSWORD",
			).
			SetKeyspace("KEYSPACE_NAME"),
	)

	table := database.Table("TABLE_NAME")

	// Find a row
	var result astra.Row
	err := table.FindOne(
		ctx,
		filter.And(
			filter.Eq("is_checked_out", false),
			filter.Lt("number_of_pages", 300),
		),
	).Decode(&result)

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

	fmt.Println(result.ToMap())
}

Use vector search with a search vector to find a row

Perform a vector search by providing a search vector in the sort clause. This returns the row whose vector column value is most similar to the provided search vector.

The vector column must be indexed.

If your table has multiple vector columns, you can only sort on one vector column at a time.

You can use the datatypes.Vector struct to binary-encode your search vector. DataStax recommends that you always use a datatypes.Vector struct instead of a slice of floats to improve performance.

When you read the value of a vector column, the client always returns a datatypes.Vector struct when you decode the results into astra.Row or map[string]any. To decode the vector as a slice of floats, decode into a custom struct that defines the vector column as []float32.

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"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

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

	// Get an existing table
	client := astra.NewClient(
		options.API().SetEnvironment(options.EnvironmentHCD),
	)

	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetUsernamePasswordTokenProvider(
				"USERNAME",
				"PASSWORD",
			).
			SetKeyspace("KEYSPACE_NAME"),
	)

	table := database.Table("TABLE_NAME")

	// Find a row
	var result astra.Row
	err := table.FindOne(
		ctx,
		filter.F{},
		options.TableFindOne().
			SetSort(sort.Table.Vector("summary_genres_vector", []float32{0.08, -0.62, 0.39})),
	).Decode(&result)

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

	fmt.Println(result.ToMap())
}

Use lexicographical matching to find a row

Lexicographical matching is currently in public preview. Development is ongoing, and the features and functionality are subject to change. Hyper-Converged Database (HCD), and the use of such, is subject to the DataStax Preview Terms.

There are two ways to use lexicographical matching to find rows with the Data API:

  • Sort to find rows with a text or ascii column value that is most relevant to a given string of space-separated keywords or terms.

  • Filter with the $match operator to find rows with a text or ascii column value that is a lexicographical match to the specified string of space-separated keywords or terms

You can use these strategies together or separately.

Lexicographical matching is only available for text or ascii columns that have a text index, not a regular index. For more information, see Create a text index (Go) and Indexes in tables (Go).

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"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

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

	// Get an existing table
	client := astra.NewClient(
		options.API().SetEnvironment(options.EnvironmentHCD),
	)

	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetUsernamePasswordTokenProvider(
				"USERNAME",
				"PASSWORD",
			).
			SetKeyspace("KEYSPACE_NAME"),
	)

	table := database.Table("TABLE_NAME")

	// Find a row
	var result astra.Row
	err := table.FindOne(
		ctx,
		filter.Table.LexicalMatch(
			"summary",
			"futuristic laboratory discovery",
		),
		options.TableFindOne().
			SetSort(sort.Table.Lexical("summary", "futuristic laboratory")),
	).Decode(&result)

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

	fmt.Println(result.ToMap())
}

Use sorting to find a row

You can use a sort clause to sort rows by one or more columns.

For best performance, only sort on columns that are indexed or that are part of the primary key.

For more information, see Sort clauses for tables (Go).

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"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

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

	// Get an existing table
	client := astra.NewClient(
		options.API().SetEnvironment(options.EnvironmentHCD),
	)

	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetUsernamePasswordTokenProvider(
				"USERNAME",
				"PASSWORD",
			).
			SetKeyspace("KEYSPACE_NAME"),
	)

	table := database.Table("TABLE_NAME")

	// Find a row
	var result astra.Row
	err := table.FindOne(
		ctx,
		filter.Eq("is_checked_out", false),
		options.TableFindOne().SetSort(sort.Asc("rating").Desc("title")),
	).Decode(&result)

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

	fmt.Println(result.ToMap())
}

Include the similarity score with the result

If you use a vector search to find a row, you can also include a $similarity property in the result. The $similarity value represents the closeness of the sort vector and the value of the row’s vector column.

This parameter doesn’t work with vectorize; it only works if you provide the search vector for vector search directly.

The client always returns the similarity score as a datatypes.Vector struct.

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"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

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

	// Get an existing table
	client := astra.NewClient(
		options.API().SetEnvironment(options.EnvironmentHCD),
	)

	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetUsernamePasswordTokenProvider(
				"USERNAME",
				"PASSWORD",
			).
			SetKeyspace("KEYSPACE_NAME"),
	)

	table := database.Table("TABLE_NAME")

	// Find a row
	var result astra.Row
	err := table.FindOne(
		ctx,
		filter.F{},
		options.TableFindOne().
			SetSort(sort.Table.Vector("summary_genres_vector", []float32{0.08, -0.62, 0.39})).
			SetIncludeSimilarity(true),
	).Decode(&result)

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

	fmt.Println(result.ToMap())
}

Include only specific columns in the response

To specify which columns to include or exclude in the returned row, use a projection.

The following example demonstrates an inclusive projection.

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 table
	client := astra.NewClient(
		options.API().SetEnvironment(options.EnvironmentHCD),
	)

	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetUsernamePasswordTokenProvider(
				"USERNAME",
				"PASSWORD",
			).
			SetKeyspace("KEYSPACE_NAME"),
	)

	table := database.Table("TABLE_NAME")

	// Find a row
	var result astra.Row
	err := table.FindOne(
		ctx,
		filter.Lt("number_of_pages", 300),
		options.TableFindOne().SetProjection(map[string]any{
			"is_checked_out": true,
			"title":          true,
		}),
	).Decode(&result)

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

	fmt.Println(result.ToMap())
}

Exclude specific columns from the response

To specify which columns to include or exclude in the returned row, use a projection.

The following example demonstrates an exclusive projection.

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 table
	client := astra.NewClient(
		options.API().SetEnvironment(options.EnvironmentHCD),
	)

	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetUsernamePasswordTokenProvider(
				"USERNAME",
				"PASSWORD",
			).
			SetKeyspace("KEYSPACE_NAME"),
	)

	table := database.Table("TABLE_NAME")

	// Find a row
	var result astra.Row
	err := table.FindOne(
		ctx,
		filter.Lt("number_of_pages", 300),
		options.TableFindOne().SetProjection(map[string]any{
			"is_checked_out": false,
			"title":          false,
		}),
	).Decode(&result)

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

	fmt.Println(result.ToMap())
}

Use filter, sort, and projection together

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"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

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

	// Get an existing table
	client := astra.NewClient(
		options.API().SetEnvironment(options.EnvironmentHCD),
	)

	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetUsernamePasswordTokenProvider(
				"USERNAME",
				"PASSWORD",
			).
			SetKeyspace("KEYSPACE_NAME"),
	)

	table := database.Table("TABLE_NAME")

	// Find a row
	var result astra.Row
	err := table.FindOne(
		ctx,
		filter.And(
			filter.Eq("is_checked_out", false),
			filter.Lt("number_of_pages", 300),
		),
		options.TableFindOne().
			SetSort(sort.Asc("rating").Desc("title")).
			SetProjection(map[string]any{
				"is_checked_out": true,
				"title":          true,
			}),
	).Decode(&result)

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

	fmt.Println(result.ToMap())
}

Client reference

For more information, see the client reference.

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