Package org.apache.flink.types

Class 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 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

      All Methods Static Methods Instance Methods Concrete Methods 
      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.

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

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