processing/src/main/java/org/apache/druid/segment/VirtualColumn.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

package org.apache.druid.segment;

import com.fasterxml.jackson.annotation.JsonSubTypes;
import com.fasterxml.jackson.annotation.JsonTypeInfo;
import org.apache.druid.java.util.common.Cacheable;
import org.apache.druid.query.dimension.DimensionSpec;
import org.apache.druid.segment.column.BitmapIndex;
import org.apache.druid.segment.column.ColumnCapabilities;
import org.apache.druid.segment.data.ReadableOffset;
import org.apache.druid.segment.vector.MultiValueDimensionVectorSelector;
import org.apache.druid.segment.vector.ReadableVectorOffset;
import org.apache.druid.segment.vector.SingleValueDimensionVectorSelector;
import org.apache.druid.segment.vector.VectorColumnSelectorFactory;
import org.apache.druid.segment.vector.VectorObjectSelector;
import org.apache.druid.segment.vector.VectorValueSelector;
import org.apache.druid.segment.virtual.ExpressionVirtualColumn;

import javax.annotation.Nullable;
import java.util.List;

/**
 * Virtual columns are "views" created over a {@link ColumnSelectorFactory} or {@link ColumnSelector}. They can
 * potentially draw from multiple underlying columns, although they always present themselves as if they were a single
 * column.
 *
 * A virtual column object will be shared amongst threads and must be thread safe. The selectors returned
 * from the various makeXXXSelector methods need not be thread safe.
 */
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type")
@JsonSubTypes(value = {
    @JsonSubTypes.Type(name = "expression", value = ExpressionVirtualColumn.class)
})
public interface VirtualColumn extends Cacheable
{
  /**
   * Output name of this column.
   *
   * @return name
   */
  String getOutputName();

  /**
   * Build a selector corresponding to this virtual column. Also provides the name that the
   * virtual column was referenced with (through {@link DimensionSpec#getDimension()}, which
   * is useful if this column uses dot notation. The virtual column is expected to apply any
   * necessary decoration from the dimensionSpec.
   */
  DimensionSelector makeDimensionSelector(DimensionSpec dimensionSpec, ColumnSelectorFactory factory);

  /**
   * Returns similar {@link DimensionSelector} object as returned by
   * {@link #makeDimensionSelector(DimensionSpec, ColumnSelectorFactory)} except this method has full access to the
   * underlying column and can potentially provide a more efficient implementation.
   *
   * Users of this interface must ensure to first call this method whenever possible. Typically this can not be called
   * in query paths on top of IncrementalIndex which doesn't have columns as in persisted segments.
   */
  @SuppressWarnings("unused")
  @Nullable
  default DimensionSelector makeDimensionSelector(
      DimensionSpec dimensionSpec,
      ColumnSelector columnSelector,
      ReadableOffset offset
  )
  {
    return null;
  }

  /**
   * Build a {@link ColumnValueSelector} corresponding to this virtual column. Also provides the name that the
   * virtual column was referenced with, which is useful if this column uses dot notation.
   */
  ColumnValueSelector<?> makeColumnValueSelector(String columnName, ColumnSelectorFactory factory);

  /**
   * Returns similar {@link ColumnValueSelector} object as returned by
   * {@link #makeColumnValueSelector(String, ColumnSelectorFactory)} except this method has full access to the
   * underlying column and can potentially provide a more efficient implementation.
   *
   * Users of this interface must ensure to first call this method whenever possible. Typically this can not be called
   * in query paths on top of IncrementalIndex which doesn't have columns as in persisted segments.
   */
  @SuppressWarnings("unused")
  @Nullable
  default ColumnValueSelector<?> makeColumnValueSelector(
      String columnName,
      ColumnSelector columnSelector,
      ReadableOffset offset
  )
  {
    return null;
  }

  default boolean canVectorize(ColumnInspector inspector)
  {
    return false;
  }

  /**
   * Build a {@link SingleValueDimensionVectorSelector} corresponding to this virtual column. Also provides the name
   * that the virtual column was referenced with (through {@link DimensionSpec#getDimension()}, which is useful if this
   * column uses dot notation. The virtual column is expected to apply any necessary decoration from the
   * {@link DimensionSpec}.
   */
  default SingleValueDimensionVectorSelector makeSingleValueVectorDimensionSelector(
      DimensionSpec dimensionSpec,
      VectorColumnSelectorFactory factory
  )
  {
    throw new UnsupportedOperationException("not supported");
  }

  /**
   * Returns similar {@link SingleValueDimensionVectorSelector} object as returned by
   * {@link #makeSingleValueVectorDimensionSelector(DimensionSpec, ColumnSelector, ReadableVectorOffset)} except this
   * method has full access to the underlying column and can potentially provide a more efficient implementation.
   *
   * Users of this interface must ensure to first call this method whenever possible.
   */
  @SuppressWarnings("unused")
  @Nullable
  default SingleValueDimensionVectorSelector makeSingleValueVectorDimensionSelector(
      DimensionSpec dimensionSpec,
      ColumnSelector columnSelector,
      ReadableVectorOffset offset
  )
  {
    return null;
  }

  /**
   * Build a {@link MultiValueDimensionVectorSelector} corresponding to this virtual column. Also provides
   * the name that the virtual column was referenced with (through {@link DimensionSpec#getDimension()}, which is useful
   * if this column uses dot notation. The virtual column is expected to apply any necessary decoration from the
   * {@link DimensionSpec}.
   */
  default MultiValueDimensionVectorSelector makeMultiValueVectorDimensionSelector(
      DimensionSpec dimensionSpec,
      VectorColumnSelectorFactory factory
  )
  {
    throw new UnsupportedOperationException("not supported");
  }

  /**
   * Returns similar {@link SingleValueDimensionVectorSelector} object as returned by
   * {@link #makeSingleValueVectorDimensionSelector(DimensionSpec, ColumnSelector, ReadableVectorOffset)} except this
   * method has full access to the underlying column and can potentially provide a more efficient implementation.
   *
   * Users of this interface must ensure to first call this method whenever possible.
   */
  @SuppressWarnings("unused")
  @Nullable
  default MultiValueDimensionVectorSelector makeMultiValueVectorDimensionSelector(
      DimensionSpec dimensionSpec,
      ColumnSelector columnSelector,
      ReadableVectorOffset offset
  )
  {
    return null;
  }


  /**
   * Build a {@link VectorValueSelector} corresponding to this virtual column. Also provides the name that the
   * virtual column was referenced with, which is useful if this column uses dot notation.
   */
  default VectorValueSelector makeVectorValueSelector(String columnName, VectorColumnSelectorFactory factory)
  {
    throw new UnsupportedOperationException("not supported");
  }

  /**
   * Returns similar {@link VectorValueSelector} object as returned by
   * {@link #makeVectorValueSelector(String, VectorColumnSelectorFactory)} except this method has full access to the
   * underlying column and can potentially provide a more efficient implementation.
   *
   * Users of this interface must ensure to first call this method whenever possible.
   */
  @SuppressWarnings("unused")
  @Nullable
  default VectorValueSelector makeVectorValueSelector(
      String columnName,
      ColumnSelector columnSelector,
      ReadableVectorOffset offset
  )
  {
    return null;
  }

  /**
   * Build a {@link VectorObjectSelector} corresponding to this virtual column. Also provides the name that the
   * virtual column was referenced with, which is useful if this column uses dot notation.
   */
  default VectorObjectSelector makeVectorObjectSelector(String columnName, VectorColumnSelectorFactory factory)
  {
    throw new UnsupportedOperationException("not supported");
  }

  /**
   * Returns similar {@link VectorObjectSelector} object as returned by
   * {@link #makeVectorObjectSelector(String, VectorColumnSelectorFactory)} except this method has full access to the
   * underlying column and can potentially provide a more efficient implementation.
   *
   * Users of this interface must ensure to first call this method whenever possible.
   */
  @SuppressWarnings("unused")
  @Nullable
  default VectorObjectSelector makeVectorObjectSelector(
      String columnName,
      ColumnSelector columnSelector,
      ReadableVectorOffset offset
  )
  {
    return null;
  }

  /**
   * This method is deprecated in favor of {@link #capabilities(ColumnInspector, String)}, which should be used whenever
   * possible and can support virtual column implementations that need to inspect other columns as inputs.
   *
   * This is a fallback implementation to return the capabilities of this virtual column, which includes a type that
   * corresponds to the best performing base selector supertype (e. g. {@link BaseLongColumnValueSelector}) of the
   * object, returned from {@link #makeColumnValueSelector(String, ColumnSelectorFactory)}. May vary based on columnName
   * if this column uses dot notation.
   *
   * @param columnName the name this virtual column was referenced with
   *
   * @return capabilities, must not be null
   */
  @Deprecated
  ColumnCapabilities capabilities(String columnName);

  /**
   * Return the {@link ColumnCapabilities} which best describe the optimal selector to read from this virtual column.
   *
   * The {@link ColumnInspector} (most likely corresponding to an underlying {@link ColumnSelectorFactory} of a query)
   * allows the virtual column to consider this information if necessary to compute its output type details.
   *
   * Examples of this include the {@link ExpressionVirtualColumn}, which takes input from other columns and uses the
   * {@link ColumnInspector} to infer the output type of expressions based on the types of the inputs.
   *
   * @param inspector column inspector to provide additional information of other available columns
   * @param columnName the name this virtual column was referenced with
   * @return capabilities, must not be null
   */
  default ColumnCapabilities capabilities(ColumnInspector inspector, String columnName)
  {
    return capabilities(columnName);
  }

  /**
   * Returns a list of columns that this virtual column will access. This may include the
   * names of other virtual columns. May be empty if a virtual column doesn't access any
   * underlying columns.
   *
   * Does not pass columnName because there is an assumption that the list of columns
   * needed by a dot-notation supporting virtual column will not vary based on the
   * columnName.
   *
   * @return column names
   */
  List<String> requiredColumns();

  /**
   * Indicates that this virtual column can be referenced with dot notation. For example,
   * a virtual column named "foo" could be referred to as "foo.bar" with the Cursor it is
   * registered with. In that case, init will be called with columnName "foo.bar" rather
   * than "foo".
   *
   * @return whether to use dot notation
   */
  boolean usesDotNotation();

  /**
   * Returns the BitmapIndex for efficient filtering on columns that support it. This method is only used if
   * {@link ColumnCapabilities} returned from {@link #capabilities(String)} has flag for BitmapIndex support.
   * @param columnName
   * @param selector
   * @return BitmapIndex
   */
  @SuppressWarnings("unused")
  @Nullable
  default BitmapIndex getBitmapIndex(String columnName, ColumnSelector selector)
  {
    throw new UnsupportedOperationException("not supported");
  }
}