com.apple.foundationdb.record.metadata

Class Index

java.lang.Object

com.apple.foundationdb.record.metadata.Index

@API(value=MAINTAINED)
public class Index
extends Object

Meta-data for a secondary index.

See Also:

RecordMetaDataBuilder.addIndex(com.apple.foundationdb.record.metadata.RecordTypeBuilder, com.apple.foundationdb.record.metadata.Index)

Field Summary

Fields

Modifier and Type	Field and Description
static KeyExpression	EMPTY_VALUE

Constructor Summary

Constructors

Constructor and Description
Index(Index orig) Copy constructor.
Index(RecordMetaDataProto.Index proto)
Index(String name, KeyExpression rootExpression)
Index(String name, KeyExpression rootExpression, KeyExpression valueExpression, String type, Map<String,String> options)
Index(String name, KeyExpression rootExpression, String type)
Index(String name, KeyExpression rootExpression, String type, Map<String,String> options) Construct new index meta-data.
Index(String name, String first)
Index(String name, String first, String second, String... rest)

Method Summary

Modifier and Type	Method and Description
static Map<String,String>	buildOptions(List<RecordMetaDataProto.Index.Option> optionList, boolean addUnique)
static Object	decodeSubspaceKey(ByteString bytes)
boolean	equals(Object o)
int	getAddedVersion() Get the version at which the index was first added.
boolean	getBooleanOption(String key, boolean defaultValue)
int	getColumnSize() Get the number of indexed value columns.
Tuple	getEntryPrimaryKey(Tuple entry) Get the primary key portion of an index entry.
int	getEntrySize(KeyExpression primaryKey) The number of columns stored for an index entry.
int	getLastModifiedVersion() Get the version at which the index was changed.
String	getName()
String	getOption(String key)
Map<String,String>	getOptions()
int[]	getPrimaryKeyComponentPositions() Get the positions of the primary key components within the index key.
KeyExpression	getRootExpression()
Object	getSubspaceKey() Get the key used to determine this index's subspace prefix.
Object	getSubspaceTupleKey() Get a Tuple-encodable version of the subspace key of this index.
String	getType()
int	getVersion() Deprecated. use getLastModifiedVersion().
boolean	hasExplicitSubspaceKey() Checks whether the subspace key was set using setSubspaceKey(Object).
int	hashCode()
static Map<String,String>	indexTypeToOptions(RecordMetaDataProto.Index.Type indexType)
static String	indexTypeToType(RecordMetaDataProto.Index.Type indexType)
boolean	isUnique() Whether this index should have the property that any two records with different primary keys should have different values for this index.
void	setAddedVersion(int addedVersion) Set the version at which the index was first added.
void	setLastModifiedVersion(int lastModifiedVersion) Set the version at which the index was changed.
void	setPrimaryKeyComponentPositions(int[] primaryKeyComponentPositions) Set the positions of primary key components within the index key.
void	setSubspaceKey(Object subspaceKey) Set the key used to determine this index's subspace prefix.
void	setVersion(int version) Deprecated. use setLastModifiedVersion(int).
RecordMetaDataProto.Index	toProto()
String	toString()
void	trimPrimaryKey(List<?> primaryKeys)
List<Descriptors.FieldDescriptor>	validate(Descriptors.Descriptor recordType)

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY_VALUE

@Nonnull
public static final KeyExpression EMPTY_VALUE

Constructor Detail

Index

public Index(@Nonnull
             String name,
             @Nonnull
             KeyExpression rootExpression,
             @Nonnull
             String type,
             @Nonnull
             Map<String,String> options)

Construct new index meta-data.

Parameters:

name - the name of the index, which is unique for the whole meta-data

rootExpression - the key expression for the index, such as what field(s) to index

type - the type of index

options - additional options, which may be type-specific

See Also:

IndexTypes

Index

public Index(@Nonnull
             String name,
             @Nonnull
             KeyExpression rootExpression,
             @Nonnull
             KeyExpression valueExpression,
             @Nonnull
             String type,
             @Nonnull
             Map<String,String> options)

Index

public Index(@Nonnull
             String name,
             @Nonnull
             KeyExpression rootExpression,
             @Nonnull
             String type)

Index

public Index(@Nonnull
             String name,
             @Nonnull
             KeyExpression rootExpression)

Index

public Index(@Nonnull
             String name,
             @Nonnull
             String first)

Index

public Index(@Nonnull
             String name,
             @Nonnull
             String first,
             @Nonnull
             String second,
             @Nonnull
             String... rest)

Index

public Index(@Nonnull
             Index orig)

Copy constructor. This will create an index that is identical to the current Index instance.

Parameters:

orig - original index to copy

Index

public Index(@Nonnull
             RecordMetaDataProto.Index proto)
      throws KeyExpression.DeserializationException

Throws:

KeyExpression.DeserializationException

Method Detail

decodeSubspaceKey

public static Object decodeSubspaceKey(@Nonnull
                                       ByteString bytes)

buildOptions

public static Map<String,String> buildOptions(List<RecordMetaDataProto.Index.Option> optionList,
                                              boolean addUnique)

indexTypeToType

public static String indexTypeToType(RecordMetaDataProto.Index.Type indexType)

indexTypeToOptions

public static Map<String,String> indexTypeToOptions(RecordMetaDataProto.Index.Type indexType)

getName

@Nonnull
public String getName()

getType

@Nonnull
public String getType()

getOptions

@Nonnull
public Map<String,String> getOptions()

getOption

@Nullable
public String getOption(@Nonnull
                                  String key)

getBooleanOption

public boolean getBooleanOption(@Nonnull
                                String key,
                                boolean defaultValue)

getRootExpression

@Nonnull
public KeyExpression getRootExpression()

isUnique

public boolean isUnique()

Whether this index should have the property that any two records with different primary keys should have different values for this index. The default value for this is false if the option is not set explicitly.

Returns:

the value of the "unique" option

getSubspaceKey

@Nonnull
public Object getSubspaceKey()

Get the key used to determine this index's subspace prefix. All of the index's data will live within a subspace constructed by adding this key to a record store's subspace for secondary indexes. Each index within a given meta-data definition must have a unique subspace key. By default, this is equal to the index's name, but alternative keys can be set by calling setSubspaceKey(Object).

Returns:

the key used to determine this index's subspace prefix

See Also:

FDBRecordStore.indexSubspace(Index)

getSubspaceTupleKey

@Nonnull
public Object getSubspaceTupleKey()

Get a Tuple-encodable version of the subspace key of this index. As the subspace key is not guaranteed to be of a Tuple-encodable type on its own, this method is preferred over getSubspaceKey() if one is constructing a key to read or write data from the database.

Returns:

a Tuple-encodable version of index subspace key

setSubspaceKey

public void setSubspaceKey(@Nonnull
                           Object subspaceKey)

Set the key used to determine this index's subspace prefix. This value must be unique for each index within a given meta-data definition and must be serializable using a FoundationDB Tuple. As this value will prefix all keys used by the index, it is generally advisable that this key have a compact serialized form. For example, integers are encoded by the Tuple layer using a variable length encoding scheme that makes them a natural choice for this key.

It is important that once an index has data that its subspace key not change. If one wishes to change the key, the guidance would be to create a new index with the same definition but at the new key. Then that index can be built using the OnlineIndexer. When that index has been fully built, the original index can be safely dropped.

Parameters:

subspaceKey - the key used to determine this index's subspace prefix

See Also:

getSubspaceKey()

hasExplicitSubspaceKey

public boolean hasExplicitSubspaceKey()

Checks whether the subspace key was set using setSubspaceKey(Object).

Returns:

true if the subspace key was set using #setSubspaceKey(Object)

getPrimaryKeyComponentPositions

@Nullable
public int[] getPrimaryKeyComponentPositions()

Get the positions of the primary key components within the index key. This is used if the index key and the primary key expressions share fields to avoid duplicating the shared fields when writing serializing the index entry. This might return null if there are no common fields used by both the index key and the primary key. Otherwise, it will return an array that is the same length as the column size of the primary key. Each position in the array should either contain the index in the index key where one can find the value of the primary key component in that position or a negative value to indicate that that column is not found in the index key.

For example, suppose one had an index defined on a record type with a primary key of Key.Expressions.concatenateFields("a", "b") and suppose the index was defined on Key.Expressions.concatenateFields("a", "c"). A naïve approach might serialize index key tuples of the form (a, c, a, b) by concatenating the index key (i.e., (a, c)) with the primary key (i.e., (a, b)). However, as the first component of the primary key tuple can be found within the index's tuple, indexes will instead serialize index key tuples of the form (a, c, b). This function will then return the array {0, -1} to indicate that the first component of the primary key can be found at position 0 in the index entry key but the second component is found after the index key data (which is the default location).

This method should generally not be called by users outside of the Record Layer. For the most part, it should be sufficient for index maintainers to call FDBRecordStoreBase.indexEntryPrimaryKey() to determine the primary key of a record from an index entry and FDBRecordStoreBase.indexEntryKey() to determine the index entry given a record's primary key.

At the moment, this optimization is not used with multi-type or universal indexes. See Issue #93 for more details.

Returns:

the positions of primary key components within the index key or null

setPrimaryKeyComponentPositions

public void setPrimaryKeyComponentPositions(int[] primaryKeyComponentPositions)

Set the positions of primary key components within the index key. This generally should not be called by users outside of the Record Layer as it can affect how data are serialized to disk in incompatible ways.

Parameters:

primaryKeyComponentPositions - the positions of primary key components within the index key

See Also:

getPrimaryKeyComponentPositions()

trimPrimaryKey

@API(value=INTERNAL)
public void trimPrimaryKey(List<?> primaryKeys)

getColumnSize

public int getColumnSize()

Get the number of indexed value columns.

Returns:

the number of columns

getEntrySize

public int getEntrySize(KeyExpression primaryKey)

The number of columns stored for an index entry. Does not count primary key columns that are part of the indexed value, which do not need to be duplicated.

Parameters:

primaryKey - the primary key for eliminating duplicates

Returns:

the size of an index entry

getEntryPrimaryKey

@Nonnull
public Tuple getEntryPrimaryKey(@Nonnull
                                         Tuple entry)

Get the primary key portion of an index entry.

Parameters:

entry - the index entry

Returns:

the primary key extracted from the entry

getVersion

@Deprecated
public int getVersion()

Deprecated. use getLastModifiedVersion().

Synonynm for getLastModifiedVersion().

Returns:

the last modified version

setVersion

@Deprecated
public void setVersion(int version)

Deprecated. use setLastModifiedVersion(int).

Synonynm for setLastModifiedVersion(int).

Parameters:

version - the last modified version

getAddedVersion

public int getAddedVersion()

Get the version at which the index was first added.

Returns:

the added version

setAddedVersion

public void setAddedVersion(int addedVersion)

Set the version at which the index was first added.

Parameters:

addedVersion - the added version

getLastModifiedVersion

public int getLastModifiedVersion()

Get the version at which the index was changed. Any record store older than this will need to have the index rebuilt.

Returns:

the last modified version

setLastModifiedVersion

public void setLastModifiedVersion(int lastModifiedVersion)

Set the version at which the index was changed.

Parameters:

lastModifiedVersion - the last modified version

validate

public List<Descriptors.FieldDescriptor> validate(@Nonnull
                                                  Descriptors.Descriptor recordType)

toProto

@Nonnull
public RecordMetaDataProto.Index toProto()
                                           throws KeyExpression.SerializationException

Throws:

KeyExpression.SerializationException

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object