io.deephaven.engine.table.impl.locations.TableLocationKey Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of deephaven-engine-table Show documentation

Engine Table: Implementation and closely-coupled utilities

There is a newer version: 0.37.1

Show newest version

/**
 * Copyright (c) 2016-2022 Deephaven Data Labs and Patent Pending
 */
package io.deephaven.engine.table.impl.locations;

import io.deephaven.base.log.LogOutputAppendable;
import io.deephaven.util.type.NamedImplementation;
import org.jetbrains.annotations.NotNull;

import java.util.Set;

/**
 * 
 * Interface for opaque table location keys for use in {@link TableLocationProvider} implementations. Note that
 * implementations are generally only comparable to other implementations intended for use in the same provider and
 * discovery framework.
 *
 * 

 * This interface also provides a mechanism for communicating partition information from a discovery framework
 * to the table engine. A partition of a table represents some sub-range of the overall available data, but can always
 * be thought of as a table in its own right. By representing partition membership as an ordered set of key-value pairs
 * with mutually-comparable values, we make it possible to:
 * 

 * Totally order the set of partitions belonging to a table, and thus all rows of the table
 * Refer to partitions via columns of the data, allowing vast savings in filtering efficiency for filters that only
 * need evaluate one or more partitioning columns
 * 
 *
 * 
 * Generally, only {@link io.deephaven.engine.table.impl.PartitionAwareSourceTable PartitionAwareSourceTable} and
 * {@link io.deephaven.engine.table.impl.SourcePartitionedTable SourcePartitionedTable} are properly partition-aware.
 */
public interface TableLocationKey extends Comparable, NamedImplementation, LogOutputAppendable {

    /**
     * Lookup the value of one of the table partitions enclosing the location keyed by {@code this}.
     *
     * @param partitionKey The name of the partition
     * @param  The expected type of the partition value
     * @return The partition value
     * @throws UnknownPartitionKeyException If the partition cannot be found
     */
    > PARTITION_VALUE_TYPE getPartitionValue(
            @NotNull final String partitionKey);

    /**
     * Get the set of available partition keys.
     *
     * @return The set of available partition keys
     */
    Set getPartitionKeys();

    /**
     * Get an {@link ImmutableTableLocationKey} that is equal to this.
     *
     * @return An immutable version of this key
     */
    ImmutableTableLocationKey makeImmutable();
}