Find distinct values

Tables with the Data API are currently in public preview. Development is ongoing, and the features and functionality are subject to change. Astra DB Serverless, and the use of such, is subject to the DataStax Preview Terms.

Finds the distinct values of a column for rows in a table.

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

This method finds all rows that match the filter, or all rows if no filter is applied. There can be performance, latency, and billing implications if there are many matching rows.

Method signature

  • Python

  • TypeScript

  • Java

  • curl

The following method belongs to the astrapy.Table class.

distinct(
  key: str,
  *,
  filter: Dict[str, Any],
  general_method_timeout_ms: int,
  request_timeout_ms: int,
  timeout_ms: int,
) -> list[Any]

The TypeScript client does not support this method. Instead, you can use Find rows, and then extract the desired values from the response.

The following methods belong to the com.datastax.astra.client.tables.Table class.

<R> List<R> distinct(
  String fieldName,
  Filter filter,
  Class<R> resultClass
)
<R> List<R> distinct(
  String fieldName,
  Filter filter,
  Class<R> resultClass,
  TableDistinctOptions options
)

This method has no literal equivalent in HTTP. Instead, you can use Find rows, and then extract the desired values from the response.

Result

  • Python

  • TypeScript

  • Java

  • curl

Returns a list of the distinct values of the specified key.

Example response:

['home_appliance', None, 'sports_equipment', {'cat_id': 54, 'cat_name': 'gardening_gear'}]

The TypeScript client does not support this method. Instead, you can use Find rows, and then extract the desired values from the response.

Returns a list of the distinct values of the specified key.

This method has no literal equivalent in HTTP. Instead, you can use Find rows, and then extract the desired values from the response.

Parameters

  • Python

  • TypeScript

  • Java

  • curl

Name Type Summary

key

str

The name of the field whose value is inspected across rows. Keys are typically just column names, although they can use dot notation to select particular entries in map columns. For set and list columns, individual entries are unrolled automatically. Particularly for lists, numeric indices can be used in the key dot-notation syntax. Examples of acceptable key values include "a_column", "map_column.map_key", and "list_column.2".

filter

dict

A dictionary expressing which condition the inspected rows must satisfy. You can use filter operators to compare columns with literal values. For example:

  • {"match_no": 123}: Uses the implied equality ($eq) operator. Shorthand for {"match_no": {"$eq": 123}}.

  • {"match_no": 123, "round": "C"}: Uses the implied equality operator and combines the two conditions with an implicit $and.

  • {}: An empty filter (all rows).

general_method_timeout_ms

int | None

A timeout, in milliseconds, to impose on the underlying API request. If not provided, the Table defaults apply. This parameter is aliased as timeout_ms for convenience.

request_timeout_ms

int | None

A timeout, in milliseconds, for each API request performed while scrolling through matches (see find). If not provided, this object’s defaults apply.

The TypeScript client does not support this method. Instead, you can use Find rows, and then extract the desired values from the response.

Name Type Summary

fieldName

String

The name of the field on which perform the distinct

filter

Filter

A filter expressing which condition the inspected rows must satisfy. You can use filter operators to compare columns with literal values. Filters can be instantiated with its constructor and specialized with method where(..) or leverage the class Filters.

columnClass

Class<?>

Represents the expected type of the column returned. For example, if the target column is text or ascii, then the returned value type is String.class.

options

TableDistinctOptions

A wrapper for the different options and specialization of this search.

This method has no literal equivalent in HTTP. Instead, you can use Find rows, and then extract the desired values from the response.

Examples

The following examples demonstrate how to find distinct values of a column for rows in a table.

Find distinct values of a column for rows that match a filter

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Find distinct values
result = table.distinct(
  "publicationYear",
  filter={
    "$and": [
      {"isCheckedOut": False},
      {"numberOfPages": {"$lt": 300}},
    ]
  }
)

print(result)

The TypeScript client does not support this method. Instead, you can use Find rows, and then extract the desired values from the response.

package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.tables.Table;

import java.util.List;

public class FindDistinct {

    public static void main(String[] args) {
        // Get an existing table
        Table<Row> table = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getTable("TABLE_NAME");

        // Find distinct values
        Filter filter = Filters.and(
          Filters.eq("isCheckedOut", false),
          Filters.lt("numberOfPages", 300));
        List<String> result = table
                .distinct("publicationYear", filter, String.class);

        for (String fieldValue : result) {
            System.out.println(fieldValue);
        }
    }
}

This method has no literal equivalent in HTTP. Instead, you can use Find rows, and then extract the desired values from the response.

Find distinct values of a column for all rows

To find the distinct values of a column for all rows in the table, use an empty filter.

You should avoid this if you have a large number of rows.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Find distinct values
result = table.distinct(
  "publicationYear",
  filter={}
)

print(result)

The TypeScript client does not support this method. Instead, you can use Find rows, and then extract the desired values from the response.

package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.tables.Table;

import java.util.List;

public class FindDistinct {

    public static void main(String[] args) {
        // Get an existing table
        Table<Row> table = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getTable("TABLE_NAME");

        // Find distinct values
        Filter filter = new Filter();
        List<String> result = table
                .distinct("publicationYear", filter, String.class);

        for (String fieldValue : result) {
            System.out.println(fieldValue);
        }
    }
}

This method has no literal equivalent in HTTP. Instead, you can use Find rows, and then extract the desired values from the response.

Client reference

  • Python

  • TypeScript

  • Java

  • curl

For more information, see the client reference.

The TypeScript client does not support this method. Instead, you can use Find rows, and then extract the desired values from the response.

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

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