com.apple.foundationdb.record.metadata

Class Key.Expressions

java.lang.Object

com.apple.foundationdb.record.metadata.Key.Expressions

Enclosing class:

Key

public static class Key.Expressions
extends Object

Holder class for the static methods for creating Key Expressions.

Field Summary

Fields

Modifier and Type	Field and Description
static String	MAP_KEY_FIELD The name of the key field in Protobuf map messages.
static String	MAP_VALUE_FIELD The name of the value field in Protobuf map messages.

Method Summary

Modifier and Type	Method and Description
static ThenKeyExpression	concat(KeyExpression first, KeyExpression second, KeyExpression... rest) Concatenate multiple expressions together.
static ThenKeyExpression	concat(List<KeyExpression> children) Concatenate multiple expressions together.
static ThenKeyExpression	concatenateFields(List<String> fields) Concatenate multiple fields together.
static ThenKeyExpression	concatenateFields(String first, String second, String... fields) Shortuct for `concat(field(first), field(second), field(rest[0]), ...)`
static EmptyKeyExpression	empty() The empty key expression.
static FieldKeyExpression	field(String name) Create an expression of a single scalar (i.e.
static FieldKeyExpression	field(String name, KeyExpression.FanType fanType) Creates an expression of a field.
static FieldKeyExpression	field(String name, KeyExpression.FanType fanType, Key.Evaluated.NullStandin nullStandin) Creates an expression of a field.
static FieldKeyExpression	fromDescriptor(Descriptors.FieldDescriptor fieldDescriptor) Convert a field descriptor into a expression.
static FunctionKeyExpression	function(String name) Create a function call with arguments that will result in a key expression.
static FunctionKeyExpression	function(String name, KeyExpression arguments) Create a function call with arguments that will result in a key expression.
static boolean	hasRecordTypePrefix(KeyExpression key) Determine whether the given key expression has a record type key prefix.
static KeyWithValueExpression	keyWithValue(KeyExpression child, int splitPoint) A keyWithValue expression is a top level expression that takes as input an expression that produces more than one column, and indicates that all columns before the specified splitPoint should be used in the key of an index and all of the values starting at the splitPoint are to be used as the value of the index.
static ListKeyExpression	list(KeyExpression... children) Combine multiple expressions into a list.
static ListKeyExpression	list(List<KeyExpression> children) Combine multiple expressions into a list.
static NestingKeyExpression	mapKeys(String name) Index key from a map.
static NestingKeyExpression	mapKeyValues(String name) Index key and value from a map.
static NestingKeyExpression	mapValueKeys(String name) Index value and key from a map.
static NestingKeyExpression	mapValues(String name) Index value from a map.
static RecordTypeKeyExpression	recordType() The record type key expression, which indicates that a unique record type identifier should be contained within the key.
static <T> LiteralKeyExpression<T>	value(T value) Create a static scalar value of type T.
static VersionKeyExpression	version() The version key expression, which indicates that a versionstamp should be contained within the key.

Methods inherited from class java.lang.Object

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

Field Detail

MAP_KEY_FIELD

@Nonnull
public static final String MAP_KEY_FIELD

The name of the key field in Protobuf map messages.

See Also:

Constant Field Values

MAP_VALUE_FIELD

@Nonnull
public static final String MAP_VALUE_FIELD

The name of the value field in Protobuf map messages.

See Also:

Constant Field Values

Method Detail

field

@Nonnull
public static FieldKeyExpression field(@Nonnull
                                                String name)

Create an expression of a single scalar (i.e. not repeated) field. This sets the Key.Evaluated.NullStandin to Key.Evaluated.NullStandin.NULL. See field(String, KeyExpression.FanType, com.apple.foundationdb.record.metadata.Key.Evaluated.NullStandin) for more details.

Parameters:

name - the name of the field to evaluate

Returns:

a new Field expression, which can further be nested if the associated field is of the Message type.

See Also:

field(String, KeyExpression.FanType, com.apple.foundationdb.record.metadata.Key.Evaluated.NullStandin)

field

@Nonnull
public static FieldKeyExpression field(@Nonnull
                                                String name,
                                                @Nonnull
                                                KeyExpression.FanType fanType)

Creates an expression of a field. This field can be repeated or not, depending on the fanType. If fanType is Concatenate or None, this expression will only create 1 index entry. If it is FanOut it will create 1 index entry per value of the field. This sets the Key.Evaluated.NullStandin to Key.Evaluated.NullStandin.NULL. See field(String, KeyExpression.FanType, com.apple.foundationdb.record.metadata.Key.Evaluated.NullStandin) for more details.

Parameters:

name - the name of the field to evaluate

fanType - the way that repeated fields should be handled

Returns:

a new Field expression which can further be nested if the associated field is of the Message type.

See Also:

field(String, KeyExpression.FanType, com.apple.foundationdb.record.metadata.Key.Evaluated.NullStandin)

field

@Nonnull
public static FieldKeyExpression field(@Nonnull
                                                String name,
                                                @Nonnull
                                                KeyExpression.FanType fanType,
                                                @Nonnull
                                                Key.Evaluated.NullStandin nullStandin)

Creates an expression of a field. This field can be repeated or not, depending on the fanType. If fanType is Concatenate or None, this expression will only create 1 index entry. If it is FanOut it will create 1 index entry per value of the field.

This also takes a Key.Evaluated.NullStandin value to describe the field's behavior when it encounters an unset field. If the value is NOT_NULL, it will use the field's default value instead of null. If the value is NULL, it will return the value null and disable any uniqueness checks (if the index is a unique index). If the value is NULL_UNIQUE, it will return null and not disable any uniqueness checks. (In other words, it will treat null just like any other value.) Note that for most use cases, the same value should be used for the nullStandIn every time the field is referenced by any key expression or different indexes may have different ideas as to, for example, whether a field can be null or not. For this reason, there are plans to move this expression from the field to meta-data on the RecordType. See Issue #677 for more details.

Parameters:

name - the name of the field to evaluate

fanType - the way that repeated fields should be handled

nullStandin - value to use in place of missing values, determining whether it will contribute to unique indexes

Returns:

a new Field expression which can further be nested if the associated field is of the Message type.

concat

@Nonnull
public static ThenKeyExpression concat(@Nonnull
                                                KeyExpression first,
                                                @Nonnull
                                                KeyExpression second,
                                                @Nonnull
                                                KeyExpression... rest)

Concatenate multiple expressions together. This multiplies the index entry count of its children. For example if the first expression generates two entries [a, b], and the second generates 3: [1, 2, 3], then the concatenation will generate 6 index entries: [[a,1], [a,2], [a,3], [b,1], [b,2], [b,3]]. No context is shared by this expression between it's children. This flattens children, so concat(concat(field), concat(field2)) == concat(field1, field2).

Parameters:

first - the first child expression to use in the index

second - the second child expression to use in the index

rest - this supports any number children (at least 2), this is the rest of them

Returns:

a new expression which evaluates each child and returns the cross product

concat

@Nonnull
public static ThenKeyExpression concat(@Nonnull
                                                List<KeyExpression> children)

Concatenate multiple expressions together. This multiplies the index entry count of its children. For example if the first expression generates two entries [a, b], and the second generates 3: [1, 2, 3], then the concatenation will generate 6 index entries: [[a,1], [a,2], [a,3], [b,1], [b,2], [b,3]]. No context is shared by this expression between it's children. This flattens children, so concat(concat(field), concat(field2)) == concat(field1, field2).

Parameters:

children - child expressions

Returns:

a new expression which evaluates each child and returns the cross product

concatenateFields

@Nonnull
public static ThenKeyExpression concatenateFields(@Nonnull
                                                           String first,
                                                           @Nonnull
                                                           String second,
                                                           @Nonnull
                                                           String... fields)

Shortuct for `concat(field(first), field(second), field(rest[0]), ...)`

Parameters:

first - the name of the first field to use in the index

second - the name of the second field to use in the index

fields - this supports any number fields (at least 2), this is the rest of them

Returns:

a new expression which evaluates each field returns them all in a single key

concatenateFields

@Nonnull
public static ThenKeyExpression concatenateFields(@Nonnull
                                                           List<String> fields)

Concatenate multiple fields together.

Parameters:

fields - names of the fields

Returns:

a new expression which evaluates each field and returns them all in a single key

list

@Nonnull
public static ListKeyExpression list(@Nonnull
                                              KeyExpression... children)

Combine multiple expressions into a list.

Parameters:

children - child expressions

Returns:

a new expression which evaluates each child and returns the cross product as a list

list

@Nonnull
public static ListKeyExpression list(@Nonnull
                                              List<KeyExpression> children)

Combine multiple expressions into a list.

Parameters:

children - child expressions

Returns:

a new expression which evaluates each child and returns the cross product as a list

mapKeyValues

@Nonnull
public static NestingKeyExpression mapKeyValues(@Nonnull
                                                         String name)

Index key and value from a map. A map can be an actual Protobuf 3 map field or, in Protobuf 2, a repeated message field with fields named key and value.

Parameters:

name - name of the map field

Returns:

a new expression which evaluates to the key and value pairs of the given map field.

mapKeys

@Nonnull
public static NestingKeyExpression mapKeys(@Nonnull
                                                    String name)

Index key from a map. A map can be an actual Protobuf 3 map field or, in Protobuf 2, a repeated message field with fields named key and value.

Parameters:

name - name of the map field

Returns:

a new expression which evaluates to the values of the given map field.

mapValues

@Nonnull
public static NestingKeyExpression mapValues(@Nonnull
                                                      String name)

Index value from a map. A map can be an actual Protobuf 3 map field or, in Protobuf 2, a repeated message field with fields named key and value.

Parameters:

name - name of the map field

Returns:

a new expression which evaluates to the values of the given map field.

mapValueKeys

@Nonnull
public static NestingKeyExpression mapValueKeys(@Nonnull
                                                         String name)

Index value and key from a map. Like mapKeyValues(java.lang.String), but with the key and value field order reversed. This allows queries such as equality on the value and inequality on the key or equality on the value ordered by the key. A map can be an actual Protobuf 3 map field or, in Protobuf 2, a repeated message field with fields named key and value.

Parameters:

name - name of the map field

Returns:

a new expression which evaluates to the value and key pairs of the given map field.

function

@Nonnull
public static FunctionKeyExpression function(@Nonnull
                                                      String name,
                                                      @Nonnull
                                                      KeyExpression arguments)

Create a function call with arguments that will result in a key expression.

Parameters:

name - the name of the function

arguments - the arguments to the function

Returns:

a new key expression that evaluates by calling the named function

function

@Nonnull
public static FunctionKeyExpression function(@Nonnull
                                                      String name)

Create a function call with arguments that will result in a key expression.

Parameters:

name - the name of the function

Returns:

a new key expression that evaluates by calling the named function

value

@Nonnull
public static <T> LiteralKeyExpression<T> value(@Nullable
                                                         T value)

Create a static scalar value of type T. The typical use case for this would be to pass arguments to a function call (see FunctionKeyExpression).

Type Parameters:

T - the type of the value

Parameters:

value - the T value

Returns:

a new key expression that evaluates to the given value

keyWithValue

@Nonnull
public static KeyWithValueExpression keyWithValue(@Nonnull
                                                           KeyExpression child,
                                                           int splitPoint)

A keyWithValue expression is a top level expression that takes as input an expression that produces more than one column, and indicates that all columns before the specified splitPoint should be used in the key of an index and all of the values starting at the splitPoint are to be used as the value of the index.

Parameters:

child - the key expression to split

splitPoint - the position in the key result to split keys before this position are part of the key and keys after this position are part of the value

Returns:

an expression splitting the key and value

empty

@Nonnull
public static EmptyKeyExpression empty()

The empty key expression.

Returns:

the empty key expression

See Also:

EmptyKeyExpression

version

@Nonnull
public static VersionKeyExpression version()

The version key expression, which indicates that a versionstamp should be contained within the key.

Returns:

the version key expression

See Also:

VersionKeyExpression

recordType

@Nonnull
public static RecordTypeKeyExpression recordType()

The record type key expression, which indicates that a unique record type identifier should be contained within the key.

Returns:

the record type key expression

See Also:

RecordTypeKeyExpression

fromDescriptor

@Nonnull
public static FieldKeyExpression fromDescriptor(@Nonnull
                                                         Descriptors.FieldDescriptor fieldDescriptor)

Convert a field descriptor into a expression. Assumes FanOut for repeated keys.

Parameters:

fieldDescriptor - a field in a record type.

Returns:

a new Field to get the value of the given field descriptor.

hasRecordTypePrefix

public static boolean hasRecordTypePrefix(@Nonnull
                                          KeyExpression key)

Determine whether the given key expression has a record type key prefix.

Parameters:

key - key expression to check

Returns:

true if the given key expression has a record type key prefix