ColumnFilter (apache-cassandra API)
Date: 2018-02-14

org.apache.cassandra.db.filter

## Class ColumnFilter

- java.lang.Object
- - org.apache.cassandra.db.filter.ColumnFilter

-     public class ColumnFilter
      extends java.lang.Object

  Represents which (non-PK) columns (and optionally which sub-part of a column for complex columns) are selected by a query. We distinguish 2 sets of columns in practice: the _fetched_ columns, which are the columns that we (may, see below) need to fetch internally, and the _queried_ columns, which are the columns that the user has selected in its request. The reason for distinguishing those 2 sets is that due to the CQL semantic (see #6588 for more details), we often need to internally fetch all columns for the queried table, but can still do some optimizations for those columns that are not directly queried by the user (see #10657 for more details). Note that in practice: - the _queried_ columns set is always included in the _fetched_ one. - whenever those sets are different, we know the _fetched_ set contains all columns for the table, so we don't have to record this set, we just keep a pointer to the table metadata. The only set we concretely store is thus the _queried_ one. - in the special case of a `SELECT *` query, we want to query all columns, and _fetched_ == _queried. As this is a common case, we special case it by keeping the _queried_ set `null` (and we retrieve the columns through the metadata pointer). For complex columns, this class optionally allows to specify a subset of the cells to query for each column. We can either select individual cells by path name, or a slice of them. Note that this is a sub-selection of _queried_ cells, so if _fetched_ != _queried_, then the cell selected by this sub-selection are considered queried and the other ones are considered fetched (and if a column has some sub-selection, it must be a queried column, which is actually enforced by the Builder below).

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ColumnFilter.Builder` A builder for a `ColumnFilter` object.
    `static class` | `ColumnFilter.Serializer`
    `static class` | `ColumnFilter.Tester`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static ColumnFilter.Serializer` | `serializer`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static ColumnFilter` | `all(CFMetaData metadata)` A filter that includes all columns for the provided table.
    `static ColumnFilter.Builder` | `allColumnsBuilder(CFMetaData metadata)` Returns a `ColumnFilter`} builder that fetches all columns (and queries the columns added to the builder, or everything if no column is added).
    `boolean` | `allFetchedColumnsAreQueried()` Whether _fetched_ == _queried_ for this filter, and so if the `isQueried()` methods can return `false` for some column/cell.
    `boolean` | `equals(java.lang.Object other)`
    `boolean` | `fetchedCellIsQueried(ColumnDefinition column, CellPath path)` Whether the provided complex cell (identified by its column and path), which is assumed to be _fetched_ by this filter, is also _queried_ by the user.
    `boolean` | `fetchedColumnIsQueried(ColumnDefinition column)` Whether the provided column, which is assumed to be _fetched_ by this filter (so the caller must guarantee that `fetches(column) == true`, is also _queried_ by the user.
    `PartitionColumns` | `fetchedColumns()` The columns that needs to be fetched internally for this filter.
    `boolean` | `fetches(ColumnDefinition column)` Whether the provided column is fetched by this filter.
    `boolean` | `fetchesAllColumns()`
    `ColumnFilter.Tester` | `newTester(ColumnDefinition column)` Creates a new `Tester` to efficiently test the inclusion of cells of complex column `column`.
    `PartitionColumns` | `queriedColumns()` The columns actually queried by the user.
    `static ColumnFilter` | `selection(CFMetaData metadata, PartitionColumns queried)` A filter that fetches all columns for the provided table, but returns only the queried ones.
    `static ColumnFilter` | `selection(PartitionColumns columns)` A filter that only fetches/queries the provided columns.
    `static ColumnFilter.Builder` | `selectionBuilder()` Returns a `ColumnFilter` builder that only fetches the columns/cells added to the builder.
    `java.lang.String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### serializer

          public static final ColumnFilter.Serializer serializer

  - ### Method Detail

    - #### all

          public static ColumnFilter all(CFMetaData metadata)

      A filter that includes all columns for the provided table.

    - #### selection

          public static ColumnFilter selection(PartitionColumns columns)

      A filter that only fetches/queries the provided columns.

      Note that this shouldn't be used for CQL queries in general as all columns should be queried to preserve CQL semantic (see class javadoc). This is ok for some internal queries however (and for #6588 if/when we implement it).

    - #### selection

          public static ColumnFilter selection(CFMetaData metadata,
                                               PartitionColumns queried)

      A filter that fetches all columns for the provided table, but returns only the queried ones.

    - #### fetchedColumns

          public PartitionColumns fetchedColumns()

      The columns that needs to be fetched internally for this filter.
      Returns:
        the columns to fetch for this filter.

    - #### queriedColumns

          public PartitionColumns queriedColumns()

      The columns actually queried by the user.

      Note that this is in general not all the columns that are fetched internally (see `fetchedColumns()`).

    - #### fetchesAllColumns

          public boolean fetchesAllColumns()

    - #### allFetchedColumnsAreQueried

          public boolean allFetchedColumnsAreQueried()

      Whether _fetched_ == _queried_ for this filter, and so if the `isQueried()` methods can return `false` for some column/cell.

    - #### fetches

          public boolean fetches(ColumnDefinition column)

      Whether the provided column is fetched by this filter.

    - #### fetchedColumnIsQueried

          public boolean fetchedColumnIsQueried(ColumnDefinition column)

      Whether the provided column, which is assumed to be _fetched_ by this filter (so the caller must guarantee that `fetches(column) == true`, is also _queried_ by the user. !WARNING! please be sure to understand the difference between _fetched_ and _queried_ columns that this class made before using this method. If unsure, you probably want to use the `fetches(org.apache.cassandra.config.ColumnDefinition)` method.

    - #### fetchedCellIsQueried

          public boolean fetchedCellIsQueried(ColumnDefinition column,
                                              CellPath path)

      Whether the provided complex cell (identified by its column and path), which is assumed to be _fetched_ by this filter, is also _queried_ by the user. !WARNING! please be sure to understand the difference between _fetched_ and _queried_ columns that this class made before using this method. If unsure, you probably want to use the `fetches(org.apache.cassandra.config.ColumnDefinition)` method.

    - #### newTester

          public ColumnFilter.Tester newTester(ColumnDefinition column)

      Creates a new `Tester` to efficiently test the inclusion of cells of complex column `column`.
      Returns:
        the created tester or `null` if all the cells from the provided column are queried.

    - #### allColumnsBuilder

          public static ColumnFilter.Builder allColumnsBuilder(CFMetaData metadata)

      Returns a `ColumnFilter`} builder that fetches all columns (and queries the columns added to the builder, or everything if no column is added).

    - #### selectionBuilder

          public static ColumnFilter.Builder selectionBuilder()

      Returns a `ColumnFilter` builder that only fetches the columns/cells added to the builder.

    - #### equals

          public boolean equals(java.lang.Object other)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

Copyright © 2018 The Apache Software Foundation