Class JsonRowBridge<T>

java.lang.Object
io.krabka.streams.columnar.JsonRowBridge<T>
Type Parameters:
T - the Jackson-compatible row type
All Implemented Interfaces:
RowBridge<T>
public final class JsonRowBridge<T> extends Object implements RowBridge<T>
Converts JSON-compatible Java records to flat Arrow columns.

Values are mapped through Jackson: each top-level property becomes one column. Text becomes Utf8, integral numbers Int(64), floating point FloatingPoint(DOUBLE), booleans Bool, and binary Binary; nested objects and arrays are stored as their JSON text. Scalar types such as String or Long map to a single column named value.

The Arrow schema can come from three places, in order of preference: an explicit Arrow Schema, a JSON Schema document through fromJsonSchema(Class, String), or inference from the first batch's non-null sample values. Inference locks in after the first non-empty batch, so later batches use the same schema; prefer an explicit schema in production so a batch of unusual first values cannot change column types.

Example

record Transaction(String user, long amount) {}

var bridge = new JsonRowBridge<>(Transaction.class);
try (var batch = bridge.rowsToBatch(List.of(new Transaction("ada", 7)), allocator)) {
    // columns: user (Utf8), amount (Int(64))
    List<Transaction> back = bridge.batchToRows(batch);
}

  • Constructor Summary

    Constructors
    Constructor
    Description
    JsonRowBridge(Class<T> type)
    Creates a bridge that infers its Arrow schema from the first non-empty batch.
    JsonRowBridge(Class<T> type, com.fasterxml.jackson.databind.ObjectMapper objectMapper)
    Creates a schema-inferring bridge with a caller-supplied Jackson mapper.
    JsonRowBridge(Class<T> type, com.fasterxml.jackson.databind.ObjectMapper objectMapper, org.apache.arrow.vector.types.pojo.Schema schema)
    Creates a bridge with an explicit Arrow schema and Jackson mapper.
    JsonRowBridge(Class<T> type, org.apache.arrow.vector.types.pojo.Schema schema)
    Creates a bridge with an explicit Arrow schema.

  • Method Summary

    Modifier and Type
    Method
    Description
    List<T>
    batchToRows(org.apache.arrow.vector.VectorSchemaRoot batch)
    Converts an Arrow payload batch back into one value per row.
    static <T> JsonRowBridge<T>
    fromJsonSchema(Class<T> type, String jsonSchema)
    Creates a bridge whose Arrow fields come from a JSON Schema instead of sample rows.
    static <T> JsonRowBridge<T>
    fromJsonSchema(Class<T> type, String jsonSchema, com.fasterxml.jackson.databind.ObjectMapper objectMapper)
    Creates a JSON Schema driven bridge with a caller-supplied Jackson mapper.
    org.apache.arrow.vector.VectorSchemaRoot
    rowsToBatch(List<T> rows, org.apache.arrow.memory.BufferAllocator allocator)
    Builds one Arrow batch with one row per value.

    Methods inherited from class Object

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

  • Constructor Details

    • JsonRowBridge

      public JsonRowBridge(Class<T> type)
      Creates a bridge that infers its Arrow schema from the first non-empty batch.
      Parameters:
      type - the row class values are bound to and from

    • JsonRowBridge

      public JsonRowBridge(Class<T> type, com.fasterxml.jackson.databind.ObjectMapper objectMapper)
      Creates a schema-inferring bridge with a caller-supplied Jackson mapper.
      Parameters:
      type - the row class values are bound to and from
      objectMapper - the mapper used for binding rows

    • JsonRowBridge

      public JsonRowBridge(Class<T> type, org.apache.arrow.vector.types.pojo.Schema schema)
      Creates a bridge with an explicit Arrow schema.
      Parameters:
      type - the row class values are bound to and from
      schema - the Arrow schema every batch uses

    • JsonRowBridge

      public JsonRowBridge(Class<T> type, com.fasterxml.jackson.databind.ObjectMapper objectMapper, org.apache.arrow.vector.types.pojo.Schema schema)
      Creates a bridge with an explicit Arrow schema and Jackson mapper.
      Parameters:
      type - the row class values are bound to and from
      objectMapper - the mapper used for binding rows
      schema - the Arrow schema every batch uses

  • Method Details

    • fromJsonSchema

      public static <T> JsonRowBridge<T> fromJsonSchema(Class<T> type, String jsonSchema)
      Creates a bridge whose Arrow fields come from a JSON Schema instead of sample rows.

      Property types map as in schema inference; a property is nullable unless it is listed in required, and $ref pointers within the document are resolved.

      Type Parameters:
      T - the Jackson-compatible row type
      Parameters:
      type - the row class values are bound to and from
      jsonSchema - the JSON Schema document describing the rows
      Returns:
      a bridge with fields derived from the schema
      Throws:
      IllegalArgumentException - if the document is not a JSON object, lacks properties, or contains an unresolvable reference

    • fromJsonSchema

      public static <T> JsonRowBridge<T> fromJsonSchema(Class<T> type, String jsonSchema, com.fasterxml.jackson.databind.ObjectMapper objectMapper)
      Creates a JSON Schema driven bridge with a caller-supplied Jackson mapper.
      Type Parameters:
      T - the Jackson-compatible row type
      Parameters:
      type - the row class values are bound to and from
      jsonSchema - the JSON Schema document describing the rows
      objectMapper - the mapper used for binding rows
      Returns:
      a bridge with fields derived from the schema
      Throws:
      IllegalArgumentException - if the document is not a JSON object, lacks properties, or contains an unresolvable reference

    • rowsToBatch

      public org.apache.arrow.vector.VectorSchemaRoot rowsToBatch(List<T> rows, org.apache.arrow.memory.BufferAllocator allocator)
      Builds one Arrow batch with one row per value.

      If the bridge has no schema yet, one is inferred from this batch's non-null values and kept for all later batches, provided the batch is not empty.

      Specified by:
      rowsToBatch in interface RowBridge<T>
      Parameters:
      rows - the values to convert, in record order
      allocator - the allocator that owns the batch's buffers
      Returns:
      the payload batch; the caller must close it
      Throws:
      ColumnarException - if a required field is null or a value cannot be written

    • batchToRows

      public List<T> batchToRows(org.apache.arrow.vector.VectorSchemaRoot batch)
      Converts an Arrow payload batch back into one value per row.
      Specified by:
      batchToRows in interface RowBridge<T>
      Parameters:
      batch - the payload batch to convert; the bridge reads it and leaves it open
      Returns:
      the values in row order
      Throws:
      ColumnarException - if a row cannot be bound to the row class