/coral

Coral is a translation, analysis, and query rewrite engine for SQL and other relational languages.

Primary LanguageJavaBSD 2-Clause "Simplified" LicenseBSD-2-Clause

Coral

Coral is a library for analyzing, processing, and rewriting views defined in the Hive Metastore, and sharing them across multiple execution engines. It performs SQL translations to enable views expressed in HiveQL (and potentially other languages) to be accessible in engines such as Trino (formerly PrestoSQL), Apache Spark, and Apache Pig. Coral not only translates view definitions between different SQL/non-SQL dialects, but also rewrites expressions to produce semantically equivalent ones, taking into account the semantics of the target language or engine. For example, it automatically composes new built-in expressions that are equivalent to each built-in expression in the source view definition. Additionally, it integrates with Transport UDFs to enable translating and executing user-defined functions (UDFs) across Hive, Trino, Spark, and Pig. Coral is under active development. Currently, we are looking into expanding the set of input view language APIs beyond HiveQL, and implementing query rewrite algorithms for data governance and query optimization.

Slack

  • Join the discussion with the community on Slack here!

Modules

Coral consists of following modules:

  • Coral-Hive: Converts definitions of Hive views with UDFs to equivalent view logical plan.
  • Coral-Trino: Converts view logical plan to Trino (formerly PrestoSQL) SQL, and vice versa.
  • Coral-Spark: Converts view logical plan to Spark SQL.
  • Coral-Pig: Converts view logical plan to Pig-latin.
  • Coral-Schema: Derives Avro schema of view using view logical plan and input Avro schemas of base tables.
  • Coral-Spark-Plan: Converts Spark plan strings to equivalent logical plan (in progress).
  • Coral-Service: Service that exposes REST APIs that allow users to interact with Coral (see Coral-as-a-Service for more details).

How to Build

Clone the repository:

git clone https://github.com/linkedin/coral.git

Build:

./gradlew clean build

Contributing

The project is under active development and we welcome contributions of different forms. Please see the Contribution Agreement.

Resources

Coral-as-a-Service

Coral-as-a-Service or simply, Coral Service is a service that exposes REST APIs that allow users to interact with Coral without necessarily coming from a compute engine. Currently, the service supports an API for query translation between different dialects and another for interacting with a local Hive Metastore to create example databases, tables, and views so they can be referenced in the translation API. The service can be used in two modes: remote Hive Metastore mode, and local Hive Metastore mode. The remote mode uses an existing (already deployed) Hive Metastore to resolve tables and views, while the local one creates an empty embedded Hive Metastore so users can add their own table and view definitions.

API Reference

/translate

A GET API which takes the following parameters and returns the translated query:

  • query: SQL query to translate between two dialects
  • fromLanguage: Input dialect (e.g., spark, trino, hive -- see below for supported inputs)
  • toLanguage: Output dialect (e.g., spark, trino, hive -- see below for supported outputs)

/create

A POST API which takes a SQL query to create a database/table/view in the local metastore (note: this endpoint is only available with Coral Service in local metastore mode).

Instructions to use with examples

  1. Clone Coral repo
git clone https://github.com/linkedin/coral.git  
  1. From the root directory of Coral, access the coral-service module
cd coral-service  
  1. Build
../gradlew clean build  

To run Coral Service using the local metastore:

  1. Run
../gradlew bootRun --args='--spring.profiles.active=localMetastore'  

Example workflow using local metastore:

(Note: Use an online URL encoder to encode SQL queries.)

  1. Create a database called db1 in local metastore using the /create endpoint
# Non-URL encoded statement: CREATE DATABASE IF NOT EXISTS db1

curl -X POST "http://localhost:8080/create?statement=CREATE%20DATABASE%20IF%20NOT%20EXISTS%20db1"
Creation successful
  1. Create a table called airport within db1 in local metastore using the /create endpoint
# Non-URL encoded statement: CREATE TABLE IF NOT EXISTS db1.airport(name string, country string, area_code int, code string, datepartition string)

curl -X POST "http://localhost:8080/create?statement=CREATE%20TABLE%20IF%20NOT%20EXISTS%20db1.airport%28name%20string%2C%20country%20string%2C%20area_code%20int%2C%20code%20string%2C%20datepartition%20string%29"
  1. Translate a query on db1.airport in local metastore using the /translate endpoint
# Non-URL encoded statement: SELECT * FROM db1.airport

curl "http://localhost:8080/translate?query=SELECT%20%2A%20FROM%20db1.airport&fromLanguage=hive&toLanguage=trino"

The translation result is:

Original query in hive: SELECT * FROM db1.airport
Translated to trino: SELECT "name", "country", "area_code", "code", "datepartition"
FROM "db1"."airport"

To run Coral Service using the remote metastore:

  1. Add your kerberos client keytab file to coral-service/src/main/resources
  2. Appropriately replace all instances of SET_ME in coral-service/src/main/resources/hive.properties
  3. Run
../gradlew bootRun  
  1. Translate a query on existing table/view in remote metastore using the /translate endpoint

Currently Supported Translation Flows

  1. Hive to Trino
  2. Hive to Spark
  3. Trino to Spark
    Note: During Trino to Spark translations, views referenced in queries are considered to be defined in HiveQL and hence cannot be used when translating a view from Trino. Currently, only referencing base tables is supported in Trino queries. This translation path is currently a POC and may need further improvements.