org.apache.flink.types

Class Row

java.lang.Object

org.apache.flink.types.Row

All Implemented Interfaces:

Serializable

@PublicEvolving
public final class Row
extends Object
implements Serializable

A row is a fixed-length, null-aware composite type for storing multiple values in a deterministic field order. Every field can be null regardless of the field's type. The type of row fields cannot be automatically inferred; therefore, it is required to provide type information whenever a row is produced.

The main purpose of rows is to bridge between Flink's Table and SQL ecosystem and other APIs. Therefore, a row does not only consist of a schema part (containing the fields) but also attaches a RowKind for encoding a change in a changelog. Thus, a row can be considered as an entry in a changelog. For example, in regular batch scenarios, a changelog would consist of a bounded stream of RowKind.INSERT rows. The row kind is kept separate from the fields and can be accessed by using getKind() and setKind(RowKind).

Fields of a row can be accessed either position-based or name-based. An implementer can decide in which field mode a row should operate during creation. Rows that were produced by the framework support a hybrid of both field modes (i.e. named positions):

Position-based field mode

withPositions(int) creates a fixed-length row. The fields can be accessed by position (zero-based) using getField(int) and setField(int, Object). Every field is initialized with null by default.

Name-based field mode

withNames() creates a variable-length row. The fields can be accessed by name using getField(String) and setField(String, Object). Every field is initialized during the first call to setField(String, Object) for the given name. However, the framework will initialize missing fields with null and reorder all fields once more type information is available during serialization or input conversion. Thus, even name-based rows eventually become fixed-length composite types with a deterministic field order. Name-based rows perform worse than position-based rows but simplify row creation and code readability.

Hybrid / named-position field mode

Rows that were produced by the framework (after deserialization or output conversion) are fixed-length rows with a deterministic field order that can map static field names to field positions. Thus, fields can be accessed both via getField(int) and getField(String). Both setField(int, Object) and setField(String, Object) are supported for existing fields. However, adding new field names via setField(String, Object) is not allowed. A hybrid row's equals(Object) supports comparing to all kinds of rows. A hybrid row's hashCode() is only valid for position-based rows.

A row instance is in principle Serializable. However, it may contain non-serializable fields in which case serialization will fail if the row is not serialized with Flink's serialization stack.

The equals(Object) and hashCode() methods of this class support all external conversion classes of the table ecosystem.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
Row(int arity) Creates a fixed-length row in position-based field mode.
Row(RowKind kind, int arity) Creates a fixed-length row in position-based field mode.

Method Summary

Modifier and Type	Method and Description
void	clear() Clears all fields of this row.
static Row	copy(Row row) Creates a new row which is copied from another row (including its RowKind).
boolean	equals(Object o)
int	getArity() Returns the number of fields in the row.
Object	getField(int pos) Returns the field's content at the specified field position.
Object	getField(String name) Returns the field's content using the specified field name.
<T> T	getFieldAs(int pos) Returns the field's content at the specified field position.
<T> T	getFieldAs(String name) Returns the field's content using the specified field name.
Set<String>	getFieldNames(boolean includeNamedPositions) Returns the set of field names if this row operates in name-based field mode, otherwise null.
RowKind	getKind() Returns the kind of change that this row describes in a changelog.
int	hashCode()
static Row	join(Row first, Row... remainings) Creates a new row with fields that are copied from the other rows and appended to the resulting row in the given order.
static Row	of(Object... values) Creates a fixed-length row in position-based field mode and assigns the given values to the row's fields.
static Row	ofKind(RowKind kind, Object... values) Creates a fixed-length row in position-based field mode with given kind and assigns the given values to the row's fields.
static Row	project(Row row, int[] fieldPositions) Creates a new row with projected fields and identical RowKind from another row.
static Row	project(Row row, String[] fieldNames) Creates a new row with projected fields and identical RowKind from another row.
void	setField(int pos, Object value) Sets the field's content at the specified position.
void	setField(String name, Object value) Sets the field's content using the specified field name.
void	setKind(RowKind kind) Sets the kind of change that this row describes in a changelog.
String	toString()
static Row	withNames() Creates a variable-length row in name-based field mode.
static Row	withNames(RowKind kind) Creates a variable-length row in name-based field mode.
static Row	withPositions(int arity) Creates a fixed-length row in position-based field mode.
static Row	withPositions(RowKind kind, int arity) Creates a fixed-length row in position-based field mode.

Methods inherited from class java.lang.Object

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

Constructor Detail

Row

public Row(RowKind kind,
           int arity)

Creates a fixed-length row in position-based field mode.

The semantics are equivalent to withPositions(RowKind, int). This constructor exists for backwards compatibility.

Parameters:

kind - kind of change a row describes in a changelog

arity - the number of fields in the row

Row

public Row(int arity)

Creates a fixed-length row in position-based field mode.

The semantics are equivalent to withPositions(int). This constructor exists for backwards compatibility.

Parameters:

arity - the number of fields in the row

Method Detail

withPositions

public static Row withPositions(RowKind kind,
                                int arity)

Creates a fixed-length row in position-based field mode.

Fields can be accessed by position via setField(int, Object) and getField(int).

See the class documentation of Row for more information.

Parameters:

kind - kind of change a row describes in a changelog

arity - the number of fields in the row

Returns:

a new row instance

withPositions

public static Row withPositions(int arity)

Creates a fixed-length row in position-based field mode.

Fields can be accessed by position via setField(int, Object) and getField(int).

By default, a row describes an RowKind.INSERT change.

See the class documentation of Row for more information.

Parameters:

arity - the number of fields in the row

Returns:

a new row instance

withNames

public static Row withNames(RowKind kind)

Creates a variable-length row in name-based field mode.

Fields can be accessed by name via setField(String, Object) and getField(String).

See the class documentation of Row for more information.

Parameters:

kind - kind of change a row describes in a changelog

Returns:

a new row instance

withNames

public static Row withNames()

Creates a variable-length row in name-based field mode.

Fields can be accessed by name via setField(String, Object) and getField(String).

By default, a row describes an RowKind.INSERT change.

See the class documentation of Row for more information.

Returns:

a new row instance

getKind

public RowKind getKind()

Returns the kind of change that this row describes in a changelog.

By default, a row describes an RowKind.INSERT change.

See Also:

RowKind

setKind

public void setKind(RowKind kind)

Sets the kind of change that this row describes in a changelog.

By default, a row describes an RowKind.INSERT change.

See Also:

RowKind

getArity

public int getArity()

Returns the number of fields in the row.

Note: The row kind is kept separate from the fields and is not included in this number.

Returns:

the number of fields in the row

getField

@Nullable
public Object getField(int pos)

Returns the field's content at the specified field position.

Note: The row must operate in position-based field mode.

Parameters:

pos - the position of the field, 0-based

Returns:

the field's content at the specified position

getFieldAs

public <T> T getFieldAs(int pos)

Returns the field's content at the specified field position.

Note: The row must operate in position-based field mode.

This method avoids a lot of manual casting in the user implementation.

Parameters:

pos - the position of the field, 0-based

Returns:

the field's content at the specified position

getField

@Nullable
public Object getField(String name)

Returns the field's content using the specified field name.

Note: The row must operate in name-based field mode.

Parameters:

name - the name of the field or null if not set previously

Returns:

the field's content

getFieldAs

public <T> T getFieldAs(String name)

Returns the field's content using the specified field name.

Note: The row must operate in name-based field mode.

This method avoids a lot of manual casting in the user implementation.

Parameters:

name - the name of the field, set previously

Returns:

the field's content

setField

public void setField(int pos,
                     @Nullable
                     Object value)

Sets the field's content at the specified position.

Note: The row must operate in position-based field mode.

Parameters:

pos - the position of the field, 0-based

value - the value to be assigned to the field at the specified position

setField

public void setField(String name,
                     @Nullable
                     Object value)

Sets the field's content using the specified field name.

Note: The row must operate in name-based field mode.

Parameters:

name - the name of the field

value - the value to be assigned to the field

getFieldNames

@Nullable
public Set<String> getFieldNames(boolean includeNamedPositions)

Returns the set of field names if this row operates in name-based field mode, otherwise null.

This method is a helper method for serializers and converters but can also be useful for other row transformations.

Parameters:

includeNamedPositions - whether or not to include named positions when this row operates in a hybrid field mode

clear

public void clear()

Clears all fields of this row.

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

of

public static Row of(Object... values)

Creates a fixed-length row in position-based field mode and assigns the given values to the row's fields.

This method should be more convenient than withPositions(int) in many cases.

For example:

     Row.of("hello", true, 1L);
 

instead of

     Row row = Row.withPositions(3);
     row.setField(0, "hello");
     row.setField(1, true);
     row.setField(2, 1L);
 

By default, a row describes an RowKind.INSERT change.

ofKind

public static Row ofKind(RowKind kind,
                         Object... values)

Creates a fixed-length row in position-based field mode with given kind and assigns the given values to the row's fields.

This method should be more convenient than withPositions(RowKind, int) in many cases.

For example:

     Row.ofKind(RowKind.INSERT, "hello", true, 1L);
 

instead of

     Row row = Row.withPositions(RowKind.INSERT, 3);
     row.setField(0, "hello");
     row.setField(1, true);
     row.setField(2, 1L);
 

copy

public static Row copy(Row row)

Creates a new row which is copied from another row (including its RowKind).

This method does not perform a deep copy. Use RowSerializer.copy(Row) if required.

project

public static Row project(Row row,
                          int[] fieldPositions)

Creates a new row with projected fields and identical RowKind from another row.

This method does not perform a deep copy.

Note: The row must operate in position-based field mode. Field names are not projected.

Parameters:

fieldPositions - field indices to be projected

project

public static Row project(Row row,
                          String[] fieldNames)

Creates a new row with projected fields and identical RowKind from another row.

This method does not perform a deep copy.

Note: The row must operate in name-based field mode.

Parameters:

fieldNames - field names to be projected

join

public static Row join(Row first,
                       Row... remainings)

Creates a new row with fields that are copied from the other rows and appended to the resulting row in the given order. The RowKind of the first row determines the RowKind of the result.

This method does not perform a deep copy.

Note: All rows must operate in position-based field mode.