Package 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:

  • Constructor Summary

    Constructors
    Constructor
    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
    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 Details

    • 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 Details

    • 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:

    • 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:

    • 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.