Implementation:Apache Paimon ViewSchema

Knowledge Sources	Apache_Paimon
Domains	View Management, Schema Serialization
Last Updated	2026-02-08 00:00 GMT

Overview

ViewSchema is a serializable schema representation for views, containing fields, queries, dialects, comments, and options for persistent storage.

Description

ViewSchema is a public class providing a JSON-serializable representation of a view's schema and metadata, designed for persistent storage in catalogs and metadata systems. It contains five key components: a list of DataField objects defining the result schema, the primary SQL query string, a map of dialect-specific query variants, an optional comment for documentation, and a map of configuration options. The class uses Jackson annotations for JSON serialization, making it suitable for file-based storage, REST APIs, and distributed catalog systems.

All fields are private and final, ensuring immutability and thread safety. The class uses @JsonProperty annotations to define explicit JSON field names (fields, query, dialects, comment, options) and @JsonGetter annotations on accessor methods to control serialization. The comment field is marked with @JsonInclude(JsonInclude.Include.NON_NULL) to omit it from JSON when null, reducing storage overhead for views without documentation.

ViewSchema implements standard equals() and hashCode() methods based on all five fields, supporting proper usage in collections and comparison operations. The @JsonCreator constructor enables deserialization from JSON, with @JsonProperty annotations mapping JSON fields to constructor parameters. The @JsonIgnoreProperties(ignoreUnknown = true) annotation ensures forward compatibility by ignoring unknown fields during deserialization, allowing older code to read schemas created by newer versions.

Usage

Use ViewSchema for persisting view definitions to files or databases, transmitting view metadata over REST APIs, versioning view definitions, or implementing catalog systems that store view schemas alongside table schemas.

Code Reference

Source Location

Repository: Apache_Paimon
File: paimon-api/src/main/java/org/apache/paimon/view/ViewSchema.java

Signature

@JsonIgnoreProperties(ignoreUnknown = true)
public class ViewSchema {

    private static final String FIELD_FIELDS = "fields";
    private static final String FIELD_QUERY = "query";
    private static final String FIELD_DIALECTS = "dialects";
    private static final String FIELD_COMMENT = "comment";
    private static final String FIELD_OPTIONS = "options";

    public ViewSchema(List<DataField> fields,
                      String query,
                      Map<String, String> dialects,
                      @Nullable String comment,
                      Map<String, String> options)

    public List<DataField> fields()

    public String query()

    public Map<String, String> dialects()

    @Nullable
    public String comment()

    public Map<String, String> options()

    @Override
    public boolean equals(Object o)

    @Override
    public int hashCode()
}

Import

import org.apache.paimon.view.ViewSchema;

I/O Contract

Inputs

Name	Type	Required	Description
fields	List<DataField>	Yes	Result schema fields
query	String	Yes	Primary SQL query
dialects	Map<String, String>	Yes	Dialect-specific queries (can be empty)
comment	String	No	Optional view description
options	Map<String, String>	Yes	Configuration options (can be empty)

Outputs

Name	Type	Description
ViewSchema	ViewSchema	Immutable schema object
JSON	String	Serialized JSON representation
Fields/query/etc	Various	Individual schema components

Usage Examples

// Create a view schema
List<DataField> fields = Arrays.asList(
    DataTypes.FIELD(0, "customer_id", DataTypes.BIGINT()),
    DataTypes.FIELD(1, "order_count", DataTypes.BIGINT()),
    DataTypes.FIELD(2, "total_amount", DataTypes.DECIMAL(10, 2))
);

String query = "SELECT customer_id, COUNT(*) as order_count, " +
               "SUM(amount) as total_amount FROM orders GROUP BY customer_id";

Map<String, String> dialects = new HashMap<>();
dialects.put("spark", "SELECT customer_id, COUNT(*) as order_count, " +
                      "SUM(amount) as total_amount FROM orders GROUP BY customer_id");

String comment = "Customer order summary with total counts and amounts";

Map<String, String> options = new HashMap<>();
options.put("materialization.enabled", "true");
options.put("refresh.interval", "1h");

ViewSchema schema = new ViewSchema(fields, query, dialects, comment, options);

// Access schema components
List<DataField> schemaFields = schema.fields();
String sqlQuery = schema.query();
Map<String, String> dialectMap = schema.dialects();
String desc = schema.comment();
Map<String, String> opts = schema.options();

// JSON serialization
ObjectMapper mapper = new ObjectMapper();
String json = mapper.writeValueAsString(schema);
// Produces JSON with all fields

// JSON deserialization
ViewSchema restored = mapper.readValue(json, ViewSchema.class);

// Schema without comment
ViewSchema noComment = new ViewSchema(
    fields,
    query,
    dialects,
    null,  // no comment
    options
);
String jsonNoComment = mapper.writeValueAsString(noComment);
// "comment" field omitted from JSON

// Schema comparison
boolean same = schema.equals(restored); // true if identical

// Create minimal schema
ViewSchema minimal = new ViewSchema(
    fields,
    query,
    Collections.emptyMap(),  // no dialects
    null,                     // no comment
    Collections.emptyMap()    // no options
);

// Example: Persisting view schema to file
public void saveViewSchema(ViewSchema schema, Path path) throws IOException {
    ObjectMapper mapper = new ObjectMapper();
    mapper.writerWithDefaultPrettyPrinter()
          .writeValue(path.toFile(), schema);
}

// Example: Loading view schema from file
public ViewSchema loadViewSchema(Path path) throws IOException {
    ObjectMapper mapper = new ObjectMapper();
    return mapper.readValue(path.toFile(), ViewSchema.class);
}

// Example: Converting View to ViewSchema
public ViewSchema toViewSchema(View view) {
    return new ViewSchema(
        view.rowType().getFields(),
        view.query(),
        view.dialects(),
        view.comment().orElse(null),
        view.options()
    );
}

// Example: Catalog integration
public class CatalogImpl {
    public void createView(String name, ViewSchema schema) {
        Path schemaPath = getViewSchemaPath(name);
        saveViewSchema(schema, schemaPath);
    }

    public ViewSchema getViewSchema(String name) {
        Path schemaPath = getViewSchemaPath(name);
        return loadViewSchema(schemaPath);
    }
}

// JSON format example:
/*
{
  "fields": [
    {
      "id": 0,
      "name": "customer_id",
      "type": "BIGINT"
    },
    {
      "id": 1,
      "name": "order_count",
      "type": "BIGINT"
    }
  ],
  "query": "SELECT customer_id, COUNT(*) FROM orders GROUP BY customer_id",
  "dialects": {
    "spark": "...",
    "flink": "..."
  },
  "comment": "Customer order summary",
  "options": {
    "materialization.enabled": "true"
  }
}
*/

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment