io.cdap.cdap.api.dataset.lib

Class IndexedTable

java.lang.Object

io.cdap.cdap.api.dataset.lib.AbstractDataset

io.cdap.cdap.api.dataset.lib.IndexedTable

All Implemented Interfaces:

BatchReadable<byte[],Row>, BatchWritable<byte[],Put>, RecordScannable<StructuredRecord>, RecordWritable<StructuredRecord>, Dataset, MeteredDataset, Table, Closeable, AutoCloseable, org.apache.tephra.TransactionAware

Deprecated.

table based datasets will be removed in a future version

@Deprecated
public class IndexedTable
extends AbstractDataset
implements Table

Implements a table that creates and maintains indexes on values stored within a configured set of column names.

This dataset uses two tables:

• the actual data table, which stores the raw, unmodified rows which are written; and
• an index table, with rows keyed by the indexed column and value (plus data row key for uniqueness), which contains a reference to the row key in the data table matching the indexed value.

The indexed values need not be unique. When reading the data back by index value, a Scanner will be returned, allowing the client to iterate through all matching rows. Exact matches as well as range lookups on indexed values are supported.

Index entries are created by storing additional rows in a second table. These index rows are keyed by column name, column value, and original row key, each field separated by a single null byte delimiter. It is not recommended that the name of an index column contains the null byte (this can cause a degradation in performance of index reads).

The columns to index can be configured in the DatasetProperties used when the dataset instance in created. Multiple column names should be listed as a comma-separated string (with no spaces):

public class MyApp extends AbstractApplication {
   public void configure() {
     setName("MyApp");
     ...
     createDataset("indexedData", IndexedTable.class,
                   DatasetProperties.builder().add(
                       IndexedTableDefinition.INDEX_COLUMNS_CONF_KEY, "col1,col2").build());
     ...
   }
 }

Note that this means that the column names which should be indexed cannot contain the comma character, as it would break parsing of the configuration property.

See Also:

INDEX_COLUMNS_CONF_KEY

Field Summary

Fields

Modifier and Type	Field and Description
static String	DYNAMIC_INDEXING Deprecated. Configuration that specifies that the index columns will be specified at runtime, rather than at configure time.
static String	DYNAMIC_INDEXING_PREFIX Deprecated. Configuration that specifies the prefix to use to distinguish indexed rows of different tables when dynamic indexing is enabled.
static String	INDEX_COLUMNS_CONF_KEY Deprecated. Configuration key for defining column names to index in the DatasetSpecification properties.
static String	TYPE Deprecated. Type name

Fields inherited from interface io.cdap.cdap.api.dataset.table.Table

DEFAULT_COLUMN_FAMILY, PROPERTY_COLUMN_FAMILY, PROPERTY_CONFLICT_LEVEL, PROPERTY_READLESS_INCREMENT, PROPERTY_SCHEMA, PROPERTY_SCHEMA_ROW_FIELD, PROPERTY_TTL

Constructor Summary

Constructors

Constructor and Description
IndexedTable(String name, Table table, Table index, SortedSet<byte[]> columnsToIndex) Deprecated. Configuration time constructor.
IndexedTable(String name, Table table, Table index, SortedSet<byte[]> columnsToIndex, byte[] keyPrefix) Deprecated. Configuration time constructor.

Method Summary

Modifier and Type	Method and Description
boolean	compareAndSwap(byte[] row, byte[] column, byte[] expected, byte[] newValue) Deprecated. Perform a swap operation by primary key.
SplitReader<byte[],Row>	createSplitReader(Split split) Deprecated. Creates a reader for the split of a dataset.
RecordScanner<StructuredRecord>	createSplitRecordScanner(Split split) Deprecated. Creates a reader for the split of a dataset.
void	delete(byte[] row) Deprecated. Deletes all columns of the specified row.
void	delete(byte[] row, byte[] column) Deprecated. Deletes specified column of the specified row.
void	delete(byte[] row, byte[][] columns) Deprecated. Deletes specified columns of the specified row.
void	delete(Delete delete) Deprecated. Perform a delete on the data table.
Row	get(byte[] row) Deprecated. Reads values of all columns of the specified row.
byte[]	get(byte[] row, byte[] column) Deprecated. Reads the value of the specified column of the specified row.
Row	get(byte[] row, byte[][] columns) Deprecated. Reads the values of the specified columns of the specified row.
Row	get(byte[] row, byte[] startColumn, byte[] stopColumn, int limit) Deprecated. Reads the values of all columns in the specified row that are between the specified start (inclusive) and stop (exclusive) columns.
Row	get(Get get) Deprecated. Read a row by row key from the data table.
List<Row>	get(List<Get> gets) Deprecated. Reads values for the rows and columns defined by the Get parameters.
Type	getRecordType() Deprecated. The type of records that the dataset exposes as a schema.
List<Split>	getSplits() Deprecated. Returns all splits of the dataset.
List<Split>	getSplits(int numSplits, byte[] start, byte[] stop) Deprecated. Returns splits for a range of keys in the table.
void	increment(byte[] row, byte[][] columns, long[] amounts) Deprecated. Increments (atomically) the specified row and columns by the specified amounts, without returning the new values.
void	increment(byte[] row, byte[] column, long amount) Deprecated. Increments (atomically) the specified row and column by the specified amount, without returning the new value.
void	increment(Increment increment) Deprecated. Increments (atomically) the specified row and columns by the specified amounts, without returning the new values.
Row	incrementAndGet(byte[] row, byte[][] columns, long[] amounts) Deprecated. Increments (atomically) the specified row and columns by the specified amounts, and returns the new values.
long	incrementAndGet(byte[] row, byte[] column, long amount) Deprecated. Increments (atomically) the specified row and column by the specified amount, and returns the new value.
Row	incrementAndGet(Increment increment) Deprecated. Increments (atomically) the specified row and columns by the specified amounts, and returns the new values.
void	put(byte[] row, byte[][] columns, byte[][] values) Deprecated. Writes the specified values for the specified columns of the specified row.
void	put(byte[] row, byte[] column, byte[] value) Deprecated. Writes the specified value for the specified column of the specified row.
void	put(Put put) Deprecated. Writes a put to the data table.
Scanner	readByIndex(byte[] column, byte[] value) Deprecated. Reads table rows by the given secondary index key.
Scanner	scan(byte[] startRow, byte[] stopRow) Deprecated. Scans table.
Scanner	scan(Scan scan) Deprecated. Returns a Scanner as specified by a given Scan.
Scanner	scanByIndex(byte[] column, byte[] startValue, byte[] endValue) Deprecated. Reads table rows within the given secondary index key range.
void	write(byte[] bytes, Put put) Deprecated. Writes the {key, value} record into a dataset.
void	write(StructuredRecord structuredRecord) Deprecated. Writes the record into a dataset.

Methods inherited from class io.cdap.cdap.api.dataset.lib.AbstractDataset

close, commitTx, getName, getTransactionAwareName, getTxChanges, postTxCommit, rollbackTx, setMetricsCollector, startTx, toString, updateTx

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.io.Closeable

close

Field Detail

TYPE

public static final String TYPE

Deprecated.

Type name

See Also:

Constant Field Values

INDEX_COLUMNS_CONF_KEY

public static final String INDEX_COLUMNS_CONF_KEY

Deprecated.

Configuration key for defining column names to index in the DatasetSpecification properties. Multiple column names should be listed as a comma-separated string, e.g. "column1,column2,etc".

See Also:

Constant Field Values

DYNAMIC_INDEXING

public static final String DYNAMIC_INDEXING

Deprecated.

Configuration that specifies that the index columns will be specified at runtime, rather than at configure time. Using this property, a single index table can shared across multiple logical tables.

See Also:

Constant Field Values

DYNAMIC_INDEXING_PREFIX

public static final String DYNAMIC_INDEXING_PREFIX

Deprecated.

Configuration that specifies the prefix to use to distinguish indexed rows of different tables when dynamic indexing is enabled.

See Also:

Constant Field Values

Constructor Detail

IndexedTable

public IndexedTable(String name,
                    Table table,
                    Table index,
                    SortedSet<byte[]> columnsToIndex)

Deprecated.

Configuration time constructor.

Parameters:

name - the name of the table

table - table to use as the table

index - table to use as the index

columnsToIndex - the names of the data columns to index

IndexedTable

public IndexedTable(String name,
                    Table table,
                    Table index,
                    SortedSet<byte[]> columnsToIndex,
                    byte[] keyPrefix)

Deprecated.

Configuration time constructor.

Parameters:

name - the name of the table

table - table to use as the table

index - table to use as the index

columnsToIndex - the names of the data columns to index

keyPrefix - the dynamic indexing prefix. See DYNAMIC_INDEXING_PREFIX

Method Detail

get

public Row get(Get get)

Deprecated.

Read a row by row key from the data table.

Specified by:

get in interface Table

Parameters:

get - the read operation, as if it were on a non-indexed table

Returns:

the result of the read on the underlying primary table

get

public Row get(byte[] row)

Deprecated.

Description copied from interface: Table

Reads values of all columns of the specified row.

NOTE: Depending on the implementation of this interface and use-case, calling this method can be less efficient than calling the same method with columns as parameters because it can require making a round trip to the persistent store.

NOTE: objects that are passed in parameters can be re-used by underlying implementation and present in returned data structures from this method.

Specified by:

get in interface Table

Parameters:

row - row to read from

Returns:

instance of Row: never null; returns an empty Row if nothing read

get

public byte[] get(byte[] row,
                  byte[] column)

Deprecated.

Description copied from interface: Table

Reads the value of the specified column of the specified row.

Specified by:

get in interface Table

Parameters:

row - row to read from

column - column to read value for

Returns:

value of the column or null if the value is absent

get

public Row get(byte[] row,
               byte[][] columns)

Deprecated.

Description copied from interface: Table

Reads the values of the specified columns of the specified row.

NOTE: objects that are passed in parameters can be re-used by underlying implementation and present in returned data structures from this method.

Specified by:

get in interface Table

Parameters:

row - row to read from

columns - collection of columns to read; if empty, will return an empty Row.

Returns:

instance of Row: never null; returns an empty Row if nothing read

get

public Row get(byte[] row,
               byte[] startColumn,
               byte[] stopColumn,
               int limit)

Deprecated.

Description copied from interface: Table

Reads the values of all columns in the specified row that are between the specified start (inclusive) and stop (exclusive) columns.

NOTE: objects that are passed in parameters can be re-used by underlying implementation and present in returned data structures from this method.

Specified by:

get in interface Table

startColumn - beginning of range of columns, inclusive

stopColumn - end of range of columns, exclusive

limit - maximum number of columns to return

Returns:

instance of Row; never null; returns an empty Row if nothing read

get

public List<Row> get(List<Get> gets)

Deprecated.

Description copied from interface: Table

Reads values for the rows and columns defined by the Get parameters. When running in distributed mode, and retrieving multiple rows at the same time, this method should be preferred to multiple Table.get(Get) calls, as the operations will be batched into a single remote call per server.

Specified by:

get in interface Table

Parameters:

gets - defines the rows and columns to read

Returns:

a list of Row instances

readByIndex

public Scanner readByIndex(byte[] column,
                           byte[] value)

Deprecated.

Reads table rows by the given secondary index key. If no rows are indexed by the given key, then a Scanner with no results will be returned.

Returns:

a Scanner returning rows from the data table, whose stored value for the given column matches the given value.

Throws:

IllegalArgumentException - if the given column is not configured for indexing.

scanByIndex

public Scanner scanByIndex(byte[] column,
                           @Nullable
                           byte[] startValue,
                           @Nullable
                           byte[] endValue)

Deprecated.

Reads table rows within the given secondary index key range. If no rows are indexed, falling within the given range, then a Scanner with no results will be returned.

Parameters:

column - the column to use for the index lookup

startValue - the inclusive start of the range for which rows must fall within to be returned in the scan. null means start from first row of the table

endValue - the exclusive end of the range for which rows must fall within to be returned in the scan null means end with the last row of the table

Returns:

a Scanner returning rows from the data table, whose stored value for the given column is within the the given range.

Throws:

IllegalArgumentException - if the given column is not configured for indexing.

put

public void put(Put put)

Deprecated.

Writes a put to the data table. If any of the columns in the Put are configured to be indexed, the appropriate indexes will be updated with the indexed values referencing the data table row.

Specified by:

put in interface Table

Parameters:

put - The put operation to store

put

public void put(byte[] row,
                byte[] column,
                byte[] value)

Deprecated.

Description copied from interface: Table

Writes the specified value for the specified column of the specified row.

Specified by:

put in interface Table

Parameters:

row - row to write to

column - column to write to

value - to write

put

public void put(byte[] row,
                byte[][] columns,
                byte[][] values)

Deprecated.

Description copied from interface: Table

Writes the specified values for the specified columns of the specified row.

NOTE: Depending on the implementation, this can work faster than calling Table.put(byte[], byte[], byte[]) multiple times (especially in transactions that alter many columns of one row).

Specified by:

put in interface Table

Parameters:

row - row to write to

columns - columns to write to

values - array of values to write (same order as values)

delete

public void delete(Delete delete)

Deprecated.

Perform a delete on the data table. Any index entries referencing the deleted row will also be removed.

Specified by:

delete in interface Table

Parameters:

delete - The delete operation identifying the row and optional columns to remove

delete

public void delete(byte[] row)

Deprecated.

Description copied from interface: Table

Deletes all columns of the specified row.

NOTE: Depending on the implementation of this interface and use-case, calling this method can be less efficient than calling the same method with columns as parameters because it can require a round trip to the persistent store.

Specified by:

delete in interface Table

Parameters:

row - row to delete

delete

public void delete(byte[] row,
                   byte[] column)

Deprecated.

Description copied from interface: Table

Deletes specified column of the specified row.

Specified by:

delete in interface Table

Parameters:

row - row to delete from

column - column name to delete

delete

public void delete(byte[] row,
                   byte[][] columns)

Deprecated.

Description copied from interface: Table

Deletes specified columns of the specified row.

NOTE: Depending on the implementation, this can work faster than calling Table.delete(byte[], byte[]) multiple times (especially in transactions that delete many columns of the same rows).

Specified by:

delete in interface Table

Parameters:

row - row to delete from

columns - names of columns to delete; if empty, nothing will be deleted

compareAndSwap

public boolean compareAndSwap(byte[] row,
                              byte[] column,
                              byte[] expected,
                              byte[] newValue)

Deprecated.

Perform a swap operation by primary key. Parameters are as if they were on a non-indexed table. Note that if the swap is on the secondary key column, then the index must be updated; otherwise, this is a pass-through to the underlying table.

Specified by:

compareAndSwap in interface Table

Parameters:

row - row to modify

column - column to modify

expected - expected value before change

newValue - value to set

Returns:

true if compare and swap succeeded, false otherwise (stored value is different from expected)

incrementAndGet

public long incrementAndGet(byte[] row,
                            byte[] column,
                            long amount)

Deprecated.

Increments (atomically) the specified row and column by the specified amount, and returns the new value. Note that performing this operation on an indexed column will generally have a negative impact on performance, since up to three writes will need to be performed for every increment (one removing the index for the previous, pre-increment value, one adding the index for the incremented value, and one for the increment itself).

Specified by:

incrementAndGet in interface Table

Parameters:

row - row which value to increment

column - column to increment

amount - amount to increment by

Returns:

new value of the column

See Also:

Table.incrementAndGet(byte[], byte[], long)

incrementAndGet

public Row incrementAndGet(byte[] row,
                           byte[][] columns,
                           long[] amounts)

Deprecated.

Increments (atomically) the specified row and columns by the specified amounts, and returns the new values. Note that performing this operation on an indexed column will generally have a negative impact on performance, since up to three writes will need to be performed for every increment (one removing the index for the previous, pre-increment value, one adding the index for the incremented value, and one for the increment itself).

Specified by:

incrementAndGet in interface Table

Parameters:

row - row whose values to increment

columns - columns to increment

amounts - amounts to increment columns by (in the same order as the columns)

Returns:

Row with a subset of changed columns

See Also:

Table.incrementAndGet(byte[], byte[][], long[])

incrementAndGet

public Row incrementAndGet(Increment increment)

Deprecated.

Increments (atomically) the specified row and columns by the specified amounts, and returns the new values. Note that performing this operation on an indexed column will generally have a negative impact on performance, since up to three writes will need to be performed for every increment (one removing the index for the previous, pre-increment value, one adding the index for the incremented value, and one for the increment itself).

Specified by:

incrementAndGet in interface Table

Parameters:

increment - defines changes

Returns:

Row with a subset of changed columns

See Also:

Table.incrementAndGet(Increment)

increment

public void increment(byte[] row,
                      byte[] column,
                      long amount)

Deprecated.

Increments (atomically) the specified row and column by the specified amount, without returning the new value. Note that performing this operation on an indexed column throws IllegalArgumentException.

Specified by:

increment in interface Table

Parameters:

row - row which values to increment

column - column to increment

amount - amount to increment by

See Also:

Table.increment(byte[], byte[], long)

increment

public void increment(byte[] row,
                      byte[][] columns,
                      long[] amounts)

Deprecated.

Increments (atomically) the specified row and columns by the specified amounts, without returning the new values. Note that performing this operation on an indexed column throws IllegalArgumentException.

Specified by:

increment in interface Table

Parameters:

row - row which values to increment

columns - columns to increment

amounts - amounts to increment columns by (same order as columns)

See Also:

Table.increment(byte[], byte[][], long[])

increment

public void increment(Increment increment)

Deprecated.

Increments (atomically) the specified row and columns by the specified amounts, without returning the new values. Note that performing this operation on an indexed column throws IllegalArgumentException.

Specified by:

increment in interface Table

Parameters:

increment - the row and column increment amounts

See Also:

Table.increment(Increment)

scan

public Scanner scan(@Nullable
                    byte[] startRow,
                    @Nullable
                    byte[] stopRow)

Deprecated.

Description copied from interface: Table

Scans table.

Specified by:

scan in interface Table

Parameters:

startRow - start row inclusive; null means start from first row of the table

stopRow - stop row exclusive; null means scan all rows to the end of the table

Returns:

instance of Scanner

scan

public Scanner scan(Scan scan)

Deprecated.

Description copied from interface: Table

Returns a Scanner as specified by a given Scan.

Specified by:

scan in interface Table

Parameters:

scan - a Scan instance

Returns:

instance of Scanner

getSplits

public List<Split> getSplits(int numSplits,
                             byte[] start,
                             byte[] stop)

Deprecated.

Description copied from interface: Table

Returns splits for a range of keys in the table.

Specified by:

getSplits in interface Table

Parameters:

numSplits - Desired number of splits. If greater than zero, at most this many splits will be returned. If less than or equal to zero, any number of splits can be returned.

start - if non-null, the returned splits will only cover keys that are greater or equal

stop - if non-null, the returned splits will only cover keys that are less

Returns:

list of Split

getRecordType

public Type getRecordType()

Deprecated.

Description copied from interface: RecordScannable

The type of records that the dataset exposes as a schema. The schema will be derived from the type using reflection.

Specified by:

getRecordType in interface RecordScannable<StructuredRecord>

Specified by:

getRecordType in interface RecordWritable<StructuredRecord>

Returns:

the schema type.

write

public void write(StructuredRecord structuredRecord)
           throws IOException

Deprecated.

Description copied from interface: RecordWritable

Writes the record into a dataset.

Specified by:

write in interface RecordWritable<StructuredRecord>

Parameters:

structuredRecord - record to write into the dataset.

Throws:

IOException - when the RECORD could not be written to the dataset.

getSplits

public List<Split> getSplits()

Deprecated.

Description copied from interface: BatchReadable

Returns all splits of the dataset.

For feeding the whole dataset into a batch job.

Specified by:

getSplits in interface BatchReadable<byte[],Row>

Specified by:

getSplits in interface RecordScannable<StructuredRecord>

Returns:

A list of Splits.

createSplitRecordScanner

public RecordScanner<StructuredRecord> createSplitRecordScanner(Split split)

Deprecated.

Description copied from interface: RecordScannable

Creates a reader for the split of a dataset.

Specified by:

createSplitRecordScanner in interface RecordScannable<StructuredRecord>

Parameters:

split - The split to create a reader for.

Returns:

The instance of a RecordScanner.

createSplitReader

public SplitReader<byte[],Row> createSplitReader(Split split)

Deprecated.

Description copied from interface: BatchReadable

Creates a reader for the split of a dataset.

Specified by:

createSplitReader in interface BatchReadable<byte[],Row>

Parameters:

split - The split to create a reader for.

Returns:

The instance of a SplitReader.

write

public void write(byte[] bytes,
                  Put put)

Deprecated.

Description copied from interface: Table

Writes the {key, value} record into a dataset.

Specified by:

write in interface BatchWritable<byte[],Put>

Specified by:

write in interface Table

Parameters:

bytes - always ignored, and it is safe to write null as the key.

put - a Put for one row of the table.